chore(ci): purge cargo-zigbuild, zig and cargo-xwin for soldr's blessed cross path

[zackees]

Retires every zig- and xwin-based cross-compilation wrapper in favour of soldr's blessed path (soldr prepare --target X + soldr build --target X), adds a lint and a hook so they cannot come back, and documents the traps that cost real time getting here.

Why

soldr's prepare --help states the contract: it "installs the Rust standard library, selects and materializes the blessed compiler/linker plus SDK or sysroot, and exports the target-scoped environment. Legacy backend wrappers are diagnostic-only overrides and are never selected by this command."

Carrying the wrappers anyway was pure liability, proven twice in one day:

• cargo-zigbuild was pip-installed unpinned and floated 0.23.1 → 0.23.4 mid-release, breaking both apple-darwin lanes of 2.5.22 with unable to read exported symbols list '-dead_strip': FileNotFound.
• cargo-xwin required ~40 lines of CRT-casing symlink repair in the workflow to satisfy MSVC import libraries on a case-sensitive filesystem.

Verified before changing anything

target	result
aarch64-apple-darwin	soldr build → real Mach-O arm64 binary
x86_64-pc-windows-msvc	soldr build → 41 MB fbuild.exe, no xwin shims
x86_64-unknown-linux-gnu (PyO3 cdylib)	max symbol GLIBC_2.16

Both mac and windows lanes are green in CI on this branch (run 33815922498).

That last row is the one that matters for wheels: soldr's catalogue sysroot holds the manylinux_2_17 floor by itself, and holds it lower than the cargo zigbuild --target ...-gnu.2.17 lane it replaces (2.17).

The trap, now documented

Do not port zigbuild's .2.17 suffix onto a soldr target. soldr has no such target, logs the miss as a warning, falls back to the bare host toolchain and still exits 0 — yielding a GLIBC_2.39 .so tagged manylinux_2_17, which installs fine and fails at import on anything older than the build host. Filed upstream as zackees/soldr#3082.

Upstream work this depended on

The musl lanes needed three soldr fixes, all filed, fixed and merged:

• musl: -L for a pkg-config syslib is the sysroot concatenated with an absolute path (ld: cannot find -lbz2) zackees/soldr#3081 → PR #3083: soldr exported PKG_CONFIG_SYSROOT_DIR, and pkg-config prefixed it onto every absolute -L, so a managed syslib resolved to sysroot+absolute. Our musl lanes died with ld: cannot find -lbz2.
• release: staging runs host GNU binutils over cross-built artifacts, failing 3 lanes of v0.9.12 zackees/soldr#3085 → PR #3086: release staging ran host GNU binutils against cross-built artifacts (objcopy: Unable to recognise the format, strip: file format not recognized).
• Re-gate publish on the macOS x64 Recovery replay once the lane can stay green zackees/soldr#3088 → PR #3089: publish was gated on a macOS Recovery-guest replay that had never once been green.

setup-soldr is pinned to 0.9.12, the first release carrying them.

Changes

• template_native_build.yml: four per-target build branches collapse to one soldr prepare + soldr build. Deleted the cargo-xwin install, the xwin system-deps step (clang/lld/llvm + the clang-cl symlink), the CRT-casing repair block, and the pip install.
• ci/check_no_legacy_cross.py + ci/test_no_legacy_cross.py: the gate, wired into ci-workflow-drift.yml. Scans runnable lines only so comments keep the history; one-line lint-allow: legacy-cross pragma for a genuine exception.
• ci/hooks/tool_guard.py: real-time half — blocks the retired commands in Bash, including soldr cargo zigbuild.
• agents/docs/cross-compilation.md: the blessed path, the measured glibc floors, the suffix trap. Wired into the root routing table.
• Cargo.toml: [workspace.metadata.soldr] targets so --target all resolves.
• ci/docker-mac-cross/: migrated to soldr build; the image installs no cross toolchain of its own.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CfdhKY6DmrRJ6mzSTzLU58