docs(20): state what is supported before stating how it is designed (#577)

"mcpp implements ONE mechanism, the island" is a claim about the DESIGN, and it
sat where a reader meets it first, so it was read -- more than once -- as "only
one thing is supported". The paragraph immediately after it says SYCL is reached
through the island, so the document's content already contradicted the
impression its opening left.

The real gap is that the multi-backend capability was never stated at all.
Measured:

  --accel "cuda12.9+{sm_89}, vulkan1.2"   both cfg(accelerator=…) fire
  --accel "cuda12.9+{sm_89} vulkan1.2"    only cuda

The comma separates ENTRIES in the set; a space separates MODIFIERS within one
entry. The "two-chunk accel" of the HIP and SYCL rules is not a special
grammar, it is this grammar with one entry naming a model and one naming a
device.

A new section covers writing the source sets for several backends, and with it
a failure the manifest can avoid: the four examples write
`cfg(not(accelerator = "<its own>"))`, which is correct for one backend and
wrong for several -- a CUDA build satisfies `not(accelerator = "vulkan")` too,
so the CPU implementation joins the link beside the CUDA one and the seam's
shared `extern "C"` symbols collide. Measured: `multiple definition of 'impl'`.
Negating the whole set fixes it, and the section also names the shape that
needs no such list: do not select at link time at all, which is what ggml does
and what `ggml-org:llamacpp` is built as.

Also lands round 5's ecosystem review and the plan's F2 pre-measurement, which
were held back until the release tag existed because pushing to main between
the merge and the dispatch moves the commit being released. The measurement
changes F2's plan: round 3's "blocked on a payload matrix" no longer holds, and
CUDA's shape turns out simpler than Vulkan's because it has no generator.

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

Author: Sunrisepeak

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

@@ -297,6 +297,56 @@ defect that no example had. If R1-R4 need an engine change, round 5 stops and
 that change ships first, with its own test in mcpp. Frameworks F2-F9 do not
 start until F1's example generates tokens.
 
+## 7c. F2's pre-measurement, which changed the answer
+
+The plan told F2 to re-measure round 3's "blocked on a payload matrix" before
+assuming it still held. Measured 2026-09-06 against `xim-pkgindex` origin/main:
+**it no longer holds.** `cuda-nvcc`, `cuda-cudart`, `libcublas`, `cuda-cccl`
+and `libcurand` are all published, and `<cub/cub.cuh>` is the only external
+device include across all 186 translation units. Only `libnccl` is missing, and
+that is the multi-GPU path, guarded by `find_package(NCCL)`.
+
+**F2's shape is simpler than F1's, not harder.** 186 device translation units
+against F1's 134 shaders is comparable scale, but CUDA has no generator: the
+`.cu` files are ordinary device units, and `mcpp.rules.cuda` in `mcpp:plugins`
+0.2.0 already compiles device sources declared by a constrained glob. F2 should
+need a feature, one constrained glob and the payload declarations -- no new
+rule package.
+
+The hazard round 3 found on its own gate, device objects dropped from static
+libraries, is closed: F1 measured 134 device objects inside `libllama.a` with
+`ar t`. The first thing to measure for F2 is the same archive at 186 units and
+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.
+
+**The four examples' CPU fallback does not generalise.** Each writes
+`cfg(not(accelerator = "<its own>"))`, which is correct for one backend and
+wrong for several. docs/20 now states the multi-backend idiom and the measured
+failure mode; the examples themselves stay single-backend because each teaches
+one model.
+
 ## 8. The method this round produced, which outlives its features
 
 Eight defects, six in work written for the round, none found by reading code.

.agents/docs/2026-09-06-round5-f1-ecosystem-review.md

@@ -0,0 +1,87 @@
+# Ecosystem review — round 5, F1 (llama.cpp on Vulkan)
+
+Four repositories, one lane carried from an engine primitive to generated text
+on a machine with no GPU. Written against the measurements, not the intent.
+
+| repository | change | state |
+|---|---|---|
+| mcpp-index | `compat:spirv-headers@1.4.357.0` | merged (#358), CN mirror byte-identical |
+| mcpp | two engine fixes, the example regrouping, two new checks | PR #576 |
+| llama.cpp-m | `backend-vulkan`, released as `b10069.1` | PR pending mcpp's release |
+| mcpp-plugins | none needed | 0.2.0 already carries the glslc route |
+
+## What was actually verified
+
+Not "it built". The criteria, and what each can say no to:
+
+* **The device computed the right thing.** The device decode and the host
+  decode of one prompt under greedy sampling produce the SAME token (471), and
+  the offload is asserted from llama.cpp's own log FIRST -- without that, two
+  host decodes agree trivially. A token merely inside the vocabulary is
+  produced by a backend that computed nonsense.
+* **The shaders are graph edges.** 136 declared action rules for 134 vendored
+  shaders plus the generator and the header; 134 generated sources joined the
+  compile set; `ar t libllama.a` carries 134 shader objects. A build program
+  that looped would leave the same artifacts and no edges.
+* **The feature costs a CPU consumer nothing.** With the lock removed, a
+  CPU-only build writes no `mcpp.lock` at all: it resolves nothing.
+* **The artifact's host surface.** `ldd` outside the mcpp registry: the
+  kernel's vDSO and the Khronos loader this ecosystem builds from source.
+* **The published form.** V5 section F builds a consumer that declares the
+  dependency and the feature and nothing else. Red until the index entry lands,
+  by construction.
+
+## The defects this round produced
+
+Seven, none reported by a pre-existing test; six found reviewing work written
+in this same round.
+
+| where | defect | what surfaced it |
+|---|---|---|
+| mcpp engine | `[feature-xlings]` tool installed and then invisible to `xpkg_dir` | building the backend |
+| mcpp engine | `[feature-deps]` shared library compiled and then left off the link line | the same build, at link |
+| mcpp manifest | the version warning predicted a failure it cannot see | V5's own output |
+| llama.cpp-m | the manifest claimed a platform refusal the code did not make | reading the comment against the code |
+| llama.cpp-m | a probe that failed for any other reason reported "supported" | reading upstream's rule |
+| llama.cpp-m | a warning quoting a diagnostic truncated at the first newline | the directive channel is line-based |
+| llama.cpp-m | `-static` not portable between the compilers; the clang variant that links SEGFAULTS | building under `--toolchain llvm@22.1.8` |
+
+**The two engine defects are one shape**: an answer resolved and never wired to
+the decision that reads it. Neither had a diagnostic, and the second was quiet
+because of its SHAPE -- a library package's `mcpp build` produces an archive,
+and an archive resolves no symbols.
+
+## Two of my own criteria were pointed at the wrong object
+
+Both would have shipped as green.
+
+* **e2e 615, first draft.** With a binary root it passed on both the defective
+  and the fixed engine -- measured. A fixture built around `mcpp run` was a test
+  that could not fail. The defect needs a library root whose test binary links.
+* **V5 section C, first draft.** It grepped `resolution.json`, which records
+  the machine environment's runtime binding and names `mesa-lavapipe` whether or
+  not the project asked for it. `mcpp.lock` records what the project resolved.
+
+## Stated rather than fixed
+
+* **`backend-vulkan` needs libstdc++ on this checkpoint** -- upstream destroys
+  a `std::unique_ptr<vk_memory_logger>` where the class is forward-declared.
+  Deliberately not refused: the distinction a refusal needs (which standard
+  library the project resolved) is not something mcpp hands a build program,
+  and the compiler's name would refuse clang with libstdc++, which works. That
+  gap should land WITH its consumer, not as a field nobody reads.
+* **ggml excludes a software Vulkan device on TYPE** -- lavapipe advertises
+  every required feature and is dropped for being `eCpu`. Upstream's policy,
+  upstream's selector.
+* **Two local e2e failures are machine state.** Both reproduce on the binary
+  predating every change here, and `ci-linux-e2e` is green on the base commit.
+
+## Verdict
+
+The lane is complete and the evidence is behavioural at every layer. Each
+engine fix has a criterion that exits 1 on the previous binary and 0 on this
+one, measured with the two binaries side by side.
+
+Remaining risk is entirely the release chain, whose order is forced: mcpp must
+be installable before llama.cpp-m's CI can be green, and llama.cpp-m must be
+tagged before the index can name it.

CHANGELOG.md

@@ -5,6 +5,29 @@
 
 ## [Unreleased]
 
+### docs/20 先说支持什么,再说为什么一套机制够
+
+「mcpp 只实现一套机制 —— 岛」这句话是关于**设计**的,却被放在开头当标题读,于是它被
+反复读成「只支持一种」。它下一段自己就说 SYCL 是经由岛接进来的 —— 文档的内容和它给人的
+印象互相矛盾。
+
+真正的缺口是:**多后端能力从头到尾没被写出来过**。实测:
+
+| `--accel` | 命中的 `cfg(accelerator = …)` |
+|---|---|
+| `"cuda12.9+{sm_89}, vulkan1.2"` | cuda 与 vulkan **都命中** |
+| `"cuda12.9+{sm_89} vulkan1.2"`(空格) | 只有 cuda |
+
+逗号分隔的是集合里的**条目**,空格分隔的是**同一条目内的修饰符**。「两段式 accel」
+(`"hip, cuda12.9+{sm_89}"`)不是一条特例语法,它就是这条语法,只不过两个条目一个是
+编程模型一个是设备。
+
+新增「一个构建里的多个后端」一节,连同一条本可避免的失败:四个示例写的
+`cfg(not(accelerator = "<它自己那个>"))` 对单后端是对的、对多后端是**错的** ——
+一次 CUDA 构建同样满足 `not(accelerator = "vulkan")`,CPU 实现会和 CUDA 实现一起进链接,
+实测得到 `multiple definition of 'impl'`。正确写法是否定整个集合;而更值得考虑的是
+**根本不在链接期选择**(ggml 的形态),那样就没有名单要维护。
+
 ## [2026.9.6.2] - 2026-09-06
 
 ### docs/20 增加「框架层是什么形状」

docs/20-heterogeneous-builds.md

@@ -4,7 +4,29 @@ GPU and AI accelerator targets, and mixed host/device compilation: how mcpp
 builds device code, and how a prebuilt artifact states which devices it can
 run on.
 
-## Two shapes, and the one mechanism mcpp implements
+## What is supported
+
+A build names the device backends it targets, and it may name **several**:
+
+```toml
+[build]
+accel = "cuda12.9+{sm_89}, vulkan1.2"
+```
+
+`accelerator` is a target-side **set**, so both `cfg(accelerator = "cuda")` and
+`cfg(accelerator = "vulkan")` are true in that build, each backend's rule
+package compiles its own device units, and one artifact carries all of them.
+The comma separates entries in that set; a space separates modifiers WITHIN one
+entry (`cuda12.9+{sm_89} ptx>=89` is one backend with an architecture set and a
+PTX floor). See "Several backends in one build" below for how the source sets
+are then written.
+
+Four programming models have rule packages today -- CUDA, HIP, SYCL and
+Vulkan/SPIR-V -- and the table under "The lanes" says which compiler and which
+payloads each drives. Nothing in the engine holds a vendor name, so a fifth is
+a package rather than an engine change.
+
+## Two shapes, and why one mechanism reaches both
 
 Accelerator toolchains come in two shapes. They describe how a toolchain is
 normally used, not how many mechanisms a build system needs.
@@ -18,9 +40,11 @@ A **whole-target** model puts device code in ordinary `.cpp` files and compiles
 the entire target with a compiler capable of offloading. SYCL, OpenMP offload
 and stdpar are used this way.
 
-mcpp implements ONE mechanism, the island, and that is the whole of the design.
-A whole-target toolchain is reached **through** it rather than beside it, when
-its device code can be separated at all.
+mcpp implements ONE mechanism, the island. That is a statement about the
+DESIGN, not about how many backends are supported: a whole-target toolchain is
+reached **through** the island rather than beside it, so supporting it costs a
+rule package and no second mechanism. SYCL is in the shipped set for exactly
+this reason.
 
 **SYCL's can.** A SYCL kernel is a lambda inside a `submit`, so a project can
 confine every one of them to a translation unit of its own by convention, and
@@ -281,6 +305,81 @@ The comparison is membership, so a build enabling both CUDA and ROCm answers
 true to each. `any`, `all` and `not` compose over it as ordinary boolean
 combinators.
 
+## Several backends in one build
+
+`accel` names a set, so a project supporting more than one device writes one
+section per backend and the sets compose:
+
+```toml
+[package]
+accelerators = ["cuda", "vulkan"]
+
+[build]
+accel   = "cuda12.9+{sm_89}, vulkan1.2"
+sources = [
+  "src/*.cppm", "src/*.cpp",
+  { glob = "src/kernels/**/*.cu",  accel = "cuda12.9+{sm_89}" },
+  { glob = "shaders/*.comp",       accel = "vulkan1.2" },
+]
+
+[target.'cfg(accelerator = "cuda")'.build]
+sources = ["src/cuda/*.cpp"]
+
+[target.'cfg(accelerator = "vulkan")'.build]
+sources = ["src/vulkan/*.cpp"]
+```
+
+Each constrained glob is narrowed by the set, so `--accel vulkan1.2` alone
+compiles the shaders and leaves the `.cu` out without any hand-written
+condition.
+
+### The CPU fallback, when there is more than one backend
+
+The four examples each write `cfg(not(accelerator = "<its own>"))`, which is
+correct for a project with ONE backend and wrong for a project with several: a
+CUDA build satisfies `not(accelerator = "vulkan")` too, so the CPU
+implementation joins the link beside the CUDA one. With a seam they define the
+same `extern "C"` symbols, and the result is measured:
+
+```
+ld: obj/src/cpu/impl.o: multiple definition of `impl';
+    obj/src/cuda/impl.o: first defined here
+```
+
+Loud, and at the link rather than at run time -- but it is a failure the
+manifest can avoid. Negate the whole set:
+
+```toml
+[target.'cfg(not(any(accelerator = "cuda", accelerator = "vulkan")))'.build]
+sources = ["src/cpu/*.cpp"]
+```
+
+`any`, `all` and `not` compose over the membership test as ordinary boolean
+combinators. The cost is that the list is a second place the backend set is
+written: a third backend added without extending this line produces the link
+error above.
+
+### The other shape: no link-time selection
+
+The exclusion exists only because a **seam** replaces one implementation with
+another, so exactly one may be linked. A project that wants one binary to run
+on whatever the machine has should not select at link time:
+
+* compile **every** backend it was built with -- each `cfg(accelerator = ...)`
+  section adds its own sources, and the CPU implementation is unconditional;
+* give each one a distinct name, and have the seam ask at run time which
+  devices are present.
+
+There is then no `not(any(...))` to maintain, and the artifact answers the
+question the user of the binary actually has. This is the shape ggml uses: each
+backend registers itself, and `ggml_backend_reg_by_name` picks one when the
+program runs. `ggml-org:llamacpp` is built that way, and its `backend-vulkan`
+feature is additive over `backend-cpu` rather than exclusive with it.
+
+Which shape to choose is a property of the program, not of mcpp: a seam that
+swaps an implementation wants link-time selection, and a program that ships to
+machines it has not seen wants run-time selection.
+
 ## Two boundaries worth stating
 
 **`--accel` and `--no-accel` are `build`, `run` and `test` options** (run and