docs, examples: an island's entry points arrive in the module's own namespace (#591)

* docs, examples: an island's entry points arrive in the module's own namespace

`docs/42` states one rule for both lanes -- the module name and the namespace
are one identifier path -- and the shader lane followed it while
`mcpp.tools.island` did not: every entry point was emitted at global scope, so
`import app.kernels` bought a file name and nothing else. `mcpp:plugins` 0.5.0
makes the island lane follow it, and this updates the three examples that use
the generator and the chapters that describe it.

The rule is now stated once, for both lanes, with the leaf identifier as the
only difference: the data lane derives it from a file name because a payload
has no name of its own, and the island lane takes the entry point's name
because the author wrote one. That is also why a file name reaches nothing on
the island lane, and why moving a function between two files in one directory
renames nothing a consumer wrote.

The generator's section moves from 31 to 42. 31's reader is a rule author, and
no rule package calls the generator -- `tools/island.cppm` says a project does,
from its own build program. What stays in 31 is the one field a rule owes it,
`options::flags`, and a link. `docs/README.md`'s concept row moves with it, and
`MCPP_EXPORT_C` is now explained in the chapter that row points at rather than
named in a table cell.

`examples/09-heterogeneous/boundary` gains a second island one directory deeper,
because the namespace mirroring the tree is the thing the example exists to
show, and it takes `strip_prefix` -- it is the one example whose consumer
writes a boundary name directly. `cuda` and `sycl` name two roots and say which
supplies the shape; their seams call `kernels::saxpy_device` from inside
`namespace app`.

Every example pins 0.5.0, so one version of the package is resolved across the
tree.

Verified against the released mcpp 2026.9.8.1 before the pin was restored:
`boundary` prints `6 12 18 24` and `nm` shows one `boundary_saxpy` and no
`saxpy`; the CPU legs of `cuda` and `sycl` build and run with the namespaced
boundary. `check_docs_structure.sh`, `check_docs_style.sh`,
`check_version_pins.sh` and e2e 616 pass.

* examples: pin mcpp:plugins 0.5.1, and record what shipped

0.5.1 adds the refusal of overlapping roots that the design record states and
0.5.0 shipped without. Every example resolves one version of the package.

* examples: pin mcpp:plugins 0.5.2

0.5.2 fixes a defect the cross-platform run of the generator's fixture found:
`namespace_of` trimmed a base directory off a file's directory as a string, and
on Windows a root stated with forward slashes against a directory iterator
appending with the preferred separator left `\image` rather than `image` -- so
the root directory became a namespace segment and an entry point landed in
`app::kernels::_::image`.

The shader lane shares that function and had the defect latent: its Windows
fixture keeps every payload in one directory, so a segment was never derived
there. `examples/09-heterogeneous/vulkan` and `examples/10-graphics/offscreen`
therefore take this pin for a reason of their own.

Verified against the published package: `boundary` resolves
`mcpp-x-plugins/0.5.2` from the index and prints `6 12 18 24`.

* docs(plan): the plan records three releases, not one

0.5.0 carried the design, 0.5.1 the refusal of overlapping roots the design
states and 0.5.0 omitted, and 0.5.2 the separator defect the first
cross-platform run of the generator's fixture found.

---------

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

Author: Sunrisepeak

.agents/docs/2026-09-08-island-boundary-names-implementation-plan.md

@@ -0,0 +1,215 @@
+---
+subject: heterogeneous
+status: active
+---
+
+# Implementation plan: the island boundary's names
+
+Executes [2026-09-08-island-boundary-names.md](2026-09-08-island-boundary-names.md)
+across three repositories. One pull request per repository, ordered by what each
+one's CI needs to be green.
+
+## Global constraints
+
+* `mcpp:plugins` 0.5.0. The floor stays **mcpp 2026.9.8.1** -- nothing here uses
+  an engine API newer than 0.4.0 already required, so `MCPP_VERSION` in the
+  plugins CI does not move and neither does any index floor.
+* The generated header stays flat, `extern "C"`, free of namespaces, and is what
+  a device compiler reads. Only the `.cppm` gains namespaces.
+* No compatibility flag. The four call sites are updated in the same batch.
+* Prose is declarative and free of decoration; no emoji in documentation, in
+  code comments, or in commit messages.
+* Every generated name passes through one sanitiser, shared by both lanes.
+
+## The order, and why it is not free
+
+```
+  T1..T5  mcpp-plugins PR ──> merge ──> tag v0.5.0 ──> GitHub release
+                                                        │
+                                                        ├─> gtc: CN asset
+                                                        │
+                                                   T6  mcpp-index PR (0.5.0 + latest)
+                                                        │
+                                                   T7..T10  mcpp PR (docs + examples)
+                                                        │
+                                                   T11 sandbox verification
+```
+
+`examples/09-heterogeneous/boundary` is built by mcpp's own CI
+(`.github/tools/build_examples.sh`) and resolves `mcpp:plugins` through the
+index, so the mcpp pull request cannot be green until 0.5.0 is published and
+indexed. The plugins fixtures use `path = "../.."` and are therefore independent.
+
+---
+
+## T1 -- one sanitiser, shared by both lanes
+
+**Files:** `src/plugins.cppm` (add `mcpp::plugins::names`),
+`rules/spirv.cppm` (call it instead of defining it).
+
+`identifier`, `split_module_name`, `common_base_dir` and `namespace_of` become
+`mcpp::plugins::names::*`. `surface` and the island generator both call them, so
+a directory named `2d` or `default` gets one answer rather than two that agree
+today by inspection.
+
+Exported inline functions in this package must not range-for over a
+`std::string`: GCC 16 then instantiates `std::string::iterator` in the BMI and
+every consumer's build program fails to compile in `<bits/stl_iterator.h>`.
+Index instead. `tools/island.cppm` records the measurement.
+
+*Criterion:* `rules/spirv.cppm` contains no definition of `common_base_dir` or
+`namespace_of`, and `tests/spirv-module-consumer` still emits
+`namespace default_ {`.
+
+## T2 -- roots, layout root, and namespaced emission
+
+**Files:** `tools/island.cppm`.
+
+```cpp
+struct options {
+    std::string module_name;                  // the module root
+    std::string out_dir;
+    std::string produced_by;
+    bool        emit_module   = true;
+    std::string marker        = "MCPP_EXPORT_C";
+    std::vector<std::string> roots;           // directories, or single files
+    std::string layout_root;                  // default: roots.front()
+    std::vector<std::string> extensions;      // default: device table + C/C++
+    std::string strip_prefix;                 // empty: no short name
+};
+
+struct entry {
+    std::string decl;                         // verbatim, as scanned
+    std::string name;                         // the identifier before `(`
+    std::vector<std::string> name_space;      // segments below the layout root
+    std::string origin;                       // the file it was first seen in
+};
+
+std::optional<std::vector<entry>> scan(const options&);
+std::optional<emitted>            emit(std::span<const entry>, const options&);
+entry declared(std::string decl, std::vector<std::string> ns = {});  // rung L2
+```
+
+`scan` walks each root in declaration order, sorted by path, reading files whose
+extension is in the set. For each marked declaration it records the entry, its
+name and the namespace segments of its directory relative to its own root. An
+entry's namespace is the one it has in the layout root; an entry the layout root
+does not declare keeps the namespace of the first root that does.
+
+`emit` writes one flat header and one module. The module groups entries by
+namespace path and opens each block once.
+
+*Criteria:* the four fixtures below.
+
+## T3 -- the two checks
+
+**Files:** `tools/island.cppm`.
+
+* A name declared twice within one root is refused, naming both files and saying
+  that two implementations of one entry point belong in two roots.
+* A name declared in several roots whose declarations differ is refused, naming
+  both files and both declarations. This is the check 0.4.0 performs; what
+  changes is that it no longer doubles as the collision check.
+* `scan` that finds no marked entry point in any root is an error naming the
+  roots. An empty module is a misspelled path or a marker that never arrived.
+
+## T4 -- the short name
+
+**Files:** `tools/island.cppm`.
+
+`strip_prefix` non-empty emits `inline constexpr auto <short> = <name>;` beside
+`using ::<name>;`. The short name passes through `names::identifier`. Two entries
+stripping to one short name are refused naming both. An entry not carrying the
+prefix gets no short name.
+
+Measured 2026-09-08: `app::kernels::image::blur == &app::kernels::image::opkit_blur`
+under clang++ (DPC++ 7.1.0) `-std=c++23`, and the same declarations compile under
+GCC 13.
+
+## T5 -- fixtures and CI
+
+**Files:** `tests/island-interface/**`, `.github/workflows/ci.yml`,
+`README.md`, `mcpp.toml` (0.5.0), `src/plugins.cppm` (the version constant).
+
+The fixture gains a subdirectory in the layout root and a flat fallback file, so
+the namespace, the flat-fallback allowance and the layout root's authority are
+all exercised by the shape of the tree rather than by an assertion about it:
+
+```
+src/kernels/saxpy.c            island_saxpy_device   -> ::kernels
+src/kernels/image/scale.c      island_scale_device   -> ::kernels::image
+src/cpu/ops.c                  both, flat
+```
+
+CI steps, each with a denominator:
+
+1. the module carries `export namespace island_interface::kernels {` and
+   `export namespace island_interface::kernels::image {`;
+2. the header carries neither `namespace` nor any of the short names;
+3. the flat fallback is accepted and `image` survives -- moving `src/cpu/ops.c`
+   to `src/cpu/deep/ops.c` leaves the generated `.cppm` byte-identical;
+4. two files in ONE root declaring one name are refused naming both;
+5. two entries stripping to one short name are refused naming both;
+6. roots that hold no marker are refused naming the roots;
+7. the short name and the long name are one entity, and the artifact holds one
+   symbol for the pair;
+8. the 0.4.0 disagreement check still fires, unchanged;
+9. the CPU leg (`--no-accel`) reaches the same qualified names.
+
+## T6 -- mcpp-index
+
+**Files:** `pkgs/m/mcpp.plugins.lua`.
+
+A `0.5.0` entry in each of the three platform tables with the release tarball's
+sha256, and `["latest"] = { ref = "0.5.0" }` in each. The header comment gains
+the paragraph describing what 0.5.0 changes. Existing consumers pin exact
+versions, so moving `latest` breaks none of them.
+
+*Criterion:* `mcpp add mcpp:plugins` in a sandbox resolves 0.5.0, and the
+descriptor holds exactly one `["latest"]` per platform table.
+
+## T7 -- examples
+
+**Files:** `examples/09-heterogeneous/boundary/**`,
+`examples/09-heterogeneous/cuda/app/**`, `examples/09-heterogeneous/sycl/app/**`.
+
+Each pins `plugins = { version = "0.5.2", ... }`, passes `roots` and a
+`layout_root`, and reaches the boundary through the qualified name. `boundary`
+additionally shows `strip_prefix`, because it is the example whose whole subject
+is the generated interface.
+
+## T8 -- documentation
+
+**Files:** `docs/42-heterogeneous-builds.md`, `docs/zh/42-...`,
+`docs/31-authoring-a-rule-package.md`, `docs/zh/31-...`, `docs/README.md`,
+`docs/zh/README.md`, `examples/09-heterogeneous/boundary/README.md`,
+`examples/09-heterogeneous/README.md`.
+
+The island generator's section moves from 31 to 42, because 31's reader is a
+rule author and no shipped rule calls the generator. 31 keeps one sentence and a
+link. The name table in 42 gains the island rows. Both languages, with the
+section numbering and the cross-references checked.
+
+## T9 -- the check that keeps the two languages equal
+
+`.github/tools/` already holds the documentation parity check that CI runs. The
+new sections are added to both languages in the same commit, and the check is
+run locally before the pull request.
+
+## T10 -- release
+
+Tag the release, publish it from the tag, `gtc` upload of the same bytes to
+GitCode, then T6. This ran three times: 0.5.0 for the design, 0.5.1 for the
+refusal of overlapping roots that the design states and 0.5.0 omitted, and
+0.5.2 for the separator defect the first cross-platform run of the fixture
+found.
+
+## T11 -- ecosystem verification
+
+In an xlings sandbox, with the CN mirror configured for both mcpp and xlings:
+resolve `mcpp:plugins@0.5.0` from the index, build and run the `boundary`
+example against the published package rather than a path override, and confirm
+the qualified names in the generated module.
+
+*Criterion:* the sandbox is the only thing that verifies the published artifact;
+a path override in a working tree verifies the working tree.