# Consistent-read engineering report

Engineering checkpoints are 9590a28 (baseline), 9e9fe7b (design), c260a43 (core, query and client integration) and 3517c00 (final lifecycle and verification). The operator guide defines the API and limits. [Design](CONSISTENT_READ_DESIGN.md) · [Guide](CONSISTENT_READS.md)

## Findings

A snapshot captures an immutable v3 radix root and its extent. All lookups, including primary ID, secondary posting, unique field and fallback scan, use that root. Writers continue appending and publishing new roots. The snapshot adds volatile retention accounting and a read-only adapter to the existing storage format. Ordinary pages still resolve the latest committed root. V1 requires an offline migration.

The default 16 readers, 60-second lifetime and 256 MiB reservation budget bound even idle clients. The 100,000-document fixture reserved 106,228,923 bytes for one view. Two such views fit the default budget, a third would exceed it. A reader that reaches EOF releases the reservation immediately. The registry prunes released or expired entries on access, and the server also sweeps idle sessions. Its bounded slot-array capacity can be reused. Individual page calls still serialize through the server mutex. Time spent processing a page can delay a writer. No mutex spans page requests.

Two authenticated writers each inserted, updated indexed fields and deleted records as two other clients traversed 1,000 original documents in 20-row pages. The test compares each full ordered result with the original records, checks current writes from an ordinary client and kills the server with a snapshot page loop active. The two writers received 294 acknowledgements. On Windows mean write time was 7.961 ms and historical page time was 0.752 ms. On WSL Linux the corresponding means were 16.180 ms and 0.376 ms. These include file-backed TCP request handling. The workload synchronizes each pair of reads after six writer acknowledgements.

## Embedded measurements

Release builds using MemoryStorage, one nonunique index, 64-row pages and a 20% indexed equality result. Times are arithmetic means for a single run per host and size. The Windows and WSL runs shared a workstation and overlapped other verification. They describe workload costs and should not be used as production latency percentiles.

|Host|Documents|Begin / close and reap (ns)|Scan ordinary / snapshot (µs/page)|Indexed ordinary / snapshot (µs/page)|Three-mutation write batch alone / with reader (µs)|Reopen and audit (ms)|
|---|---:|---:|---:|---:|---:|---:|
|Windows|1,000|156 / 78|67.9 / 71.7|206.5 / 219.2|91.0 / 103.9|25|
|Windows|10,000|145 / 77|96.0 / 89.7|307.1 / 321.9|121.0 / 126.1|274|
|Windows|100,000|146 / 76|70.0 / 73.7|340.3 / 332.0|120.5 / 141.8|3,303|
|WSL Linux|1,000|103 / 57|59.4 / 61.8|378.0 / 202.1|83.3 / 102.5|25|
|WSL Linux|10,000|100 / 57|64.8 / 66.0|314.5 / 309.5|104.1 / 119.8|309|
|WSL Linux|100,000|130 / 66|87.3 / 85.4|394.3 / 403.2|122.5 / 157.4|3,489|

At every size the first filtered handle used 376 additional live heap bytes (also the peak at begin) and its Rust object occupied 192 bytes. The heap measurement includes first registry allocation, a short scalar filter and two short namespace strings. Longer filters, IDs, decoded documents, page buffers and network sessions have separate costs. Warm begin and release measurements average 500 operations.

|Documents|Reservation per reader (bytes)|Write batches during traversal|Final adapter extent (bytes)|Additional physical bytes from snapshot|
|---:|---:|---:|---:|---:|
|1,000|746,723|15|1,048,576|0|
|10,000|9,060,923|156|9,961,472|0|
|100,000|106,228,923|1,562|115,081,216|0|

The reader checked each original value in order. The writer-only control repeated the same commits from an identical initial image. The resulting adapter images matched byte for byte at all three sizes. V3 retains historical log bytes until offline compaction regardless of reader count. Releasing a reservation restores admission capacity. Reclaiming actual file space requires a compact copy. Reproduce with `cargo run --release --locked -p ratdb-document --example snapshot_cost`.

## Regression and recovery evidence

- Full Windows GNU and Ubuntu WSL gates passed formatting, all-target workspace tests, doctests, no-default-feature core tests, strict Clippy, release builds and subprocess suites (12 Windows, 13 Linux). The Linux gate also exercises terminal behavior. Embedded, Rust network, Python, Node and shell paths exercised real continuations.
- Document tests verify empty, sparse and multipage traversals, historical values after repeated edits/deletes, primary and unique lookups, new uniqueness enforcement and a dropped index. Core tests corrupt retained data, inject adapter I/O errors and interrupt compact copies. The historical reader reports corruption when it reaches damaged data.
- File-backed tests reject foreign, replayed, wrong-den and altered-filter continuations, exercise idle expiry, count and byte limits, terminal-page cleanup, explicit close and disconnect. Reopen rejects old handles, audits current state and checks committed values. A separate subprocess dies while writing the compaction staging file. The original is byte-identical afterward and a new migration passes verification.
- The portable core compiled for thumbv7em-none-eabi without default features. A custom storage adapter with sector operations and short transfers exercised the historical read path. The host supplies monotonic time. Existing adapter operations, exclusive ownership and synchronization semantics suffice.

## Remaining work

Qualify physical power cuts and flush behavior on an Asterhold storage device. Measure tail latency, sparse scans and retained-byte admission under long-running file-backed workloads. Any future online compactor must honor live roots before it can reuse a page. A session or process restart ends its snapshot. Recovering a long-running export across a restart would require a separate persistent-view design.