FigDB Technical Reference Manual

The system under documentation is an ordered, persistent key-value store with crash-safe durability semantics. This manual describes its architecture, component design, external interfaces, verification strategy, build process, measured performance, and known limitations.

This manual describes the system as checked in. Statements about future work (replication, transactions, sharding) are marked as such and are not part of the implemented behavior. See Known Limitations for the explicit list of what is not claimed.

The recommended reading order is:

Key terms used throughout this manual:

The Markdown files already in this repository remain the canonical prose record. This manual summarizes them and links to them:

The target topology is a sharded, replicated store. What exists today is the bottom of the storage engine running as a single-node process (the layers in Implemented components and their crates.), plus Raft consensus through durability: a deterministic core, a seeded simulation harness, and crash-safe persistence — not yet wired to the server (R3). See ADR-006 for the R1/R2/R3 split.

The following terms are never conflated in this manual:

There is no replication yet, so the only acknowledgement point is Wal::sync(): everything at or before the last sync survives a crash. The exact rule is stated in architecture/durability.md and summarized in Design.

The log is a sequence of framed records carrying dense sequence numbers. Each frame carries a checksum. Replay reads a prefix:

The engine applies PUT to the WAL first, then to the in-memory table. Restart replays the log into a fresh table. Rejected writes leave no trace.

Tables are immutable: checksummed blocks, an index, a footer, per-table Bloom filters, and tombstones for deletes. When 8 tables accumulate, the oldest batch of 8 is merged (size-tiered oldest-batch policy) with the same publish protocol as flush, so compaction crash windows reduce to the flush cases above.

Tombstone garbage collection runs only on full merges with an empty memtable, where no older layer can exist below a dropped tombstone, so a dropped tombstone can never resurrect a shadowed key.

The core (fig-raft::Node) is a pure state machine: no I/O, no threads, no clock. Inputs are messages plus timer events; outputs are outbound messages plus committed entries. Elections, log matching (truncate-then-append, no holes), current-term commit advancement, and exactly-once in-order application all live here (R1; see ADR-006).

Durability is explicit (R2). The core reports what changed via take_dirty; persist::Store writes current_term, voted_for, and the log to raft-state.json atomically (tmp, sync, rename, directory fsync) and replays it into Node::restore on restart. Heartbeats mark nothing dirty, so steady-state leadership costs no disk write. An uncommitted suffix may be overwritten by a new leader — it is never applied before commit.

A seeded simulation harness (virtual ticks, partitions, drops) proves single-leader election, ordered replication, failover preserving the committed prefix, and partition healing deterministically on fixed seeds.

The server speaks newline-delimited JSON over TCP: one request line gets one response line. Keys and values are arbitrary bytes, so they travel base64-encoded (standard alphabet) in *_b64 fields. Every request carries a seq number for pipelining; every response echoes that seq with ok, and failures add a stable code (plus a human message) so clients branch on codes, never on text.

Unknown operations and malformed lines return INVALID_ARGUMENT and the connection stays up; see Verification for the wire gate tests.

Keys and values are arbitrary bytes subject to fig-core::Config::Limits, validated at the API boundary before they reach the log:

Oversized inputs are rejected with INVALID_ARGUMENT.

The fastest path is fig-cli, which takes raw UTF-8 strings and handles the base64 framing itself (arbitrary binary keys remain a client-library concern, not a shell concern):

The equivalent raw session over TCP (fig-server defaults to 127.0.0.1:7001), one JSON object per line:

In application terms the cycle is:

All failures use shared error kinds (fig-core::Error) surfaced on the wire as stable code strings: bad input is INVALID_ARGUMENT, a missing key is NOT_FOUND. Corruption is fail-safe: replay stops at the first corrupt frame and truncates the suffix rather than surfacing torn data.

sync is the only acknowledgement point. In application terms:

Reference models are compared against the implementation on seeded random operation streams: the naive oracle must agree with the real structure on every get and scan, including tombstone behavior. Crash tests plant failures at every publish window and assert that reopen yields exactly the acknowledged state.

The local gate runs everything:

Two operational gates run outside cargo test: fig-bench --verify-only recomputes the oracle for a load run with zero shared state, and scripts/soak.sh repeats load/sync/SIGKILL/restart cycles, re-verifying every earlier cycle’s keys after each restart.

Release builds use link-time optimization ([profile.release], single codegen unit); see benchmarks/ for measured release-vs-debug comparisons.

All runs use fig-bench (per-operation latency in microseconds, p50/p99 over the full run) against a local server with a stated durability policy (for example, an explicit sync every 500 puts, so every measured put is acknowledged). Hardware, compiler, dataset, and durability policy are recorded with each run because throughput is meaningless without them.

Throughput and latency are related by the offered load. For a single sequential client over n operations with mean latency \(E[L\)]:

With concurrent clients the wall-clock form applies instead (\(T = n / T_{wall}\)), which is why single-client and multi-client figures are reported separately in benchmarks/.