examples: the module surface, and one header kept for contrast (#588)

The payload lane and the boundary lane are separate, and each example now
shows one of them.

`vulkan` reaches its SPIR-V through a MODULE. `src/vulkan/saxpy.cpp` opened
with `#include "scale_comp.h"` -- a name no line in the project produced and
no reader could derive without opening the rule -- and now imports
`vulkan_saxpy.shaders`, whose name and whose `scale_comp()` accessor are both
derived from names the project already wrote. The accessor answers with the
address and the byte count together, which is what makes `sizeof` the wrong
question rather than merely an awkward one: the rule may put the words in an
object, and there is then no array to take the size of.

`cuda` and `sycl` GENERATE their `extern "C"` boundary. Each entry point is
marked with `MCPP_EXPORT_C` where it is defined, and `mcpp.tools.island`
writes the header the island's compiler reads and the module the seam
imports. `include/saxpy/saxpy.h` is gone from both. Both halves are handed to
the scan, so a signature that drifted between the island and the CPU
fallback is refused while the boundary is generated -- the one point at which
both texts exist at once, and the only check available at a boundary where C
language linkage does not mangle and the two halves are never in one link.

The island names nothing and the host half writes one `#include`, and that
asymmetry is measured rather than incidental. The island is compiled by a
driver mcpp did not invoke, so its rule takes forced-include flags for that
one command line. The host half is ordinary project C++, and the only
project-wide channel would force the header into every C++ translation unit
including the seam, where declarations ahead of `export module` are
ill-formed.

`hip` keeps its hand-written header, and its README says why. It computes the
same thing through the same seam as `cuda`, so the difference between the two
examples is exactly this one thing, and the hand-written form is what every C
boundary looks like today. Neither is deprecated; the generated form is the
default because the copy it removes is the one that goes wrong quietly.

`multi-backend` reaches its SPIR-V as `opkit.shaders` too, and keeps
`include/opkit/opkit.h` written by hand -- which is the distinction this example
is for. That header is a LIBRARY boundary: consumers outside this tree compile
against it, so it is not an intermediate and generating it would not remove a
copy, it would move one. The shader payload is an intermediate, and it moves.

`examples/10-graphics/offscreen` moves too, and it is the one example CI both
builds AND RUNS on two platforms -- so the surface is exercised there rather
than merely compiled. Two includes become one import, and the two stages are
`offscreen::shaders::triangle_vert()` and `::triangle_frag()`.

`cann` is unchanged. Its boundary has a different shape -- `saxpy_device`
between the seam and a host glue file, `saxpy_launch` between that glue and
the kernel -- and both halves of the first one are compiled by mcpp, so the
forced-include asymmetry above does not apply. Its README already records
that the example does not build yet.

Verified on this host: cuda and sycl build and run on an RTX 4080 with the
generated boundary on the island's own command line, vulkan runs on the same
device with its shader reached as a module, multi-backend runs on lavapipe with
`--accel "vulkan1.2"`, the offscreen triangle renders on lavapipe at centre
pixel `(124, 70, 62, 255)` -- the same pixel its CPU leg produces, which is the
assertion CI makes -- and each CPU leg builds and runs under `--no-accel`.

`docs/20`'s two-lanes section said the seam is written by hand and the shader
lane's equivalent is generated. Half of that still holds: the seam is a design
decision. What sits under it is each signature written a second time, and that
half is now generated too. The section says so, and gains the table that maps a
file name to the call it arrives as -- which is the question a reader of that
document actually has.

Every example under `examples/09-heterogeneous` and `examples/10-graphics`
pins 0.3.0 now, `hip` and `cann` included. Neither uses anything new, and
leaving them behind would be defensible in isolation -- but `hip` exists to
be read beside `cuda`, and a reader comparing the two would find a second
difference the text never explains. The floor sentences move with them.

The six plugin pins in `docs/05` and `docs/20` move too, in both languages.
A version in a document is the line someone pastes, and 0.2.1 and 0.2.4
predate every declaration those sections now describe -- a reader who copied
one would get a build in which the rules never route.

The Windows graphics run step was brought back as a MEASUREMENT and is
withdrawn again, this time with an answer. Four rounds established what it is
not -- a missing `vulkan-1.dll`, an unparseable ICD manifest (a real defect,
fixed in openxlings/xim-pkgindex#781, and not this failure's cause), a failed
`LoadLibrary`, or the driver-files variable's vintage -- and the last round
asked the loader instead of guessing:

    INFO: Loader is running with elevated permissions.
          Environment variable VK_DRIVER_FILES will be ignored
    INFO: Loader is running with elevated permissions.
          Environment variable VK_ICD_FILENAMES will be ignored
    ERROR | DRIVER: Registry lookup failed to get ICD manifest files.

A GitHub Windows runner runs elevated, and the loader discards every
driver-path environment variable when it is -- it will not let a path a
non-administrator could write inject a driver into an elevated process. It
falls back to the registry, which has no ICD. No package change reaches
that; the mechanism this example uses on Linux and macOS is unavailable to
an elevated process on Windows, and reaching lavapipe there means a registry
entry under `HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\Vulkan\Drivers` or an
unelevated run.

The four eliminations and the loader's own words are recorded beside the
withdrawn step, so the next attempt starts from there rather than from the
first hypothesis. Windows keeps building the Vulkan half and running the CPU
fallback.

Requires mcpp:plugins 0.3.0.

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

Author: Sunrisepeak

.agents/docs/2026-09-07-module-first-heterogeneous-surface.md

@@ -846,6 +846,55 @@ and a newer one moves a project to the module surface with nothing declared.
 | Seamless upgrade | A project that writes nothing new keeps its behaviour | Header storage stays the default under `modules = false`; the default surface follows `[language] modules` |
 | Test coverage | Each surface and each storage has a consumer that runs | P7 |
 
+### 13.3.1 What the self-review found after the surface was working
+
+Four findings, three of them in names the surface generates. Every one was found
+by giving the generator an input nobody had tried, and none of them by reading
+the code -- which is the reason they are recorded together.
+
+**The user-facing name came from the wrong question.** The module a consumer
+imports was derived from the leaf of `MCPP_MANIFEST_DIR` -- a directory name --
+because nothing in the build-program contract answered "what package am I
+building". `examples/09-heterogeneous/vulkan/app/` declares
+`name = "vulkan-saxpy"` and generated `app.shaders`. Worse than the defect is
+that no fixture could see it: all fourteen had a package name equal to their
+directory name, so both derivations produced the same string. Fixed by
+`MCPP_PKG_NAME` in the engine, and by making one fixture's two names differ on
+purpose.
+
+**A generated name may not be a C++ keyword.** Six sites ran the same character
+filter and none checked for reserved words. `shaders/default/` produced
+`namespace default {` in a generated file. Fixed by one `surface::identifier`
+that owns all three transformations, applied at the point where the accessor is
+EMITTED rather than in each producer -- a rule that builds the name from a file
+stem cannot know it has produced a keyword until it reaches the line that writes
+the function's name.
+
+**A seam's two halves are compared nowhere else.** The island and the host
+fallback define one `extern "C"` boundary and are never in one link, and C
+language linkage does not mangle, so two that declare a name differently build
+cleanly and the artifact reads its arguments by whichever it was compiled with.
+`mcpp.tools.island::scan` is handed both files and is therefore the only point
+at which both texts exist at once. It refuses there.
+
+**One fix was written and withdrawn.** `host-module` is inferred from a rule
+feature the consumer REQUESTS. A rule package whose rule sits in its own
+`[features] default` activates without being named, so the rule modules are
+collected -- that reads the resolved set -- while the inference reads the
+requested one. Extending the inference to the dependency's defaults was measured
+against a probe package and made the outcome WORSE: the refusal went from
+
+    error: build.mcpp imports 'probe.rules.probe', and no dependency provides
+           it as a host module.
+           declared without `host-module = true`: probe.rules
+
+to the same refusal plus `importable here: rules`, which says the dependency is
+wired up while the feature's own module still is not. The gap is further down,
+in when a default feature's sources are folded into the set `units()`
+enumerates. `mcpp:plugins` declares `default = []`, so nothing shipped reaches
+it, and the existing refusal already names exactly what to add. Recorded here
+rather than half-fixed.
+
 ### 13.4 Release and verification sequence
 
 1. mcpp pull request: E1 through E5. CI green on the head, then merged, then the

.github/workflows/ci-windows.yml

@@ -456,41 +456,62 @@ jobs:
           done
           echo "ok: both shader stages compiled and the Vulkan half linked"
 
-      # WINDOWS STAYS AT "BUILDS", AND WHAT REMAINS OPEN IS THE DRIVER.
+      # WINDOWS STAYS AT "BUILDS", AND FOUR MEASUREMENTS SAY WHY IT IS NOT
+      # WAITING ON ANY OF THE THINGS IT WAS THOUGHT TO BE.
       #
-      # A run step was written, pushed, and measured (run 34135108981). The
-      # manifest declaration worked -- `Provisioning [xlings.workspace] entries
-      # (xim:mesa-lavapipe@26.2.0)` -- the ICD manifest was found in the store,
-      # and the program printed `render unavailable`, which is `src/main.cpp`
-      # reporting that the render function returned nothing.
+      # 1. Not a missing `vulkan-1.dll`. The program printed `render
+      #    unavailable`, which `src/main.cpp` writes after the render function
+      #    returns nothing. A process that could not resolve `vkCreateInstance`
+      #    from that DLL fails during image load and prints nothing at all.
+      #    mcpp-index's own `vulkan-tests` member calls
+      #    `vkEnumerateInstanceVersion` on the windows shards and passes.
       #
-      # THAT OUTPUT PLACES THE FAILURE AFTER THE LOADER, NOT AT IT. The Vulkan
-      # leg imports `vkCreateInstance` from `vulkan-1.dll` through the import
-      # library, so a process missing that DLL fails during image load and
-      # prints nothing at all. It printed. The loader was there, it ran, and it
-      # enumerated no device -- which is a statement about the ICD.
+      # 2. Not an unparseable ICD manifest, though that WAS a real defect.
+      #    `xim:mesa-lavapipe` wrote its rewritten `library_path` into the
+      #    JSON string unescaped, so `C:\Users\...` carried `\U` and the
+      #    loader's cJSON parser rejected the file -- an ICD it skips with no
+      #    error. Fixed in openxlings/xim-pkgindex#781. With the fix the runner
+      #    reads
+      #      "library_path": "C:/Users/.../lib/vulkan_lvp.dll"
+      #    and the manifest parses. The program still prints `render
+      #    unavailable`.
       #
-      # An earlier revision of this comment named a missing `vulkan-1.dll` as
-      # the cause. That was an inference from the descriptor's note about static
-      # linkage rather than a reading of the failure, and the log refutes it.
-      # Two facts stand against it: this program ran, and mcpp-index's own
-      # `vulkan-tests` member calls `vkEnumerateInstanceVersion` on the windows
-      # shards and passes.
+      # 3. Not a failed `LoadLibrary`. `vulkan_lvp.dll` imports only
+      #    ADVAPI32, GDI32, KERNEL32, ntdll, ole32, SHELL32 and USER32, all of
+      #    which any Windows has; the payload ships nothing else that could be
+      #    missing.
       #
-      # A separate measurement, recorded here because it removes a second thing
-      # from the list of suspects: the Khronos loader in `compat:vulkan` builds
-      # into a working `vulkan-1.dll` from the source the index already carries
-      # (mingw, 265 exports matching upstream's `vulkan-1.def` exactly, DllMain
-      # present, importing only ADVAPI32/CFGMGR32/KERNEL32/msvcrt). The
-      # descriptor's note argues that a Windows loader must be a DLL, not that
-      # it cannot be built -- so a hermetic Windows loader is available whenever
-      # it is wanted. It is not what this step is waiting on.
+      # 4. Not the environment variable's vintage. Both `VK_DRIVER_FILES` and
+      #    `VK_ICD_FILENAMES` were set, which covers loaders on either side of
+      #    1.3.234.
       #
-      # What this step is waiting on is `xim:mesa-lavapipe`'s Windows payload
-      # producing a device under an mcpp-launched process. Until that is
-      # measured, the job builds the Vulkan half and runs the CPU fallback.
-      # macOS is not in the same position: MoltenVK enumerates once the instance
-      # asks for portability, which `src/vulkan/render.cpp` now does.
+      # What the loader itself said under `VK_LOADER_DEBUG=all`:
+      #
+      #   INFO: Loader is running with elevated permissions.
+      #         Environment variable VK_DRIVER_FILES will be ignored
+      #   INFO: Loader is running with elevated permissions.
+      #         Environment variable VK_ICD_FILENAMES will be ignored
+      #   DRIVER: Found no registry files in
+      #           HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\Vulkan\Drivers
+      #   ERROR | DRIVER: windows_read_data_files_in_registry: Registry lookup
+      #           failed to get ICD manifest files.  Possibly missing Vulkan driver?
+      #
+      # THAT IS THE WHOLE ANSWER, AND NO PACKAGE CHANGE REACHES IT. A GitHub
+      # Windows runner runs elevated, and the loader discards every driver-path
+      # environment variable when it is -- it will not let a path a
+      # non-administrator could write inject a driver into an elevated process.
+      # It then falls back to the registry, which has no ICD. The mechanism this
+      # example uses on Linux and macOS is simply unavailable here.
+      #
+      # Reaching lavapipe on Windows therefore means registering the ICD under
+      # `HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\Vulkan\Drivers`, or running the
+      # program unelevated. `xim:mesa-lavapipe`'s `config()` says outright that
+      # it places the payload and leaves naming the ICD to the consumer, so the
+      # registry entry is a decision for that package or for this repository,
+      # not a defect in either
+      #
+      # So the platform builds the Vulkan half and runs the CPU fallback, and
+      # the next attempt starts from here rather than from the top.
 
       - name: "Toolchain: LLVM — build mcpp (self-host)"
         shell: bash

docs/01-examples.md

@@ -32,10 +32,10 @@ examples.
 | 07 | [`examples/07-project-subos`](../examples/07-project-subos/) | A build program that finds its tools in the environment the project declared | `[xlings] subos`, `[xlings.workspace]`, a build program whose `PATH` is the environment the project named |
 | 08 | [`examples/08-build-rules`](../examples/08-build-rules/) | Two rule packages and a project that uses both | `host-module = true`, `[build-dependencies]`, `mcpp::action` with `role = "check"` |
 | 09 | [`examples/09-heterogeneous`](../examples/09-heterogeneous/) | One computation on a device, in several programming models, with a CPU fallback in each; plus one artifact carrying several backends at once | `accel`, constrained source globs, the seam module, rule packages from `mcpp:plugins`, `cfg(accelerator = …)` |
-| 09a | [`…/cuda`](../examples/09-heterogeneous/cuda/) | A CUDA kernel behind a seam module | `mcpp.rules.cuda`, `mcpp::action` with `role = "object"`, the driver stated as a fact and a floor |
-| 09b | [`…/vulkan`](../examples/09-heterogeneous/vulkan/) | The same computation as a Vulkan compute shader, on a GPU or on the CPU | `mcpp.rules.spirv`, `mcpp::action` with `role = "source"`, generated headers, a software driver as a payload |
-| 09c | [`…/sycl`](../examples/09-heterogeneous/sycl/) | The same computation as a SYCL kernel, compiled by a second compiler | `mcpp.rules.sycl`, the `.sycl` device extension, a chained `mcpp::action` for the device link, `compat:sycl-runtime` |
-| 09d | [`…/hip`](../examples/09-heterogeneous/hip/) | The same computation in HIP, reaching an NVIDIA device | `mcpp.rules.hip`, HIP as a header layer over the CUDA runtime, a two-chunk `accel` |
+| 09a | [`…/cuda`](../examples/09-heterogeneous/cuda/) | A CUDA kernel behind a seam module, with the `extern "C"` boundary GENERATED | `mcpp.rules.cuda`, `mcpp.tools.island`, `mcpp::action` with `role = "object"`, the driver stated as a fact and a floor |
+| 09b | [`…/vulkan`](../examples/09-heterogeneous/vulkan/) | The same computation as a Vulkan compute shader, with the SPIR-V payload reached as a MODULE | `mcpp.rules.spirv`, the module surface, `mcpp::action` with `role = "source"`, a software driver as a payload |
+| 09c | [`…/sycl`](../examples/09-heterogeneous/sycl/) | The same computation as a SYCL kernel, compiled by a second compiler | `mcpp.rules.sycl`, `mcpp.tools.island`, the `.sycl` device extension, a chained `mcpp::action` for the device link, `compat:sycl-runtime` |
+| 09d | [`…/hip`](../examples/09-heterogeneous/hip/) | The same computation in HIP, with the boundary WRITTEN BY HAND — the contrast against 09a | `mcpp.rules.hip`, HIP as a header layer over the CUDA runtime, a two-chunk `accel` |
 | 09e | [`…/multi-backend`](../examples/09-heterogeneous/multi-backend/) | Several backends in ONE artifact, chosen at run time — the library shape, not the program shape | `accel` as a set, `cfg(accelerator = "none")` and its negation, a dispatch chain, a module seam over a C island boundary |
 | 09f | [`…/cann`](../examples/09-heterogeneous/cann/) | An Ascend C kernel behind the same seam. **Does not build yet** — its README names the two missing pieces | the `.asc` device extension, `op_kernel`/`op_host` as an island CANN already has, `accelerator = "none"` for the fallback |
 | 10 | [`examples/10-graphics`](../examples/10-graphics/) | Graphics rather than compute: a rendering pipeline whose result is pixels | `mcpp.rules.spirv` for the vertex and fragment stages, offscreen rendering as the assertable form |

docs/05-mcpp-toml.md

@@ -2308,7 +2308,7 @@ have none, and nothing is what they write:
 
 ```toml
 [build-dependencies.mcpp]
-plugins = { version = "0.2.4", features = ["rules-cuda"], host-module = true }
+plugins = { version = "0.3.0", features = ["rules-cuda"], host-module = true }
 ```
 
 That one edge is the whole declaration. The rule package names the packages its
@@ -2546,7 +2546,7 @@ rules-spirv = { sources = ["rules/spirv.cppm"] } # export module mcpp.rules.spir
 ```toml
 # a consumer
 [build-dependencies.mcpp]
-plugins = { version = "0.2.1", features = ["rules-spirv"], host-module = true }
+plugins = { version = "0.3.0", features = ["rules-spirv"], host-module = true }
 ```
 
 **`[build-dependencies]`, not `[dependencies]`** — a rule package is the case

docs/20-heterogeneous-builds.md

@@ -185,13 +185,20 @@ could read a BMI.
 The seam above is written by hand, and the shader lane's equivalent is
 generated. That is not an inconsistency; the two lanes carry different things.
 
-**A device translation unit is code.** Its interface is a design decision --
-which functions, which types, what happens on failure -- and no generator can
-make that decision well. So CUDA, HIP, SYCL and Ascend C get a hand-written
-seam, and the `extern "C"` header exists for the ABI reason above. Both are
-already invisible to a consumer: only the seam includes the header, and
-everything downstream writes `import app.saxpy`. **These lanes are module-first
-today and always have been.**
+**A device translation unit is code, and the seam over it is a design
+decision** -- which functions, which types, what happens on failure. No
+generator makes that decision well, so CUDA, HIP, SYCL and Ascend C get a
+hand-written seam, and everything downstream writes `import app.saxpy`.
+
+**The `extern "C"` boundary UNDER that seam is not a design decision.** It is
+each entry point's signature, stated a second time in a header, at the one place
+where a disagreement is invisible: C language linkage does not mangle, and a
+device island and its host fallback are never in one link. `mcpp.tools.island`
+reads the marked declarations out of both implementations and writes that header
+and a module over it, so the signatures exist once and two halves that disagree
+are refused where both texts are in front of the generator.
+`examples/09-heterogeneous/cuda` and `.../sycl` are that shape;
+`.../hip` keeps its header written by hand, so the two can be read side by side.
 
 **A shader or an embedded file is data.** Its interface is an address and a
 size, which is mechanical, so a rule package generates it and a consumer writes
@@ -203,6 +210,31 @@ So the rule is not "generate the interface" or "write it by hand". It is: a
 mechanical interface is generated, a designed one is written, and in both cases
 the header is an intermediate that no consumer names.
 
+#### The name a payload arrives under
+
+The module and the namespace are one identifier path, derived from names the
+project already wrote.
+
+| Written | Reached as |
+|---|---|
+| `[package] name = "myapp"` | module root `myapp` |
+| `shaders/scale.comp` | `myapp::shaders::scale_comp()` |
+| `shaders/a/scale.comp` | `myapp::shaders::a::scale_comp()` |
+| a `MCPP_EXPORT_C` entry point | `export using ::the_name;` in the boundary module |
+
+The root is the **package's** name with non-identifier characters replaced, not
+its directory's -- the two differ whenever a package sits under a generic folder,
+and mcpp reports the package name to a build program from 2026.9.7.1 for exactly
+this. The stem and the stage make the accessor (`scale.comp` -> `scale_comp`),
+and the directory below the group's base becomes namespace segments, which is
+what makes two shaders sharing a stem two things rather than a collision. A
+project that wants another name passes one; `examples/09-heterogeneous/cuda`
+does, so its boundary is `app.kernels` beside its seam `app.saxpy`.
+
+The accessor answers with the address and the byte count together. `sizeof` is
+not merely awkward at this boundary, it is unanswerable: the words may be in an
+object rather than in an array, and there is then nothing to take the size of.
+
 ## Compiling an island
 
 The command that invokes a device compiler is not built into mcpp. It is
@@ -221,7 +253,7 @@ A project that wants a CUDA island writes one edge:
 
 ```toml
 [build-dependencies.mcpp]
-plugins = { version = "0.2.4", features = ["rules-cuda"], host-module = true }
+plugins = { version = "0.3.0", features = ["rules-cuda"], host-module = true }
 ```
 
 and nothing else. The vendor toolkit, its runtime and whatever else the rule