feat(build): resolve the schedule once, record it in the graph, report why

—— 决策、并发与可观测性收敛到一处;图的形态尚未改变

`schedule::decide()` 在 prepare 里求值一次,结果落在 `BuildPlan` 上:
后端据此写图、图头记下 tag、`--verbose` 打印理由 —— 三个读者,一次推导。

    # mcpp:graph=normal;schedule=detach-codegen
    build: schedule: detach-codegen — gcc: publishes the BMI with rename()
           at ~22% of the compile, so importers can start before code generation

**并发解析也搬进 policy**。「跑几个」和「什么形状」是同一类决策,分开放就会再次
出现两处推导 —— 这正是 BMI 等价判断(藏在 ninja 命令里的 POSIX shell,Windows 整段没有)
和作业数(ninja 默认值)当初漂开的原因。`execute` 现在读 `plan.scheduleNinjaJobs`,
不再自己解析;`resolve_jobs` 用回调报告非法值,因而不依赖 UI、可单测。

**失效靠指纹,不靠守卫**。两条快路径跑在 plan 之前,拿不到工具链,
所以不可能在那里推导出「本次应有的调度」——给它传参数就等于第二次推导。
改为把开关折进指纹:换了调度就换构建目录,旧形状的图**结构上不可达**。
图头那行 tag 因此是给人看的(和 `mcpp explain`),不承担失效职责。
只在开关非默认时才折入,已有构建目录的身份不受影响。

顺带:`[build] schedule`(auto|on|off)+ `MCPP_BMI_SCHEDULE`,与 `jobs` 同样存为文本 ——
"auto" 的含义取决于做构建的那台机器,parse 期解析等于把一台机器的答案冻进 manifest。

Author: speak-agent

src/build/execute.cppm

