feat(windows): zig cross-build knob, AE_TEST_RUNNER hook, fast CI lane

[paul-hammant]

Closes #1592, closes #1593, closes #1594 — the three-part plan for a fast Linux-hosted Windows signal.

Why: the MSYS2 legs take ~20 minutes, so Windows-only compile breakage is discovered long after the author context-switched away. This lane compiles the same code paths on a Linux runner in minutes. Minutes are free on a public repo — the prize is PR turnaround, and now also not burning 20 minutes of doomed compute when the fast lane fails.

WINDOWS=1 cross knob (#1592)

Mirrors FREEBSD=1, via zig cc -target x86_64-windows-gnu. Simpler than the FreeBSD leg: zig bundles the mingw-w64 headers and CRT, so there is no sysroot to fetch.

make compiler ae stdlib WINDOWS=1 ZIG=/path/to/zig
file build/ae.exe   # PE32+ executable (console) x86-64, for MS Windows

Capability-lean by design (out of scope: cross-compiling OpenSSL/nghttp2, the genuinely expensive part) — those std features ship as their "unavailable" stubs, exactly as on any box without the libraries. Vendored PCRE2 needs no host library, so std.regex survives.

Three host-uname-keyed spots had to opt out or the cross link picked up the host's POSIX libs (zig-lld: unable to find dynamic system library 'pthread'): AUDIO_LDFLAGS, the -pthread block, and __USE_MINGW_ANSI_STDIO — the last of which turned out to be correct as-is, since zig ships mingw-w64's libmingwex.

AE_TEST_RUNNER hook (#1592)

ae run / ae test prefix the binary they just built with the runner instead of exec'ing it — cargo's CARGO_TARGET_<triple>_RUNNER pattern. Empty by default, so every existing caller is byte-for-byte unaffected. 45 lines, two call sites.

The point is that it keeps target-awareness at the edge: no forked _windows spec files, nothing in std.spec or the test sources knows it is under an emulator, and the AE_SPEC_FORMAT/AE_SPEC_REPORT contract is inherited straight through the wrapper.

Fast CI lane (#1593)

windows-cross lives inside windows.yml, not a separate file — needs: only works within one workflow, and gating was the point. Both MSYS2 legs and headers-msvc now needs: windows-cross, so a fast-lane failure skips the slow tier. (needs:-skipped jobs report as skipped, not failed; the PR still reads red from the fast lane's own failure, so branch protection behaves.)

Steps: provision zig (same cache discipline as ci.yml's FreeBSD leg) → cross-build → assert the artifacts really are PE → warm the Wine prefix once → smoke-test hello-world → sweep with AE_TEST_RUNNER=wine.

Exclusions are named in tests/ae_sweep_prune_wine.txt, not skipped silently — fs/path semantics (Wine's case-mapping is not NTFS), sockets/h2/sendfile (IOCP and TransmitFile, not epoll/sendfile), actor-scheduler timing (flake under emulation), and the LD_PRELOAD sandbox. make test-ae gained AE_SWEEP_EXTRA_PRUNE=<file>, applied to both the .ae and .sh sweeps — the .sh sweep had no prune filter at all, so the excluded suites would otherwise have run anyway.

Build-target stamp (fell out of the work)

One build/ tree holds one target's objects and archives; mixing ELF and PE dies deep in the link with unknown file type, and a cross build silently clobbers libaether.a for the next native build. build/.build-target now makes the next mismatching build stop immediately with an actionable message. make clean/help are exempt — the guard must not block its own remedy.

Docs (#1594)

README's "enforced down to libc" names the platform boundary; docs/containment-sandbox.md states Windows is out by construction (there is no LD_PRELOAD, so this is not a port waiting to be written) and that a Wine run does not exercise containment at all — preloading into the wine process intercepts wine's libc calls, not the guest's, so a green run there would be actively misleading. docs/build-system.md documents both cross knobs and the runner hook.

Verification

• Clean WINDOWS=1 build from scratch → PE32+ ae.exe + aetherc.exe, correct stamp.
• AE_TEST_RUNNER proven to intercept with a logging wrapper on both ae run and ae test; inert when unset or empty.
• Native build unaffected; 390 unit tests pass; AE_SWEEP_EXTRA_PRUNE verified end-to-end (687 → 203 tests with a test list, message reports the count).
• Every pattern in the wine prune list checked to match real paths (no dead entries).
• Full .ae sweep: 850 passing. The only failures are http_server_h2 — documented as failing on clean main in asks/h2-50-stream-stress-framing-layer-error.md — plus a load-related http_request_remote_addr flake that passes in isolation, and contrib_vulkan_portability (no GPU on this box).

Honest gap: the Wine execution half is unproven locally (no Wine installed here). The cross-build and the runner hook are both proven; CI is the first real exercise of AE_TEST_RUNNER=wine. If it needs tuning, expect it in the timeout or the prune list rather than the mechanism.

Incidentally the lane already earned its keep: the cross-build surfaced two Windows-only -Wsign-compare diagnostics inside Winsock's own FD_SET macro (SOCKET is unsigned). They originate in zig's bundled headers rather than our code, so the fast lane deliberately does not promote warnings to errors — that enforcement stays with the MSYS2 legs, against the headers Windows users actually compile with.

🤖 Generated with Claude Code

[paul-hammant]

Scope correction after the first CI run: the Wine execution half is deferred; this PR is now compile-only.

The run is worth reading as a result rather than a failure — it invalidated a premise in #1593's plan that neither of us had tested:

step	outcome
Install toolchain + Wine	✅
Provision zig	✅
Cross-build (WINDOWS=1)	✅
Verify artifacts are PE	✅
Warm Wine prefix	✅
Smoke: hello-world via ae.exe under Wine	❌ [ae] GCC not found. Downloading MinGW-w64 GCC (~250 MB)...

ae is a compile-and-run driver. Running ae.exe inside a Wine prefix means the compiler runs there too, so it wants a Windows C toolchain in that prefix to compile the C it emits. Wine alone was never enough.

I checked the obvious alternative before giving up on it: drive the native ae with AE_CC="zig cc -target x86_64-windows-gnu" so only the resulting binary goes through Wine. That needs a Windows libaether.a beside the native one — confirmed locally, it fails to link against the Linux archive — and one build/ tree holds exactly one target's archives (the very collision this PR's .build-target stamp exists to catch). The sweep step would also have failed independently: test-ae shells out to build/ae, which is build/ae.exe in a WINDOWS=1 tree.

That is a real piece of design work, not a tweak, so it belongs in its own issue rather than blocking this one.

What still ships, and why it is still worth it:

• WINDOWS=1 cross knob (WINDOWS=1 zig-cross knob (mirror FREEBSD=1) + AE_TEST_RUNNER hook in ae test/run #1592) — unchanged, proven.
• AE_TEST_RUNNER (WINDOWS=1 zig-cross knob (mirror FREEBSD=1) + AE_TEST_RUNNER hook in ae test/run #1592) — unchanged, proven on both ae run and ae test. It is exactly what a future execution lane needs; keeping it costs nothing since it is inert unless set.
• windows-cross job — cross-builds and asserts the artifacts really are PE. The gating is intact and was most of the value: MSYS2 legs needs: it, so a Windows compile break skips ~20 min of doomed compute and surfaces at minute ~4.
• tests/ae_sweep_prune_wine.txt — kept and reframed as the design record. The durable part was always the analysis of which areas a Wine lane must never claim to cover, not the wiring.
• Docs (docs: README's 'enforced down to libc' reads cross-platform; LD_PRELOAD layer is Linux/FreeBSD-only #1594) — unchanged and, if anything, more accurate now.

CHANGELOG, docs/build-system.md and docs/containment-sandbox.md all describe what ships rather than what was planned, and the deferred work is written down where the next person will find it.

Happy to close #1593 as partially-delivered and open a follow-up for the execution lane, or leave #1593 open scoped down to just that — your call on which reads better in the tracker.