perf(build): 让「接口没变就不级联重编」真正生效 + bench 改测真实二进制

## 1. mcpp 侧:一个从未生效过的机制

`cxx_module` 规则保留上一份 BMI、重编、内容相同则换回旧文件,让 ninja 的 restat
判定输出未变、从而不重建导入者。这套机制 2026-05-12 就设计并实现了,判据是 `cmp -s`。

**它一次都没走通过。** GCC 把 wall-clock 写进 BMI 的内容:

    buildtime: 2026/08/12 02:25:01 UTC
    localtime: 2026/08/12 02:25:01 UTC

同一份源码相隔一秒的两次编译,BMI 差恰好 4 个字节,`cmp` 永远报「变了」。当年的
设计说明只预见到 GCC 会重写文件(mtime 抖动)并据此开出内容比较的药方,没有预见到
时间戳本身就是内容 —— 所以药方按原样写出来就不可能生效。

新增 `mcpp bmi-equal`(内部子命令,由 ninja 规则调用),比较时掩掉这两个字段。

刻意不用 `SOURCE_DATE_EPOCH`:那会把整个编译的 epoch 钉死,从而改变**用户代码**里
`__DATE__` / `__TIME__` 的展开;掩码只改变 mcpp 认为「什么算相等」,别的都不动。

构造上保守:找不到预期字段、或两份文件对字段位置判断不一致时回落为严格比较 ——
可以把等价的判成不同,但绝不会把不同的判成相同。

实测(`bench --project` 测 mcpp 构建 mcpp 自身,touch 一个 46 导入者、内容未变的文件):

    scenario     2026.8.11.3   2026.8.12.1
    noop              0.27s        0.19s
    touch-hub        73.99s        0.45s      ~164x

单测从两侧钉死(8 例):只测「等价的判相等」会放过一个恒返回 true 的实现,而那比
原缺陷更糟 —— 它会静默吞掉所有真实的级联。

## 2. bench 侧:测二进制,不测模拟

删掉 `mcpp-opt` 引擎。它靠在构建前后设 `SOURCE_DATE_EPOCH` 来**模拟**优化 ——
在 harness 里模拟一个改动,测的是 harness 对该改动的理解,而且一旦真实实现与之
分叉就会静默地不再跟踪。

改为**按二进制参数化**:`--engines mcpp=<路径A>,mcpp=<路径B>` 注册两个引擎,各自
向自己的二进制询问版本并据此标注(`mcpp@2026.8.11.3` / `mcpp@2026.8.12.1`),
两行永远不会塌成一行。上面那张对比表就是这么测出来的。

新增 `--project <dir>`:就地测量一个已存在的工程,mcpp 自身即基础用例。该模式下
variant 轴坍缩为 `native`(工程就是它现在的样子,在它之上生成会毁掉被测对象);
需要扰动文件的场景必须显式指定 `--hub/--leaf/--body`,否则报 `skipped` **并说明
原因**,而不是挑一个文件产出一个看着有效的数字。

`edit-body` 会改源文件。项目模式下那是用户的文件,因此逐字节保存并在退出时恢复 ——
包括构建失败的路径,那正是遗留改动最容易被漏掉的时候。

## 3. 顺带修掉的两个真实问题

- **生成的 fixture 没钉工具链**,依赖机器的全局默认。本机绿、CI 红(`seed build
  exited 1`)。现在与本仓库其他 mcpp 工程一样显式 pin。
- **e2e 失败时只打印子进程日志的路径**,而那个 tmpdir 在 trap 里已被删除 ——
  在 CI 上等于没有信息。现在直接转储内容。

验证:`mcpp build` ✅ · 新增 8 个单测 ✅ · e2e 230 ✅ · 六引擎本机实测 ✅

Author: speak-agent

.agents/docs/2026-08-12-bench-suite-architecture-and-plan.md

@@ -131,21 +131,23 @@ fixtures/synth-<N>x<D>/
 
 第三种变体直接对应上一轮分析的 **F4 / §6.3**:把实现移出接口单元。有了它,"改一行函数体"的代价差异就是**测出来的**,不是推断的。
 
-同时保留 `self` fixture —— 即 mcpp 自身(137 模块),因为真实工程的依赖形状不是合成器能编出来的。
+同时提供 **`--project <dir>` 模式**:直接就地测量一个已存在的工程(mcpp 自身即基础用例),因为真实工程的依赖形状不是合成器能编出来的。该模式下 variant 轴坍缩为 `native`,并且 `edit-body` 会在测量前后**逐字节保存并恢复**被改的源文件 —— 包括构建失败的路径,那正是遗留改动最容易被忽略的时候。
 
 ---
 
 ## 5. 场景矩阵
 
 | 维度 | 取值 |
 |---|---|
