the query answers why, and three tests asserted things that were not the claim

`compiler.chosenBy` carries the selection origin into the machine interface:
a consumer asking why a build resolved llvm had to parse the status line, which
is the substring matching that document exists to remove.

Three test defects found by reading, not by failing:

  - the capability-row refusal offered "depend on a package that supplies this
    target's system" — a remedy a capability pin ignores by construction, and
    the sentence directly above it already said so. Split by row kind.
  - 303 read `suppliesTarget` through jq's `//`, which returns its right side
    when the left is null OR FALSE. `false` is an answer; it read as absent,
    and windows-x86_64 reported the field missing when it was there.
  - 281 asserted the old global remedy, which the only refusal that still
    reaches it cannot be fixed by.

303's third half stacks a musl c-abi over the host's own target and not every
host stacks that; granted by reason, with linux-x86_64 as the denominator.

Author: speak-agent

.github/workflows/ci-target-matrix.yml

@@ -188,8 +188,19 @@ jobs:
             "OK: a request that named no C library resolves to a row that exists" || fail=1
           check 300_a_registered_family_is_not_reported_unknown.sh \
             "OK: a registered family is not reported unknown" || fail=1
-          check 303_the_query_gives_one_answer_for_the_c_library.sh \
-            "OK: the query gives one answer for the C library" || fail=1
+          # ⚠️ 303's third half stacks a musl c-abi over this host's own target,
+          # and not every host stacks that — an MSVC-ABI host answers the
+          # layering question first, correctly, and there is then no
+          # two-answer document to check. Granted by reason; linux-x86_64 below
+          # is the denominator that must run the whole file.
+          if [ "${{ matrix.host }}" = linux-x86_64 ]; then
+            check 303_the_query_gives_one_answer_for_the_c_library.sh \
+              "OK: the query gives one answer for the C library" || fail=1
+          else
+            check_or_declared_skip 303_the_query_gives_one_answer_for_the_c_library.sh \
+              "OK: the query gives one answer for the C library" \
+              "refuses a musl c-abi over its own target" || fail=1
+          fi
 
           # ⚠️ 301/302 NEED TWO COMPILER FAMILIES, AND THAT IS A PROPERTY OF THE
           # MACHINE RATHER THAN OF THE CLAIM. "A requirement that DIFFERS from

CHANGELOG.md

@@ -45,6 +45,10 @@
   | 已有 gcc 默认的机器 | 拒绝,要求改全局默认 | 装/用 llvm,`config.toml` 不动 |
   | 什么都没装的机器 | 装 gcc → 持久化 gcc → 再拒绝 | 首次运行分支根本不进,直接装 llvm |
 
+  ⭐ 状态行点名是哪个包要求的、顶掉了什么;`why toolchain --format json` 新增
+  `compiler.chosenBy = {origin, requiredBy, replaced}`,让「为什么是 llvm」不必去
+  解析那行提示 —— 那正是机器接口存在的理由所要消除的字符串匹配。
+
   拒绝只剩一种局面:工程自己在 `[toolchain]` 或 `[target.X]` 写下了相反的编译器。
   ⚠️ 那种局面里全局默认与本次构建无关,因此原来那条 `mcpp toolchain default llvm`
   的建议**连问题都解决不了**,已改为指向那条陈述本身。两个包要求不同的族则是错误

docs/11-machine-output.md

@@ -262,11 +262,28 @@ It resolves and reports; it does not build. `data` is:
 | `requested` | `{target, toolchain}` — what was asked for |
 | `status` | `ok` or `refused` |
 | `reason` | a refusal token, or `none` |
-| `compiler` | `{family, version, driver}` — the driver that would run |
+| `compiler` | `{family, version, driver, chosenBy}` — the driver that would run, and why |
 | `triple` | `{requested, toolchain, llvm}` |
 | `cLibrary` | `{mode, path, origin, suppliesTarget}` — `mode` is `sysroot` / `payload-first` / `none`; `origin` is `payload` / `subos` / `host` / `none` |
 | `layers[]` | the five target-side layers: `{layer, interface, impl, origin, subset}` |
 
