feat(example): the CUDA example takes its toolkit from a payload, not from the host

The example shipped in 2026.9.5.1 wrote `-L/usr/local/cuda/lib64` in its
manifest and probed `/usr/local/cuda/bin/nvcc` and `/usr/include/crt/host_config.h`
in its rule package. It was the project's own demonstration of how to do this,
and what it demonstrated was reaching for the host.

The project now names the toolkit:

    [xlings.workspace]
    "xim:cuda-nvcc"   = "12.9.86"
    "xim:cuda-cudart" = "12.9.79"

and the rule resolves it with `mcpp::xpkg_dir`, building the whole invocation
from what it finds — compiler, include directories, and library search paths
through `mcpp::link_search`. The manifest names libraries and no locations.
Host paths remain in the rule as a last fallback so a machine with only a
distribution toolkit still builds.

⚠️ THE PAYLOAD'S HEADERS HAVE TO BE NAMED. nvcc adds
`<its own directory>/../include` by itself, and on the 12.x line that holds
`crt/` but not `cuda_runtime.h` — which is in the `cuda-cudart` component. The
first revision of this change left it out: nvcc resolved `cuda_runtime.h` from
/usr/include and then read the HOST's `crt/host_config.h` beside it, and the
build failed with the host toolkit's complaint (`clang version must be less than
15`) while using the payload's compiler. Naming the payload include directories
is what makes "uses the payload" true rather than nearly true.

Verified: `mcpp run` prints `12 24 36 48`, and

    $ mcpp build -v | grep -c '/usr/local/cuda\|/usr/bin/nvcc|-I/usr/include'
    0

nvcc and both include directories resolve under
`registry/data/xpkgs/xim-x-cuda-*`. 100 test binaries pass.

Author: speak-agent

examples/09-cuda-kernel/README.md

@@ -35,21 +35,52 @@ fallback without any consumer of `app.saxpy` changing, and the one place a
 `cfg(accelerator = ...)` section has to apply. Remove it and every importer
 becomes backend-specific.
 
+## Where the toolkit comes from
+
+The project names it:
+
+```toml
+[xlings.workspace]
+"xim:cuda-nvcc"   = "12.9.86"
+"xim:cuda-cudart" = "12.9.79"
+```
+
+These are payloads, so the version is the project's choice and not the machine's.
+The rule package resolves them with `mcpp::xpkg_dir` and builds the whole
+invocation from what it finds — the compiler, the include directories and the
+library search paths. **No path in this example is absolute**, and a build here
+touches nothing of the host's CUDA:
+
+```
+$ mcpp build -v | grep -c '/usr/local/cuda\|/usr/bin/nvcc'
+0
+```
+
+Host locations remain in the rule as a last fallback, so a machine that has only
+a distribution toolkit still builds. They are a fallback, not the design.
+
+⚠️ **The payload's headers have to be named.** nvcc adds
+`<its own directory>/../include` by itself, and on the 12.x line that holds
+`crt/` but not `cuda_runtime.h` — which lives in the `cuda-cudart` component. An
+earlier revision of this rule left it out, and nvcc resolved `cuda_runtime.h`
+from `/usr/include` and then read the **host's** `crt/host_config.h` beside it.
+The build failed with the host toolkit's complaint while using the payload's
+compiler.
+
 ## The rule package, and why nvcc's host compiler is its problem
 
 nvcc refuses host compilers newer than a bound it states in its own
 `crt/host_config.h`, and mcpp's toolchain payload is routinely newer than that
-bound. The rule reads the bound, selects a host compiler that satisfies it, and
-says which one it chose:
+bound. The rule reads the bound — from the payload, which states a newer one
+than a distribution toolkit does — selects a host compiler that satisfies it,
+and says which one it chose:
 
 ```