-| engine | mcpp, mcpp-opt(优化后), cmake, xmake, meson, bazel |
+| engine | `mcpp=<binary>`(可给多个,自动按版本标注)、cmake、xmake、meson、bazel |
 | variant | headers, modules, modules-impl |
 | profile | release, debug |
 | scenario | cold, noop, touch-hub, edit-body, touch-leaf |
 | compiler | gcc, clang, msvc(平台可用者) |
 
-**`mcpp` vs `mcpp-opt`**:同一份源码、同一编译器,区别只在是否启用上一轮验证过的优化(BMI 时间戳归一 + BMI 落盘即释放)。这让"优化前后"成为矩阵里的**一个正交维度**,而不是另做一次实验。
+**"优化前后"用两个真实二进制表达,不用模拟。** `--engines mcpp=<旧>,mcpp=<新>` 会注册两个引擎,各自向自己的二进制询问版本并据此标注(`mcpp@2026.8.11.3` / `mcpp@2026.8.12.1`)。
+
+早期设计里有一个 `mcpp-opt` 引擎,靠在构建前后设 `SOURCE_DATE_EPOCH` 来**模拟**优化。已删除:**在 harness 里模拟一个改动,测的是 harness 对该改动的理解**,而且一旦真实实现与之分叉,它会静默地不再跟踪。优化属于 mcpp,基准测的是二进制。
 
 矩阵是笛卡尔积但**不是全跑**:`spec.cppm` 用显式的 include/exclude 规则裁剪,CI 默认跑一个小集合,`workflow_dispatch` 可放开。
 

.agents/docs/2026-08-12-modular-build-performance-deep-analysis.md

@@ -333,11 +333,11 @@ GCC 的 BMI 携带函数体(为了跨模块内联),所以任何编辑都会改
 
 按 **收益 / 成本** 排序。每条都给出判据与验证方式。
 
-### 6.1 【L0·一行改动 · 仅 GCC】固化 BMI 时间戳,让级联抑制真正生效
+### 6.1 ✅【已实施 · 2026.8.12.1】让级联抑制真正生效(仅 GCC)
 
 **问题**:F3。**仅适用于 GCC** —— Clang 的 `.pcm` 实测字节稳定(§7.2),那边的级联抑制本来就在工作。
 
