refactor(modules): nine subsystems, and the build.mcpp contract among them

The unit under `modules/` is a SUBSYSTEM, not a file. One file per package
would turn a directory listing into nine manifests and call it architecture.

  libs             json + toml -- text-format parsers, vendored and in-house
  log              leveled diagnostics
  versioning       mcpp.version + mcpp.version_req
  source-kind      the source-file role table
  dyndep           ninja dyndep emission
  platform         the OS abstraction: fs, process, axis, shell, terminal
  manifest         mcpp.toml and the xpkg descriptor, plus the vocabulary they
                   are written in
  toolchain-model  what a toolchain IS -- triple, model, dialect, cppfly,
                   fingerprint, linkmodel
  buildmcpp        the build.mcpp CONTRACT -- program_protocol, directives,
                   provisions, tool_store

Dependencies between them are declared and enforced rather than assumed, so
`mcpp test -p <member>` builds each one ALONE and a subsystem relying on
something it does not declare fails there while compiling fine in the root.

## Three cuts, one mistake

Every group-level cycle was produced by a countable set of back-edges, and each
one was a module named for where it sat rather than for what it did.

`src/platform/xlings/` was never platform: it is the xlings integration, which
by its nature knows about packages, indexes and manifests. Its modules were
named `mcpp.platform.xlings` while their namespace already said
`mcpp::xlings`; both now agree, in `src/xlings/`.

`runtime_binding.cppm` imported the whole of `mcpp.config` to read ONE path out
of it, which put the OS layer above configuration, xlings and the package
manager. The caller passes the path; the file describes the xlings runtime
contract rather than the OS, so it moved to `src/runtime/` with its only
dependent.

`toolchain.fingerprint` imported `toolchain.detect` for a type -- `Toolchain`
-- that `toolchain.model` defines and `detect` merely re-exports. The import
named a CONSUMER of the type rather than its provider and dragged toolchain
detection behind it. That one is load-bearing: every module on the
build-program side needs `fingerprint` for `hash_file`, so while that edge
pointed at `detect` the whole build.mcpp contract sat transitively above the
package manager. One import line was the entire distance.

## What stays in src/, and why it is not a defect

`build_program.cppm` and `hostprogram.cppm` -- the half that compiles and runs
the program -- need `toolchain.registry` and `toolchain.stdmod`, which reach
into detection, the compiler families and xlings. A thing that compiles and
runs a program is a toolchain consumer by construction; moving it would
relocate the dependency rather than remove it.

## Tests at two altitudes

Each package carries its own tests, and the root keeps a suite that crosses
layers. A subsystem test going red means the contract changed; the root's
cross-check going red means the contract held and a consumer drifted.

`tests/unit/test_subsystem_contracts.cpp` is the new one: it asserts that the
protocol number the bundled module announces is SUBSTITUTED rather than spelled
(so the announced value cannot drift from the checked one), and that the
compiled binary's version equals the root manifest's.

⚠️ `mcpp test -p <member>` exits 0 for a member with no tests, so CI's loop is
green either way and "has no tests" reads exactly like "tests pass".
`check_modules_wiring.sh` prints which members have none, and does not fail on
them.

`versioning` is not called `version`: that word is a reserved key inside a
dependency specification, so `[dependencies.mcpp] version = { path = … }`
parses as the mcpp dependency's version field and fails with an error about the
wrong table.

Author: speak-agent

.agents/docs/2026-08-29-build-rule-package-spec.md

@@ -567,6 +567,39 @@ before, once for the directive cache and once for the advisory channel.
    limit. The question is which objects join the build program's link, and it
    has to be answered before a rule can depend on an ordinary library.
 
