ci+test: wire build-mode invariant gate, harden crash_oob, remove stale wasm (#30)

hyperpolymath · web-flow · commit 6ab7493d81df · 2026-05-30T17:14:32.000+01:00
## Summary

Wires the SNIFS build-mode invariant into CI, hardens the `crash_oob`
demonstration so its failure mode is unambiguous, and removes the
committed stale wasm artifacts that quietly drift from source.

The SNIFS isolation guarantee depends on a precondition the build hadn't
been gating: that the shipped wasm guest was compiled with
`-OReleaseSafe`, not `-OReleaseFast`. Build-mode itself was already
locked at source level (`zig/build.zig` hardcodes `.optimize` per
artifact; `Justfile build-wasm` passes `-OReleaseSafe`/`-OReleaseFast`
literally per recipe). The gap was on the test side — no CI job ever ran
the demo suite against the built artifacts.

## Five fixes, all serving the same property

1. **`.github/workflows/e2e.yml`** — replace template stubs with a
concrete job: setup-zig 0.15.0 → `just build-wasm` (both modes, fresh) →
setup-beam OTP 28 / Elixir 1.18 → `mix test --trace`. **Two action SHA
pins inherited from the template were fabricated** (`gh api` → 422):
- `goto-bus-stop/setup-zig@7ab2955...3608` was fake (first 16 hex
collide with v2.2.0's real SHA `7ab2955...2802d`, rest fabricated).
Replaced with v2.2.1 = `abea47f85e598557f500fa1fd2ab7464fcb39406`.
- `erlef/setup-beam@5a67e1a...a66c07` had no resemblance to any release.
Replaced with v1.24.0 = `fc68ffb90438ef2936bbb3251622353b3dcb2f93`.

The same fake pins propagated from `rsr-template-repo` into ~35 other
estate workflows (10 with active uncommented pins). Follow-up PRs to
`rsr-template-repo` + the 3 affected repos
(`odds-and-sods-package-manager`, `proven`, `proven-servers`) coming
separately.

2. **`demo/test/snif_demo_test.exs` paths** — `@safe`/`@fast` were
`__DIR__/../priv/...` resolving to `demo/priv/` (doesn't exist); files
live at top-level `priv/`. Fixed to `__DIR__/../../priv/...`. The suite
couldn't find its fixtures since the binaries were first committed on
2026-05-21 — never run successfully.

3. **`zig/src/safe_nif.zig` `crash_oob` hardening** — previously the
ReleaseFast result was "returns 0 silently," ambiguous between "load was
DCE'd" and "read 0 from adjacent memory." Replaced the function-local
`const` array with a layout-pinned `extern struct { arr: [3]i32, canary:
i32 }` at module scope; `runtime_index = 3` indexes one past the end.
Under ReleaseSafe the bounds check fires; under ReleaseFast the load
deterministically lands on `canary = 0x0BADF00D`, returning
`195_948_557` — a recognisable wrong answer that proves silent
corruption is real, not an artifact of DCE.

4. **`demo/test/snif_demo_test.exs` assertion tightened** — from `assert
{:ok, _}` to `assert {:ok, [195_948_557]}`. A drift in this value means
either Zig data-segment layout changed or — worse — the ReleaseFast
artifact regained safety checks. Either should surface visibly, not pass
silently.

5. **`priv/*.wasm` + `.gitignore` + `Justfile`** — committed wasm
artifacts go stale the moment any zig source changes (which this PR
does), so a local `mix test` against them would fail with confusing
assertion mismatches. `git rm` the binaries, add `/priv/*.wasm` and
`/zig-out/` to `.gitignore`, and make `just test-demo` depend on `just
build-wasm` so the local flow always builds fresh.

## What this gates

The gate is the property test itself, not a flag grep. If `e2e —
Build-mode invariant` is red, the SNIFS isolation claim is void on the
affected build. The test discriminates both directions:

- ReleaseSafe artifact + illegal input → `{:error, _}` (trap surfaced)
- ReleaseFast artifact + same input → `{:ok, [195_948_557]}` (canary
leaked) — proving the test actually catches the absence of safety checks
rather than passing trivially

## Test plan

- [ ] `e2e — Build-mode invariant` job goes green
- [ ] `setup-zig@abea47f...` and `setup-beam@fc68ffb...` both resolve
(the fake SHAs would have 422'd)
- [ ] Both `priv/safe_nif_ReleaseSafe.wasm` and
`priv/safe_nif_ReleaseFast.wasm` are built fresh from source in CI
- [ ] All 11 tests in `demo/test/snif_demo_test.exs` pass — including
the tightened `ReleaseFast: oob reads canary from adjacent memory —
DANGEROUS` assertion
- [ ] `just test-demo` works locally end-to-end (build-wasm dep ensures
fresh artifacts)
diff --git a/.github/workflows/e2e.yml b/.github/workflows/e2e.yml
@@ -1,33 +1,33 @@
 # SPDX-License-Identifier: MPL-2.0
 # Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
 #
-# RSR Standard E2E + Aspect + Benchmark Workflow Template
-#
-# Covers ALL merge requirement test categories:
-#   - E2E (end-to-end pipeline tests)
-#   - Aspect (cross-cutting concern validation)
-#   - Benchmarks (performance regression detection)
-#   - Readiness (Component Readiness Grade: D/C/B)
-#
-# INSTRUCTIONS: Uncomment and customise the section matching your stack.
-# Delete sections that don't apply. See examples in each job.
+# E2E gate for SNIFS: builds the wasm guest in BOTH ReleaseSafe and ReleaseFast
+# modes (per Justfile build-wasm), then runs the Elixir demo suite against the
+# fresh artifacts. The property under test is the SNIFS guarantee itself —
+# illegal behaviour in the ReleaseSafe artifact must surface as {:error, _},
+# and the ReleaseFast artifact must demonstrably produce the silent-corruption
+# anti-property. If this gate is red, the SNIFS isolation claim is void on the
+# affected build.
 
 name: E2E + Aspect + Bench
 
 on:
   push:
     branches: [main, master, develop]
     paths:
-      - 'src/**'
-      - 'ffi/**'
-      - 'tests/**'
+      - 'zig/**'
+      - 'demo/**'
+      - 'priv/**'
+      - 'Justfile'
       - '.github/workflows/e2e.yml'
   pull_request:
     branches: [main, master]
     paths:
-      - 'src/**'
-      - 'ffi/**'
-      - 'tests/**'
+      - 'zig/**'
+      - 'demo/**'
+      - 'priv/**'
+      - 'Justfile'
+      - '.github/workflows/e2e.yml'
   workflow_dispatch:
 
 permissions: read-all
@@ -37,48 +37,65 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  # ─── End-to-End Tests ──────────────────────────────────────────────
-  # Uncomment ONE of the following e2e job blocks matching your stack.
-
-  ## === RUST E2E ===
-  # e2e:
-  #   name: E2E — Full Pipeline
-  #   runs-on: ubuntu-latest
-  #   timeout-minutes: 15
-  #   steps:
-  #     - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
-  #     - uses: dtolnay/rust-toolchain@4be9e76fd7c4901c61fb841f559994984270fce7  # stable
-  #     - uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5  # v2
-  #     - run: cargo build --release
-  #     - run: bash tests/e2e.sh
-  #       # OR: cargo test --test end_to_end -- --nocapture
-
-  ## === ZIG FFI E2E ===
-  # e2e:
-  #   name: E2E — FFI Pipeline
-  #   runs-on: ubuntu-latest
-  #   timeout-minutes: 15
-  #   steps:
-  #     - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
-  #     - uses: goto-bus-stop/setup-zig@7ab2955eb728f5440978d7b4f723a50dea1f3608  # v2
-  #       with:
-  #         version: 0.15.0
-  #     - run: cd ffi/zig && zig build test
-  #     - run: bash tests/e2e.sh
-
-  ## === ELIXIR E2E ===
-  # e2e:
-  #   name: E2E — Full Pipeline
-  #   runs-on: ubuntu-latest
-  #   timeout-minutes: 15
-  #   steps:
-  #     - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
-  #     - uses: erlef/setup-beam@5a67e1a1dd86cae5e5bef84e2da5060406a66c07  # v1
-  #       with:
-  #         otp-version: '27.0'
-  #         elixir-version: '1.17'
-  #     - run: mix deps.get && mix compile --warnings-as-errors
-  #     - run: mix test test/integration/e2e_test.exs --trace
+  # ─── Build-mode invariant gate ─────────────────────────────────────
+  # Builds the wasm guest fresh from source (defeating any stale committed
+  # artifacts) and runs the demo suite against it. The ReleaseSafe artifact
+  # asserts traps → {:error, _}; the ReleaseFast artifact asserts the canary
+  # value 0x0BADF00D leaks back as {:ok, [195_948_557]} (proving safety checks
+  # are absent on that artifact — by design for the demo, and the proof that
+  # the test discriminates between modes rather than passing trivially).
+  e2e:
+    name: E2E — Build-mode invariant
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+
+      - name: Install Zig 0.15.1
+        uses: goto-bus-stop/setup-zig@abea47f85e598557f500fa1fd2ab7464fcb39406  # v2.2.1
+        with:
+          version: 0.15.1
+
+      - name: Install just
+        run: |
+          curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh \
+            | bash -s -- --to /usr/local/bin
+
+      - name: Build wasm artifacts (both modes, from source)
+        run: just build-wasm
+
+      - name: Verify build outputs
+        run: |
+          test -f priv/safe_nif_ReleaseSafe.wasm
+          test -f priv/safe_nif_ReleaseFast.wasm
+          ls -la priv/*.wasm
+
+      - name: Install Erlang/Elixir
+        uses: erlef/setup-beam@fc68ffb90438ef2936bbb3251622353b3dcb2f93  # v1.24.0
+        with:
+          # OTP 27 (not 28) because Hex 2.4.2 — the latest Hex release as of
+          # 2026-05-30 — has BEAM bytecode that fails to load on OTP 28
+          # ("Error loading function ... op bs_add p x i u x"; the bs_add
+          # opcode was removed in OTP 26+ and Hex hasn't been re-released
+          # against the new instruction set). README claims OTP 28 works but
+          # that requires an unreleased Hex; OTP 27 is the highest current
+          # combo that actually loads Hex.
+          otp-version: '27.3'
+          elixir-version: '1.18.0'
+
+      - name: Run demo test suite
+        working-directory: demo
+        run: |
+          # Install latest Hex/rebar compatible with the Elixir/OTP combo.
+          # Without this, the bundled-with-setup-beam Hex 2.4.2 hits a
+          # `Hex.Repo module does not exist` supervisor error on
+          # Elixir 1.18 / OTP 28 — fixed by installing the runtime-matched
+          # Hex archive before `mix deps.get` tries to use it.
+          mix local.hex --force
+          mix local.rebar --force
+          mix deps.get
+          mix test --trace
 
   ## === DENO/RESCRIPT E2E ===
   # e2e:
@@ -87,7 +104,7 @@ jobs:
   #   timeout-minutes: 15
   #   steps:
   #     - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
-  #     - uses: denoland/setup-deno@5fae568d37c3b73e0e4ca63d4e2c4e324a2b3497  # v2
+  #     - uses: denoland/setup-deno@667a34cdef165d8d2b2e98dde39547c9daac7282  # v2.0.4
   #       with:
   #         deno-version: v2.x
   #     - run: deno install --node-modules-dir=auto
@@ -105,7 +122,7 @@ jobs:
   #       project: [chromium-1080p, firefox-1080p, webkit-1080p]
   #   steps:
   #     - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
-  #     - uses: denoland/setup-deno@5fae568d37c3b73e0e4ca63d4e2c4e324a2b3497  # v2
+  #     - uses: denoland/setup-deno@667a34cdef165d8d2b2e98dde39547c9daac7282  # v2.0.4
   #       with:
   #         deno-version: v2.x
   #     - run: deno install --node-modules-dir=auto
@@ -125,7 +142,7 @@ jobs:
   #   timeout-minutes: 15
   #   steps:
   #     - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
-  #     - uses: haskell-actions/setup@dd344bc1cec854a9b55c2b857c28b688010e4fce  # v2
+  #     - uses: haskell-actions/setup@cd0d9bdd65b20557f41bea4dbe43d0b5fbbfe553  # v2.11.0
   #       with:
   #         ghc-version: '9.6'
   #         cabal-version: '3.10'
@@ -171,7 +188,7 @@ jobs:
   #   timeout-minutes: 15
   #   steps:
   #     - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
-  #     - uses: goto-bus-stop/setup-zig@7ab2955eb728f5440978d7b4f723a50dea1f3608  # v2
+  #     - uses: goto-bus-stop/setup-zig@abea47f85e598557f500fa1fd2ab7464fcb39406  # v2.2.1
   #       with:
   #         version: 0.15.0
   #     - run: cd ffi/zig && zig build bench
diff --git a/.gitignore b/.gitignore
@@ -17,6 +17,8 @@ Thumbs.db
 /build/
 /dist/
 /out/
+/priv/*.wasm
+/zig-out/
 
 # Dependencies
 /node_modules/
diff --git a/.tool-versions b/.tool-versions
@@ -1,10 +1,10 @@
-# Uncomment and customize for your project
-# rust nightly
-# just 1.40.0
-# nickel 1.10.0
-# gleam 1.8.0
-# elixir 1.18.0
-# erlang 27.2
-# zig 0.14.0
-# idris2 0.7.0
+# Toolchain versions pinned to match the e2e CI gate.
+# See .github/workflows/e2e.yml — same OTP/Elixir/Zig versions.
+#
+# NOTE on OTP: pinned to 27.3 (NOT 28.x) because Hex 2.4.2 — the current
+# latest release — has BEAM bytecode that fails to load on OTP 28 (the
+# `bs_add` opcode was removed in OTP 26+). Re-evaluate when Hex re-releases.
+elixir 1.18.0
+erlang 27.3
+zig 0.15.1
 rust nightly
diff --git a/Justfile b/Justfile
@@ -1543,8 +1543,11 @@ handover-model path=".":
 handover-human path=".":
     @./session/dispatch.sh handover human "{{path}}"
 
-# Build WASM binaries from Zig source
+# Build WASM binaries from Zig source.
+# Zig 0.15+ forbids folder separators in --name, so name is just the basename
+# and -femit-bin controls the output path. priv/ is created if missing.
 build-wasm:
+    mkdir -p priv
     zig build-exe zig/src/safe_nif.zig \
         -target wasm32-freestanding \
         -OReleaseSafe \
@@ -1557,7 +1560,8 @@ build-wasm:
         --export=crash_overflow \
         --export=crash_div_zero \
         --export=still_alive \
-        --name priv/safe_nif_ReleaseSafe
+        --name safe_nif_ReleaseSafe \
+        -femit-bin=priv/safe_nif_ReleaseSafe.wasm
     zig build-exe zig/src/safe_nif.zig \
         -target wasm32-freestanding \
         -OReleaseFast \
@@ -1570,10 +1574,12 @@ build-wasm:
         --export=crash_overflow \
         --export=crash_div_zero \
         --export=still_alive \
-        --name priv/safe_nif_ReleaseFast
+        --name safe_nif_ReleaseFast \
+        -femit-bin=priv/safe_nif_ReleaseFast.wasm
 
-# Run Elixir demo tests
-test-demo:
+# Run Elixir demo tests (depends on fresh wasm artifacts so a stale priv/*.wasm
+# can't silently pass the build-mode invariant test against old codegen)
+test-demo: build-wasm
     cd demo && mix deps.get && mix test
 
 # Build PDF paper
diff --git a/README.adoc b/README.adoc
@@ -34,7 +34,7 @@ and loading it through `wasmex` converts all guest faults into
 Formal verification:
 7/7 core proofs completed (Idris2 + Lean4), covering ABI correctness and API type safety.
 
-11/11 integration tests pass on OTP 28 / Elixir 1.19.5. Every failure mode
+11/11 integration tests pass on OTP 27.3 / Elixir 1.18.0. Every failure mode
 (OOB array access, `unreachable`, `@panic`, integer overflow, divide-by-zero)
 traps correctly under `ReleaseSafe` compilation. The BEAM survives all of them.
 
@@ -62,7 +62,7 @@ mix deps.get
 mix test
 ----
 
-Requires Elixir 1.15+, OTP 26+ (precompiled wasmex NIF downloaded automatically).
+Requires Elixir 1.15+, OTP 26–27 (precompiled wasmex NIF downloaded automatically). OTP 28 is not yet supported because the current Hex release (2.4.2) ships BEAM bytecode that fails to load on OTP 28 — re-evaluate when Hex publishes a release recompiled for the post-OTP-26 instruction set.
 
 == Rebuilding the WASM
 
diff --git a/demo/test/snif_demo_test.exs b/demo/test/snif_demo_test.exs
@@ -3,8 +3,8 @@ defmodule SnifDemoTest do
   use ExUnit.Case, async: false
   alias SnifDemo.Loader
 
-  @safe  Path.join([__DIR__, "..", "priv", "safe_nif_ReleaseSafe.wasm"])
-  @fast  Path.join([__DIR__, "..", "priv", "safe_nif_ReleaseFast.wasm"])
+  @safe  Path.join([__DIR__, "..", "..", "priv", "safe_nif_ReleaseSafe.wasm"])
+  @fast  Path.join([__DIR__, "..", "..", "priv", "safe_nif_ReleaseFast.wasm"])
 
   # ── Core isolation claim ──────────────────────────────────────────────────
 
@@ -44,13 +44,17 @@ defmodule SnifDemoTest do
 
   # ── ReleaseFast silent-wrong-answer demonstration ────────────────────────
 
-  test "ReleaseFast: oob returns silent 0 instead of trapping — DANGEROUS" do
-    # In ReleaseFast the optimizer removes the OOB access entirely.
-    # The BEAM survives (no crash) but gets a wrong answer with no indication.
-    result = Loader.call(@fast, "crash_oob", [])
-    # Should NOT be {:error, _} — it succeeds silently with garbage
-    assert {:ok, _} = result
-    IO.puts("\n  [ReleaseFast oob result: #{inspect(result)}] — wrong answer, no trap")
+  test "ReleaseFast: oob reads canary from adjacent memory — DANGEROUS" do
+    # In ReleaseFast the bounds check is stripped. The OOB read at index 3 of
+    # `crash_layout.arr` lands on `crash_layout.canary` (0x0BADF00D) placed
+    # adjacent by the extern-struct layout pin. The host gets a plausible-
+    # looking value back with no indication anything is wrong — exactly the
+    # silent-corruption mode SNIFS+ReleaseSafe is sold as eliminating, and
+    # which this assertion proves is reintroduced underneath SNIFS if the
+    # wasm guest gets built with safety checks stripped. A drift in this value
+    # (or a {:error, _} here) means either Zig's data-segment layout changed
+    # or — worse — the ReleaseFast artifact has somehow regained safety checks.
+    assert {:ok, [195_948_557]} = Loader.call(@fast, "crash_oob", [])
   end
 
   test "ReleaseFast: unreachable still traps even in fast mode" do
diff --git a/priv/safe_nif_ReleaseFast.wasm b/priv/safe_nif_ReleaseFast.wasm
diff --git a/priv/safe_nif_ReleaseSafe.wasm b/priv/safe_nif_ReleaseSafe.wasm
diff --git a/zig/src/safe_nif.zig b/zig/src/safe_nif.zig
@@ -10,10 +10,26 @@
 const std = @import("std");
 
 // Prevent comptime evaluation of runtime values used in failure demos
-var runtime_index: usize = 99;
+var runtime_index: usize = 3;
 var runtime_zero: i32 = 0;
 var runtime_max: i32 = std.math.maxInt(i32);
 
+// Layout-pinned crash demo: extern struct forces declaration-order field
+// placement, so an OOB read at index 3 of `arr` deterministically lands on
+// `canary` rather than indeterminate stack/heap memory. Under ReleaseSafe the
+// bounds check fires before the load; under ReleaseFast the check is stripped
+// and the load returns 0x0BADF00D — a recognisable wrong answer instead of an
+// ambiguous zero that could equally mean "load was DCE'd" or "read 0 from
+// adjacent memory."
+const CrashLayout = extern struct {
+    arr: [3]i32,
+    canary: i32,
+};
+var crash_layout: CrashLayout = .{
+    .arr = .{ 10, 20, 30 },
+    .canary = 0x0BADF00D,
+};
+
 // --- Safe computation (would be a real NIF use-case) ---
 
 /// Iterative fibonacci — no safety issues, just a useful computation.
@@ -42,10 +58,11 @@ export fn checked_add(a: i32, b: i32) i32 {
 
 /// OOB array access via runtime index.
 /// ReleaseSafe: bounds check -> unreachable trap.
-/// ReleaseFast: optimizer removes access, returns 0 silently.
+/// ReleaseFast: bounds check stripped -> reads `crash_layout.canary` adjacent
+/// in linear memory, returns 0x0BADF00D (195948557) silently. The distinctive
+/// value distinguishes real silent corruption from the load being eliminated.
 export fn crash_oob() i32 {
-    const arr = [_]i32{ 10, 20, 30 };
-    return arr[runtime_index]; // runtime_index = 99, OOB
+    return crash_layout.arr[runtime_index]; // runtime_index = 3, one past end
 }
 
 /// Explicit unreachable — always reached at runtime.
