feat(windows): give the SDK and the runtime the axes the compiler already had

Implements §1 / §2 / §3 of
.agents/docs/2026-08-16-windows-toolchain-three-axes-design.md.

Three questions were entangled because only one of them had ever been
modelled. The compiler got a version axis in the last round; the headers it
compiles against and the runtime the artifact loads did not.

§2 THE SDK IS BOUND, NOT SEARCHED.

`find_windows_sdk()` scanned — WindowsSdkDir, then the sibling store, then
the conventional roots — for BOTH origins. So a pinned `msvc@<toolset>` was a
pin the environment could overwrite, and two machines could build one
manifest against two SDKs with nothing in the log naming either. It is now
resolved by origin: a managed toolset takes the SDK payload from its own
store and ignores WindowsSdkDir/WindowsSdkVersion *out loud*; `msvc@system`
keeps today's chain, because a machine's things can only be found by looking.

A managed toolset with no SDK payload beside it still falls back to the
machine's — working beats failing — and says so, because that build is no
longer reproducible and only that line records it.

§2.3 `ucrt@<version>` FILLS A SLOT THAT HAS BEEN RESERVED SINCE THE FIELD
EXISTED. `RuntimeBinding::runtimeId`'s comment has documented it from the
start and nothing ever wrote one, so the SDK version never reached
`runtimeContractHash` and two SDKs shared one build cache.

It is NOT isomorphic to `glibc@`, and the comment says so where it will be
read: glibc@ binds a payload (headers + .so, patchelf makes the artifact run
on that copy), ucrt@ declares a floor (ucrtbase.dll is an OS component from
Win10 on; mcpp's windows-sdk payload deliberately carries only half of ucrt
and no redistributable). It is therefore not projected into `libc`. The
`glibc@`-prefix gates become `runtime_provider()` dispatch, so another
provider reads as "no rules here" rather than "no identity".

§3.3 `toolchain-coupled` NOW MEANS SOMETHING ON PE. The refusal said the MSVC
runtime "ships with the OS/redistributable, not with the toolchain" — true of
ucrtbase.dll, false of vcruntime140.dll/msvcp140.dll, which sit in
VC\Redist\MSVC\ inside every toolset. That is the relationship gcc has to
libstdc++.so, so it takes the same contract; PE has no rpath, so the
mechanism is a copy beside the artifact rather than a search path. /MT stays
a degradation, and a genuine one: a static CRT leaves no DLL to couple to.