+4. **`role = "check"` cannot be written portably, and this is the finding the
+   second rule produced.** Section 4 predicted that writing the next rule
+   without consulting the guidance is what would expose the gaps; attempting a
+   `clangtidy` package is what found this one.
+
+   A check's output is a stamp and **the command has to create it**. Analysers
+   do not: clang-tidy's verdict is its exit code, and it writes no file on
+   success. So a check action needs a wrapper — and an action's `command` is an
+   argv with no shell assumed, which is correct for Windows and is exactly what
+   makes the wrapper unwritable there. `tests/e2e/188` and
+   `examples/08-build-rules` both reach for `sh`, and both are therefore POSIX
+   only.
+
+   The consequence is that the role with no ecosystem consumer also has no
+   portable way to acquire one, and that is not a coincidence.
+
+   The stamp is bookkeeping the graph needs, not something an author should
+   have to produce — the contract of a check is already "the exit code is the
+   verdict". Two shapes worth weighing:
+
+   - **mcpp creates the stamp when a check command exits zero** and its
+     declared output does not exist. Backward compatible, since a command that
+     already writes the stamp keeps working, and it needs no new process. It
+     does mean ninja's output is written by something other than the edge's own
+     command.
+   - **mcpp wraps the command** (`mcpp __check --stamp <p> -- <argv…>`). One
+     extra process per check, and the engine is already on disk on every
+     platform, so it is portable by construction.
+
+   Neither is implemented. Until one is, a check rule should say in its own
+   documentation that it requires a POSIX shell, rather than appearing to be
+   portable and failing on a Windows consumer's first build.
+
 ---
 
 ## 9a. The work, and what depends on what
@@ -926,20 +959,35 @@ manifest removes all eight edges at once.
 
 ### 12.3 The layering that falls out of the measurement
 
+**The unit is a SUBSYSTEM, not a file.** A package under `modules/` is a group
+of modules that answer one question and are used together; one file per package
+would turn a directory listing into nine manifests and call it architecture.
+
 ```
-modules/     independent packages, each with its own mcpp.toml, used by path
-  M0   log, version, version_req, source_kind, dyndep, libs(json)
-         6 modules, zero mcpp imports; extractable with no edge cut at all
-  M1   platform, minus platform/xlings/
-         20 files, 4,852 lines; one edge to cut
-  M2   vocabulary: dep_spec, index_spec, compat, dependency_selector
-         ~680 lines; removes manifest's dependency on pm
-  M3   manifest
-         4 files, 5,560 lines
-src/         mcpp itself, including main.cpp and the binary target;
-             everything not yet separated, and shrinking it is the direction
+modules/          independent packages, each with its own mcpp.toml, used by path
+  libs            json + toml — text-format parsers, vendored and in-house
+  log             leveled diagnostics
+  versioning      mcpp.version + mcpp.version_req
+  source-kind     the source-file role table
+  dyndep          ninja dyndep emission
+  platform        the OS abstraction: fs, process, axis, shell, terminal
+  manifest        mcpp.toml and the xpkg descriptor, plus the vocabulary they
+                  are written in (dep_spec, dependency_selector, index_spec,
+                  compat, glob, mangle, targetside)
+  toolchain-model what a toolchain IS — triple, model, dialect, cppfly,
+                  fingerprint, linkmodel
+  buildmcpp       the build.mcpp CONTRACT — program_protocol, directives,
+                  provisions, tool_store
+src/              the build tool's skeleton: prepare, plan, execute, the
+                  toolchain families and detection, pm, pack, cli, xlings,
+                  runtime — and shrinking it is the direction
 ```
 
+Dependencies between them are declared and enforced, not assumed:
+`toolchain-model` → `platform`, `versioning`; `manifest` → `libs`, `platform`,
+`source-kind`, `versioning`; `buildmcpp` → `libs`, `manifest`, `source-kind`,
+`toolchain-model`. `platform` and the five below it declare nothing at all.
+
 **Two directories, not three.** xlings additionally separates `apps/` from
 `modules/`, and that separation earns its place there because xlings produces
 two binaries — `xlings` and `xlings-gui` — so "what becomes a binary" is a
@@ -1024,7 +1072,53 @@ from the release, so the pinned version must already understand workspaces plus
 path dependencies. xlings demonstrates the feature works; the pin is the thing
 to check, not the feature.
 
