2026.9.6.1: .sycl is a device source, and the criterion is the compiler (#573)

`SourceKind::Device` documents itself as a GRAPH ROLE -- "not scanned, no BMI,
compiled by a device compiler mcpp does not drive" -- explicitly so the table
does not grow a row per vendor. Until now every extension in it was also a
dialect an ordinary C++ compiler would refuse, so the distinction had never
been tested. `.sycl` tests it: its content is ordinary C++ and nothing in the
file would tell a reader otherwise. What makes it a device unit is that it goes
to a second compiler with a device back end -- icpx, or a clang built with the
SYCL front end -- which mcpp does not drive and which does not accept C++20
modules.

One row, and nothing else in the engine changes.

THE ALTERNATIVE, AND WHY IT WAS REJECTED. A constrained glob could have carried
`.cpp`. Then one extension would mean two things depending on which glob
matched first, and the seam a device build is written around -- device code
reaches the program only through an `extern "C"` header -- is legible precisely
because the file name says which side of it a unit is on.

THE ADDITION IS INERT ON EXISTING BUILDS, and the two conditions hold jointly:
device extensions are absent from `default_source_globs`, so no glob widens;
and a file with one of these extensions named in `sources` was a hard error
before the row existed, so nothing silently switches role.

e2e 613 is five sections and two of them are the ones that make the other three
a measurement:

  * section three is the control -- the SAME CONTENT named `.cpp` must still be
    compiled as C++ and must NOT reach the build program. A test naming only
    `.sycl` would pass on a table that had started classifying by content.
  * section five asserts the WHOLE default glob list rather than the absence of
    one name, so a future addition cannot pass this file while changing what a
    default build compiles.

Section four is the variant switch applied to the new row: `--no-accel` takes
the constrained glob out, which is what makes the CPU half of a seam reachable
without editing the manifest. Its first draft asserted that a `.sycl` in an
UNCONSTRAINED glob is refused; that was wrong and the run said so -- an
extension the table names is accepted wherever it is globbed, and the
compatibility guarantee is section five, not a refusal.

Chapter 20 gains the table of lanes -- which rule drives which compiler, which
payloads it needs, and what `[build] accel` says -- in both languages, and its
"Not implemented" section is corrected: the whole-target shape is no longer
among the missing, because a SYCL toolchain is now reached THROUGH the island
rather than beside it.

The rules themselves ship in `mcpp:plugins` 0.2.0: `mcpp.rules.sycl` drives the
`xim:dpcpp` payload, `mcpp.rules.hip` treats HIP on the NVIDIA platform as the
header layer over the CUDA runtime that it is, and `mcpp.rules.spirv` gains the
glslc route now that `xim:shaderc` publishes one.

Unit 105/105 (the new case verified to run by name, not by the suite being
green); e2e 606, 609, 610 and 613 pass against this binary.

Author: speak-agent

.agents/docs/2026-09-05-heterogeneous-build-ecosystem-design-v2.md

@@ -390,3 +390,110 @@ The first sandbox run failed six assertions. One was a defect in the ecosystem,
 **The second retired criterion: the exit code of a mirror write.** Both tools print their configuration on stderr, so reading it through `2>/dev/null` returned an empty string and reported a mirror that was in fact set to CN.
 
 **Two properties of the sandbox that the run established.** A subos root has no `/run`, so the inherited `XDG_RUNTIME_DIR` names a directory that does not exist; Mesa falls back to it when `memfd` is unavailable and lavapipe fails with `Failed to create anonymous file for memory allocations` before it reports a device. And the registry's index snapshot is shared with whatever wrote it last: the run resolved against a snapshot four commits behind `main`, where `compat.opencl-headers` reported `download artifact missing` because the recipe was not in it. The verification script now redirects the first and refreshes the second before it measures anything.
+
+## 7. Round 4 (2026-09-06): the second device API, and the compiler each one needs
+
+Rounds 1 to 3 closed the host surface and delivered two lanes, CUDA and Vulkan,
+each through a rule package in `mcpp:plugins`. What they did not deliver is the
+evidence that the shape generalises: a single lane proves a rule package can
+drive one vendor's compiler, and the claim this ecosystem makes is that the
+engine knows no vendor at all. Round 4 is the second instance of that claim,
+taken in the direction where it is most likely to break -- a device API that is
+not CUDA (`HIP`), and a compilation model that is not the island (`SYCL`, where
+the device compiler consumes ordinary C++ and emits a fat object).
+
+### 7.1 What round 3 left open, and which of it this round closes
+
+| row | item | round 4 |
+|---|---|---|
+| C2 | `mcpp.rules.sycl` driving the `dpcpp` payload | closed |
+| C3 | `mcpp.rules.hip` | closed, on the NVIDIA platform, which is the platform this machine can decide |
+| C4 | llama.cpp Vulkan lane | its blocker is closed (`glslc` has no payload); the framework itself is a packaging round of its own and stays open |
+| A5 / X4 | Intel `anv` in the Mesa payload | its two missing links are closed (`libclc`, `llvm-spirv`); the Mesa rebuild stays open, and the reason is stated in 7.5 |
+| A3 | aarch64 for the third class | stays open; the blocker X1 recorded is unchanged |
+| T1.2 | `llvm-offload` | withdrawn: the `dpcpp` payload carries `clang-linker-wrapper`, `clang-offload-bundler` and `llvm-offload-binary`, which is the whole of what the row asked for, and round 4 makes that payload reachable through a rule |
+
+### 7.2 The one engine change, and why it is one row
+
+SYCL is compiled by a second compiler from a translation unit that is ordinary
+C++ -- there is no `.cu` to route. The engine's device-extension table is the
+mechanism that routes a source away from mcpp's own compiler, so the table gains
+`.sycl` and nothing else changes. The table's own comment states the two
+conditions under which an addition is inert, and both hold: device extensions
+are absent from `default_source_globs`, so no glob widens, and a file with one of
+these extensions named in `sources` is today a hard error, so nothing silently
+changes role.
+
+The alternative -- letting a constrained glob carry `.cpp` -- was rejected. It
+would make one extension mean two things depending on which glob matched it
+first, and the seam discipline round 2 settled on (device code reaches the
+program only through an `extern "C"` header) is legible exactly because the file
+name says which side of the seam a unit is on.
+
+### 7.3 Schedule
+
+Status is one of `done`, `open`, `deferred (reason)`.
+
+#### xim-pkgindex (single PR)
+
+| # | task | criterion | depends on | status |
+|---|---|---|---|---|
+| Z1 | `xim:shaderc` 2026.3: `glslc` and `libshaderc`, conda-forge repack with its closure, x86_64 and aarch64, both mirrors | `glslc --version` from the payload; a `.comp` compiles to SPIR-V; every `DT_NEEDED` of every payload object resolves inside payloads | - | open |
+| Z2 | `xim:hip-nvidia` rocm-7.2.4: the HIP headers plus `hipother`'s `nvidia_detail`, architecture-independent | a `.hip` translation unit compiles against it with `__HIP_PLATFORM_NVIDIA__` and links against the CUDA payload | - | open |
+| Z3 | `xim:libclc` 22.1.8 and `xim:llvm-spirv` 22.1.2, conda-forge repacks | each installs; `llvm-spirv --version` answers; the libclc bitcode for `nvptx64` and `spirv64` is present | - | open |
+| Z4 | CI green; merge; index artifact published | `Publish Index Artifact` green on the merge commit | Z1-Z3 | open |
+
+#### mcpp (single PR, version 2026.9.6.1)
+
+| # | task | criterion | depends on | status |
+|---|---|---|---|---|
+| N1 | `.sycl` in the device-extension table | a unit test over the whole table with the table as its denominator; e2e: a `.sycl` in a constrained glob reaches `MCPP_DEVICE_SOURCES`, and the same file outside one is still a hard error | - | open |
+| N2 | `examples/11-sycl-compute`: one SYCL kernel behind a seam, the CUDA backend and the host device from one artifact | `12 24 36 48` on the RTX 4080 and again with `--no-accel` | N1, Q1 | open |
+| N3 | `examples/12-hip-compute`: a `.hip` kernel through `mcpp.rules.hip` on the NVIDIA platform | `12 24 36 48`, and no `/usr` path on any command line | Q2, Z2 | open |
+| N4 | Chapter 20 gains the SYCL and HIP lanes and the table of which rule drives which compiler; chapter 18 gains the two devices; both languages | `check_docs_style.sh` passes; the Chinese chapter has the rows the English one has | N2, N3 | open |
+| N5 | Version 2026.9.6.1, CHANGELOG, unit and e2e suites, PR, CI green, self-review | no e2e failure other than the ones already failing on `origin/main` | N1-N4 | open |
+| N6 | Release, mirror, index bump, bootstrap pin | both mirrors return 200 and identical bytes for every asset; xim-pkgindex names it `latest` | N5 | open |
+
+#### mcpp-plugins (single PR, version 0.2.0)
+
+| # | task | criterion | depends on | status |
+|---|---|---|---|---|
+| Q1 | `mcpp.rules.sycl`, feature `rules-sycl` | a fixture compiles a `.sycl` unit with the `dpcpp` payload and links it into a C++23-modules program; the rule refuses with the declaration to add when the payload is absent | N1 | open |
+| Q2 | `mcpp.rules.hip`, feature `rules-hip` | a fixture compiles a `.hip` unit on the NVIDIA platform; the rule names the platform it selected and why | Z2 | open |
+| Q3 | `mcpp.rules.spirv` gains the `glslc` route now that a payload exists | both compilers produce a header the same program includes; the rule states which one it used and refuses a mixture | Z1 | open |
+| Q4 | CI: one consumer fixture per feature, built with the pinned mcpp | green on the PR head | Q1-Q3, N6 | open |
+| Q5 | Release `v0.2.0`; GitHub archive and a GitCode asset with identical bytes; index descriptor | both URLs return 200 and one sha256 | Q4 | open |
+
+#### mcpp-index (single PR)
+
+| # | task | criterion | depends on | status |
+|---|---|---|---|---|
+| R1 | `mcpp:plugins` 0.2.0 in `pkgs/m/mcpp.plugins.lua`, floor 2026.9.6.1 | `mcpp add mcpp:plugins` resolves in a sandbox and the new features are selectable | Q5, N6 | open |
+| R2 | CI green; merge; index artifact published | `Publish Index Artifact` green on the merge commit | R1 | open |
+
+#### Verification
+
+| # | task | criterion | depends on | status |
+|---|---|---|---|---|
+| V3 | A fresh subos, CN mirror for both tools: install mcpp 2026.9.6.1 from the index, build examples 09 through 12 against `mcpp:plugins` 0.2.0 | every example builds; example 10 answers on lavapipe; the device half of 09, 11 and 12 compiles and says cleanly that the sandbox has no device | Z4, N6, Q5, R2 | open |
+| V4 | The same on this host with the GPU | `12 24 36 48` from 09, 11 and 12 on the RTX 4080 | V3 | open |
+
+### 7.4 The completion rule
+
+This round is not finished when its pull requests merge. It is finished when
+every row above reads `done` against its own criterion and the ecosystem has
+been exercised end to end on a machine that starts with none of it installed:
+the released engine fetched from the index, the rule collection fetched from
+the index, every payload fetched from its mirror, and each example answering.
+A row whose work is written but not measured stays `open`; a row that cannot be
+measured here says so and names what would decide it. V3 and V4 are that
+measurement, and no part of this round is reported as complete before they are
+green.
+
+### 7.5 Dynamic updates
+
+Every change to the plan is recorded here with its reason.
+
+| date | change | reason |
+|---|---|---|
+| 2026-09-06 | table created | - |

CHANGELOG.md

@@ -5,6 +5,30 @@
 
 ## [Unreleased]
 
+## [2026.9.6.1] - 2026-09-06
+
+### `.sycl` 进设备扩展名表:判据是编译器,不是方言
+
+`SourceKind::Device` 自陈是一个**图上的角色** —— 「不扫描、不产 BMI、由 mcpp 不驱动的
+设备编译器编译」—— 而在此之前表里每一个扩展名都是普通 C++ 编译器会拒绝的方言。`.sycl`
+不是:它的内容就是普通 C++。使它成为设备单元的是它交给谁 —— 一个带设备后端、且不接受
+C++20 modules 的第二个编译器(icpx,或带 SYCL 前端的 clang)。
+
+被否掉的替代是「让收窄的 glob 去承载 `.cpp`」。那会让同一个扩展名因为哪条 glob 先匹配
+而指向两个不同的编译器,而设备构建赖以可读的接缝(设备代码只经 `extern "C"` 头进入程序)
+正是因为文件名说明了一个单元在接缝的哪一侧。
+
+这次加行**对既有构建是惰性的**,两个条件同时成立:设备扩展名不在 `default_source_globs`
+里,所以没有任何 glob 变宽;而把这类扩展名写进 `sources` 在加行之前是硬错误,所以没有
+任何文件悄悄换了角色。e2e 613 的第五段对**整张默认 glob 列表**做断言而不是对两个名字,
+第三段则用同一份内容的 `.cpp` 拼法做对照 —— 只测 `.sycl` 的用例在一张「按内容分类」的
+表上同样会通过。
+
+配套的规则包在 `mcpp:plugins` 0.2.0:`mcpp.rules.sycl` 驱动 `xim:dpcpp` 载荷,
+`mcpp.rules.hip` 在 NVIDIA 平台上把 HIP 当作 CUDA 运行时之上的一层头文件,
+`mcpp.rules.spirv` 增加 `glslc` 路线(`xim:shaderc` 使它从一句声明变成一条路线)。
+文档见 `docs/20-heterogeneous-builds.md` 的「lanes」一节。
+
 ### `mcpp clean --stale`:只清 target/ 里已无构建使用的指纹目录 (#565)
 
 每次配置指纹变化都会在 `target/<三元组>/` 下新开一个目录,旧目录从不回收;`mcpp clean` 只有整删

docs/20-heterogeneous-builds.md

@@ -18,7 +18,14 @@ 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 work this way. There is no island to separate.
 
-This document describes the island shape, which is what mcpp implements.
+mcpp implements the island shape, and a whole-target toolchain is reached
+through it rather than beside it: a SYCL translation unit is named `.sycl`,
+routed to the SYCL compiler by the same constrained glob that routes a `.cu`,
+and joins the link through the same seam. What the file name buys is that one
+extension means one thing -- letting a glob carry `.cpp` would make the same
+name mean two different compilers depending on which glob matched first, and
+the seam is legible precisely because the name says which side of it a unit is
+on.
 
 ## Device translation units
 
@@ -27,12 +34,17 @@ unit**. mcpp classifies it as such and treats it accordingly: it is never
 scanned for imports and never produces a BMI, because no device compiler
 accepts C++20 modules.
 
-The criterion is the compiler, not the vendor (the table below is
-2026.9.5.3+; before it, `.cu` and `.hip` alone):
+The criterion is the compiler, not the language (the table below is
+2026.9.5.3+; before it, `.cu` and `.hip` alone). `.sycl` is where that
+distinction becomes visible: its content is ordinary C++ and nothing in the
+file would tell a reader otherwise. What makes it a device unit is that it goes
+to a compiler with a device back end -- one mcpp does not drive, and one that
+does not accept C++20 modules.
 
 | language | extensions |
 |---|---|
 | CUDA, HIP | `.cu`, `.hip` |
+| SYCL | `.sycl` (2026.9.6.1+) |
 | GLSL, by stage | `.comp`, `.vert`, `.frag`, `.geom`, `.tesc`, `.tese`, `.mesh`, `.task`, `.rgen`, `.rint`, `.rahit`, `.rchit`, `.rmiss`, `.rcall` |
 | GLSL, stage-less | `.glsl` |
 | HLSL | `.hlsl` |
@@ -269,10 +281,43 @@ in precisely the way the dimension exists to prevent. A publisher writes the
 field explicitly today, which is what index descriptors do; `mcpp pack` will
 emit it once `kind = "device"` puts the device compilation inside mcpp.
 
+## The lanes, and what each one drives
+
+A rule package owns one compiler's spelling. The engine knows none of these
+names: `tests/unit/test_core_vendor_probes.cpp` asserts that no vendor tool
+name appears in `src/` once comments are stripped, with the file count as its
+own denominator.
+
+| feature of `mcpp:plugins` | module | compiler it drives | payloads it needs | `[build] accel` |
+|---|---|---|---|---|
+| `rules-cuda` | `mcpp.rules.cuda` | the project's own clang (`-x cuda`), or nvcc with a GCC toolchain | `xim:cuda-nvcc`, `xim:cuda-cudart`, `xim:libcurand`, `xim:cuda-cccl` | `cuda12.9+{sm_89} ptx>=89` |
+| `rules-hip` | `mcpp.rules.hip` | the project's own clang (`-x cuda`) on the NVIDIA platform | the above plus `xim:hip-nvidia` | `hip, cuda12.9+{sm_89}` |
+| `rules-sycl` | `mcpp.rules.sycl` | the `xim:dpcpp` payload's clang (`-fsycl`) | `xim:dpcpp`, `xim:gcc`, `xim:cuda-nvcc` for an NVIDIA target | `sycl` or `sycl, cuda12.9+{sm_89}` |
+| `rules-spirv` | `mcpp.rules.spirv` | `glslangValidator` or `glslc` | `xim:glslang` or `xim:shaderc` | `vulkan1.2` |
+
+Two chunks, not one, in the `accel` value of the HIP and SYCL rows. The first
+names the programming model and the second names the device, so a device is
+spelled once in this ecosystem however many models reach it: `sm_89` is the
+same `sm_89` whichever rule reads it. `accel = "sycl"` with no second chunk
+compiles to SPIR-V and lets the runtime choose a device.
+
+**HIP on the NVIDIA platform is a header layer, not a second runtime.** Every
+HIP entry point is an inline wrapper over the CUDA one, so the object links
+against the CUDA runtime and there is no ROCm on the machine. `xim:hip-nvidia`
+therefore contains no binaries. The AMD platform needs a ROCm runtime this
+ecosystem does not publish yet, and the rule refuses it by name rather than
+producing an object nothing can link.
+
+**A SYCL build carries two C++ runtimes, and the seam is what makes that safe.**
+`libsycl.so` is compiled against libstdc++ while an mcpp artifact links libc++,
+so both are in the image and mcpp's duplicate-symbol check reports the
+unwinder symbols they share. Nothing may cross the seam: a SYCL exception is
+caught in the device translation unit and returned as a code, because the
+runtime that threw it is not the one the caller would unwind with.
+
 ## Not implemented
 
-The whole-target shape (SYCL, OpenMP offload, stdpar), device targets and the
-device linking they imply, static libraries containing device code, and
-accelerator payloads supplied through xim. See
-`.agents/docs/2026-09-05-accelerator-support-design.md` for the design these
-follow from.
+Device targets and the device linking they imply for the island shape, OpenMP
+offload and stdpar, the AMD platform of HIP, and Metal. See
+`.agents/docs/2026-09-05-heterogeneous-build-ecosystem-design-v2.md` for the
+design these follow from and the reason each is open.