fix(build): a package's generated inputs come before its compiles; an empty link is refused (2026.8.30.1)

Three defects, one change of mind about evidence. Each of them was a place
where something answered "is this ready?" from a proxy instead of from the
artifact.

── mcpp#534: `role = "source"` did not order a generated header ─────────────

The engine's own comment claimed ordering needed no special handling because
"a Source action's outputs ARE the compile edge's inputs". That is true of a
generated `.cpp` and false of a generated `.h`: a header is reached through
`-I`, never appears as an edge input, and the depfile that would record it does
not exist until a compile has already succeeded.

So an action whose outputs were all headers had a node in build.ninja that
nothing could reach — not `default` (Source outputs are excluded on purpose),
not the goal phony (objects and link outputs only), and no consuming edge. It
never ran. The issue was filed as an intermittent race; it is deterministic,
and five consecutive builds reproduce it identically. What made it look like a
race is that `prepare_actions` wrote a zero-byte placeholder for every declared
Source output, headers included — so the file was on disk whether or not the
generator had run.

  * `BuildAction` records the package that declared it, spelled the same way
    `CompileUnit::packageName` is (`qualified_package_name`, now exported so
    the two cannot drift).
  * Each package that declares a gating action gets one phony over its outputs,
    and every compile edge of that package takes it as an order-only
    prerequisite. Per package, not per build: `include_dir` colours only the
    declaring package's own TUs, and a build-wide edge would express a
    dependency that does not exist while landing on the critical path.
  * `check_action_ordering` scans the emitted manifest and fails the build if
    any such edge is missing one — including the denominator, because "every
    edge that should carry it does" is vacuously true when none does, which was
    exactly the previous state. Seven call sites append the string today; being
    careful at seven sites is not a mechanism.
  * `blocking` on a `check` now does what it has been documented to do since it
    was introduced. It was typed, emitted over the build-program protocol,
    parsed, documented in two languages and demonstrated in a shipped example —
    and read by nothing.
  * Placeholders are no longer written for outputs that are not translation
    units. The scan never reads a header, and the empty file only ever turned
    "the generator did not run" into "the header is empty".

── mcpp#533: an empty link unit, reported as a shell error ──────────────────