-**Order.** M0 first: six modules, zero edges to cut, and it exercises the whole
-mechanism — workspace member, path dependency, bootstrap, cache, CI — against
-the smallest possible blast radius. If M0 measures badly, nothing further should
-proceed.
+**Order.** The leaves first: six packages with no edges to cut, exercising the
+whole mechanism — workspace member, path dependency, bootstrap, cache, CI —
+against the smallest possible blast radius, before anything with a cut in it.
+
+### 12.7 Where the boundary actually fell, and why
+
+Three edges had to be cut, and each was the same mistake wearing different
+clothes: a module named for where it sat rather than for what it did.
+
+| Cut | What it was |
+|---|---|
+| `src/platform/xlings/` → `src/xlings/` | Not platform. The xlings integration, which by its nature knows about packages, indexes and manifests. Its module names said `mcpp.platform.xlings` while its namespace already said `mcpp::xlings`; the rename made the two agree. |
+| `runtime_binding.cppm` → `src/runtime/` | Imported the whole of `mcpp.config` to read **one** path out of it, which put the OS layer above configuration, xlings and the package manager. The caller passes the path now. |
+| `fingerprint → toolchain.detect` | The type it needed, `Toolchain`, is defined in `mcpp.toolchain.model`; `detect` merely re-exports it. The import named a **consumer** of the type rather than its provider, and dragged toolchain detection behind it. |
+
+That third one is the load-bearing one. Every module on the build-program side
+needs `fingerprint` for `hash_file`, so while that edge pointed at `detect` the
+entire build.mcpp contract sat transitively above the package manager and could
+not be separated from it. One import line was the whole distance.
+
+**What stays in `src/`, and why it is not a defect.** `build_program.cppm` and
+`hostprogram.cppm` — the half that compiles and runs the program — need
+`toolchain.registry` and `toolchain.stdmod`, which reach into detection, the
+compiler families and xlings. A thing that compiles and runs a program is a
+toolchain consumer by construction. Moving it would relocate the dependency
+rather than remove it, and the boundary between the contract and its executor
+is the honest place to stop.
+
+### 12.8 Tests at two altitudes
+
+Each package under `modules/` carries its own tests, and the root keeps a suite
+that crosses layers. The pair produces two distinguishable failures:
+
+| Red | Meaning |
+|---|---|
+| the subsystem's own test | the contract changed |
+| the root's cross-check | the contract held and a consumer drifted |
+| both | the change was made once and propagated — the normal case |
+
+The subsystem tests are also built in a configuration the root suite never
+produces: the package **alone**, with only its declared dependencies present. A
+subsystem that has quietly come to rely on something it does not declare
+compiles in the root build and fails there, which is the reason to run both
+rather than pick one.
+
+⚠️ `mcpp test -p <member>` exits 0 for a member with no tests, so the CI loop is
+green either way and "has no tests" reads exactly like "tests pass".
+`check_modules_wiring.sh` therefore prints which members have none. It does not
+fail on them: a package of vendored parsers legitimately has nothing of its own
+to state.

.github/actions/bootstrap-mcpp/action.yml

@@ -13,7 +13,7 @@ inputs:
   xlings-version:
     description: xlings release to bootstrap from
     required: false
-    # Must equal `pinned::kXlingsVersion` in src/platform/xlings/xlings.cppm — enforced by
+    # Must equal `pinned::kXlingsVersion` in src/xlings/xlings.cppm — enforced by
     # .github/tools/check_version_pins.sh, not by this comment. (The previous
     # comment here listed the files to keep in lock-step, and that list was
     # already incomplete; that is why the check exists.)

.github/tools/check_modules_wiring.sh

@@ -31,6 +31,7 @@ set -uo pipefail
 cd "$(dirname "$0")/../.."
 
 fail=0
+untested=()
 bad() { echo "FAIL: $*" >&2; fail=1; }
 note() { echo "  $*"; }
 
@@ -71,8 +72,31 @@ for d in "${dirs[@]}"; do
     # (4) the two package-manager-less builds
     [[ -d "$d/src" ]] \
         || bad "$d has no src/ — the xmake source lists glob modules/*/src/**.cppm and would silently miss it"
+
+    # (5) tests, REPORTED rather than required.
+    #
+    # `mcpp test -p <member>` exits 0 for a member with no tests, so CI's
+    # per-subsystem loop is green either way and "has no tests" is
+    # indistinguishable from "tests pass" in its output. Naming them here is
+    # what makes the difference visible; failing would be wrong, because a
+    # package of vendored parsers legitimately has nothing of its own to state.
+    n=0
+    [[ -d "$d/tests" ]] && n=$(find "$d/tests" -name '*.cpp' | wc -l)
+    if (( n == 0 )); then
+        untested+=("$name")
+    else
+        note "$name: $n subsystem test file(s)"
+        grep -q '^\[dev-dependencies' "$d/mcpp.toml" \
+            || bad "$d has tests but declares no [dev-dependencies] — they cannot link a framework"
+    fi
 done
 