-**方案 A(推荐,零语义影响)**——把"BMI 是否相等"的判据从裸 `cmp` 换成**时间戳无关比较**。mcpp 已有 helper 子命令模式(`mcpp stage` / `mcpp dyndep`),新增 `mcpp bmi-equal <a> <b>`,跳过 BMI 内的 `buildtime:` / `localtime:` 字段。`cxx_module` 规则里把
+**已按方案 A 实施**(2026.8.12.1):把"BMI 是否相等"的判据从裸 `cmp` 换成**时间戳无关比较**。新增 `mcpp bmi-equal <a> <b>`(内部子命令),跳过 BMI 内的 `buildtime:` / `localtime:` 字段。`cxx_module` 规则里把
 
 ```sh
 cmp -s "$bmi_out" "$bmi_out.bak"
@@ -351,7 +351,14 @@ $mcpp bmi-equal "$bmi_out" "$bmi_out.bak"
 
 **副作用**:方案 B 会改变 `__DATE__` / `__TIME__` 的值。用户代码可能依赖,因此不宜作为默认。**方案 A 无此问题,应作为默认;方案 B 作为可选项。**
 
-**实测收益**:touch 一个 46 导入者的模块,**73.0s → 0.22s(332×)**。正确性不变(真实接口变更仍完整级联)。
+**实测收益(落地后,由 `bench --project` 测 mcpp 构建自身)**:
+
+| 场景 | 2026.8.11.3 | 2026.8.12.1 |
+|---|---|---|
+| `noop` | 0.27s | 0.19s |
+| **`touch-hub`**(46 导入者,内容未变) | **73.99s** | **0.45s** |
+
+正确性由单测从**两侧**钉死(`tests/unit/test_bmi_equivalent.cpp`):真实接口变更仍完整级联。
 
 **验证方式**:`bench/run.sh --scenario touch-hub`,并**必须同时验证**接口变更场景仍然级联——只测 touch 分不清"级联被正确抑制"和"级联坏了"。
 

CHANGELOG.md

@@ -5,6 +5,44 @@
 
 ## [2026.8.12.1] — 2026-08-12
 
+### 性能
+
+- **⚠️ 「接口没变就不级联重编」的机制从设计之日起从未生效过 —— 现已修复。**
+
+  `cxx_module` 规则会保留上一份 BMI、重编、然后在内容相同时把旧文件换回去,让
+  ninja 的 `restat` 判定输出未变、从而**不重建导入者**。这套机制 2026-05-12 就设计
+  并实现了,判据是 `cmp -s`。
+
+  但 GCC 把 wall-clock **写进了 BMI 的内容**:
+
+  ```
+  buildtime: 2026/08/12 02:25:01 UTC
+  localtime: 2026/08/12 02:25:01 UTC
+  ```
+
+  同一份源码相隔一秒的两次编译,BMI 差**恰好 4 个字节** —— `cmp` 于是永远报「变了」,
+  这条快路径**一次都没有走通过**。当年的设计说明只预见到 GCC 会重写文件(mtime 抖动)
+  并据此开出内容比较的药方,没有预见到时间戳本身就是内容,所以药方按原样写出来就不
+  可能生效。
+
+  新增 `mcpp bmi-equal`(内部子命令,由 ninja 规则调用),比较时掩掉这两个字段。
+  刻意**不用 `SOURCE_DATE_EPOCH`**:那会把整个编译的 epoch 钉死,从而改变**用户代码**里
+  `__DATE__` / `__TIME__` 的展开结果;掩码只改变 mcpp 认为「什么算相等」,别的什么都不动。
+
+  构造上保守:找不到预期字段、或两份文件对字段位置的判断不一致时,回落为严格比较 ——
+  它可以把等价的 BMI 判成不同,但**绝不会**把不同的 BMI 判成相同。
+
+  实测(用 `bench/` 套件测 mcpp 构建 mcpp 自身,touch 一个被 46 个模块导入、**内容未变**
+  的文件):
+
+  | 场景 | 2026.8.11.3 | 2026.8.12.1 |
+  |---|---|---|
+  | `noop` | 0.27s | 0.19s |
+  | **`touch-hub`** | **73.99s** | **0.45s** |
+
+  ~164×。正确性由单测从**两侧**钉死:只测「等价的判相等」会放过一个恒返回 true 的实现,
+  而那比原缺陷更糟 —— 它会静默吞掉所有真实的级联。
+
 ### 新增
 
 - **`bench/` —— 构建引擎基准套件(顶层目录,用 mcpp 自己写)。**

bench-child.log

@@ -0,0 +1,7 @@
+   Resolving toolchain
+    Resolved gcc@16.1.0 → @mcpp/registry/data/xpkgs/xim-x-gcc/16.1.0/bin/g++
+    Inferred sources [src/**/*.{cppm,cpp,cc,c,S,s,asm}]
+    Inferred target mcpp (bin from src/main.cpp)
+   Compiling mcpp v2026.8.12.1 (.)
+      Cached mcpplibs.cmdline v0.0.1 (3 units)
+    Finished release [optimized] in 0.22s

bench/README.md

@@ -8,13 +8,24 @@ Written in C++23 and built by mcpp, so it runs identically on Linux, macOS and
 Windows — a shell-based harness cannot, and this suite replaced one that could
 only run on Linux.
 
-```
-bench --engines mcpp,mcpp-opt,cmake,xmake,meson,bazel \
+```bash
+# generated fixtures, across engines and source forms
+bench --engines mcpp,cmake,xmake,meson,bazel \
       --variants headers,modules,modules-impl \
       --scenarios cold,noop,touch-hub,edit-body \
       --compiler /path/to/g++ --jobs 32 --out report.json
+
+# a REAL project, measured in place — e.g. mcpp building itself,
+# comparing two mcpp binaries
+bench --project . --engines mcpp=/usr/bin/mcpp,mcpp=./target/*/*/bin/mcpp \
+      --scenarios noop,touch-hub --hub src/platform/platform.cppm
 ```
 
+Each `mcpp=<path>` engine labels itself from the version that binary reports
+(`mcpp@2026.8.12.1`), so two releases never collapse into one row. That is how
+"did this release get faster?" is answered — by running both, not by emulating
+one of them in the harness.
+
 ---
 
 ## 1. What is measured
