fix(build): verify staging by content, and route the last in-place copy through it

Sunrisepeak · Sunrisepeak · commit cb7f3df71bc3 · 2026-07-30T11:59:38.000+08:00
Windows CI caught two things the Linux-only self-checks structurally could not.

1. `rule runtime_alias` was a SECOND `Copy-Item -Force`. PE has no soname
   symlink, so an alias is a copy of a freshly built DLL — the same hazard as
   BMI staging (a program still running from a previous `mcpp run` holds the old
   one). Its Windows branch now goes through `$mcpp stage` too; POSIX keeps
   `ln -s`, where the symlink is semantics and not merely how the file is
   written. The 'no Copy-Item anywhere' assertion is a no-op on Linux, which is
   why only the Windows job could find this.

2. Size-only equivalence was unsound for exactly those DLL payloads: PE section
   padding makes 'genuinely rebuilt, identical size' ordinary, so a stale DLL
   could survive in the build dir. Content comparison is unconditionally
   correct — a destination equal to the source needs no write — and it only runs
   when ninja has already decided the edge is dirty. It is now the default;
   `--verify size` / MCPP_STAGE_VERIFY=size stays for callers that know the
   source is fingerprint-scoped, and an unrecognized value falls back to the
   SAFE mode rather than the fast one.

Also from CI: a read-only destination is replaceable on POSIX (rename rewrites
the directory entry) but not on Windows, so that test now asserts both outcomes
per platform instead of one; the e2e scripts unescape ninja node names (a
Windows drive letter arrives as `C$:/Users/...`) and use BSD `stat -f` when GNU
`stat -c` is absent (macOS).
diff --git a/.agents/docs/2026-07-30-issue311-bmi-staging-and-cache-root-design.md b/.agents/docs/2026-07-30-issue311-bmi-staging-and-cache-root-design.md
@@ -195,7 +195,7 @@ mcpp stage --output <dst> <src>
 | 步 | 条件 | 行为 |
 |---|---|---|
 | 1 | `src` 不存在 | 报错退出 1（这是真 bug，不容忍） |
-| 2 | `dst` 存在 且 `size(dst) == size(src)` 且（`--verify content` 时字节亦相等） | **一个字节都不写，也不动任何时间戳**；退出 0 |
+| 2 | `dst` 存在 且 `size(dst) == size(src)` 且**内容逐字节相等**(默认;`--verify size` 时只比 size) | **一个字节都不写,也不动任何时间戳**;退出 0 |
 | 3 | 否则 | 写 `dst.tmp.<pid>`（同目录）→ `rename` 覆盖 `dst` |
 | 4 | 步 3 失败 | 退化为原地覆写（`copy_file` overwrite）——赢下"可写但不可删"的持有者形态 |
 | 5 | 步 3+4 都失败 | 退避重试 3 次（100/300/900 ms）后仍失败 → 结构化诊断 + 退出 1 |
@@ -220,9 +220,14 @@ mcpp stage --output <dst> <src>
 也就是说：**std staging 是全仓库唯一强制覆写的那一处**，这个不对称本身就是缺陷。
 S1 把它拉回一致。
 
-内容校验默认关闭（只比 size）：上面的 fp 判据已经足够强，逐字节比较要多读两遍 31 MB。
-留开关是为了排障（`--verify content` / `MCPP_STAGE_VERIFY=content`）。选逐字节比较而不是
-hash：同样的 I/O 成本，但没有碰撞面，且能提前退出。
+**内容校验是默认,不是开关**(这一条被 Windows CI 纠正过一次)。初稿让 size 相等即视为已
+staged,理由是 fp 判据;但同一条 rule 还搬 **DLL**(`runtimeDeployFiles`、以及 Windows 上的
+`runtime_alias`),而 PE 的节对齐让「真的重建了、大小却一模一样」十分常见 —— size-only 会把
+一个过期的 DLL 留在 build dir 里。逐字节比较则**无条件正确**:内容相同就是不需要写。
+
+成本可接受,因为这个判断只在 ninja 已经认定 edge 脏了才会跑(罕见),此时多读两遍 31 MB 换
+的是正确性。`--verify size` / `MCPP_STAGE_VERIFY=size` 保留给「调用方确知源是 fp 作用域」的
+快路径。选逐字节比较而不是 hash:同样的 I/O 成本,但没有碰撞面,且能提前退出。
 
 **为什么步 2 连时间戳都不碰**（这一条实测修正过一次）：
 