@@ -377,46 +377,11 @@ compute_subos_env(const mcpp::build::BuildPlan& plan) {
 // so the latter doesn't call prepare_build twice (and re-print the toolchain
 // resolution banner).
 // How many compiles to run at once.
-//
-// Precedence: `--jobs` (arriving as MCPP_JOBS, same channel --offline uses and
-// for the same reason — the consumers span subsystems) > `[build] jobs` >
-// 0, which means "say nothing" and leaves ninja's own default (nproc + 2).
-// The default is deliberately unchanged: altering everyone's concurrency is a
-// behaviour change, and this lands as an opt-in first.
-//
-// `auto` is resolved HERE, against the machine doing the build, never frozen
-// into a manifest. Measured on this repository: the cold self-build takes
-// 81.0s at -j8 and 79.9s at -j32 — 4x the workers for 1.4%, because the build
-// is latency-bound. Meanwhile a single module compile peaks at 0.5-1.0 GB, so
-// the extra jobs are pure memory pressure; on a high-core, modest-RAM machine
-// ninja's default swaps.
-std::size_t resolve_parallel_jobs(const mcpp::build::BuildPlan& plan) {
-    auto from_text = [&](std::string_view v) -> std::optional<std::size_t> {
-        if (v.empty()) return std::nullopt;
-        if (v == "auto") {
-            const auto cap = mcpp::platform::capacity::host_capacity();
-            return static_cast<std::size_t>(
-                mcpp::platform::capacity::recommended_jobs(cap));
-        }
-        std::size_t n = 0;
-        const auto* first = v.data();
-        const auto* last  = v.data() + v.size();
-        if (auto [p, ec] = std::from_chars(first, last, n);
-            ec == std::errc{} && p == last && n > 0)
-            return n;
-        // A malformed value must not silently become "use the default" — that
-        // is how a typo turns into a build that is mysteriously slower.
-        mcpp::ui::warning(std::format(
-            "ignoring invalid job count '{}' (expected a positive number or 'auto')", v));
-        return std::nullopt;
-    };
-
-    if (const char* e = std::getenv("MCPP_JOBS"))
-        if (auto n = from_text(e)) return *n;
-    if (auto n = from_text(plan.manifest.buildConfig.jobs)) return *n;
-    return 0;
-}
-
+// Concurrency and the module-edge schedule are resolved together in
+// mcpp.build.schedule.policy and stamped onto the plan, so this reads one value
+// instead of re-deriving it. `scheduleNinjaJobs` is NOT the compiler cap under
+// detach-codegen: a detached compiler stops holding a ninja slot, so ninja is
+// handed a larger number on purpose.
 export int run_build_plan(BuildContext& ctx, bool verbose, bool no_cache,
                    std::string_view targetOverride = "") {
     // `--cache=off` means a cold build: no global cache, and target/ cleared —
@@ -488,7 +453,7 @@ export int run_build_plan(BuildContext& ctx, bool verbose, bool no_cache,
 
     mcpp::build::BuildOptions opts;
     opts.verbose = verbose;
-    opts.parallelJobs = resolve_parallel_jobs(ctx.plan);
+    opts.parallelJobs = static_cast<std::size_t>(ctx.plan.scheduleNinjaJobs);
     auto r = be->build(ctx.plan, opts);
     if (!r) {
         std::fflush(stdout);

src/build/graph_shape.cppm

@@ -47,8 +47,15 @@ std::string_view to_string(GraphShape shape) {
 
 // The marker line, without its newline. A ninja comment, so it costs nothing
 // and older ninja versions do not care.
-std::string header_line(GraphShape shape) {
-    return std::format("# mcpp:graph={}", to_string(shape));
+// `scheduleTag` names the SHAPE OF THE MODULE EDGES (see
+// mcpp.build.schedule.policy): "none", "two-phase", "detach-codegen". It rides
+// the same line for the same reason the shape does — build.ninja is shared
+// mutable state and the fast path replays it, so a graph built under one
+// schedule must not be replayed under another. Flipping the switch has to
+// invalidate the graph, and the only way that cannot be forgotten is if the
+// graph says which schedule produced it.
+std::string header_line(GraphShape shape, std::string_view scheduleTag) {
+    return std::format("# mcpp:graph={};schedule={}", to_string(shape), scheduleTag);
 }
 
 // Read the shape back. `nullopt` means "this file does not say" — a build.ninja
@@ -68,6 +75,10 @@ std::optional<GraphShape> read_shape(const std::filesystem::path& ninjaPath) {
         auto value = std::string_view(line).substr(prefix.size());
         while (!value.empty() && (value.back() == '\r' || value.back() == ' '))
             value.remove_suffix(1);
+        // `graph=<shape>[;schedule=<tag>]`. Split before comparing, so adding
+        // the schedule field does not turn every existing graph into "unknown".
+        if (const auto semi = value.find(';'); semi != std::string_view::npos)
+            value = value.substr(0, semi);
         if (value == "normal") return GraphShape::Normal;
         if (value == "test")   return GraphShape::WithTests;
         // A shape this binary does not know is not `Normal`. An older mcpp
@@ -77,7 +88,40 @@ std::optional<GraphShape> read_shape(const std::filesystem::path& ninjaPath) {
     return std::nullopt;
 }
 
+// The schedule tag this graph was written with. Empty means the file predates
+// the field — which is NOT the same as "none": an unlabelled graph is exactly
+// the case that must not be replayed blind, so callers compare and miss.
+std::string read_schedule(const std::filesystem::path& ninjaPath) {
+    std::ifstream input(ninjaPath);
+    if (!input) return {};
+    std::string line;
+    for (int i = 0; i < 8 && std::getline(input, line); ++i) {
+        constexpr std::string_view prefix = "# mcpp:graph=";
+        if (!line.starts_with(prefix)) continue;
+        auto value = std::string_view(line).substr(prefix.size());
+        while (!value.empty() && (value.back() == '\r' || value.back() == ' '))
+            value.remove_suffix(1);
+        const auto semi = value.find(';');
+        if (semi == std::string_view::npos) return {};
+        auto rest = value.substr(semi + 1);
+        constexpr std::string_view schedPrefix = "schedule=";
+        if (!rest.starts_with(schedPrefix)) return {};
+        return std::string(rest.substr(schedPrefix.size()));
+    }
+    return {};
+}
+
 // The one question every fast path asks.
+//
+// It deliberately does NOT compare the schedule tag. The fast paths run BEFORE
+// a plan exists, so they have no toolchain to derive the expected schedule
+// from — and passing one in would mean deriving the same decision a second
+// time, in a place that cannot see the compiler.
+//
+// Instead the schedule SWITCH is part of the toolchain fingerprint, so flipping
+// it lands in a different build directory: a graph written under one schedule
+// is structurally unreachable from a build configured with another. The tag on
+// the line is then for humans and for `mcpp explain`, not for invalidation.
 bool is_plain_build_graph(const std::filesystem::path& ninjaPath) {
     return read_shape(ninjaPath) == GraphShape::Normal;
 }

src/build/ninja_backend.cppm

@@ -407,7 +407,7 @@ std::string emit_ninja_string(const BuildPlan& plan) {
     // #407: the graph declares which mode produced it, because three modes
     // write this one file and the fast path has to know what it is about to
     // replay. Must stay within the first few lines — see read_shape.
-    append(mcpp::build::header_line(plan.graphShape) + "\n");
+    append(mcpp::build::header_line(plan.graphShape, plan.scheduleTag) + "\n");
     append("ninja_required_version = 1.11\n\n");
 
     // All compile/link flags are computed once via flags.cppm.

src/build/plan.cppm

@@ -145,6 +145,18 @@ struct BuildPlan {
     // share an output directory and overwrite each other's graph; this is what
     // lets a fast path tell them apart (mcpp#407, mcpp.build.graph_shape).
     GraphShape                      graphShape = GraphShape::Normal;
+    // The module-edge schedule this plan will emit, resolved ONCE (see
+    // mcpp.build.schedule.policy). The backend writes the graph in this shape,
+    // the graph records the tag, and the fast path compares against it — three
+    // readers, one derivation. Deriving it separately in the backend and in the
+    // executor is how the BMI-equivalence check and the job count drifted into
+    // disagreeing about what a module edge is.
+    std::string                     scheduleTag = "none";
+    // What to hand ninja. Under detach-codegen a compiler stops holding a slot
+    // when it publishes, so this must exceed the real compiler cap or the ready
+    // frontier starves — see the hazard note in schedule/detach_codegen.
+    int                             scheduleNinjaJobs = 0;
+    int                             scheduleCompilerCap = 0;
     // One immutable snapshot selected before workspace member substitution.
     // Build/run/test and cache fast paths consume this value; none may re-read
     // xlings active/current state.

src/build/prepare.cppm

@@ -33,6 +33,7 @@ import mcpp.toolchain.post_install;
 import mcpp.toolchain.abi;
 import mcpp.toolchain.triple;
 import mcpp.build.plan;
+import mcpp.build.schedule.policy;
 import mcpp.build.graph_shape;  // #407: the graph says which mode wrote it
 import mcpp.build.runtime_validation;  // declared artifact -> identity verdict
 import mcpp.build.cache_key;
@@ -5226,6 +5227,17 @@ prepare_build(bool print_fingerprint,
     fpi.cppStandard         = m->package.standard;
     fpi.compileFlags        = canonical_compile_flags(*m)
                               + canonical_package_build_metadata(packages);
+    // The module-edge schedule changes the SHAPE of build.ninja, and the fast
+    // path replays that file without a plan to compare against. Folding the
+    // switch into the fingerprint puts a differently-scheduled build in a
+    // different directory, which makes replaying the wrong shape structurally
+    // impossible instead of merely guarded. Only appended when non-default, so
+    // existing build directories keep their identity.
+    if (const auto sched = mcpp::build::schedule::requested_switch(*m);
+        sched != "auto") {
+        fpi.compileFlags += " #schedule=";
+        fpi.compileFlags += sched;
+    }
     if (m->cppStandard.experimental) {
         // c++fly gate flags are derived (not manifest-declared): fold them in
         // so a cppfly table change across mcpp versions re-fingerprints.
@@ -5311,6 +5323,24 @@ prepare_build(bool print_fingerprint,
     ctx.plan.graphShape = (includeDevDeps || !extraTargets.empty())
         ? mcpp::build::GraphShape::WithTests
         : mcpp::build::GraphShape::Normal;
+    // Resolve the module-edge schedule ONCE, here, where both the toolchain and
+    // the manifest are in hand. The backend writes the graph in this shape, the
+    // graph records the tag, and `mcpp build --verbose` prints the reason — all
+    // three read this, none of them re-derives it.
+    {
+        const auto decision = mcpp::build::schedule::decide(
+            ctx.plan.toolchain,
+            mcpp::build::schedule::requested_switch(*m),
+            mcpp::build::schedule::resolve_jobs(*m, [](std::string_view bad) {
+                mcpp::ui::warning(std::format(
+                    "ignoring invalid job count '{}' (expected a positive number or 'auto')", bad));
+            }));
+        ctx.plan.scheduleTag         = std::string(mcpp::build::schedule::to_string(decision.strategy));
+        ctx.plan.scheduleNinjaJobs   = decision.ninjaJobs;
+        ctx.plan.scheduleCompilerCap = decision.compilerCap;
+        mcpp::log::verbose("build", std::format("schedule: {} — {}",
+                                                ctx.plan.scheduleTag, decision.reason));
+    }
     ctx.plan.runtimeBinding = runtimeBindingSnapshot;
     mcpp::build::merge_runtime_binding_contract(
         ctx.plan, runtimeBindingSnapshot);

src/build/schedule/policy.cppm

@@ -7,10 +7,13 @@
 // whatever ninja defaulted to. Deriving the same decision in two places is how
 // the two halves drifted apart. This module is the only place it is derived.
 //
-// PURE. No filesystem, no processes, no environment reads — a caller passes the
-// facts in and gets a Decision plus the sentence explaining it. That is what
-// makes the policy unit-testable without a toolchain, and what lets the reason
-// be printed, logged and written into build.ninja unchanged.
+// `decide()` IS PURE. No filesystem, no processes, no environment — a caller
+// hands it facts and gets a Decision plus the sentence explaining it, so the
+// table is unit-testable without a toolchain and the reason can be printed,
+// logged and written into build.ninja unchanged. `requested_switch()` is the
+// one impure function here, and it is impure on purpose: the switch has to be
+// read somewhere, and two callers each doing env-then-manifest in their own
+// order is exactly the duplicate derivation this module exists to prevent.
 //
 // THE MEASUREMENTS BEHIND THE TABLE (2026-08-13, mcpp building itself: 138
 // module interface units, 57k lines, i9-13900K, gcc@16.1.0 / llvm@22.1.8):
@@ -49,6 +52,8 @@ export module mcpp.build.schedule.policy;
 
 import std;
 import mcpp.toolchain.model;
+import mcpp.manifest;
+import mcpp.platform.capacity;
 
 export namespace mcpp::build::schedule {
 
@@ -84,6 +89,32 @@ struct Decision {
     int ninjaJobs = 0;
 };
 
+// The one place the switch is READ. `decide` above stays pure — a caller hands
+// it facts — but the switch itself has to come from somewhere, and having two
+// callers each read env-then-manifest in their own order is precisely the
+// duplicate-derivation this module exists to prevent.
+//
+// Precedence matches every other mcpp switch: environment beats manifest.
+std::string requested_switch(const manifest::Manifest& m);
+
+// How many compilers this machine should run at once.
+//
+// Precedence: MCPP_JOBS (where `--jobs` lands) > `[build] jobs` > 0, meaning
+// "say nothing" and leave the backend's own default. The default is unchanged
+// on purpose: altering everyone's concurrency is a behaviour change.
+//
+// `auto` is resolved HERE, against the machine doing the build, never frozen
+// into a manifest. Measured on this repository: the cold self-build takes 81.0s
+// at -j8 and 79.9s at -j32 — 4x the workers for 1.4%, because the build is
+// latency-bound — while a single module compile peaks at 0.5–1.0 GB, so the
+// extra jobs are pure memory pressure. On a high-core, modest-RAM machine the
+// backend default swaps.
+//
+// `onInvalid` is called with the offending text instead of warning directly, so
+// this stays free of any UI dependency and remains testable.
+int resolve_jobs(const manifest::Manifest& m,
+                 const std::function<void(std::string_view)>& onInvalid = {});
+
 // `requested` is the user's switch: "auto" (default), "on", "off". `hostJobs` is
 // the already-resolved parallelism (`--jobs`, `[build] jobs`, or the backend
 // default), i.e. how many compilers this machine should run at once.
@@ -137,4 +168,35 @@ Decision decide(const toolchain::Toolchain& tc, std::string_view requested, int
     return d;
 }
 
+int resolve_jobs(const manifest::Manifest& m,
+                 const std::function<void(std::string_view)>& onInvalid) {
+    auto from_text = [&](std::string_view v) -> std::optional<int> {
+        if (v.empty()) return std::nullopt;
+        if (v == "auto") {
+            const auto cap = platform::capacity::host_capacity();
+            return platform::capacity::recommended_jobs(cap);
+        }
+        int n = 0;
+        const auto* first = v.data();
+        const auto* last  = v.data() + v.size();
+        if (auto [p, ec] = std::from_chars(first, last, n);
+            ec == std::errc{} && p == last && n > 0)
+            return n;
+        // A malformed value must not silently become "use the default" — that
+        // is how a typo turns into a build that is mysteriously slower.
+        if (onInvalid) onInvalid(v);
+        return std::nullopt;
+    };
+    if (const char* e = std::getenv("MCPP_JOBS"))
+        if (auto n = from_text(e)) return *n;
+    if (auto n = from_text(m.buildConfig.jobs)) return *n;
+    return 0;
+}
+
+std::string requested_switch(const manifest::Manifest& m) {
+    if (const char* e = std::getenv("MCPP_BMI_SCHEDULE"); e && *e) return std::string(e);
+    if (!m.buildConfig.schedule.empty()) return m.buildConfig.schedule;
+    return "auto";
+}
+
 }  // namespace mcpp::build::schedule

src/manifest/toml.cppm

@@ -1046,6 +1046,7 @@ std::expected<Manifest, ManifestError> parse_string(std::string_view content,
     // where they are used, so a bad value warns at build time instead of making
     // the whole manifest unloadable. (A published package carrying an unknown
     // key must never break an older mcpp — same rule the dependency keys follow.)
+    if (auto v = doc->get_string("build.schedule")) m.buildConfig.schedule = *v;
     if (auto v = doc->get_string("build.jobs")) m.buildConfig.jobs = *v;
     else if (auto n = doc->get_int("build.jobs")) m.buildConfig.jobs = std::to_string(*n);
     if (auto v = doc->get_string("build.default-profile")) m.buildConfig.defaultProfile = *v;
@@ -1080,7 +1081,7 @@ std::expected<Manifest, ManifestError> parse_string(std::string_view content,
         "allow_host_libs", "build_program_timeout", "c_standard", "cache",
         "cflags", "cxxflags", "cxx_runtime", "default-profile", "defines",
         "dialect_cxxflags", "flags", "include_dirs", "include_dirs_after",
-        "jobs", "ldflags", "macos_deployment_target", "module_extensions", "profile",
+        "jobs", "ldflags", "schedule", "macos_deployment_target", "module_extensions", "profile",
         "sources", "static_stdlib", "target",
     };
     if (auto* bt = doc->get_table("build")) {

src/manifest/types.cppm

@@ -360,6 +360,11 @@ struct BuildConfig : BuildInputs {
     // that actually runs: resolving it at parse time would freeze one machine's
     // core count into a value that then travels with the manifest.
     std::string jobs;
+    // `[build] schedule` — the module-edge shape: "auto" (default), "on",
+    // "off". Text for the same reason `jobs` is: the meaning of "auto" depends
+    // on the compiler doing the build, and resolving it at parse time would
+    // freeze one machine's answer into a manifest that travels.
+    std::string schedule;
     // feature name → extra source globs gated by that feature. A glob listed
     // here is EXCLUDED from the default build and only compiled/linked when the
     // feature is active for this package (resolved in prepare_build). Lets a