Closes #812. Closes #813. Closes #696. The Zig FFI tree did not compile. `zig build test` failed on all five roots, so the 18 C exports and 16 connectors were pinned only by the `abi-codegen-drift` text gate — never by a compiler. This migrates the tree to the Zig 0.16 std, then gates it. ## The five commits | Commit | Issue | What | |---|---|---| | `1145e0f` | #812 | Migrate the tree to the 0.16 std API — 16 call sites, all five roots | | `3ef3627` | #812 | Widen the CI job from one file to `zig build test`; rewrite the stale header | | `6642e96` | #696 | Pin the 18-symbol C ABI export surface | | `38478ee` | #813 | Pin `mise.toml` to Zig 0.16.0 and assert it against `ZIG_VERSION` | | `d7705a9` | #696 | Rebuild from a removed artefact in the export step | ## #812 — the migration 0.16 did not rename these symbols; it made I/O capability an explicit `Io` parameter. `std.fs` now exports only `path` and the base64 tables, and the real homes are `std.Io.Dir` and `std.Io.Clock`. Measured against the 0.16 std source rather than guessed, because a plausible guess here produces a migration that compiles and is wrong. **The C ABI does not change.** `src/Hypatia/ABI/FFI.idr` enumerates six normative ABI functions — `HealthCheck`, `ScanRepo`, `Dispatch`, `RecordOutcome`, `ForceLearningCycle`, `GetConfidence` — and those are exactly the six exports carrying no handle. Adding an `Io` parameter or a new init entry point would change the wire contract this FFI exists to pin. So the capability is acquired once at the `export fn` boundary (`src/runtime.zig`) and threaded explicitly inwards. Two decisions worth reviewing rather than skimming: - **`init_single_threaded`, deliberately.** `Io.Threaded.init` installs SIGIO and SIGPIPE handlers (`std/Io/Threaded.zig:1660-1661`), which a shared object loaded into a host process must not do. - **`getenv` via libc, deliberately.** 0.16 removed `getenv` from std and models the environment as a `process.Environ` given to the `Io` implementation — but `init_single_threaded` sets that block to `.empty` on every non-Windows target (`Threaded.zig:1675`). An `Io`-sourced lookup would return null for every key, and every `orelse default` would silently take the default. That is a symbol "fixed" by deletion wearing a passing test, which #812 forbids. `build.zig` sets `link_libc = true` on all six artifacts, so `getenv(3)` is the honest equivalent, and a positive-control test now fails unless the variable is read. Also fixed, and **not** a 0.16 change: `Handle` was declared `opaque` with two fields, a compile error under every Zig version. `main.zig` had therefore never compiled, which is why nothing caught the rest. ### The mutant A passing suite proves nothing until one dies. Mutating the *implementation* — `portFor`'s `+ 1` to `+ 2` in `unified-api-adapter.zig` — rather than a test literal, so the red proves the suite catches a real wire-layout defect: ``` error: 'unified-api-adapter.test.port layout matches v-lang reference' failed: expected 8001, found 8002 at ffi/zig/src/unified-api-adapter.zig:154 Build Summary: 9/11 steps succeeded (1 failed); 20/21 tests passed (1 failed) ``` All five roots still reported `compile test Debug native success`, so this is an **assertion failure, not a compile error** — which is what #812's third criterion asks for. Reverting restored rc=0. ### The workflow header Rewritten, not trimmed. Every factual claim in it was about the pre-migration tree: that `zig build test` is "independently RED on `main`", the measured `4/11 steps succeeded (3 failed); 7/7 tests passed`, the enumeration of the 16 un-migrated call sites and the `opaque`-with-fields defect at `main.zig:46`, and the instruction to widen the job "once the tree is migrated". ### The denominator guard Kept and re-derived, not dropped. `zig build test` reports through a different line than `zig test`, so the old awk — matching `All N tests passed` and `N of N tests passed` — would have matched nothing, read 0, and failed the step on arrival. Both forms were measured locally: ``` Build Summary: 11/11 steps succeeded; 21/21 tests passed Build Summary: 9/11 steps succeeded (1 failed); 20/21 tests passed (1 failed) ``` They share a field layout, so one parse covers both. Verified against the real green log, the failure line from the mutant run, and input with no summary line at all (yields 0, which fails). `--summary all` is now explicit: without it a fully cached build prints no summary line, so the guard would have nothing to parse on exactly the runs most likely to be green. The floor is **8, not 21**. #812 requires more than the 7 tests the single-file scope reached; an exact count would redden the gate every time someone adds a test. ## #696 — the C ABI export pin `MUST.contractile` states C ABI compatibility as an invariant and nothing verified it. The gate is `zig build` plus `nm -D --defined-only`, asserting exactly 18 `T hypatia_*` symbols. 18 is written as a **contract, not a measurement** — the error message says changing it is a deliberate ABI decision, because a gate whose expected value can be edited to match reality is not a gate. A count alone cannot see a rename that preserves it, so the six normative functions are also named individually. There is no C header in this repository to diff a full name set against; naming the normative six is the honest pin available. **Both mutants die:** | Mutant | Count | Result | |---|---|---| | Un-export `hypatia_version` | 18 → 17 | fails on the count | | Rename `hypatia_health_check` → `hypatia_healthcheck` | stays 18 | fails on the normative-name check | The second is the case the count alone cannot see, and the reason those six are named. The untouched tree passes before and after each. `d7705a9` came out of that exercise: running the gate after a *failed* build reported `exported: 18 (expected 18)` and passed, because `nm` read the shared object left by the previous build. Under `set -euo pipefail` a failed `zig build` aborts first, and a fresh runner has no stale artefact — but the step now removes the file before rebuilding, so the property does not depend on either. **#696's other half is already closed.** The six byte-identical `src/abi/*.idr` duplicates it names were deleted under #815; `src/abi/` now holds only the two `.ipkg` files and a README. **Not closed here:** #696's "For contrast" section recorded two documentation defects that are not part of either fix — `AFFIRMATION.adoc`'s "zero escape hatches" claim needing scoping, and `docs/proof-debt.md` citing a nonexistent `scripts/check-trusted-base.sh` and `check-trusted-base` job. Rather than let them close silently with this PR, they are **#831**. ## #813 — the version pin `mise.toml` said `zig = "latest"` while the workflow pinned `0.16.0`. Developers built with whatever Zig was current and CI built with 0.16.0, so a green CI result said nothing about the compiler anyone actually ran — and `latest` moves on its own, so the disagreement could appear with nobody touching the repository. The `Justfile` stated a **third** version: `asdf plugin add zig && asdf install zig 0.13.0`. Rather than update that literal to 0.16.0 — three places to keep in step, and a copy the assertion cannot see — it now says `mise install zig` and defers to the pin. Three stated versions become two, and the two are asserted equal. (asdf was the wrong tool to name regardless: this repository configures mise.) #813 says a comment naming the other file is the weakest acceptable form, so this is an **assertion**: a CI step parses the `zig` pin out of `mise.toml` and compares it to `ZIG_VERSION`, before the toolchain install so a disagreement fails in seconds. Verified in all four directions — the real file passes; a pin of `0.15.1` fails; a pin floated back to `latest` fails; a deleted `zig` line fails as "no pinned version", because mise.toml having no pin *is* the defect. And the pinned version is the one **measured** green, not assumed to be. ## Verification Every step body was run locally, verbatim, before pushing: ``` STEP: Agree with the mise.toml pin mise.toml zig = 0.16.0; ZIG_VERSION = 0.16.0 rc=0 STEP: Verify the toolchain 0.16.0 rc=0 STEP: Run the Zig tests Build Summary: 11/11 steps succeeded; 21/21 tests passed → tests run: 21 rc=0 STEP: Pin the C ABI export surface exported C functions: 18 (expected 18) all six normative names present rc=0 ``` Was: did not compile. `actions.lock` is untouched and stays valid — `.github/workflows/zig.yml` is already listed and **no `uses:` line changed** in this PR, which also avoids the `validate-spdx` staged-mode trap on any commit touching the lock. ## Also raised, not fixed here - **#831** — the two #696 documentation defects above. - **#832** — `mise.toml` also provisions `python` and `denojs`, both banned estate-wide, plus a Python-only toolchain (`pip`, `black`, `isort`, `ruff`, `pytest`) and `PYTHON*` env vars around them. Removing the two runtime lines alone would leave tools that cannot run, so it is its own change with its own blast radius rather than a rider on a Zig version pin. ## Note on enforcement `main` carries exactly one required check (`abi-codegen-drift`), so the Zig job lands **advisory**. It has no `paths:` filter, deliberately, so it stays eligible to be made required without the filter/required deadlock — making it required is an owner action. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_0113HQM9LVGkNCzU1WwkJZSV --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Uh oh!