ADR-0001 — Zero-Copy Ring Buffer as the Internal Data Transport Primitive
Status: ACCEPTED Date: 2026-02-28 Authors: Matthew Lynch matthew.lynch@helix-os.ai FR-Refs: FR-HAL-001, FR-AUD-001 Supersedes: None Superseded by: None
Context
HELIX OS ingests high-frequency telemetry from bioreactor instruments at rates exceeding 10,000 concurrent streams with a P99 latency target of < 2 ms (FR-HAL-001). Every data write must be appended to the audit ledger (FR-AUD-001). The internal transport between the HAL ingestion layer, the audit ledger, the simulation engine, and the digital twin must be fast enough that the transport itself never becomes the bottleneck.
Traditional message-passing architectures (e.g., MPSC channels with heap-allocated payloads) introduce allocation pressure and cache misses that are incompatible with the latency budget. A shared-memory, zero-copy approach eliminates per-message allocations and enables downstream consumers to read telemetry frames in-place without deserialization.
This decision must be made first because every crate in the workspace — helix-hal, helix-ledger, helix-core, helix-sim, helix-dtwin — depends on the data transport primitive. Changing it later would require a full re-architecture and re-validation.
Decision
The system shall use a lock-free, single-producer multi-consumer (SPMC) ring buffer backed by a contiguous memory-mapped region as the sole internal data transport primitive between crates. All telemetry frames, simulation outputs, and control signals flow through ring buffer channels.
Key properties:
- Zero-copy reads — Consumers receive slices into the ring buffer. No data is copied or deserialized.
- Fixed-capacity, pre-allocated — Each ring buffer is allocated once at process startup. No dynamic allocation occurs on the hot path.
- Cache-line aligned — Buffer slots are aligned to 64-byte cache lines to prevent false sharing between producer and consumer cores.
- Sequence-number indexed — Producers write a monotonically increasing sequence number per slot. Consumers track their own read position. Slow consumers detect overruns via sequence gap detection.
- Memory-mapped backing — Ring buffers may optionally be backed by
mmap'd memory to enable cross-process shared access for external tooling (e.g.,helix-bench).
The ring buffer implementation will reside in helix-core and will be the only sanctioned mechanism for inter-crate data flow within a single HELIX OS process.
Rationale
- Latency: Zero-copy eliminates serialization/deserialization overhead. Benchmarks from comparable LMAX Disruptor-style ring buffers demonstrate < 100 ns per message at high throughput — well within the 2 ms P99 budget.
- Determinism: Pre-allocated, fixed-size buffers produce no garbage collection pressure and exhibit predictable memory access patterns. This is critical for a GMP-regulated system where non-deterministic latency spikes could affect process control decisions.
- Auditability: Because all data flows through a single primitive, the audit ledger (FR-AUD-001) can tap every channel at a single interception point rather than instrumenting multiple transport mechanisms.
- Simplicity: One transport primitive means one set of failure modes, one performance model, and one set of tests. This reduces the validation surface area significantly.
Alternatives Considered
| Alternative | Reason for Rejection |
|---|---|
| Tokio MPSC channels | Heap-allocated per message; unbounded backpressure risk; non-deterministic latency under contention. |
| Crossbeam bounded channels | Better than Tokio but still copies data per send. Does not support zero-copy consumer reads. |
Shared Arc<RwLock<VecDeque>> | Lock contention under high concurrency is unacceptable for the latency budget. |
| Unix domain sockets / IPC | Kernel-mediated; adds syscall overhead per message; incompatible with < 2 ms P99 at scale. |
| Shared-nothing actor model (e.g., Actix) | Message copies between actors; dynamic dispatch overhead; harder to audit data flow centrally. |
Consequences
Positive
- All inter-crate data transport is zero-copy and allocation-free on the hot path.
- A single audit interception point simplifies ledger integrity enforcement.
- Deterministic memory usage — no OOM risk from unbounded queues.
- Cache-friendly access patterns yield consistent low-latency performance.
Negative
- Ring buffer capacity must be sized correctly at startup. Under-sizing causes consumer overrun; over-sizing wastes memory.
- Consumers must keep up with the producer or accept data loss (by design — this is a real-time system, not a queuing system).
- Zero-copy semantics require careful lifetime management in Rust — consumers must not hold references past the producer's write cursor.
Risks
- Complexity of lock-free correctness: Lock-free data structures are notoriously difficult to implement correctly. Mitigation: extensive property-based testing with
proptestand Miri for undefined behavior detection. - Platform-specific memory ordering: Atomic operations may behave differently across architectures. Mitigation: explicit
Ordering::SeqCston all critical-path atomics during initial development; relax only with benchmarked justification.
Compliance Notes
- FR-HAL-001 requires < 2 ms P99 ingest latency at 10,000 concurrent streams. The ring buffer's zero-copy design is the primary mechanism for meeting this requirement.
- FR-AUD-001 requires every data write to be appended to the Blake3 ledger. The ring buffer provides a centralized interception point for audit tapping.
- This ADR is permanent per
HELIX-VAL-STR-001. Superseding it requires a full re-validation cycle including IQ/OQ/PQ.
Revision History
| Date | Author | Change |
|---|---|---|
| 2026-02-28 | Matthew Lynch | Initial accepted decision |