feat(doctor): read the device toolkit from a payload before the host, and state the driver relation without probing for it

## The report was answering about the wrong toolkit

`mcpp self doctor` located `crt/host_config.h` through `CUDA_PATH`, `CUDA_HOME`,
`/usr/local/cuda` and `/usr/include` — host locations only. A toolkit installed
through xlings is the one a build will use, and it is usually the newer one:
measured here, a 12.9 payload states `gcc <= 14` and a 13.3 payload `gcc <= 15`,
where this machine's distribution CUDA 12.0 states `gcc <= 12`. The report said
`gcc 13 exceeds the bound of 12` about a toolkit the build was not using.

Payload stores are now searched first. Both of them: mcpp keeps its own under
`<mcpp home>/registry/data/xpkgs`, and `xlings install` writes to
`<xlings home>/data/xpkgs` — 191 packages in one and 211 in the other on this
machine, with the CUDA components only in the second. The host locations remain,
last, because a machine with a distribution toolkit and no payload is real.

Reading changes accordingly:

    before   warning: cuda will refuse this host compiler: gcc 13 exceeds
                      the bound of 12 stated in /usr/include/crt/host_config.h
    after    ok       cuda accepts this host compiler (gcc 13 <= 15)

## The driver relation, and why the acquisition is not here

A device runtime must not be newer than the driver it runs against. Measured on
a driver serving CUDA 12.4: the 13.3 payload compiles and links cleanly and then
fails at the first allocation with "CUDA driver version is insufficient for CUDA
runtime version", while the 12.9 payload prints the right answer.

`mcpp::toolchain::driver_accepts_toolkit` states when one version may meet
another, including that minor-version compatibility makes 12.9 fine against a
driver serving 12.4 — the case a naive "toolkit <= driver" check would have
refused. Five unit tests, including that either side unknown makes no claim.

The acquisition is NOT here. Asking a machine which driver it has means running
a vendor's tool, and `tests/unit/test_runtime_contract.cpp` refuses exactly that
in `src/`. It caught the first revision of this change, which launched one. The
rule predates this work and it is right: a core that learns to run one vendor's
probe learns to run four. Those numbers will reach the report as declarations —
a toolkit payload stating the driver it needs, and the package that owns the
host driver stating what the host has — which is the rule-package channel.

## Verified

`tests/e2e/602_device_toolkit_payload_first.sh` fabricates a payload store whose
header states `gcc <= 41`, a bound nothing real would state, and asserts the
report reads it. The control is the half that matters: without the payload store
the same command must not report 41, or the assertion would pass against a
doctor that hardcoded it.

100 test binaries pass, including the contract test that rejected the earlier
revision.

Author: speak-agent

docs/20-accelerators.md

@@ -85,6 +85,24 @@ The bound is read from the toolkit rather than tabulated in mcpp, so a toolkit
 mcpp has never seen still answers, and a header mcpp cannot parse yields no
 bound and therefore no claim.
 
+**A payload is read before the host.** A toolkit installed through xlings is the
+one a build will use, and it is usually the newer one: a 12.9 payload states
+`gcc <= 14` and a 13.3 payload `gcc <= 15`, where a distribution's CUDA 12.0
+states `gcc <= 12`. Both package stores are searched — mcpp's own and the one
+`xlings install` writes to — and the host's locations remain, last, because a
+machine with a distribution toolkit and no payload is a real configuration.
+
+**What is not checked here, and why.** A device runtime must not be newer than
+the driver it runs against; when it is, the build compiles and links cleanly and
+fails at the first allocation with *"CUDA driver version is insufficient for
+CUDA runtime version"*. mcpp knows the relation — `driver_accepts_toolkit`
+states when one version may meet another, including that minor-version
+compatibility means a 12.9 runtime is fine on a driver serving 12.4 — but it
+does not ask the machine which driver it has, because asking means running a
+vendor's tool and the engine owns no vendor probes. Those numbers reach the
+report as declarations instead: a toolkit payload states the driver it needs,
+and the package that owns the host driver states what the host has.
+
 This is reported rather than enforced: a project that compiles no device code
 is unaffected by an incompatible pair.
 