+if (( ${#untested[@]} )); then
+    echo
+    echo "  no subsystem tests (allowed, and reported so it is not read as a pass):"
+    printf '    %s\n' "${untested[@]}"
+fi
+
 # The two xmake source lists must actually carry the glob. Asserted by content
 # rather than by trusting the loop above: a renamed pattern would leave every
 # per-module check passing while compiling nothing.
@@ -87,11 +111,11 @@ done
 # appears in three places and has already moved once.
 for f in scripts/bootstrap-macos.sh .github/workflows/bootstrap-macos.yml \
          bench/projects/mcpp/xmake.lua; do
-    grep -qF 'modules/json/src/json' "$f" \
-        || bad "$f does not add the json include dir (modules/json/src/json)"
+    grep -qF 'modules/libs/src/json' "$f" \
+        || bad "$f does not add the json include dir (modules/libs/src/json)"
 done
-[[ -f modules/json/src/json/json.hpp ]] \
-    || bad "modules/json/src/json/json.hpp is missing, but three files name that path"
+[[ -f modules/libs/src/json/json.hpp ]] \
+    || bad "modules/libs/src/json/json.hpp is missing, but three files name that path"
 
 if (( fail )); then
     echo

.github/tools/check_version_pins.sh

@@ -5,13 +5,13 @@
 # Two invariants that used to live only in a comment:
 #
 #   1. Every xlings version pinned anywhere in .github/ equals
-#      `pinned::kXlingsVersion` in src/platform/xlings/xlings.cppm — which is the version
+#      `pinned::kXlingsVersion` in src/xlings/xlings.cppm — which is the version
 #      `mcpp self env` reports and the one release.yml bundles into the
 #      tarball as <install>/registry/bin/xlings.
 #
 #   2. mcpp's own version is identical in all four places that carry it.
 #
-# Why this exists: src/platform/xlings/xlings.cppm used to say "keep in lock-step with the
+# Why this exists: src/xlings/xlings.cppm used to say "keep in lock-step with the
 # XLINGS_VERSION pins in release.yml / cross-build-test.yml / ci-linux-e2e.yml"
 # and that list was ALREADY incomplete — it omitted both composite actions,
 # which sat on 0.4.30 while everything else moved to 0.4.69. CI's sandbox
@@ -38,12 +38,12 @@ strip_comments() { sed 's/#.*//'; }
 
 # ── 1. xlings pins ────────────────────────────────────────────────────────
 
-XLINGS_EXPECTED=$(grep -oE 'kXlingsVersion[[:space:]]*=[[:space:]]*"[^"]+"' src/platform/xlings/xlings.cppm \
+XLINGS_EXPECTED=$(grep -oE 'kXlingsVersion[[:space:]]*=[[:space:]]*"[^"]+"' src/xlings/xlings.cppm \
                   | grep -oE '"[^"]+"' | tr -d '"' | head -1)
 [ -n "$XLINGS_EXPECTED" ] || {
-  echo "FAIL: could not read kXlingsVersion from src/platform/xlings/xlings.cppm" >&2; exit 1; }
+  echo "FAIL: could not read kXlingsVersion from src/xlings/xlings.cppm" >&2; exit 1; }
 
-note "expected xlings pin: $XLINGS_EXPECTED  (src/platform/xlings/xlings.cppm)"
+note "expected xlings pin: $XLINGS_EXPECTED  (src/xlings/xlings.cppm)"
 
 # Anchored patterns only — a bare "version-looking number on a line mentioning
 # xlings" would also match `xlings install llvm@20.1.7`, which pins LLVM, not
@@ -100,13 +100,13 @@ done < <(find .github -type f \( -name '*.yml' -o -name '*.yaml' -o -name '*.sh'
 # ── 2. mcpp's own version ─────────────────────────────────────────────────
 
 v_toml=$(awk -F '"' '/^version[[:space:]]*=/{print $2; exit}' mcpp.toml)
-v_src=$(grep -oE 'MCPP_VERSION[[:space:]]*=[[:space:]]*"[^"]+"' src/version.cppm \
+v_src=$(grep -oE 'MCPP_VERSION[[:space:]]*=[[:space:]]*"[^"]+"' modules/versioning/src/version.cppm \
         | grep -oE '"[^"]+"' | tr -d '"' | head -1)
 v_xl=$(grep -oE '"mcpp"[[:space:]]*:[[:space:]]*"[^"]+"' .xlings.json \
        | grep -oE '"[^"]+"$' | tr -d '"' | head -1)
-note "mcpp version: building=$v_toml (src/version.cppm=$v_src)  bootstrap pin=$v_xl"
+note "mcpp version: building=$v_toml (modules/versioning/src/version.cppm=$v_src)  bootstrap pin=$v_xl"
 
-for n in "mcpp.toml:$v_toml" "src/version.cppm:$v_src" \
+for n in "mcpp.toml:$v_toml" "modules/versioning/src/version.cppm:$v_src" \
          ".xlings.json:$v_xl"; do
   [ -n "${n##*:}" ] || bad "${n%:*} — could not read the mcpp version"
 done
@@ -131,7 +131,7 @@ fi
 #     same number by definition — release.yml derives the tag from the former
 #     and the smoke test greps the latter out of `mcpp --version`.
 [ -z "$v_src" ] || [ "$v_src" = "$v_toml" ] \
-  || bad "src/version.cppm has '$v_src' but mcpp.toml has '$v_toml'"
+  || bad "modules/versioning/src/version.cppm has '$v_src' but mcpp.toml has '$v_toml'"
 
 # (b) The version BOOTSTRAPPED FROM (.xlings.json) names a mcpp that is already
 #     published, and is NOT required to equal the version being built. It

.github/workflows/bootstrap-macos.yml

@@ -78,7 +78,7 @@ jobs:
               -- directly.
               add_files("modules/*/src/**.cppm")
               add_packages("cmdline")
-              add_includedirs("modules/json/src/json")
+              add_includedirs("modules/libs/src/json")
               set_policy("build.c++.modules", true)
               -- Static link libc++ for minimal runtime dependencies
               add_ldflags("-static-libstdc++", {force = true})

.github/workflows/ci-aarch64-fresh-install.yml

@@ -20,7 +20,7 @@ on:
     branches: [ main ]
     paths:
       - 'src/build/build_program.cppm'
-      - 'src/platform/process.cppm'
+      - 'modules/platform/src/process.cppm'
       - 'tests/e2e/168_build_mcpp_musl_host_static.sh'
       - '.github/workflows/ci-aarch64-fresh-install.yml'
   push:

.github/workflows/ci-linux.yml

@@ -108,9 +108,32 @@ jobs:
         run: |
           # Use freshly-built mcpp for test (it has --mirror support)
           MCPP_FRESH=$(realpath "$(find target -type f -name mcpp -printf '%T@ %p\n' | sort -rn | head -1 | cut -d' ' -f2)")
+          echo "MCPP_FRESH=$MCPP_FRESH" >> "$GITHUB_ENV"
           "$MCPP_FRESH" self config --mirror GLOBAL
           "$MCPP_FRESH" test
 
+      # Each package under `modules/` carries its own tests, and they are built
+      # as that package ALONE -- a configuration the root suite never produces,
+      # since there every module is linked together. A subsystem that has
+      # quietly come to depend on something it does not declare compiles in the
+      # root build and fails here, which is the whole reason to run both.
+      #
+      # Every member is run, and the loop is derived from the manifest rather
+      # than written out: a list maintained by hand is a list that stops
+      # matching, and `check_modules_wiring.sh` cannot see this file.
+      - name: Per-subsystem tests (`mcpp test -p <member>`)
+        run: |
+          set -euo pipefail
+          members=$(sed -n '/^\[workspace\]/,/^\[/p' mcpp.toml \
+                    | grep -oE '"modules/[a-z0-9-]+"' | tr -d '"' | sed 's|modules/||')
+          [ -n "$members" ] || { echo "no workspace members found in mcpp.toml"; exit 1; }
+          echo "members: $(echo $members | tr '\n' ' ')"
+          for m in $members; do
+            echo "::group::mcpp test -p $m"
+            "$MCPP_FRESH" test -p "$m"
+            echo "::endgroup::"
+          done
+
   # A cold, from-scratch self-host build with the manifest-pinned GCC: the
   # property `build-test` cannot cover, because it builds incrementally on a
   # restored target/. `mcpp test` is deliberately NOT repeated here — it would

.github/workflows/cross-build-test.yml

@@ -106,7 +106,7 @@ jobs:
       - name: Bootstrap mcpp via xlings
         env:
           XLINGS_NON_INTERACTIVE: '1'
-          # Must equal `pinned::kXlingsVersion` (src/platform/xlings/xlings.cppm) and the
+          # Must equal `pinned::kXlingsVersion` (src/xlings/xlings.cppm) and the
           # xlings the release bundles — enforced by
           # .github/tools/check_version_pins.sh.
           #