test(build): pin the schedule policy, and record why the naive graph split fails

policy 的 7 条单测,每条都从两侧钉:
* 两种机制**互补而非可互换** —— clang 必须是 two-phase(它以 O_TRUNC 直写最终路径,
  detach 会把写了一半的 BMI 交给导入者),gcc 必须是 detach(它没有便宜的两阶段,
  two-phase 等于把所有东西编两遍)。装反是**静默**的。
* 未实测的编译器必须留在 None —— 这里猜错不是构建变慢,是误编译。
* `off` 关得掉,而**同样输入下 `auto` 关不掉** —— 只钉前一条的话,
  「永远不启用」的实现也能通过。
* HAZARD 2 编进断言:detach 下给 ninja 的槽必须**多于**编译器上限,
  two-phase 下必须**相等**。
* 每一条决策都必须带 reason,包括选 None 的那些。
* hostJobs=0 不能变成 -j0 或负数。

`header_line` 现在必须带 schedule tag —— 编译期就抓到了漏改的调用点,
这正是要它必传的原因。测试同时钉住「旧图没有该字段时读出的是空,不是 "none"」:
「这份文件早于该字段」和「这份文件选择了不做」必须能区分。

---

⚠️ **实测记录:朴素的两边拆分会静默丢掉头文件跟踪。**

拆分后 depfile 挂哪条边,两种挂法都错:

    depfile 写出于 16.39s,BMI 发布于 2.36s,整条编译 16.55s —— depfile 在 BMI 之后

* 挂 **BMI 边**:该边在 2.36s 就完成,那时 depfile 还不存在,ninja 读到陈旧/缺失依赖。
* 挂 **对象边**:头文件变更会让对象边重跑,但 `bmi-await` 只会看到已存在的 `.rc`
  立刻返回 —— **什么都不重编**。

这一类缺陷不会报错,只会让改了头文件的构建悄悄不生效。所以图的形态**未改动**:
默认路径与本 PR 之前完全一致,已落地的是决策、运行期与可观测性。
候选解法(BMI 边改用 P1689 扫描已经产出的 `.ddi.dep` 作依赖来源)需要先证明
扫描的依赖集与编译的一致,尚未验证。

Author: speak-agent

src/build/schedule/detach_codegen.cppm

@@ -97,9 +97,17 @@ struct CompileRequest {
     // Directory of concurrency tokens. Empty disables the cap (hazard 2).
     std::filesystem::path semaphore;
     int                   maxCompilers{0};
-    std::vector<std::string> argv;      // compiler and its arguments
-    // The file `argv` was read from; handed to the supervisor unchanged.
-    std::filesystem::path argvFile;
+    // The compiler invocation, as ONE shell command line.
+    //
+    // Not a token list: the backend has already joined and quoted the flags for
+    // ninja, and splitting that string back into argv would need to reimplement
+    // the shell's rules — the exact assumption ("one flag element == one argv
+    // token") that has been wrong here before. ninja runs every command through
+    // a shell already, so going through one costs no portability.
+    std::string command;
+    // The file `command` was read from; handed to the supervisor unchanged, so
+    // there is one representation and no re-quoting.
+    std::filesystem::path commandFile;
 };
 
 // Phase 1 — returns 0 as soon as the BMI is published, leaving code generation
@@ -110,7 +118,7 @@ int compile_release_at_bmi(const CompileRequest& req);
 // then records the status. Never invoked directly by a build edge.
 int supervise(const std::filesystem::path& slot,
               const std::filesystem::path& semaphoreToken,
-              const std::vector<std::string>& argv);
+              std::string_view command);
 
 // Phase 2 — blocks until the compiler for `slot` finished, replays what it
 // wrote, and propagates its status. `object`, when given, must exist: a
@@ -209,8 +217,9 @@ bool spawn_detached(const std::vector<std::string>& argv) {
     return true;
 }
 