A dependency whose `install()` was skipped over a package-identity collision
left a version directory with no sources. mcpp planned its shared library
anyway and the user was shown `/bin/sh: 1: -shared: not found`.

  * A link unit with no inputs is refused at plan time, naming the target. The
    static case is why this is an error rather than a better linker message:
    `ar rcs` with no members exits 0 and writes an 8-byte archive, so the build
    REPORTED SUCCESS and every consumer failed later with undefined symbols.
  * `cc` is emitted unconditionally, for the reason `c_ldflags` twenty-six
    lines below already carried (mcpp#426). The rule had been written down for
    one variable of `c_link`/`c_shared` and not for the other.
  * `check_rule_commands_name_a_program` scans the manifest for the class: a
    rule's command must begin with a program. Deliberately not the more obvious
    "no undefined variables" — ninja's empty expansion is a feature several
    rules rely on (`$soname_flag`, `$unit_ldflags`), and that check would have
    needed an allowlist of exceptions.
  * `.mcpp_ok` is no longer written from the installer's exit code plus the
    existence of a directory the installer creates before doing any work. It
    now requires one entry that neither mcpp nor xlings wrote. Withheld rather
    than fatal, because a package may legitimately install no payload.
  * The same predicate runs on the fast path, so a store already poisoned by
    this bug heals on the next build instead of requiring the user to know
    which directory to delete.
  * The lib-root warning asked `has_lib_target` — "does this produce a library"
    — when the property it wants is "is this a C++ module library". A
    source-built C package warned that `src/<name>.cppm` was missing in every
    consumer's build.

── Tests ───────────────────────────────────────────────────────────────────

e2e 314 (a dependency generating its only header), 315 (blocking gates the
compile, non-blocking does not), 316 (empty shared AND static targets refused;
a populated one still builds). All three were run against the pre-fix binary
and all three fail there, so they discriminate rather than describe.

Unit: 14 new cases over the two emitter guards, the ordering denominator, and
the install-marker evidence — including the poisoned-store heal.

Analysis and cross-repo plan: .agents/docs/2026-08-30-*.md

Refs #533, #534

Author: speak-agent

.agents/docs/2026-08-30-cross-repo-fix-plan-532-533-534.md

@@ -311,14 +311,27 @@ attach:
 
 | `role` | Outputs | Ordering | Typical |
 |---|---|---|---|
-| `source` | join the compile set | the compile edge consumes them | protoc, a transpiler |
-| `check` | a stamp file, written by mcpp | runs **alongside** compilation (set `blocking = true` to gate it) | clang-tidy, a format or ABI check |
+| `source` | compilable ones join the compile set; the rest are produced but not compiled | **every compile edge of the declaring package waits for them** | protoc, a transpiler, a protocol/IDL generator |
+| `check` | a stamp file, written by mcpp | runs **alongside** compilation; `blocking = true` makes the package's compile edges wait for it | clang-tidy, a format or ABI check |
 | `object` | join the **link** set | the link edge consumes them | a resource compiler, `objcopy` embedding a blob, a generated `.def`, a pre-built `.o` |
 | `artifact` | a new file | its *inputs* are link outputs, so it runs after the link | codesign, packaging, size budgets |
 
-No phase machinery is involved: ninja's own file dependencies do the
-sequencing, which is also why an `artifact` action cannot double-apply itself
-the way a naive "post-build hook" would.
+No phase machinery is involved. `object` and `artifact` are sequenced by
+ninja's own file dependencies — which is also why an `artifact` action cannot
+double-apply itself the way a naive "post-build hook" would. `source` and a
+blocking `check` are sequenced by an order-only edge from the declaring
+package's compile edges to that package's action outputs.
+
+> **Why `source` needs the edge (mcpp 2026.8.30.2+).** A generated `.cpp`
+> becomes an input of the edge that compiles it, so it was ordered for free. A
+> generated **header** never does: it is reached through `-I`, and the depfile
+> that would record it does not exist until a compile has already succeeded.
+> Before this, an action whose outputs were all headers had a node in
+> `build.ninja` that nothing could reach — not `default`, not the goal set, no
+> consuming edge — so it never ran, and what the compiler read was the empty
+> placeholder mcpp writes for a declared output. The ordering is **per
+> package**, because `include_dir` colours only the declaring package's own
+> translation units.
 
 **A check's command does not have to write its stamp** (mcpp 2026.8.29.1+).
 The verdict is the exit code; the stamp is bookkeeping the graph needs, and

.agents/docs/2026-08-30-issues-532-533-534-analysis.md

@@ -277,13 +277,22 @@ int main() {
 
 | `role` | 输出 | 顺序 | 典型 |
 |---|---|---|---|
-| `source` | 进编译集 | 编译边消费它们 | protoc、转译器 |
-| `check` | 一个 stamp 文件,由 mcpp 写入 | **与编译并行**(`blocking = true` 才前置) | clang-tidy、格式/ABI 检查 |
+| `source` | 可编译的进编译集,其余只产出、不编译 | **声明它的那个包的每条编译边都等它** | protoc、转译器、协议/IDL 生成器 |
+| `check` | 一个 stamp 文件,由 mcpp 写入 | 与编译并行;`blocking = true` 让该包的编译边等它 | clang-tidy、格式/ABI 检查 |
 | `object` | 进**链接**集 | 链接边消费它们 | 资源编译器、`objcopy` 嵌 blob、生成的 `.def`、预编译 `.o` |
 | `artifact` | 一个新文件 | 它的**输入**是链接产物,所以在链接之后跑 | 签名、打包、size budget |
 
-全程不涉及任何 phase 机制:顺序由 ninja 自己的文件依赖决定 —— 这也是为什么
-`artifact` 不会像朴素的「post 构建钩子」那样把自己重复施加一遍。
+全程不涉及任何 phase 机制。`object` 与 `artifact` 由 ninja 自己的文件依赖定序 ——
+这也是为什么 `artifact` 不会像朴素的「post 构建钩子」那样把自己重复施加一遍。
+`source` 与 blocking 的 `check` 则由一条 order-only 边定序:从声明它的那个包的
+编译边,指向该包的 action 产物。
+
+> **`source` 为什么需要这条边(mcpp 2026.8.30.2+)。** 生成的 `.cpp` 会成为编译它
+> 那条边的输入,所以顺序是白得的。生成的**头文件**永远不会:它是通过 `-I` 找到的,
+> 而能记录它的 depfile 要等到某次编译成功之后才存在。在此之前,一个产物全是头文件的
+> action 在 `build.ninja` 里有节点却无人可达 —— 不在 `default`、不在 goal 集、没有
+> 任何边消费它 —— 于是它从不执行,而编译器读到的是 mcpp 为已声明产物写下的那个空占位
+> 文件。这条边**按包**划分,因为 `include_dir` 只染色声明它的那个包自己的 TU。
 
 **check 的命令不必自己写 stamp**(mcpp 2026.8.29.1+)。判定是退出码,stamp 是**构建图**
 需要的记账;命令成功时由 mcpp 创建它。在此之前每个 check 都需要一个包装脚本去 touch

docs/07-build-mcpp.md

@@ -1,6 +1,6 @@
 [package]
 name        = "mcpp"
-version = "2026.8.29.1"
+version = "2026.8.30.1"
 description = "Modern C++ build & package management tool"
 license     = "Apache-2.0"
 authors     = ["mcpp-community"]

docs/zh/07-build-mcpp.md

@@ -387,8 +387,17 @@ std::string action_error(const Directives& d);
 // Never truncates an existing file: after the first build the real content is
 // there, and rewriting it would make ninja think the input changed on every
 // prepare.
+//
+// ⚠️ ONLY FOR OUTPUTS THAT ARE TRANSLATION UNITS, which is why this needs the
+// table. A placeholder exists so the SCAN has something to read, and the scan
+// never reads a header — but writing one anyway turned "the generator did not
+// run" into "the header is empty", and mcpp#534 was diagnosed as a race for
+// exactly that reason: the file was on disk, so the action looked like it had
+// run. A missing file is the honest report, and after the ordering fix the
+// generator runs before anything reads it either way.
 void prepare_actions(std::vector<mcpp::manifest::BuildAction>& actions,
-                     const std::filesystem::path& pkgRoot);
+                     const std::filesystem::path& pkgRoot,
+                     const mcpp::ExtensionTable& extensions);
 
 // Does this action output belong in the COMPILE set?
 //
@@ -773,7 +782,8 @@ bool is_compilable_output(const fs::path& p, const mcpp::ExtensionTable& t) {
 }
 
 void prepare_actions(std::vector<mcpp::manifest::BuildAction>& actions,
-                     const fs::path& pkgRoot) {
+                     const fs::path& pkgRoot,
+                     const mcpp::ExtensionTable& extensions) {
     for (auto& a : actions) {
         auto absolutize = [&](std::vector<std::string>& v) {
             for (auto& p : v) {
@@ -788,6 +798,11 @@ void prepare_actions(std::vector<mcpp::manifest::BuildAction>& actions,
         if (a.role != mcpp::manifest::BuildAction::Role::Source) continue;
         for (auto const& o : a.outputs) {
             if (o.find("${mcpp.") != std::string::npos) continue;
+            // A placeholder exists so the scan has a translation unit to read.
+            // A header is not one — nothing scans it, and the empty file it
+            // used to leave behind is what made a generator that never ran
+            // look like one that had (mcpp#534).
+            if (!is_compilable_output(o, extensions)) continue;
             std::error_code ec;
             fs::path p(o);
             if (fs::exists(p, ec)) continue;      // real content already there

mcpp.toml

@@ -300,6 +300,18 @@ struct BuildAction {
     enum class Role { Source, Check, Object, Artifact };
 
     std::string                        id;        // diagnostics + edge naming
+    // Which package's `build.mcpp` declared this. Filled by the engine when
+    // actions are collected into the plan, NOT by the build program — the
+    // program does not know, and the engine already does.
+    //
+    // Load-bearing, not bookkeeping: the ordering edge an action needs is
+    // scoped to the declaring package, because `include_dir` colours only that
+    // package's own translation units. A build-wide ordering would express a
+    // dependency that does not exist and put it on the critical path of a
+    // build whose wall clock is dominated by one. Spelled the same way
+    // `CompileUnit::packageName` is (`qualified_package_name`), because the
+    // two are matched against each other.
+    std::string                        packageName;
     Role                               role = Role::Source;
     std::vector<std::string>           inputs;    // absolute or package-relative
     std::vector<std::string>           outputs;   // ditto; declared, see INV-D

modules/buildmcpp/src/directives.cppm

@@ -31,6 +31,6 @@ import std;
 
 export namespace mcpp {
 
-inline constexpr std::string_view MCPP_VERSION = "2026.8.29.1";
+inline constexpr std::string_view MCPP_VERSION = "2026.8.30.1";
 
 } // namespace mcpp