chore: port the ABI-FFI gate from Python to Julia (RSR-H4: no Python) (#174)

## Summary

Clears the one pre-existing red on the estate's `governance / Language /
package anti-pattern policy` check. `scripts/abi-ffi-gate.py` was the
repo's **last Python file** (RSR-H4 bans Python — Julia for
scripts/data, Rust for systems), and the whole-tree scanner flags it.
Rather than suppress the scanner, this **ports the gate to Julia** and
removes the `.py`, so the check goes green *and* the ABI↔FFI conformance
gate keeps doing its job.

(Follow-up to #173 — this is the cleanup of the lone pre-existing
failure carried on #172/#173.)

## Changes

- **`scripts/abi-ffi-gate.jl`** (new) — a 1:1 Julia port of the former
Python gate (Julia PCRE maps directly onto Python `re`). Same three
checks, same messages, same exit codes:
  1. the Zig FFI carries no unrendered `{{...}}` template tokens;
2. every `%foreign "C:<name>"` symbol in the ABI `.idr` sources is
`export fn`-ed by the Zig FFI;
3. the Idris `resultToInt` map and the Zig `Result = enum(c_int)` agree
on **names and values** (`Error`/`err` unified).
- **`.github/workflows/abi-ffi-gate.yml`** — the `ABI ↔ FFI structural
conformance` job now installs the pinned **Julia 1.11.5** release
tarball (mirroring the adjacent `zig-build` job's pinned-tarball
pattern) and runs `julia scripts/abi-ffi-gate.jl`.
- **`scripts/abi-ffi-gate.py`** (removed) — the last Python file in the
repo.

## RSR Quality Checklist

### Required

- [x] Tests pass — gate runs clean locally (julia 1.11.5);
`cargo`/Zig/Idris surfaces untouched
- [x] Code is formatted — idiomatic Julia
- [x] Linter is clean
- [x] **No banned language patterns — this PR *removes* the last Python
file** (RSR-H4)
- [x] No `unsafe` blocks without `// SAFETY:` — n/a
- [x] No banned functions
- [x] SPDX license header present on `abi-ffi-gate.jl` (MPL-2.0)
- [x] No secrets, credentials, or `.env` files

### As Applicable

- [x] ABI/FFI changes validated — the conformance gate's behaviour is
preserved (verified below)
- [ ] State files / CHANGELOG — no released-version change

## Testing

Verified locally with **julia 1.11.5** against this tree:

```
# OK path is byte-identical to the Python it replaces:
$ diff <(python3 abi-ffi-gate.py) <(julia abi-ffi-gate.jl)   → identical
  ABI-FFI GATE: OK (verisimiser) — 24 ABI functions exported, 8 result codes match   (exit 0)
```

Adversarial (the gate must **fail** on drift) — each returns exit 1 with
the right diagnosis:

| Injected drift | Result |
|---|---|
| `null_pointer = 4` → `9` in the Zig enum | ❌ "Result-code map differs
(name or value)" |
| remove an `export fn` | ❌ "1 ABI function(s) not exported by the Zig
FFI" |
| add a `{{PROJECT_NAME}}` token to the Zig | ❌ "Zig FFI has unrendered
template tokens" |

So the port is behaviour-equivalent **and** non-vacuous.

## Screenshots

n/a (script + workflow)

---

🤖 Generated with [Claude Code](https://claude.com/claude-code)


---
_Generated by [Claude
Code](https://claude.ai/code/session_01JdqVWGSSv36Ph8ZWvizGMp)_

Co-authored-by: Claude <noreply@anthropic.com>

Author: hyperpolymath

.github/workflows/abi-ffi-gate.yml

@@ -21,8 +21,13 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+      - name: Install Julia 1.11.5
+        run: |
+          curl -fsSL https://julialang-s3.julialang.org/bin/linux/x64/1.11/julia-1.11.5-linux-x86_64.tar.gz -o /tmp/julia.tar.gz
+          tar -xf /tmp/julia.tar.gz -C /tmp
+          echo "/tmp/julia-1.11.5-linux-x86_64/bin" >> "$GITHUB_PATH"
       - name: Run ABI-FFI gate
-        run: python3 scripts/abi-ffi-gate.py
+        run: julia scripts/abi-ffi-gate.jl
 
   zig-build:
     name: Zig FFI builds + tests (Zig 0.14.0)

scripts/abi-ffi-gate.jl

@@ -0,0 +1,116 @@
+#!/usr/bin/env julia
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+#
+# abi-ffi-gate.jl — fail (exit 1) if the Zig FFI does not conform to the Idris2
+# ABI. The Idris2 ABI is the source of truth. Checks, with no compile toolchain
+# needed (pure base-Julia text analysis):
+#
+#   1. the Zig FFI carries no unrendered `{{...}}` template tokens;
+#   2. every `%foreign "C:<name>"` symbol declared anywhere in the ABI .idr
+#      sources is exported by the Zig FFI (`export fn <name>`);
+#   3. the Zig `Result = enum(c_int)` and the Idris `resultToInt` agree on BOTH
+#      names and integer values (the `Error`/`err` spelling is treated as one).
+#
+# Usage: julia scripts/abi-ffi-gate.jl [repo_root]   (defaults to cwd)
+#
+# Julia port of the former scripts/abi-ffi-gate.py (Python is banned estate-wide,
+# RSR-H4); behaviour is identical.
+
+"camelCase / PascalCase → snake_case (insert `_` before each non-initial capital)."
+camel_to_snake(s) = lowercase(replace(s, r"(?<!^)(?=[A-Z])" => "_"))
+
+"Canonical result-code key: lowercased, with `err`/`error` unified to `error`."
+function canon_rc(name)
+    n = lowercase(name)
+    (n == "err" || n == "error") ? "error" : n
+end
+
+"Return {variant => value} for the C-ABI `Result` enum (the `enum(c_int)` block whose `ok = 0`), or empty."
+function find_result_enum(zig::AbstractString)
+    best = Dict{String,Int}()
+    for m in eachmatch(r"enum\s*\(\s*c_int\s*\)\s*\{(.*?)\}"s, zig)
+        body = m.captures[1]
+        variants = Dict{String,Int}()
+        for vm in eachmatch(r"@?\"?([A-Za-z_][A-Za-z0-9_]*)\"?\s*=\s*(\d+)", body)
+            variants[canon_rc(vm.captures[1])] = parse(Int, vm.captures[2])
+        end
+        # The Result enum is the one starting at ok = 0.
+        if get(variants, "ok", nothing) == 0 && length(variants) > length(best)
+            best = variants
+        end
+    end
+    return best
+end
+
+"Collect every `*.idr` under `abi_dir`, skipping any `build/` output directory."
+function idr_sources(abi_dir::AbstractString)
+    files = String[]
+    isdir(abi_dir) || return files
+    for (root, _dirs, fs) in walkdir(abi_dir)
+        occursin("/build/", root * "/") && continue
+        for f in fs
+            endswith(f, ".idr") && push!(files, joinpath(root, f))
+        end
+    end
+    return files
+end
+
+function main(root::AbstractString)::Int
+    name = basename(rstrip(abspath(root), '/'))
+    abi_dir = joinpath(root, "src/interface/abi")
+    zig_path = joinpath(root, "src/interface/ffi/src/main.zig")
+    errs = String[]
+
+    idr_files = idr_sources(abi_dir)
+    if isempty(idr_files)
+        println("ABI-FFI GATE: SKIP ($name) — no Idris2 ABI .idr files under $abi_dir")
+        return 0
+    end
+    if !isfile(zig_path)
+        println("ABI-FFI GATE: FAIL ($name) — no Zig FFI at $zig_path")
+        return 1
+    end
+
+    idr = join((read(p, String) for p in idr_files), "\n")
+    zig = read(zig_path, String)
+
+    # 1. unrendered template tokens
+    toks = sort(unique(String(m.match) for m in eachmatch(r"\{\{[A-Za-z0-9_]+\}\}", zig)))
+    isempty(toks) || push!(errs, "Zig FFI has unrendered template tokens: $(toks)")
+
+    # 2. foreign C symbols must be exported
+    csyms = sort(unique(String(m.captures[1]) for m in eachmatch(r"C:([A-Za-z0-9_]+)", idr)))
+    exports = Set(String(m.captures[1]) for m in eachmatch(r"export fn ([A-Za-z0-9_]+)", zig))
+    missing_syms = [s for s in csyms if !(s in exports)]
+    isempty(missing_syms) ||
+        push!(errs, "$(length(missing_syms)) ABI function(s) not exported by the Zig FFI: $(missing_syms)")
+
+    # 3. result-code map (names + values) must agree
+    idr_rc = Dict{String,Int}()
+    for m in eachmatch(r"resultToInt\s+([A-Za-z0-9]+)\s*=\s*(\d+)", idr)
+        idr_rc[canon_rc(camel_to_snake(m.captures[1]))] = parse(Int, m.captures[2])
+    end
+    zig_rc = find_result_enum(zig)
+    if !isempty(idr_rc) && isempty(zig_rc)
+        push!(errs, "no Zig `enum(c_int)` Result block (with `ok = 0`) found to compare result codes")
+    elseif !isempty(idr_rc) && !isempty(zig_rc) && idr_rc != zig_rc
+        push!(errs, "Result-code map differs (name or value):\n" *
+                    "      Idris resultToInt: $(sort(collect(idr_rc)))\n" *
+                    "      Zig   Result enum: $(sort(collect(zig_rc)))")
+    end
+
+    if !isempty(errs)
+        println("ABI-FFI GATE: FAIL ($name)")
+        for e in errs
+            println("  - " * e)
+        end
+        return 1
+    end
+    println("ABI-FFI GATE: OK ($name) — $(length(csyms)) ABI functions exported, " *
+            "$(length(idr_rc)) result codes match")
+    return 0
+end
+
+root = length(ARGS) >= 1 ? ARGS[1] : "."
+exit(main(root))