+⭐ **`compiler.chosenBy` answers "why this one".** `{origin, requiredBy,
+replaced}` — `origin` is the same phrase the build's status line uses
+(`[toolchain] in mcpp.toml`, `your default`, `target default`,
+`required by the dependency graph`, `first-run default`). `requiredBy` names the
+package when a `requires = ["mcpp:compiler=…"]` decided it, and `replaced` names
+the spec that was displaced; both are empty when nothing was.
+
+```jsonc
+"compiler": { "family": "clang", "version": "22.1.8", "driver": "…/clang++",
+              "chosenBy": { "origin":     "required by the dependency graph",
+                            "requiredBy": "openkal-llvm-runtime@0.1.3",
+                            "replaced":   "gcc@16.1.0" } }
+```
+
+Without it a consumer asking *why* would have to parse the status line — the
+substring matching this document exists to remove.
+
 ⚠️ **`cLibrary` and `layers[].c-abi` answer two questions, and `suppliesTarget`
 says which one governs.** `cLibrary` describes the *payload's* link model — the
 search paths a payload-supplied C library would use. `layers[].c-abi` describes

docs/zh/11-machine-output.md

@@ -231,11 +231,27 @@ mcpp why toolchain [--target <triple>] [--toolchain <spec>] --format json
 | `requested` | `{target, toolchain}` —— 问的是什么 |
 | `status` | `ok` 或 `refused` |
 | `reason` | 拒绝的记号,或 `none` |
-| `compiler` | `{family, version, driver}` —— 真正会跑的驱动器 |
+| `compiler` | `{family, version, driver, chosenBy}` —— 真正会跑的驱动器,以及为什么是它 |
 | `triple` | `{requested, toolchain, llvm}` |
 | `cLibrary` | `{mode, path, origin, suppliesTarget}`;`mode` 取 `sysroot` / `payload-first` / `none`,`origin` 取 `payload` / `subos` / `host` / `none` |
 | `layers[]` | 目标侧五层:`{layer, interface, impl, origin, subset}` |
 
+⭐ **`compiler.chosenBy` 回答「为什么是它」。** `{origin, requiredBy, replaced}`
+—— `origin` 与构建状态行用的是同一句话(`[toolchain] in mcpp.toml`、
+`your default`、`target default`、`required by the dependency graph`、
+`first-run default`)。当某条 `requires = ["mcpp:compiler=…"]` 做了决定时,
+`requiredBy` 点名那个包,`replaced` 点名被顶掉的那个 spec;没有发生时两者都为空。
+
+```jsonc
+"compiler": { "family": "clang", "version": "22.1.8", "driver": "…/clang++",
+              "chosenBy": { "origin":     "required by the dependency graph",
+                            "requiredBy": "openkal-llvm-runtime@0.1.3",
+                            "replaced":   "gcc@16.1.0" } }
+```
+
+没有它,要问「为什么」的消费方只能去解析状态行 —— 而那正是这份文档存在的理由所要
+消除的字符串匹配。
+
 ⚠️ **`cLibrary` 与 `layers[].c-abi` 回答的是两个问题,`suppliesTarget` 说明哪一个
 管用。** `cLibrary` 描述的是**载荷**的链接模型 —— 一份由载荷供给的 C 库会用到的
 搜索路径。`layers[].c-abi` 描述的是**这次构建**。当依赖供给 C 库时两者分叉,而在

src/build/prepare.cppm

