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

[Sunrisepeak]

Implements .agents/docs/2026-09-08-island-boundary-names.md on this side. mcpp:plugins 0.5.2 is released and indexed (mcpp-index#374), so the examples here resolve it through the index rather than through a path override.

The rule, stated once

docs/42 already said that the module name and the namespace are one identifier path. The shader lane followed it; the island lane did not, and put every entry point at global scope -- so import app.kernels bought a file name and nothing else. The chapter now states the rule for both lanes with the leaf identifier as the only difference:

The module name is the root. Each directory below the group's base extends the namespace. The leaf identifier is decided by the lane: the data lane derives it from the file name, because a payload has no name of its own; 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 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. So the chapter that described it was the one whose reader does not use it. 31 keeps 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 explained in the chapter that row points at rather than named in a table cell -- it appeared four times in docs/ before this, all inside one table row and one index line.

Examples

boundary/ gains a second island one directory deeper, because the namespace mirroring the tree is what the example exists to show, and it takes strip_prefix -- it is the one example whose consumer writes a boundary name directly:

import boundary.kernels;

boundary::kernels::saxpy(2.0f, x, y, out, 4);   // short spelling of boundary_saxpy
boundary::kernels::vec::scale(0.5f, out, 4);    // one directory deeper

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.2, so one version of the package is resolved across the tree.

Three releases, and why there are three

0.5.0 carried the design. 0.5.1 added the refusal of overlapping roots that the design record states and 0.5.0 shipped without -- a requirement folded into a larger change, gone when that change shipped, because §6 stated it in prose and the criteria table gave it none. 0.5.2 fixed a defect that the first cross-platform run of the generator's fixture found: namespace_of trimmed a base directory as a string, and on Windows a root written 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. 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.

Measured

Against the released mcpp 2026.9.8.1, resolving mcpp:plugins through the index:

boundary	6 12 18 24; nm shows one boundary_saxpy and no saxpy, so the short name costs the artifact nothing
boundary, generated module	export namespace boundary::kernels and export namespace boundary::kernels::vec
cuda, device leg on an RTX 4080	12 24 36 48, device: NVIDIA GeForce RTX 4080 -- island plus CUDA with the namespaced boundary, which no CI job covers
cuda --no-accel, sycl --no-accel	12 24 36 48, device: cpu (this build names no accelerator)
a fresh project in an xlings subos --sandbox, CN mirror	resolved registry/data/xpkgs/mcpp-x-plugins/0.5.2 from the index, printed 6 12 18 24, and the published generator refused overlapping roots naming both
check_docs_structure.sh, check_docs_style.sh, check_version_pins.sh, e2e 616	pass

The generator's own eleven criteria are in mcpp-plugins#13, #14 and #15, and run on Linux, macOS and Windows.