feat(l1-prep): scaffold all missing L1 Cap'n Proto artifacts

Five files land as pre-work so L1 can start immediately once the L3
gate opens (T1 green ≥ 7 days), with no design bikeshedding:

schemas/VERSIONING.md
  Versioning policy: safe vs breaking changes, schemaVersion field
  convention, capnp-gen regeneration requirement, Idris2 ABI update
  instructions, multi-language consumer table.

src/julia/ipc.jl  (module EchidnaIPC)
  Julia IPC stub mirroring Rust src/rust/ipc/mod.rs: connect_ipc()
  with UDS primary / TCP fallback, gnn_rank_request() throwing until
  L1 wave 1 lands, ipc_available() probe, Option A/B decision block.

src/abi/EchidnaABI/CapnSchemas.idr
  Idris2 ABI mirror of all 7 Cap'n Proto message types (ProofGoal 6
  fields, OutcomeTag 8 variants, NodeKind 7, EdgeKind 8, DangerLevel 4,
  DispatchStrategy 3). 13 constructive proofs: schemaIdNonZero, 6×
  bounded (LTE n 256 via %search), 5× injective Fin maps, field-count
  Refl witnesses, topKDefaultPositive. Zero believe_me, zero postulate.

ffi/zig/src/capnp_bridge.zig
  Zig C-ABI bridge: EchidnaGnnRequest/Response extern structs,
  echidna_capnp_connect (UDS via std.net), echidna_capnp_close,
  echidna_capnp_gnn_rank (stub returning -2 until bindings land),
  echidna_capnp_free_response, echidna_capnp_status_message.
  Thread-local error storage matches main.zig pattern.

Justfile: capnp-gen recipe
  `capnp compile -orust schemas/echidna.capnp -I /usr/include` with
  guard for missing capnp binary and commit reminder.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: hyperpolymath

Justfile

@@ -358,6 +358,14 @@ doc:
 update:
     cargo update
 
+# Regenerate Cap'n Proto bindings from schemas/echidna.capnp.
+# Requires capnp compiler: https://capnproto.org/install.html
+# Output: src/rust/ipc/echidna_capnp.rs (checked in; do not edit by hand)
+capnp-gen:
+    @command -v capnp >/dev/null 2>&1 || { echo "capnp compiler not found — install from https://capnproto.org/install.html"; exit 1; }
+    capnp compile -orust schemas/echidna.capnp -I /usr/include
+    @echo "Rust bindings generated. Commit src/rust/ipc/echidna_capnp.rs."
+
 # Audit dependencies
 audit:
     cargo audit

ffi/zig/src/capnp_bridge.zig