@@ -581,6 +581,19 @@ export struct BuildContext {
     // whether a cached build.ninja was generated for the profile being asked
     // for — and so `Finished <profile>` stops being a hardcoded "release".
     std::string                     profile;
+    // ⭐ WHY THIS COMPILER — carried so the QUERY can answer it too.
+    //
+    // A build says so on its status line. `mcpp why toolchain --format json`
+    // exists precisely to answer "what would this resolve to, and why", and a
+    // consumer that had to parse the prose to learn that a dependency chose the
+    // compiler would be doing the substring matching the machine interface was
+    // introduced to remove.
+    struct CompilerChoice {
+        std::string origin;      // tc_origin_name(): who decided
+        std::string requiredBy;  // the package, when the graph decided
+        std::string replaced;    // the spec displaced, when one was
+    };
+    CompilerChoice                  compilerChoice;
     // Resolved global-cache mode. Read side is honored in prepare_build; write
     // side in run_build_plan.
     CacheMode                       cacheMode = CacheMode::Global;
@@ -5408,31 +5421,54 @@ prepare_build(bool print_fingerprint,
                 // here — where both halves are known — beats a compiler
                 // complaining about a file the reader never named.
                 else if (tcOrigin == TcOrigin::TargetPin) {
+                    // ⚠️⚠️ THE TWO ROWS REFUSE UNDER ONE RULE AND FOR TWO
+                    // REASONS, AND ONE REMEDY DOES NOT SERVE BOTH.
+                    //
+                    // A CONVENTION pin is cancelled by a graph that supplies the
+                    // target's system — that is `graphSuppliesSystem`, one
+                    // screen up — so "depend on a package that supplies it" is
+                    // exactly the way out.
+                    //
+                    // A CAPABILITY pin is not: `targetPinIsCapability` keeps it
+                    // applied no matter what the graph supplies, because no
+                    // other family emits the target at all. Offering the same
+                    // remedy there prints an instruction that the sentence
+                    // directly above it has already ruled out — the failure
+                    // this release removes from `check_requirements`, reproduced
+                    // three screens away.
+                    std::string_view why = targetPinIsCapability
+                        ? "The row names its compiler as a capability: no other "
+                          "family emits this target."
+                        : "The row's payload is what supplies this target's "
+                          "headers and C library,\n       and nothing in the "
+                          "dependency graph supplies them instead.";
+                    std::string remedy = targetPinIsCapability
+                        ? std::format(
+                              "       Drop the package that requires `{}`, or "
+                              "take a version of it built\n"
+                              "       for `{}`.",
+                              reqCompiler, targetPinCandidate)
+                        : std::format(
+                              "       Depend on a package that supplies this "
+                              "target's system (its kernel\n"
+                              "       interface and C library) so the row's "
+                              "payload is not needed, or drop\n"
+                              "       the package that requires `{}`.",
+                              reqCompiler);
                     refusal::record(refusal::Code::CompilerRequirementConflict);
                     return std::unexpected(std::format(
                         "`{}` requires the compiler to be `{}`, and target '{}' "
                         "cannot be built with it here.\n"
                         "         target row       {:<14} ({})\n"
                         "         required         {:<14} (required by {})\n"
-                        "       {}\n"
-                        "       Depend on a package that supplies this target's "
-                        "system (its kernel\n"
-                        "       interface and C library) so the row's payload is "
-                        "not needed, or drop\n"
-                        "       the package that requires `{}`.",
+                        "       {}\n{}",
                         reqCompilerBy, reqCompiler,
                         targetRowName.empty() ? overrides.target_triple
                                               : targetRowName,
                         targetPinCandidate,
                         targetPinIsCapability ? "capability" : "convention",
                         reqCompiler, reqCompilerBy,
-                        targetPinIsCapability
-                            ? "The row names its compiler as a capability: no "
-                              "other family emits this target."
-                            : "The row's payload is what supplies this target's "
-                              "headers and C library,\n       and nothing in the "
-                              "dependency graph supplies them instead.",
-                        reqCompiler));
+                        why, remedy));
                 }
                 // Free to take it. `tcSpec` is either absent (nothing configured
                 // anywhere) or one of mcpp's own remembered answers.