The DLL set comes from `vc_redist_dir()` — the single criterion that excludes
`debug_nonredist\`, which may not be redistributed. A second, name-shaped
rule here could disagree with it, and disagreeing about that is a licensing
defect rather than a bug.

§1 THE ORIGIN AXIS IS CONTAINED, NOT GENERALISED.

- `gcc@system` / `llvm@system` are refused where they are read, naming both
  things the user might have meant. They used to parse and then fail
  elsewhere as `xim:gcc@system` → "no such package", sending the reader after
  a version that was never going to exist. `msvc@system` is a concession to
  one platform, not a capability the other families lack; the family-less
  `system` escape hatch is untouched.
- `resolve_managed_msvc()` replaces two hand-written copies of "where does a
  managed toolset live, and why is the fetcher's `root` wrong for it" — the
  reason existed in only one of them.
- `needs_linux_sysroot_payloads()` replaces two spellings of one rule whose
  comment claimed they mirrored each other. They did not: the PE term was
  missing from one. Unreachable today, which is how it survived.
- The toolchain resolution order was documented twice, as "3 steps" and "4
  steps", naming five of the nine inputs and disagreeing about two. One table
  now, keyed to `TcOrigin` enumerators so it cannot quietly stop matching.

`dist::Format` is derived from the target triple before falling back to the
host, which only ADDS answers — and makes a Windows contract assertable on
the Linux runner that reviews most of this.

Tests: 22 new. The SDK-override criterion is the design doc's §6 acceptance
test as a unit test (point WindowsSdkDir elsewhere; the payload SDK must
still win, and the note must say the variable was ignored); the deploy tests
assert reachability twice over, since a copy edge nothing asks for never runs
under explicit ninja goals.

Author: speak-agent

src/build/distribution.cppm

@@ -268,6 +268,16 @@ struct Mechanism {
     // global constructor that touches std::cout runs before the streams
     // exist. Asks the backend for the ordering shim. See issue #336.
     bool        streamInitShim = false;
+    // PE + MSVC runtime + toolchain-coupled: the toolset's own redistributable
+    // CRT DLLs must be STAGED BESIDE the artifact.
+    //
+    // On ELF, `toolchain-coupled` needs no files copied — the artifact carries
+    // an rpath into the toolchain's lib directory and the loader follows it.
+    // PE has no rpath: a DLL is resolved from the directory of the executable
+    // (and then PATH), so on this format the mechanism IS the copy. Same
+    // contract, same meaning, different mechanism — which is exactly the split
+    // this module's three layers exist to express.
+    bool        deployToolchainRuntime = false;
 };
 
 namespace detail {
@@ -426,12 +436,43 @@ Mechanism resolve(const MechanismInput& in) {
                       "it everywhere; using host-coupled here"
                     : "";
             } else if (in.requested == Contract::ToolchainCoupled) {
-                // Only reachable from an explicit request: it is never a default.
-                m.degraded = true;
-                m.diagnostic = std::format(
-                    "cxx_runtime = \"toolchain-coupled\" has no meaning for the "
-                    "MSVC runtime (it ships with the OS/redistributable, not with "
-                    "the toolchain); using {}", to_string(m.effective));
+                // THIS USED TO BE A FLAT REFUSAL, and the sentence it refused
+                // with was half true:
+                //
+                //   "…has no meaning for the MSVC runtime (it ships with the
+                //    OS/redistributable, not with the toolchain)"
+                //
+                // True of `ucrtbase.dll`, which IS an OS component since
+                // Win10. NOT true of `vcruntime140.dll` / `msvcp140.dll`,
+                // which are the toolset's own and sit inside every MSVC
+                // toolset ever shipped:
+                //
+                //   VC\Redist\MSVC\<ver>\<arch>\Microsoft.VC<N>.CRT\*.dll
+                //
+                // That is the same relationship gcc has to libstdc++.so, so it
+                // takes the same contract — and refusing it left a hole in the
+                // matrix that had a real cost: the default `/MD` artifact
+                // depends on DLLs a machine with only a managed toolset does
+                // not have, and there was no spelling that made them travel.
+                //
+                // `/MT` is the one case that stays a degradation, and it is a
+                // genuine contradiction rather than a missing mechanism: a
+                // static CRT leaves NO DLL to couple to. Say which one won.
+                if (in.msvcStaticCrt) {
+                    m.effective  = Contract::SelfContained;
+                    m.degraded   = true;
+                    m.diagnostic =
+                        "cxx_runtime = \"toolchain-coupled\" cannot apply to a "
+                        "project compiled with the static CRT (/MT): there is "
+                        "no vcruntime140.dll/msvcp140.dll dependency left to "
+                        "couple to. Drop linkage = \"static\" (or the "
+                        "project-wide self-contained contract) if the toolset's "
+                        "CRT should travel beside the artifact instead; using "
+                        "self-contained";
+                } else {
+                    m.effective              = Contract::ToolchainCoupled;
+                    m.deployToolchainRuntime = true;
+                }
             }
             return m;
         }

src/build/flags.cppm

@@ -77,6 +77,28 @@ struct CompileFlags {
     // macOS + self-contained: link units need the initializer-ordering shim
     // object prepended to their inputs (issue #336).
     bool needsStreamInitShim = false;
+    // PE + `toolchain-coupled`: the toolset's own CRT DLLs, to be staged
+    // beside the artifact. Resolved HERE rather than in the emitter because
+    // "which files does this contract imply" is a contract question; the
+    // backend only knows how to spell a copy edge.
+    //
+    // A whole-BUILD list, not a per-role one, and that is a property of the
+    // format rather than a simplification: a PE artifact resolves a DLL from
+    // its own directory, so one directory holds one answer and two roles in
+    // one output tree cannot disagree about it. Any built role asking for the
+    // contract is enough to populate it.
+    //
+    // The DIRECTORY comes from `msvc::vc_redist_dir()` via
+    // `Toolchain::linkRuntimeDirs`, which is what keeps `debug_nonredist\`
+    // (vcruntime140d.dll & friends — NOT redistributable) out of the list. The
+    // criterion lives in exactly one place on purpose: a second name-shaped
+    // rule here could disagree with it, and a copy step that disagrees about
+    // what may be redistributed is a licensing defect, not a bug.
+    //
+    // Already deduped against the plan's own deploy files, so the emitter can
+    // append without deciding anything: a name the manifest already claims
+    // stays the manifest's and the conflict is reported through `diagnostics`.
+    std::vector<BuildPlan::DeployFile> toolchainRuntimeDeploy;
     // Non-empty when a requested contract could not be honored. The caller
     // MUST surface these — a silent downgrade is the failure mode this whole
     // model exists to prevent. Emitted once by the backend, not here, because
@@ -762,6 +784,22 @@ CompileFlags compute_flags(const BuildPlan& plan) {
         // produces a PE and must take the PE answer.
         const dist::Format format = [&] {
             if (isMingwTc) return dist::Format::Pe;
+            // The TARGET's own word, when it has one. `isMingwTc` was the only
+            // cross case this knew about, so every other question about the
+            // output format was answered by asking the HOST — which is right
+            // whenever they agree and unaskable in a test that does not run on
+            // the platform it is about. A triple that names its OS is a fact;
+            // the host is a stand-in for one.
+            //
+            // Only ADDS answers: a triple that says neither falls through to
+            // exactly the previous derivation, so no existing build changes.
+            const auto& t = plan.toolchain.targetTriple;
+            if (t.find("windows") != std::string::npos
+                || t.find("mingw") != std::string::npos)
+                return dist::Format::Pe;
+            if (t.find("apple") != std::string::npos
+                || t.find("darwin") != std::string::npos)
+                return dist::Format::MachO;
             if constexpr (mcpp::platform::needs_explicit_libcxx)
                 return dist::Format::MachO;
             else if constexpr (mcpp::platform::is_windows)
@@ -896,6 +934,8 @@ CompileFlags compute_flags(const BuildPlan& plan) {
             });
         };
 
+        bool wantsToolchainRuntime = false;
+
         for (auto [role, requested, wasAsked] : {
                  std::tuple{dist::Role::Distributable, base,           explicitBase},
                  std::tuple{dist::Role::Test,          testsContract,  explicitTests},
@@ -910,10 +950,65 @@ CompileFlags compute_flags(const BuildPlan& plan) {
             f.ldStdlibCByRole[i] = r.unitFlagsC;
             f.contractByRole[i] = r.effective;
             if (r.streamInitShim) f.needsStreamInitShim = true;
+            // Only a role this build actually HAS may pull DLLs into the
+            // output tree. The contract is resolved for every role because
+            // `ldStdlibByRole` must be total; staging files is a side effect
+            // on disk, and a project with no test binaries should not get a
+            // CRT copied beside nothing.
+            if (r.deployToolchainRuntime && role_is_built(role))
+                wantsToolchainRuntime = true;
             if (!r.diagnostic.empty() && role_is_built(role))
                 f.diagnostics.push_back(std::format(
                     "{} target: {}", dist::to_string(role), r.diagnostic));
         }
+        if (wantsToolchainRuntime) {
+            // `linkRuntimeDirs` is the toolset's own redistributable CRT
+            // directory and nothing else on this toolchain — `enrich_toolchain
+            // _from_cl` puts exactly `vc_redist_dir()` there. Guarded on the
+            // compiler anyway: the field means "the toolchain's private
+            // runtime" for every provider, and on gcc it holds libstdc++'s
+            // directory, which has no business being copied into a PE tree.
+            if (plan.toolchain.compiler == mcpp::toolchain::CompilerId::MSVC) {
+                std::vector<std::filesystem::path> sources;
+                std::error_code ec;
+                for (auto const& dir : plan.toolchain.linkRuntimeDirs) {
+                    for (auto const& e :
+                         std::filesystem::directory_iterator(dir, ec)) {
+                        if (!e.is_regular_file(ec)) continue;
+                        auto ext = e.path().extension().string();
+                        std::ranges::transform(ext, ext.begin(),
+                            [](unsigned char c) { return std::tolower(c); });
+                        if (ext != ".dll") continue;
+                        sources.push_back(e.path());
+                    }
+                }
+                // Directory order is not a stable input: this list reaches
+                // build.ninja, and a graph that differs between two runs of
+                // the same build re-runs edges for no reason.
+                std::ranges::sort(sources);
+                for (auto const& src : sources) {
+                    auto dest = std::filesystem::path("bin") / src.filename();
+                    // An explicit `[runtime] deploy_files` naming the same DLL
+                    // WINS, and says so. A human wrote that one down; this list
+                    // is derived. Silently overwriting a vendored redist with
+                    // the toolset's copy is a different program than the one
+                    // the manifest describes.
+                    auto clash = std::ranges::find_if(plan.runtimeDeployFiles,
+                        [&](auto const& d) { return d.dest == dest; });
+                    if (clash != plan.runtimeDeployFiles.end()) {
+                        if (clash->source.lexically_normal()
+                            != src.lexically_normal())
+                            f.diagnostics.push_back(std::format(
+                                "toolchain-coupled would stage '{}' beside the "
+                                "artifact, but this project already deploys "
+                                "'{}' there; keeping the project's file",
+                                src.string(), clash->source.string()));
+                        continue;
+                    }
+                    f.toolchainRuntimeDeploy.push_back({src, dest});
+                }
+            }
+        }
         // Two roles usually share a contract, so they usually share a
         // complaint; report each distinct one once.
         std::ranges::sort(f.diagnostics);

