T3 (#724 W3/W4/W5): a device source is not a compile unit; a failed build

program's own diagnostic survives; emit writes no project file

W3 (src/build/plan.cppm): the compile-unit loop now skips
SourceKind::Device graph units, so build.ninja carries no dead cxx_object
edge for a rule-claimed device source, and compile_commands.json / the S1
document agree without their own filter (unit_invocations already excluded
only NASM; nothing else needed to change). The source stays in `watch` and
still reaches the package's build program through MCPP_DEVICE_SOURCES,
since both read the manifest's sources glob directly, not plan.compileUnits.
Checked every other consumer of plan.compileUnits (prepare/plan.cpp's
dependency-cache collection keys by path, not by index, so it is unaffected
beyond a smaller artifact set for a package with device sources).

W4: a package whose build program failed under `emit`'s plan_only records
MCPP_BUILD_DATABASE_PROGRAM_FAILED and applies none of its directives
(state.cppm: new PrepareState::programFailedPackages, set at both call
sites in target_side.cpp and features.cpp). The device-source orphan check
in target_side.cpp now skips such a package outright, instead of reading
every device source as unclaimed and failing the whole member. Also: notes
a phase recorded before prepare_build's own failing return are no longer
silently dropped (driver.cpp: a thread_local sink in the same per-run-sink
style as mcpp::build::refusal, exported as
mcpp::build::take_notes_on_failure); cmd_build.cppm's emit failure path
folds any such note into the one diagnostic SPEC-005 R5.2 allows a wholly-
failed member (path stays the member's mcpp.toml, exactly one entry), so
the true cause is not lost behind a downstream symptom without violating
that invariant. hasProgram's existing exists(build.mcpp) check is now
correct by construction, since a failed program's package never reaches it.

W5 (src/build/prepare/xlings.cpp): ensure_project_index_dir's two calls
under a private work_dir are collapsed into the one call the
ownerRoot==workRoot branch always made, targeting workRoot in every case.
Previously the runtime-environment half (deps/subos/workspace) went to
runtimeSelection.ownerRoot, which is always the real project root
regardless of emit's private work_dir -- so `emit build-database` wrote
<root>/.mcpp/.xlings.json into a project that declares [xlings] deps.

SPEC-005: R3.7 names device sources beside NASM units (both absent from S1
and compile_commands.json, for different reasons -- NASM is a compile unit
excluded from export, a device source is never a compile unit at all). R5.2
gains the sentence that a check whose premise is a build program's
directives does not run for a package whose program failed in this pass.
R2.1 needed no change.

Tests: e2e 808 (device source: no dead ninja edge, absent from both
databases, and the rule still compiles it and the build still runs), e2e
809 (a device source plus a build.mcpp that does not compile: PROGRAM_FAILED
with path build.mcpp, no device-source mention, package still described),
e2e 817 (688's project-tree digest repeated on a stub-xlings fixture with
[xlings] deps: byte-identical tree, no .mcpp/.xlings.json, no write-project
effect, and the private work directory does gain one naming the
dependency). Each fails against the released 2026.9.27.1 binary and passes
on the fresh build. Full regression: all 15 emit/build-database e2e
scripts, 798, and four more that exercise the compile-unit loop (asm/GAS,
NASM, object-path-collision, multi-module) all still pass; `mcpp test`
(130 unit tests) passes.

Author: speak-agent

docs/specs/build-database.md

@@ -100,7 +100,11 @@ mcpp 输出的 S1 文档满足 S1 等级 2,不输出 `ide.options`。等级 3 
 
 ### 3.3 翻译单元
 
-- **R3.7** 除 NASM 单元外,构建计划中的每个编译单元是一个翻译单元。`source`、
+- **R3.7** 除 NASM 单元与规则声明的设备源文件(`SourceKind::Device`)外,构建计划中
+  的每个编译单元是一个翻译单元;两者都不在 S1 文档与 `compile_commands.json` 中
+  出现,但原因不同——NASM 单元是构建计划的编译单元,只是被逐出翻译单元的集合;
+  设备源文件从不是构建计划的编译单元(引擎对其扩展名没有编译规则,能编译它的只有
+  包自己的构建程序,通过一个动作),因而也从不进入这一集合。`source`、
   `work-directory`、`arguments`、`object` 与 `compile_commands.json` 中对应条目的
   `file`、`directory`、`arguments`、`output` 取自同一条记录,因而逐字相同。
   `work-directory` 是编译器实际运行的目录——即输出目录
@@ -170,7 +174,10 @@ mcpp 输出的 S1 文档满足 S1 等级 2,不输出 `ide.options`。等级 3 
   的成员中,构建程序失败的包被描述为不含该程序产生的指令(清单自身的配置、工具链、
   模块图与标准库单元仍照常描述),`diagnostics` 另有一条 `error`,
   `MCPP_BUILD_DATABASE_PROGRAM_FAILED`,`path` 为该包的 `build.mcpp`;后续失败若是
-  由缺失的指令引起,则按前一条规则使整个成员失败。只要 `diagnostics` 中有一条
+  由缺失的指令引起,则按前一条规则使整个成员失败。一项检查若以构建程序的指令为
+  前提(例如"每个设备源文件都被某个动作消费"),对本轮构建程序失败的包不运行:
+  该包已经带着这一条 `PROGRAM_FAILED` 诊断被描述,不应因指令缺失这一后果本身被
+  判成第二个失败,把真正的诊断挤出信封。只要 `diagnostics` 中有一条
   `error`,退出码就是 1,无论 `data` 是否出现。**已实现**(离线诊断码:
   mcpp >= 2026.9.16.1;成员独立规划、`path` 与构建程序失败的描述:mcpp >= 2026.9.26.2)
 - **R5.3** 信封的 `effects` 为 `read-project` 与 `write-global-cache`,运行了构建程序时

src/build/plan.cppm

@@ -1844,8 +1844,24 @@ make_plan(const mcpp::manifest::Manifest&         manifest,
     };
 
     // 1. Compile units in topological order
+    //
+    // A device-kind source (`SourceKind::Device`) is not one of them. The
+    // engine has no compile rule for it — it is compiled, if at all, by the
+    // package's build program through an action (`mcpp::action`), never by a
+    // `cxx_object`/`c_object` edge — so turning it into a `CompileUnit` here
+    // gave every consumer of `plan.compileUnits` a unit nothing runs: a dead
+    // `cxx_object` edge in `build.ninja` with no consumer, and an entry in
+    // `compile_commands.json` and the S1 document naming a compiler that never
+    // ran on the file (design 2026-09-27 §4.1, mcpp#724). Fixed at the source,
+    // once, so ninja, the compile database and S1 agree without each needing
+    // its own filter for this kind. The file itself still reaches `watch`
+    // (build_database.cppm expands the sources glob directly, not through
+    // `plan.compileUnits`), and it still reaches the package's build program
+    // through `MCPP_DEVICE_SOURCES` (features.cpp), which is the one thing
+    // that does compile it.
     for (auto idx : topoOrder) {
         auto& u = graph.units[idx];
+        if (u.kind == mcpp::SourceKind::Device) continue;
         CompileUnit cu;
         cu.source = u.path;
         cu.packageName = u.packageName;

src/build/prepare.cppm

@@ -725,4 +725,27 @@ prepare_build(bool print_fingerprint, bool includeDevDeps = false,
               std::vector<mcpp::manifest::Target> extraTargets = {},
               BuildOverrides overrides = {});
 
+// The PlanNotes a failed call recorded before the phase that failed it.
+//
+// On success, `prepare_build` copies `PrepareState::planNotes` into
+// `BuildContext::planNotes` (phase13_finish) — but on failure it returns only
+// `r.error()`, a plain string, and the `PrepareState` that held the notes is a
+// local of `prepare_build` and is gone the moment it returns. A note recorded
+// by an earlier phase (`MCPP_BUILD_DATABASE_PROGRAM_FAILED`, say) was
+// therefore lost on every failure of a later phase, not only the one that
+// motivated this (design 2026-09-27 §4.2, mcpp#724 side finding A, fix item
+// 2): under `emit build-database`'s `plan_only`, a member the caller could
+// otherwise describe the ordinary way (R5.2) instead reported nothing but the
+// later phase's own message.
+//
+// Same per-run-sink discipline as `mcpp::build::refusal` (refusal.cppm), and
+// for the same reason: widening `prepare_build`'s return type would touch
+// every caller of `.error()` to carry something only the failure path of one
+// caller (`emit`) reads. Written immediately before prepare_build's own
+// failing return, from the state that failure saw; read by the caller that
+// turns that failure into diagnostics. `take` reads and clears, so neither a
+// later failure of the SAME call nor a later, unrelated call inherits a stale
+// set of notes.
+export std::vector<PlanNote> take_notes_on_failure();
+
 } // namespace mcpp::build

src/build/prepare/driver.cpp

@@ -24,6 +24,22 @@ import mcpp.platform;
 
 namespace mcpp::build {
 
+namespace {
+// `thread_local` for the same reason `mcpp::build::refusal`'s sink is
+// (refusal.cppm): `prepare_build` recurses for nested host sub-builds on the
+// calling thread, and a failure of the INNER call must not leave notes behind
+// for an outer call that goes on to succeed. Cleared at the top of every
+// `prepare_build` call and on its success path, so only a call that is
+// itself failing can leave something here for its caller to take.
+thread_local std::vector<PlanNote> g_notesOnFailure;
+} // namespace
+
+std::vector<PlanNote> take_notes_on_failure() {
+    auto notes = std::move(g_notesOnFailure);
+    g_notesOnFailure.clear();
+    return notes;
+}
+
 std::expected<BuildContext, std::string>
 prepare_build(bool print_fingerprint,
               bool includeDevDeps,
@@ -32,18 +48,29 @@ prepare_build(bool print_fingerprint,
     PrepareState state(print_fingerprint, includeDevDeps,
                         std::move(extraTargets), std::move(overrides));
     pending_flag_words_notes().clear();
+    g_notesOnFailure.clear();
+
+    // Every early return below carries `state.planNotes` as they stood at the
+    // failing phase, so a caller whose only handle on the failure is
+    // `.error()` (a plain string) can still read what an earlier phase
+    // recorded — see `take_notes_on_failure`'s declaration in prepare.cppm.
+    auto fail = [&](std::string message) -> std::unexpected<std::string> {
+        g_notesOnFailure = state.planNotes;
+        return std::unexpected(std::move(message));
+    };
 
-    if (auto r = phase0_manifest_and_workspace(state); !r) return std::unexpected(r.error());
-    if (auto r = phase1_toolchain_spec_and_axes(state); !r) return std::unexpected(r.error());
-    if (auto r = phase2_define_toolchain_resolver(state); !r) return std::unexpected(r.error());
-    if (auto r = phase3_xlings_before_graph(state); !r) return std::unexpected(r.error());
-    if (auto r = phase4a_graph_load(state); !r) return std::unexpected(r.error());
-    if (auto r = phase4b_graph_worklist(state); !r) return std::unexpected(r.error());
-    if (auto r = phase5_toolchain_after_graph(state); !r) return std::unexpected(r.error());
-    if (auto r = phase6_features_and_host_tools(state); !r) return std::unexpected(r.error());
-    if (auto r = phase9_target_side(state); !r) return std::unexpected(r.error());
-    if (auto r = phase11_scan(state); !r) return std::unexpected(r.error());
+    if (auto r = phase0_manifest_and_workspace(state); !r) return fail(r.error());
+    if (auto r = phase1_toolchain_spec_and_axes(state); !r) return fail(r.error());
+    if (auto r = phase2_define_toolchain_resolver(state); !r) return fail(r.error());
+    if (auto r = phase3_xlings_before_graph(state); !r) return fail(r.error());
+    if (auto r = phase4a_graph_load(state); !r) return fail(r.error());
+    if (auto r = phase4b_graph_worklist(state); !r) return fail(r.error());
+    if (auto r = phase5_toolchain_after_graph(state); !r) return fail(r.error());
+    if (auto r = phase6_features_and_host_tools(state); !r) return fail(r.error());
+    if (auto r = phase9_target_side(state); !r) return fail(r.error());
+    if (auto r = phase11_scan(state); !r) return fail(r.error());
 
+    g_notesOnFailure.clear();
     return phase13_finish(state);
 }
 

src/build/prepare/features.cpp

@@ -1768,6 +1768,12 @@ std::expected<void, std::string> phase6_features_and_host_tools(PrepareState& st
                                     pkg.manifest.package.name, r.error()),
                         mcpp::wire::Severity::Error,
                         (pkg.root / "build.mcpp").string()});
+                    // Same reason as the root's mirror of this in
+                    // target_side.cpp: a later check whose premise is this
+                    // program's directives (the device-source check) must be
+                    // able to tell this package apart from one with no program
+                    // at all.
+                    state.programFailedPackages.insert(pkg.root.string());
                     continue;
                 }
                 return std::unexpected(std::format(

src/build/prepare/state.cppm

@@ -462,6 +462,16 @@ struct PrepareState {
     std::vector<std::pair<std::string, std::string>> abiRequiresExceptions;
     std::map<std::string, std::vector<std::string>> capExclusive;
     std::map<std::string, std::vector<std::string>> deviceSourcesByPackage;
+    // Keyed like `deviceSourcesByPackage`, by `pkg.root.string()` (root
+    // package included: `packages[0].root == *root`). Holds a package whose
+    // build program failed IN THIS PASS, under `plan_only` (`emit
+    // build-database`) — the one case a failed program does not already end
+    // the whole call (SPEC-005 R5.2, #699 item 2, E3). A check whose premise
+    // is that program's directives must not run for such a package: with no
+    // directives applied, every premise reads as unmet, which is a symptom of
+    // the recorded `MCPP_BUILD_DATABASE_PROGRAM_FAILED`, not a second defect
+    // (design 2026-09-27 §4.2, mcpp#724 side finding A).
+    std::set<std::string> programFailedPackages;
     std::function<std::optional<std::string>()> checkVersionFloors;
     mcpp::targetside::TargetSide resolvedTargetSide;
     std::optional<std::size_t> cxxLayerProviderIndex;

src/build/prepare/target_side.cpp

@@ -1622,6 +1622,10 @@ std::expected<void, std::string> phase9_target_side(PrepareState& state) {
             state.planNotes.push_back({"MCPP_BUILD_DATABASE_PROGRAM_FAILED",
                 bp.error(), mcpp::wire::Severity::Error,
                 (*state.root / "build.mcpp").string()});
+            // Named so the device-source check below (and anything else whose
+            // premise is this program's directives) can tell a package whose
+            // program failed apart from one that simply has no program.
+            state.programFailedPackages.insert(state.root->string());
         }
         if (bp) {
             // THE SAME RULE THE DEPENDENCIES ARE HELD TO, WITH THE ROOT AS A PARTY.
@@ -1764,8 +1768,18 @@ std::expected<void, std::string> phase9_target_side(PrepareState& state) {
     // condition an action needs anyway -- one that compiles a file it does not
     // declare as an input does not rerun when that file changes -- so a rule
     // that satisfies it is a rule that rebuilds correctly.
+    //
+    // THE PREMISE OF THIS CHECK IS THE BUILD PROGRAM'S DIRECTIVES: an action
+    // consuming a device source is one such directive. A package whose program
+    // failed in this pass (`plan_only`, above) applied none of them, so every
+    // device source would read as an orphan -- not a second defect, only the
+    // shape the first one takes here. Such a package already carries its one
+    // diagnostic, `MCPP_BUILD_DATABASE_PROGRAM_FAILED`; this check does not run
+    // for it, exactly as SPEC-005 R5.2 now states (design 2026-09-27 §4.2,
+    // mcpp#724 side finding A).
     for (std::size_t i = 0; i < state.packages.size(); ++i) {
         auto const& pkg = state.packages[i];
+        if (state.programFailedPackages.contains(pkg.root.string())) continue;
         auto dit = state.deviceSourcesByPackage.find(pkg.root.string());
         if (dit == state.deviceSourcesByPackage.end() || dit->second.empty()) continue;
         auto const& mm = (i == 0) ? *state.m : pkg.manifest;
@@ -1781,6 +1795,9 @@ std::expected<void, std::string> phase9_target_side(PrepareState& state) {
                 orphans += "         " + rel + "\n";
         if (orphans.empty()) continue;
         std::error_code hasEc;
+        // The `programFailedPackages` skip above means this package's program,
+        // if it has one, ran and succeeded — `exists(build.mcpp)` here can no
+        // longer be true of a program that merely started and failed.
         const bool hasProgram = std::filesystem::exists(pkg.root / "build.mcpp", hasEc)
                               || !pkg.manifest.buildConfig.ruleModules.empty();
         refusal::record(refusal::Code::DeviceSourceUnconsumed);

src/build/prepare/xlings.cpp

@@ -429,17 +429,24 @@ std::expected<void, std::string> phase3_xlings_before_graph(PrepareState& state)
                                 penv.workspace.emplace_back(entry.target, entry.pin());
                         }
             }
-            if (state.runtimeSelection.ownerRoot == state.workRoot) {
-                mcpp::config::ensure_project_index_dir(
-                    **cfg2, state.workRoot, state.m->indices, penv);
-            } else {
-                if (!state.m->indices.empty())
-                    mcpp::config::ensure_project_index_dir(
-                        **cfg2, state.workRoot, state.m->indices, {});
-                if (materializeRootRuntime)
-                    mcpp::config::ensure_project_index_dir(
-                        **cfg2, state.runtimeSelection.ownerRoot, {}, penv);
-            }
+            // `state.workRoot` is where THIS invocation writes (SPEC-005
+            // R2.1's cache directory under `emit build-database`'s
+            // `plan_only`, or a host tool's private store under tool
+            // provisioning); `runtimeSelection.ownerRoot` is always the real
+            // project root (`select_runtime`, `runtime_selection.cppm`),
+            // regardless of either. The two used to disagree on where the
+            // runtime-environment half (`penv`: deps/subos/workspace) of
+            // `.mcpp/.xlings.json` belongs whenever they differ: the custom-
+            // indices half already went to `workRoot`, but `penv` went to
+            // `ownerRoot` — the actual project tree — which is exactly what
+            // `emit` must never write into (design 2026-09-27 §4.3, mcpp#724
+            // side finding B). Both halves now go to the one root this
+            // invocation writes everything else to, `workRoot`; when it
+            // equals `ownerRoot` (an ordinary rooted build) that is the same
+            // write the `if` branch always made, so this is one call in
+            // every case, not two.
+            mcpp::config::ensure_project_index_dir(
+                **cfg2, state.workRoot, state.m->indices, penv);
 
             // `[xlings] deps` are DECLARED above and, until now, nothing
             // installed them (mcpp-index #281 §9).

src/cli/cmd_build.cppm

@@ -400,10 +400,28 @@ export int cmd_emit_build_database(const mcpplibs::cmdline::ParsedArgs& parsed)
                                                   includeDevDeps,
                                                   std::move(discovered->targets), mo);
             if (!ctx) {
+                // A wholly-failed member contributes exactly one `error`
+                // diagnostic, `path` its `mcpp.toml` (SPEC-005 R5.2) — that
+                // invariant is kept exactly, so a note an earlier phase
+                // recorded (most importantly
+                // `MCPP_BUILD_DATABASE_PROGRAM_FAILED`) is folded into THIS
+                // diagnostic's own message instead of becoming a diagnostic of
+                // its own. Without it, a later phase's failure that follows
+                // from the missing directives (SPEC-005 R5.2's own words) read
+                // as a single, unexplained symptom, and the actual cause —
+                // recorded, then discarded the moment `prepare_build` returned
+                // — never reached the reader (design 2026-09-27 §4.2, mcpp#724
+                // side finding A, fix item 2).
+                std::string message = member.empty() ? ctx.error()
+                                                     : std::format("{}: {}", member, ctx.error());
+                for (auto const& note : mcpp::build::take_notes_on_failure())
+                    message += note.path.empty()
+                        ? std::format("\n       earlier in this pass, {}: {}",
+                                      note.code, note.message)
+                        : std::format("\n       earlier in this pass, {} ({}): {}",
+                                      note.code, note.path, note.message);
                 diagnostics.push_back({plan_failure_code(), Severity::Error,
-                    member.empty() ? ctx.error()
-                                   : std::format("{}: {}", member, ctx.error()),
-                    memberPath});
+                                       std::move(message), memberPath});
                 failedMemberRoots.push_back(memberRoot);
                 continue;
             }