feat: refuse a prebuilt artifact whose device code cannot run on the target

This is the failure the whole dimension exists to move. A library built for one
compute capability and consumed by a build targeting another linked cleanly and
failed at the first kernel launch, with a runtime message that names neither
the package nor the architecture either side expected.

The refusal now names both, and the remedy is the one that can work. The
generic advice to pin [toolchain] is actively misleading on this axis, because
no toolchain pin changes which GPU architecture a build targets; the device
case offers --accel and --no-accel instead. The published listing carries the
dimension too, since it travels beside the tag rather than inside it and a
listing showing only tags would print two indistinguishable lines for a package
publishing a CPU and a device build of one triple.

Observed:

    error: mcpplibs.gpuonly@0.1.0: no prebuilt artifact matches this toolchain.
      your toolchain : x86_64-linux-gnu-gcc16-libstdcxx16-c++23  accel=cuda12.8+{sm_86}
      published tags :
                       x86_64-linux-gnu  accel=cuda12.8+{sm_90f}
      closest is x86_64-linux-gnu, and it differs on:
        accel     needs cuda12.8+{sm_90f}, this build has cuda12.8+{sm_86}

The accompanying end-to-end test also covers the ordering rule: a descriptor
listing its CPU-only artifact first lets a build targeting an architecture no
device variant carries fall back to the portable one, which is the same
ordering that keeps an mcpp predating this field selecting a usable artifact.

Author: speak-agent

modules/manifest/src/toml.cppm

