feat(abi): generate the Zig and Rust wire enums from the normative Idris2 ABI (#120)

[hyperpolymath]

Closes #120.

The 16-connector wire contract existed in five hand-maintained copies that
agreed only by discipline. This makes three of them generated from the
normative Idris2 ABI, so drift becomes impossible rather than merely detected.

What generates what

src/Hypatia/ABI/Gen.idr + src/abi/hypatia-abi-gen.ipkg build an Idris2
executable that imports Hypatia.ABI.Types and evaluates it. It never
parses .idr text. Because Gen is the mainfile, --total is genuinely
re-checked for it (Idris2 only re-checks --total for the mainfile).

Generated	From
ffi/zig/src/connector_generated.zig	src/Hypatia/ABI/Types.idr
clients/rust/hypatia-client/src/connector_generated.rs	same
ffi/connectors.json	same

ffi/connectors.json previously called itself the "Golden source-of-truth",
which contradicts the ABI-authority ruling. That claim is gone.

zigIdent / rustIdent live in Gen, not in the ABI — the normative module
must not know about its consumers. Both are total with one clause per
constructor, so adding a connector without naming it is a build failure,
which is strictly stronger than a CI diff.

The hand-written unified-api-adapter.zig and connector.rs keep their own
tests. A generated test re-asserts its own source and proves nothing.

just abi-gen regenerates. Every generated file carries
// ABI source blob: <git hash-object src/Hypatia/ABI/Types.idr>.
⚠ Deliberate consequence: any byte change to Types.idr, comments
included, reddens the gate until just abi-gen is re-run and committed.
Touching the normative ABI should force you to look at what it generated.

Three things this PR found, stated plainly

1. Before this PR, neither "independent pin" on the wire contract executed
anywhere.

• The Zig comptime 16-connector assertion and the four tests in
  unified-api-adapter.zig were reachable from no test root. build.zig
  rooted main.zig, json_writer.zig, file_ops.zig and
  test/integration_test.zig; none import the adapter. They had never run,
  locally or in CI. This PR adds the fourth root — zig build test goes from
  3 tests to 7.
• cargo test --workspace is red on main for an unrelated pre-existing
  reason: integration/Cargo.toml requires testcontainers ^0.28 and
  testcontainers-modules ^0.15, which needs testcontainers ^0.27. That is
  unsatisfiable at the manifest level, so no lockfile can fix it and
  hypatia-client never gets compiled. Its five tests were verified against
  the generated enum in a standalone crate: 5 passed, 0 failed.

So abi-codegen-drift is currently the only executing pin on the wire
contract, and zig.yml makes the comptime assertion the second. That is an
improvement on nothing rather than "one of three independent pins".

2. The Elixir drift guard was reading a dead file. It bound its golden to
src/abi/Types.idr — a byte-identical copy that is compiled by nothing (the
live module is src/Hypatia/ABI/Types.idr; src/abi/hypatia-abi.ipkg sets
sourcedir = "..", which resolves to src/). The live ABI could drift and the
guard would stay green. This is instance 21 of the guard-asks-a-different-
question-than-its-consumer trap. Repointed, and a mutant proves the fix:
renaming a connector in the live module reddens the guard while the dead copy
is untouched.

The guard also gained a wire-id check. A mutant showed the name-only
version stayed green through an id swap — names and their order are
unchanged by a renumber, so a name-only guard sleeps through a C ABI break.

3. zig build test is red on main for pre-existing reasons unrelated to
this PR: three of four roots fail to compile against the Zig 0.16 std — 16 call
sites across six removed or relocated symbols (std.fs.cwd,
std.posix.getenv, std.fs.openFileAbsolute, std.fs.createFileAbsolute,
std.fs.deleteFileAbsolute, std.time.timestamp) plus an opaque type
declared with fields at main.zig:46. zig.yml therefore runs the maximal
green subset (zig test on the adapter), not the whole build. Filed as its own
issue rather than folded in here.

The gate

.github/workflows/abi-codegen-drift.yml, no paths: filter, so it fires
on every PR and can be made required later without the filter/required
deadlock. (verify-proofs.yml filters on src/abi/**, src/Hypatia/ABI/**
and verify/** and lists none of the generated targets, so a hand-edit to
a generated file would not have fired it.)

It regenerates into $RUNNER_TEMP and diffs — never in place with
git diff. Measured, in an isolated repo: a no-op generator + git diff
produces an empty diff, rc=0, reads GREEN. The temp-dir design on the same
no-op prints connectors emitted: 0 / files compared: 0 of 3 and fails.

It prints its denominator and fails on a zero one. It does not assert
N == 16 — that would be a sixth hand-written 16; the count is the proof's
job (connectorCount = Refl).

It reuses verify-proofs.yml's Idris2 install verbatim, including the same
cache key so it shares that warm cache.

Mutants — a passing gate proves nothing until one dies

Every red below was verified to be a drift or assertion failure, not a compile
error.

#	Mutant	Result
1	hand-edit a generated Zig wire name	gate RED, guard RED (independently)
2	swap wire ids 3↔4 in the live ABI, do not regenerate	gate RED on all 3 files; guard initially GREEN → blind spot → guard strengthened → now RED
3a	add a 17th connector, do not name it in Gen	generator BUILD FAILS: rustFile,variant is not covering
3b	…then name it and regenerate	Zig comptime RED; Rust count_is_sixteen + from_id_round_trip RED
4	replace the generator with a silent no-op exiting 0	connectors emitted: 0 / files compared: 0 of 3, RED

Positive control, clean tree: gate rc=0 printing connectors emitted: 16 /
files compared: 3 of 3; guard 4/4; zig test 4/4; zig build test 7/7;
Rust 5/5; just abi-gen byte-identical and idempotent.

actions.lock

Hand-edited, purely additive: 6 insertions, 0 deletions — two workflow keys
in alphabetical position. Both actions already had dependency entries, so none
was added. Tags, not SHAs, because that is the format every one of the other 30
workflow entries uses; a lone SHA-pinned workflow would be inconsistent with
the lock in use. Fix/rewrite mode was not used — it has previously
de-pinned 24 SHAs and invented invalid uses: refs.

gh actions-lock --verify-local (offline, writes nothing) goes from
2 of 32 workflows failed: 4 not-pinned to
All 32 workflows have complete lockfile coverage.

This gate lands advisory

rules/branches/main on this repo returns [] — zero effective rules, proven
with a positive control (a repo returning 8 rule types) and a 404 negative
control. Optimus-Branch exists but is enforcement: disabled. So nothing
here can block anything until a ruleset requires it. Giving it teeth is an
owner action, tracked separately.

⚠ Do not enable Optimus-Branch for this — it carries five required
contexts whose reporting on hypatia PRs is unmeasured, and a required context
that never reports is how a default branch deadlocks.

Follow-ups (issues, not blockers)

• Delete the six duplicated src/abi/*.idr modules and correct the ~15 prose
  references — the agreed immediately-following PR.
• Zig 0.16 std migration (the 16 call sites above).
• The integration/ testcontainers conflict. Note DEBT-REGISTER CI-1 blames
  "a stale dtolnay/rust-toolchain@stable pin … 13 jobs die at Set up job" —
  that is now wrong; the jobs start and die at cargo resolution.
• mise.toml pins zig = "latest" — a floating pin.
• verification/PROOF-STATUS.adoc is stale.
• IDApTIK docs/abi/ABI-AUTHORITY.md should repoint to
  src/Hypatia/ABI/Types.idr.

🤖 Generated with Claude Code

https://claude.ai/code/session_0113HQM9LVGkNCzU1WwkJZSV

---

Residue, filed as issues (added post-merge)

Per the standing rule that a new finding is an issue, not a merge blocker —
each with explicit acceptance criteria:

• Migrate ffi/zig to the Zig 0.16 std (3 of 4 test roots do not compile) #812 — Migrate ffi/zig to the Zig 0.16 std. 3 of the 4 test roots do not
  compile; 16 call sites (std.fs.cwd ×5, std.posix.getenv ×3,
  std.fs.deleteFileAbsolute ×3, std.fs.openFileAbsolute ×2,
  std.fs.createFileAbsolute ×2, std.time.timestamp ×1), plus opaque types
  cannot have fields at main.zig:46. This is why zig.yml roots only
  unified-api-adapter.zig rather than zig build test.
• mise.toml pins zig = "latest" — a floating pin that disagrees with zig.yml #813 — mise.toml pins zig = "latest", disagreeing with zig.yml's
  pinned 0.16.0.
• cargo test --workspace is red on main: unsatisfiable testcontainers conflict (DEBT-REGISTER CI-1 names the wrong cause) #814 — cargo test --workspace is red on main: unsatisfiable
  testcontainers ^0.28 vs testcontainers-modules ^0.15 → ^0.27. Records
  that DEBT-REGISTER CI-1 names the wrong cause — it blames a stale
  dtolnay/rust-toolchain@stable pin and says "13 jobs die at Set up job";
  the jobs actually start and die at cargo resolution.
• Delete the six duplicated src/abi/*.idr modules and repoint ~15 references #815 — Delete the six duplicated src/abi/*.idr modules and repoint the
  ~15 prose references. The agreed immediate follow-up to this PR.
• verification/PROOF-STATUS.adoc is stale: wrong path, wrong LOC, wrong proofs #816 — verification/PROOF-STATUS.adoc is stale: wrong path, wrong LOC
  (140 vs 242), wrong proofs.
• Repoint docs/abi/ABI-AUTHORITY.md: the Idris2 ABI is normative, and the Zig/Rust/JSON files are now generated metadatastician/IDApTIK#137 — Repoint docs/abi/ABI-AUTHORITY.md at
  src/Hypatia/ABI/Types.idr and re-digest.

Discovered after merge:

• fix(ci): install the Chez support tree so the ABI drift gate can pass #817 — this PR's own ABI codegen drift gate shipped red: compiling
  an Idris2 executable needs the Chez support tree, which the cache shared with
  verify-proofs.yml never carried because that workflow only builds
  libraries. Fixed forward.
• governance / Actions lockfile verify is red on every PR: #810 bumped 7 actions without refreshing actions.lock #818 — governance / Actions lockfile verify is red on every PR because
  chore(deps): bump the actions group with 7 updates #810 bumped 7 actions without refreshing actions.lock. Not caused by this
  PR; every finding is on a workflow it does not touch.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 96083ec5-4027-4b4c-81f0-eb110eb7acbc

📥 Commits

Reviewing files that changed from the base of the PR and between 0157a9b and 086998f.

⛔ Files ignored due to path filters (1)

• .github/workflows/actions.lock is excluded by !**/*.lock

📒 Files selected for processing (14)

• .github/workflows/abi-codegen-drift.yml
• .github/workflows/zig.yml
• Justfile
• clients/rust/hypatia-client/src/connector.rs
• clients/rust/hypatia-client/src/connector_generated.rs
• clients/rust/hypatia-client/src/lib.rs
• ffi/connectors.json
• ffi/zig/build.zig
• ffi/zig/src/connector_generated.zig
• ffi/zig/src/unified-api-adapter.zig
• src/Hypatia/ABI/Gen.idr
• src/Hypatia/ABI/Types.idr
• src/abi/hypatia-abi-gen.ipkg
• test/unified-api-adapter-contract_test.exs

 _________________________________________________________________
< You sanitized... the wrong thing. That's impressively specific. >
 -----------------------------------------------------------------
  \
   \   (\__/)
       (•ㅅ•)
       / 　 づ

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• 🔴 Error committing to branch - (🔄 Check to retry)
• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

❌ Failed to create Coding Agent finishing-touch task. Please try again.