src/build/ninja_backend.cppm

@@ -449,6 +449,18 @@ std::string emit_ninja_string(const BuildPlan& plan) {
     // All compile/link flags are computed once via flags.cppm.
     auto flags = compute_flags(plan);
 
+    // Everything that has to sit beside the artifact, from both producers:
+    // the manifest's `[runtime] deploy_files` (already in the plan) and the
+    // C++ runtime contract's own answer (`toolchain-coupled` on PE — see
+    // mcpp.build.distribution). Merged ONCE, here, because three places below
+    // consume the list — the implicit dependency of each executable, the copy
+    // edges, and `default` — and a list that is complete in two of them is a
+    // graph where the DLL is copied only when something else happens to ask.
+    auto deployFiles = plan.runtimeDeployFiles;
+    deployFiles.insert(deployFiles.end(),
+                       flags.toolchainRuntimeDeploy.begin(),
+                       flags.toolchainRuntimeDeploy.end());
+
     bool need_c_rule = false, need_asm_rule = false, need_nasm_rule = false;
     for (auto& cu : plan.compileUnits) {
         if (is_c_source(cu))         need_c_rule = true;
@@ -1770,7 +1782,7 @@ std::string emit_ninja_string(const BuildPlan& plan) {
         // beside the .exe before the build is considered done. Empty on RPATH
         // platforms (no *.dll deps), so other targets are unaffected.
         if (lu.kind == LinkUnit::Binary || lu.kind == LinkUnit::TestBinary) {
-            for (auto const& d : plan.runtimeDeployFiles)
+            for (auto const& d : deployFiles)
                 implicit += " " + escape_ninja_path(d.dest);
         }
 
@@ -1826,13 +1838,13 @@ std::string emit_ninja_string(const BuildPlan& plan) {
     // — which also means a DLL still loaded by a running program from a
     // previous `mcpp run` gets the skip-if-equivalent treatment instead of a
     // hard "cannot copy" failure.
-    // Inert on RPATH platforms where runtimeDeployFiles is empty.
-    for (auto const& d : plan.runtimeDeployFiles) {
+    // Inert on RPATH platforms where the merged deploy list is empty.
+    for (auto const& d : deployFiles) {
         append(std::format("build {} : stage_file {}\n",
             escape_ninja_path(d.dest),
             escape_ninja_path(d.source)));
     }
-    if (!plan.runtimeDeployFiles.empty())
+    if (!deployFiles.empty())
         append("\n");
 
     // ── Declared build-graph nodes (`mcpp:action=`) ─────────────────────────
@@ -1899,7 +1911,7 @@ std::string emit_ninja_string(const BuildPlan& plan) {
                 defaults += " " + escape_ninja_path(alias);
             }
         }
-        for (auto const& d : plan.runtimeDeployFiles) {
+        for (auto const& d : deployFiles) {
             defaults += " " + escape_ninja_path(d.dest);
         }
         defaults += actionDefaults;