fix(wire): a target row's toolchain meant two things, so the convention got its own field

On an installed row it is the payload that is here; on a vocabulary row it is
the target table's convention pin. A row can have the first and no second —
`x86_64-linux-gnu` has an installed gcc and no convention at all.

That is acceptable for a column a person reads and wrong for a field a program
reads. Measured on ubuntu-24.04: e2e 298 selected "a row whose convention is a
gcc" from `toolchain`, got `x86_64-linux-gnu`, and demanded a refusal that
correctly did not happen. Locally the first matching row was
`aarch64-linux-musl`, which does have one, so it passed.

Same defect family as the release this interface was added for, introduced in
the interface itself.

Also: docs/03 now states the convention/capability distinction, in both
languages — including which two kinds of row cannot be overridden and why.

Author: speak-agent

docs/03-toolchains.md

@@ -417,6 +417,41 @@ toolchain = "gcc@16.1.0"
 linkage   = "static"
 ```
 
+### A convention may be overridden. A capability may not.
+
+The pin on a **hosted** row answers *which payload supplies this target's C
+library*, so a project that supplies one itself may name any compiler — that is
+the escape hatch the whole openkal ecosystem is built on. What it may not do is
+name a different compiler and supply nothing:
+
+```
+$ mcpp build --target x86_64-linux-musl        # [toolchain] default = "llvm@…"
+error: target 'x86_64-linux-musl' takes its C library from the 'gcc@16.1.0'
+       payload, and 'llvm@22.1.8' has none here.
+```
+
+Two rows answer a different question, and their pin cannot be overridden at all:
+
+| row | why |
+|---|---|
+| every `*-none-elf` | no per-host cross payload exists; clang and lld are cross-compilers by construction and gcc is not |
+| `x86_64-windows-musl` | no gcc payload emits a PE with a musl C library — the mingw payload emits PE with the MinGW CRT, which is the separate `-gnu` row |
+
+```
+$ mcpp build --target riscv64-none-elf         # [toolchain] default = "gcc@…"
+error: target 'riscv64-none-elf' cannot be emitted by 'gcc@16.1.0'.
+```
+
+⭐ **Both refusals are decided where the decision is made**, not left to the
+compiler. Before 2026.8.26.1 the first ran the whole build and died at the link
+on `crtbeginT.o (bare name)`, and the second produced
+`g++: error: unrecognized argument in option '-mabi=lp64d'` — a message about an
+option, for a decision made a hundred lines earlier.
+
+A program classifying these reads `data.reason` from
+`mcpp why toolchain --format json` (`convention-unreplaced` / `capability-pin`)
+rather than the sentence — see [chapter 11](11-machine-output.md).
+
 A project can set its *default* build target — this is where "this project
 ships fully-static" belongs (static output is a product property, not a
 compiler-family property):

docs/zh/03-toolchains.md

@@ -386,6 +386,39 @@ toolchain = "gcc@16.1.0"
 linkage   = "static"
 ```
 
+### 约定可以被推翻,能力不行
+
+**有宿主**那一行的 pin 回答的是*哪个载荷供给这个目标的 C 库*,所以一个自己供给
+C 库的工程可以写任何编译器 —— 整个 openkal 生态就建立在这道口子上。不能做的是
+写另一个编译器而什么都不供给:
+
+```
+$ mcpp build --target x86_64-linux-musl        # [toolchain] default = "llvm@…"
+error: target 'x86_64-linux-musl' takes its C library from the 'gcc@16.1.0'
+       payload, and 'llvm@22.1.8' has none here.
+```
+
+有两类行回答的是另一个问题,它们的 pin 根本不可被推翻:
+
+| 行 | 为什么 |
+|---|---|
+| 所有 `*-none-elf` | 不存在按宿主分的交叉载荷;clang 与 lld 按构造就是交叉编译器,gcc 不是 |
+| `x86_64-windows-musl` | 没有任何 gcc 载荷发得出 PE + musl —— mingw 载荷发的是 PE + MinGW CRT,那是隔壁 `-gnu` 那一行 |
+
+```
+$ mcpp build --target riscv64-none-elf         # [toolchain] default = "gcc@…"
+error: target 'riscv64-none-elf' cannot be emitted by 'gcc@16.1.0'.
+```
+
+⭐ **两处拒绝都发生在做出决定的地方**,而不是留给编译器。2026.8.26.1 之前,前者
+会跑完整个构建然后死在链接上,报 `crtbeginT.o (bare name)`;后者给出
+`g++: error: unrecognized argument in option '-mabi=lp64d'` —— 一条关于选项的
+消息,而决定在一百行之前。
+
+要给这些结果分类的程序读 `mcpp why toolchain --format json` 的 `data.reason`
+(`convention-unreplaced` / `capability-pin`),而不是那句话 ——
+见[第 11 章](11-machine-output.md)。
+
 项目还可以声明自己的*默认*构建 target——"本项目发布全静态"这类语义
 就该放在这里(全静态是产物属性,不是编译器家族属性):
 

