build(zig): migrate FFI to Zig 0.15 + real linked integration tests (#67)

- build.zig: 0.11 addStaticLibrary/addSharedLibrary API -> 0.15
  addLibrary/root_module; same artifacts (libochrance.a + libochrance.so,
  soname unchanged for the Idris %foreign contract)
- main.zig: callconv(.C) -> callconv(.c); Ed25519.KeyPair.create ->
  generateDeterministic (0.15 renames)
- test/integration_test.zig: replace never-compiling {{project}} template
  debris with a real C-ABI integration suite (17 tests: lifecycle, error
  paths, strings, BLAKE3 KAT, thread smoke) linked against libochrance.a
  and wired into 'zig build test'; drop the unguarded double-free assert
- test-ed25519*.zig: fix for 0.15 (fromBytes infallible; comptime Type
  printing)
- CI zig-ffi.yml + session-start hook + docs: Zig pin 0.11.0 -> 0.15.2

Verified locally: zig build test 24/24; dlopen link test PASS;
tests/ffi/run_ffi_test.sh 6/6 (production Merkle root = real BLAKE3
across the Idris->Zig boundary, != XOR spec root); tests/e2e_test.sh
27/27. Progresses #39.

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

Author: hyperpolymath

.claude/hooks/session-start.sh

@@ -7,7 +7,7 @@
 # The web container is ephemeral and cloned fresh, so the toolchains this repo
 # needs are reinstalled at session start:
 #   - Idris2  v0.8.0  (core framework, proofs, parser, verification)
-#   - Zig     0.11.0  (cryptographic FFI in ffi/zig)
+#   - Zig     0.15.2  (cryptographic FFI in ffi/zig)
 #   - just            (build/recipe runner; `just build`, `just check`, ...)
 #   - Agda    2.6.3   (estate formal-verification toolchain)
 #
@@ -41,10 +41,10 @@ if ! { have just && have agda && have idris2; }; then
     || log "WARN: some apt packages failed to install"
 fi
 
-# --- Zig 0.11.0 via the PyPI ziglang package (ziglang.org is blocked) -------
+# --- Zig 0.15.2 via the PyPI ziglang package (ziglang.org is blocked) -------
 if ! have zig; then
-  log "installing Zig 0.11.0 via PyPI ziglang ..."
-  if pip3 install --break-system-packages --quiet "ziglang==0.11.0"; then
+  log "installing Zig 0.15.2 via PyPI ziglang ..."
+  if pip3 install --break-system-packages --quiet "ziglang==0.15.2"; then
     cat > /usr/local/bin/zig <<'SH'
 #!/bin/sh
 # Thin shim exposing the PyPI `ziglang` package as a `zig` command.

.github/workflows/zig-ffi.yml

@@ -26,10 +26,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
-      - name: Set up Zig 0.11.0
+      - name: Set up Zig 0.15.2
         uses: mlugg/setup-zig@d1434d08867e3ee9daa34448df10607b98908d29 # v2.2.1
         with:
-          version: 0.11.0
+          version: 0.15.2
       - name: Build (libochrance.so + libochrance.a)
         working-directory: ffi/zig
         run: zig build

ROADMAP.adoc

@@ -151,7 +151,7 @@ Target: Production-ready filesystem verification for OSTree deployments
 === Required
 
 * **Idris2** 0.8.0+ (dependent types, totality checking)
-* **Zig** 0.11+ (FFI implementation)
+* **Zig** 0.15+ (FFI implementation)
 * **BLAKE3** (cryptographic hashing)
 
 === Optional (Phase 2+)

ffi/zig/build.zig

@@ -1,7 +1,8 @@
 // SPDX-License-Identifier: MPL-2.0
 // Copyright (c) Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
 //
-// Minimum Zig version: 0.11.0
+// Minimum Zig version: 0.15.0 (Build.addLibrary / root_module API; for the
+// old 0.11 addStaticLibrary/addSharedLibrary form see git history)
 // Required for: std.crypto.hash.Blake3, C ABI export, @memcpy builtin
 //
 const std = @import("std");
@@ -10,44 +11,58 @@ pub fn build(b: *std.Build) void {
     const target = b.standardTargetOptions(.{});
     const optimize = b.standardOptimizeOption(.{});
 
-    // Build libochrance.so shared library
-    const lib = b.addStaticLibrary(.{
-        .name = "ochrance",
-        .root_source_file = .{ .cwd_relative = "src/main.zig" },
+    // One module definition shared by every artifact. libc is required by
+    // std.heap.c_allocator (used by the handle lifecycle) and is the natural
+    // choice for a C-ABI FFI library.
+    const mod = b.createModule(.{
+        .root_source_file = b.path("src/main.zig"),
         .target = target,
         .optimize = optimize,
+        .link_libc = true,
     });
 
-    // libc is required by std.heap.c_allocator (used by the handle lifecycle)
-    // and is the natural choice for a C-ABI FFI library.
-    lib.linkLibC();
-    b.installArtifact(lib);
+    // Static libochrance.a
+    const static_lib = b.addLibrary(.{
+        .name = "ochrance",
+        .linkage = .static,
+        .root_module = mod,
+    });
+    b.installArtifact(static_lib);
 
-    // Also create a shared library version (libochrance.so) — this is what the
-    // Idris2 FFI loads at runtime. The name MUST be "ochrance" so the artifact is
-    // libochrance.so: the Idris bindings declare `%foreign "C:blake3_hash,
-    // libochrance"` (ochrance-core/Ochrance/FFI/Crypto.idr), so the runtime loader
-    // resolves the soname libochrance.so. Any other shared-library name would never
-    // be found. A static libochrance.a and a shared libochrance.so share the base
+    // Shared libochrance.so — this is what the Idris2 FFI loads at runtime.
+    // The name MUST be "ochrance" so the artifact is libochrance.so: the Idris
+    // bindings declare `%foreign "C:blake3_hash, libochrance"`
+    // (ochrance-core/Ochrance/FFI/Crypto.idr), so the runtime loader resolves
+    // the soname libochrance.so. Any other shared-library name would never be
+    // found. A static libochrance.a and a shared libochrance.so share the base
     // name without clashing (distinct extensions).
-    const shared_lib = b.addSharedLibrary(.{
+    const shared_lib = b.addLibrary(.{
         .name = "ochrance",
-        .root_source_file = .{ .cwd_relative = "src/main.zig" },
-        .target = target,
-        .optimize = optimize,
+        .linkage = .dynamic,
+        .root_module = mod,
     });
-    shared_lib.linkLibC();
     b.installArtifact(shared_lib);
 
-    // Tests
+    // Unit tests (in-module test blocks: KAT vectors, Ed25519 round-trip)
     const tests = b.addTest(.{
-        .root_source_file = .{ .cwd_relative = "src/main.zig" },
-        .target = target,
-        .optimize = optimize,
+        .root_module = mod,
+    });
+
+    // Integration tests: extern declarations linked against libochrance.a,
+    // exercising the C ABI exactly as an external consumer (Idris2) does.
+    const integration_tests = b.addTest(.{
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("test/integration_test.zig"),
+            .target = target,
+            .optimize = optimize,
+            .link_libc = true,
+        }),
     });
-    tests.linkLibC();
+    integration_tests.linkLibrary(static_lib);
 
     const run_tests = b.addRunArtifact(tests);
-    const test_step = b.step("test", "Run unit tests");
+    const run_integration_tests = b.addRunArtifact(integration_tests);
+    const test_step = b.step("test", "Run unit + integration tests");
     test_step.dependOn(&run_tests.step);
+    test_step.dependOn(&run_integration_tests.step);
 }

ffi/zig/src/main.zig

@@ -210,7 +210,7 @@ export fn ochrance_build_info() [*:0]const u8 {
 //==============================================================================
 
 /// Callback function type (C ABI)
-pub const Callback = *const fn (u64, u32) callconv(.C) u32;
+pub const Callback = *const fn (u64, u32) callconv(.c) u32;
 
 /// Register a callback
 export fn ochrance_register_callback(
@@ -260,7 +260,7 @@ export fn ochrance_is_initialized(handle: ?*Handle) u32 {
 //   int  ed25519_verify(const uint8_t sig[64], const uint8_t pk[32],
 //                       const uint8_t* msg, size_t msg_len);  // 1=valid, 0=invalid
 //
-// Backed by Zig's audited std.crypto (Zig 0.11.0). These replace the XOR/zero
+// Backed by Zig's audited std.crypto (Zig 0.15+). These replace the XOR/zero
 // placeholder hashes; see ROADMAP Phase 1 and docs/VALENCE_SHELL_BRIDGE.adoc,
 // which gate cryptographic-integrity claims on closing exactly this gap.
 //==============================================================================
@@ -368,7 +368,7 @@ test "sha3_256_hash known-answer vectors" {
 
 test "ed25519_verify accepts valid and rejects tampered" {
     const seed = [_]u8{42} ** 32;
-    const kp = try Ed25519.KeyPair.create(seed);
+    const kp = try Ed25519.KeyPair.generateDeterministic(seed);
     const message: []const u8 = "ochrance attestation";
     const signature = try kp.sign(message, null);
     const sig_bytes = signature.toBytes();

ffi/zig/test-ed25519-api.zig

@@ -4,7 +4,9 @@ const std = @import("std");
 const Ed25519 = std.crypto.sign.Ed25519;
 
 pub fn main() !void {
-    // Check what fields Signature has
-    const T = @typeInfo(Ed25519.Signature);
-    std.debug.print("Signature type: {}\n", .{T});
+    // Check what fields Signature has (std.builtin.Type is comptime-only, so
+    // enumerate field names rather than printing the Type value itself)
+    inline for (@typeInfo(Ed25519.Signature).@"struct".fields) |field| {
+        std.debug.print("Signature field: {s}: {s}\n", .{ field.name, @typeName(field.type) });
+    }
 }

ffi/zig/test-ed25519.zig

@@ -6,7 +6,7 @@ const Ed25519 = std.crypto.sign.Ed25519;
 pub fn main() !void {
     // Create a keypair
     const seed: [32]u8 = [_]u8{1} ** 32;
-    const keypair = try Ed25519.KeyPair.create(seed);
+    const keypair = try Ed25519.KeyPair.generateDeterministic(seed);
 
     // Sign something
     const message = "test";
@@ -19,8 +19,8 @@ pub fn main() !void {
     const sig_bytes = sig.toBytes();
     std.debug.print("Signature bytes length: {}\n", .{sig_bytes.len});
 
-    // Try fromBytes
-    const sig2 = try Ed25519.Signature.fromBytes(sig_bytes);
+    // Try fromBytes (infallible since Zig 0.12: returns Signature directly)
+    const sig2 = Ed25519.Signature.fromBytes(sig_bytes);
     _ = sig2;
 
     std.debug.print("Success!\n", .{});