@@ -7301,6 +7337,10 @@ prepare_build(bool print_fingerprint,
     ctx.runtimeSelection = runtimeSelection;
     ctx.runtimeBinding = runtimeBindingSnapshot;
     ctx.profile     = effectiveProfile;
+    ctx.compilerChoice = { std::string(tc_origin_name(tcOrigin)),
+                           graphCompilerRequiredBy,
+                           graphCompilerReplaced.empty() ? pinReplacedDefault
+                                                         : graphCompilerReplaced };
     ctx.cacheMode   = cacheMode;
     ctx.projectRoot= *root;
     ctx.outputDir  = target_dir(*tc, fp, workRoot);

src/doctor.cppm

@@ -886,10 +886,20 @@ export int why_toolchain_json(std::string_view target, std::string_view tcSpec)
 
     data["status"] = "ok";
     data["reason"] = "none";
+    // ⭐ AND WHY THIS ONE. The build's status line says it; a consumer of the
+    // machine interface asking "what would this resolve to, and why" would
+    // otherwise have to parse that prose — the substring matching this document
+    // exists to remove. `requiredBy` and `replaced` are empty unless something
+    // was required and something was displaced.
     data["compiler"] = {
         {"family",  std::string(tc.compiler_name())},
         {"version", tc.version},
         {"driver",  tc.binaryPath.string()},
+        {"chosenBy", {
+            {"origin",     ctx->compilerChoice.origin},
+            {"requiredBy", ctx->compilerChoice.requiredBy},
+            {"replaced",   ctx->compilerChoice.replaced},
+        }},
     };
     data["triple"] = {
         {"requested", std::string(target)},

tests/e2e/281_target_side_rules.sh

@@ -54,8 +54,25 @@ out="$(MCPP_TOOLCHAIN=gcc@16.1.0 "$MCPP" build 2>&1)" || rc=$?
 [[ "$rc" -ne 0 ]] || { echo "a requirement gcc does not meet was accepted:"; echo "$out"; exit 1; }
 grep -q "requires the compiler to be" <<< "$out" || {
     echo "the refusal does not name the requirement:"; echo "$out"; exit 1; }
-grep -q "mcpp toolchain default" <<< "$out" || {
+# ⚠️ THE NEXT STEP MUST BE ONE THAT WOULD ACTUALLY WORK, AND UNTIL 2026.8.26.2
+# THE FIRST ONE OFFERED WAS `mcpp toolchain default llvm`.
+#
+# That is a GLOBAL change — the default for every project on the machine —
+# printed because ONE project's dependency asked. And since the graph's
+# requirement is now applied wherever mcpp's own answer was revisable, the only
+# way to reach this refusal is a compiler the project STATED (here,
+# `MCPP_TOOLCHAIN`). In that situation the global default is not what is being
+# used, so changing it fixes nothing: the advice has to name the statement that
+# decided.
+grep -q "remove it" <<< "$out" || {
     echo "the refusal names no next step:"; echo "$out"; exit 1; }
+# ⚠️ `if`, NOT `grep … && { … }`. Under `set -e` a trailing `&&` list whose
+# left side fails takes the script down — and here grep FAILING is the passing
+# case. This repo has paid for that shape more than once.
+if grep -q "mcpp toolchain default" <<< "$out"; then
+    echo "the refusal offers a global change that would not fix this failure:"
+    echo "$out"; exit 1
+fi
 # The evidence the decision rests on must be printed even though the compiler
 # layer comes from the payload and is suppressed in an ordinary report.
 grep -qE "^\s+compiler\s+gcc" <<< "$out" || {

tests/e2e/301_the_graphs_compiler_is_taken_and_nothing_is_written.sh

@@ -113,18 +113,41 @@ else
     exit 1
 fi
 
-# ── And the status line says who asked ───────────────────────────────────
+# ── And the query says who asked ─────────────────────────────────────────
 #
 # ⚠️ A COMPILER THE USER DID NOT NAME, REPORTED WITHOUT ITS REASON, IS A RULE
 # THAT CAN ONLY BE LEARNED BY EXPERIMENT. The same argument that put a reason on
 # the target row's substitution applies here, and more so: this one overrides a
 # value the user set with `mcpp toolchain default`.
+#
+# ⭐ FROM `compiler.chosenBy`, NOT FROM THE PROSE. A consumer asking "why this
+# compiler" reading the status line would be doing the substring matching the
+# machine interface exists to remove — and so would this test.
+by="$(printf '%s' "$j" | jq -r '.data.compiler.chosenBy.requiredBy // ""' | tr -d '\r')"
+was="$(printf '%s' "$j" | jq -r '.data.compiler.chosenBy.replaced // ""' | tr -d '\r')"
+case "$by" in
+  needs-"$want"@*) echo "  ok  and the query names the package that asked ($by)" ;;
+  "")  echo "FAIL: compiler.chosenBy.requiredBy is empty — the document does not"
+       echo "      say a dependency decided this"; exit 1 ;;
+  *)   echo "FAIL: compiler.chosenBy.requiredBy is '$by', expected needs-$want@…"
+       exit 1 ;;
+esac
+if [ -n "$was" ]; then
+    echo "  ok  and names what it displaced ($was)"
+else
+    echo "FAIL: compiler.chosenBy.replaced is empty, yet '$current' was displaced"
+    exit 1
+fi
+
+# ⭐ AND THE HUMAN-FACING LINE STILL CARRIES IT. The token is for programs; the
+# person running the build reads the status line, and a decision reported there
+# without its reason is the rule learned by experiment.
 out="$("$MCPP" build 2>&1 || true)"
 ok=1
 printf '%s\n' "$out" | grep -q "needs-$want"          || ok=0
 printf '%s\n' "$out" | grep -q "mcpp:compiler=$want"  || ok=0
 if [ "$ok" = 1 ]; then
-    echo "  ok  and the status line names the package that asked"
+    echo "  ok  and the status line names it too"
 else
     echo "FAIL: the resolution does not say who required this compiler"
     printf '%s\n' "$out" | head -6 | sed 's/^/        /'

tests/e2e/302_a_stated_compiler_outranks_the_graph_and_two_requirements_do_not_stack.sh

@@ -109,4 +109,48 @@ else
     exit 1
 fi
 
+# ── Half three: a capability row's remedy is not a convention row's ──────
+#
+# ⚠️⚠️ THE TWO ROWS REFUSE UNDER ONE RULE AND FOR TWO REASONS, AND ONE REMEDY
+# DOES NOT SERVE BOTH.
+#
+# A convention pin is cancelled by a graph that supplies the target's system, so
+# "depend on a package that supplies it" is the way out. A capability pin is
+# not — it stays applied whatever the graph supplies, because no other family
+# emits the target. Printed there, that remedy is an instruction the sentence
+# directly above it has already ruled out.
+#
+# ⭐ FOUND BY READING THE MESSAGE, NOT BY A FAILING BUILD. This half exists so
+# the next rewording cannot put it back.
+#
+# ⚠️ The refusal is decided from the VOCABULARY (the row's pin) before any
+# payload is resolved, so this half is host-independent and needs nothing
+# installed.
+printf '[package]\nname    = "app"\nversion = "0.1.0"\n\n[dependencies]\nneeds-gcc = { path = "../needs-gcc" }\n' \
+    > mcpp.toml
+j3="$("$MCPP" why toolchain --target riscv64-none-elf --format json 2>/dev/null)"
+reason3="$(printf '%s' "$j3" | jq -r '.data.reason // "-"' | tr -d '\r')"
+msg3="$(printf '%s' "$j3" | jq -r '.diagnostics[].message' | tr -d '\r')"
+
+if [ "$reason3" != compiler-requirement-conflict ]; then
+    echo "FAIL: a capability row against a gcc requirement gave reason '$reason3'"
+    printf '%s\n' "$msg3" | sed 's/^/        /'
+    exit 1
+fi
+echo "  ok  a capability row refuses a requirement it cannot satisfy"
+
+if printf '%s\n' "$msg3" | grep -qi 'capability'; then
+    echo "  ok  and it says the pin is a capability"
+else
+    echo "FAIL: the refusal does not say the row's pin is a capability"
+    printf '%s\n' "$msg3" | sed 's/^/        /'
+    exit 1
+fi
+if printf '%s\n' "$msg3" | grep -q "supplies this target's system"; then
+    echo "FAIL: the remedy offers to supply the system, which a capability pin ignores"
+    printf '%s\n' "$msg3" | sed 's/^/        /'
+    exit 1
+fi
+echo "  ok  and it does not offer a remedy a capability pin ignores"
+
 echo "OK: a stated compiler outranks the graph and two requirements do not stack"