src/toolchain/lifecycle.cppm

@@ -573,6 +573,20 @@ export int toolchain_list(const mcpp::config::GlobalConfig& cfg,
         std::string target;      // canonical triple
         std::string note;        // "host" / "static" / "PE" / "cross" tags
         std::string toolchain;   // "gcc 16.1.0" or "—"
+        // ⚠️⚠️ `toolchain` MEANS TWO DIFFERENT THINGS DEPENDING ON THE ROW, and
+        // that is fine for a column a person reads and wrong for a field a
+        // program reads. On an INSTALLED row it is the payload that is here; on
+        // a vocabulary row it is the target table's convention pin. A row can
+        // have the first and no second — `x86_64-linux-gnu` has an installed
+        // gcc and no convention at all.
+        //
+        // Measured 2026-08-26: e2e 298 selected "a row whose pin is a gcc" from
+        // this field and got `x86_64-linux-gnu` on the CI runner, where the pin
+        // is empty. It then asserted a refusal that correctly did not happen.
+        //
+        // ⭐ So the convention travels in its own field, empty when there is
+        // none. Same defect family as the release this was written for.
+        std::string pin;         // the target table's convention pin, or empty
         std::string status;      // installed | available | planned
         bool        isDefault = false;
         int         rank = 0;    // display order: installed < available < planned
@@ -604,6 +618,8 @@ export int toolchain_list(const mcpp::config::GlobalConfig& cfg,
         r.target    = t.str();
         r.note      = note_for(t);
         r.toolchain = tcLabel;
+        for (auto const& info : mcpp::toolchain::triple::known_targets())
+            if (info.canonical == r.target) { r.pin = std::string(info.pin); break; }
         r.status    = "installed";
         r.rank      = 0;
         r.isDefault = defSpec
@@ -666,6 +682,7 @@ export int toolchain_list(const mcpp::config::GlobalConfig& cfg,
         std::string pin(info.pin);
         if (auto at = pin.find('@'); at != std::string::npos) pin[at] = ' ';
         r.toolchain = pin.empty() ? "—" : pin;
+        r.pin       = std::string(info.pin);
         // Three answers, not two. "available" means a payload here produces it;
         // "via dependency graph" means the compiler is here and the system has
         // to come from packages — a different thing to do next, so a different
@@ -688,6 +705,7 @@ export int toolchain_list(const mcpp::config::GlobalConfig& cfg,
             {"target",    r.target},
             {"note",      r.note},
             {"toolchain", r.toolchain},
+            {"pin",       r.pin},
             {"status",    r.status},
             {"default",   r.isDefault},
         });

tests/e2e/298_overriding_a_convention_requires_replacing_it.sh

@@ -55,12 +55,23 @@ fail=0
 # The target is read from the machine rather than hardcoded: any row whose pin
 # names a family other than llvm will do, and which rows exist is the target
 # table's business, not this test's.
-# ⭐ A ROW WHOSE PIN IS A gcc AND WHOSE STATUS SAYS THIS HOST SERVES IT.
-# Both halves matter: a `planned` row would refuse for a different rule and
-# half one would then pass while testing nothing.
+# ⭐⭐ `pin`, NOT `toolchain` — AND THE DIFFERENCE COST A RED CI RUN.
+#
+# `toolchain` is what the row is associated with: the installed payload on an
+# installed row, the convention on a vocabulary row. A row can have the first
+# and no second. This test needs a row that HAS a convention, so it reads the
+# field that carries only that.
+#
+# Measured 2026-08-26 on ubuntu-24.04: selecting on `toolchain` picked
+# `x86_64-linux-gnu`, whose convention pin is empty, and the test then demanded
+# a refusal that correctly did not happen.
+#
+# The status filter matters for the same reason in the other direction: a
+# `planned` row refuses under a different rule, and half one would pass while
+# testing nothing.
 pinned="$("$MCPP" toolchain list --format json 2>/dev/null \
           | jq -r '[.data.targets[]
-                    | select(.toolchain | startswith("gcc"))
+                    | select(.pin | startswith("gcc"))
                     | select(.status != "planned")
                     | .target][0] // empty')"
 if [ -z "$pinned" ]; then