fix(build): sequence staged artifacts before compilation, and stop hiding std entries

Three fixes from the first CI round.

Module partitions. Replacing a package's compile edges with stage edges also
removes the ordering those compile edges carried. A consumer that imports `pkg`
has `pkg`'s BMI in its dyndep and nothing else — the partition BMI `pkg:part` was
reached only because `pkg`'s own compile edge depended on it. With independent
stage edges ninja may start the consumer while the partition is still unstaged:

  error: failed to find module file for module 'mcpplibs.cmdline:options'

macOS CI hit it; Linux won the race, which is why it is now an invariant rather
than a scheduling accident. Every staged artifact becomes an ORDER-ONLY
prerequisite of every non-staged edge, aggregated through one phony so no edge
repeats the list (mcpp#274: long ninja lines are how a 50781-character command
line blew past cmd.exe's 8191 limit). Order-only is the right strength — the real
content dependencies are still declared where they always were, so a changed BMI
still invalidates its consumers; this adds sequencing, not dirtiness. Verified
locally on both GCC and Clang against mcpplibs.cmdline, which has a `:options`
partition.

Ages were computed against the wrong epoch. file_time_type is
std::chrono::file_clock, whose epoch is not the Unix epoch, so `cache list`
printed "74509d ago". Converted through clock_cast.

Test fallout, all of it real:

- 22_doctor_cache_publish asserted `cache list` was empty after `mcpp self
  doctor`, which precompiles a std module. That assertion only held because the
  old `cache list` walked dep entries and skipped std ones — and hiding them is
  how 16 GB of duplicated std BMIs went unnoticed. The empty-cache check moved
  ahead of doctor; the std entry is now asserted to be visible, with a bound on
  the age column that would have caught the epoch bug.
- 40_llvm_bmi_cache used `--no-cache` to force a cold first build, then expected
  the second build to reuse it. `--no-cache` is now an alias for `--cache=off`,
  which means neither read NOR write — so it left nothing to reuse. The test's
  actual intent (fresh MCPP_HOME is already cold) is now what it says, and it
  additionally asserts zero compile edges and the partition sequencing. The
  semantic tightening is called out in the CHANGELOG: a mode named `off` that
  still writes the cache would not be defensible.
- 98_reflection_import_std grepped $MCPP_HOME/bmi, the pre-v1 root. It passed
  locally purely because this machine still holds 26 GB of legacy entries, one of
  which happened to record -freflection — a false green of exactly the kind the
  plan warned about. It and two siblings now select the std entry by CONTENT
  instead of `find | head -1`, which is no longer well-defined: one MCPP_HOME can
  hold several std identities now, and that is the point.

Author: Sunrisepeak

CHANGELOG.md

@@ -63,6 +63,8 @@
 
   `--no-cache` 保留为 `off` 的兼容别名。它的旧 help 文案「Force-clear target/ before building」两处不准:它清的是**构建目录**(`target/<triple>/<fp>/`)而不是整个 `target/`,而且名字与缓存无关。`mcpp run` / `mcpp test` 一并补上这两个 flag(此前它们连 `--no-cache` 都没有)。
 
+  ⚠️ **`--no-cache` 的语义有一处收紧**:此前它只清构建目录、**仍然会回填全局缓存**;现在它等于 `off`,即**不读也不写**。想要「从零重编但仍然刷新缓存」的,用 `mcpp clean` 或 `rm -rf target` 后正常构建。这个收紧是为了让三个模式正交:一个叫 `off` 的模式还偷偷写缓存是说不通的。
+
 - **`mcpp cache` 补齐到可运维。** `cache dir`(缓存到底在哪 —— 此前 `cache *`/`doctor`/`clean --bmi-cache` 各自解析根目录,而 config 的 reset 路径用 `GlobalConfig::bmiCacheDir`,两者可能不是同一个目录)、`cache gc --max-size <N>{MiB,GiB} / --older-than <N>{s,m,h,d}`(**真 LRU**)、`cache clean --deps|--std|--all|--legacy`、`cache list --json`、`cache verify`(逐条目校验清单与磁盘,残缺条目非零退出)。`cache info` 现在打印该条目的键输入 —— 怀疑命中错了时第一件想看的东西。
 
   `prune` 此前按**目录 mtime** 排序,而那只记录条目被**写入**的时间:一个每次构建都命中的热包,和一个一个月没人碰过的冷包一样「陈旧」。`entry.json` 的 `accessed` 由每次命中刷新(只重写 `entry.json`,**不动产物 mtime** —— 那些 mtime 参与 ninja 的 restat 判定),`gc` 按它排序。`cache clean` 开头那句 `remove_all(<root>/"deps")` 指向一个从不存在的路径(dep 条目在 `<root>/<fp>/deps`),是死代码。

src/bmi_cache/maintenance.cppm

@@ -128,14 +128,20 @@ std::int64_t stamp_of(const nlohmann::json& j, const char* field) {
     return 0;
 }
 
-// mtime fallback for entries whose stamp is missing (written by an mcpp that
-// predates `accessed`). Reported as such rather than silently treated as fresh.
+// mtime fallback for entries with no `accessed` stamp (std entries, and package
+// entries written by an mcpp that predates the field).
+//
+// file_time_type is std::chrono::file_clock, whose epoch is NOT the Unix epoch —
+// on libstdc++ it is 1970 shifted, so reading time_since_epoch() and comparing
+// it against system_clock produced ages like "74509d ago". Convert through the
+// clock rather than assuming a shared epoch.
 std::int64_t dir_mtime_seconds(const std::filesystem::path& p) {
     std::error_code ec;
     auto t = std::filesystem::last_write_time(p, ec);
     if (ec) return 0;
+    auto sys = std::chrono::clock_cast<std::chrono::system_clock>(t);
     return std::chrono::duration_cast<std::chrono::seconds>(
-        t.time_since_epoch()).count();
+        sys.time_since_epoch()).count();
 }
 
 void measure(Entry& e) {

src/build/ninja_backend.cppm

@@ -872,6 +872,11 @@ std::string emit_ninja_string(const BuildPlan& plan) {
         append("\n");
     }
 
+    // Aggregate target for everything staged out of the global cache. Named
+    // with a leading underscore so it cannot collide with a module or target
+    // name (both of which are identifiers or paths).
+    constexpr std::string_view kStagedCachePhony = "_mcpp_staged_cache";
+
     auto bmi_path = [&traits](std::string_view name) {
         std::string s(traits.bmiDir);
         s += '/';
@@ -916,24 +921,55 @@ std::string emit_ninja_string(const BuildPlan& plan) {
     // this package's own config and its dependencies' keys, so for a given key
     // equal size IS equivalence — and size comes from directory metadata, which
     // stays readable even when a holder denies opening the file.
+    //
+    // ORDERING. Replacing a package's compile edges with stage edges also
+    // removes the ordering those compile edges carried. A module partition is
+    // the case that breaks: a consumer imports `pkg`, so its dyndep declares
+    // `pkg`'s BMI and nothing else — the partition BMI `pkg:part` was reached
+    // only because `pkg`'s own compile edge depended on it. With independent
+    // stage edges, ninja may finish staging `pkg` and start the consumer while
+    // `pkg:part` is still unstaged, and Clang then fails with
+    // `failed to find module file for module 'pkg:part'`. (Observed on macOS
+    // CI; Linux happened to win the race, which is exactly why this is stated
+    // as an invariant rather than left to scheduling.)
+    //
+    // So every staged artifact becomes an ORDER-ONLY prerequisite of every edge
+    // that is not itself staged. Order-only (`||`) is the right strength: the
+    // real content dependencies are still declared where they always were (a
+    // dyndep-supplied implicit input, or the static-mode implicit list), so a
+    // changed BMI still invalidates its consumers — this adds sequencing, not
+    // dirtiness. The cost is that a handful of copies finish before compilation
+    // starts, which is what used to happen anyway when those units were built.
+    std::string stagedOrderOnly;
     {
-        bool any = false;
+        std::vector<std::string> staged;
         for (auto& cu : plan.compileUnits) {
             if (!cu.servedFromCache) continue;
             if (cu.cachedObject.empty()) continue;
-            any = true;
-            append(std::format("build {} : stage_file {}\n",
-                               escape_ninja_path(cu.object),
+            auto obj = escape_ninja_path(cu.object);
+            append(std::format("build {} : stage_file {}\n", obj,
                                escape_ninja_path(cu.cachedObject)));
             append("  verify = --verify size\n");
+            staged.push_back(obj);
             if (cu.providesModule && !cu.cachedBmi.empty()) {
-                append(std::format("build {} : stage_file {}\n",
-                                   bmi_path(*cu.providesModule),
+                auto bmi = bmi_path(*cu.providesModule);
+                append(std::format("build {} : stage_file {}\n", bmi,
                                    escape_ninja_path(cu.cachedBmi)));
                 append("  verify = --verify size\n");
+                staged.push_back(bmi);
             }
         }
-        if (any) append("\n");
+        if (!staged.empty()) {
+            append("\n");
+            // One phony aggregates them so each consuming edge names a single
+            // prerequisite instead of repeating the whole list (mcpp#274: long
+            // ninja lines are how a 50781-character command line blew past
+            // cmd.exe's 8191 limit on Windows).
+            append("build " + std::string(kStagedCachePhony) + " : phony");
+            for (auto& s2 : staged) append(" " + s2);
+            append("\n\n");
+            stagedOrderOnly = " || " + std::string(kStagedCachePhony);
+        }
     }
 
     if (dyndep) {
@@ -955,8 +991,8 @@ std::string emit_ninja_string(const BuildPlan& plan) {
                 continue;
             auto ddi = (cu.object.parent_path() / cu.source.filename()).string() + ".ddi";
             ddi_paths.push_back(ddi);
-            append(std::format("build {} : cxx_scan {}\n", escape_ninja_path(ddi),
-                               escape_ninja_path(cu.source)));
+            append(std::format("build {} : cxx_scan {}{}\n", escape_ninja_path(ddi),
+                               escape_ninja_path(cu.source), stagedOrderOnly));
             append(std::format("  compile_target = {}\n", escape_ninja_path(cu.object)));
             if (auto includes = local_include_flags(cu, msvcDeps); !includes.empty())
                 append(std::format("  local_includes ={}\n", includes));
@@ -1027,17 +1063,18 @@ std::string emit_ninja_string(const BuildPlan& plan) {
                 auto it = ddi_to_dd.find(ddi);
                 if (it != ddi_to_dd.end()) {
                     out_line += " | " + it->second;
+                    out_line += stagedOrderOnly;
                     out_line += "\n  dyndep = " + it->second;
                     // P2: set bmi_out for the copy_if_different logic in cxx_module.
                     if (cu.providesModule) {
                         out_line += "\n  bmi_out = " + bmi_path(*cu.providesModule);
                     }
                     out_line += "\n";
                 } else {
-                    out_line += "\n";
+                    out_line += stagedOrderOnly + "\n";
                 }
             } else {
-                out_line += "\n";
+                out_line += stagedOrderOnly + "\n";
             }
             if (auto includes = local_include_flags(cu, msvcDeps); !includes.empty())
                 out_line += "  local_includes =" + includes + "\n";
@@ -1089,6 +1126,7 @@ std::string emit_ninja_string(const BuildPlan& plan) {
             out_line += std::format(" : {} {}", rule, escape_ninja_path(cu.source));
             if (!implicit.empty())
                 out_line += " |" + implicit;
+            out_line += stagedOrderOnly;
             out_line += "\n";
             if (auto includes = local_include_flags(cu, msvcDeps); !includes.empty())
                 out_line += "  local_includes =" + includes + "\n";

src/cli.cppm

@@ -54,7 +54,7 @@ void print_usage() {
     std::println("  mcpp build [options]                 Build the current package");
     std::println("  mcpp run [target] [-- args...]       Build + run a binary target");
     std::println("  mcpp test [pattern] [-- args...]     Build + run tests/**/*.cpp (--list, --timeout, --message-format json)");
-    std::println("  mcpp clean [--bmi-cache]             Remove target/ (and optionally BMI cache)");
+    std::println("  mcpp clean [--bmi-cache]             Remove target/ (and optionally the build cache)");
     std::println("  mcpp add <pkg>[@<ver>]               Add a dependency to mcpp.toml");
     std::println("  mcpp remove <pkg>                    Remove a dependency from mcpp.toml");
     std::println("  mcpp update [pkg]                    Re-resolve deps and rewrite mcpp.lock");
@@ -286,8 +286,8 @@ int run(int argc, char** argv) {
                 return cmd_test(p, std::span<const std::string>(passthrough));
             })))
         .subcommand(cl::App("clean")
-            .description("Remove target/ (and optionally the global BMI cache)")
-            .option(cl::Option("bmi-cache").help("Also wipe the global BMI cache"))
+            .description("Remove target/ (and optionally the global build cache)")
+            .option(cl::Option("bmi-cache").help("Also wipe the global build cache (see `mcpp cache clean`)"))
             .action(wrap_rc(cmd_clean)))
         .subcommand(cl::App("why")
             .description("Explain how the toolchain / runtime / deps were resolved")

src/config.cppm

@@ -6,7 +6,8 @@
 //     registry/                 XLINGS_HOME for mcpp's xlings
 //       bin/xlings              vendored xlings binary (= <XLINGS_HOME>/bin/xlings)
 //       .xlings.json            seeded with index_repos = [mcpplibs]
-//     bmi/<fp>/                 BMI cache (existing)
+//     build-cache/v1/           cross-project build cache (pkg/ + std/)
+//     bmi/                      pre-v1 build cache; unused, `cache clean --legacy`
 //     cache/                    metadata caches
 //     config.toml               this module's input
 //

src/doctor.cppm

@@ -461,10 +461,11 @@ export int explain_code(std::string_view code) {
          "The [toolchain] pin in mcpp.toml does not match the detected toolchain.\n"
          "Either install the pinned toolchain (xlings install ...) or relax the\n"
          "pin (e.g. \"gcc@>=15\" instead of \"gcc@15.1.0\")."},
-        {"E0005", "BMI cache corruption",
-         "A cached BMI file referenced by manifest.txt is missing on disk. Run\n"
-         "`mcpp cache prune --older-than 0d` to drop stale entries; the next build\n"
-         "will repopulate."},
+        {"E0005", "build cache corruption",
+         "A file listed in a cache entry's entry.json is missing on disk. Such an\n"
+         "entry is treated as a miss and rebuilt, so this is never wrong output —\n"
+         "only wasted space. `mcpp cache verify` lists every affected entry and\n"
+         "`mcpp cache gc --older-than 0s` reclaims them."},
         {"E0006", "index requires a newer mcpp",
          "The package index declares (index.toml [index].min_mcpp) that its\n"
          "descriptors need a newer mcpp than this binary — parsing them would\n"

tests/e2e/100_cppfly_reflection.sh

@@ -104,10 +104,12 @@ out=$("$binary")
 }
 
 # The std BMI prebuild carries the same dialect (scan/prebuild/compile agree).
-metadata="$(find "$MCPP_HOME/build-cache/v1/std" -name std-module.json | head -1)"
-grep -q '"std_flag": "-std=c++26 -freflection' "$metadata" || {
-    cat "$metadata"
-    echo "FAIL: std-module.json std_flag lacks -std=c++26 -freflection"
+# Recursive grep, not `find | head -1`: one MCPP_HOME can hold several std
+# identities now, so "the first one" is arbitrary.
+grep -rl '"std_flag": "-std=c++26 -freflection' "$MCPP_HOME/build-cache/v1/std" >/dev/null 2>&1 || {
+    find "$MCPP_HOME/build-cache/v1/std" -name std-module.json \
+        -exec grep -H '"std_flag"' {} \; 2>/dev/null
+    echo "FAIL: no std-module.json records std_flag -std=c++26 -freflection"
     exit 1
 }
 

tests/e2e/22_doctor_cache_publish.sh

@@ -11,6 +11,14 @@ TMP=$(mktemp -d)
 trap "rm -rf $TMP" EXIT
 export MCPP_HOME="$TMP/mcpp-home"
 
+# 0) cache list on a genuinely empty cache: friendly message.
+#    This has to come BEFORE doctor — doctor resolves a build plan, which
+#    precompiles the std module, and `cache list` now reports std entries too.
+#    Hiding them is how 16 GB of duplicated std BMIs went unnoticed, so listing
+#    them is the fix, not a regression.
+out=$("$MCPP" cache list 2>&1)
+[[ "$out" == *"empty"* ]] || { echo "cache list on empty cache: '$out'"; exit 1; }
+
 # 1) doctor: should always run, exit 0 or 1 (warn ok), never 2
 rc=0
 "$MCPP" self doctor > doctor.log 2>&1 || rc=$?
@@ -21,9 +29,24 @@ grep -q 'Checking registry'       doctor.log || { cat doctor.log; echo "no regis
 grep -q 'Checking cache health'   doctor.log || { cat doctor.log; echo "no cache check"; exit 1; }
 grep -q 'Doctor result'             doctor.log || { cat doctor.log; echo "no result line"; exit 1; }
 
-# 2) cache list (empty): friendly message
+# 2) after doctor, the std module it precompiled must be VISIBLE. std entries
+#    dominate the cache's size, and `cache list` used to walk only dep entries.
 out=$("$MCPP" cache list 2>&1)
-[[ "$out" == *"empty"* ]] || { echo "cache list empty: '$out'"; exit 1; }
+[[ "$out" == *"std"* ]] || { echo "cache list omits the std entry: '$out'"; exit 1; }
+# The age column must be plausible: file_time_type's epoch is not the Unix
+# epoch, and reading it as if it were printed ages like "74509d ago".
+if [[ "$out" =~ ([0-9]+)d\ ago ]] && (( BASH_REMATCH[1] > 3650 )); then
+    echo "cache list reports an implausible age (clock epoch bug): '$out'"
+    exit 1
+fi
+
+# 2b) cache dir must point at the cache the rest of the tool uses.
+out=$("$MCPP" cache dir 2>&1)
+[[ "$out" == "$MCPP_HOME/build-cache/v1"* ]] || {
+    echo "cache dir '$out' != '$MCPP_HOME/build-cache/v1'"; exit 1; }
+
+# 2c) verify must pass on a healthy cache.
+"$MCPP" cache verify > /tmp/_v.log 2>&1 || { cat /tmp/_v.log; echo "verify failed"; exit 1; }
 
 # 3) publish dry-run on a fresh package. Publish uses `git archive` for the
 #    source tarball, so we git-init + commit first. We also need a non-empty

tests/e2e/40_llvm_bmi_cache.sh

@@ -60,22 +60,45 @@ int main() {
 }
 EOF
 
-# First build — should compile the dependency
-out1=$("$MCPP" build --no-cache 2>&1)
+# First build — populates the cache. Deliberately NOT `--no-cache`: that is now
+# an alias for `--cache=off`, which means neither read NOR write, so a build that
+# used it would leave nothing for the second build to reuse. MCPP_HOME is fresh
+# here, so this build is already cold.
+out1=$("$MCPP" build 2>&1)
 echo "$out1" | grep -q "Compiling.*mcpplibs.cmdline" || {
-    # It's OK if it says "Cached" because global cache may exist
-    echo "$out1" | grep -q "Cached.*mcpplibs.cmdline" || {
-        echo "FAIL: mcpplibs.cmdline not mentioned in first build: $out1"
-        exit 1
-    }
+    echo "FAIL: mcpplibs.cmdline not compiled in the first (cold) build: $out1"
+    exit 1
 }
 
-# Second build (clean target, keep BMI cache) — dependency should be cached
+# Second build, clean target dir, cache kept — the dependency must be reused.
 rm -rf target
 out2=$("$MCPP" build 2>&1)
 echo "$out2" | grep -q "Cached.*mcpplibs.cmdline" || {
     echo "FAIL: mcpplibs.cmdline not cached on second build: $out2"
     exit 1
 }
 
+# ...and reuse must mean "not recompiled". The status line alone used to be
+# printed while ninja rebuilt every unit behind it, so assert on the graph.
+NINJA="$(find target -name build.ninja | head -1)"
+[[ -n "$NINJA" ]] || { echo "FAIL: no build.ninja"; exit 1; }
+if grep -qE ': (cxx_module|cxx_object|cxx_scan) .*mcpplibs' "$NINJA"; then
+    echo "FAIL: cached dependency still has compile edges"
+    grep -nE ': (cxx_module|cxx_object|cxx_scan) .*mcpplibs' "$NINJA" | head
+    exit 1
+fi
+
+# Clang + module partitions: mcpplibs.cmdline has a `:options` partition, which a
+# consumer never imports directly. Its stage edge must be sequenced before the
+# consumer's compile, or clang fails with `failed to find module file for module
+# 'mcpplibs.cmdline:options'` — a race Linux won and macOS lost.
+grep -q '_mcpp_staged_cache' "$NINJA" || {
+    echo "FAIL: staged artifacts are not sequenced before compilation"
+    exit 1
+}
+
+# And the whole thing must actually link and run.
+out3=$("$MCPP" run 2>&1) || { echo "FAIL: run: $out3"; exit 1; }
+echo "$out3" | grep -q 'cache test ok' || { echo "FAIL: run output: $out3"; exit 1; }
+
 echo "OK"

tests/e2e/59_cpp_standard_config.sh

@@ -71,11 +71,14 @@ if grep -q -- "-std=c++23" compile_commands.json; then
     exit 1
 fi
 
-metadata="$(find "$MCPP_HOME/build-cache/v1/std" -name std-module.json | head -1)"
-[[ -n "$metadata" ]] || { echo "FAIL: std module metadata missing"; exit 1; }
-grep -q '"cpp_standard": "c++26"' "$metadata" || {
-    echo "FAIL: std module metadata missing C++26 standard"
-    cat "$metadata"
+# The entry recording c++26, selected by CONTENT rather than by `find | head -1`:
+# one MCPP_HOME can hold several std identities now.
+metadata="$(grep -rl '"cpp_standard": "c++26"' \
+    "$MCPP_HOME/build-cache/v1/std" 2>/dev/null | head -1)"
+[[ -n "$metadata" ]] || {
+    echo "FAIL: no std module metadata records c++26"
+    find "$MCPP_HOME/build-cache/v1/std" -name std-module.json \
+        -exec grep -H '"cpp_standard"' {} \; 2>/dev/null
     exit 1
 }
 grep -q '"std_flag": "-std=c++26"' "$metadata" || {