@@ -297,6 +302,12 @@ staging rule 加 `restat = 1`。这是 S1 步 2"不写字节"能真正省掉级
 部署复用的是同一条 rule（`ninja_backend.cppm:1077-1083`）。**DLL 部署是同一类失败的第二个
 受害者**（往正在运行的进程/调试器已加载的 DLL 上 `Copy-Item -Force` 同样失败），S1 一并治好。
 
+还有**第三个**:`rule runtime_alias`(`ninja_backend.cppm:758-764`)在 Windows 上也是一条
+`Copy-Item -Force` —— PE 没有 soname 符号链接,别名就是刚建出来的 DLL 的副本,同一危险类。
+Windows 分支一并改走 `$mcpp stage`(+ `restat`),**POSIX 分支保持 `ln -s` 不变**:那里符号
+链接是语义而不只是写法(改成拷贝会改变打包产物)。这一处是 Windows CI 抓出来的 —— 初稿的
+「`Copy-Item` 归零」自查项在本地(Linux)恒为真,永远不会失败。
+
 另有一处必改：`mcpp = <exe>` 这个 ninja 变量目前只在 `if (dyndep)` 里绑定
 （`ninja_backend.cppm:403-409`）。新 rule 在**所有**配置下都要用它，必须把绑定提到该
 条件之外，否则 GCC 非 dyndep 路径会生成 `$mcpp` 为空的命令。
@@ -335,7 +346,7 @@ staging rule 加 `restat = 1`。这是 S1 步 2"不写字节"能真正省掉级
 
 | 风险 | 缓解 |
 |---|---|
-| size 相等但内容不同（S1 步 2 误跳过） | fp 判据 + `--verify=hash` 开关；e2e 用"改一个字节但保持长度"的负例锁住 hash 模式 |
+| size 相等但内容不同(S1 步 2 误跳过) | **默认逐字节比较**,单测双向锁住(默认必拷贝 / `--verify size` 才跳过) |
 | `restat = 1` 引入意外的"永不重建" | 单测锁 rule 文本；e2e 正例：改 std 源/换 toolchain ⇒ fp 变 ⇒ 新 build dir，不受影响 |
 | 收敛缓存根导致老用户一次性重编 std | 只影响 self-contained 与 Windows 两种形态；一次 10–60 s；CHANGELOG 写明，doctor 提示遗留目录 |
 | `mcpp` 变量提取出 `if (dyndep)` 后 ninja 文本变化 | `tests/unit/test_ninja_backend.cpp` 断言两种配置（dyndep on/off）下都绑定 |