docs/zh/20-accelerators.md

@@ -67,6 +67,20 @@ warning: cuda will refuse this host compiler: gcc 13 exceeds the bound of 12
 上界是从工具包读出的,不是抄在 mcpp 里的表,因此一个 mcpp 从未见过的工具包同样能作答;
 而一个 mcpp 无法解析的头文件产生不出上界,也就不产生任何断言。
 
+**载荷先于 host 被读取。** 经 xlings 装的工具包才是构建会用的那个,而且通常更新:
+12.9 载荷声明 `gcc <= 14`、13.3 载荷声明 `gcc <= 15`,而发行版的 CUDA 12.0 声明
+`gcc <= 12`。两个包 store 都会搜 —— mcpp 自己的,以及 `xlings install` 写入的那个;
+host 的位置保留在最后,因为「有发行版工具包、没有载荷」是一种真实配置。
+
+**这里不检查什么,以及为什么。** 设备运行时不得比它将运行于其上的驱动更新;
+更新时构建**干净地编译并链接**,却在第一次分配时失败,报
+*"CUDA driver version is insufficient for CUDA runtime version"*。
+mcpp 知道这个关系 —— `driver_accepts_toolkit` 陈述一个版本何时可以遇上另一个,
+包括「小版本兼容」意味着 12.9 的运行时在只服务到 12.4 的驱动上没问题 ——
+但它**不去问机器装的是哪个驱动**,因为问就意味着运行一个厂商的工具,而引擎不持有
+任何厂商探针。那两个数字改以**声明**的形式抵达:工具包载荷声明它需要的驱动,
+持有宿主驱动的那个包声明宿主有什么。
+
 这是报告而非强制:一个不编译任何设备代码的工程,不受不兼容配对的影响。
 
 ## 设备编译器能否够到自己的后端

src/doctor.cppm