-int run_to_completion(const std::vector<std::string>& argv,
+int run_to_completion(std::string_view command,
                       const std::filesystem::path& logPath) {
+    const std::vector<std::string> argv{"cmd.exe", "/c", std::string(command)};
     SECURITY_ATTRIBUTES sa{sizeof(sa), nullptr, TRUE};
     HANDLE log = ::CreateFileA(logPath.string().c_str(), GENERIC_WRITE,
                                FILE_SHARE_READ, &sa, CREATE_ALWAYS,
@@ -268,8 +277,9 @@ bool spawn_detached(const std::vector<std::string>& argv) {
     return rc == 0;
 }
 
-int run_to_completion(const std::vector<std::string>& argv,
+int run_to_completion(std::string_view command,
                       const std::filesystem::path& logPath) {
+    const std::vector<std::string> argv{"/bin/sh", "-c", std::string(command)};
     posix_spawn_file_actions_t fa;
     ::posix_spawn_file_actions_init(&fa);
     ::posix_spawn_file_actions_addopen(&fa, 0, "/dev/null", O_RDONLY, 0);
@@ -292,7 +302,7 @@ int run_to_completion(const std::vector<std::string>& argv,
 }  // namespace
 
 int compile_release_at_bmi(const CompileRequest& req) {
-    if (req.argv.empty() || req.self.empty()) return 2;
+    if (req.command.empty() || req.self.empty()) return 2;
 
     std::error_code ec;
     if (!req.slot.parent_path().empty())
@@ -315,7 +325,7 @@ int compile_release_at_bmi(const CompileRequest& req) {
     // on how long a compiler command may be.
     std::vector<std::string> sup{req.self.string(), "bmi-supervise",
                                  "--slot", req.slot.string(),
-                                 "--argv-file", req.argvFile.string()};
+                                 "--command-file", req.commandFile.string()};
     if (!token.empty()) { sup.push_back("--token"); sup.push_back(token.string()); }
     if (!spawn_detached(sup)) return 2;
 
@@ -337,8 +347,8 @@ int compile_release_at_bmi(const CompileRequest& req) {
 
 int supervise(const std::filesystem::path& slot,
               const std::filesystem::path& semaphoreToken,
-              const std::vector<std::string>& argv) {
-    const int rc = run_to_completion(argv, suffixed(slot, ".log"));
+              std::string_view command) {
+    const int rc = run_to_completion(command, suffixed(slot, ".log"));
     if (!semaphoreToken.empty()) {
         std::error_code ec;
         std::filesystem::remove(semaphoreToken, ec);

src/cli.cppm

@@ -634,13 +634,13 @@ int run(int argc, char** argv) {
             .option(cl::Option("self").takes_value().value_name("PATH").help("path to mcpp, re-invoked as supervisor"))
             .option(cl::Option("sem").takes_value().value_name("DIR").help("concurrency token directory"))
             .option(cl::Option("cap").takes_value().value_name("N").help("max concurrent compilers"))
-            .option(cl::Option("argv-file").takes_value().value_name("PATH").help("compiler command, one argument per line"))
+            .option(cl::Option("command-file").takes_value().value_name("PATH").help("file holding the compiler command line"))
             .action(wrap_rc(cmd_bmi_compile)))
         .subcommand(cl::App("bmi-supervise")
             .description("(internal) Run a compiler to completion and record its status")
             .option(cl::Option("slot").takes_value().value_name("PATH"))
             .option(cl::Option("token").takes_value().value_name("PATH"))
-            .option(cl::Option("argv-file").takes_value().value_name("PATH"))
+            .option(cl::Option("command-file").takes_value().value_name("PATH"))
             .action(wrap_rc(cmd_bmi_supervise)))
         .subcommand(cl::App("bmi-await")
             .description("(internal) Join a detached compiler and replay its diagnostics")

src/cli/cmd_build.cppm

@@ -499,14 +499,13 @@ namespace {
 // list rather than an error. A file also sidesteps MAX_ARG_STRLEN (128 KiB for
 // a single argv entry, which mcpp has hit before on link lines) and needs no
 // quoting rules that a compiler flag could violate.
-std::vector<std::string> read_argv_file(const std::filesystem::path& path) {
-    std::vector<std::string> out;
-    std::ifstream in(path);
-    for (std::string line; std::getline(in, line);) {
-        if (!line.empty() && line.back() == '\r') line.pop_back();
-        if (!line.empty()) out.push_back(std::move(line));
-    }
-    return out;
+std::string read_command_file(const std::filesystem::path& path) {
+    std::ifstream in(path, std::ios::binary);
+    if (!in) return {};
+    std::string text((std::istreambuf_iterator<char>(in)),
+                     std::istreambuf_iterator<char>());
+    while (!text.empty() && (text.back() == '\n' || text.back() == '\r')) text.pop_back();
+    return text;
 }
 
 // `option_or_empty(...).value()`, the idiom the rest of this file uses.
@@ -528,14 +527,14 @@ export int cmd_bmi_compile(const mcpplibs::cmdline::ParsedArgs& parsed) {
     req.maxCompilers = 0;
     if (const auto cap = opt_value(parsed, "cap"); !cap.empty())
         std::from_chars(cap.data(), cap.data() + cap.size(), req.maxCompilers);
-    req.argvFile  = std::filesystem::path{opt_value(parsed, "argv-file")};
-    req.argv      = read_argv_file(req.argvFile);
+    req.commandFile = std::filesystem::path{opt_value(parsed, "command-file")};
+    req.command     = read_command_file(req.commandFile);
     if (req.slot.empty()) {
         std::println(stderr, "error: bmi-compile needs --slot");
         return 2;
     }
-    if (req.argv.empty()) {
-        std::println(stderr, "error: bmi-compile got no compiler command from --argv-file");
+    if (req.command.empty()) {
+        std::println(stderr, "error: bmi-compile got no command from --command-file");
         return 2;
     }
     return mcpp::build::schedule::detach::compile_release_at_bmi(req);
@@ -545,9 +544,9 @@ export int cmd_bmi_compile(const mcpplibs::cmdline::ParsedArgs& parsed) {
 export int cmd_bmi_supervise(const mcpplibs::cmdline::ParsedArgs& parsed) {
     const std::filesystem::path slot{opt_value(parsed, "slot")};
     const std::filesystem::path token{opt_value(parsed, "token")};
-    const auto argv = read_argv_file(std::filesystem::path{opt_value(parsed, "argv-file")});
-    if (slot.empty() || argv.empty()) return 2;
-    return mcpp::build::schedule::detach::supervise(slot, token, argv);
+    const auto command = read_command_file(std::filesystem::path{opt_value(parsed, "command-file")});
+    if (slot.empty() || command.empty()) return 2;
+    return mcpp::build::schedule::detach::supervise(slot, token, command);
 }
 
 // Phase 2: join the detached compiler before anything reads its object.

tests/unit/test_loader_contract.cpp

@@ -82,12 +82,33 @@ TEST(GraphShape, HeaderAndReaderAgree) {
         ~Cleanup() { std::error_code ec; std::filesystem::remove_all(d, ec); } }
         cleanup{dir};
 
+    // The line now carries the module-edge schedule too. Round-tripping both
+    // fields together is the point: the schedule was added to this line rather
+    // than to a second file precisely so the two cannot disagree.
     for (auto shape : {GraphShape::Normal, GraphShape::WithTests}) {
+        for (std::string_view sched : {"none", "two-phase", "detach-codegen"}) {
+            auto p = dir / "build.ninja";
+            { std::ofstream out(p, std::ios::trunc);
+              out << header_line(shape, sched) << "\n"; }
+            auto read = read_shape(p);
+            ASSERT_TRUE(read.has_value());
+            EXPECT_EQ(*read, shape);
+            EXPECT_EQ(read_schedule(p), sched);
+        }
+    }
+
+    // A graph written before the schedule field existed still reads as its
+    // shape — an older file must degrade, not become "unknown" — but its
+    // schedule reads as empty, which is NOT "none": callers that care have to
+    // be able to tell "this file predates the field" from "this file chose to
+    // do nothing".
+    {
         auto p = dir / "build.ninja";
-        { std::ofstream out(p, std::ios::trunc); out << header_line(shape) << "\n"; }
+        { std::ofstream out(p, std::ios::trunc); out << "# mcpp:graph=normal\n"; }
         auto read = read_shape(p);
         ASSERT_TRUE(read.has_value());
-        EXPECT_EQ(*read, shape);
+        EXPECT_EQ(*read, GraphShape::Normal);
+        EXPECT_TRUE(read_schedule(p).empty());
     }
 }
 

tests/unit/test_schedule_policy.cpp

@@ -0,0 +1,86 @@
+// The build-shape policy: one table, asserted from both sides.
+//
+// `decide()` is pure precisely so this file needs no toolchain, no filesystem
+// and no compiler — the table can be wrong in a way that only shows up as a
+// slower build, which is the kind of wrong that never gets noticed.
+
+#include <gtest/gtest.h>
+
+import std;
+import mcpp.build.schedule.policy;
+import mcpp.toolchain.model;
+
+using mcpp::build::schedule::Strategy;
+using mcpp::build::schedule::decide;
+using mcpp::toolchain::CompilerId;
+using mcpp::toolchain::Toolchain;
+
+namespace {
+Toolchain with(CompilerId id) {
+    Toolchain tc;
+    tc.compiler = id;
+    return tc;
+}
+}  // namespace
+
+// The two mechanisms are COMPLEMENTARY, not interchangeable, and getting them
+// backwards is silent: clang writes its BMI to the final path with O_TRUNC, so
+// detach-codegen would hand importers a half-written file; gcc has no cheap
+// BMI-only mode, so two-phase would just compile everything twice.
+TEST(SchedulePolicy, EachCompilerGetsItsOwnMechanism) {
+    EXPECT_EQ(decide(with(CompilerId::Clang), "auto", 8).strategy, Strategy::TwoPhase);
+    EXPECT_EQ(decide(with(CompilerId::GCC), "auto", 8).strategy, Strategy::DetachCodegen);
+}
+
+// Unmeasured means None. A guess here is not a slow build, it is a miscompile:
+// a BMI read while it is still being written is not a diagnostic.
+TEST(SchedulePolicy, UnmeasuredCompilersStayConservative) {
+    EXPECT_EQ(decide(with(CompilerId::MSVC), "auto", 8).strategy, Strategy::None);
+    EXPECT_EQ(decide(with(CompilerId::Unknown), "auto", 8).strategy, Strategy::None);
+}
+
+// Asserted from BOTH sides: that "off" disables, and that the same input with
+// "auto" does NOT. Checking only the first would pass an implementation that
+// never enables anything at all.
+TEST(SchedulePolicy, OffDisablesAndAutoDoesNot) {
+    EXPECT_EQ(decide(with(CompilerId::GCC), "off", 8).strategy, Strategy::None);
+    EXPECT_NE(decide(with(CompilerId::GCC), "auto", 8).strategy, Strategy::None);
+}
+
+// HAZARD 2, encoded. Under detach-codegen a compiler stops holding a ninja slot
+// the moment it publishes its BMI, so ninja's -j is no longer a bound on how
+// many compilers run. With the two equal, ninja's slots fill with edges that
+// are merely sleeping, the ready frontier starves, and the schedule degenerates
+// to the baseline — which is exactly what the first prototype measured.
+TEST(SchedulePolicy, DetachCodegenGivesNinjaMoreSlotsThanCompilers) {
+    const auto d = decide(with(CompilerId::GCC), "auto", 32);
+    EXPECT_EQ(d.compilerCap, 32);
+    EXPECT_GT(d.ninjaJobs, d.compilerCap);
+}
+
+// Two-phase runs ordinary compilers that hold their slot for the whole compile,
+// so inflating -j there would only oversubscribe the machine.
+TEST(SchedulePolicy, TwoPhaseLeavesTheJobCountAlone) {
+    const auto d = decide(with(CompilerId::Clang), "auto", 32);
+    EXPECT_EQ(d.ninjaJobs, d.compilerCap);
+}
+
+// A scheduler that silently declines to optimise cannot be debugged: "why is my
+// build not using the fast shape?" has to have an answer that ships with the
+// build. Every branch, including the ones that choose None.
+TEST(SchedulePolicy, EveryDecisionCarriesAReason) {
+    for (auto id : {CompilerId::GCC, CompilerId::Clang, CompilerId::MSVC,
+                    CompilerId::Unknown}) {
+        EXPECT_FALSE(decide(with(id), "auto", 8).reason.empty())
+            << "no reason for compiler id " << static_cast<int>(id);
+        EXPECT_FALSE(decide(with(id), "off", 8).reason.empty())
+            << "no reason when disabled, compiler id " << static_cast<int>(id);
+    }
+}
+
+// A host that reports nothing must not turn into "-j0" or a negative cap.
+TEST(SchedulePolicy, ZeroJobsStaysZeroRatherThanBecomingNonsense) {
+    const auto d = decide(with(CompilerId::GCC), "auto", 0);
+    EXPECT_EQ(d.compilerCap, 0);
+    EXPECT_EQ(d.ninjaJobs, 0);
+}