@@ -44,6 +55,7 @@ claim gets a number instead of an argument.
 | # | Invariant | How it is enforced |
 |---|---|---|
 | I1 | Identical compiler **binary** across engines | `--compiler <path>` is threaded into cmake (`-DCMAKE_CXX_COMPILER`), meson & xmake (`CXX`), bazel (`CC` + `--action_env`). mcpp uses its hermetic payload — a **declared asymmetry**, see §5. |
+| I0 | Optimisations are measured, never emulated | Engines are parameterised by BINARY (`mcpp=<path>`). The harness contains no "what if we also set X" mode: emulating a change measures the harness's idea of it and silently stops tracking the implementation. |
 | I2 | Identical source set | All variants come from one generator; no engine globs its own inputs. |
 | I3 | Identical language level | C++23 everywhere; `import std;` is **absent from every fixture** (see §5). |
 | I4 | Same parallelism | `--jobs N` is passed to every engine that accepts one. |
@@ -52,6 +64,25 @@ claim gets a number instead of an argument.
 
 ---
 
+## 2b. Two modes
+
+| mode | fixture | when |
+|---|---|---|
+| **generated** (default) | `--units/--fanin/--weight` synthesise the same project in three source forms | comparing **source forms**, and engines against each other on identical input |
+| **project** (`--project DIR`) | an existing tree, measured **in place** | comparing **engine binaries** on a real codebase — mcpp building itself is the base case |
+
+In project mode the variant axis collapses to `native`: the project is whatever
+it already is, and generating over it would destroy the thing being measured.
+Scenarios that perturb a file need to be told which one (`--hub`, `--leaf`,
+`--body`); without it they report `skipped` **with the reason** rather than
+picking a file and producing a number that looks valid.
+
+`edit-body` rewrites a source file. In project mode that file belongs to the
+user, so its exact bytes are captured before and restored afterwards — including
+when the build fails, which is precisely when a leftover edit would be missed.
+
+---
+
 ## 3. Scenarios
 
 | Scenario | Perturbation | What it exercises |

bench/src/engines/mcpp.cppm

@@ -1,10 +1,16 @@
-// bench.engines.mcpp — mcpp as a measured engine, including its optimised form.
+// bench.engines.mcpp — mcpp as a measured engine.
 //
-// Two engines live here because they differ by CONFIGURATION, not by code:
-// `mcpp` is the shipped behaviour, `mcpp-opt` additionally applies the
-// optimisations validated in the 2026-08-12 analysis. Keeping them as two
-// registry entries makes "before vs after" an ordinary axis of the matrix
-// instead of a separate experiment run by hand.
+// PARAMETERISED BY BINARY, not by a simulated flag. `--engines mcpp=/path/to/A,
+// mcpp=/path/to/B` registers two engines that differ only in which mcpp runs, and
+// each labels itself with the version it reports. That is how "did this release
+// get faster?" is answered: by running both releases, not by approximating one
+// of them.
+//
+// An earlier revision had an `mcpp-opt` engine that set SOURCE_DATE_EPOCH around
+// the build to emulate an optimisation. It was removed: emulating a change in
+// the harness measures the harness's idea of the change, and it silently stops
+// tracking the real implementation the moment the two diverge. Optimisations
+// belong in mcpp; the bench measures binaries.
 export module bench.engines.mcpp;
 
 import std;
