2026.9.8.1: a package's host modules are ordered by what they import, and the design document aligned with what shipped

[speak-agent]

Two engine defects, and a design document brought back into line with what shipped

No new protocol surface. An earlier draft of this branch added one — mcpp::recompile_if_changed, protocol 9 — and it was withdrawn, because a prototype showed the dependency it existed for is expressible with the graph primitive the engine already has. That account is kept in .agents/docs/… §14.1; what remains here is two real defects and the documentation.

1. A package's host modules were ordered by their paths

The units a host-module package contributes were compiled in the order their paths sorted: the lib root, then everything else out of a std::set<path>. build_program.cppm accumulates module flags as it goes, so each unit sees only the BMIs ahead of it. rules/spirv.cppm sorts before src/declare.cppm, so a member importing a unit its own package shares was compiled first:

failed to read compiled module: No such file or directory
note: imports must be built before being imported

Reproduced in both directions. Renaming the shared unit so its path sorted first made the same package build. So the cause is the sort and nothing else.

What it cost was not a failure but a design decision made against the wrong cause

mcpp:plugins read this as "a second unit is not compiled as a host module at all" and folded everything its members shared into the lib root — twenty lines to about seven hundred. Its design document recorded that as a cost paid, together with the mistaken cause.

The fix

Topological order over declared imports, with path order as the stable tie-break: a package with no internal imports is ordered exactly as it is today, so this can only change builds that were already broken.

A cycle is left to the compiler on purpose — it is ill-formed C++, the compiler names both units, and refusing here would report the same fact in a worse place.

declared_imports sits beside declared_interface_name and matches its discipline: line-based, comment-aware, deliberately shallow. It answers "which units of THIS package must precede this one"; every other name is discarded by the caller. It is not a module scanner.

Criterion

tests/e2e/633, two legs:

1. A fully reversed chain — three units whose import order is the exact reverse of their path order. Under a path sort each one precedes what it imports; under an import sort each one follows it. Nothing but the ordering decides whether it builds. The criterion is a value the three modules compute together, surfaced through mcpp::warning — the one build-program channel mcpp build prints on success.
2. The unconstrained case must keep path order. Not decoration: a topological sort that ignored the original order is free to emit any valid order, and a package that works today would be silently reordered.

Reverting the fix to a path sort turns leg 1 red, as it should.

2. device_extensions and rule_module were read, then reported as unsupported

Both are parsed about forty lines above the check that rejects them, stored in featureDeviceExtensions / featureRuleModule, and read by prepare when a consumer activates the feature — they are the whole basis for "a new device language costs no engine release". They were simply missing from kKnownFeatureKeys:

[features].rules-spirv has unsupported key 'rule_module' (ignored).
Supported keys: defines, flags, forward, implies, provides, requires, sources.

Worse than a wrong message: it advises a package author to delete the two lines that make their rule work.

It went unnoticed because the host-module path a rule package is normally loaded through does not print schema warnings; an ordinary build of the same package does. A rule package that produces a binary for tools = [...] makes ordinary builds of rule packages routine, which is how this surfaced.

The design document, aligned

.agents/docs/2026-09-07-module-first-heterogeneous-surface.md had become four documents under one heading — a design argued against base commits that predate the release, a plan, an implementation record, and an open-items register — and the first of those still described a syntax that was designed and withdrawn. Someone who opens it to understand this design is misinformed by section 5 before reaching section 13, which says the opposite.

Fourteen in-place corrections, in three kinds:

Kind	Where	What shipped instead
A withdrawn syntax	§5.2, §5.5, §6, §8.D	options::module_name, options::surface, default_surface() reading MCPP_LANGUAGE_MODULES — never [rules], which grep '"rules"' modules/manifest/src/toml.cppm confirms does not exist
A mechanism that shipped in another shape	§4.1, §4.3	§4.1's host-tool binary was not built (it is, in plugins 0.4.0); §4.3's "shares its fix" is refuted by measurement
Items listed open that had closed	§1, §3.5, §7, §12	annotated one by one

Nothing is deleted: an argument's rejection is part of its record, and so is the shape a design took on contact with reality. A status is stated once — "which rules pass a depfile" lives in §14.2 and nowhere else, because three copies are three places to forget when it changes.

§14 is the only register of what is open. §14.1 and §14.2 are now CLOSED with their analysis kept; §14.7 and §14.8 are new; §13.2.1 records this batch's cross-repository waves.

The two transferable findings in §14.1

A requirement folded into another item's fix disappears when that item ships. §4.3 wrote the requirement down before any code existed, then added five words pointing at the depfile item. The depfile shipped, the item was marked done, and .incbin went with it — silently, with every test green, because the test written for the other item passed.

The first measurement asked the wrong tool. -MD on a compiler driver is a preprocessor channel, and .incbin is not an include, so a very convincing "no" described a channel that was never a candidate. The assembler has its own, and the two disagree: GNU as names the embedded file in --MD; clang's integrated assembler has no dependency output of any kind. Taking the assembler's word would have left the dependency tracked under GCC and silently absent under Clang — worse than absent under both.

Ecosystem

mcpp:plugins 0.4.0 depends on the ordering fix: it splits the surface into a pure generator (importing only std, so the same code compiles into mcpp-embed) and a build-program half in src/declare.cppm, which the members import. Its CI downloads a released mcpp, so the order is not interchangeable — this merges and releases first.

Local: the full e2e suite and the unit suite green; the plugins branch verified against a locally built engine, including a control leg that goes red when the mechanism is removed.