diff --git a/.agents/docs/2026-07-30-issue311-implementation-plan.md b/.agents/docs/2026-07-30-issue311-implementation-plan.md
@@ -84,7 +84,7 @@ std::expected<StageResult, StageError> stage_file(
    hint 必须点名 clangd 与 `compile_commands.json` 的因果）。
 8. 每次退出前清理残留 `dst.tmp.<pid>`。
 
-`Verify::Content` 由 `MCPP_STAGE_VERIFY=content` 或 `--verify content` 打开；实现是分块
+`Verify::Content` 是**默认**；`--verify size` / `MCPP_STAGE_VERIFY=size` 才退回只比 size。实现是分块
 逐字节比较（同 I/O 成本、无碰撞面、可提前退出），不引入 hash 依赖。
 
 **CLI 接线**（照 `dyndep` 的形状）：
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -13,9 +13,9 @@
 
   staging 改为走 mcpp 自己的内部子命令 `mcpp stage`(形态对齐既有的 `mcpp dyndep`):**目标已等价就一个字节都不写**,否则先写同目录临时文件再 rename,再退化为原地覆写,失败按退避重试,最终失败时给出点名文件与可能持有者(clangd / 编辑器索引 / 杀软 / 上一次 `mcpp run` 还在跑的程序)的诊断。**绝不降级为 warning** —— staged BMI 过期或缺失会变成难以归因的 `module 'std' not found`,或者更糟:旧 BMI 配新 `std.o` 静默链接。
 
-  「已等价就不写」的判据是 fingerprint:build dir(`target/<triple>/<fp>`)与缓存目录(`$MCPP_HOME/bmi/<fp>`)共享同一个 fp,而 fp 已覆盖编译器身份/target triple/stdlib/std 源哈希/标准与方言 flag。dep BMI 缓存一直就是这么做的(`bmi_cache.cppm`: *"Existing project outputs are left untouched"*)—— std staging 是全仓库唯一强制覆写的那一处,这个不对称本身就是缺陷。
+  「已等价」由**逐字节比较**判定 —— 无条件正确:内容相同就是不需要写。这个判断只在 ninja 已经认定 edge 脏了才会跑,所以代价可以忽略。(`--verify size` 保留给确知源是 fingerprint 作用域的调用方:build dir 与缓存目录共享同一个 fp,而 fp 已覆盖编译器身份/target triple/stdlib/std 源哈希/标准与方言 flag。但它**不是默认** —— 同一条 rule 还搬 DLL,而 PE 的节对齐让「真的重建了、大小却一样」十分常见。)dep BMI 缓存一直就是「已存在就不动」的(`bmi_cache.cppm`: *"Existing project outputs are left untouched"*)—— std staging 是全仓库唯一强制覆写的那一处,这个不对称本身就是缺陷。
 
-  同一条 rule 也用于 **Windows 运行期 DLL 部署**,因此「往上一次 `mcpp run` 还加载着的 DLL 上覆写」这个同类失败一并治好。
+  同一条 rule 也用于 **Windows 运行期 DLL 部署**,以及 Windows 上的 `runtime_alias`(PE 没有 soname 符号链接,别名就是刚建出来的 DLL 的副本),因此「往上一次 `mcpp run` 还加载着的 DLL 上覆写」这个同类失败一并治好。POSIX 的 `runtime_alias` 保持符号链接不变 —— 那里符号链接是语义,不只是写法。
 
 - **重新 stage 一个未变的 std BMI 不再重编整张模块图。** staged BMI 是每个 importer 的 implicit input,而 staging rule 既不保留 mtime 也没有 `restat`,于是缓存侧 BMI 只要 mtime 变新(在下面那个缓存根缺陷下,**换个 cwd 跑就会发生**),所有 `import std` 的 TU 全部重编 —— 即使字节完全相同。
 
diff --git a/src/build/ninja_backend.cppm b/src/build/ninja_backend.cppm
@@ -757,11 +757,21 @@ std::string emit_ninja_string(const BuildPlan& plan) {
 
     append("rule runtime_alias\n");
     if constexpr (mcpp::platform::is_windows) {
-        append("  command = powershell -NoProfile -Command \"Copy-Item -Force '$in' -Destination '$out'\"\n");
+        // PE has no soname symlink, so the alias is a copy — and a copy of a
+        // just-rebuilt DLL is exactly the hazard #311 is about (a program still
+        // running from a previous `mcpp run` holds the old one). Route it
+        // through the same staging primitive rather than a second in-place
+        // PowerShell copy. Content-verified, so a same-size rebuild still
+        // refreshes the alias.
+        append("  command = $mcpp stage --output $out $in\n");
     } else {
         append("  command = mkdir -p $$(dirname $out) && rm -f $out && ln -s $$(basename $in) $out\n");
     }
-    append("  description = ALIAS $out\n\n");
+    append("  description = ALIAS $out\n");
+    if constexpr (mcpp::platform::is_windows) {
+        append("  restat = 1\n");
+    }
+    append("\n");
 
     if (dyndep) {
         // Scan rule: produce P1689 .ddi for one TU.
diff --git a/src/build/stage.cppm b/src/build/stage.cppm
@@ -16,14 +16,17 @@
 //
 // The rules this module implements:
 //
-//   1. Never write bytes we don't have to. The destination and the source live
-//      under the SAME build fingerprint (target/<triple>/<fp> vs
-//      $MCPP_HOME/bmi/<fp>), and the fingerprint already covers compiler
-//      identity, target triple, stdlib, std module source hash and the
-//      standard/dialect flags. Same fingerprint + same size ⇒ equivalent ⇒
-//      the file is already staged. This mirrors what the dep BMI cache has
-//      always done (bmi_cache.cppm: "Existing project outputs are left
-//      untouched").
+//   1. Never write bytes that are already there. Equivalence is decided by
+//      COMPARING CONTENT, which is unconditionally correct — a destination
+//      identical to the source needs no write, whatever the reason. Size alone
+//      is only a heuristic and is available as `--verify size` for the paths
+//      where the caller knows better (a std BMI is fingerprint-scoped: the
+//      cache dir and the build dir share the fp that covers compiler identity,
+//      target triple, stdlib, std source hash and the dialect flags). It is
+//      NOT the default, because staging also carries .dll payloads whose PE
+//      section padding makes "same size, different bytes" ordinary.
+//      Skipping mirrors what the dep BMI cache has always done
+//      (bmi_cache.cppm: "Existing project outputs are left untouched").
 //   2. When we do write, write out of place and rename — atomic for readers,
 //      and it survives a transient sharing violation (antivirus, indexer)
 //      that an in-place overwrite would lose to.
@@ -49,12 +52,12 @@ export namespace mcpp::build::stage {
 
 // How hard to look before declaring the destination already-staged.
 enum class Verify {
-    Size,       // default: size match under an identical build fingerprint
-    Content,    // byte-for-byte compare (MCPP_STAGE_VERIFY=content / --verify content)
+    Content,    // default: byte-for-byte compare — always correct
+    Size,       // size match only (MCPP_STAGE_VERIFY=size / --verify size)
 };
 
 struct StageOptions {
-    Verify                    verify  = Verify::Size;
+    Verify                    verify  = Verify::Content;
     int                       retries = 3;                 // attempts after the first
     std::chrono::milliseconds backoff{100};                // ×3 per retry: 100/300/900ms
 };
@@ -76,7 +79,8 @@ std::expected<StageOutcome, StageError> stage_file(const std::filesystem::path&
 // unreadable or the sizes differ.
 bool same_content(const std::filesystem::path& a, const std::filesystem::path& b);
 
-// Parse a --verify / MCPP_STAGE_VERIFY value. Unknown values fall back to Size.
+// Parse a --verify / MCPP_STAGE_VERIFY value. Unknown values fall back to the
+// safe default (Content).
 Verify parse_verify(std::string_view value);
 
 } // namespace mcpp::build::stage
@@ -171,7 +175,7 @@ bool same_content(const std::filesystem::path& a, const std::filesystem::path& b
 }
 
 Verify parse_verify(std::string_view value) {
-    return value == "content" ? Verify::Content : Verify::Size;
+    return value == "size" ? Verify::Size : Verify::Content;
 }
 
 std::expected<StageOutcome, StageError> stage_file(const std::filesystem::path& src,
@@ -193,7 +197,8 @@ std::expected<StageOutcome, StageError> stage_file(const std::filesystem::path&
         }
     }
 
-    // Already staged? (see module comment for why size is a sound default)
+    // Already staged? Content by default — size is the caller-opt-in shortcut
+    // (see module comment).
     std::error_code sec;
     if (std::filesystem::is_regular_file(dst, sec)) {
         std::error_code se1, se2;
diff --git a/tests/e2e/170_bmi_staging_no_cascade.sh b/tests/e2e/170_bmi_staging_no_cascade.sh
@@ -17,6 +17,14 @@
 # Toolchain-neutral: only needs a package that says `import std;`.
 set -e
 
+# build.ninja node names are ninja-ESCAPED: on Windows a drive letter arrives as
+# `C$:/Users/...`. Unescape before touching the filesystem (the Windows job
+# failed on exactly this).
+unescape_ninja() { printf '%s' "$1" | sed 's/\$:/:/g; s/\$\$/$/g'; }
+# Compare paths across the Windows fork: MCPP_HOME is `C:\Users\...` while ninja
+# writes forward slashes.
+norm_path() { printf '%s' "$1" | tr '\\' '/'; }
+
 TMP=$(mktemp -d)
 trap "rm -rf $TMP" EXIT
 cd "$TMP"
@@ -44,13 +52,13 @@ EDGE=$(grep -E '^build [^ ]+ : stage_file ' "$NINJA" | head -1)
 [[ -n "$EDGE" ]] || {
     grep -n "std" "$NINJA" | head -20
     echo "FAIL: no stage_file edge for the std BMI (did import std resolve?)"; exit 1; }
-DST=$(echo "$EDGE" | awk '{print $2}')
-SRC=$(echo "$EDGE" | awk '{print $NF}')
+DST=$(unescape_ninja "$(echo "$EDGE" | awk '{print $2}')")
+SRC=$(unescape_ninja "$(echo "$EDGE" | awk '{print $NF}')")
 echo "staging: $SRC -> $DST"
 
 # ── invariant 2: the cache root is $MCPP_HOME/bmi, never a cwd-local dir ──
-HOME_ROOT="${MCPP_HOME:-$HOME/.mcpp}"
-case "$SRC" in
+HOME_ROOT=$(norm_path "${MCPP_HOME:-$HOME/.mcpp}")
+case "$(norm_path "$SRC")" in
     "$HOME_ROOT"/bmi/*) ;;
     *) echo "FAIL: std BMI cache is '$SRC', expected under '$HOME_ROOT/bmi'"; exit 1 ;;
 esac
diff --git a/tests/e2e/171_bmi_staging_locked_dest.sh b/tests/e2e/171_bmi_staging_locked_dest.sh
@@ -20,6 +20,14 @@
 # runs as root.
 set -e
 
+# build.ninja node names are ninja-ESCAPED: on Windows a drive letter arrives as
+# `C$:/Users/...`. Unescape before touching the filesystem (the Windows job
+# failed on exactly this).
+unescape_ninja() { printf '%s' "$1" | sed 's/\$:/:/g; s/\$\$/$/g'; }
+# Compare paths across the Windows fork: MCPP_HOME is `C:\Users\...` while ninja
+# writes forward slashes.
+norm_path() { printf '%s' "$1" | tr '\\' '/'; }
+
 TMP=$(mktemp -d)
 trap "rm -rf $TMP" EXIT
 cd "$TMP"
@@ -41,11 +49,14 @@ cd app
 NINJA=$(find target -name build.ninja | head -1)
 EDGE=$(grep -E '^build [^ ]+ : stage_file ' "$NINJA" | head -1)
 [[ -n "$EDGE" ]] || { echo "FAIL: no stage_file edge for the std BMI"; exit 1; }
-DST="$(dirname "$NINJA")/$(echo "$EDGE" | awk '{print $2}')"
-SRC=$(echo "$EDGE" | awk '{print $NF}')
+DST="$(dirname "$NINJA")/$(unescape_ninja "$(echo "$EDGE" | awk '{print $2}')")"
+SRC=$(unescape_ninja "$(echo "$EDGE" | awk '{print $NF}')")
 [[ -f "$DST" ]] || { echo "FAIL: staged BMI missing at $DST"; exit 1; }
 
-identity() { stat -c '%i %Y %s' "$1"; }
+# GNU stat vs BSD/macOS stat (the macOS job failed on `stat -c`).
+identity() {
+    stat -c '%i %Y %s' "$1" 2>/dev/null || stat -f '%i %m %z' "$1"
+}
 BEFORE=$(identity "$DST")
 
 # Dirty the staging edge without touching the shared cache's CONTENT.
diff --git a/tests/unit/test_build_stage.cpp b/tests/unit/test_build_stage.cpp
@@ -35,7 +35,7 @@ std::string read_file(const std::filesystem::path& p) {
 
 // Retries would only slow the failure tests down; the behaviour under test is
 // the decision, not the backoff.
-StageOptions no_retry(Verify v = Verify::Size) {
+StageOptions no_retry(Verify v = Verify::Content) {
     return StageOptions{.verify = v, .retries = 0, .backoff = std::chrono::milliseconds{0}};
 }
 
@@ -75,33 +75,35 @@ TEST(BuildStage, EquivalentDestinationIsNotTouched) {
     EXPECT_EQ(std::filesystem::last_write_time(dst), recorded);
 }
 
-// Same size, different bytes: the size-only default deliberately treats this as
-// already-staged (destination and source share a build fingerprint, which
-// covers compiler identity, stdlib and std source hash).
-TEST(BuildStage, SameSizeDifferentBytesIsSkippedUnderSizeVerify) {
+// Same size, different bytes must be copied by DEFAULT. Staging also carries
+// .dll payloads, where PE section padding makes equal sizes across a real
+// rebuild ordinary — so size-only equivalence cannot be the default.
+TEST(BuildStage, SameSizeDifferentBytesIsCopiedByDefault) {
     Tmp tmp;
     auto src = tmp.path / "src.bin";
     auto dst = tmp.path / "dst.bin";
     write_file(src, "AAAA");
     write_file(dst, "BBBB");
 
-    auto r = stage_file(src, dst, no_retry(Verify::Size));
+    auto r = stage_file(src, dst, no_retry());
     ASSERT_TRUE(r.has_value());
-    EXPECT_FALSE(r->copied);
-    EXPECT_EQ(read_file(dst), "BBBB");
+    EXPECT_TRUE(r->copied);
+    EXPECT_EQ(read_file(dst), "AAAA");
 }
 
-TEST(BuildStage, SameSizeDifferentBytesIsCopiedUnderContentVerify) {
+// `--verify size` is the opt-in shortcut for callers that know the source is
+// fingerprint-scoped; it accepts the same-size destination as already staged.
+TEST(BuildStage, SameSizeDifferentBytesIsSkippedUnderSizeVerify) {
     Tmp tmp;
     auto src = tmp.path / "src.bin";
     auto dst = tmp.path / "dst.bin";
     write_file(src, "AAAA");
     write_file(dst, "BBBB");
 
-    auto r = stage_file(src, dst, no_retry(Verify::Content));
+    auto r = stage_file(src, dst, no_retry(Verify::Size));
     ASSERT_TRUE(r.has_value());
-    EXPECT_TRUE(r->copied);
-    EXPECT_EQ(read_file(dst), "AAAA");
+    EXPECT_FALSE(r->copied);
+    EXPECT_EQ(read_file(dst), "BBBB");
 }
 
 TEST(BuildStage, DifferentSizeIsAlwaysCopied) {
@@ -124,10 +126,12 @@ TEST(BuildStage, MissingSourceIsAnError) {
     EXPECT_NE(r.error().message.find("nope.bin"), std::string::npos);
 }
 
-// A read-only destination is the closest POSIX analogue of the Windows holder:
-// an in-place overwrite cannot open it, so staging must go through the
-// temp-file + rename path.
-TEST(BuildStage, ReadOnlyDestinationIsReplacedViaRename) {
+// A read-only destination that must actually be replaced: POSIX can do it
+// (the directory entry is what gets rewritten, so temp-file + rename wins),
+// Windows cannot (replacing a read-only file is denied however you spell it) —
+// and there the contract is the loud failure, not a silent skip. Asserted per
+// platform rather than skipped, so neither side can rot unnoticed.
+TEST(BuildStage, ReadOnlyDestinationOutcomeIsPlatformDefined) {
     Tmp tmp;
     auto src = tmp.path / "src.bin";
     auto dst = tmp.path / "dst.bin";
@@ -136,9 +140,15 @@ TEST(BuildStage, ReadOnlyDestinationIsReplacedViaRename) {
     std::filesystem::permissions(dst, std::filesystem::perms::owner_read);
 
     auto r = stage_file(src, dst, no_retry());
+#if defined(_WIN32)
+    ASSERT_FALSE(r.has_value());
+    EXPECT_NE(r.error().message.find("hint:"), std::string::npos);
+    EXPECT_EQ(read_file(dst), "old");
+#else
     ASSERT_TRUE(r.has_value()) << r.error().message;
     EXPECT_TRUE(r->copied);
     EXPECT_EQ(read_file(dst), "new-content");
+#endif
 }
 
 // When staging genuinely cannot proceed, the failure must name the file and
@@ -176,6 +186,7 @@ TEST(BuildStage, SameContentComparesBytesNotJustSize) {
 TEST(BuildStage, VerifyModeParsing) {
     EXPECT_EQ(parse_verify("content"), Verify::Content);
     EXPECT_EQ(parse_verify("size"), Verify::Size);
-    EXPECT_EQ(parse_verify("nonsense"), Verify::Size);
-    EXPECT_EQ(parse_verify(""), Verify::Size);
+    // Anything unrecognized must land on the SAFE mode, not the fast one.
+    EXPECT_EQ(parse_verify("nonsense"), Verify::Content);
+    EXPECT_EQ(parse_verify(""), Verify::Content);
 }
diff --git a/tests/unit/test_ninja_backend.cpp b/tests/unit/test_ninja_backend.cpp