@@ -0,0 +1,193 @@
+// ECHIDNA Cap'n Proto C-ABI Bridge
+//
+// C-compatible functions for IPC between the Rust core and the Julia ML
+// layer over Unix domain sockets. Actual Cap'n Proto serialisation will
+// be generated by `just capnp-gen` in L1 wave 1; until then the
+// gnn_rank function is a clearly-labelled stub that returns an error
+// code so callers can wire the ABI boundary and test error paths now.
+//
+// Error reporting follows the same pattern as main.zig:
+//   - Return value: 0 = success, negative = error
+//   - Detail: call echidna_capnp_status_message(code, buf, buflen)
+//   - Thread-local storage makes this safe for concurrent Rust threads.
+//
+// SPDX-License-Identifier: PMPL-1.0-or-later
+// Copyright (c) 2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
+
+const std = @import("std");
+const builtin = @import("builtin");
+
+const BRIDGE_VERSION = "0.1.0";
+
+// ─── Status codes ─────────────────────────────────────────────────────────────
+
+pub const CapnpStatus = enum(c_int) {
+    ok                   =  0,
+    not_connected        = -1,
+    stub_not_implemented = -2,
+    invalid_param        = -3,
+    io_error             = -4,
+    connect_failed       = -6,
+    unknown_error        = -99,
+};
+
+// ─── Thread-local error storage ───────────────────────────────────────────────
+
+threadlocal var last_error_buf: [512]u8 = undefined;
+threadlocal var last_error_len: usize = 0;
+threadlocal var last_error_status: CapnpStatus = .ok;
+
+fn setError(status: CapnpStatus, comptime fmt: []const u8, args: anytype) void {
+    last_error_status = status;
+    const result = std.fmt.bufPrint(&last_error_buf, fmt, args) catch blk: {
+        const msg = "(error message truncated)";
+        @memcpy(last_error_buf[0..msg.len], msg);
+        break :blk last_error_buf[0..msg.len];
+    };
+    last_error_len = result.len;
+}
+
+fn clearError() void {
+    last_error_status = .ok;
+    last_error_len = 0;
+}
+
+// ─── C-compatible structs ─────────────────────────────────────────────────────
+
+/// GNN rank request passed across the C-ABI boundary.
+/// The graph is encoded as a pre-serialised JSON blob for the stub phase;
+/// L1 wave 1 replaces this with a zero-copy Cap'n Proto builder once
+/// `capnp compile -ozig` output is available.
+pub const EchidnaGnnRequest = extern struct {
+    /// Opaque request identifier (null-terminated, max 63 chars + NUL).
+    request_id: [64]u8,
+    /// Pointer to UTF-8 JSON array of graph nodes (NOT null-terminated).
+    graph_nodes_json_ptr: [*c]const u8,
+    /// Byte length of graph_nodes_json_ptr.
+    graph_nodes_len: usize,
+    /// Maximum number of premises to return (must be > 0; default 20).
+    top_k: u32,
+    /// Minimum score threshold; results below this are suppressed.
+    min_score: f32,
+};
+
+/// GNN rank response returned across the C-ABI boundary.
+/// On success the caller owns rankings_json_ptr and MUST call
+/// echidna_capnp_free_response to release it.
+pub const EchidnaGnnResponse = extern struct {
+    /// Echo of the request_id from the matching EchidnaGnnRequest.
+    request_id: [64]u8,
+    /// Pointer to UTF-8 JSON array of PremiseScore objects. NULL on error.
+    rankings_json_ptr: [*c]const u8,
+    /// Byte length of rankings_json (0 on error).
+    rankings_len: u32,
+    /// Round-trip wall-clock time in milliseconds.
+    elapsed_ms: u64,
+};
+
+// ─── Exported C-ABI functions ─────────────────────────────────────────────────
+
+/// Open a Unix domain socket connection to the ECHIDNA IPC endpoint.
+///
+/// Returns: ≥ 0 file descriptor on success, -1 on failure.
+/// On failure call echidna_capnp_status_message(-1, buf, buflen) for details.
+export fn echidna_capnp_connect(sock_path: [*c]const u8) callconv(.C) i32 {
+    if (sock_path == null) {
+        setError(.invalid_param, "sock_path must not be NULL", .{});
+        return -1;
+    }
+    const path_slice = std.mem.sliceTo(sock_path, 0);
+    if (path_slice.len == 0) {
+        setError(.invalid_param, "sock_path must not be empty", .{});
+        return -1;
+    }
+
+    const addr = std.net.Address.initUnix(path_slice) catch |err| {
+        setError(.connect_failed, "invalid socket path '{s}': {}", .{ path_slice, err });
+        return -1;
+    };
+
+    const sock = std.net.tcpConnectToAddress(addr) catch |err| {
+        setError(.connect_failed, "connect to '{s}' failed: {}", .{ path_slice, err });
+        return -1;
+    };
+
+    clearError();
+    return sock.handle;
+}
+
+/// Close a file descriptor previously returned by echidna_capnp_connect.
+/// Safe to call with fd < 0 (no-op).
+export fn echidna_capnp_close(fd: i32) callconv(.C) void {
+    if (fd < 0) return;
+    std.posix.close(@intCast(fd));
+}
+
+/// Send a GNN rank request and receive the response.
+///
+/// STUB — returns CapnpStatus.stub_not_implemented until L1 wave 1 lands.
+/// The response struct is zeroed before returning so callers that check
+/// rankings_json_ptr for NULL get a well-defined value.
+///
+/// Returns: 0 on success, negative on error.
+///   -2 (stub_not_implemented): expected until `just capnp-gen` is run in L1 wave 1.
+export fn echidna_capnp_gnn_rank(
+    fd: i32,
+    req: *const EchidnaGnnRequest,
+    resp: *EchidnaGnnResponse,
+) callconv(.C) i32 {
+    if (fd < 0) {
+        setError(.not_connected, "fd {d} is invalid (not connected)", .{fd});
+        return @intFromEnum(CapnpStatus.not_connected);
+    }
+    _ = req;
+    resp.* = std.mem.zeroes(EchidnaGnnResponse);
+    setError(
+        .stub_not_implemented,
+        "L1 wave 1: Cap'n Proto bindings not yet generated — run `just capnp-gen`",
+        .{},
+    );
+    return @intFromEnum(CapnpStatus.stub_not_implemented);
+}
+
+/// Free a response buffer allocated by echidna_capnp_gnn_rank.
+/// No-op in the stub (no allocations are made). Must be called in the real
+/// implementation to release the Cap'n Proto message buffer.
+export fn echidna_capnp_free_response(resp: *EchidnaGnnResponse) callconv(.C) void {
+    _ = resp;
+}
+
+/// Write a human-readable description of `status` into `buf`.
+///
+/// If the most recent call on this thread stored a detailed message for
+/// this status code, that message is used. Otherwise a generic description
+/// is written. Output is always null-terminated and never exceeds buflen bytes.
+export fn echidna_capnp_status_message(
+    status: i32,
+    buf: [*c]u8,
+    buflen: usize,
+) callconv(.C) void {
+    if (buflen == 0 or buf == null) return;
+
+    if (last_error_len > 0 and @intFromEnum(last_error_status) == status) {
+        const src = last_error_buf[0..last_error_len];
+        const n = @min(src.len, buflen - 1);
+        @memcpy(buf[0..n], src[0..n]);
+        buf[n] = 0;
+        return;
+    }
+
+    const generic: []const u8 = switch (status) {
+        0   => "ok",
+        -1  => "not connected",
+        -2  => "stub not implemented (L1 wave 1 pending)",
+        -3  => "invalid parameter",
+        -4  => "I/O error",
+        -6  => "connect failed",
+        -99 => "unknown error",
+        else => "unrecognised status code",
+    };
+    const n = @min(generic.len, buflen - 1);
+    @memcpy(buf[0..n], generic[0..n]);
+    buf[n] = 0;
+}