@@ -17,16 +23,26 @@ namespace bench::engines {
 
 class McppEngine : public Engine {
 public:
-    explicit McppEngine(bool optimised) : optimised_(optimised) {}
+    // `program` may be a bare name resolved through PATH or an absolute path to
+    // a specific build. `label` is what appears in results; empty means "ask the
+    // binary", which is what makes a two-version comparison self-describing.
+    explicit McppEngine(std::string program = "mcpp", std::string label = {})
+        : program_(std::move(program)), label_(std::move(label)) {}
 
-    std::string_view name() const override { return optimised_ ? "mcpp-opt" : "mcpp"; }
+    std::string_view name() const override {
+        if (label_.empty()) label_ = discover_label();
+        return label_;
+    }
 
     Availability probe() const override {
-        return probe_program("mcpp", {"mcpp", "--version"});
+        const auto v = version_string();
+        if (v.empty())
+            return {false, std::format("{} not runnable", program_)};
+        return {true, v};
     }
 
-    // mcpp compiles plain .cpp as readily as modules, so every fixture variant
-    // is in scope.
+    // mcpp compiles plain .cpp as readily as modules, and a Native project is
+    // whatever it already is, so every variant is in scope.
     bool supports(Variant) const override { return true; }
     std::string unsupported_reason(Variant) const override { return {}; }
 
@@ -36,40 +52,47 @@ public:
 
     platform::RunResult build(const Job& job) const override {
         const std::vector<std::string> argv{
-            "mcpp", "build", job.profile == "debug" ? "--dev" : "--release"};
-
-        // The optimisation under test is `SOURCE_DATE_EPOCH`. GCC stamps a wall
-        // clock into every BMI, so mcpp's content-comparison cascade
-        // suppression can never fire; pinning the epoch makes BMIs byte-stable
-        // and it fires — measured 73.0 s -> 0.22 s on touch-hub.
-        //
-        // A FIXED constant, not "now": the whole point is that two builds a
-        // minute apart produce identical bytes. The value is arbitrary but must
-        // not change within a comparison.
-        //
-        // Scoped, so the variable never leaks into the next cell — an
-        // unoptimised `mcpp` measurement running after an `mcpp-opt` one would
-        // otherwise silently inherit the optimisation and the two would tie.
-        if (optimised_) {
-            platform::ScopedEnv epoch("SOURCE_DATE_EPOCH", "1700000000");
-            return platform::run(argv, job.project_dir, job.log_path);
-        }
+            program_, "build", job.profile == "debug" ? "--dev" : "--release"};
         return platform::run(argv, job.project_dir, job.log_path);
     }
 
     void clean(const Job& job) const override {
         // Artifacts only. ~/.mcpp holds the toolchain and the dependency cache;
-        // deleting those would measure provisioning, which is a different
-        // question and would make "cold" mean something else for this engine
+        // removing those would measure provisioning, which is a different
+        // question, and would make "cold" mean something else for this engine
         // than for the others.
         platform::remove_tree(job.project_dir / "target");
     }
 
 private:
-    bool optimised_;
+    std::string         program_;
+    mutable std::string label_;
+
+    // `mcpp --version` prints "mcpp <version>". Empty means the binary could not
+    // be run at all — which probe() reports as unavailable rather than failed.
+    std::string version_string() const {
+        const auto out = platform::run_capture({program_, "--version"});
+        if (!out) return {};
+        auto line = *out;
+        if (const auto nl = line.find('\n'); nl != std::string::npos) line.resize(nl);
+        while (!line.empty() && (line.back() == '\r' || line.back() == ' ')) line.pop_back();
+        return line;
+    }
+
+    std::string discover_label() const {
+        const auto v = version_string();          // e.g. "mcpp 2026.8.12.1"
+        if (v.empty()) return "mcpp";
+        const auto sp = v.rfind(' ');
+        if (sp == std::string::npos) return "mcpp";
+        // "mcpp@2026.8.12.1" — distinct per version, so two binaries never
+        // collapse into one row of the result table.
+        return std::format("mcpp@{}", v.substr(sp + 1));
+    }
 };
 
-export std::unique_ptr<Engine> make_mcpp()     { return std::make_unique<McppEngine>(false); }
-export std::unique_ptr<Engine> make_mcpp_opt() { return std::make_unique<McppEngine>(true); }
+export std::unique_ptr<Engine> make_mcpp(std::string program = "mcpp",
+                                         std::string label = {}) {
+    return std::make_unique<McppEngine>(std::move(program), std::move(label));
+}
 
 }  // namespace bench::engines

bench/src/fixture/buildfiles.cppm

@@ -76,10 +76,17 @@ inline void emit_mcpp(const std::filesystem::path& root, Variant variant, const
         "\n"
         "[build]\n"
         "default-profile = \"release\"\n";
-    if (variant != Variant::Headers)
-        toml += "include_dirs = [\"src\"]\n";
-    else
-        toml += "include_dirs = [\"include\"]\n";
+    toml += variant == Variant::Headers ? "include_dirs = [\"include\"]\n"
+                                        : "include_dirs = [\"src\"]\n";
+    // The toolchain is PINNED, matching every other mcpp project in this repo.
+    // Relying on the machine's global default makes the fixture build depend on
+    // ambient state — it works on a developer box that has one and fails on a
+    // fresh CI sandbox that does not, which is exactly how this surfaced: green
+    // locally, "seed build exited 1" on the runner.
+    toml += "\n[toolchain]\n"
+            "default = \"gcc@16.1.0\"\n"
+            "macos   = \"llvm@22.1.8\"\n"
+            "windows = \"llvm@20.1.7\"\n";
     detail::write(root / "mcpp.toml", toml);
 }