Bump the build-cache epoch: a corrected key cannot tell a poisoned entry

from a trustworthy one

The previous commit made fill_package_config read the realised environment,
but a corrected derivation does not make an entry written under the old,
wrong one safe to keep. An entry is poisoned exactly when its recorded key
and its actual compiled inputs already disagreed at write time, and the
package most likely to still produce an unchanged key after the fix is the
one this same PR newly exempts from the realisation: a kernel-abi provider
inferred into c-environment = "platform" now has an empty
privateBuild.cflags, so its new key is computed from nothing -- matching
its old key, which was also computed from nothing, while the object on disk
was compiled WITH the substitution. No cheaper mechanism distinguishes a
pre-fix entry from a post-fix one, so kCacheEpoch moves (2 -> 3): every
existing ~/.mcpp/build-cache/v1 entry is orphaned unconditionally, one cold
rebuild for everyone, rather than trust a key equality that is wrong for
exactly the entries that matter most.

Also adds CacheKey.EveryPrivateBuildBroadcastFieldReachesTheKey, a durable
guard for the class of defect rather than only this one instance of it:
PackageRoot::privateBuild (UsageRequirements) is the engine's own broadcast
channel, and every one of its members -- today includeDirs, includeDirsAfter,
cflags, cxxflags, asmflags, ldflags, modules -- has to move the cache key,
because the key's only job is to describe what reaches the compiler. This
predates the c-abi wave (targetSideUsage's own broadcast, and __openkal__,
had the identical exposure before [c-abi] existed); the two fields nothing
broadcasts into yet (ldflags, modules) are asserted uncovered on purpose,
with an explicit instruction to flip that assertion in the same change that
adds their broadcast.

Author: speak-agent

CHANGELOG.md

@@ -47,8 +47,18 @@
   环境构建的镜像,一个镜像混两种 C 环境且没有任何诊断,这正是本设计要防止的那个不变量本身。
   现在 `fill_package_config` 把 `privateBuild.cflags`/`cxxflags`/新增的 `asmflags`(广播后的
   值)与包自身声明的标志一起折进键里,和它原本处理 include 目录的方式一致。
+  **升级到这个版本后,第一次构建会是一次冷构建**:`kCacheEpoch` 从 2 提到了 3,已有的
+  `~/.mcpp/build-cache/v1` 条目会被整体作废,而不是逐条判断哪些还能信。这不是求稳的富余
+  动作——键改对了以后,恰恰是那些*不再*触发替换的包最危险:比如同一个 PR 里被推导进
+  `c-environment = "platform"` 的 kernel-abi 包,它 broadcast 前后 `privateBuild.cflags`
+  都是空的,新键和旧键因此照样相同,而旧键当初对应的目标文件,正是带着替换令牌编译出来
+  的那一份——键从一开始就没描述对它,普通的输入变化检测看不出来,只有作废整个缓存才够。
   (`src/build/cache_key.cppm`,单测 `test_cache_key.cpp` 的
-  `TwoDifferentRealisedCEnvironmentsDoNotShareASlot`)
+  `TwoDifferentRealisedCEnvironmentsDoNotShareASlot` 与
+  `EveryPrivateBuildBroadcastFieldReachesTheKey`——后者是给这一类缺陷立的长期防线:
+  `privateBuild`(`UsageRequirements`)每加一个新的广播字段,都要在这个测试和
+  `fill_package_config` 里同时补上一行,否则历史会重演,`-D__openkal__` 和
+  `targetSideUsage` 自己的广播在这次修订之前就已经有过同样的缺口)
 - **`__CYGWIN__`/`__CYGWIN32__` 保持定义,经 openkal-musl 尖峰实验修订。** 最初的实现
   取消定义它们(理由是图里没有真正的 Cygwin 用户态)。第三方可移植代码里需要知道**目标文件
   格式**——不是 C 环境,也不是平台 API——的那部分,没有别的名字能指代「PE 格式 + 呈现

docs/22-target-side.md

@@ -479,6 +479,21 @@ declared flags, exactly as it already did for include directories.
 `--cache=off`, or clearing the cache directory, was never a sign the key
 was RIGHT; both routes bypass it entirely.
 