@@ -655,8 +655,55 @@ export int doctor_report() {
     // code is unaffected by an incompatible pair, and refusing its build would
     // be a false alarm.
     if (!mcpp::platform::is_windows) {
+        // ⭐ PAYLOADS BEFORE THE HOST, AND THE ORDER IS THE POINT.
+        //
+        // A toolkit installed through xlings is the one a build will use, and
+        // it is also the newer one: measured on this machine, the payload's own
+        // `crt/host_config.h` states gcc<=15 where the distribution's CUDA 12.0
+        // states gcc<=12. Reporting the host's bound while the build uses the
+        // payload's would answer a question nobody asked.
+        //
+        // The host entries stay, last, because a machine with a distribution
+        // toolkit and no payload is a real configuration and reporting nothing
+        // there would be worse than reporting its bound.
+        auto payload_roots = [] {
+            std::vector<std::filesystem::path> out;
+            std::error_code ec;
+            // `cuda-crt` carries the header in 13.x; in 12.x `cuda-nvcc`
+            // carries it. Both are scanned, newest version directory first --
+            // string order is right here because upstream pads nothing.
+            // ⚠️ TWO STORES, AND A PAYLOAD MAY BE IN EITHER. mcpp keeps its own
+            // under `<mcpp home>/registry/data/xpkgs`; a package installed with
+            // `xlings install` lands in `<xlings home>/data/xpkgs`. Measured on
+            // this machine: 191 packages in one and 211 in the other, with the
+            // CUDA components only in the second. Scanning one of them reports
+            // the host's toolkit while the build uses the payload's.
+            std::vector<std::filesystem::path> stores{
+                mcpp::home::root() / "registry" / "data" / "xpkgs"};
+            {
+                std::string xhome;
+                if (const char* p = std::getenv("XLINGS_HOME")) xhome = p;
+                else if (const char* h = std::getenv("HOME"))
+                    xhome = std::string(h) + "/.xlings";
+                if (!xhome.empty())
+                    stores.push_back(std::filesystem::path(xhome) / "data" / "xpkgs");
+            }
+            for (auto const& store : stores)
+            for (auto const* pkg : {"xim-x-cuda-crt", "xim-x-cuda-nvcc",
+                                    "local-x-cuda-crt", "local-x-cuda-nvcc"}) {
+                auto dir = store / pkg;
+                if (!std::filesystem::is_directory(dir, ec)) continue;
+                std::vector<std::filesystem::path> versions;
+                for (auto& v : std::filesystem::directory_iterator(dir, ec))
+                    if (v.is_directory(ec)) versions.push_back(v.path());
+                std::ranges::sort(versions, std::ranges::greater{});
+                for (auto& v : versions) out.push_back(v);
+            }
+            return out;
+        }();
+
         auto header = [&]() -> std::optional<std::filesystem::path> {
-            std::vector<std::filesystem::path> roots;
+            std::vector<std::filesystem::path> roots = payload_roots;
             if (const char* p = std::getenv("CUDA_PATH")) roots.emplace_back(p);
             if (const char* p = std::getenv("CUDA_HOME")) roots.emplace_back(p);
             roots.emplace_back("/usr/local/cuda");
@@ -728,6 +775,34 @@ export int doctor_report() {
             //
             // Asked rather than assumed: `--dryrun` prints the plan without
             // running it, so the answer is nvcc's own.
+            // ── The driver this toolkit will meet ──────────────────────
+            //
+            // A device runtime must not be newer than the driver it runs
+            // against, and the failure when it is comes at the FIRST
+            // ALLOCATION, after a clean compile and a clean link. Measured
+            // 2026-09-05 on a driver serving CUDA 12.4: the 13.3 payload builds
+            // cleanly and then reports "CUDA driver version is insufficient for
+            // CUDA runtime version", while the 12.9 payload prints the right
+            // answer.
+            //
+            // ⚠️ THE RELATION IS HERE; THE ACQUISITION IS NOT, AND THAT IS
+            // DELIBERATE. `mcpp::toolchain::driver_accepts_toolkit` states when
+            // one version may meet another and is unit-tested. Asking a machine
+            // which driver it has means running a vendor's tool, and
+            // `tests/unit/test_runtime_contract.cpp` refuses exactly that in
+            // `src/` -- it caught the first revision of this check, which
+            // launched one. The rule is the repository's, it predates this
+            // work, and it is right: a core that learns to run one vendor's
+            // probe learns to run four.
+            //
+            // The numbers reach this report through declarations instead: a
+            // toolkit payload states the driver it needs, and the package that
+            // owns the host driver states what the host has. Both are ordinary
+            // manifest data. Wiring that is the rule-package channel, and until
+            // it exists this section reports the pairing it can already read --
+            // the host compiler bound above -- and says nothing about a driver
+            // rather than guessing at one.
+
             if (auto missing = unreachable_device_stage(); missing) {
                 warn(std::format(
                     "nvcc cannot reach its own back-end: it invokes '{}' by "

src/toolchain/devicehost.cppm

@@ -73,6 +73,51 @@ DeviceDryRun parse_dryrun(std::string_view text);
 bool host_compiler_accepted(const HostCompilerBounds& b,
                             std::string_view family, int major);
 
+// ── The driver a device runtime will meet ──────────────────────────────────
+//
+// A device runtime must not be NEWER than the driver it runs against, and the
+// driver is the one component that cannot be redistributed: it is in ABI
+// lockstep with a kernel module. So the toolkit version a build uses is bounded
+// by a fact about the machine, and that fact is knowable before anything is
+// compiled.
+//
+// ⚠️⚠️ MEASURED, 2026-09-05, on a host whose driver reports CUDA 12.4: a
+// binary built with the 13.3 payload COMPILES AND LINKS CLEANLY and then fails
+// at the first allocation with
+//
+//     cudaMalloc: CUDA driver version is insufficient for CUDA runtime version
+//
+// while the same source built with the 12.9 payload prints the right answer.
+// Everything that could have caught it earlier was silent -- which is the whole
+// reason this is checked rather than left to happen.
+//
+// ⭐ The comparison is separated from the acquisition on purpose. Which
+// function asks the driver its version is a vendor's business and belongs to a
+// rule package; whether one version may meet another is a relation, and that
+// is what lives here.
+
+// A dotted version reduced to (major, minor). Absent or unreadable parts are
+// zero, which makes an unreadable version compare as older rather than as a
+// refusal.
+struct DeviceVersion {
+    int major = 0;
+    int minor = 0;
+    bool known() const { return major != 0; }
+};
+
+DeviceVersion parse_device_version(std::string_view text);
+
+// May a runtime built against `toolkit` run on a machine whose driver supports
+// up to `driver`?
+//
+// The rule is minor-version compatibility, which is the vendor's and not
+// invented here: within one major version an application built against any
+// minor runs on a driver supporting that major. Across majors it does not.
+//
+// ⚠️ Either side unknown yields TRUE. A check that cannot reach an answer must
+// not manufacture a refusal -- the same rule the host-compiler bound follows.
+bool driver_accepts_toolkit(DeviceVersion toolkit, DeviceVersion driver);
+
 } // namespace mcpp::toolchain
 
 namespace mcpp::toolchain {
@@ -161,6 +206,35 @@ DeviceDryRun parse_dryrun(std::string_view text) {
     return plan;
 }
 
+DeviceVersion parse_device_version(std::string_view text) {
+    DeviceVersion v;
+    std::size_t i = 0;
+    while (i < text.size() && !std::isdigit(static_cast<unsigned char>(text[i]))) ++i;
+    int  acc = 0;
+    bool any = false;
+    for (; i < text.size() && std::isdigit(static_cast<unsigned char>(text[i])); ++i) {
+        acc = acc * 10 + (text[i] - '0');
+        any = true;
+    }
+    if (!any) return v;
+    v.major = acc;
+    if (i < text.size() && text[i] == '.') {
+        ++i;
+        acc = 0;
+        for (; i < text.size() && std::isdigit(static_cast<unsigned char>(text[i])); ++i)
+            acc = acc * 10 + (text[i] - '0');
+        v.minor = acc;
+    }
+    return v;
+}
+
+bool driver_accepts_toolkit(DeviceVersion toolkit, DeviceVersion driver) {
+    if (!toolkit.known() || !driver.known()) return true;   // no claim
+    if (toolkit.major != driver.major) return toolkit.major < driver.major;
+    // Same major: minor-version compatibility covers it.
+    return true;
+}
+
 bool host_compiler_accepted(const HostCompilerBounds& b,
                             std::string_view family, int major)
 {

tests/e2e/602_device_toolkit_payload_first.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# The device-toolkit report reads a PAYLOAD before it reads the host.
+#
+# A toolkit installed through xlings is the one a build will use, and it is
+# also the newer one -- measured on the development machine, a payload states
+# `gcc <= 15` where the distribution's CUDA 12.0 states `gcc <= 12`. Reporting
+# the host's bound while the build uses the payload's answers a question nobody
+# asked, and the two answers differ by three major compiler versions.
+#
+# No CUDA is required to assert the ordering: a fabricated `crt/host_config.h`
+# in a fabricated payload directory is enough, because what is under test is
+# which of two files the report reads.
+set -e
+
+TMP=$(mktemp -d)
+trap "rm -rf $TMP" EXIT
+
+# A payload store laid out the way xlings lays one out, holding a header whose
+# bound is one nothing on a real machine would state.
+PAYLOAD="$TMP/xlings/data/xpkgs/local-x-cuda-crt/99.9.99/include/crt"
+mkdir -p "$PAYLOAD"
+cat > "$PAYLOAD/host_config.h" <<'HDR'
+#if __GNUC__ > 41
+#error -- unsupported GNU version! gcc versions later than 41 are not supported!
+#endif
+HDR
+
+out="$TMP/doctor.log"
+XLINGS_HOME="$TMP/xlings" "$MCPP" self doctor > "$out" 2>&1 || true
+
+grep -q "device toolkit" "$out" || { cat "$out"; echo "FAIL: no device toolkit section"; exit 1; }
+
+# The bound reported must be the payload's 41, whatever the host has. On a
+# machine with no CUDA at all this is also the only way the section appears.
+if ! grep -qE "<= ?41|bound of 41" "$out"; then
+    grep -A3 "device toolkit" "$out"
+    echo "FAIL: the report did not read the payload's host_config.h"
+    exit 1
+fi
+echo "PASS: the payload's bound is the one reported"
+
+# The control. Without the payload store, the same command must NOT report 41 --
+# otherwise the assertion above would pass against a doctor that hardcodes it.
+out2="$TMP/doctor2.log"
+XLINGS_HOME="$TMP/empty" "$MCPP" self doctor > "$out2" 2>&1 || true
+if grep -qE "<= ?41|bound of 41" "$out2"; then
+    echo "FAIL: 41 is reported with no payload present; the test measures nothing"
+    exit 1
+fi
+echo "PASS: without the payload the bound is not 41"
+
+echo "PASS: device toolkit payload-first"

tests/unit/test_devicehost.cpp

@@ -147,3 +147,55 @@ TEST(DeviceDryRun, TextThatIsNotAPlanYieldsNoStages) {
     EXPECT_TRUE(plan.programs.empty());
     EXPECT_TRUE(plan.searchPath.empty());
 }
+
+// ── The driver a device runtime will meet ──────────────────────────────────
+//
+// Measured 2026-09-05 on a host whose driver reports CUDA 12.4: a binary built
+// with the 13.3 payload compiles and links cleanly and then fails at the first
+// allocation; the same source built with the 12.9 payload prints the right
+// answer. These assert the relation that turns that into a message before
+// anything is compiled.
+
+using mcpp::toolchain::parse_device_version;
+using mcpp::toolchain::driver_accepts_toolkit;
+
+TEST(DeviceDriver, ReadsAVersionOutOfSurroundingText) {
+    // The two real shapes: `nvcc --version` ends with "release 12.9, V12.9.86",
+    // and `nvidia-smi`'s header carries "CUDA Version: 12.4".
+    auto a = parse_device_version("12.9, V12.9.86");
+    EXPECT_EQ(a.major, 12);
+    EXPECT_EQ(a.minor, 9);
+    auto b = parse_device_version(" 12.4     |");
+    EXPECT_EQ(b.major, 12);
+    EXPECT_EQ(b.minor, 4);
+}
+
+TEST(DeviceDriver, MinorVersionCompatibilityHolds) {
+    // Within one major, any minor runs. This is the vendor's rule, and it is
+    // why the 12.9 payload works against a driver that serves 12.4 -- the case
+    // a naive "toolkit must be <= driver" check would have refused.
+    EXPECT_TRUE(driver_accepts_toolkit(parse_device_version("12.9"),
+                                       parse_device_version("12.4")));
+    EXPECT_TRUE(driver_accepts_toolkit(parse_device_version("12.0"),
+                                       parse_device_version("12.4")));
+}
+
+TEST(DeviceDriver, ANewerMajorIsRefused) {
+    EXPECT_FALSE(driver_accepts_toolkit(parse_device_version("13.3"),
+                                        parse_device_version("12.4")));
+}
+
+TEST(DeviceDriver, AnOlderMajorIsAccepted) {
+    EXPECT_TRUE(driver_accepts_toolkit(parse_device_version("11.8"),
+                                       parse_device_version("12.4")));
+}
+
+TEST(DeviceDriver, EitherSideUnknownMakesNoClaim) {
+    // The same rule the host-compiler bound follows: a check that cannot reach
+    // an answer must not manufacture a refusal. A machine with no driver, or a
+    // toolkit whose version could not be read, is not a machine with a defect.
+    EXPECT_TRUE(driver_accepts_toolkit(parse_device_version("13.3"),
+                                       parse_device_version("no gpu here")));
+    EXPECT_TRUE(driver_accepts_toolkit(parse_device_version(""),
+                                       parse_device_version("12.4")));
+}