Make the Zig FFI compile + memory-safety fixes + CI (W1-6) (#38)

## What & why

The Zig C-ABI FFI in `ffi/zig` did not compile and had no CI, so it
could rot
undetected while every other check stayed green. `main.zig` declared
`Handle` as
`opaque {}` yet gave it fields and `allocator.create(Handle)`d it (both
hard Zig
compile errors), `integration_test.zig` re-declared its own conflicting
`Handle`,
and `build.zig` referenced a missing header and bench file. This makes
the FFI
compile, memory-safe, and CI-checked.

**The FFI is EXPERIMENTAL:** the exported operations validate their
arguments and
enforce handle liveness but are PLACEHOLDERS — they are NOT backed by
the Julia
statistical core, and no Idris2 ABI is wired up. That is deliberate and
called out
in a status comment block at the top of `main.zig`; the documentation
reframe is
tracked separately (W2-4). This PR does not invent a Julia bridge.

## Changes

- **`ffi/zig/src/main.zig`** — `Handle` is now a real internal `struct`
(crossing
the C ABI only as an opaque `*Handle`). Added a `magic` liveness cookie
(`HANDLE_MAGIC`) that is poisoned (`HANDLE_FREED`) before the block is
released,
and checked on every entry point that dereferences a handle. Double-free
and
  use-after-free are now safe: a second `statistikles_free` returns
`.invalid_param` instead of a second `destroy()`; operations on a freed
handle
return an error rather than invoking UB. Fixed the
`statistikles_last_error`
ownership leak — error messages are program-lifetime string literals
(static
  storage), documented as a borrowed, never-freed pointer. Added
`export fn statistikles_abi_version() callconv(.C) u32` returning a
monotonic
  ABI number alongside the existing semantic version string.
- **`ffi/zig/test/integration_test.zig`** — imports the ONE shared
`Handle`/`Result`
from the root module (via the `statistikles` module wired in
`build.zig`) instead
of re-declaring them, so the tests and library can never drift on the
ABI. The
double-free test asserts the safe-error behaviour (`.invalid_param`),
not merely
  "should not crash".
- **`ffi/zig/build.zig`** — removed the dead references to the missing
`include/statistikles.h` and `bench/bench.zig`; wires `src/main.zig` in
as the
`statistikles` module for the integration tests; `zig build test` runs
both the
  unit and integration test suites.
- **`.github/workflows/zig.yml`** (NEW) — SHA-pinned `actions/checkout`
(`9c091bb2…` = v7.0.0) + SHA-pinned `mlugg/setup-zig` (`d1434d08…` =
v2.2.1)
pinning Zig **0.13.0**, running `zig build test --summary all` in
`ffi/zig`.
Matches the repo's SHA-pinning style; `permissions: read-all`;
step-level
  path/branch triggers only.

## Zig version

Built and CI-checked against **Zig 0.13.0**. The setup environment
shipped Zig
0.16.0, whose std Io redesign is incompatible with this code's dialect,
so the
workflow pins 0.13.0 (the version `build.zig` / the source target) via
`mlugg/setup-zig`.

## Verification

Local (WSL Debian, Zig 0.13.0 binary), `zig build test --summary all` in
`ffi/zig`:

```
Build Summary: 5/5 steps succeeded; 24/24 tests passed
```

The 24 tests include the memory-safety cases: double-free returns
`.invalid_param`
(not UB), operations on a freed handle are rejected, `free(null)` is a
safe no-op,
and `last_error` returns the same stable static pointer across calls (no
leak).
CI runs the identical `zig build test` on `ubuntu-latest`.

## Skipped / out of scope

Real Julia-backed FFI semantics, the Idris2 ABI, and the documentation
reframe
(W2-4) are intentionally out of scope per the work order.

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

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

.github/workflows/zig.yml

@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+#
+# Statistikles — Zig FFI Build + Test
+#
+# The C-ABI FFI in ffi/zig is EXPERIMENTAL (placeholder ops, not yet backed by
+# the Julia core), but it must compile and its memory-safety tests must pass so
+# it cannot silently rot. Builds and tests against Zig 0.13.0 — the version the
+# FFI's build.zig / source dialect targets.
+
+name: Zig FFI
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'ffi/zig/**'
+      - '.github/workflows/zig.yml'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'ffi/zig/**'
+      - '.github/workflows/zig.yml'
+  workflow_dispatch:
+
+permissions: read-all
+
+concurrency:
+  group: zig-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  zig-ffi:
+    name: Zig FFI — build + test
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+
+      - name: Setup Zig 0.13.0
+        uses: mlugg/setup-zig@d1434d08867e3ee9daa34448df10607b98908d29  # v2.2.1
+        with:
+          version: 0.13.0
+
+      - name: Build + test FFI
+        working-directory: ffi/zig
+        run: zig build test --summary all

ffi/zig/.gitignore

@@ -0,0 +1,4 @@
+# Zig build outputs
+.zig-cache/
+zig-cache/
+zig-out/

ffi/zig/build.zig

@@ -1,23 +1,28 @@
 // SPDX-License-Identifier: MPL-2.0
 // Copyright (c) Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
 // STATISTIKLES FFI Build Configuration
+//
+// Built and CI-checked against Zig 0.13.0.
 
 const std = @import("std");
 
 pub fn build(b: *std.Build) void {
     const target = b.standardTargetOptions(.{});
     const optimize = b.standardOptimizeOption(.{});
 
-    // Shared library (.so, .dylib, .dll)
+    // Shared library (.so, .dylib, .dll). The version must be passed here so the
+    // versioned-filename fields are computed at creation time (setting
+    // `lib.version` afterwards leaves them null and crashes installArtifact).
     const lib = b.addSharedLibrary(.{
         .name = "statistikles",
         .root_source_file = b.path("src/main.zig"),
         .target = target,
         .optimize = optimize,
+        .version = .{ .major = 0, .minor = 1, .patch = 0 },
     });
-
-    // Set version
-    lib.version = .{ .major = 0, .minor = 1, .patch = 0 };
+    // The FFI uses std.heap.c_allocator (malloc/free) so it interops with C
+    // consumers and `statistikles_free_string`; that requires libc.
+    lib.linkLibC();
 
     // Static library (.a)
     const lib_static = b.addStaticLibrary(.{
@@ -26,42 +31,46 @@ pub fn build(b: *std.Build) void {
         .target = target,
         .optimize = optimize,
     });
+    lib_static.linkLibC();
 
     // Install artifacts
     b.installArtifact(lib);
     b.installArtifact(lib_static);
 
-    // Generate header file for C compatibility
-    const header = b.addInstallHeader(
-        b.path("include/statistikles.h"),
-        "statistikles.h",
-    );
-    b.getInstallStep().dependOn(&header.step);
-
-    // Unit tests
+    // Unit tests (main.zig's own test blocks)
     const lib_tests = b.addTest(.{
         .root_source_file = b.path("src/main.zig"),
         .target = target,
         .optimize = optimize,
     });
+    lib_tests.linkLibC();
 
     const run_lib_tests = b.addRunArtifact(lib_tests);
 
-    const test_step = b.step("test", "Run library tests");
-    test_step.dependOn(&run_lib_tests.step);
-
-    // Integration tests
+    // Integration tests. Import src/main.zig as the `statistikles` module so the
+    // tests exercise the SAME Handle/Result types the library exports (one
+    // shared definition, no re-declared opaque types that can drift).
     const integration_tests = b.addTest(.{
         .root_source_file = b.path("test/integration_test.zig"),
         .target = target,
         .optimize = optimize,
     });
-
-    integration_tests.linkLibrary(lib);
+    integration_tests.root_module.addAnonymousImport("statistikles", .{
+        .root_source_file = b.path("src/main.zig"),
+        .target = target,
+        .optimize = optimize,
+    });
+    integration_tests.linkLibC();
 
     const run_integration_tests = b.addRunArtifact(integration_tests);
 
-    const integration_test_step = b.step("test-integration", "Run integration tests");
+    // `zig build test` runs BOTH the unit and integration tests.
+    const test_step = b.step("test", "Run library + integration tests");
+    test_step.dependOn(&run_lib_tests.step);
+    test_step.dependOn(&run_integration_tests.step);
+
+    // Keep a dedicated integration-only step for convenience.
+    const integration_test_step = b.step("test-integration", "Run integration tests only");
     integration_test_step.dependOn(&run_integration_tests.step);
 
     // Documentation
@@ -70,26 +79,12 @@ pub fn build(b: *std.Build) void {
         .target = target,
         .optimize = .Debug,
     });
+    docs.linkLibC();
 
     const docs_step = b.step("docs", "Generate documentation");
     docs_step.dependOn(&b.addInstallDirectory(.{
         .source_dir = docs.getEmittedDocs(),
         .install_dir = .prefix,
         .install_subdir = "docs",
     }).step);
-
-    // Benchmark (if needed)
-    const bench = b.addExecutable(.{
-        .name = "statistikles-bench",
-        .root_source_file = b.path("bench/bench.zig"),
-        .target = target,
-        .optimize = .ReleaseFast,
-    });
-
-    bench.linkLibrary(lib);
-
-    const run_bench = b.addRunArtifact(bench);
-
-    const bench_step = b.step("bench", "Run benchmarks");
-    bench_step.dependOn(&run_bench.step);
 }