@@ -1905,8 +1905,15 @@ std::expected<Manifest, ManifestError> parse_string(std::string_view content,
             std::string path;
             auto const& table = value.as_table();
             for (auto const& [key, _] : table) {
+                // ⚠️ A CLOSED whitelist: an unrecognised key is an error here,
+                // unlike the published xpkg descriptor, whose reader collects
+                // and skips one. The two readers differ on purpose — a typo in
+                // a hand-written manifest should be loud — but it means adding
+                // a key to THIS table is a compatibility event: an mcpp that
+                // predates the key refuses the whole manifest rather than
+                // ignoring the field. See the accelerator design's RK-2.
                 if (key != "role" && key != "path" && key != "provenance"
-                    && key != "abi" && key != "digest"
+                    && key != "abi" && key != "accel" && key != "digest"
                     && key != "host_fingerprint") {
                     return std::unexpected(error(origin, std::format(
                         "runtime.artifacts[{}] has unsupported key '{}'",
@@ -1917,6 +1924,7 @@ std::expected<Manifest, ManifestError> parse_string(std::string_view content,
                 || !table_string(table, "path", path)
                 || !table_string(table, "provenance", artifact.provenance)
                 || !table_string(table, "abi", artifact.abi)
+                || !table_string(table, "accel", artifact.accel)
                 || !table_string(table, "digest", artifact.digest)
                 || !table_string(table, "host_fingerprint",
                                  artifact.hostFingerprint)) {

src/pack/prebuilt.cppm

@@ -104,7 +104,12 @@ check_prebuilt(const mcpp::manifest::Manifest& m, const PrebuiltCheck& in)
             accepted = true;
             continue;
         }
-        publishedTags.push_back(a.abi);
+        // The device dimension is not part of the tag string, so a listing
+        // that printed only the tag would show two indistinguishable lines for
+        // a package publishing a CPU and a device build of the same triple.
+        publishedTags.push_back(a.accel.empty()
+                                    ? a.abi
+                                    : std::format("{}  accel={}", a.abi, a.accel));
         auto published = parse_abi_tag(a.abi);
         if (!published) { accepted = true; continue; }   // unreadable → lenient
         // The device dimension travels beside the tag rather than inside it.
@@ -123,16 +128,35 @@ check_prebuilt(const mcpp::manifest::Manifest& m, const PrebuiltCheck& in)
         std::string tags;
         for (auto const& t : publishedTags) tags += std::format("\n                   {}", t);
         std::string why;
-        for (auto const& b : bestRefusal)
+        bool accelOnly = !bestRefusal.empty();
+        for (auto const& b : bestRefusal) {
             why += std::format("\n    {:<9} needs {}, this build has {}", b.dimension, b.need, b.got);
+            if (b.dimension != "accel") accelOnly = false;
+        }
+        // The remedy differs by dimension, and the generic one is actively
+        // misleading for the device axis: pinning [toolchain] cannot change
+        // which GPU architecture a build targets.
+        const std::string fix = accelOnly
+            ? std::string(
+                "  fix: build for an architecture the package carries (--accel), or take\n"
+                "       a variant that carries no device code (--no-accel), or ask the\n"
+                "       publisher for one covering yours.")
+            : std::string(
+                "  fix: ask the publisher for a build matching your toolchain, or pin\n"
+                "       [toolchain] to the one the package was built with.");
+        // The device dimension travels beside the tag, so the summary line has
+        // to name it too or it contradicts the per-dimension list below.
+        const std::string current = in.current.accel.empty()
+            ? in.current.str()
+            : std::format("{}  accel={}", in.current.str(),
+                          accel_str(in.current.accel));
         return std::unexpected(std::format(
             "{}: no prebuilt artifact matches this toolchain.\n"
             "  your toolchain : {}\n"
             "  published tags :{}\n"
             "  closest is {}, and it differs on:{}\n"
-            "  fix: ask the publisher for a build matching your toolchain, or pin\n"
-            "       [toolchain] to the one the package was built with.",
-            in.packageLabel, in.current.str(), tags, bestRefusalTag, why));
+            "{}",
+            in.packageLabel, current, tags, bestRefusalTag, why, fix));
     }
 
     // ── 3. the interface is the one the binaries were built from ──────

tests/e2e/600_accel_variant_selection.sh

@@ -0,0 +1,114 @@
+#!/usr/bin/env bash
+# requires: elf
+# The accelerator dimension decides which prebuilt artifact a build may take.
+#
+# Two packages, because the two halves of the rule need different shapes:
+#
+#   gpuonly  publishes ONE artifact, for sm_90f. A build targeting sm_86 has
+#            nothing it can use, so it must be refused — and the refusal must
+#            name the dimension, not a digest or a triple.
+#   gpukit   publishes a CPU-only artifact FIRST and a device one after it.
+#            The same sm_86 build must succeed by taking the first, which is
+#            the ordering that also keeps an mcpp predating this field working.
+set -e
+
+TMP=$(mktemp -d)
+trap "rm -rf $TMP" EXIT
+cd "$TMP"
+
+TRIPLE="x86_64-linux-gnu"
+
+make_pkg() {                     # $1 name, $2... artifact tables
+    local name="$1"; shift
+    mkdir -p "$name/lib" "$name/include"
+    : > "$name/lib/lib${name}.a"
+    {
+        echo '[package]'
+        echo "name    = \"$name\""
+        echo 'version = "0.1.0"'
+        echo '[language]'
+        echo 'standard = "c++23"'
+        printf '%s\n' "$@"
+    } > "$name/mcpp.toml"
+}
+
+# One device-only artifact.
+make_pkg gpuonly \
+'[[runtime.artifacts]]' \
+'role       = "static-library"' \
+'path       = "lib/libgpuonly.a"' \
+'provenance = "mcpp-pack/1"' \
+"abi        = \"$TRIPLE\"" \
+'accel      = "cuda12.8+{sm_90f}"'
+
+# CPU-only first, device second.
+make_pkg gpukit \
+'[[runtime.artifacts]]' \
+'role       = "static-library"' \
+'path       = "lib/libgpukit.a"' \
+'provenance = "mcpp-pack/1"' \
+"abi        = \"$TRIPLE\"" \
+'' \
+'[[runtime.artifacts]]' \
+'role       = "static-library"' \
+'path       = "lib/libgpukit.a"' \
+'provenance = "mcpp-pack/1"' \
+"abi        = \"$TRIPLE\"" \
+'accel      = "cuda12.8+{sm_90f}"'
+
+consumer() {                     # $1 dep name
+    rm -rf app; "$MCPP" new app > /dev/null; cd app
+    cat > mcpp.toml <<EOF
+[package]
+name    = "app"
+version = "0.1.0"
+[language]
+standard = "c++23"
+[dependencies]
+$1 = { path = "../$1" }
+EOF
+    cat > src/main.cpp <<'EOF'
+int main() { return 0; }
+EOF
+    rm -f src/*.cppm
+    cd ..
+}
+
+# ── 1. a device-only package refuses a build targeting another architecture ──
+consumer gpuonly
+cd app
+if "$MCPP" build --accel 'cuda12.8+{sm_86}' > out.log 2>&1; then
+    cat out.log; echo "FAIL: sm_86 accepted an sm_90f-only artifact"; exit 1
+fi
+grep -q 'accel' out.log || { cat out.log; echo "FAIL: refusal does not name the accel dimension"; exit 1; }
+grep -q 'sm_90f' out.log || { cat out.log; echo "FAIL: refusal does not say what the artifact has"; exit 1; }
+grep -q 'sm_86'  out.log || { cat out.log; echo "FAIL: refusal does not say what this build asked for"; exit 1; }
+# The remedy has to be the one that can actually work. Pinning [toolchain]
+# cannot change which GPU architecture a build targets, so the generic advice
+# is worse than none here.
+grep -q -- '--no-accel' out.log \
+    || { cat out.log; echo "FAIL: refusal offers no remedy for the device axis"; exit 1; }
+grep -q 'accel=cuda12.8+{sm_90f}' out.log \
+    || { cat out.log; echo "FAIL: the published listing hides the device dimension"; exit 1; }
+cd ..
+
+# ── 2. the same package accepts the architecture it was built for ────────────
+cd app
+"$MCPP" build --accel 'cuda12.8+{sm_90}' > ok.log 2>&1 \
+    || { cat ok.log; echo "FAIL: sm_90 refused by an sm_90f artifact"; exit 1; }
+cd ..
+
+# ── 3. a build asking for no accelerator is satisfied vacuously ──────────────
+cd app
+"$MCPP" build --no-accel > none.log 2>&1 \
+    || { cat none.log; echo "FAIL: --no-accel refused"; exit 1; }
+cd ..
+
+# ── 4. CPU-first ordering lets an unmatched device build fall back ───────────
+consumer gpukit
+cd app
+"$MCPP" build --accel 'cuda12.8+{sm_86}' > fallback.log 2>&1 \
+    || { cat fallback.log; echo "FAIL: CPU-only artifact listed first did not accept sm_86"; exit 1; }
+cd ..
+
+echo "PASS: accel variant selection"