Architecture Decision Records
Lightweight ADRs (MADR-ish). Status values: Proposed / Accepted / Superseded. Everything marked Accepted below is the working default chosen 2026-06-09 and is revisable — these are decisions of record, not laws.
| # | Decision | Status |
|---|---|---|
| 0001 | Thread-per-core, network-sharded concurrency | Accepted |
| 0002 | Per-worker io_uring rings, immutable snapshot fds, striped parallel reads | Accepted |
| 0003 | Best-effort cache semantics; RAM head = write-through cache of an SSD-resident prefix | Accepted |
| 0004 | C++23 toolchain & build | Accepted |
| 0005 | Protocol surface: memcache over TCP and native RDMA, HTTP object path, no UDP, no auth | Accepted |
| 0006 | Positional tiering & the request-triggered read-ahead pipeline | Accepted |
| 0007 | Eviction: size-aware, FIFO-based (S3-FIFO/SIEVE + GDSF), not LRU/LFU | Accepted |
| 0008 | RAM allocator: power-of-two block array + intra-block buddy | Accepted |
| 0009 | Drive pools: immutable generation files and rotated round-robin striping | Accepted |
| 0010 | Per-write admission: EVICT vs BLOCK (no capacity reclaim) on filesystem exhaustion | Accepted |
| 0011 | O_DIRECT: own the backing store, bypass the kernel page cache | Proposed |
| 0012 | Multi-resource eviction: RAM heads, global object count, and per-filesystem capacity | Accepted |
| 0013 | Ephemeral v1: no persistence, wipe-on-start (dedicated subdir + marker guard) | Accepted |
| 0014 | Keyless identity: client keys → 256-bit SHA-256 digest as the internal ID | Accepted |
| 0015 | HTTP key derivation: path vs virtual-host mode; --source directory preloader |
Accepted |
| 0016 | Bounded, locked memory: local --memory, optional per-node --sub-memory, fixed streaming pools |
Accepted (partial) |
| 0017 | Buffer taxonomy: fixed heads, inline small responses, and streaming I/O pools | Accepted |
| 0018 | Concurrency: thread-per-core network, shared locked storage | Accepted |
| 0019 | Decayed per-key access scores and hot full-block NUMA promotion | Accepted |
| 0020 | Native RDMA: inline control ring plus registered, credit-controlled bulk windows | Accepted |
| 0021 | HTTP mirror mode: bounded lockstep origin streaming and shared-cache semantics | Accepted |
See the project README for the readable overview that ties these together.