feat(windows): the SDK and the runtime get the axes the compiler already had - #448

…eady 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.

`mcpp pack` refused Windows with `#if defined(_WIN32)`, and the reason given
was that the tools were POSIX-only. That was the symptom. The cause is one
layer down: the dependency closure comes from

    LD_TRACE_LOADED_OBJECTS=1 '<binary>'

which RUNS the artifact — so it can cross neither an OS (a Linux box cannot
execute a PE) nor an ARCHITECTURE (an x86_64 box cannot execute an aarch64
ELF, same OS or not). Porting `tar` would not have helped, and every tool the
2026-05-19 design proposed — dumpbin, ImageNtHeader, Compress-Archive — would
have reintroduced the obstacle one layer down, because each exists only on the
platform where the problem had already gone away.

mcpp.pack.binfmt reads it out of the file instead: ELF DT_NEEDED through the
segment table, PE imports AND delay-imports (a missing delay-load does not
fail at startup — it fails at the first call through it, which is strictly
worse to debug). Cross-OS packaging is then not a feature that had to be
added; it is what remains once nothing has to be executed.

mcpp.pack.zip writes the archive, for the same reason: no zip tool exists on
every host (GNU tar cannot write zip, `zip(1)` is often absent,
Compress-Archive is Windows-only). Entries are STORED, which is a real size
cost and the honest trade — a DEFLATE encoder is the one part that could
produce an archive that unpacks WRONG rather than failing loudly, and mcpp has
no zlib to borrow one from. Deterministic by construction: no timestamps are
read, so a published checksum means something.

THE CONTRACT NOW REACHES PACKAGING (§4.3). `cxx_runtime` used to stop at the
compile and link flags, so the step that decides which files actually travel
could not see what had been promised — on ELF the `ldd` closure agreed with it
by luck, on PE nothing did. It is now an input:

  toolchain-coupled  the toolchain's runtime directory joins the search set
  host-coupled       it stays OUT, so a vcruntime140.dll in the toolset is not
                     silently swept into a package that promised the host
                     would provide it
  --mode system/static + toolchain-coupled → refused, naming the way out

PE layout is flat, and that is the relocation mechanism rather than a style:
the Win32 loader resolves a DLL from the directory of the executable, and
there is no rpath to point elsewhere. Windows' own DLLs are never bundled —
two of something that must be unique is a broken program, not a heavier one —
but `force_bundle` overrides that, as it always did on ELF.

Verified on a Linux host against a real cross-built PE, not only synthesised
fixtures: e2e 240 builds a mingw target, drops a stand-in for a DLL the EXE
imports, packs, and has PYTHON verify the archive. The msvcrt.dll assertion is
the positive half (a parser that read nothing could not have produced it) and
the kernel32.dll assertion the negative half; together they are decisive. It
runs in the mingw-cross job because running it on Windows would prove nothing.

Docs: the Windows layout, the cross-host story and both size/determinism
consequences in 02-pack-and-release (en+zh); the MSVC half of `cxx_runtime` in
05-mcpp-toml (en+zh), replacing a claim about /MT that stopped being true;
SDK-by-origin and the `@system` rule in 03-toolchains (en; the zh MSVC section
was rewritten — it still described msvc as a system-only toolchain and
`msvc@19.44` as a pin-verify). 2026-05-19-pack-windows-design.md is marked
superseded with what it got wrong and why, since the mistake is instructive.

…came

The design doc gains a status section per item, including the two places the
PLAN was corrected by the implementation and the one half of §4 that was
deliberately not done:

- `dist::Format` now reads the target triple before falling back to the host.
  Everything but MinGW used to ask the host, which made a Windows contract
  unassertable on the Linux runner where most of this gets reviewed. It only
  ADDS answers, so no existing build changes.
- `force_bundle` had to reach the PE system list too. ELF always worked that
  way; making the PE exclusion unconditional would have turned an explicitly
  written decision into decoration.
- The ELF closure still runs the artifact. `ldd` hands back RESOLVED PATHS
  while `DT_NEEDED` gives only names, and turning names into paths means
  reimplementing the loader's search order ($ORIGIN, DT_RPATH before
  LD_LIBRARY_PATH before DT_RUNPATH before ld.so.cache, hwcaps). Rewriting
  that under a correct, e2e-covered path is more risk than it buys — and the
  cost is stated rather than left to be discovered: cross-ARCHITECTURE ELF
  packing is still unsupported, which is the second limit §4.1 names.

`mcpp self doctor` reports the Windows SDK PER ORIGIN. One unlabelled line was
the same "one question, two answerers" shape this axis exists to close: a user
reading it would believe it applied to their pinned build, and it did not.

The combined test died with SIGSEGV on the macOS ARM64 runner and nowhere
else — not under ASan+UBSan with clang 22 + libc++, not as a clang module on
x86_64 Linux, not under gcc. A single test that builds a fixture, identifies
it and parses it cannot say which of the three it was, so each hypothesis
costs a CI round. Three tests now: the fixture is well-formed, identify(),
and needed_names().

The MinGW section says the key does not exist and is silently ignored; the
MSVC section two hundred lines down showed exactly that form as the way to
select `/MT`. Found by writing it out and watching mcpp print "unsupported
key 'linkage' (ignored)" — which is also what a user following the page would
have got, without the page telling them why nothing changed.

`linkage` is exact-triple only (`[target.<triple>]`, or `--static`). Both
language editions now show that, and say which section each key lives in —
the zh page had it right before this round and lost it when the MSVC section
was rewritten from the English one.

…dies

Splitting the test localised the macOS ARM64 SIGSEGV to
ThePeFixtureItselfIsWellFormed — fixture code that calls no module at all. So
it is not mcpp.pack.binfmt, and the three probes that came back clean (ASan +
UBSan under clang 22 + libc++, the same module compiled by clang on x86_64
Linux, gcc everywhere) were looking in the right place for the wrong thing.

The fixture used two `std::span` parameters and two lambdas that mutated a
captured string through a captured cursor. It now takes vectors, indexes
explicitly, and captures nothing — and traces each phase to stderr, so if it
moves again the log names the step instead of costing another CI round.

`#include <cstdio>` is not redundant next to `import std;`: `stderr` is a
macro, and a module cannot export one.

`--mode static` on its own has always meant "the musl-static ELF", and that
is unchanged. But the re-prepare that enforces it ignored `opts.targetTriple`,
so `--mode static --target x86_64-windows-gnu` silently produced a LINUX
build. That was invisible while PE packaging did not exist — there was no
Windows package to notice was missing — and it is a wrong answer now that
there is.

Measured both ways: with an explicit target the output is
`…-x86_64-w64-mingw32-static.zip`; without one it is still
`…-x86_64-linux-musl-static.tar.gz`.

It did its job — the plain rewrite is green on macOS ARM64 — and 24 lines of
stderr in every CI run forever is a poor trade for a crash that is currently
fixed. `MCPP_TEST_TRACE=1` brings it back, which keeps a recurrence one CI
round to localise instead of the four this one cost.