schemas/VERSIONING.md

@@ -0,0 +1,107 @@
+<!--
+SPDX-License-Identifier: PMPL-1.0-or-later
+SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
+-->
+
+# Cap'n Proto Schema Versioning Policy
+
+Schema file: `schemas/echidna.capnp`
+Schema ID: `@0xd3b45f8ae1c79012` (immutable — generated once, never changed)
+
+## Wire Compatibility Guarantee
+
+Cap'n Proto's wire format is **forward- and backward-compatible by default**,
+but only if the following rule is obeyed without exception:
+
+> **Add fields at the end of a struct only. Never reorder, rename, or remove
+> existing fields. Never change an existing field's type or ordinal number.**
+
+Each field carries an explicit ordinal (`@N`). The ordinal is its wire identity.
+Renaming a field in the `.capnp` source is safe (it only changes the generated
+symbol name). Changing `@N` or the field type is a **breaking change**.
+
+## Non-Breaking Changes (safe to make freely)
+
+| Change | Why it is safe |
+|--------|----------------|
+| Add a new field at the end of a struct (`@N` where N > current max) | Older readers ignore unknown fields; older writers produce zero for missing fields |
+| Add a new struct or enum anywhere in the file | Unused by older code |
+| Add a new enum variant at the end | Older code sees it as an unknown discriminant |
+| Rename a field or type (source only) | Ordinals and wire layout unchanged |
+| Change a default value in the schema | Wire encoding unaffected; generated code picks up the new default |
+| Add a new `annotation` | Not encoded on the wire |
+
+## Breaking Changes (require a new struct name or a bumped `schemaVersion` field)
+
+| Change | Why it breaks |
+|--------|---------------|
+| Remove or reorder a field | Changes the ordinal-to-meaning mapping |
+| Change a field's type | Existing wire bytes are misinterpreted |
+| Change a field's ordinal number | Direct wire breakage |
+| Remove an enum variant | Existing discriminant values become invalid |
+| Reorder enum variants | Discriminant values shift |
+
+If a breaking change is truly necessary, **create a new top-level struct**
+(e.g. `GnnRankRequestV2`) and increment the `schemaVersion` content field.
+Do not alter `@0xd3b45f8ae1c79012`.
+
+## Content Versioning (`schemaVersion` field)
+
+The schema ID identifies the file-level wire format and is fixed. For
+application-level content versioning, add a `schemaVersion @N :UInt32`
+field to any message that needs it (default `1`). Consumers check this field
+and reject or transform messages from unexpected versions. Current L1 messages
+omit it — add when the first breaking content change is needed.
+
+## Adding a New Message Type
+
+1. Append the new struct or enum at the **end** of `echidna.capnp`.
+2. Add a section-header comment (see existing style).
+3. Run `just capnp-gen` to regenerate all language bindings.
+4. Update `src/abi/EchidnaABI/CapnSchemas.idr` (see §Idris2 below).
+5. If the new type is part of a breaking redesign, bump `schemaVersion` in
+   the affected request/response structs rather than changing the schema ID.
+
+## Regenerating Bindings (`just capnp-gen`)
+
+After every schema change — including non-breaking additions — run:
+
+```sh
+just capnp-gen
+```
+
+This regenerates `src/rust/ipc/echidna_capnp.rs` (and future Zig/Julia targets
+as they are wired into the recipe). **Commit generated bindings.** They are
+checked in so that consumers without a local `capnp` installation can build.
+A CI check (`just capnp-gen-check`) verifies committed bindings match the
+schema; failing it is a merge blocker.
+
+## Multi-Language Consumers
+
+| Language | Binding mechanism | Status |
+|----------|------------------|--------|
+| **Rust** | `capnpc-rust` (generated `echidna_capnp.rs`) | L1 wave 1 target |
+| **Idris2** | `src/abi/EchidnaABI/CapnSchemas.idr` — type mirror + proofs | Present; update alongside schema |
+| **Julia** | `CapnProto.jl` or Zig C-ABI shim (TBD — see open question in TODO.md) | `src/julia/ipc.jl` stub present |
+| **Zig** | C-ABI bridge in `ffi/zig/src/capnp_bridge.zig` | Stub present; real impl in L1 wave 1 |
+
+## Idris2 ABI Proofs (`src/abi/EchidnaABI/CapnSchemas.idr`)
+
+`CapnSchemas.idr` mirrors enum cardinalities and struct field counts as Idris2
+types and proves bounded-representation invariants. When adding a field or
+enum variant:
+
+1. Add the corresponding constructor to the Idris2 mirror type.
+2. Update the `allXxx` Vect witness and its `xxxCountCorrect : length … = n` proof.
+3. Re-run `%search` on the `xxxBounded : LTE n 256` proof (it will still hold).
+4. Zero `believe_me` is a hard invariant — all proofs must be constructive.
+
+## Quick Reference
+
+```
+Safe:    add field at end, add struct, add enum variant at end, rename
+Unsafe:  remove, reorder, change type, change ordinal
+If breaking: new struct name + increment schemaVersion field
+After any change: just capnp-gen && commit generated bindings
+Update CapnSchemas.idr to match
+```