ADR 0004: Lock-Free /dev/shm Seqlock Ring for Cross-Agent Telepathy¶
Status¶
Accepted (2026-11-16)
Superseded in part by ADR-0005 (v1.1.0).
Context¶
Multiple agent processes (Claude Code, Codex, Antigravity CLI, Hermes) running concurrently on the same workstation need to share real-time working context (e.g., discovered bugs, file edits, failing assertions). Using SQLite or HTTP alone introduces lock contention (SQLITE_BUSY) or multi-millisecond serialization overhead inside synchronous hooks, and risks deadlocks if a hook process is killed mid-write (SIGKILL).
Decision¶
We implement a POSIX shared-memory Lock-Free Seqlock Ring Buffer (/dev/shm/icx-fabric-v1 or .icx/icx-fabric-v1.shm) in crates/icx-bus under #![forbid(unsafe_code)]:
- Fixed
256slots of4,096bytes each (1,048,640bytes total including the64-byteFabricHeader). FabricHeaderandSeqlockSlotare represented as 100% safeAtomicU32andAtomicU64word arrays (#[repr(C, align(64))]) with compile-time size and alignment assertions, and file-backed/dev/shmpersistence uses safe positional I/O (std::os::unix::fs::FileExt::{read_exact_at, write_all_at}).- Writers claim a slot via
AtomicU64::fetch_addon the global sequence counter and bracket writes with odd/evenAcqRel/Releaseupdates on the per-slot seqlock counter. - Readers execute wait-free optimistic reads validated by even sequence parity (
s1 == s2).
Consequences¶
- Positive:
< 300 nslock-free publish/poll latency for the in-process atomic ring (BackingStore::InProcess) and< 10 µscross-process/dev/shmpositional I/O + OS advisory lock transport (BackingStore::SharedFile); 100% safe Rust (unsafe_code = "forbid"across all 8 crates); immune to deadlocks even if an agent process crashes or isSIGKILLed mid-write. - Negative: Positional
AtomicU64word packing andpread/pwritesyscalls on the file-backed/dev/shmpath add a few microseconds over rawmmap, which remains well within the< 100 µssynchronous hook budget while guaranteeing 100% safe Rust.