-example.rules.cuda: nvcc /usr/bin/nvcc with -ccbin /usr/bin/clang++-14
+example.rules.cuda: nvcc …/xpkgs/xim-x-cuda-nvcc/12.9.86/bin/nvcc with -ccbin …
 ```
 
-On the machine this example was verified on, the toolkit is CUDA 12.0
-(`__GNUC__ > 12` is refused, clang must be below 15) and mcpp's payload is gcc
-16.1.0, so passing mcpp's own compiler through would fail. `mcpp self doctor`
-reports the same pairing independently.
+`mcpp self doctor` reports the same pairing independently, and reads the same
+payload.
 
 Everything about nvcc's spelling lives in the rule package. The engine owns the
 graph, the artifact's identity and the architecture set; it does not own

examples/09-cuda-kernel/app/mcpp.toml

@@ -29,7 +29,19 @@ cuda-runtime = "2026.09.05"
 # mcpp a path it can put on the artifact's runtime search path — mcpp's private
 # loader does not consult /usr/lib, so without this the statically linked CUDA
 # runtime cannot dlopen the driver and reports it as missing.
+# The toolkit this project builds with, named rather than discovered.
+#
+# ⭐ These are PAYLOADS, so the version is the project's choice and not the
+# machine's. The 12.9 line is named on purpose: a runtime must not be newer than
+# the driver it will meet, and 12.x reaches every driver from r525 onward.
+# `mcpp self doctor` reports the pairing.
+#
+# The 12.x `cuda-nvcc` carries its own NVVM back end; on the 13.x line that is a
+# separate `libnvvm` alongside `cuda-crt`, and `cuda-nvcc`'s install hook brings
+# them. Either way the project names the compiler and gets a working one.
 [xlings.workspace]
+"xim:cuda-nvcc"         = "12.9.86"
+"xim:cuda-cudart"       = "12.9.79"
 "xim:libcuda-host-link" = { linux = "0.0.1" }
 
 [build]
@@ -39,10 +51,14 @@ cuda-runtime = "2026.09.05"
 # redistributable half in leaves exactly one host dependency, libcuda.so.1,
 # which is the driver and genuinely cannot be redistributed — that is what the
 # libcuda-host-link sentinel package in xim exists for.
-accel    = "cuda12.0+{sm_89} ptx>=89"
+accel    = "cuda12.9+{sm_89} ptx>=89"
 include_dirs = ["include"]
-ldflags  = ["-L/usr/local/cuda/lib64", "-L/usr/lib/x86_64-linux-gnu",
-            "-lcudart_static", "-lrt", "-lpthread", "-ldl"]
+# ⭐ NO ABSOLUTE PATHS. The CUDA runtime comes from the `cuda-cudart` payload
+# named above, and the rule package puts its library directory on the link line
+# from `mcpp::xpkg_dir` -- so this manifest names libraries, never locations.
+# The one host component left is `libcuda.so.1`, which the driver owns and the
+# `compat.cuda-runtime` dependency reaches.
+ldflags  = ["-lcudart_static", "-lrt", "-lpthread", "-ldl"]
 
 [targets.cuda-saxpy]
 kind = "bin"

examples/09-cuda-kernel/rules-cuda/src/rules-cuda.cppm

@@ -56,8 +56,29 @@ inline std::string first_existing(std::span<const std::string> candidates) {
     return {};
 }
 
+// The toolkit directory this project declared, or empty.
+//
+// ⭐ PAYLOAD FIRST, AND THE PROJECT NAMES IT. `mcpp::xpkg_dir` answers for a
+// package the manifest declared under `[xlings.workspace]`, which is how a
+// build says which toolkit it wants instead of taking whichever one a machine
+// happens to have. The 13.x line splits the compiler across components, so the
+// pieces are looked up separately and joined here.
+inline std::vector<std::string> payload_roots() {
+    std::vector<std::string> out;
+    for (const char* name : { "cuda-nvcc", "cuda-crt", "cuda-cudart" })
+        if (const char* d = mcpp::xpkg_dir("xim", name); d && *d)
+            out.emplace_back(d);
+    return out;
+}
+
 inline std::string find_nvcc() {
     std::vector<std::string> c;
+    for (auto const& r : payload_roots()) c.push_back(r + "/bin/nvcc");
+    // ⚠️ HOST LOCATIONS ARE LAST AND ARE A FALLBACK, NOT THE DESIGN. A project
+    // that declares the payload gets a toolkit whose version it chose and whose
+    // host-compiler bound is far newer -- 12.9 accepts gcc 14 and 13.3 accepts
+    // gcc 15, where a distribution's CUDA 12.0 stops at 12. These entries exist
+    // so a machine that has only a distribution toolkit still builds.
     for (const char* var : { "CUDA_PATH", "CUDA_HOME" })
         if (const char* v = std::getenv(var)) c.push_back(std::string(v) + "/bin/nvcc");
     c.push_back("/usr/local/cuda/bin/nvcc");
@@ -67,6 +88,9 @@ inline std::string find_nvcc() {
 
 inline std::string find_host_config(std::string_view nvcc) {
     std::vector<std::string> c;
+    // 13.x moved this header into its own component, so the payload that has it
+    // is not necessarily the one that has nvcc.
+    for (auto const& r : payload_roots()) c.push_back(r + "/include/crt/host_config.h");
     if (!nvcc.empty()) {
         std::filesystem::path p{std::string(nvcc)};
         c.push_back((p.parent_path().parent_path() / "include/crt/host_config.h").string());
@@ -152,6 +176,24 @@ inline std::vector<edge> plan(std::span<const std::string> sources, options opt
     }
     std::println("example.rules.cuda: nvcc {} with -ccbin {}", nvcc, ccbin);
 
+    // ⭐ THE LINK LINE GETS ITS DIRECTORIES FROM HERE, NOT FROM THE MANIFEST.
+    //
+    // A manifest that writes `-L/usr/local/cuda/lib64` has decided where the
+    // toolkit is, which is the machine's business and not the project's. The
+    // rule knows: it just resolved the payload, and it puts that payload's
+    // library directory on the link line. The manifest names libraries only.
+    //
+    // Emitted for every payload root, because the 13.x line splits the runtime
+    // out of the compiler and a build may hold both.
+    for (auto const& r : payload_roots()) {
+        auto lib = r + "/lib";
+        if (std::filesystem::is_directory(lib)) mcpp::link_search(lib.c_str());
+        // Some components ship `lib64` instead; naming both costs nothing and
+        // guessing wrong costs a link error that names a symbol.
+        auto lib64 = r + "/lib64";
+        if (std::filesystem::is_directory(lib64)) mcpp::link_search(lib64.c_str());
+    }
+
     for (auto const& src : sources) {
         const auto stem = std::filesystem::path(src).stem().string();
         const auto obj  = opt.out_dir + "/" + stem + ".cu.o";
@@ -161,6 +203,19 @@ inline std::vector<edge> plan(std::span<const std::string> sources, options opt
         e.command     = { nvcc, "-c", root + "/" + src, "-o", obj,
                           "-ccbin", ccbin, "-std=c++17", "-O2",
                           "--compiler-options", "-fPIC" };
+        // ⚠️ THE PAYLOAD'S OWN HEADERS MUST BE NAMED, OR nvcc FINDS THE HOST'S.
+        //
+        // nvcc adds `<its own dir>/../include` automatically, and on the 12.x
+        // line that directory holds `crt/` but NOT `cuda_runtime.h` -- that
+        // lives in the `cuda-cudart` component. Without these flags nvcc
+        // resolved `cuda_runtime.h` from /usr/include and then read the HOST's
+        // `crt/host_config.h` beside it, which on this machine states a bound
+        // three major versions older than the payload's. The build failed with
+        // the host toolkit's complaint while using the payload's compiler.
+        for (auto const& r : payload_roots()) {
+            auto inc = r + "/include";
+            if (std::filesystem::is_directory(inc)) e.command.push_back("-I" + inc);
+        }
         for (auto const& inc : opt.includes)
             e.command.push_back("-I" + root + "/" + inc);
         for (auto const& a : opt.archs) {