feat: cxx_stdlib, the curriculum in CI, and two criteria that machine state decided (#579)

`mcpp::cxx_stdlib()` / `MCPP_CXX_STDLIB` (2026.9.6.3). The engine has resolved
this value for a long time -- it is in the cache key, the ABI tag, the toolchain
fingerprint and `resolution.json` -- and never handed it to the layer that has
to decide on it. `compiler()` cannot answer it: clang links libc++ on one
machine and libstdc++ on another and reports "clang" either way, while the two
differ in what they accept. llama.cpp-m has the case today, and its refusal
lands in the same round. e2e 617 compares the answer against `resolution.json`
and against the compiler family; removing the wiring turns it red.

The examples say which device ran them. All four islands in 09-heterogeneous
printed the same four numbers as their CPU fallback, so a silent fallback was
indistinguishable from a device run -- in the one set of examples whose subject
is which device ran the computation. The seam carries `saxpy_device_name()`,
each backend fills in its own device, and it is set only after a successful
call: a device run that did not happen has no device to report. Measured:
`device: llvmpipe (LLVM 22.1.8, 256 bits)` against
`device: cpu (this build names no accelerator)`.

CI builds the curriculum. No job did. `.github/tools/build_examples.sh`
enumerates the example ROOTS from the tree and compares them against a build
list and a skip table; a root in neither fails the job, and every skip names its
reason and where the coverage is. Six of fifteen build, including
05-lib-distribution through its own README's two-step order -- which also checks
that the ABI tag its consumer hardcodes is still the one `mcpp pack` produces.
The Vulkan example is built and RUN on the lavapipe payload.

Two e2e criteria were decided by machine state, and both were green on every
runner because a runner installs exactly one of anything.
`206_runtime_binding_physics` asserted `inconclusive` on the assumption that the
private loader cannot reach a host `libtinfo`; `xim:ncurses` is an ordinary
ecosystem package, and a sub-OS that has it puts `libtinfo.so.6` on the
artifact's RPATH, where the closure genuinely closes. It now reads the
artifact's own search path and asserts in both directions.
`168_build_mcpp_musl_host_static` selected its payload with `ls | head -1` --
lexicographic order, hence the oldest -- and on a machine with three musl
toolchains chose one that predates the `std` module. It takes the newest, which
is what resolution picks when nothing pins a version.

The four device examples move to `mcpp:plugins` 0.2.1; the SYCL one also
declares `xim:glibc` and `xim:linux-headers`, unpinned, because the device
compiler is a second compiler and does not inherit the toolchain the engine
configured.

Co-authored-by: speak-agent <248744407+speak-agent@users.noreply.github.com>

Author: Sunrisepeak

.agents/docs/2026-09-06-ecosystem-plan-v3.md

@@ -235,14 +235,45 @@ forced rather than chosen.
 | R4 | done | `llvmpipe (LLVM 22.1.8, 256 bits)`, 7/7 layers offloaded, host token 471 = device token 471; the chat example generates 32 tokens |
 | R6 | written | a `vulkan` job on a GPU-less runner, gated on the lavapipe payload and `GGML_VK_VISIBLE_DEVICES=0` |
 | R7 | done | docs/20 and docs/zh/20, "What a framework looks like on top of this" |
-| R5 | blocked on release order | the index entry can only name an artefact that exists, so it follows llama.cpp-m's tag |
+| R5 | done, with a second lever | mcpp-index#359 carries `b10069.1`. It also had to raise the index's CI pin: `validate.yml` was on 2026.8.27.2, ten releases behind, and this package's build program calls an accessor from 2026.9.5.2. `min_mcpp` deliberately did NOT move -- see 7e |
 
 **The release order is the reverse of the dependency order**, as it always is
 here: mcpp 2026.9.6.2 first (llama.cpp-m's CI pins it), then llama.cpp-m
 `b10069.1`, then the index entry that names that tag. The index PR for
 `compat:spirv-headers` went first and separately because llama.cpp-m cannot
 build without it -- splitting it out was forced by the cycle, not chosen.
 
+## 7e. The index's CI pin is not its floor
+
+`ggml-org:llamacpp@b10069.1` failed three of mcpp-index's workspace jobs with
+
+    error: 'toolchain_sysroot' is not a member of 'mcpp'
+
+because `validate.yml` pinned mcpp 2026.8.27.2 while that accessor is
+2026.9.5.2+. Two levers exist and they govern different things:
+
+| | governs | moves when |
+|---|---|---|
+| `index.toml [index] min_mcpp` | descriptor GRAMMAR -- the oldest mcpp able to resolve every descriptor | a descriptor uses a new key, in lock-step with the CI pin |
+| `validate.yml MCPP_VERSION` | which mcpp the index builds its members with | the engine moves; a pin that lags validates the index against an engine no user runs |
+
+A build program's API belongs to the second. Raising `min_mcpp` would refuse
+the WHOLE index (E0006) to a client on the floor over one package's
+build-program call it may never reach, which is the failure mode
+`index-floor-must-degrade` names: the index is data, mcpp is the program, and
+publishing data must not invalidate the program. Measured: all 218 descriptors
+parse under both versions, so the grammar did not move; `b10069` stays
+published for a client that cannot use `b10069.1`.
+
+The cost is paid once per raise: the members' caches key on `MCPP_VERSION`, so
+the first run after the pin moves rebuilds everything.
+
+This is not a one-off. `b10069.2` calls `mcpp::cxx_stdlib()` (2026.9.6.3), so
+the same five-step chain runs again: mcpp release, xim-pkgindex bump, package
+change, package release, index bump carrying the new pin. mcpp has no
+per-package engine floor, so a client on an older engine gets
+`'X' is not a member of 'mcpp'` rather than a refusal that names a version.
+
 ### What the angles decide
 
 **Architecture.** The shader pipeline is 136 edges in the build graph, not one
@@ -319,27 +350,52 @@ libraries, is closed: F1 measured 134 device objects inside `libllama.a` with
 a consumer's link line, since `cudart_static` plus 186 objects is the largest
 link this ecosystem has attempted.
 
-## 7d. Open, with the reason each is open
-
-**`mcpp::toolchain_stdlib()`.** mcpp resolves `stdlibId` and writes it into
-`resolution.json`; the build-program environment does not carry it. A build
-program driving a SECOND compiler may need it, and llama.cpp-m has the case
-today -- `backend-vulkan` cannot compile under libc++ (upstream's own source),
-and the refusal it would like to write is impossible because the only available
-signal is the compiler's NAME, which would also refuse clang with libstdc++.
-Same family as the two defects this round fixed. Deliberately not shipped
-alone: without a consumer in the same release it is a recorded field with no
-reader, which is the shape this ecosystem keeps finding.
-
-**No CI job builds an example.** e2e 616 checks that the curriculum and its
-index agree structurally, and says so: it builds nothing. The Vulkan example
-needs no GPU, so it is the one that could join CI first.
-
-**`206_runtime_binding_physics` is decided by machine state.** It asserts a
-status that depends on the private loader's default prefix NOT existing, and a
-leftover `fromsource-x-glibc@2.39/lib` makes it exist. Green in CI, red on a
-developer machine that has one. The criterion should name the directory it
-depends on rather than assume its absence.
+## 7d. Closed in round 5b, and what remains open
+
+Round 5 left four items recorded rather than done, on the stated ground that
+each needed a consumer or a measurement it did not yet have. Three are now
+closed; the reasons they were open turned out to be partly wrong, and saying so
+is the point of writing them down.
+
+**`mcpp::cxx_stdlib()` -- done, 2026.9.6.3.** Shipped as `MCPP_CXX_STDLIB` and
+`mcpp::cxx_stdlib()`, with its consumer in the same round: llama.cpp-m's
+`backend-vulkan` refuses a libc++ toolchain by name instead of handing the user
+a page of errors from an upstream header. The name changed from the one
+recorded here -- `cxx` is in it because `MCPP_TARGET_LIBC` is the C library,
+and in an ecosystem that names glibc and musl constantly the two must not share
+a word. Its criterion (e2e 617) compares the answer against `resolution.json`
+and against the compiler family, and was checked by removing the wiring and
+watching it go red.
+
+**No CI job builds an example -- done.** `.github/tools/build_examples.sh`
+enumerates the example ROOTS from the tree and compares them against a build
+list and a skip table; a root in neither fails the job, and every skip carries
+its reason and where the coverage actually is. Six of fifteen build, including
+`05-lib-distribution` through its own README's two-step order, which also
+checks that the ABI tag the consumer hardcodes is still the tag `mcpp pack`
+produces. The Vulkan example is built AND RUN on the lavapipe payload.
+
+That run needed one more change. All four device examples printed the same four
+numbers as their CPU fallback, so a run that silently fell back was
+indistinguishable from a device run -- in a curriculum whose subject is
+heterogeneous compute. The seam now carries `saxpy_device_name()`, each backend
+fills in its own device, and `main` prints it after the call, never before.
+
+**`206_runtime_binding_physics` -- done, and the recorded reason was wrong.**
+It was not a stale `fromsource-x-glibc` prefix. `xim:ncurses` is an ordinary
+ecosystem package, and a sub-OS that has it links `libtinfo.so.6` into the
+library view that IS on the artifact's RPATH; there the closure genuinely
+closes and `pass` is the correct verdict. The test now reads the artifact's own
+runtime search path and decides which verdict the model owes, so it fails in
+both directions instead of assuming a directory is absent.
+
+A second test had the same shape and was found while fixing the first:
+`168_build_mcpp_musl_host_static` selected its musl payload with `ls | head -1`
+-- lexicographic order, hence the OLDEST installed version. On a machine with
+13.3.0, 15.1.0 and 16.1.0 it chose 13.3.0, which predates the `std` module, and
+the error it produced described the test's own choice. It now takes the newest,
+which is what resolution picks when nothing pins a version. Both were green on
+every CI runner, because a runner installs exactly one of anything.
 
 **The four examples' CPU fallback does not generalise.** Each writes
 `cfg(not(accelerator = "<its own>"))`, which is correct for one backend and

.agents/docs/2026-09-06-round5-verify.sh

@@ -1,12 +1,13 @@
 #!/usr/bin/env bash
-# Ecosystem verification for round 5: mcpp 2026.9.6.2, compat:spirv-headers,
-# and ggml-org:llamacpp's backend-vulkan feature.
+# Ecosystem verification for rounds 5 and 5b: mcpp (2026.9.6.2, then
+# 2026.9.6.3), compat:spirv-headers, ggml-org:llamacpp's backend-vulkan
+# feature, and the build-program API a release carries embedded in its binary.
 #
 #   # The sandbox has an EMPTY $HOME and a fresh /tmp, so this file is not
 #   # visible from inside it. Pass the script itself in:
 #   B64=$(base64 -w0 <this file>)
-#   xlings subos use verify-962 --sandbox --cmd \
-#     "echo $B64 | base64 -d > /tmp/v.sh && MCPP_VERIFY_VERSION=2026.9.6.2 bash /tmp/v.sh"
+#   xlings subos use verify-963 --sandbox --cmd \
+#     "echo $B64 | base64 -d > /tmp/v.sh && MCPP_VERIFY_VERSION=2026.9.6.3 bash /tmp/v.sh"
 #
 # `xlings subos use <name>` -- the bare `xlings subos <name>` form this header
 # used to give is rejected as an unknown subcommand, and a sandbox that has to
@@ -300,6 +301,61 @@ else
     tail -20 "$work/consumer.log"
 fi
 
+# -- G. the build-program API the published binary carries ------------------
+section "G. mcpp::cxx_stdlib() answers, in the published binary"
+# A BUILD-PROGRAM API IS PART OF THE PUBLISHED FORM, and nothing above tests
+# that. The `mcpp` module a build program imports is EMBEDDED IN THE BINARY --
+# so a release whose module source did not travel would compile every project
+# in this repository (they use a checkout) and fail for the first user who
+# wrote `mcpp::cxx_stdlib()`. That is the shape this ecosystem keeps meeting:
+# the development form and the published form are not the same graph.
+#
+# The criterion is the ANSWER, not the compile: an accessor that exists and
+# returns "" would compile here and be useless, so the value is compared
+# against `resolution.json`, which the same binary writes from its own
+# resolution.
+probe="$work/stdlibq"
+mkdir -p "$probe/src"
+printf 'int main() { return 0; }\n' > "$probe/src/main.cpp"
+cat > "$probe/mcpp.toml" <<'TOML'
+[package]
+name    = "stdlibq"
+version = "0.1.0"
+[targets.stdlibq]
+kind = "bin"
+main = "src/main.cpp"
+TOML
+cat > "$probe/build.mcpp" <<'CPP'
+#include <cstdio>
+#include <string>
+import mcpp;
+int main() {
+    // To a file: a build program's stdout reaches the user only when it fails.
+    std::string out = std::string(mcpp::manifest_dir()) + "/answer.txt";
+    std::FILE* f = std::fopen(out.c_str(), "w");
+    if (f == nullptr) return 1;
+    const char* s = mcpp::cxx_stdlib();
+    std::fprintf(f, "%s\n", s == nullptr ? "" : s);
+    std::fclose(f);
+    return 0;
+}
+CPP
+if (cd "$probe" && "$STORE" build >"$work/stdlibq.log" 2>&1); then
+    answered=$(cat "$probe/answer.txt" 2>/dev/null | head -1)
+    engine=$(find "$probe/target" -name resolution.json -print -quit 2>/dev/null \
+             | xargs -r sed -n 's/.*"stdlib"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1)
+    if [ -z "$answered" ]; then
+        fail "G: mcpp::cxx_stdlib() answered nothing"
+    elif [ "$answered" != "$engine" ]; then
+        fail "G: the build program read '$answered', the engine resolved '$engine'"
+    else
+        ok "G: mcpp::cxx_stdlib() = '$answered', matching this binary's own resolution.json"
+    fi
+else
+    fail "G: a build program calling mcpp::cxx_stdlib() did not build against the published $VER"
+    tail -12 "$work/stdlibq.log"
+fi
+
 printf '\n== summary ==\n'
 if [ -n "$skipped" ]; then
     printf 'NOT RUN, and therefore not verified:%s\n' "$skipped"

.github/tools/build_examples.sh

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+# Build every example in `examples/` that this runner can build.
+#
+# WHY THIS EXISTS. Until it did, no CI job built any example. e2e 616 checks
+# that the curriculum and the table documenting it agree structurally, and says
+# so explicitly: it builds nothing. Every example here could have stopped
+# compiling and the first report would have come from a reader.
+#
+# THE LIST IS DERIVED FROM THE TREE. `BUILD` and `SKIP` are compared against
+# the roots actually on disk, and a root in neither list fails this script.
+# That is the denominator: adding an example forces a decision about whether CI
+# can build it, instead of leaving it silently uncovered.
+#
+# A SKIP CARRIES ITS REASON AND ITS ELSEWHERE. "CI cannot build this" is only
+# acceptable when something else does, and each entry says what.
+set -uo pipefail
+
+MCPP="${MCPP:?set MCPP}"
+cd "$(dirname "$0")/../.."
+
+BUILD=(
+    examples/01-hello
+    examples/02-with-deps
+    examples/03-pack-static
+    examples/04-workspace
+    examples/08-build-rules/app
+)
+
+# `key|reason`.
+SKIP=(
+    "examples/05-lib-distribution/producer|packed and then consumed by the dedicated step below, which is the order the example's own README gives"
+    "examples/05-lib-distribution/consumer|same"
+    "examples/06-openkal-cross|cross-builds to a second target; the payload matrix is what the target-matrix workflow already covers, and repeating it here would double a long job for no new signal"
+    "examples/07-project-subos|provisions a project-local sub-OS, which e2e 27_self_contained_home covers directly and far more cheaply"
+    "examples/08-build-rules/rules-embed|a rule package is not a standalone build: its interface imports the bundled mcpp module, which exists only inside a consumer's build. Verified by building 08-build-rules/app, the same way mcpp-plugins verifies its own members"
+    "examples/08-build-rules/rules-tidy|same"
+    "examples/09-heterogeneous/cuda/app|needs the CUDA payload set, and a device to run; the rule package is covered by mcpp-plugins' own CI"
+    "examples/09-heterogeneous/hip/app|same, for the HIP payloads"
+    "examples/09-heterogeneous/sycl/app|needs the dpcpp payload (over a gigabyte) and a device its runtime accepts"
+    "examples/09-heterogeneous/vulkan/app|built AND RUN by the next step of this job, on the lavapipe payload, which needs no GPU"
+)
+
+# Every ROOT manifest in the tree: a directory with an `mcpp.toml` that has no
+# ancestor manifest below `examples/`. A workspace member is not a root.
+mapfile -t FOUND < <(
+    find examples -name mcpp.toml -not -path '*/target/*' | while read -r m; do
+        d=$(dirname "$m"); p=$(dirname "$d"); root=1
+        while [ "$p" != "." ] && [ "$p" != "examples" ]; do
+            [ -f "$p/mcpp.toml" ] && { root=0; break; }
+            p=$(dirname "$p")
+        done
+        [ "$root" = 1 ] && echo "$d"
+    done | sort -u
+)
+
+fail=0
+declare -A known=()
+for b in "${BUILD[@]}"; do known["$b"]=build; done
+for s in "${SKIP[@]}"; do known["${s%%|*}"]=skip; done
+
+echo "== the tree has ${#FOUND[@]} example roots =="
+for f in "${FOUND[@]}"; do
+    if [ -z "${known[$f]:-}" ]; then
+        echo "ERROR: $f is in neither BUILD nor SKIP."
+        echo "       Add it to one. A skip must say why, and where it is covered instead."
+        fail=1
+    fi
+done
+for k in "${!known[@]}"; do
+    printf '%s\n' "${FOUND[@]}" | grep -Fxq "$k" || {
+        echo "ERROR: $k is listed here but is not a root in the tree."
+        fail=1
+    }
+done
+[ "$fail" -eq 0 ] || exit 1
+
+for s in "${SKIP[@]}"; do
+    echo "SKIP ${s%%|*}: ${s#*|}"
+done
+
+built=0
+for d in "${BUILD[@]}"; do
+    echo "== $d =="
+    if (cd "$d" && "$MCPP" build); then built=$((built + 1)); else
+        echo "FAIL: $d did not build"; fail=1
+    fi
+done
+
+# ── 05-lib-distribution: pack, then consume ────────────────────────────────
+# The consumer names the produced directory by its ABI TAG, which is what the
+# README tells a reader to do. Building it here is therefore also a check that
+# the tag in the manifest is still the tag `mcpp pack` produces -- a claim the
+# example makes in prose and nothing else verified.
+echo "== examples/05-lib-distribution (pack, then consume) =="
+if (cd examples/05-lib-distribution/producer && "$MCPP" pack mathkit); then
+    named=$(sed -n 's/.*path = "\(\.\.\/producer[^"]*\)".*/\1/p' \
+            examples/05-lib-distribution/consumer/mcpp.toml | head -1)
+    if [ -d "examples/05-lib-distribution/consumer/$named" ]; then
+        if (cd examples/05-lib-distribution/consumer && "$MCPP" build); then
+            built=$((built + 1))
+        else
+            echo "FAIL: the consumer did not build"; fail=1
+        fi
+    else
+        echo "FAIL: the consumer names '$named', which mcpp pack did not produce."
+        echo "      Produced:"; ls examples/05-lib-distribution/producer/target/dist 2>&1 | sed 's/^/        /'
+        fail=1
+    fi
+else
+    echo "FAIL: mcpp pack mathkit"; fail=1
+fi
+
+echo "== built $built of $(( ${#BUILD[@]} + 1 )) =="
+[ "$built" -eq $(( ${#BUILD[@]} + 1 )) ] || fail=1
+exit "$fail"

.github/workflows/ci-linux.yml

@@ -243,3 +243,61 @@ jobs:
           "$MCPP" self config --mirror GLOBAL
           "$MCPP" build
           "$MCPP" run
+
+  # THE CURRICULUM WAS NEVER BUILT BY ANY JOB. e2e 616 checks that the examples
+  # and the table that documents them agree, and says so explicitly: it builds
+  # nothing. Every example in this repository could therefore stop compiling and
+  # the only signal would be a user reporting it.
+  #
+  # The list is DERIVED FROM THE TREE, not written here. An example that is in
+  # neither the build list nor the skip table fails this job, so adding one
+  # forces a decision about whether CI can build it rather than silently
+  # leaving it uncovered.
+  examples:
+    name: "examples: the curriculum builds"
+    runs-on: ubuntu-24.04
+    # Generous rather than tight: six cold example builds plus the Vulkan one,
+    # which provisions the shader compiler and a software driver as payloads.
+    timeout-minutes: 90
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/bootstrap-mcpp
+
+      - name: Build mcpp from source (self-host)
+        run: |
+          export MCPP_VENDORED_XLINGS="$XLINGS_BIN"
+          "$XLINGS_BIN" config --mirror GLOBAL 2>/dev/null || true
+          "$MCPP" self config --mirror GLOBAL 2>/dev/null || true
+          "$MCPP" build
+          MCPP_FRESH=$(realpath "$(find target -type f -name mcpp -printf '%T@ %p\n' | sort -rn | head -1 | cut -d' ' -f2)")
+          cp "$MCPP_FRESH" /tmp/mcpp-fresh
+          echo "MCPP=/tmp/mcpp-fresh" >> "$GITHUB_ENV"
+
+      - name: Build every example the runner can build
+        run: |
+          export MCPP_VENDORED_XLINGS="$XLINGS_BIN"
+          bash .github/tools/build_examples.sh
+
+      - name: "Vulkan example: build the device half and run it on lavapipe"
+        run: |
+          export MCPP_VENDORED_XLINGS="$XLINGS_BIN"
+          cd examples/09-heterogeneous/vulkan/app
+          "$MCPP" build
+          # BOTH STORES, because which one holds the payload is decided by how
+          # this mcpp resolved its home -- and a `find` over only one of them
+          # is the defect this repository has already paid for twice (e2e 614,
+          # llama.cpp-m's Vulkan job). Ask for the file, not for a layout.
+          icd=$(find "${MCPP_HOME:-$HOME/.mcpp}/registry/data/xpkgs/xim-x-mesa-lavapipe" \
+                     "$HOME/.xlings/data/xpkgs/xim-x-mesa-lavapipe" \
+                     -name 'lvp_icd.x86_64.json' -print -quit 2>/dev/null || true)
+          [ -n "$icd" ] || { echo "no lavapipe ICD in either store"; exit 1; }
+          echo "using ICD $icd"
+          out=$(VK_DRIVER_FILES="$icd" "$MCPP" run 2>&1) || { echo "$out"; exit 1; }
+          echo "$out"
+          # The device leg is the point: a run that silently fell back to the
+          # CPU variant would print the same numbers, so the assertion is that
+          # the program says which device answered AND that it is the payload's.
+          echo "$out" | grep -q 'llvmpipe' \
+            || { echo "the run did not reach the lavapipe device"; exit 1; }
+          echo "$out" | grep -q '12 24 36 48' \
+            || { echo "the device produced the wrong result"; exit 1; }