+**This release also bumps the cache's epoch, orphaning every existing
+entry — the first build after upgrading is cold.** A corrected key does not
+by itself make an entry written under the old, wrong derivation safe to
+keep: an entry is poisoned exactly when its recorded key and its actual
+compiled inputs already disagreed, and the package MOST likely to still
+show an unchanged key after the fix is the one this same revision newly
+exempts from the realisation (a `kernel-abi` provider inferred into
+`c-environment = "platform"`, above) — its `privateBuild.cflags` is now
+empty, so the new key is computed from nothing, matching the OLD key, which
+was also computed from nothing, while the object on disk was compiled WITH
+the substitution. No cheaper check tells a pre-fix entry from a post-fix
+one, so `mcpp.build.cache_key::kCacheEpoch` moves (2 → 3), which orphans
+the whole cache unconditionally rather than trust a key equality that
+cannot be trusted for exactly the entries that matter most.
+
 **Store key — not yet closed.** A package whose *install hook* compiles a
 static library from source into the shared store is keyed by package and
 version, not by which environment it was built against — the same gap

docs/zh/22-target-side.md

@@ -384,6 +384,16 @@ C 环境,而且没有任何诊断。`fill_package_config` 现在把 `PackageRoot
 include 目录的方式完全一致。`--cache=off`,或者干脆清空缓存目录,从来都不是键本身正确
 的信号——这两条路径都是绕开了这个键,而不是证明了它。
 
+**这次发布还把缓存的 epoch 提了一版,让已有条目全部作废——升级后第一次构建会是冷构建。**
+键改对了,不代表用旧的、错误推导方式写下的条目就可以留着继续信:一个条目被污染,恰恰是
+因为它记录的键和它实际编译时的输入从一开始就对不上——而修好之后最可能仍然拿到不变的键
+的那个包,正好是这次修订里新推导进 `c-environment = "platform"` 的那一类(上文的
+kernel-abi 提供者):它的 `privateBuild.cflags` 现在是空的,新键因此是从空内容算出来的,
+跟旧键(同样是从空内容算出来的)一样;而磁盘上那份目标文件,却是带着替换令牌编译出来的。
+没有更便宜的办法能把修复前写下的条目和修复后写下的条目分开,所以
+`mcpp.build.cache_key::kCacheEpoch` 往上提了一版(2 → 3),让整个缓存无条件作废,而不是
+去相信一个恰恰在最要紧的那些条目上靠不住的键相等判断。
+
 **存储键——尚未补上。** 安装钩子把从源码编译的静态库装进共享 store 时,键只含包名与版本,
 不含针对哪种环境编译——这与 [requires](#requires) 已经记录的 C++ 运行时选择缺口同形。用同样
 的方式补上(一条 `requires` 形状的环境声明,在解析时核对、不符即拒绝)已经设计好,但尚未

src/build/cache_key.cppm

@@ -73,7 +73,26 @@ export namespace mcpp::build::cache_key {
 // not ask for. They would all miss anyway (probe_cached compares the REQUESTED
 // artifacts), but sharing a directory between two layouts makes `cache gc`'s
 // size accounting and `cache verify`'s output meaningless.
-inline constexpr int kCacheEpoch = 2;
+// 3 (design 2026-09-18, coordinator review): `fill_package_config` used to
+// read only a package's OWN declared cflags/cxxflags, never the engine
+// broadcast channel (`privateBuild`) the realised [c-abi] environment and
+// `-D__openkal__` actually travel through — so an entry written before this
+// fix can be WRONG in a way probe_cached's normal "did the inputs change"
+// check cannot see: the compiled object and the recorded key silently
+// disagreed about what was compiled from the moment they were written, not
+// from a change since. This is the one case in this axis's whole design
+// (see the header comment above `struct BuildAxes`) where a narrower fix
+// is not enough — the poisoned entries are not the ones whose inputs
+// changed, they are ENTRIES WHOSE KEY NEVER DESCRIBED THEM, and the package
+// most likely to still show the identical (wrong) key after the fix is
+// exactly the one whose `privateBuild.cflags` just emptied out from under
+// it (a `kernel-abi` provider inferred into `c-environment = "platform"` in
+// this same PR): its new key is computed from nothing, matching its old
+// key, which was ALSO computed from nothing, while the STORED OBJECT was
+// compiled WITH the substitution. Bumping this orphans the entire cache —
+// one cold rebuild — rather than trust a key equality that cannot tell a
+// pre-fix entry from a post-fix one.
+inline constexpr int kCacheEpoch = 3;
 
 // Axes A/B/C — identical for every package in one build, computed once.
 struct BuildAxes {

tests/unit/test_cache_key.cpp

@@ -428,6 +428,76 @@ TEST(CacheKey, TwoDifferentRealisedCEnvironmentsDoNotShareASlot) {
     EXPECT_NE(lp64Key, llp64Key);
 }
 
+// A DURABLE GUARD FOR THE WHOLE CLASS THE PREVIOUS TEST FOUND ONE INSTANCE
+// OF — this predates the c-abi wave (`targetSideUsage`'s own broadcast, and
+// `-D__openkal__`, had the identical exposure before [c-abi] existed) and
+// will recur: `PackageRoot::privateBuild` (`mcpp.modgraph.scanner
+// ::UsageRequirements`) is the engine's OWN channel for "this reaches a
+// package's compile command line even though the package wrote nothing" —
+// today's members are `includeDirs`, `includeDirsAfter`, `cflags`,
+// `cxxflags`, `asmflags`, `ldflags`, `modules` — and every one of them has
+// to move `fill_package_config`'s output, because the cache key's only job
+// is to describe what actually reaches the compiler.
+//
+// C++ has no reflection this side of the standard that could enumerate
+// `UsageRequirements`'s members and fail this test automatically the day a
+// new one is added without a matching line below — so this is the nearest
+// substitute the language allows: one assertion per CURRENT member, so the
+// list itself is the checklist. Adding a member to `UsageRequirements`
+// without adding its case here and its read in `fill_package_config` is
+// exactly the shape of the defect `TwoDifferentRealisedCEnvironmentsDoNotSh
+// areASlot` above caught — if you are adding one, add it in both places in
+// the SAME change.
+//
+// `ldflags` and `modules` are asserted UNCOVERED, on purpose: nothing
+// broadcasts into `privateBuild.ldflags` or `.modules` today (checked by
+// grep across `src/` and `modules/` when this test was written), so there
+// is nothing yet for `fill_package_config` to be missing on those two — the
+// day something does broadcast into either, this pair of assertions must
+// flip (start reading it) at the same time the broadcast is added, not
+// after.
+TEST(CacheKey, EveryPrivateBuildBroadcastFieldReachesTheKey) {
+    std::filesystem::path store = "/home/u/.mcpp/registry/data/xpkgs";
+    auto keyFor = [&](auto mutate) {
+        auto pkgRoot = rootAt(store / "p" / "1");
+        pkgRoot.usageResolved = true;
+        mutate(pkgRoot);
+        ck::PackageAxes p;
+        p.indexName = "p"; p.packageName = "p"; p.version = "1";
+        ck::fill_package_config(p, pkgRoot, store);
+        return ck::key_hex(axes(), p);
+    };
+    const auto baseline = keyFor([](auto&) {});
+
+    EXPECT_NE(baseline, keyFor([](auto& r) {
+        r.privateBuild.includeDirs = {"/somewhere/broadcast-only-include"};
+    })) << "privateBuild.includeDirs";
+    EXPECT_NE(baseline, keyFor([](auto& r) {
+        r.privateBuild.includeDirsAfter = {"/somewhere/broadcast-only-after"};
+    })) << "privateBuild.includeDirsAfter";
+    EXPECT_NE(baseline, keyFor([](auto& r) {
+        r.privateBuild.cflags = {"-Dbroadcast_only_c"};
+    })) << "privateBuild.cflags";
+    EXPECT_NE(baseline, keyFor([](auto& r) {
+        r.privateBuild.cxxflags = {"-Dbroadcast_only_cxx"};
+    })) << "privateBuild.cxxflags";
+    EXPECT_NE(baseline, keyFor([](auto& r) {
+        r.privateBuild.asmflags = {"-Dbroadcast_only_asm"};
+    })) << "privateBuild.asmflags";
+
+    // Documented gap, not an oversight — see the comment above.
+    EXPECT_EQ(baseline, keyFor([](auto& r) {
+        r.privateBuild.ldflags = {"-Wl,--broadcast-only"};
+    })) << "privateBuild.ldflags is not yet a live broadcast channel; if "
+           "this starts failing, something now writes it, and "
+           "fill_package_config must be taught to read it in the SAME change "
+           "that flips this expectation";
+    EXPECT_EQ(baseline, keyFor([](auto& r) {
+        r.privateBuild.modules = {"broadcast.only.module"};
+    })) << "privateBuild.modules is not yet a live broadcast channel; see "
+           "the ldflags case above for what to do when it becomes one";
+}
+
 // THE HEADER SET THE DRIVER IS POINTED AT IS PART OF THE IDENTITY.
 //
 // Everything else on axis A describes the COMPILER. Nothing described the