chore(l1): record CapnProto.jl decision + all L1 design questions settled

STATE.a2ml [l1-design-decisions]: julia-ipc-library = CapnProto.jl (Option A);
UDS path /run/echidna/ipc.sock; no IPC-layer signing; request-response for L1;
Chapel locale transit = byte-copy safe.

src/julia/ipc.jl: promote Option A to primary path with concrete steps;
retain Zig shim reference as fallback of last resort.

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

Author: hyperpolymath

.machine_readable/6a2/STATE.a2ml

@@ -987,3 +987,11 @@ known-p0-failure-modes = [
 ]
 recommended-action = "Manually open https://github.com/hyperpolymath/echidna/actions/workflows/live-provers.yml and inspect the most recent scheduled run (triggered 2026-04-26T03:00Z on 757df703). For any red T2 cell: pull the log via 'gh run view <id> --log-failed --job <jobId>', classify against the four P0 failure modes above, and open a GitHub issue titled 'live-provers nightly red: <backend> — <one-line root cause>' (body: run URL, failing step, ~10-line log excerpt, suspected fix). Do NOT open issues for T1 reds."
 branch = "nightly-triage/2026-04-26"
+
+[l1-design-decisions]
+summary = "L1 Cap'n Proto design questions settled 2026-04-26."
+julia-ipc-library = "CapnProto.jl (Option A). Decision: use CapnProto.jl for the Julia-side deserialisation rather than the Zig C-ABI shim. Rationale: idiomatic Julia, schema evolution propagates automatically via regenerated bindings. Risk acknowledged: CapnProto.jl is pre-1.0 and the RPC layer may need patching; patch upstream if required rather than switching approaches. Zig shim (Option B) remains scaffolded in ffi/zig/src/capnp_bridge.zig as a fallback if CapnProto.jl proves unworkable in practice."
+uds-path = "Primary: /run/echidna/ipc.sock (overridable via $ECHIDNA_IPC_SOCK). TCP fallback: 127.0.0.1:9090 (overridable via $ECHIDNA_IPC_HOST + $ECHIDNA_IPC_PORT). Both sides (Rust src/rust/ipc/mod.rs and Julia src/julia/ipc.jl) use the same env-var priority order."
+handshake-signing = "None at the IPC layer. BLAKE3/SHAKE3-512 integrity is per-solver-binary (src/rust/integrity/), not per-IPC-connection. The IPC channel is local UDS only; no TLS or signing needed."
+streaming = "Request-response for L1. Cap'n Proto RPC streaming deferred to L2 when Chapel batching requires it."
+chapel-schemas = "Cap'n Proto messages are self-contained byte strings — locale-to-locale transit is byte-copy safe. No special multi-locale handling needed in L1; revisit when L2.5 (multi-locale PGAS) is scoped."

src/julia/ipc.jl

@@ -19,26 +19,22 @@
 
 # ─── TODO: what must land before this stub becomes real ──────────────────────
 #
-# Option A — CapnProto.jl (preferred if the package reaches stability):
+# DECISION (2026-04-26): Use CapnProto.jl (Option A).
+#
+# Implementation steps:
 #   1. Add CapnProto to Project.toml / Manifest.toml.
-#   2. Replace gnn_rank_request body with:
+#   2. Add a Julia codegen target to the `just capnp-gen` Justfile recipe
+#      so that `capnp compile -ojulia schemas/echidna.capnp` generates
+#      GnnRankRequest / GnnRankResponse Julia structs.
+#   3. Replace gnn_rank_request body with:
 #        msg = CapnProto.build(GnnRankRequest, parse_request_fields(request_json))
 #        write(sock.sock, CapnProto.encode(msg))
 #        raw = read(sock.sock, CapnProto.ResponseHeader)
 #        return CapnProto.decode(GnnRankResponse, raw)
-#   3. Wire GnnRankRequest / GnnRankResponse structs from generated Julia
-#      bindings (add a Julia target to the `just capnp-gen` Justfile recipe).
-#
-# Option B — Zig C-ABI shim (fallback if CapnProto.jl is not viable):
-#   1. Build ffi/zig/src/capnp_bridge.zig as a shared library.
-#   2. Use ccall to call:
-#        ccall((:echidna_capnp_gnn_rank, "libechidna_capnp"),
-#              Cint, (Cint, Ref{EchidnaGnnRequest}, Ref{EchidnaGnnResponse}),
-#              fd, req, resp)
-#   3. The Zig shim handles Cap'n Proto framing and socket I/O; Julia only
-#      passes/receives C-compatible structs.
+#   4. If CapnProto.jl's RPC layer is missing/broken, patch upstream rather
+#      than switching approaches. The Zig C-ABI shim in
+#      ffi/zig/src/capnp_bridge.zig remains as a fallback of last resort.
 #
-# Decision tracked in: docs/handover/TODO.md §L1 design questions
 # Gated on: L3 Tier-1 green for ≥ 7 days (same gate as Rust IPC side).
 # ─────────────────────────────────────────────────────────────────────────────