flatsql 3.11.1 → 3.12.1

package/docs/PARTITION-STORE.md

@@ -1,2380 +0,0 @@
-# FlatSQL partition store (format 2): native engine
-
-The engine of the partition store program. Part I (§1–§11) is T1: append-only
-partition logs, one writer per partition on a pinned pool, durable acks,
-per-commit indexes, type owners, and durable-tail open. Part II (§12–§21) is
-T2: reader instances and lanes, the snapshot protocol, the SQL surface, the
-fan-out merge, admission and results. Part III (§23–§30) is T3: compaction,
-reclamation, meta-segment retirement, disk accounting and quota. Part IV
-(§31–§35) is T3b: store-migrate gseqs, the entry-size setting, hot-partition
-splitting and arrivals compaction; §36 records the quota eviction race T3 #3
-met on Linux. Part V (§37) bounds a reader instance's memory. Part VI (§38)
-records the memory-safety and race work: the ps-wasm trap, the sanitizers and
-the first disk-full emergency. Part VII (§39) closes the query gaps T6 found
-on the host-02 fixture and accepts records stored with their own size
-prefix. Part VIII (§40) makes a partition's bookkeeping O(1) or O(log S) per
-commit (the terabyte audit's B4) and adds manifest version 3 (M3). Part IX
-(§41) is TB03: format levels with a ratchet, and paged lane checkpoints that
-lift the 1,170-lane cap (level 3). The
-design is
-the stack's `docs/architecture/flatsql-partition-store.md` (§22 overrides
-§0–§21; §22.4 holds the owner rulings). This file records what was built, how
-to run it, the measured acceptance, and every place the build departs from the
-design.
-
-The wasm artifact is T4; SDN and browser integration are T6/T10.
-
-## 1. Code map
-
-| Path | Contents |
-|---|---|
-| `cpp/include/flatsql/flatsql_io.h`, `cpp/src/flatsql_io_native.cpp` | Seven-import host contract; flags `CREATE_PARENTS` 0x0100, `UNLINK_IF_UNUSED` 0x0200, `OPEN_DEFERRED` 0x0400, status `BUSY` −7 (the module-sdk 0.8.22 values). Native host: lock-free handle table, `F_FULLFSYNC` on darwin, `fdatasync` on Linux, parent-directory fsyncs. |
-| `cpp/include/flatsql/ps/format.h`, `src/ps/format.cpp` | On-disk structs, magics, key encodings, A17 CID sort key, head slots, paths. |
-| `ps/index.h`, `src/ps/index_l0.cpp`, `index_l1.cpp` | Per-commit L0 blocks, L1 runs (4 KiB blocks, fences, blooms, TOC), streaming k-way merge. |
-| `ps/ring.h`, `src/ps/ring.cpp` | 64 KiB slab pool, SPSC rings, page map-ahead, rejects, owner word. |
-| `ps/extract.h`, `src/ps/extract.cpp` | Per-type config (BFBS + rule text), frame checks, key extraction (A19), producer token (A3), sealed envelopes. |
-| `ps/registry.h`, `src/ps/registry.cpp` | Registry frames and head (A10). |
-| `ps/writer.h`, `src/ps/writer_pool.cpp` | Engine, writers, commit rounds, sync pool, mailbox, maintenance, producers. |
-| `src/ps/partition_log.cpp` | Staging, dedupe, RETAG, supersede, TOMB, RECONCILE, TOMB_RANGE, transactions, publish. |
-| `src/ps/merge.cpp` | Warm/cool, merge planning and outputs (A11), manifests. |
-| `src/ps/type_owner.cpp` | Labels, arrivals (A15), cid catalog, REPEAT, REHOME (A14), type-level deletes, notices (A25). |
-| `src/ps/journal.cpp` | Per-writer commit journal (A8 fallback). |
-| `src/ps/open.cpp` | Open, journal replay, durable-tail adoption (A4), registration. |
-| `ps/flatsql_ps.h`, `src/ps/capi_ps.cpp` | C ABI (i32/f64 only). |
-| `schemas/flatsql_attr.fbs` | `RecordAttr` / `SourceTag` (generated with the published flatc-wasm). |
-| `cpp/test/ps/`, `cpp/test/io_fault.cpp` | Tests, fault-injecting host, bench driver, A19 vectors. |
-
-## 2. On-disk layout
-
-```
-<root>/fsql2/
-  STORE  MIGRATED  registry.fsl  registry.fsh
-  STORE.tmp                          only while a format ratchet runs (§41)
-  j/<writer:02x>-{a,b}.fsj           commit journal (only with commitJournal)
-  p/<pid:08x>/
-    h.fsh                             head, A/B 4 KiB slots
-    m-<seg:06x>.fsl                   meta log, one per data segment (A9)
-    d-<seg:06x>.fsd                   frames, [u32 size][FlatBuffer]
-    r-<seg>.fsr  a-<seg>.fsa          dense rows / attributes (merged ranges)
-    x-<seg>-<gen:04x>.fsx             L1 runs
-    mf-<gen:06x>.fsm                  segment manifest
-    l.fsl                             lane table (tuples)
-    lk-<gen:06x>.fsl                  level 3: paged lane checkpoint (§41)
-  t/<fid hex8>/
-    h.fsh  m-<seg>.fsl                type head and log (A10 batches)
-    g-<seg:06x>.fsg                   arrivals, 24 B entries (A15 segments)
-    g.fsf                             arrivals gseq fence index (A15)
-    x-<gen:06x>.fsx  mf-<gen>.fsm     cid catalog runs and manifest
-    s-<fp:016x>.fsc                   type config (BFBS + rules)
-```
-
-Byte layouts are the structs in `format.h` (all little-endian, CRC32C).
-
-## 3. Write path
-
-1. A producer reserves credits (`min(ring cap − used, pool free − reserve)`),
-   copies one entry into its ring and rings the owner's doorbell.
-2. The owning writer stages each partition with backlog: verify (size, fid,
-   BFBS), CID check, extraction, dedupe (writer cid table, blooms, L0/L1),
-   RETAG for a new tag tuple (A2), supersede, lane deltas, the L0 block.
-3. A commit round writes every staged batch and makes it durable:
-   - **file mode** (default, §6.4 as amended by A8): pwrite `d`/`l`/`g`/fence,
-     one concurrent sync round; pwrite `m` batches, a second sync round. Two
-     sync rounds per iteration whatever the number of dirty partitions.
-   - **journal mode** (`commitJournal`, §22.4 ruling 5): the same pwrites plus
-     one journal record holding their bytes; the journal fsync is the round's
-     only sync. A checkpoint thread later syncs the touched files and heads
-     (paced, see deviation 13) and truncates the retired journal file.
-4. Publish: state, seqlock publication, head slot pwrite (checkpoint heads are
-   synced one round later in file mode, by the journal checkpoint in journal
-   mode), acks, notices to the type owners (A25: a full queue drops the
-   notice; the owner compares `labeled_through` with each partition's HWM).
-5. Maintenance, bounded per iteration: merge planning (INTENT_MERGE first,
-   A11), MERGE_DONE once a helper has written and synced the outputs, seal by
-   size/records/age, next-segment pre-creation, idle reclaim, journal
-   checkpoints.
-
-Mailbox commands (never ring entries, A24): adopt/handoff, rebalance, type
-registration, type-level kills (TOMB_CID fan-out, A14) and `TOMB_RANGE{seg,
-epoch < t}` for the quota planner. TOMB_RANGE runs in bounded steps, spares
-supersede-lane heads and control kinds, and completes when its TOMBs are
-durable.
-
-Ownership (A26): owner word `{epoch u32, writer u8, state}`. A rebalance waits
-for any in-flight merge helper, sets HANDOFF, and the target CASes it to
-OWNED with epoch + 1. A helper re-validates `{epoch, OWNED}` before every file
-mutation.
-
-## 4. Open and recovery
-
-1. `STORE` and `MIGRATED` (refused without the marker). A level above the
-   engine's `kFormatMax` is refused before any file is touched; a lower one
-   ratchets once the registry is non-empty (§41).
-2. Registry: frames scanned past the head, truncated at the first bad CRC;
-   incarnation = max seen + 1, recorded durably before any batch.
-3. Journal replay (A8): both files of every writer id from 0 until the first
-   id without journals; records in `seq` order; parts pwritten into their
-   files; the files fsynced; the journals truncated.
-4. Types: head slot, label checkpoint (A10, > 128 pids), tail batches (commit
-   chain, incarnation, arrivals CRC, A15 segment switch; a journaled batch only
-   if replayed), fence index validation, fsync before adoption.
-5. Partitions: head slot, tail batches across SEAL continuations (same rules),
-   fsync `d`/`m`, A11 intent cleanup (`UNLINK_IF_UNUSED`), DURABLE_CKPT head.
-   At level 3 a head that names a LaneRef folds the lane table from it, and
-   open removes a lane checkpoint no durable head names (§41).
-6. Type heads for adopted type tails, written after the partitions are
-   attached (their inline labels come from them).
-
-Open never reads a `d-*` byte and never parses a frame
-(`openDataBytes = framesParsedAtOpen = 0` in every crash trial).
-
-## 5. Extraction rules (A19)
-
-A type's extraction is engine data: `TypeConfig` = schema name, fid, BFBS,
-rule text, limits, flags. The rule language is documented in `extract.h`
-(`epoch`, `col`, `epoch_day`, `object`, `require`, `supersede`).
-
-The production rule texts for OMM, MPE, OEM, CAT, PNM and RFB are
-`cpp/test/ps/vectors/<TYPE>.rules`. `format_extraction_golden_vectors_A19`
-checks them against rows produced by sdn-server's `extractIndexedFields`,
-`recordIndexArgs` and `recordSupersedeKey` (copied verbatim into
-`vectors/gen/goref.go`, built against the published SDS Go bindings 1.226.0)
-over 420 frames built from the published SDS 1.226.0 schemas with the
-published flatc-wasm: 310 OMM from a Space-Track GP archive day plus edge
-cases (fallbacks, time zones, invalid dates, pre-1970), 44 MPE, 10 OEM, 48 CAT
-(every enum value, out-of-range values, all supersede branches), 4 PNM,
-4 RFB. All 420 match.
-
-## 6. C ABI
-
-`flatsql_ps_init(role, cfg, len)`, `flatsql_ps_start()`,
-`flatsql_ps_layout(out)`, `flatsql_ps_wake(addr, n)`,
-`flatsql_ps_pump(budget_us)`, `flatsql_ps_stop(deadline_ms)`,
-`flatsql_ps_stats(out, len)`, `flatsql_ps_register_type(cfg, len)`,
-`flatsql_ps_register_partition(peer, len, fid)`, `flatsql_ps_ring(pid)`.
-Config TLV tags are listed in `flatsql_ps.h`.
-
-## 7. Configuration (`EngineConfig`)
-
-| Field | Default | Meaning |
-|---|---|---|
-| `writers` | 1 | writer threads (production: clamp(cores − 2, 1, 16)) |
-| `syncThreads` | 0 = clamp(writers, 4, 8) | concurrent sync pool, fair per writer |
-| `poolBytes` / `slabBytes` | 192 MiB / 64 KiB | ring slab pool |
-| `defaultRingCap` | 4 MiB | per partition (type config may override) |
-| `commitBytes` / `commitFrames` | 4 MiB / 1024 | per partition per commit |
-| `sealBytes` / `sealRecords` / `sealAgeMs` | 64 MiB / 1 M / 1 h | segment seal |
-| `ckptIntervalMs` / `ckptMetaBytes` | 250 / 64 KiB | head checkpoints (file mode) |
-| `mergeL0Blocks` / `mergeL0Bytes` / `mergeMinL0Bytes` | 16 / 1 MiB / 64 KiB | merge triggers |
-| `mergeHelpers` | 1 | merge builder threads (0: build on the writer) |
-| `zeroFillStep` | 1 MiB | A8 zero-fill ahead |
-| `arrivalsSegBytes` | 64 MiB | A15 arrivals segment |
-| `commitJournal` | false | A8 fallback: per-writer commit journal |
-| `journalCkptBytes` / `journalCkptMs` | 8 MiB / 1000 | journal checkpoint triggers |
-| `noticeQueue` | 1024 | A25 notice queue per type |
-| `typeCommitRows` / `reconcileStep` | 8192 / 4096 | bounded steps |
-
-## 8. Tests and benchmarks
-
-```
-cmake -S cpp -B cpp/build -DCMAKE_BUILD_TYPE=RelWithDebInfo
-cmake --build cpp/build -j 8 --target flatsql_ps_test flatsql_ps_bench
-cpp/build/flatsql_ps_test                         # default suite, T1 + T2 (~2 min)
-cpp/build/flatsql_ps_test --test=<name>           # one test, slow ones included
-cpp/build/flatsql_ps_test --crash-trials=N --crash-seed=S --test=crash_faults_T1_1
-cpp/build/flatsql_ps_bench --mode=scaling|host02|dirty|soak [--journal=1] [--io=mem|fs] [--dir=D]
-```
-
-Slow tests: `crash_faults_T1_1_full` (10,000 trials, 64 types, 256
-partitions), `writer_single_writer_under_rebalance_T1_4_full` (10 min),
-`type_notices_never_block_A25_full` (10 min),
-`open_clean_1M_records_256_partitions_T1_2_full` and `_real_fs`.
-
-The crash harness (FaultFs) injects: drop all unsynced writes, drop a random
-subset, tear the last write at a 512 B boundary, reorder unsynced writes, and
-kill -9 keeping the page cache; every other trial adds the A4 sequence
-(reopen, resend, publish, second crash dropping everything). Half the stores
-run in journal mode; seals, merges (helper and inline), arrivals seals,
-RECONCILE, TOMB_CID, TOMB_RANGE, transactions and registrations run under the
-crashes. A stalled ack counts as a failure.
-
-## 9. Acceptance (§18 T1 as amended)
-
-Machines: **Mac** = owner Mac Studio (Darwin 25.3.0, arm64, 28 cores,
-APFS, `F_FULLFSYNC`), shared with other lanes (load average 13–42 during
-these runs). **Docker** = Linux 6.12 linuxkit arm64 in Docker Desktop on that
-Mac (ext4 on a virtual disk), `--cpus`/`--memory` as noted. Neither is
-host-02 or a Linux-8 box; §11 lists what needs one. All numbers come from
-`MEASURED` lines of the tests and `flatsql_ps_bench`, run on task-branch builds from 16a4c63 to 7f941bc.
-
-| # | Acceptance | Result | Where |
-|---|---|---|---|
-| 1 | 10,000 injected crashes, 256 partitions, 64 types (OMM/MPE/CAT/IQC shapes); acked bytes identical, gap-free pseqs, counters = recount, no gseq reassigned, 0 `d-*` bytes read by open; A4 crash → reopen → resend → second drop-all crash; A10 type/registry crash points; A11 merge crash points | **Pass.** Final build (7f941bc), Mac: 10,000 trials over the five modes (about 2,000 each: drop all unsynced, drop a subset, tear the last write at 512 B, reorder, kill -9) plus an A4 second drop-all crash every other trial; 3,437,331 acked records verified; 526,105 merges, 1,087 seals, 69,126 arrivals seals, 11,107 TOMB_RANGE commands, 983,753 journal records replayed (half the stores journaled); 243 s. Linux (Docker): 2 × 1,000 trials on the final build, 5 × 1,000 on earlier ones. | Mac `crash_faults_T1_1_full`; Docker `--crash-trials=1000` |
-| 2 | Open, 1 M records in 256 partitions: clean ≤ 150 ms and ≤ 1 MiB I/O; after drop-unsynced ≤ 64 KiB `m` per active partition; 0 frames parsed | **Pass.** Real fs: Docker ext4 39.6 ms, 476 KB read; Mac APFS 34.1 ms, 574 KB read, 1 fsync (the registry incarnation). In-memory host: 4.5 ms, 577 KB. After drop-unsynced: 24 KB of `m` per partition (64 partitions). `framesParsedAtOpen = 0`, `openDataBytes = 0`. | `open_clean_1M_records_256_partitions_T1_2_real_fs`, `_full`, `open_after_drop_unsynced_reads_bounded_meta` |
-| 3 | Resend the last 10 k acked after a crash: 0 new rows, 0 `d-*` bytes read | **Pass.** 0 rows, 0 bytes. | `open_resend_after_crash_dedupes_T1_3` |
-| 4 | Rebalance every 50 ms for 10 min: pseq strictly increasing and gap-free, one writer thread per ownership interval, no overlap; A26: rebalances during merges with helpers stalled 100 ms, 0 non-owner writes | **Pass.** 600 s, 8 writers, 64 partitions, producers paced to ~6,400 records/s: 10,623 moves, 761,217 audited commits, 7,624 ownership intervals, 0 violations (gap, order, overlap, second thread in an interval); 33,511 merges, 5,181 injected 100 ms helper stalls, 5,448 handoffs that waited for an in-flight helper, 0 non-owner helper writes; every sent record present after reopen. | `writer_single_writer_under_rebalance_T1_4_full` (Mac) |
-| 5 | One partition flooded: ring ≤ cap, others' p99 changes ≤ 20%, pool within budget, credits reach 0 and recover, 0 frames lost | **Pass.** Ring max 4,193,680 of 4,194,304 B; others' ack p99 34.5 → 30.4 ms (ratio 0.88; 28 hardware threads); pool peak 111 slabs (≤ total − reserve); 101,094 zero-credit samples and 14,006 credit waits, credits > 0 after; every sent frame present after reopen. The test enforces the ring, pool, credit and frame checks on every machine. The 20% ack-p99 ratio is a Linux-8 acceptance: it is enforced only on machines with ≥ 8 hardware threads and otherwise printed with the thread count (a 3-vCPU CI runner measured 91.6 → 154.9 ms once, then passed on rerun). | `writer_backpressure_flood_T1_5` (Mac) |
-| 6 | Linux-8: N=8/N=1 ≥ 5× in memory, ≥ 3× with real fdatasync; 2 fsyncs per partition commit | **Pass on the proxy.** Docker `--cpus 8`: in memory 154,230 → 829,233 records/s (5.38×); real fs 80,883 → 456,263 records/s (5.64×); `d` 1.000 + `m` 1.000 fsyncs per framed partition commit. Journal mode: 1 journal fsync per committing iteration. | `flatsql_ps_bench --mode=scaling --io=mem|fs --writers=8` |
-| 7 | host-02: N=1 ≥ 5,000 OMM records/s durable over 50 partitions; ack p99 ≤ 40 ms at 2,500/s | **Needs host-02.** Sustained rate passes everywhere measured (Docker 4 vCPU 38,912–100,598 records/s; 1 vCPU 35,788–85,149; Mac 19,920–26,936). Ack p99 at 2,500/s follows the disk's fsync tail and the shared box's load, not the engine: the same Docker 4 vCPU profile gave file mode p50 17–20 ms / p99 153–214 ms and journal mode p50 1.1–4.0 ms / p99 120 ms at load 15–20 (that disk's `fio` fdatasync p50 0.66 ms, p99 27 ms, p99.9 142 ms), and p99 0.4–4.4 s in both modes (an A/B run of the build at da0ad51 gave the same), when the box ran at load 12–42 with other lanes' I/O. Mac APFS (`F_FULLFSYNC`, load 14–22): file p50 757 / p99 998 ms, journal p50 343 / p99 567 ms. A8 at 1/10/50 dirty partitions (Docker 4 vCPU, load 15–20): file p99 23 / 95 / 185 ms, journal 17 / 93 / 170 ms. | `--mode=host02`, `--mode=dirty`, `--journal=0|1` |
-| 8 | 30-min soak: every shared lock max hold ≤ 50 ms, p99.9 ≤ 1 ms; hot-path `malloc` per record = 0 | **Pass.** Mac, 1,800 s, 3,600,000 records over 50 partitions, 2 writers, real fs: hot-path `malloc` 0 per record; partition seqlock writer sections (144,399) max 0.027 ms, p99.9 ≤ 0.001 ms; registration lock (116 holds) max 0.025 ms, p99.9 bucket ≤ 0.033 ms. The other locks are queue mutexes held for one push or pop. `writer_hot_path_zero_malloc_T1_8`: 0 allocations over 4,000 records in file and in journal mode. (Ack p99 in that run was 6.5 s: the Mac's `F_FULLFSYNC` at 2 per partition commit, see row 7.) | `flatsql_ps_bench --mode=soak` (Mac); `writer_hot_path_zero_malloc_T1_8` |
-| 9 | 2,048 partitions, 64 active: writer committed memory ≤ 288 MiB; idle partitions hold 0 slabs | **Pass.** 80.6 MiB committed (pool 25.8 MiB touched of 192 MiB, descriptors 11.9 MiB); 0 idle partitions with slabs. | `writer_memory_2048_partitions_64_active_T1_9` |
-
-§22 amendments naming T1:
-
-| Amendment | Status |
-|---|---|
-| A2 TAG rows, RETAG, RECONCILE | Built; B1/B2 sequence gives 0 TOMBs and 0 new arrivals, B3 tombstones exactly the removed record (`writer_dedupe_retag_reconcile_A2`); RECONCILE and TAG_TOMB under crashes. |
-| A4 durable tails | Built (fsync before adoption, DURABLE_CKPT head, quarantine on fsync EIO, dedupe acks at durable commit); the crash harness's A4 mode. |
-| A8 sync rounds, zero-fill, journal fallback | Built: 2 sync rounds per iteration (file mode) or 1 (journal mode), zero-fill ahead, A8 ack p99 reported at 1/10/50 dirty partitions. |
-| A9 segmented meta log | Built (`m-<seg>` per data segment). Retirement is T3 (deviation 3). |
-| A10 type-log and registry durability | Built (type batch format, > 128 pids label checkpoints, registry truncation, EXCL heads, pid never reused). |
-| A11 merge intents | Built (INTENT_MERGE, idempotent `r`/`a`, fresh `x`/`mf`, open unlinks orphans). |
-| A14 kills and promotion | Built (TOMB_CID fan-out, REHOME keeps gseq). |
-| A15 arrivals | Segments and fence index built; compaction is T3 (deviation 4). MaxRowID = published `gseq_hi`. |
-| A19 extraction parity, sealed frames | Built; 420/420 golden rows (§5); sealed envelopes checked by magic and size only. |
-| A25 notices never block | Built. 10-minute run (Mac, 2 writers, crossed type ownership, notice queue of 1): 253,777 notices dropped, `labeled_through` lag p99 0.001 ms and max 222 ms, longest producer ack wait 414 ms (0 stalls ≥ 1 s). Under a load that saturates the type owners' labeling, the lag is throughput-bound, not bounded by the commit window. |
-| A26 ownership epochs | Built except stage-1 prep states (deviation 2). |
-| A34 published deps | `flatsql_attr_generated.h` and the A19 vectors come from the published flatc-wasm, SDS npm 1.226.0 and SDS Go 1.226.0; no sibling checkout is read at build time except the flatbuffers sources CMake already used. |
-| A35 host-02 budget | Memory measured against the host-02 profile (row 9); the ops receipt (`nproc`, `free -m`, `df`, `fio`) needs the hosts (§11). |
-
-## 10. Design deviations
-
-Each entry: what the design says, what was built, why, and the evidence.
-
-1. **Merge outputs are built and synced by a maintenance helper thread**
-   (design §4.5/§11: the owner merges between commits; helpers only for split
-   hot partitions, §12). The owner plans the merge (INTENT_MERGE), a helper
-   writes `r`/`a` at plan-derived offsets and fresh `x`/`mf` files, syncs them,
-   and the owner commits MERGE_DONE. Why: building a run on the writer stalled
-   every partition it owns (maintenance step max at 50 dirty partitions, Linux
-   1 vCPU profile: 325.8 ms with merges on the writer, 125.7 ms with the helper
-   sharing that one CPU); the owner law puts
-   compaction "per partition, off the hot path". The helper writes only new
-   files or regions no reader can see before MERGE_DONE, re-validates the owner
-   epoch before every mutation (A26), and a HANDOFF waits for it
-   (`writer_single_writer_under_rebalance_T1_4`: helpers stalled 100 ms, 0
-   non-owner writes). Its syncs no longer ride the commit's first sync round.
-2. **No stage-1 helpers; ring entries carry no prep state** (§5.2, A26 "FREE →
-   CLAIMED(epoch) → PREPARED"). The owning writer verifies, extracts and
-   checks CIDs itself. Scaling came from partitions spread over writers
-   (T1 #6 met without them, see §9), so the extra protocol bought
-   nothing measurable. A26's other clauses (owner word, epoch re-validation,
-   slab grace) are built.
-3. **A torn-both-heads rebuild replays the meta log from segment 0** (A9:
-   "scans only the active m segment plus the manifest"). Sealed `m` segments
-   are retired by T3 (A12 lifecycle), which also records `first_live_m_seg`;
-   until then segment 0 onward is the only complete source.
-4. **A15 arrivals compaction is not built.** Arrivals are segmented with a
-   gseq fence index (`g-<seg>.fsg`, `g.fsf`); dropping dead entries and
-   folding DEAD entries out of catalog runs belong with T3's compaction and
-   quota planner, which trigger them. MaxRowID is the published `gseq_hi`.
-5. **The A8 commit journal is a configuration mode, off by default.** §22.4
-   ruling 5 makes it the fallback "if a host misses T1 #7"; host-02 has not
-   been measured (no ssh from this lane). Both modes pass the crash harness
-   (half its stores run journaled) and are benchmarked in §9.
-6. **A19 golden vectors come from a local archive day, not the host-02
-   inventory sample** (no host access). The frames are real Space-Track GP
-   records (`/opt/data/sdn-archive/spacetrack/gp/2026/2026-09-27.json.gz`)
-   plus constructed edge cases; the expected rows come from the Go functions
-   themselves.
-7. **New rule directive `require <table path>`**: OEM's Go extraction returns
-   no keys at all when the first block has no OBJECT; the rule language had no
-   way to say that.
-8. **New index kind `TAG_DEAD`** (A2 lists only TAG_TOMB rows). A PUT row is
-   also its record's first tag instance; posting its TAG_TOMB under `DEAD`
-   would have killed the record. `TAG_DEAD` keys a dead tag instance
-   separately from a dead record.
-9. **A full type L0 directory (48 blocks) makes the type owner wait for its
-   merge** instead of committing more label batches; the head lists at most
-   48 unmerged blocks.
-10. **The registration lock holds no I/O.** A registry frame reserves its
-    offset under a short mutex, is pwritten outside every lock, and returns
-    once all earlier frames are written (so its fsync covers them); a failed
-    pwrite breaks the registry for the run and open truncates at the hole.
-    The hint head is encoded under the lock and written after it. A second
-    registrant of the same key waits for the first. With the fsyncs inside,
-    the 30-minute Mac soak measured a 92 ms hold; with only the pwrite inside,
-    1.8 ms (a pwrite queued behind another registrant's `F_FULLFSYNC`).
-11. **In journal mode heads carry no DURABLE_CKPT meaning.** Heads are written
-    every commit and made durable by the journal checkpoint; open trusts
-    `max(head, replayed journal)` and never adopts a journaled batch its
-    journal did not replay.
-12. **Backpressure acceptance "credits go to 0"** is measured as samples with
-    less than one entry of credit (< 1 KiB) and producer credit waits during
-    the flood, then credits > 0 after it.
-13. **Journal checkpoints run on their own thread and are paced** (a 50% duty
-    cycle per file sync). Back-to-back checkpoint fsyncs queued ahead of the
-    journal fsyncs acks wait on, and a long checkpoint on the merge helper
-    delayed merges until L0 directories filled.
-
-## 11. Needs a Linux host or ops
-
-Commands for the rows this lane could not measure (run from a flatsql
-checkout at the landed commit, `cmake --build cpp/build -j 8 --target
-flatsql_ps_bench flatsql_ps_test` first):
-
-- **T1 #7 on host-02** (4 vCPU / 7.9 GiB), on the store disk, both modes:
-  `cpp/build/flatsql_ps_bench --mode=host02 --dir=<store disk>/ps-bench --journal=0` and
-  `--journal=1`; `cpp/build/flatsql_ps_bench --mode=dirty --dir=<store disk>/ps-bench --journal=0|1`.
-  If file mode misses p99 ≤ 40 ms and journal mode meets it, §22.4 ruling 5
-  selects `commitJournal` for that host.
-- **A8/A35 ops receipt** on host-01 and host-02: `nproc; free -m; df -h <store disk>;
-  fio --name=fds --rw=write --bs=16k --size=256m --fdatasync=1 --directory=<store disk>`
-  (p50/p99 of `sync`).
-- **T1 #6 on a real Linux-8 box**: `cpp/build/flatsql_ps_bench --mode=scaling --io=mem --writers=8`
-  and `--io=fs --dir=<ext4 dir>`.
-- **LazyFS** power-loss runs (the crash harness emulates the loss modes in
-  memory; a filesystem-level run needs Linux with FUSE):
-  `lazyfs` mounted at `<dir>`, then `flatsql_ps_test --test=open_clean_1M_records_256_partitions_T1_2_real_fs --dir=<dir>`
-  with `lazyfs::clear-cache` between ingest and open.
-
-# Part II: readers and SQL (T2)
-
-## 12. Code map
-
-| Path | Contents |
-|---|---|
-| `ps/lane.h`, `src/ps/lane.cpp` | Reader instances, lanes, the mailbox ABI (request slots, result rings, parking, cancellation), the native client, `CounterReader` (counters without a lane, A28). |
-| `ps/lane_arena.h`, `src/ps/lane_arena.cpp` | Per-lane TLSF arenas behind `SQLITE_CONFIG_MALLOC`, instrumented SQLite mutexes, the null VFS. |
-| `ps/snapshot.h`, `src/ps/snapshot.cpp` | The reader's view of committed state: registry view, partition and type snapshots, rows, frames, attributes, posting scans and lookups, lazily read L1 runs, the instance's shared index cache, arrivals, GONE counting. |
-| `ps/vtab.h`, `src/ps/vtab_partition.cpp` | Record virtual tables: module, plans (`xBestIndex`), columns, partition-level row sources. |
-| `src/ps/vtab_fanout.cpp` | Type level: pruning, the k-way merge, arrivals order with REHOME/GONE joins, the cid catalog, `<TYPE>_current`, offset paging. |
-| `src/ps/vtab_meta.cpp` | `flatsql_partitions`, `flatsql_lanes`, `flatsql_licences`, `flatsql_arrivals`, `flatsql_types`. |
-| `src/ps/admission.cpp` | Plan admission (bounded bit), the sandbox authorizer. |
-| `ps/result_block.h`, `src/ps/result_block.cpp` | RB1 encoder/decoder, raw-stream framing. |
-| `cpp/test/ps/{lane,fanout_merge,int64_exact,lane_isolation,snapshot,arrivals_paging,reader_concurrency}_test.cpp` | T2 tests; `reader_fixtures.*` helpers; `vectors/rb1_int64.hex` (the RB1 golden vector for T6's Go decoder). |
-
-## 13. Reader instances and lanes
-
-- A `ReaderInstance` runs L lane threads of one class: **interactive**
-  (index-bounded plans only), **bulk** (any plan; `setpriority` nice +10 on
-  Linux, QoS utility on darwin) or **sandbox** (untrusted SQL under a work
-  budget, A28). Instances share nothing with a writer: they read files only.
-- Each lane owns a SQLite connection (`:memory:`, `SQLITE_OPEN_NOMUTEX`, the
-  `flatsql_ps_null` VFS that refuses every file open, `temp_store=MEMORY`), a
-  TLSF arena (8 MiB interactive and sandbox, 128 MiB bulk) installed through
-  `SQLITE_CONFIG_MALLOC` (thread-bound dispatch), lookaside carved from that
-  arena, its own file handles (LRU of host handles) and caches.
-- SQLite is built separately for the readers (`sqlite3_ps`):
-  `THREADSAFE=2`, `DEFAULT_MEMSTATUS=0`, `OMIT_WAL`, `TEMP_STORE=3`.
-- Lane threads get explicit stacks (2 MiB default, ≥ 1 MiB enforced) with a
-  guard page and a canary word checked every loop iteration (A30).
-- **Mailbox ABI** (what the Go router programs against): a pool of request
-  slots in instance memory. A slot is a `SlotHeader` (state, cancel word,
-  doorbells, budgets, status, statistics) followed by a request area (SQL,
-  then RB1-encoded parameters) and an SPSC result ring. Clients claim a free
-  slot by CAS, write the request and queue its index on an MPMC queue; an
-  idle lane is woken through its doorbell word.
-- **Parking (A28).** A lane never blocks on output: when a slot's ring is
-  full the statement parks (its `sqlite3_stmt` stays resumable) and the lane
-  serves other slots, up to 8 parked statements per lane. A client read that
-  frees space rings the owning lane.
-- **Cancellation** is the slot's cancel word, polled by the progress handler
-  every 4,096 VM steps and by every vtab loop every 4,096 entries (A21, A28).
-  The instance's stop word is polled the same way. No deadline, no abandon.
-- **A12 announcements.** Each lane publishes the start time of its oldest
-  running (or parked) statement; `ReaderInstance::oldestActiveStart()` is the
-  minimum. The reclaimer (T3) may unlink files a SWAP retired at time t once
-  that minimum is later than t, checked twice a grace apart.
-
-## 14. Snapshot protocol (§8)
-
-1. Each statement re-reads the registry head and parses new frames only
-   (copy-on-write view; a changed incarnation rebuilds the view).
-2. A partition is snapshotted once per statement at first touch: the valid
-   head slot with the highest gen (8 KiB, one pread), then its manifest
-   (immutable, cached per lane).
-3. Type-level statements snapshot the type head first (labels inline, or the
-   A10 checkpoint plus deltas for > 128 partitions, cached incrementally),
-   then each partition. **V_p = min(pseq_hi, labeled_through[p]).** A
-   partition head older than `labeled_through` (the writer pwrites the head
-   right after the commit its type owner may already have labeled) is re-read,
-   bounded (4 ms), so V_p never hides a promotion.
-4. Rows come from `r-<seg>` (merged range, per the manifest) or the meta
-   batch the head's L0 directory names; payloads from `d-<seg>` at
-   `(off, len)`, CRC-checked against the row's `dataCrc`.
-5. Liveness: a DEAD posting with killer ≤ V_p. Type level: a row is FIRST when
-   it has no REPEAT posting (REPEAT is a lookup kind with a bloom; a REPEAT
-   label always leaves one), otherwise its latest LABEL decides (A14
-   promotions). Readers take no lock shared with a writer.
-6. A file named by the snapshot that fails with ENOENT before the first row
-   re-snapshots once; after a row it returns `FLATSQL_SNAPSHOT_GONE`
-   (retryable). The announcement protocol makes that happen only after a
-   restart.
-
-## 15. SQL surface (§9, A17, A18)
-
-Virtual tables are created lazily in the lane's temp schema the first time a
-statement names them:
-
-| Table | Rows |
-|---|---|
-| `sds_p_<producer>__<TYPE>` | every live PUT of one partition (partition-level visibility) |
-| `<TYPE>` | the fan-out: one row per live CID, FIRST copies only |
-| `<TYPE>@<source>` | `<TYPE>` with a live tag instance of that source |
-| `<TYPE>_current` | latest live record per stored supersede key, else per object key (OBJECT_EPOCH) |
-| `flatsql_partitions`, `flatsql_lanes`, `flatsql_licences`, `flatsql_arrivals`, `flatsql_types` | meta (never public) |
-
-Record vtabs expose the root table's fields (BFBS reflection, vtable-slot
-order; sealed rows project NULL) and hidden columns `_pseq _cid _cid_bin
-_epoch _arrival _gseq _producer _source _source_name _provider _batch _peer_id
-_signature _data _offset _len _kind _rowid _pid`. `_source` is
-`'<TYPE>@<source_name>'`; `_rowid` is `_pseq` on a partition and `_gseq` at
-type level.
-
-Plans (`xBestIndex`), each recording a bounded bit in its `idxStr`:
-
-| Access | Claims | Order |
-|---|---|---|
-| CID | `_cid` / `_cid_bin` EQ (type level: the cid catalog) | – |
-| pseq | `_pseq` / `_rowid` EQ or range (partition) | pseq ± |
-| gseq | `_gseq` / `_rowid` EQ or range (type: arrivals), OFFSET pushdown | gseq ± |
-| COL | indexed column EQ (`col <n> u64pos|str:FIELD` rules) | – |
-| tag | `_provider` / `_batch` / `_peer_id` EQ | – |
-| source | `_source` / `_source_name` EQ (+ `_epoch` range; the alias) | epoch ± |
-| epoch | `_epoch` range or `ORDER BY _epoch` (EPOCH index) | epoch ± |
-| default | none of the above at type level (EPOCH_CID index) | seconds DESC, CID ASC |
-| full | anything else | unbounded |
-
-A plan is bounded when its index range is closed or a LIMIT applies to an
-index order the vtab emits. The fan-out prunes by `_producer` EQ, merges
-index-ordered sub-cursors on (key, CID, pid, pseq) with a heap, drops
-adjacent duplicate CIDs, and stops at LIMIT.
-
-**Admission.** Interactive lanes read the prepared statement's own program
-(`sqlite3_stmt_explain`): any `VFilter` whose plan is unbounded returns
-`FLATSQL_NEEDS_BULK` before a row is examined. Every statement reports
-rows examined, bytes read, index entries and fence reads.
-
-**Untrusted SQL (A28, §22.4 ruling 7).** Sandbox requests keep the SandboxCaps
-contract: one read-only SELECT, the authorizer allow-list mapped onto the
-record vtab names (meta tables never public), `<TYPE>` bounded to the newest N
-arrivals (A18; `OMM` 400,000, other types 10,000), and a work budget — rows
-examined, bytes read, VM steps — that is an admission limit returning the
-existing `timeout` code. Sandbox SQL never runs on the shared bulk lane: it is
-refused `needs-bulk` there, admitted by plan on interactive lanes, and runs
-any plan on a dedicated sandbox lane under the budget.
-
-## 16. Results (RB1, raw stream)
-
-`ps/result_block.h` has the byte layout. Integers are exact 8-byte int64
-(no float64 rounding above 2^53, §2); REAL, TEXT and BLOB cells are typed per
-cell; an end record carries the status and the work counters. Raw-stream mode
-emits `[u32le size][bytes]` per BLOB cell, so `SELECT _data …` streams the
-stored frames verbatim. `cpp/test/ps/vectors/rb1_int64.hex` is the golden
-vector for T6's Go decoder.
-
-## 17. Index access and caches
-
-- **L0 blocks** are read whole once (CRC-checked) and kept as a kind
-  directory; each kind's section (entries, offsets, bloom) is cached separately
-  and binary-searched. A statement resolves each snapshot's sections once per
-  kind.
-- **L1 runs** open lazily: footer and TOC, the metadata CRC checked once per
-  lane, then a kind's fences a page (128 fences, 5 KiB) at a time and its
-  bloom while it fits (§37).
-- **Ascending scans prime runs lazily.** A run joins a posting merge with a
-  lower bound of its first entry (the scan's `lo`, or its first block's fence
-  prefix) and reads its first 4 KiB block only when it reaches the top of the
-  merge. The default order (`EPOCH_CID`, newest first) and gseq order are
-  ascending, so a LIMIT window reads blocks only from the runs it draws rows
-  from, not one block from every run of every partition. Descending scans
-  prime eagerly (a fence gives no upper bound).
-- **The instance's shared cache** holds these immutable pieces (L0
-  directories and sections, fence pages, blooms) for every lane: one shard
-  per MiB of budget (1 to 64), each only ever try-locked, so a busy shard is
-  a miss and a lane never waits on another lane (writers never touch it). A
-  lane-private front, an LRU by bytes, serves repeated hits without any lock.
-- Default budgets: 16 MiB shared per instance, 4 MiB per lane for each of
-  its private cache, its resident runs and its front, 4,096 host handles per
-  lane (the host's handles are virtual; T5 bounds real fds with its LRU).
-  Every cache is bounded by bytes (§37).
-
-## 18. Arrivals, offset paging, dead history (A14, A15)
-
-- Arrivals rows merge-join two type postings by gseq: **REHOME** (the latest
-  promotion keeps the gseq, A14) and **GONE** (a gseq whose last live copy
-  died; new, posted by the type owner). No per-entry lookup.
-- **Offset paging.** `ORDER BY _gseq|_rowid [DESC] LIMIT n OFFSET k` pushes the
-  OFFSET into the vtab. Live entries in positions [a, b) = (b − a) − GONE
-  gseqs in [g_a, g_b), counted from L1 fences (whole blocks by their counts,
-  the two edge blocks read) and the unmerged L0 sections; a binary search over
-  positions finds the k-th live entry in O(log n) probes.
-- **Dead runs.** A GONE entry starts a gallop over the same counts to the next
-  live position; short runs fall back to per-entry checks.
-- `flatsql_types` exposes MaxRowID (`gseq_hi`), TotalCount
-  (`first_live_count`) and the SnapshotID inputs (A16).
-
-## 19. Writer-side changes made by T2
-
-T2 owns the whole flatsql component; these changes to T1's writer serve the
-readers and are covered by T1's suites as well as T2's.
-
-| Change | Why |
-|---|---|
-| Index kind `EPOCH_CID` (19): complemented `floor(epoch_ms/1000)` + the A17 CID key → PUT pseq | A19's default order (seconds DESC, text CID ASC) as one ascending index scan, with copies of a CID adjacent for the merge. |
-| Type kind `GONE` (0x204): a gseq whose last live copy died | Dead arrivals counted by fences: offset paging (T2 #7), dead-run skipping (T2 #8), merge-joined arrivals. |
-| `REPEAT` (0x203) is a lookup kind (bloom) | The type-level FIRST test is a bloom probe for most rows; LABEL is read only for REPEAT copies. |
-| SWAP seam: `Engine::swapSegment`, ctl `SWAP{seg, gen, oldCgen}`, manifest segment `cgen`, `c-<seg>-<gen>.{fsd,fsr,fsa}`; the owner reads compacted files, open replays SWAP | The smallest seam T3's compaction plugs into (§20 #5 uses a verbatim copier through it). |
-| Catalog precedence at equal tcs: DEAD > PROMOTED > REPEAT > FIRST (writer `upsertCopy`, reader `catalog`/`labelOf`; REHOME candidates of one tcs resolved by liveness) | **T1 defect** found by the fan-out oracle: a batch that promoted a REPEAT and then killed it left two entries with one tcs; value order made the copy read as live, and a returning copy was labeled REPEAT instead of FIRST. |
-| A cid's catalog is gathered, resolved per copy and loaded without its dead copies | **T1 defect** found by the A14 reader test: a cid killed and re-added over 1,000 times overflowed the per-batch copy table, dropped its live REPEAT, and died without an heir (63 of 64 promotions at round 1,027). |
-| Writer threads tag themselves for the lock report | Lock-set disjointness instrumentation (T2 #1). |
-| Test fixture `buildRecord` passes a NUL-terminated file identifier | `FinishSizePrefixed` takes a C string; the fixture passed the type's four `fid` bytes, and Debug builds (CI) asserted when the next byte was not zero (T2's type variants). |
-
-## 20. Acceptance (§18 T2 as amended)
-
-Machines: **Mac** = the owner's Mac Studio (Darwin 25.3.0, arm64, 28 hardware
-threads), shared with other lanes; the 1-minute load average is recorded per
-run (20–46 during these). **Mac mem** runs use the in-memory test host (no
-fsync), **Mac APFS** the native host on APFS (`F_FULLFSYNC`). **Docker** =
-Linux 6.12 arm64 in Docker Desktop on that Mac (a 16-vCPU VM shared with the
-Mac's load), either `--cpuset-cpus 0-7` (8 pinned vCPUs, "Docker-8") or
-`--cpus 8` (a CFS quota over 16 vCPUs, whose throttling periods show up as
-100 ms+ tails; used only for correctness and disjointness); ext4 on the VM's
-disk with `fdatasync`. None is a quiet Linux-8 box: latency bounds are enforced
-by the tests only on one (a release build, 8+ usable hardware threads, load
-below a quarter of them) and reported everywhere else. Numbers come from
-`MEASURED` lines of `flatsql_ps_test` and `flatsql_ps_bench --mode=test` on
-task-branch builds of 2026-09-28; rows 1, 4 and A28 are from the final build
-(lazy run priming, §17).
-
-| # | Acceptance | Result | Where |
-|---|---|---|---|
-| 1 | 8 writers saturate 256 partitions, 16 lanes, 10 min: `flatsql_partitions` p99 ≤ 1 ms; window LIMIT 1000 p99 ≤ 10 ms; reader and writer lock sets disjoint; max lane lock wait ≤ 1 ms | **Disjointness and lock wait pass everywhere; the latency bounds are not met on any box measured (all of them CPU-saturated by the test and by other work: needs a quiet Linux-8 box).** Every SQLite mutex and the shared index cache are acquired by lanes only (writer acquisitions 0 in every run); max lane lock wait 0.000–0.022 ms (the cache is only ever try-locked). The engine's own cost, writers stopped and one client (100 statements, 1–4 L0 blocks per partition after merges, 4.7–18 M records): Mac window p50 3.0–8.1 ms, p99 6.3–48 ms following the Mac's load, `flatsql_partitions` p99 0.95–1.3 ms; Docker-8 in-memory window p50 6.3 / p99 60 ms, ext4 p50 14.6 / p99 154 ms. Under saturation the lanes share the CPUs with 8 producer threads, the writers and their merges: Mac mem 40 s at load 46 (15.4 M records): `flatsql_partitions` p99 6.5 ms, window p50 14.5 / p99 91 ms, source window p99 77 ms, counters without a lane (A28) p50 0.42 / p99 2.0 ms. Docker-8 in-memory 30 s at VM load 12 (8.6 M records): `flatsql_partitions` p99 15.7 ms, window p50 75 / p99 259 ms. Docker-8 ext4 60 s at VM load 19 (8.1 M records): `flatsql_partitions` p99 24 ms, window p50 278 / p99 762 ms (an earlier build's run at VM load 18: p50 3.6 / p99 347 ms; host contention decides). Mac APFS 10 min at load 16 (earlier build, 14.8 M records, fsync-bound): 0 errors, window p50 70 / p99 370 ms. | `readers_under_saturating_writers_T2_1[_full]` (`--dir` for a real file system) |
-| 2 | 10,000 randomized workloads (a CID across up to 8 producers, supersede, tombstones, epoch-less types) equal a brute-force reference: one row per CID, FIRST semantics, order; rows examined ≤ LIMIT × (partitions + 1). A14: readers during FIRST deaths never miss a live CID | **Pass.** Mac mem: 10,000 workloads (49,833 promotions, 10,064 type deletes, 22,043 supersedes, 13,119 RECONCILEs), 229 s; every Q1–Q5 check (default order, LIMIT prefix and its examined bound, CID lookups, gseq order, partition counts) against the Inspector's reference. A14: 10 min, 2,979 rounds of FIRST deaths, 190,656 promotions, 5,179 reader statements, 0 missing CIDs, 0 gseq changes. Two T1 defects were found on the way (§19). Docker (`--cpus 8`): 500 workloads pass. | `fanout_randomized_vs_bruteforce_T2_2_full`, `fanout_readers_during_first_deaths_A14_full` |
-| 3 | −2^63, 2^53+1, 2^63−1 round-trip exactly through RB1 (C++ encoder; Go decoder vectors for T6) | **Pass.** Encoder/decoder in any byte split, the golden vector `vectors/rb1_int64.hex`, and parameters and literals through a lane. Docker: pass. | `int64_rb1_encoder_decoder_exact_T2_3`, `int64_exact_through_sql_lane_T2_3` |
-| 4 | Bulk statement past its 128 MiB arena → `SQLITE_NOMEM`, interactive p99 within ±10%, nothing poisoned; unbounded plan on an interactive lane → `FLATSQL_NEEDS_BULK` in ≤ 1 ms with 0 rows examined | **NOMEM, no poisoning and NEEDS_BULK pass; the ±10% ratio holds on Docker-8 and is noise-bound on the Mac.** Every hog returns `kRsNoMem`; the same lane then answers, its arena passes a full consistency check and holds 160 KiB. NEEDS_BULK: lane time p50 0.012–0.016 / p99 0.051–0.099 / max 0.17 ms, 0 rows examined, over 200 unbounded shapes (Mac and Docker). Ratio (p99 with the hog / without, four alternating rounds): Docker-8 at VM load 2.0 and 3.5: 1.030 and 1.087 (rounds 0.95–1.09 and 1.02–1.43); Docker `--cpus 8`: 0.947; Mac control runs (no hog) 1.02–1.05, with the hog 0.94–2.3 at load 20–47 (one busy core streaming 300 MB beside the lanes; no shared lock, see #1). | `lane_isolation_bulk_nomem_T2_4`, `lane_needs_bulk_under_1ms_zero_rows_T2_4` |
-| 5 | 1,000 compaction SWAPs under load: statements started before a SWAP complete with pre-SWAP rows. A12: 10-min bulk export under continuous compaction, 0 SNAPSHOT_GONE | **Pass.** Mac APFS: 1,000 SWAPs while ingest runs, 2,406 partition scans verified row by row against the frames sent, 987 of them spanning a SWAP (up to 28 SWAPs during one statement), 0 errors, every retired file set unlinked once announcements allowed. A12, Mac APFS 10 min: 2,769 type-level exports (84.5 M frames), 8,153 SWAPs, 8,090 retired sets unlinked, 0 SNAPSHOT_GONE. Negative control: unlinking without the announcement check gives SNAPSHOT_GONE. Docker (`--cpus 8`, in-memory): 1,000 SWAPs, 56 partition scans all spanning SWAPs (up to 257 during one), 0 errors; A12 10 min: 18,891 exports (296.5 M frames) across 300 SWAPs (the in-memory cap), 0 SNAPSHOT_GONE. | `snapshot_swaps_under_load_T2_5`, `snapshot_bulk_export_under_compaction_A12_full --dir=…`, `snapshot_unlink_without_announce_is_snapshot_gone` |
-| 6 | Arrivals paging while 8 writers produce: gseq strictly increasing within and across pages; no gseq ≤ the snapshot head appears after the snapshot; union of pages = the FIRST-live set at the snapshot. A14: a CID's gseq never changes while a copy lives | **Pass.** Mac mem: 62 syncs (18,716 pages of 500) against 1.44 M records from 8 producers into 32 partitions; every sync equals the oracle (final arrivals ≤ its MaxRowID), 0 violations, 0 gseq changes. Docker: 46 syncs, 9,648 pages, 921,888 records, 0 violations. | `arrivals_paging_while_writers_produce_T2_6` |
-| 7 | Page 10,000 of 100 rows on a 3 M-record type examines ≤ 2 × 100 rows plus fence reads | **Pass.** Mac mem, 3,000,000 records, 10% scattered deaths: OFFSET 999,900 in gseq order examined 100 rows and 132 arrival entries with 268 fence reads, 2.5 ms; pages equal a full scan's (60 random offsets, ascending and descending, 30% deaths). Docker: 100 rows, 150 entries, 196 fence reads, 7.3 ms. | `offset_paging_page_10000_T2_7_full`, `offset_paging_matches_reference_with_deaths` |
-| 8 | A full sync of a 99%-dead history examines ≤ 2 × (live rows + fence reads) | **Pass.** 100,000-entry history, 1,000 live. Deaths clustered: 1,000 rows and 1,008–1,009 arrival entries examined, 724–1,052 fence reads. Deaths scattered (1 in 100 live): 1,000 rows and 2,001 entries examined, 57,388–67,740 fence reads (deviation 4). Docker: clustered 1,000 rows / 1,008 entries / 707 fence reads; scattered 1,000 / 2,001 / 57,492. | `dead_history_full_sync_T2_8` |
-| A30 | A maximum-depth SQL expression on a lane | **Pass.** A depth-1000 expression (`SQLITE_MAX_EXPR_DEPTH`) runs; depth 1001 is refused; the lane serves on, canary intact. | `lane_max_depth_expression_A30` |
-| A28 | 8 clients reading at 10 KB/s: counter p99 ≤ 10 ms, window p99 ≤ 50 ms. A sandbox cartesian join returns `timeout` while the bulk lane stays free | **Counter bound met on the Mac and Docker-8 in-memory; window bound met only at Mac load 20; the sandbox contract passes.** 8 slow clients park their lanes while others read. Mac mem 40 s: counter p99 1.1 / 4.1 / 2.4 ms and window p99 31.9 / 58 / 64 ms at load 20 (earlier build) / 31 / 46. Docker-8: counter p99 6.4 (in-memory) and 14.1 ms (ext4), window p99 148 and 224 ms at VM load 12 and 19. The join returns `timeout` from the work budget while a bulk statement completes in 1.5–2.3 ms; meta tables are not public; sandbox SQL is refused on the shared bulk lane. | `readers_under_saturating_writers_T2_1_full`, `lane_sandbox_contract_A28` |
-
-A12's announcement protocol, A14's promotion reads, A15's page fill and
-MaxRowID, A17's CID order in the default merge, A18's `_source` and bounded
-`<TYPE>`, A21's cancellation polls, A28 and A30 are covered by the rows above
-and `lane_test.cpp`.
-
-## 21. Design deviations (T2)
-
-Each entry: what the design says, what was built, why, and the evidence.
-
-1. **Fan-out sub-cursors run inline; no idle-lane borrowing** (§5.3: "borrows
-   idle lanes … as sub-cursor producers … when no lane is idle, the
-   sub-cursors run inline"). Only the inline form is built. A partition
-   sub-cursor costs its sections' binary searches and one block per L1 run;
-   the measured window cost (§20 #1) is dominated by per-row label, liveness
-   and row reads that a producer lane would not remove. Borrowing is an
-   optimization T6 can add behind the same `RowSource` interface.
-2. **Type-level FIRST test per row, not a REPEAT merge-join** (§8.6). Index
-   order is not pseq order, so a merge-join with the REPEAT run applies only to
-   pseq scans. Rows test the REPEAT bloom (REPEAT became a lookup kind); only
-   rows with a REPEAT posting read their latest LABEL. Arrivals order does
-   merge-join (GONE, REHOME).
-3. **Offset paging by GONE counts in arrivals order, not per-block live-FIRST
-   counts in L1 fences** (§9, A17). T1's merges write each block's entry count
-   as its live count, and liveness changes after a merge; a new type kind,
-   GONE, is counted by fences instead (§18). Offset paging is pushed down for
-   `_gseq`/`_rowid` order (the data explorer's order); the default and CID
-   orders page through SQLite (O(offset)).
-4. **A15 #8 without arrivals compaction.** Arrivals compaction (dropping dead
-   entries) is T3's. Dead runs are skipped by galloping over GONE fence counts;
-   the bound holds for rows and for arrival entries examined, but a history
-   whose deaths are scattered one-in-a-hundred costs about 60 fence probes per
-   live row (§20 #8) until T3 compacts it.
-5. **RB1 cells are typed per cell** (§9: a type vector per block). SQLite
-   values are dynamically typed per row.
-6. **One result ring per request slot** (256 KiB default), parked per
-   statement, rather than one 1 MiB ring per lane (A28 parking is per
-   statement either way).
-7. **Sandbox work budget adds VM steps** to rows examined and bytes read, so a
-   statement that reads nothing (a recursive CTE) is bounded too; the A18
-   window counts the newest N arrivals entries (dead included), not N
-   FIRST-live records (one entry read instead of a count).
-8. **`<TYPE>@<source>` matches live tag instances of the FIRST copy's PUT** in
-   its partition. An untagged record never matches a source (the legacy
-   `_source` falls back to the producer token for untagged rows); T6's
-   equivalence run on a migrated copy decides whether that case exists.
-9. **Type-level visibility is labeled rows only**; the A20 read-your-writes
-   scan of the unlabeled gap belongs to `GetRecord` (T6), which can use the
-   partition vtab (partition-level visibility is the acked HWM).
-10. **Interactive lanes at nice −5 on ≤ 2 vCPU** (A28) needs privileges the
-    engine does not have natively; bulk lanes do take nice +10 on Linux. The
-    host (T5/T6) sets both.
-11. **Shared index cache, try-locked.** The design budgets a 16 MiB block cache
-    per reader instance; the built cache holds parsed index pieces (L0 sections,
-    fences, blooms) for all lanes of an instance and is only ever try-locked, so
-    lanes never wait on each other. Per-lane budgets (4 MiB) hold manifests and
-    run views; 4,096 host handles per lane (virtual handles; T5 bounds real fds).
-12. **SWAP seam built in the writer** (T3's scope). `Engine::swapSegment` copies
-    a fully merged sealed segment verbatim to `c-<seg>-<gen>.*`, commits SWAP
-    with a new manifest, and reports the retired files; it has no
-    INTENT_COMPACT (T3 adds it with crash handling). Rows stay dense by pseq.
-13. **Lock disjointness natively covers SQLite's mutexes and the shared
-    cache**; the host handle table is measured under WasmEdge (A29, T5/T6).
-14. **CounterReader reads heads** (O(partitions) preads), the A28 path without
-    a lane; the Go snapshot refreshed on every acked commit is T6's.
-
-## 22. Running the T2 tests; what needs a Linux-8 box
-
-```
-cmake --build cpp/build -j 8 --target flatsql_ps_test flatsql_ps_bench
-cpp/build/flatsql_ps_test --test=lane_                     # lanes, parking, sandbox, isolation, A30, C ABI
-cpp/build/flatsql_ps_test --test=fanout_randomized_vs_bruteforce_T2_2_full   # 10,000 workloads
-cpp/build/flatsql_ps_test --test=fanout_readers_during_first_deaths_A14_full # 10 min
-cpp/build/flatsql_ps_test --test=snapshot_ [--dir=<real fs dir>]
-cpp/build/flatsql_ps_test --test=snapshot_bulk_export_under_compaction_A12_full --dir=<dir>  # 10 min
-cpp/build/flatsql_ps_test --test=offset_paging_page_10000_T2_7_full           # 3 M records
-cpp/build/flatsql_ps_bench --mode=test --test=readers_under_saturating_writers_T2_1_full [--dir=<dir>]
-```
-
-The default suite runs shortened forms of every slow test. Long runs that
-write a lot use `--dir` (the in-memory test host keeps every file it held).
-
-**T2 #1 and #4 on a quiet Linux-8 box** (8 cores, ext4, nothing else
-running), from a checkout at the landed commit:
-
-```
-cpp/build/flatsql_ps_bench --mode=test --test=readers_under_saturating_writers_T2_1_full --dir=<ext4 dir>
-cpp/build/flatsql_ps_test --test=lane_isolation_bulk_nomem_T2_4
-```
-
-Both enforce their bounds on such a box (a release build, 8+ usable hardware
-threads, 1-minute load below a quarter of them; the load is sampled at the end
-of the run, so the test's own writers count). The disjointness claim itself is
-measured under WasmEdge with the C host module in T5/T6 (A29).
-
-What to expect there: the window's own cost is 3–8 ms at p50 (§20 #1), so the
-10 ms p99 bound leaves little room for waiting on a CPU. The test runs 8
-producer threads, the writers and their merges and 16 lanes on 8 cores; when
-they saturate the CPUs, the window p99 is decided by the scheduler, not by the
-engine. If the bound fails there, the next steps are the design's own levers:
-fewer writer threads than cores (design §5.1: `clamp(cores−2, 1, 16)`), interactive
-lanes at a higher priority than writers (design A28 gives nice −5 only on ≤ 2 vCPU),
-and idle-lane sub-cursors (§21 deviation 1).
-
-# Part III: compaction, reclamation and quota (T3)
-
-## 23. Code map
-
-| Path | Contents |
-|---|---|
-| `ps/compaction.h`, `src/ps/compaction.cpp` | Manifest versions 2 and 3 (§40), the compacted rows format, retire items; the compaction pipeline (plan, build, SWAP, apply, abort). |
-| `src/ps/reclaim.cpp` | The per-partition file ledger (`disk_bytes`; a hash table, §40), segment lookups by binary search, the RETIRE and UNLINKED records and the RETIRE valve, reader-gated unlinking, meta-segment retirement (A9), open-time cleanup; the same for the type logs (meta log rotation and retirement, retired catalog runs and manifests, the type ledger). |
-| `ps/quota.h`, `src/ps/quota.cpp` | The quota planner, the space emergency, the ballast; the planner's per-segment summary and the compaction candidate index, kept from a change feed (§40). |
-| `src/ps/sources-t3.cmake` | Registers the T3 sources and tests on the targets `cpp/CMakeLists.txt` defines. |
-| `cpp/test/ps/{compaction,orphan,quota,bookkeeping_scale}_test.cpp` | T3 tests (the last: §40). `checkPartitionDir` and `checkTypeDir` (fixtures) walk a partition's or a type's directory against the files its head and manifest name. |
-
-## 24. Compaction (§11, A11, minor 1)
-
-A compaction rewrites a run of sealed, fully merged segments `[seg, segEnd]`
-into one new file set, `c-<seg>-<gen>.{fsd,fsr,fsa}` plus
-`x-<seg>-<gen>.fsx` and `mf-<gen>.fsm`:
-
-1. The owner plans. `INTENT_COMPACT{seg, segEnd, gen}` rides the next batch; no
-   output exists before it is durable. The head carries the intent.
-2. A compaction thread builds. It reads the DEAD and TAG_DEAD postings over the
-   inputs' pseq range from every run and L0 block at or after the inputs, keeps
-   a killer only when it is at or below the plan's kill bound (the type owner's
-   `labeled_through`), and decides per row:
-   - PUT, LICENCE and CTL rows with a killer go;
-   - RETAG rows go when their instance is TAG_DEAD, or their PUT is dead or gone;
-   - TOMB, CTL_TOMB and TAG_TOMB rows go only when an earlier SWAP removed their
-     target (minor 1): outside the inputs, or VOID within them.
-
-   It copies the surviving frames, attributes and rows in 4 MiB slices, filters
-   the inputs' L1 runs down to the surviving rows' postings (every partition
-   posting's value is the pseq of the row that emitted it), fsyncs everything,
-   and re-checks the owner word and an abort flag before every mutation (A26).
-3. The owner, once no merge is in flight, writes the manifest (its fsync joins
-   the next round's first sync phase) and queues `SWAP{seg, gen, oldCgen,
-   segEnd}`; the SWAP, the RETIRE set and the counters' adjustment ride one
-   batch. Publish attaches the new files.
-
-Rows keep their pseqs. `c-*.fsr` holds the surviving rows (dense by rank) and a
-presence directory (a bit per pseq, a rank per 512); a pseq the directory
-lacks reads as a `VOID` row (kind 8, never stored, never live). A segment with
-no survivor is `EMPTY` in the manifest and has no files.
-
-Candidates (maintenance, every 50 ms per warm partition, and at once after a
-SWAP): the sealed segment with the largest dead share at or over
-`compactDeadRatio` (15%; dead frame bytes counted as kills commit), joined by
-its adjacent segments past the ratio too (one output per wave, within the
-coalescing limits); adjacent sealed segments under 8 MiB, coalesced up to 16
-at a time and 64 MiB of output into one segment named by the first (`lastSeg`
-in the manifest; rows' `seg` is rewritten); after a restart, when the
-partition's dead share is over the ratio and the per-segment counts are
-unknown, the oldest
-segment not yet surveyed (a build that would save under 10% is abandoned and
-its count remembered). The owner keeps these candidates in an index updated
-from a change feed; a look does not walk the segments (§40).
-`Engine::swapSegment` requests one (targeted, or the
-oldest-generation compactable segment).
-
-Kill bound and readers. A type-level reader's visibility is `V_p =
-min(pseq_hi, labeled_through[p])`. A compacted segment records `killThrough`
-(the largest killer behind a removed row, the inputs' own, and the bound of
-the SWAP that removed a dropped tombstone's target) and `prevGen` (the manifest
-before its SWAP). A type-level snapshot whose `V_p` is below a segment's
-`killThrough` reads that segment through `prevGen`, repeatedly for a segment
-compacted more than once; the reader gate keeps those files for any statement
-older than the SWAP. Partition-level readers see `pseq_hi`, which is never
-below a SWAP's bound.
-
-Counters: `total_count`, `total_bytes` and `tomb_count` count the rows the
-files hold (a SWAP subtracts what it removed), so they equal a recount;
-`min_epoch`, `max_epoch` and `latest_arrival` stay bounds over everything ever
-appended.
-
-## 25. Reclamation (A12) and meta segments (A9)
-
-- **Retire.** A MERGE_DONE retires the folded runs and the manifest it
-  replaces; a SWAP retires the inputs' files, their runs and the manifest. The
-  whole outstanding set is a `RETIRE` ctl record in the same batch (the head
-  points at it: `retireSeg/retireOff/retireN`); consecutive manifests collapse
-  into one range item.
-- **Unlink.** Maintenance unlinks a retired file with `UNLINK_IF_UNUSED` once
-  the reader gate (the start of the oldest running reader statement) is past
-  its retirement time, checked twice a grace apart (60 s by
-  default). The retirement time is that of the first head write after the
-  batch commits (the head that stops naming the file): a statement that
-  starts earlier may read the previous head. In journal mode also once every
-  journal record older than the
-  retirement is checkpointed; a meta segment once a DURABLE_CKPT head names a
-  later `first_live_m_seg` (a quiet partition writes one; later items do not
-  wait for it, and a partition with retired files never goes cold). Each pass
-  takes the first check of every file past the gate, so a backlog goes about
-  one grace after its statement ends (`reclaim_backlog_goes_in_one_grace`:
-  133 files in 0.31 s at a 0.3 s grace). BUSY (a handle is open) skips to
-  later items and retries after 50 ms; idle
-  reader lanes close cached handles after 5 s. The next batch carries
-  `UNLINKED` and the shrunken set; `disk_bytes` drops then. The set rides one
-  ctl record of one batch, so it is held under a soft cap (2,048 items as the
-  record encodes them, less with a large lane table): past it the oldest go at
-  once, regardless of the gate and the grace (deviation 37). A statement older
-  than them gets the retryable SNAPSHOT_GONE; an open handle still makes the
-  unlink BUSY.
-- **Open** unlinks every file of the persisted set (a file a surviving reader
-  instance still holds stays retired), the outputs of an INTENT_COMPACT
-  without SWAP, and r/a files a first merge created without MERGE_DONE, then
-  writes a durable head.
-- **Meta segments (A9).** A sealed `m-<seg>` whose batches are all merged is
-  retired by a batch that also re-emits the full lane table (LANE_CKPT; at
-  level 3 past 32 lanes, a lane checkpoint must cover the segment first, §41)
-  and the RETIRE set, whose header carries the manifest generation, `merged_through`,
-  `first_live_m_seg` and `next_gen`; `first_live_m_seg` advances when that
-  batch commits. A rebuild of a head whose both slots are torn probes for the
-  first existing meta segment and replays from its first batch.
-- **Type logs.** A type's MERGE_DONE retires the catalog runs it folds and
-  the manifest it replaces. The new manifest persists the whole outstanding
-  set (these and any still waiting) in an appendix after its CRC trailer,
-  `[magic FSTR][n][n x RetireItem][crc][pad]`, which readers that predate it
-  never read. Unlinking follows the partition rules (reader gate twice a
-  grace apart, journal safe time, BUSY retried after 50 ms). Open unlinks the
-  appendix's files, the outputs of a merge a crash cut short (it sweeps the
-  generations after the manifest's to `next_gen + 64`, and 16 past the last
-  leftover it finds, since a head's `next_gen` can lag), and anything below
-  `first_live_m_seg`. A failed merge unlinks its outputs at once (durably;
-  one that cannot go yet is retired like the rest) and retries with the same
-  generation. At stop a merge in flight closes its handles; an unfinished
-  build's outputs go, a finished one's are left to open (a MERGE_DONE already
-  in the log may name them).
-- **Type meta segments.** The type meta log starts `m-<seg+1>` once it passes
-  `typeMetaSegBytes` (64 MiB): the sealed segment is cut at the end of its
-  last batch and synced, the new one created, and a durable head names it.
-  Open follows the batch chain from a segment's end into the next one, so a
-  stale head slot loses nothing. With more than 128 partitions the new
-  segment's first batch is a FULL_LABELS checkpoint, and readers read label
-  deltas across segments. The oldest sealed segment retires once no unmerged
-  L0 block, merge input or label checkpoint lives in it: `first_live_m_seg`
-  (a type head field) is written to both head slots and synced, then the file
-  waits for readers like any retired file.
-- **Dead copies leave the catalog (A15, catalog half).** A type merge drops the
-  CID, LABEL and REPEAT entries of every copy killed within its inputs whose
-  first posting (FIRST or REPEAT) is also among them: a copy never leaves
-  DEAD, and no older run holds any of its postings. A full fold drops every
-  dead copy. GONE and REHOME entries stay: they are keyed by gseq for
-  arrivals order, and leave with their arrival entries (T3b, §33).
-- **Reader gate in production.** The writer is its own wasm instance: the host
-  reads every reader instance's lane announcements
-  (`FlatsqlPsReaderLayout.laneAnnounce`) and passes the minimum through
-  `flatsql_ps_reader_gate` (T6 wires it). Natively, `Engine::setReaderGate`.
-
-## 26. Disk bytes (§13)
-
-`disk_bytes` is the exact size of the files a partition names: a ledger of the
-stable files (sealed segments' d and m, r/a, c-*, runs, manifests, the next
-segment's pre-created files, retired files until UNLINKED) plus the extents of
-the files still growing (h, l, the active d and m, zero-fill included). Open
-rebuilds it from the head, the manifest and file sizes; the owner maintains it
-on every append, merge, seal, SWAP and unlink. After every reopen in the crash
-tests, a walk of each partition directory finds exactly the named files and a
-total equal to `disk_bytes`. Head files are written as whole slots until they
-hold both, so a head write never grows the file again.
-
-A type's disk bytes are kept the same way: its head, meta segments from
-`first_live_m_seg`, arrivals segments and fence, catalog runs, manifest, a
-built merge's outputs until MERGE_DONE, and retired files until they are
-unlinked, maintained on every write, seal, rotation, merge and unlink and
-rebuilt at open from file sizes. Type configs (`s-*.fsc`) are registration
-and not counted. The crash tests check the type directory the same way.
-
-## 27. Quota and the full disk (§13, A13, §22.4-3)
-
-- **Planner** (writer 0's maintenance, every 100 ms): usage = Σ partition
-  `disk_bytes` + Σ type log bytes, less retired files waiting only for
-  readers. Over the cap
-  (`EngineConfig::quotaBytes`, `Engine::setQuota`, `flatsql_ps_set_quota`), it
-  evicts whole sealed segments in arrival order across partitions (their
-  `minArrival` zone) down to 0.85 of the cap: a `TOMB_RANGE{seg, all}` on the
-  owner that names the segment's rows by pseq (deviation 34; bounded 512-row
-  steps; supersede-lane heads and control kinds are spared; each step also
-  stops after 4 ms of CPU), then, once the tombstones are durable, a
-  compaction of the segment, or of the output it has been coalesced into
-  since. One wave at a time.
-- **ENOSPC.** A commit that fails NOSPACE starts an emergency: record entries
-  stop being consumed (producers see zero credits; nothing is acked), the
-  ballast file (`fsql2/ballast`, `ballastBytes`) is released, and waves evict one
-  segment at a time down to 0.85 of the usage at the failure, and at least the
-  ballast's size, but never more than half the store in one episode. Once
-  usage is under that cap the ballast is recreated and ingest resumes. NOSPACE
-  in a merge, a compaction, a head write or a segment creation is transient;
-  a merge that failed retries after 100 ms (a type merge with the same
-  generation when it left nothing behind). A partition whose L0 directory is
-  full stages no rows at all (entries, mailbox kills, TOMB_RANGE steps) until
-  a merge frees a slot.
-
-## 28. Acceptance (§18 T3 as amended)
-
-Machines: **Mac** = the owner's Mac Studio (Darwin 25.3.0, arm64, 28 hardware
-threads), shared with other lanes (1-minute load recorded per run). **Mac mem**
-runs use the in-memory fault host (no fsync). Numbers come from `MEASURED`
-lines of `flatsql_ps_test` (RelWithDebInfo) on the task-branch build landed on
-2026-09-28, run one after another at load 28–38.
-
-| # | Acceptance | Result | Where |
-|---|---|---|---|
-| 1 | A partition with 50% dead bytes compacts to ≤ 55% of its prior disk bytes; owner commit p99 and interactive lane p99 ≤ 1.5× baseline during compaction; 1,000 pre-SWAP statements complete correctly | **Size and statements pass; the latency ratio is not met on the Mac (needs a quiet Linux-8 box; T3b's Linux runs: §34).** Mac mem, load 31–35: 4 partitions × 20,000 OMM records, half killed: 106.4 MB → 51.9 MB (0.488×); 1,003 bulk statements that started before a SWAP returned exactly the live rows with their bytes, 0 errors (2,177 SWAPs). Latency over the whole SWAP period (the compaction plus the re-compactions that produced those statements; 16,093 samples): ack p99 0.133 → 18.5 ms, interactive lane p99 0.339 → 3.75 ms, commit round p99 1.05 ms. | `compaction_half_dead_T3_1_full` |
-| 2 | CAT supersede, 20% changed per cycle, 100 cycles: disk plateaus ≤ 1.3× live bytes; A9: `m` bytes ≤ one active plus one sealed segment | **Pass with the 15% trigger (deviation 24), "live bytes" read as the live set's compacted footprint.** Mac mem, load 31–33: 20,000 CAT objects, 100 cycles (each updates a random 20%), the store measured at rest after each cycle: disk peaked at 1.120× the footprint of the same live set fully compacted (19.5 MB); 346 compactions, 520 meta segments retired, 5,291 files unlinked; at most 1 meta segment on disk (A9). With §11's 25% trigger it peaks at 1.31–1.38× (six runs). Against the records' own bytes (Σ len − 4 of live PUTs, 4.9 MB) the disk is 4.5×: a fully compacted CAT record costs about 4× its frame in rows, attributes and postings, which no compaction removes | `compaction_cat_supersede_plateau_T3_2_full` |
-| 3 | Quota at 80% of current bytes: oldest records evicted first; no supersede-lane head evicted; disk ≤ cap within 3 passes; each eviction step ≤ 10 ms | **Pass (arrival order, §22.4-3).** Mac mem, load 33–35: the store with its type logs 14.1 MB, cap 11.3 MB: under the cap after 1 pass (14 segments), 0 of 256 CAT heads evicted, in each partition the evicted records are exactly its oldest (0 holes); step max 3.4 ms over 15 steps. Across partitions eviction is by whole segment, so a survivor can be older than an evicted record of another partition (288 of 6,367 records here). The 10 ms bound is enforced on a quiet box (the wasm suite at load 41 measured past it). | `quota_arrival_order_heads_spared_T3_3` |
-| 4 | 1,000 crash points during compaction: exactly one of the old or new set is live, 0 orphans, 0 acked records lost; A12: crash points inside the grace window, Σ on-disk sizes = Σ `disk_bytes` after each reopen | **Pass.** Mac mem, load 28–38: 3,224 trials, 1,000 with a compaction planned but not applied at the crash, 1,744 with retired files waiting; all five crash modes (664 drop-all, 637 drop-subset, 658 torn, 623 reordered, 642 kill -9); 41,825 compactions, 291,864 files unlinked, 24,719 meta segments retired (partitions and the type's), 723,969 dead catalog entries folded out; after every reopen each partition directory and the type directory held exactly the named files with sizes equal to the engine's disk bytes, every acked live record live with its bytes, every acked kill dead, counters equal to a recount; once labels caught up, `first_live_count` equal to the live records and 16 catalog lookups right. 507 s. The T1 crash harness (merges, A9, reclamation; compaction off: its oracle keeps dead bytes) checks the partition directories after every reopen too; the wasm build runs it ×1000. | `orphan_crash_points_during_compaction_T3_4_full`, `crash_faults_T1_1` |
-| 5 | Hot split at 4× single-writer capacity with 4 helpers | **Built in T3b** (§32); ratio and correctness in §34–§35. | `hot_split_*`, `flatsql_ps_bench --mode=hotsplit` |
-| 6 | Fill the disk to ENOSPC under ingest: ingest resumes with 0 acked losses and no operator action | **Pass.** Mac mem, load 34–35, a 16 MiB device, 1 MiB ballast, two OMM producers for 4 s: 17 episodes, the ballast released 17 times and restored 16, 41,112 records acked after a recovery, 6,318 alive at the end; in each partition the surviving acked records are exactly its newest (0 holes); after a reopen (before the engine starts) the partition and type directories hold exactly the named files at the engine's disk bytes. Before type-log reclamation the type logs filled 16 of the device's 17 MB and the run ended in the emergency with no survivor. | `quota_disk_full_resumes_without_operator_T3_6` |
-
-§22 amendments naming T3:
-
-| Amendment | Status |
-|---|---|
-| A9 meta-segment retirement | Built (§25). |
-| A11 intents | INTENT_COMPACT built; merge and compaction intents coexist in one batch. |
-| A12 reclamation lifecycle | Built (§25): RETIRE/UNLINKED, reader gate twice a grace apart, open replays the set. |
-| A13 ENOSPC, ballast, arrival order | Built with deviations 12–13. |
-| A15 arrivals compaction | Type-log half built here (§25–§27); the arrivals half in T3b (§33). |
-| A26 stage-1 prep states | Built in T3b (§32, deviations 27–28, 31). |
-
-## 29. Design deviations (T3)
-
-1. **Compaction builds on its own threads** (§11: the owner in 4 MiB / 10 ms
-   slices; helpers only for split partitions). As T1 deviation 1 did for
-   merges: a build on the writer stalls every partition it owns. The builder
-   re-checks the owner word and an abort flag before every mutation, and a
-   HANDOFF waits for it to stop (one slice).
-2. **The owner writes the manifest at SWAP time**, synced in the next round's
-   first phase, instead of the builder: merges of the active segment continue
-   while a build runs; only the SWAP waits for no merge in flight.
-3. **Kill bound and `prevGen` fallback** (not in the design): a row is removed
-   only when its killer is labeled, and a type-level snapshot below a
-   segment's bound reads the previous file set. Without it, a type-level
-   statement whose type snapshot predates a death could miss a live copy
-   (A14).
-4. **Counters are physical** (§24): recounts equal them after compaction.
-5. **Coalescing** adjacent small segments (§11 "adjacent sealed segments under
-   8 MiB each") into one output named by the first segment.
-6. **Minor 1 extended**: a tombstone whose target is VOID in the same inputs
-   (an earlier SWAP of that segment removed it) goes too. Without it the
-   supersede tombstones of a partition compacted in one piece never went
-   (measured: the CAT plateau grew by 77 KB a cycle).
-7. **Tombstone-only segments seal by age** (T1 sealed only segments with
-   frames), so a partition that stops ingesting can drop its tombstones.
-8. **Reader gate by statement start time**, not by announced manifest
-   generations (A12 text): T2 built announcements as start times
-   (`oldestActiveStart`); the host passes the minimum
-   (`flatsql_ps_reader_gate`).
-9. **RETIRE is the whole set** per changing batch, not incremental records, so
-   open reads one record (head pointer) plus the tail.
-10. **UNLINK_IF_UNUSED BUSY skips** to later items (A12: "retry later");
-    reader lanes close idle handles after 5 s.
-11. **Disk bytes include zero-fill and pre-created files** (the file sizes);
-    open stats the files it names.
-12. **ENOSPC evicts with tombstones, one segment per wave** (A13: "first unlink
-    whole eligible sealed segments, oldest first ... needs no new space").
-    Dropping a segment without per-record tombstones would leave the type
-    owner unaware of the deaths (A14: FIRST copies must be labeled DEAD and
-    REPEATs promoted), and those catalog updates need space too. The ballast
-    must hold one segment's tombstones: about 128 B of row plus postings per
-    record, twice until the tombstones' own segment is compacted.
-13. **Ballast is off in the engine default**; hosts set it (servers 256 MiB,
-    browsers one seal plus one commit), so tests and benchmarks are unaffected.
-14. **Quota counts partitions and type logs**, not the registry (a few KB)
-    or type configs (registration).
-15. **A rebalance of a partition already handed off is ignored** (a T1 race
-    the compaction timing exposed: a second release before the target adopted
-    could leave two owners).
-16. **RecordAttr bytes**: `buildRecordAttr` created its strings inside one
-    argument list, whose evaluation order C++ leaves unspecified; GCC on x86_64
-    built different bytes from clang. Each string is now created in field order;
-    `format_record_attr_golden_bytes` checks `vectors/record_attr.hex`
-    (22.3a-6).
-17. **T3 #2 "live bytes" is the live set's compacted footprint**: the same
-    records fully compacted, rows, attributes and postings included. Every
-    record carries about four times its frame in index structure, so a ratio
-    to frame bytes alone would measure the index, not garbage; both ratios are
-    reported (§28).
-18. **Type logs persist their retired set in the manifest** (not in ctl
-    records): a type has no ctl-record log, and the manifest is the one file a
-    MERGE_DONE names. The appendix sits after the CRC trailer, so readers and
-    opens that predate it parse the manifest unchanged.
-19. **A type meta segment retires with two synced head writes** instead of a
-    LANE_CKPT batch and a later DURABLE_CKPT head (A9): a type head has no
-    lane table, and after the second write neither slot names the segment,
-    whichever one a crash leaves torn.
-20. **A compaction plan pins its files**: anything retired after the plan was
-    made stays until the SWAP or the abort (a build reads the runs and meta
-    segments current at planning).
-21. **A failed build never quarantines**: the inputs are untouched, the
-    partition carries on, and requests end with an error (NOSPACE starts the
-    emergency). A quarantined partition ends its compaction requests at once.
-22. **TOMB_RANGE steps are also bounded in time** (4 ms of CPU, besides 512
-    rows): a kill looks up the row's tag instances in every run, so rows cost
-    more as a partition grows, and more under wasm (T3 #3: ≤ 10 ms a step).
-23. **Dead catalog copies are dropped by merges** (A15 says "type-log
-    compaction"): the type merge already reads every entry it could drop, so
-    no separate pass rewrites the runs; a copy goes once its first posting and
-    its DEAD posting meet in one merge (at the latest, the next full fold).
-24. **The dead-share trigger is 15%, not 25%** (§11). At rest a segment can
-    hold up to the trigger's share of dead rows, and a dead row costs as much
-    as a live one in rows, attributes and postings, so a store at rest sits
-    at up to 1/(1 − trigger) of its compacted footprint: 1.33× at 25%, above
-    T3 #2's 1.3. Measured on the T3 #2 run (20,000 CAT objects, 20% updated
-    per cycle, 100 cycles; Mac mem, load 6–26): 25%: 1.31–1.38 over six
-    runs; 20%: 1.35, 1.38; 15%: 1.115, 1.120; 10%: 1.19, with about the
-    same number of compactions (334–361). The price is write
-    amplification: a compaction at 15% rewrites 5.7 bytes per byte it
-    reclaims (3 at 25%). `EngineConfig::compactDeadRatio` sets it.
-25. **A compaction wave is one output**: segments next to the chosen one that
-    are past the trigger too join it, and the next candidate is looked for
-    right after a SWAP (not 50 ms later).
-
-## 30. Not built yet; running the T3 tests
-
-The T3 scope left open at 697a177 (#5 hot split, A15's arrivals half, A26,
-and the #1 latency ratio on a quiet Linux-8 box) went to T3b: §32–§35.
-
-```
-cpp/build/flatsql_ps_test --test=compaction_          # basic, T3 #1 and #2 (short forms)
-cpp/build/flatsql_ps_test --test=compaction_half_dead_T3_1_full [--dir=<dir>]
-cpp/build/flatsql_ps_test --test=compaction_cat_supersede_plateau_T3_2_full
-cpp/build/flatsql_ps_test --test=orphan_crash_points_during_compaction_T3_4_full   # 1,000 crash points
-cpp/build/flatsql_ps_test --test=quota_                # T3 #3, #6
-cpp/build/flatsql_ps_test --test=type_logs_reclaimed_under_readers
-```
-
-**T3 #1 on a quiet Linux-8 box** (8 cores, ext4, nothing else running), from a
-checkout at the landed commit; the test enforces the 1.5× bounds on such a box
-(what it enforces since T3b: §34):
-
-```
-cpp/build/flatsql_ps_test --test=compaction_half_dead_T3_1_full --dir=<ext4 dir>
-```
-
-# Part IV: T3b
-
-## 31. store-migrate gseqs, the entry-size setting, tag conditions
-
-store-migrate (T6, design §16.1-5) gives every migrated FIRST copy gseq = its
-legacy `sdn_record_index.rowid`, so per-schema MaxRowID and the FTS rowids
-carry over.
-
-- **Input.** `RecordAttr.migrated_gseq` (`ulong`, field 6, appended to
-  `schemas/flatsql_attr.fbs`; absent = 0, so older attributes are
-  unchanged byte for byte). `buildRecordAttr(..., migratedGseq)` writes it.
-- **Row.** A new PUT whose attribute carries one gets row flag
-  `MIGRATED_GSEQ` (0x80). The gseq stays in the attribute (in the same meta
-  batch, `ATTR_IN_M`): the RecRow has no spare u64 (offsets 108–127 hold
-  `supersedeHash`, `tagHash` and `aux`), and the attribute is as durable as
-  the row. Deviation from the T6 proposal "(b) the RecRow reserved u64 at
-  offset 116", which T1's layout had already given to `tagHash`.
-- **Labeling.** The type owner reads the flagged rows' attributes in windows
-  over the chunk it labels (one read per chunk of up to 4,096 rows when the
-  attributes fit in 1 MiB). A flagged copy labeled FIRST keeps its gseq when it
-  is above the type's committed `gseq_hi` and no arrival of the same type
-  commit holds it; the engine's gseq counter is then raised to at least gseq
-  + 1. Otherwise it gets an allocated gseq and counts a fallback; a flagged
-  copy labeled REPEAT counts a fallback too. A type commit's new arrivals are
-  sorted by gseq before they are appended, so arrivals stay strictly
-  increasing whatever order partitions are labeled in.
-- **Counters.** `EngineStats::migratedGseqs` and `migratedGseqFallbacks`,
-  appended to `flatsql_ps_stats` (entries 24 and 25). store-migrate's
-  verification (§16.1-7) needs fallbacks = 0; they are counted per labeling
-  decision, so a type commit that fails and is relabeled counts again.
-- **Crash.** The gseq is read from durable rows and attributes, so a crash
-  that loses the type commit relabels the same copies with the same gseqs.
-  An allocated fallback gseq that was never published can be reassigned
-  (as for every allocated gseq).
-- **What T6 must do** (its (d)): feed each type's FIRST copies in rowid
-  order and wait for `labeled_through` before crossing partitions, and run
-  with fallbacks = 0. gseqs are unique per type; across types a fallback could
-  reuse a legacy rowid another type migrates later, which is one more reason
-  a fallback fails the migration.
-- **Entry size.** Writer TLV 19 = `maxEntryBytes` (u64; default 1 MiB +
-  4 KiB, clamped to [64 KiB, 1 GiB]): the largest ring entry (header,
-  RecordAttr and frame). Each writer's arena grows to at least 4 ×
-  (maxEntryBytes + 4 KiB), so the frames half holds two entries. Frames
-  larger than a segment (A27 jumbo segments) are still not built.
-
-Tests: `type_migrated_gseq_preserved_fallback_and_stats` (kept, fallback
-below `gseq_hi`, REPEAT copy, ordinary allocation continues above, flags on
-disk, reopen), `type_migrated_gseq_one_commit_sorted_and_crash_reopen` (two
-partitions' interleaved gseqs in one type commit come out sorted; a crash
-before and after the type commit gives the same arrivals),
-`writer_max_entry_bytes_configurable` (a 9 MiB frame refused by default,
-stored and read back at 10 MiB), `writer_capi_tlv19_max_entry_and_stats`
-(tag 19 through `flatsql_ps_init`, the 26-entry stats array).
-
-### 31.1 Tag conditions match any live tag instance (A2)
-
-`_provider`, `_batch`, `_peer_id`, `_source` and `_source_name` conditions
-have the legacy tag table's ANY-row semantics (`indexedRecordWindowSQL`: a
-CID matches when one of its tag rows satisfies every requested condition).
-In format 2 a record's tag instances are its PUT's own tag and its RETAG rows
-(A2). As T2 built it, the vtab scanned tag postings (which name every
-instance, RETAGs included) but left each constraint for SQLite to re-check
-against the projected column, which shows only the PUT's own tag, so every
-record matched through a RETAG was dropped (T6 #7 on a migrated copy: a
-provider window of 200 read as 100; a source + batch window lost the
-re-tagged records).
-
-Now `xBestIndex` consumes every tag condition (`omit = 1`) and the vtab
-evaluates them all on one instance:
-
-- A tag or source posting scan (the plan's key) checks the remaining
-  conditions on the instance the posting names (its RecordAttr), then emits
-  the instance's record. A single condition that is the scanned key needs no
-  attribute read unless the key was capped (over 512 bytes).
-- Any other plan (CID, column index, epoch, arrivals order, full scan)
-  keeps a record when one of its live tag instances matches every condition
-  (`RowFilter::hasLiveTag`, the TAG_OF postings), as the alias table's source
-  filter already did.
-- An untagged record matches no tag condition (as the index-driven plans
-  already behaved, T2 deviation 8), and conditions that contradict each other
-  (two sources) return no rows.
-- `_source = '<TYPE>@<name>'` is compared as the column projects it: the type
-  prefix is case-sensitive (a lower-case prefix returned no rows before
-  either, after SQLite's re-check).
-- `_peer_id` conditions match the tag's producer peer (the TAG_PEER postings
-  the T2 plan scanned); the `_peer_id` column still projects the storing
-  call's `RecordAttr.peer_id`. Before, SQLite compared that BLOB column with
-  the argument, so a text argument never matched.
-- `<TYPE>_current` groups first and filters after, as SQL says: its tag
-  conditions stay SQLite's (the current version's own tag).
-- Projected columns are unchanged: they show the PUT's own tag.
-
-Test: `lane_tag_conditions_match_any_instance_A2` (two partitions, PUT tags,
-RETAGs and REPEAT copies; eleven condition sets at type and partition level
-against an ANY-instance oracle, the full `_source` form, the alias, an
-epoch-ordered window, column and CID plans). With `omit = 0` restored it
-fails 18 checks.
-
-## 32. Hot-partition split: stage-1 helpers and prep states (§12, A26)
-
-A partition keeps one appender, its owner, split or not. Splitting is a
-runtime state of the owner: nothing on disk changes, so open, readers and the
-crash rules are those of an unsplit partition.
-
-**Code.** `ps/stage1.h` (slot protocol), `src/ps/stage1.cpp` (publish, take,
-stage-1 computation, helpers), `src/ps/hot_split.cpp` (trigger, split, merge
-back). `partition_log.cpp` stages from a prepared result when there is one.
-
-**Trigger (§12).** A partition is split when its backlog stays above
-`hotSplitBacklogPct` (50) of its ring cap for `hotSplitAfterMs` (30 s) while no
-other partition of its owner has a backlog, on an engine with 2 writers or
-more. It merges back when the backlog stays under `hotUnsplitPct` (10) for
-`hotUnsplitAfterMs` (30 s). `Engine::setHotSplit(pid, on)` forces either
-(tests, hosts); a forced split stays until it is forced off. A quarantined
-partition merges back. Up to 16 split partitions are offered to helpers; a
-17th is split but its owner prepares everything itself.
-
-**Window.** The first split allocates the partition's prep window (2,048
-slots, 1.7 MB, heap, never freed while the engine runs). The owner publishes
-the upcoming ring entries (position, length, kind) in ordinal order, up to
-2,048 ahead of the entry it will stage next, and tops the window up when fewer
-than half are ahead. A split partition's ring pages are mapped for the whole
-ring (the producer runs a full ring ahead of the owner, so helpers always have
-entries), and it commits up to `hotCommitFrames` (4,096) frames per round
-instead of `commitFrames` (1,024).
-
-**Slot states (A26).** Each slot's state word is `{ordinal << 3 | state}` and
-moves by CAS:
-
-| From | To | By |
-|---|---|---|
-| (taken) | FREE(k) | the owner publishes ordinal k |
-| FREE(k) | CLAIMED(k) | a helper, after taking k from the claim counter |
-| CLAIMED(k) | WRITING(k) | the helper, its result computed |
-| WRITING(k) | READY(k) | the helper, its result copied into the slot |
-| FREE(k) or CLAIMED(k) | OWNER(k) | the owner, staging k itself |
-
-The owner takes ordinals in ring order. READY: it stages from the result.
-FREE: it takes the entry. CLAIMED: it waits up to `prepClaimWaitUs` (20 µs)
-for the helper, then takes the entry (counted as stolen). WRITING: it waits
-for one result copy. Ordinals never repeat, so a helper whose entry was taken
-fails its CLAIMED → WRITING CAS and discards what it computed (counted as
-wasted), even if the ring pages it read were recycled meanwhile.
-
-**Helpers.** An idle writer (no work of its own) prepares up to
-`prepHelpBudget` (256) entries per iteration; a publish wakes up to
-`hotHelpers` (4) writers. A helper writes nothing but its claimed slot: no
-file, no ring slab, no partition state. Per record entry it runs what
-`stageRecord` does before it touches partition state: the frame check, the CID
-check or computation (sha256), the attribute check, the tag and lane hashes,
-the CRC32C of the stored bytes, and the key extraction (kept when its strings
-fit in 480 bytes). It also looks the CID up among the owner's committed
-postings (the dedupe hint): the owner publishes its L1 run set (by version)
-and the CID entries and blooms of its unmerged L0 blocks (immutable copies),
-and a helper searches those with its own file handles. The owner then
-searches only the L0 blocks committed after the hint and the entries it has
-staged. Dedupe, supersede, pseq assignment, rows, postings and the commit stay
-with the owner.
-
-**Rebalance and stop.** A HANDOFF of a split partition moves it split: the
-window's positions belong to the partition, and the new owner continues from
-them. A helper counts
-itself into the window before it reads the split flag; the owner leaves the
-window only when it is unsplit and no helper is inside. `Engine::stop` drops
-the helpers' views before it closes files.
-
-**Counters.** `EngineStats` splits, unsplits, prepPrepared, prepUsed,
-prepStolen, prepWasted, prepHinted, l0FullStalls; `flatsql_ps_stats` entries
-26–33.
-
-**A fix to T1's L0 accelerator** found by the crash harness with splits: when
-the partition's accelerator memory could not hold a block's bloom, the loader
-stopped at that kind and the kinds after it (TAG_OF among them) read as having
-no postings in the block, so a kill missed the record's tag instances and its
-lane counters went wrong. The loader now lists every kind and leaves out only
-the blooms it cannot hold. Split partitions map their whole ring and made the
-memory run out in the harness; any partition could.
-
-Deviations from §12 and A26:
-
-26. **No SPLIT frame and no time boundary.** Sealed segments' merges and
-    compactions already build off the owner (T1 deviation 1, T3 deviation 1),
-    so §12's re-homing needs nothing new; what a split adds is stage 1. A
-    split therefore writes nothing and survives nothing: after a restart the
-    trigger decides again.
-27. **Entries are claimed one at a time from a published window**, not in
-    ranges: a helper that stalls holds one entry, which the owner takes after
-    20 µs.
-28. **Prep states carry an ordinal, not an epoch** (A26: FREE →
-    CLAIMED(epoch) → PREPARED): helpers write no file and no slab, so the
-    owner's epoch guards nothing they do; the ordinal is what makes a stale
-    claim fail. WRITING and OWNER are added so the owner can take an entry
-    without waiting on a stalled helper.
-29. **Merge back** (not in §12) at under 10% for 30 s, and a forced split
-    (`setHotSplit`).
-30. **Dedupe hints** (not in §12): after stage 1 the owner's largest per-entry
-    cost was the CID lookup in its runs.
-31. **A26's "helpers SIGSTOPped for 100 ms"** is a 100 ms sleep inside every
-    Nth claim (`testPrepStallNs`, `testPrepStallEvery`): a single thread
-    cannot be SIGSTOPped.
-
-Tests:
-
-- `hot_split_equals_unsplit_reference_T3_5`: the same CAT workload (puts,
-  supersedes, re-tags, duplicates, kills) through a split and an unsplit
-  engine with an injected clock: rows, frames, attributes and SQL results
-  equal; one appending thread per ownership interval; pseqs gap-free.
-- `hot_split_rebalance_stalled_helpers_A26` (6 s; `_full` 600 s): a split
-  partition flooded while 5 others trickle in a 48 MiB slab pool (slabs
-  recycle across partitions), rebalances every 50 ms, a 100 ms helper stall
-  every 97 claims: 0 non-owner writes, one (writer, thread) per
-  ownership epoch, contiguous pseqs, and after a reopen every stored frame
-  hashes to its row's CID and CRC with every sent CID present.
-- `hot_split_trigger_splits_and_merges_back`: the §12 trigger and the merge
-  back with an injected clock.
-- `hot_split_throughput_T3_5` (`_full`): the §18 ratio, enforced on a quiet
-  box only.
-- The T1 crash harness splits up to 16 partitions in half its stores, at
-  setup and after every reopen.
-
-## 33. Arrivals compaction (A15, arrivals half)
-
-T3 built the type-log half of A15 (§25). The arrivals half removes the
-arrival entries of dead gseqs, with their GONE postings.
-
-**Rule.** A type merge that folds GONE postings looks at every sealed arrivals
-segment (its fence entry, fixed when the merge is planned). A segment whose
-entries those GONE postings cover by at least `arrivalsCompactRatio` (0.25) is
-rewritten without them into `ga-<gen>.fsg`, `<gen>` being the merge's output
-generation, and the merge's run leaves out those GONE postings and the REHOME
-postings of the same gseqs. Entries and their GONE postings leave in the same
-MERGE_DONE, so live = entries − GONE holds in every snapshot and offset paging
-(T2) is unchanged. GONE postings of other runs, and of the active segment,
-stay with their entries. `arrivalsCompactRatio = 0` turns the rewrite off.
-
-**Manifest.** The type manifest carries an arrivals table (magic FSAC) after
-its retire set (T3 deviation 18): per rewritten segment {seg, gen, offset,
-count, first gseq, last gseq}, 40 bytes. Readers and open take a segment's
-entries from its `ga` file at that offset and its count from the table; the
-fence file is unchanged. Manifests without the table read as before.
-
-**Files.** A rewritten segment's `g-<seg>` and a superseded `ga` file are
-retired through the type's retire set (A12, letters `g` and `G`). When a
-merge rewrites segments, a `ga` file that holds entries for less than half of
-its bytes is written again, so old `ga` files do not pin bytes. Open sweeps
-`ga` files that no manifest names, and counts in the disk bytes the `ga`
-files the manifest names instead of the originals they replace; a merge in
-flight counts its outputs.
-
-**Quota.** The quota planner triggers the rewrite through its evictions: an
-evicted record's GONE posting reaches the next type merge. The planner does
-not request type merges itself (deviation 32).
-
-**Counters.** `EngineStats` arrivalSegsCompacted and arrivalEntriesDropped;
-`flatsql_ps_stats` entries 34–35.
-
-Deviation:
-
-32. **The quota planner does not start type merges** (A15: "can be triggered
-    by the quota planner"). Its evictions produce the GONE postings, and the
-    type owner merges on its own cadence (L0 fill); an eviction wave that
-    frees little arrivals space frees it at the next merge.
-
-Tests:
-
-- `type_arrivals_compaction_A15`: 3 partitions, 150 records each per round,
-  70% of the live records killed per round, 3 s, with offset paging over
-  arrivals (`ORDER BY _gseq LIMIT 40 OFFSET n`) and `count(*)` checked against
-  the live records' gseqs every 10 rounds, then a reopen; the same run with
-  the rewrite off for comparison. Mac mem, load 10: off, 191,228 entries
-  appended and 191,228 kept, 4,589,472 bytes of arrivals (24 per appended
-  entry); on, 151,188 appended and 425 kept (211 records live), 10,200 bytes
-  (0.067 per appended entry), 7,838 segments rewritten, 150,763 entries
-  dropped, 204 paging checks, 0 wrong; the type directory holds exactly the
-  named files at the engine's type disk bytes, before and after the reopen.
-- `orphan_crash_points_during_compaction_T3_4` (`_full`): half the stores
-  seal arrivals segments every 48 entries; after each reopen, arrivals strictly
-  increasing, no dead gseq's entry visible past its segment's fence, offset
-  pages equal to the live gseqs. Mac mem, load 7–12, `_full`: 2,787 trials,
-  1,000 crash points during compaction, 1,649 in the grace window, 7,592
-  arrivals segments rewritten, 76,499 entries dropped, all five crash modes
-  (567 drop-all, 583 drop-subset, 538 torn, 545 reordered, 554 kill -9),
-  394 s.
-- The T1 crash harness keeps every published gseq's entry (its oracle), so it
-  runs with the rewrite off.
-
-## 34. T3 #1 and #5 on Linux-8 (T3b item 3)
-
-**Machine.** The Linux-8 of T2: Docker Engine 29.2.0 (Docker Desktop's
-linux/arm64 VM, kernel 6.12.67-linuxkit, 16 vCPUs) on the owner's Mac Studio
-(Apple M3 Ultra, 28 cores, 256 GB), an `ubuntu:22.04` container limited to 8
-CPUs with `--cpus 8` (CFS quota 800000/100000) or pinned with
-`--cpuset-cpus 0-7`, `--memory 24g`, g++ 11.4 RelWithDebInfo, ext4 on the VM's
-virtual disk (a file on the Mac's APFS). It is not quiet: the Mac ran other
-lanes throughout (1-minute load 6–16 on 28 cores), and the VM's load average,
-recorded before each run, includes the benchmarks' own threads. Source: a `git
-archive` of the landed tree's `cpp/`.
-
-```
-docker run --rm --platform linux/arm64 --cpus 8 --memory 24g \
-  -v <checkout>:/src:ro -v <flatbuffers c72a8bed>:/fb:ro ubuntu:22.04 bash -c '
-  apt-get update && apt-get install -y cmake g++ make
-  cmake -S /src/cpp -B /tmp/b -DCMAKE_BUILD_TYPE=RelWithDebInfo -DFLATBUFFERS_DIR=/fb
-  cmake --build /tmp/b -j 8 --target flatsql_ps_test flatsql_ps_bench
-  /tmp/b/flatsql_ps_bench --mode=hotsplit --records=2000000                        # x3
-  /tmp/b/flatsql_ps_bench --mode=hotsplit --io=fs --dir=/tmp/hs --records=1000000  # x2
-  /tmp/b/flatsql_ps_test --test=compaction_half_dead_T3_1_full --dir=/tmp/c1       # ext4
-  /tmp/b/flatsql_ps_test --test=compaction_half_dead_T3_1_full'                    # in memory
-```
-
-### T3 #5: hot split throughput
-
-One partition, one closed-loop producer (the ring stays full: the offered load
-is whatever the partition takes), 5 writers, the same engine unsplit and then
-split with 4 helpers. `mem` is the in-memory host; `ext4` commits with
-fdatasync.
-
-| Run | Unsplit rec/s | Split rec/s | Ratio |
-|---|---|---|---|
-| mem, `--cpus 8`, VM load 2.0 | 185,205 | 450,587 | 2.43 |
-| mem, `--cpus 8`, 3.8 | 179,775 | 467,213 | 2.60 |
-| mem, `--cpus 8`, 5.7 | 182,512 | 472,698 | 2.59 |
-| mem, `--cpuset-cpus 0-7`, 5.1 | 176,825 | 479,294 | 2.71 |
-| mem, `--cpuset-cpus 0-7`, 5.4 | 185,216 | 479,830 | 2.59 |
-| mem, `--cpuset-cpus 0-7`, 5.6 | 176,934 | 476,050 | 2.69 |
-| ext4, `--cpus 8`, 6.5 | 142,799 | 320,235 | 2.24 |
-| ext4, `--cpus 8`, 6.9 | 157,696 | 326,783 | 2.07 |
-| ext4, `--cpuset-cpus 0-7`, 5.5 | 156,950 | 324,930 | 2.07 |
-| ext4, `--cpuset-cpus 0-7`, 5.1 | 150,486 | 333,085 | 2.21 |
-
-In memory: 2.43–2.71×, median 2.60, at least 2.5 in 5 of 6 runs. The build
-before the accelerator fix (49d4a1d, the same split path) measured 2.61, 2.63,
-2.56 (`--cpus 8`) and 2.51, 2.59, 2.56 (`--cpuset-cpus`) in memory, 1.64–2.30
-on ext4.
-
-The split partition's stage-1 results: about 1.86 M of 2 M entries prepared
-with a dedupe hint the owner used, 57–151 taken back from a helper after
-20 µs. With fdatasync every commit, the owner's syncs do not shrink with
-helpers, so the ext4 ratio is lower (the owner's CPU is no longer the whole
-cost).
-
-### T3 #1: latency during compaction
-
-`compaction_half_dead_T3_1_full`: 4 partitions × 20,000 OMM records, every
-other one killed; a paced producer on a fifth partition (ack latency), an
-interactive lane asking 100-row windows, 3 bulk lanes reading whole
-partitions; a 3 s baseline, then the compaction **pass** (every sealed
-segment of the four compacted once), then the **storm**: forced
-re-compactions until 1,000 bulk statements started before a SWAP. Ratios are
-p99 during / p99 at baseline; commit round and maintenance step p99 come from
-the engine's histograms (quarter-octave buckets), ack and lane p99 from every
-sample.
-
-| Run | Pass s | Commit round | Lane | Ack | Storm: commit / lane / ack |
-|---|---|---|---|---|---|
-| ext4 a, `--cpus 8`, VM load 2.0 | 0.64 | 1.57 / 2.62 ms = 0.60 | 0.49 / 0.81 ms = 0.61 | 26.5 / 8.8 ms = 3.01 | 2.8 / 0.76 / 3.9 |
-| ext4 b, `--cpus 8`, 5.7 | 2.97 | 41.9 / 21.0 = 2.00 | 0.45 / 0.83 = 0.55 | 102.9 / 77.9 = 1.32 | 2.8 / 0.51 / 1.8 |
-| ext4 c¹, `--cpus 8`, 2.8 | 0.71 | 1.00 | 1.34 / 0.91 = 1.47 | 27.6 / 14.6 = 1.89 | – |
-| ext4 d¹, `--cpus 8`, 8.9 | 3.90 | 1.67 | 1.62 / 0.85 = 1.90 | 263.4 / 56.6 = 4.66 | – |
-| ext4 e¹, `--cpus 8`, 10.2 | 1.89 | 3.50 | 0.53 / 0.57 = 0.92 | 176.9 / 43.0 = 4.11 | – |
-| ext4 f, `--cpus 8`, 6.8 | 0.80 | 4.19 / 4.19 = 1.00 | 0.56 / 0.86 = 0.65 | 51.4 / 21.0 = 2.45 | 1.0 / 0.62 / 2.9 |
-| ext4 g, `--cpuset-cpus 0-7`, 5.5 | 0.69 | 3.67 / 2.10 = 1.75 | 0.85 / 0.61 = 1.39 | 31.9 / 11.8 = 2.70 | 1.5 / 0.85 / 4.0 |
-| mem, `--cpus 8`, 9.6 | 0.16 | 0.082 / 0.066 = 1.25 | 0.44 / 0.68 = 0.65 | 0.139 / 0.234 = 0.60 | 40 / 7.1 / 50 |
-| mem, `--cpus 8`, 7.2 | 0.17 | 0.066 / 0.066 = 1.00 | 0.39 / 0.66 = 0.60 | 0.143 / 0.249 = 0.57 | 32 / 7.0 / 46 |
-| mem, `--cpuset-cpus 0-7`, 5.7 | 0.16 | 0.066 / 0.057 = 1.14 | 0.42 / 0.73 = 0.57 | 0.138 / 0.216 = 0.64 | 46 / 6.4 / 51 |
-
-¹ The "once at the end" half of the A/B runs in the notes below (the landed
-behavior); their log kept the pass ratios and the ack and lane baselines
-only. Rows a, b and the first in-memory row ran the working tree just before
-the landed commit (the same engine and test). The in-memory passes gave
-81–85 lane samples, under the 100 the test needs to enforce.
-
-- **In memory** the pass stays within 1.5× on all three.
-- **On ext4** the lane p99 stays within 1.5× in 6 of 7 runs, the commit round
-  p99 in 3 of 7, the ack p99 in 1 of 7. The baseline itself moves by 9× from
-  run to run (ack p99 8.8–78 ms): the virtual disk shares the Mac's SSD with
-  the other lanes. The builder syncing its outputs every 1 MiB instead of
-  once at the end (three runs of each, interleaved) gave ack ratios 1.07,
-  1.80, 6.67 against 1.89, 4.66, 4.11 and commit round ratios 2.5, 1.67, 19.2
-  against 1.0, 1.67, 3.5: nothing the variance does not cover, so it is not
-  kept.
-- **The storm** (5,000–7,000 forced SWAPs) raises ack p99 1.8–4× on ext4 and
-  46–51× in memory, and the in-memory lane p99 6–7×. Its SWAPs are the test's
-  device for collecting pre-SWAP statements, not compactions the trigger
-  would start.
-
-So **T3 #1's latency ratio is not shown on this machine**: the pass meets it
-in memory, the ext4 runs are dominated by the virtual disk. It needs a quiet
-Linux box with its own disk; the test enforces the bound there (deviation
-33).
-
-Deviation:
-
-33. **T3 #1 is measured and enforced on the compaction pass** with the
-    design's two metrics (owner commit round p99, interactive lane p99), when
-    the pass gives 100 samples of each; the storm and the ack p99 are
-    reported. T3 enforced ack and lane p99 over the storm, whose thousands of
-    back-to-back SWAPs are not "the compaction" of §18.
-
-## 35. T3b acceptance, what remains
-
-| Item | Result |
-|---|---|
-| 0: store-migrate gseqs, TLV 19, tag conditions | **Done** (ad07b80, §31); released as 3.2.0 by T6. |
-| 1: T3 #5 hot split, A26 | **Built** (§32). Correctness: split = unsplit reference (rows, frames, attributes, SQL), gap-free pseqs, one appending thread per ownership interval; A26 (6 s, Mac mem, load 5–48): 108 rebalances, 163 helper stalls of 100 ms, 44 ownership intervals, 0 non-owner writes, after a reopen 1,094,610 rows checked with 0 corrupt frames. Throughput on the Docker Linux-8 in memory: 2.43–2.71×, median 2.60, ≥ 2.5 in 5 of 6 runs; on ext4 with fdatasync 2.07–2.24× (§34). |
-| 2: A15 arrivals half | **Built** (§33): 0.067 bytes of arrivals per appended entry under churn against 24 without it, offset paging exact, disk bytes = the files, 1,000 crash points with arrivals rewrites. The planner triggers it through its evictions only (deviation 32). |
-| 3: ratios on quiet Linux-8 | Measured on the Docker Linux-8 (§34): #5 as above; **#1 not shown** there (ext4 variance), met in memory. |
-| 4: artifact, CI, gauntlet | `wasm/flatsql-ps-threads.wasm` rebuilt with the Linux wasi-sdk 30 (exports unchanged). |
-
-Remaining:
-
-- **T3 #1 on a quiet Linux-8 box with a local disk**: `cpp/build/flatsql_ps_test
-  --test=compaction_half_dead_T3_1_full --dir=<ext4 dir>` (it enforces the
-  bound when the load is under a quarter of the cores); and the hot split's
-  ext4 ratio there (`flatsql_ps_bench --mode=hotsplit --io=fs --dir=<dir>`).
-- The quota planner requesting type merges (deviation 32).
-
-```
-cpp/build/flatsql_ps_test --test=hot_split_           # T3 #5, A26, trigger
-cpp/build/flatsql_ps_test --test=hot_split_rebalance_stalled_helpers_A26_full   # 10 min
-cpp/build/flatsql_ps_test --test=type_arrivals_compaction_A15 [--seconds=N]
-cpp/build/flatsql_ps_test --test=orphan_crash_points_during_compaction_T3_4_full
-cpp/build/flatsql_ps_bench --mode=hotsplit [--helpers=4] [--io=mem|fs] [--dir=D] [--records=N]
-```
-
-## 36. Eviction ranges name rows, not segments (T3 #3 on Linux)
-
-`quota_arrival_order_heads_spared_T3_3` failed now and then on the ubuntu CI
-job (holes 585 on 71065d3; 616, then 471 on 49e7ac7). It reproduced in Docker
-(Debug, the test looped): 3 of 100 runs on linux/arm64 with 4 CPUs, 1 of 150
-on linux/amd64 with 4 CPUs and stress-ng on 2. Each failure had the same
-interleaving (traced on arm64, 4 of 100):
-
-1. The planner chose partition p's oldest segments from its summary, A
-   (`[0-1]`), B (`2`), C and later, and queued a TOMB_RANGE for each by
-   segment id.
-2. A's range started. Its first steps put A past the dead-share trigger, and
-   maintenance compacted A, which left it small.
-3. Maintenance coalesced the shrunken A with its small neighbour B into one
-   output named A (`[0-2]`).
-4. B's range reached the front of the queue and looked for segment 2. There
-   was none, so it examined nothing and completed.
-
-B's records outlived C's and every later evicted record, and stayed after the
-wave had settled: an engine bug, not the test's view.
-
-34. **An eviction's TOMB_RANGE names the segment's rows** (§13:
-    `TOMB_RANGE{seg, epoch < t}`). The summary carries each sealed segment's
-    `[firstPseq, endPseq)`, which compaction and coalescing never renumber,
-    and the planner's range examines exactly those rows wherever they live
-    now (`Engine::tombRange(pid, seg, bound, ticket, firstPseq, endPseq)`;
-    without a range, `seg` is still resolved when the range starts). A
-    compaction request for a segment coalesced since compacts the output
-    that holds it. Before, it failed NOENT, the wave's space came back only
-    through maintenance, and the next pass could evict below the low-water
-    mark.
-35. **A compaction reads the kills in the active segment's runs.** It
-    collected the runs of the segments that end after its inputs. The active
-    segment has no end until it seals, so the kills a merge had folded into
-    its runs were missed and their rows kept (an eviction's own compaction
-    met this whenever its tombstones merged before the SWAP was planned).
-
-`quota_tomb_range_follows_rows_coalesced_into_older_segment` replays both:
-A and B coalesce, B's range runs from the pseqs taken before that, one L0
-block per step so that some of the tombstones merge into the active segment,
-then B's compaction request. Before the fix, 0 of B's 157 records die and
-the request returns NOENT. With deviation 34 but not 35, the compaction
-drops 29 of the 157.
-
-The quota tests read the files under the engine's reader gate, the way a
-statement does (reclamation runs at a 1 ms grace there), and a partition
-they cannot read fails the test instead of reading as an empty live set.
-The planner's counters are atomic (ThreadSanitizer: quotaStats() read them
-while writer 0 counted).
-
-After the fix (Docker Linux, Debug, the test alone, looped):
-
-| Commit | Machine | Load | Runs | Failures |
-|---|---|---|---|---|
-| bedfe06 (deviation 34) | linux/arm64 | 4 CPUs, stress-ng on 2 | 520 | 0 |
-| 5f4af36 (34, 35) | linux/amd64 | 4 CPUs, stress-ng on 2 | 520 | 0 |
-| a416695 | linux/arm64 | 3 CPUs, stress-ng on 3 | 520 | 0 |
-
-The quota tests also pass under ThreadSanitizer (linux/arm64). The native
-suite (Mac 76 tests; Linux ctest 14 of 14), `crash_faults_T1_1_full` (10,000
-trials) and `orphan_crash_points_during_compaction_T3_4_full` pass. The T3 #4
-harness's arrivals check ran on a second reader instance the reader gate did
-not cover, so a statement could lose a file to reclamation and end
-SNAPSHOT_GONE (on 2f6d86e too: seed 9003, trial 48); the gate now covers both.
-
-`quota_disk_full_resumes_without_operator_T3_6` could stay in its first
-emergency past the test's minute on a loaded box (one episode, three
-segments evicted, the ballast never back). It predated this change: on
-linux/amd64 Debug at a host load near 40, 4 of 100 runs on 2f6d86e and 1 of
-100 here; under ThreadSanitizer, 3 of 6 and 1 of 10. Root cause and fix: §38.
-
-# Part V: reader memory
-
-## 37. Reader memory is bounded by bytes, not by the store
-
-A point reader instance grew while a writer committed: about 5 MB per 20,000
-statements in SDN's probe, a guest `bad_alloc` at 28 minutes in T6's daemon
-soak, and flat once ingest stopped. Nothing leaked per statement (SQLite
-allocates from the lane's fixed arena, every statement is finalized). A cache
-had no byte bound:
-
-- **The lane-private front** of the shared cache (`LaneStore::front_`) was
-  bounded by 65,536 entries only. Every shared-cache hit and put entered it,
-  so it kept every L0 directory and section, fence vector and bloom the lane
-  had used after the 16 MiB shared cache evicted them. Every commit and merge
-  adds keys (type L0 sections are keyed by block offset), so under ingest it
-  only grew; the entry cap lay gigabytes away.
-- A resident run pinned its fences and blooms without charging them to the
-  lane's run budget.
-- The shared cache inserted an object larger than its shard's share of the
-  budget after emptying the shard (up to 64 x the largest object over
-  budget); the private cache did the same with an object over its budget.
-- The set of runs a lane had verified grew by one entry per run ever opened.
-- A run's fences were read whole per kind: 40 bytes per 4 KiB block, about
-  1% of the run, so a lookup in a large type run held its fences whole.
-
-Built:
-
-- The front is an LRU by bytes (`LaneStoreConfig::frontBytes`, set to
-  `ReaderConfig::laneCacheBytes`) and by entries.
-- `ReaderCache` never caches an object larger than a shard's share, and has
-  one shard per MiB of budget (1 to 64: 16 at the default 16 MiB, so a shard
-  holds the largest L0 sections). The private cache never caches an object
-  larger than its budget. Such an object is read again by the next statement
-  that needs it. A manifest is charged its memory (about 200 bytes per
-  segment), not its file size.
-- A resident run is charged its blooms.
-- The verified runs are a 1,024-entry LRU of runs evicted from the lane's
-  run cache (a resident run needs no entry).
-- **Fence pages.** `FenceView` reads a kind's fences a page at a time
-  (`ReaderConfig::fencePageEntries`, 128 fences, 5 KiB) through the shared
-  cache: lookups binary-search across pages, scans walk them, GONE counts sum
-  them. A lookup holds one page whatever the run's size.
-
-**The bound.** Per reader instance, index state is at most
-
-    cacheBytes + lanes x (3 x laneCacheBytes + maxHandlesPerLane x 256 B + 1,024 x 128 B)
-
-(the instance cache; per lane its private cache, resident runs and front,
-its handle table and verified runs): 42.25 MiB with the defaults (16 MiB,
-4 MiB, 2 lanes, 4,096 handles), on top of the fixed arenas and slots. It does
-not depend on the store's size, the statement count or the commit rate.
-
-**Tests.** `ps_test_main.cpp` gives every test allocation a 16-byte header
-and counts the live bytes allocated on reader lane threads, the reader's
-state beyond its fixed arenas, wherever they are freed.
-
-- `reader_point_memory_plateaus_under_commits`: a 2-lane point instance with
-  a 1 MiB instance cache and 256 KiB lane caches runs 164,000 statements
-  (GetRecord by CID and a CID IN at type level, a partition point read) from
-  two clients while producers commit and merges run, then idle rounds. It
-  checks the bound, the lanes' budgets after every round, a flat second half
-  and flat idle rounds. Mac, native: 2.7-3.2 MiB against the 3.9 MiB bound;
-  the engine before this change reaches 7.9 MiB in the same run (linear, 1.1
-  MiB per 20,000 statements) and fails. Under the Node wasm host: 2.72-2.76
-  MiB.
-- `reader_lookups_and_scans_across_fence_pages`: two fences per page against
-  the default and the records written: type and partition point lookups,
-  index range scans both ways, offset paging after deaths (17,986 fence pages
-  past the first read in one run). `fanout_randomized_vs_bruteforce_small_fence_pages`
-  and `offset_paging_matches_reference_small_fence_pages` rerun those
-  suites with two per page; `--fence-page=N` sets it for every reader the
-  fixtures build (the default suite passes with 2).
-- `reader_memory_soak_writer` and `reader_memory_soak_reader` (slow, named):
-  two processes on one directory. The writer grows the store past
-  `--store-mib` (16 partitions, 1.8 KB records, 12 MiB/s) and appends acked
-  CIDs to a file; the reader (native, or the wasm command under the Node host)
-  looks them up in rounds of 20,000 and reports its lane live bytes and its
-  process memory.
-
-Soak, store 65 MiB to 1,200 MiB, Mac Studio (Node 25 for wasm, heap
-pre-grown to `PS_WASM_HEAP_MB`):
-
-| Reader | Caches | Statements | Lane live bytes | Process |
-|---|---|---|---|---|
-| native, before | 2 MiB / 512 KiB | 860,000 | 3.1 -> 57.2 MiB, linear | RSS 21.0 -> 90.2 MiB |
-| native, after | 2 MiB / 512 KiB | 820,000 | 2.4 -> 3.4 MiB (bound 9.25) | RSS 19.6 -> 28.3 MiB |
-| native, after | defaults | 840,000 | 2.7 -> 15.1 MiB (bound 44.25), filling its caches | RSS 20.8 -> 42.9 MiB |
-| wasm, before | 2 MiB / 512 KiB | 800,000 | 2.7 -> 61.4 MiB, linear | linear memory 68.2 -> 103.5 MiB |
-| wasm, after | 2 MiB / 512 KiB | 1,040,000 | 2.1 -> 3.3 MiB | linear memory 68.2 MiB throughout |
-| wasm, after | defaults | 800,000 | 2.3 -> 15.7 MiB (bound 44.25) | linear memory 132.2 MiB throughout |
-
-Native RSS beyond the live bytes is the allocator's high water and the
-harness's CID list (2.7 MiB). The soak reader's frames are never rebuilt:
-`ommRecord` computes `0.0001 + meanMotion * 1e-6`, which one target contracts
-to a fused multiply-add and another does not, so about 11% of a native
-writer's records have other CIDs when a wasm reader rebuilds them.
-
-**What else grows with the store** (bytes per record or segment; none is
-held across statements by the reader beyond the budgets above):
-
-| Where | What | Size | Status |
-|---|---|---|---|
-| reader: `snapshot.cpp` `loadManifest` | a partition's manifest, per statement | about 200 B per segment (3 KiB per GiB at 64 MiB segments) | cached within the lane budget; one larger than it (past about 1.3 TB in one partition) is read per statement: needs a paged manifest |
-| reader: `LazyRun::open` | the run's metadata CRC, once per lane | reads 1% (fences) plus the blooms (1.25 B per entry) of every run it opens | memory bounded (1 MiB buffer); the reads grow with the run: needs per-page CRCs |
-| reader: `loadType` | arrivals fence and segment starts, per statement | 48 B per 64 MiB arrivals segment (2.8M records) | small |
-| reader: labels past 128 partitions, registry, vtab schema | per partition | not per record | small |
-| writer: `L1Run::load` (`index_l1.cpp:168`) | every run's fences and all its blooms, held by `SegRun::run` for each warm partition's segments and each type's catalog runs | 1% of each run plus 1.25 B per entry | grows with the store: a terabyte store holds gigabytes in the writer instance; needs the reader's paging |
-| writer: `SegmentInfo::cdir` (`compaction.cpp:382`) | a compacted segment's presence directory, kept once loaded | 0.13 B per record | grows with the store |
-| writer: `Partition::segs`, `summary`, the file ledger | per segment | a few hundred bytes per segment | grows with segments |
-
-# Part VI: memory safety and races
-
-## 38. The ps-wasm trap, the sanitizers, the first emergency
-
-Task flatsql-ps-memory-safety-races-20260929. Machines: the owner's Mac
-Studio (Darwin 25.3.0, arm64, 28 hardware threads) shared with other lanes
-(1-minute load 17–95 during these runs), and linux/arm64 in Docker Desktop on
-it (gcc 13 and clang 18, `--cpus 4` with `stress-ng` on one CPU unless noted).
-
-**The ps-wasm trap is V8's shared-memory grow race, not an engine overrun**
-(PARTITION-STORE-WASM.md §4.3). CI's trap was a `memory.fill` right after an
-`operator new` on the type-merge helper, into memory another thread had just
-grown; V8 bounds-checks it against the thread's stale view of the memory's
-size. The wasm test main and `createPsNodeInstance` now grow the heap to the
-memory's maximum before any guest thread starts, and the Node host reports
-any growth after threads start. Natively, under ASan and UBSan, T2_1 found no
-memory error (loops below). UBSan found two defects:
-- A misaligned `uint64_t` reference: `Counters` is packed (on-disk).
-  `Partition::counters` is now 8-aligned.
-- Null-pointer arithmetic in `EntryIter::next` (index_l0.cpp). That fix
-  lands with flatsql-format2-query-gaps.
-
-Under WasmEdge the same runs exposed a WasmEdge 0.16.4 AOT defect: atomic
-wait and notify dropped the memarg offset. SDN's static runtime carries the
-fix, patch `04-atomic-memarg-offset` (SDN 74db37e14). `sleepNs` passes its
-address through a volatile, so its wait carries no memarg offset.
-`memory_safety_sleep_and_notify_at_folded_offsets` fails on a runtime without
-the fix.
-
-**ThreadSanitizer.** The whole default suite runs TSAN-clean (Docker, gcc 13
-`-fsanitize=thread`, `--cpus 6`) apart from the stage-1 races below. Each
-race found:
-
-| Where | What | Verdict, change |
-|---|---|---|
-| partition_log.cpp:2509 (`partitionPublish`) against type_owner.cpp:671 (`typeStage`) | The owner publishes a partition's commitSeq, pseqHi and L0 directory inside its seqlock; the type owner copies them and retries on a moved sequence. | Benign by design (a seqlock), but a plain copy on both sides is a data race in C++. Both sides now copy 8-byte words with relaxed atomic accesses (`publishPartition`, `readPublishedPartition`, writer.h). The sequence counter's fences order them. `PublishedPart::l0` is 8-aligned. `memory_safety_seqlock_publication_consistent`: readers racing a publishing owner only ever copy out whole states. |
-| writer_pool.cpp:230 (`SyncPool::runAll`) against `helpOne` | A pool thread reads a slot's `jobs` pointer while the writer publishes its next round; that stale pointer's claim then fails. | Benign by design. The pointer is `std::atomic` (relaxed); the round's `n` (release/acquire) orders the jobs. `memory_safety_sync_pool_rounds_run_each_job_once`: 6 writers × 400 rounds, each job runs exactly once with its own result, and the pool threads help. |
-| lane_arena.cpp:415 (`mxAlloc`) | Every lane's connection allocates SQLite's static mutexes again, which rewrote their shared wrappers. | Real (same values, rewritten under readers). The wrapper is filled once (`std::call_once`). |
-| lane.cpp:930 (`oldestActiveStart`) against `~ReaderInstance` | `Engine::setReaderGate` returned while a writer thread could still be inside the previous gate function, and the caller then destroyed the reader instance it reads. | Real: a use-after-free window. `setReaderGate` now clears the gate, waits for the gate calls in flight (a counter), then installs the new pair. |
-| merge.cpp:732 against open_test.cpp:296; reader_concurrency_test.cpp:216; compaction_test.cpp:565 | Tests read the owner's `nL0` from the main thread, or a latency series without its lock. | Test races. The tests read the published directory and take the lock. |
-| stage1.cpp:322 against stage1.cpp:499 (prep slots); ring.cpp:125 (a helper copies an entry the owner has consumed) | The owner republishes a slot it stole from a helper while the helper still reads it. | Benign by design (the helper's result is discarded by a failing CAS), and memory-safe (the copy stays inside the slab pool). Atomic slot fields and a racy-copy ring read belong to flatsql-ps-partition-bookkeeping-linear. |
-
-**T3 #6: the first emergency could stall for good** (§36). Traced under
-TSAN:
-- The eviction wave's partition had a full L0 directory (47 blocks) from
-  ingest before the emergency, so its TOMB_RANGE needed a merge first.
-- Meanwhile the room the ballast gave back was spent by maintenance outside
-  the eviction: the other partition's merges, and a compaction nobody
-  requested. Its build failed NOSPACE and started over with a new intent
-  batch in the meta log about ten times a second. Usage crept 8,960 B/s until
-  the device was exactly full.
-- From then on no batch committed. The wave's merge could not write outputs
-  and no TOMB step could stage, for the rest of the minute.
-
-36. **In a space emergency, maintenance leaves the ballast's room to the
-    eviction** (A13 assumes the ballast holds one segment's tombstones, and
-    says nothing of what else may spend it). Only a partition with eviction
-    work waiting merges (TOMB_RANGE steps, type-level kills, a requested
-    compaction: `partitionWantsMerge`). A compaction the planner did not
-    request does not start (`Writer::maintenance`); one in flight finishes.
-    Ring entries stop `kL0ControlSlots` (4) L0 slots before the directory's
-    cap, which mailbox kills and TOMB_RANGE steps may use, so a wave's first
-    steps never wait for a merge.
-
-Measured, in Docker:
-- **Before:** under TSAN, 4 of 12 runs, and 1 of 7 traced ones, stayed in
-  the first emergency until the test's limit (70 s).
-- **After:** 50 of 50 TSAN runs recovered (whole test 19–43 s), and 340 of
-  340 Debug runs (gcc `-O0`, 8–10 s each). The test also passes natively on
-  the Mac and under the Node host.
-
-**Loops** (Docker runs had a CPU hog on one of their CPUs; the Mac ran at
-load 17–95):
-
-| Item | Loop | Runs | Result |
-|---|---|---|---|
-| The trap | T2_1 under the Node host, heap grown to the maximum (Mac) | 500 | 0 traps. No run grew memory after a thread started. One run ended in a Node 25.4.0 SIGILL inside V8's JIT code (a host crash, not a guest trap). |
-| The trap | T2_1, native, ASan + UBSan | 488 before the T3 #6 change, then more on these sources | 0 ASan errors. UBSan reports only index_l0.cpp:319. |
-| The trap | T2_1 memio, WasmEdge 0.16.4 AOT with patch 04, no pre-grow (Mac) | 140 | 0 traps, 0 hangs. 2 failed: the memio command keeps every file in guest memory, and one run ran out of the 4 GiB address space (passing runs end near 2.7 GiB after about 500,000 records). The other run's output was not kept. |
-| Seqlock, sync pool | `memory_safety_s*` under TSAN | 520 | 0 warnings, 0 failures |
-| All races | The default suite under TSAN | 1 | Clean except the stage-1 races above. `arrivals_paging_while_writers_produce_T2_6` misses its 60 s label wait under TSAN, exactly as on 14a3075. `reader_point_memory_plateaus_under_commits` misses its idle-round bound under TSAN (0.155 MiB against 64 KiB). Both pass natively and under the Node host. |
-| T3 #6 | TSAN; Debug | 50; 340 | 0 stalls |
-
-**Writer memory that grows with the store.** §37's table lists the writer's
-per-store structures. Measured here with 200,000 OMM records in one partition
-at the defaults:
-- A warm partition's L1 accelerators (`SegmentInfo::runs`, loaded for every
-  segment by `partitionWarm`, merge.cpp:172) hold 6.0 B per record of the
-  partition's history. A partition written without a pause never cools
-  (`idleCloseMs`).
-- A type's catalog accelerators (`TypeOwner::runs`, loaded by `typeWarm`,
-  type_owner.cpp:580) hold 3.45 B per record of the type. A type owner never
-  cools.
-- Every registered partition keeps a 5,952-byte `Partition` (writer.h:505)
-  plus its ring descriptor, active or not.
-
-At 10^9 records (a terabyte of OMM-sized records) the catalog alone is
-3.4 GB in one writer instance, over the wasm32 limit.
-
-# Part VII: query gaps
-
-## 39. Query gaps found on the host-02 fixture (T6)
-
-T6 compared format 2 with format 1 on a host-02-sized migrated store (4.36 M
-records: OMM 1.70 M in one partition, MPE 1.69 M, CAT 141 k, IQC 419 k held by
-two producers). Five read shapes were slower than format 1, and store-migrate
-refused one record shape. Each is now an engine plan or check, held to a
-reference by `cpp/test/ps/query_gaps_test.cpp` (`query_gaps_*`) and to format 1
-by SDN's fixture comparison.
-
-**Text CID order (A17).** `ORDER BY _cid [DESC]` with no other index
-condition is its own plan (`kAccCidOrder`). At type level it reads the cid
-catalog (`kIxTypeCid`), whose keys are the A17 sort key: one ordered pass
-gives the live CIDs in text order. A key's entries resolve per copy (the
-latest type commit wins; DEAD over the rest at an equal tcs, as `catalog()`
-does); the live FIRST or PROMOTED copy is the record, and only its row is
-read. An `OFFSET` with no other condition is pushed down and counted from
-catalog entries alone: no row, frame or posting of a skipped record is read.
-At partition level the plan reads the partition's CID postings. With other
-conditions the plan still gives the order; the conditions are checked per
-row.
-
-**Per-object point profiles (A18).** Hidden input columns `_asof`,
-`_forward` and `_nearest` (epoch seconds, `=` only) select `kAccObjPoint`.
-Per object key it returns every live type-level row at the object's best
-second: `_asof` the latest second at or before T, `_forward` the earliest at
-or after, `_nearest` the closer of the two with a tie to the earlier. The
-plan reads the `OBJECT_EPOCH` postings `(object key, epoch)` of every
-partition, restricted by the manifests' epoch zone maps to the segments that
-can hold a candidate, merges the partitions by object key, and reads rows only
-for the candidates of each object's best seconds (from the closest outward,
-until one is live). Tag conditions and one `_epoch` range are applied before
-the choice; any other condition is refused (`SQLITE_CONSTRAINT`: SQLite would
-apply it after the choice, which is another query). `_object` projects the
-key: a u64 key in decimal, otherwise the (capped) string, NULL for a record
-without one. Records without an object key are read only from partitions whose
-`OBJECT_EPOCH` postings are fewer than their CID postings (the EPOCH index,
-their frames); each is its own entity. For OMM (NORAD, then OBJECT_ID) and MPE
-(ENTITY_ID) the object key is the legacy entity key, so SDN ranks the
-candidates exactly as format 1 did.
-
-**The sandbox window (A18).** Untrusted SQL reads `<TYPE>`, `<TYPE>@<source>`
-and every other type-level shape except a CID or gseq lookup from the arrivals
-tail: the newest N entries (`hotWindow`, dead entries included), the
-statement's conditions applied per row. An alias or source statement no longer
-walks every posting of its source; its work is bounded by N whatever the
-store's size.
-
-**Tag conditions on every copy (A2).** Type-level tag conditions (`_provider`,
-`_source_name`, `_batch`, `_peer_id`, `_source`, and the alias source) match a
-record when a live instance of any live copy (FIRST or REPEAT, any partition
-the plan reads) meets all of them, as the legacy tag table held every
-producer's tags per record. This extends §31.1 and T2 deviation 8.
-Row-driven plans check the FIRST copy's own tag first, then the other copies'
-own tags (listed by the cid catalog, only when the type has REPEAT postings),
-then RETAG instances. Posting-driven plans (tag, source, collected pages) let
-a live REPEAT copy's instance stand for its record: the record's FIRST row is
-emitted by the first matching copy in (FIRST, then REPEATs by pid, pseq)
-order, so each record comes once. `<TYPE>@<source>` is `<TYPE>` with that
-condition. The checks cost little per row: an instance's tuple is its lane's
-(`RecRow.laneId`, the partition's lane table read once per statement), a copy
-whose pseq is above the highest `max_pseq` of the lanes that meet the
-conditions cannot match (its RETAGs come after it), TAG_OF lookups read only
-the segments that can hold them and resume in the block the previous row's
-lookup read, and DEAD / TAG_DEAD lookups are skipped for a snapshot that holds
-no posting of the kind.
-
-**Gseq-ordered tag pages (A16).** At type level, `ORDER BY _gseq` with tag
-conditions and a LIMIT (or a closed gseq range) is served in arrivals order
-with each row's tags checked, unless the lane counters say the tags are rare
-(at most 262,144 matching instances and under an eighth of the type's
-arrivals): then the tags' postings are collected (the most selective of batch,
-source, provider, peer), sorted by gseq and emitted in order. A datasync page
-by source no longer sorts every match of the source.
-
-**Records stored with their own size prefix.** A record that carries its own
-size prefix (a `FinishSizePrefixed` buffer stored as is: SDN's
-dataset-publication PNMs and the local EPM) was refused with `kRejFid` (its
-identifier sits at frame offset 12), so store-migrate rejected 131 records of a
-dev node and refused to activate. `frameRootOffset()` (`extract.h`) finds the
-FlatBuffer after both prefixes (the record's u32 equals `len - 8` and the
-identifier is at 12) for the frame check, the verifier (at the record's own
-alignment origin), key extraction and column projection. The stored bytes and
-the CID (over the record, prefix included) are unchanged.
-
-**Reads ahead.** Rows met in ascending pseq order (arrivals order, epoch and
-tag postings, pseq scans) are read 32 at a time, and a frame read covers the
-frames of the rows read ahead in its segment (up to 256 KiB).
-`rowsExamined` still counts the rows a statement uses.
-
-**Measured** through SDN's storage API on the fixture (`TestZZBench`-style
-calls, each query twice in a fresh process: the first call pays the
-instance's warm-up and the page cache; format 1 is the same store before
-migration). Mac Studio (M3 Ultra, 28 cores), shared with other lanes, load
-47–55. Format 2 "before" is T6's run on the same fixture.
-
-| Gap | Query | Format 1 (call 1 / 2) | Format 2 before | Format 2 after (call 1 / 2) |
-|---|---|---|---|---|
-| 1 | OMM CID order, LIMIT 500 OFFSET 1000 | 730 ms / 26 ms | 9.9–28.4 s | 2.65 s / 3.6 ms |
-| 1 | CAT CID order, LIMIT 200 OFFSET 60000 | 2.39 s / 67 ms | 430–537 ms | 589 ms / 11 ms |
-| 1 | IQC CID order, LIMIT 1000 OFFSET 100000 | 3.90 s / 153 ms | 5.0–5.5 s | 4.14 s / 35 ms |
-| 2 | OMM `nearest` (32,015 objects) | 99 s / 22.7 s | 56–79 s | 10.6 s / 2.3 s |
-| 2 | OMM `as_of`, one source | 36 s / 19.5 s | 9.7–13.1 s | 3.9 s / 4.2 s |
-| 2 | OMM `forward` | 14.6 s / 19.5 s | 8.4–82 s | 6.8 s / 6.1 s |
-| 2 | MPE `nearest`, 2 h delta | 50 s / 17.6 s | 29–35 s | 7.1 s / 6.1 s |
-| 3 | sandbox `SELECT _data FROM "CAT@celestrak-satcat"` (N = 10,000) | 4.4 / 3.9 ms¹ | `timeout` (work budget) | 55 / 11 ms |
-| 3 | `"CAT@celestrak-satcat-csv"` | 1.3 / 1.3 ms¹ | `timeout` | 3.2 / 4.5 ms |
-| 3 | `"IQC@IQEngine"` | 14.8 / 13.3 ms¹ | `timeout` | 67 / 32 ms |
-| 3 | `"MPE@celestrak-gp"` | 3.2 / 4.3 ms¹ | `timeout` | 68 / 7.3 ms |
-| 4 | IQC source window, LIMIT 1000 (two producers) | 12.7 s / 2.0 s | 111–121 ms (per partition, merged in SDN) | 183 / 30 ms (one statement) |
-| 5 | IQC datasync by source, 5 pages of 500 | 133 s / 190 s | about 3.8 s a page | 58 / 32 ms (all 5) |
-
-¹ Format 1's hot window is an in-memory copy of the newest N records, filled
-by a hydration (17 s to 5.5 min on this fixture) and held in the arena whose
-growth is what format 2 replaces. Format 2 reads the window from disk: the
-engine's own cost for the CAT query is 2.4 ms natively (the rest is the wasm
-instance, the result ring and SDN's copy). Gap 3's acceptance (the statement
-answers within the work budget, bounded by N) is met; parity with the
-in-memory copy is not.
-
-The first call of a fresh process pays the instance's warm-up and reads the
-cid catalog's blocks into the page cache (2.65 s for OMM against 730 ms for
-format 1's index); every later call is faster than format 1.
-`TestFormat2DaemonReadsEqualTheLegacyFixture` (SDN) passes with every section
-(windows, A17 exports, A16 syncs, epoch profiles, A18 relations) equal to
-format 1 on this fixture.
-
-**store-migrate with size-prefixed records.** A copy of a dev node's store
-(9.2 GB control database, 163 PNMs in 37 partitions, 1 EPM): 0 copies
-rejected (131 before), partitions (58) and lanes (58) equal, 9 of 10 CID
-sequences equal. The tenth (IQC) differs because that store's index holds
-about 1.06 M IQC rows no producer table holds (orphans the legacy verifier's
-sequence includes; filed for SDN). `TestStoreMigrateActivatesWithSizePrefixedRecords`
-(SDN): a store with 12 PNMs in two partitions and an EPM migrates with 0
-rejects and 0 mismatches, activates, and serves the same bytes.
-
-**What these cost at 1 TB** (per statement; P partitions of the type, S
-segments per partition, R type catalog runs):
-
-- CID order: `(offset + limit) x copies per CID` catalog entries of about
-  72 B (about 56 per 4 KiB block) plus one row read per emitted record. The
-  skip is linear in the offset, as format 1's b-tree OFFSET is. Per-block live
-  counts in the catalog's fences would make it logarithmic, but a CID's copies
-  die in later type commits than their FIRST labels, so the type owner would
-  have to post a CID-keyed marker when a CID's last copy dies (outside this
-  change: `type_owner.cpp`).
-- Point profiles: the `OBJECT_EPOCH` postings (about 30 B each) of the
-  segments whose epoch zone can hold a candidate: for `_forward` near the
-  present, the newest segments; for `_asof` and `_nearest`, the segments
-  before (or around) T. No payload is read to rank; rows are read for about one
-  to two candidates per object. Enumerating the objects stays linear in the
-  postings of those segments: a per-partition object directory would make it
-  proportional to the objects.
-- Sandbox window: at most N arrivals entries (24 B) and N rows, whatever the
-  store's size.
-- Tag conditions: per row an O(1) lane check, and a TAG_OF lookup only for a
-  copy that a matching lane can still reach; a catalog lookup (R bloom-gated
-  runs) only in a type with REPEAT copies.
-- Gseq tag pages: LIMIT / selectivity arrival entries and rows per page
-  (arrivals mode), or the tags' matching instances (collected mode, at most
-  262,144).
-- Size-prefixed records: nothing (a 4-byte comparison per record).
-
-# Part VIII: writer bookkeeping at scale
-
-## 40. Per-partition bookkeeping at scale (TB audit B4, M3)
-
-The terabyte audit (stack `docs/architecture/flatsql-ps-terabyte.md`, B4)
-found a partition's bookkeeping growing as O(S²) in its segment count S. A
-single dominant partition (the GP archive import, a hot-split partition)
-reaches S = 1,000 at about 170 GB and S = 6,000 at about 1 TB. With 128 KiB
-seals, the rate fell from 116,829 rec/s at S = 235 to 465 rec/s at
-S = 5,188. Commit rounds reached a p99 of 100.7 ms and maintenance steps
-100.7 ms. The causes:
-
-- The ledger (§26) was a vector searched linearly.
-- `partitionPublishSummary` made three ledger scans per sealed segment on
-  every commit that carried a MERGE_DONE, SEAL, SWAP, RETIRE or UNLINKED.
-- The compaction look walked every segment every 50 ms, with the same three
-  scans and an L0 scan per segment.
-- Segment lookups were linear.
-- Open rebuilt the ledger in O(S²).
-- A MERGE_DONE and a SWAP recomputed the accelerator bytes by walking every
-  run.
-- A split partition re-signed its run set on every commit by walking every
-  run, and its helpers matched their previous view run by run in O(runs²).
-
-What the owner keeps now (`PartitionLedger`, `ps/quota.h`):
-
-- **The ledger** is an open-addressing table keyed by `(letter, seg, gen)`,
-  with the same matching rules as before: manifests by generation, `d r a m`
-  by segment, the rest by both. The byte total changes with every set and
-  drop. A lookup, change or drop costs O(1).
-- **A change feed.** A ledger change to a segment's files, a new entry, a
-  kill count, a survey and every input of a SWAP name the segments
-  concerned. The planner's summary and the compaction candidate index update
-  only those segments. The summary does this on the commits that publish
-  it, the index on each look. Open rebuilds both in one walk.
-- **The compaction candidate index** applies §24's rules unchanged:
-  - segments past the dead ratio, ordered by share (largest first, lowest
-    id among equals);
-  - starts of adjacent small pairs, where the first run of small segments
-    begins at the lowest pair and grows within the coalescing limits;
-  - segments not surveyed since a restart.
-  A look costs O(log S), plus the output's neighbours.
-- **Segment lookups** binary-search the ascending entry list. Entries are
-  created in order, and a pseq search steps over entries that hold no rows
-  yet. Open walks the unmerged sealed segments alongside the entries.
-- **Accelerator bytes** change by the runs a MERGE_DONE or SWAP adds and
-  removes.
-- **The split run set** is signed by the manifest generation, since every
-  change to it commits a new one. A republish for new L0 blocks shares the
-  run list instead of copying it. Helpers find reusable runs by
-  `(seg, gen)`.
-
-Stage-1 helpers (§32) no longer race the owner or producers (ThreadSanitizer):
-- A slot's `pos`, `len` and `kind` are relaxed atomics. The owner may take a
-  CLAIMED slot and republish it for the next ordinal while the helper still
-  reads them.
-- A helper copies an entry with `ringReadShared` (relaxed 8-byte word
-  loads), never through a pointer into the ring. After a steal, the owner may
-  consume and release the entry, and a producer may rewrite its bytes while
-  the helper copies.
-- `ringWrite` stores relaxed words and edge bytes, which natively cost what
-  plain stores do; the wasm hosts write slabs themselves.
-- In both cases the helper's CLAIMED to WRITING step fails and its result is
-  dropped, as before. What it parsed is its own copy.
-- Slabs must be whole 8-byte words.
-
-Deviations:
-
-37. **The RETIRE set is held under what one batch carries** (A12 said: past
-    2,048 items, the oldest go regardless of the gate once a grace has
-    passed). The set rides one ctl record, whose length is a u16, inside the
-    batch's 64 KiB ctl buffer, alongside UNLINKED (up to 1,024 items) and the
-    lane table. A set that does not fit refuses every batch of the
-    partition. A busy partition retires a manifest and folded runs per
-    merge, and a coalescing SWAP retires a dozen files per input, so within
-    the 60 s grace its set outgrew a batch. Ingest then stopped for the rest
-    of the grace. The audit harness showed 843 rec/s for 50,000 records at a
-    time, about every minute. The valve counts the set as its record
-    encodes it (consecutive manifest generations collapse). The soft cap is
-    2,048 items, or less when a large lane table leaves less room. Past it,
-    the oldest items are unlinked at once, without waiting for the reader
-    gate or the grace:
-    - A statement older than those items gets the retryable SNAPSHOT_GONE.
-    - A file held open is BUSY and waits as before.
-    - A meta segment still waits for a durable head (A9).
-    - Crash safety never depended on the grace. The batch that retired a
-      file is durable before its retirement counts, and open replays that
-      batch.
-    - While a compaction in flight pins the newest items and the set is past
-      halfway from the soft cap to the hard cap, merges wait. Merges are the
-      steady source of retirements, so the SWAP or abort can land first.
-38. **Manifest version 3 (M3)** carries the segment count as a u32 in the
-    header's last word (the u16 then reads 0xFFFF). It is written only when
-    a partition's list outgrows the u16, so an engine that predates it still
-    reads every store it can represent, and refuses a version 3 manifest
-    instead of misreading it. Every version now decodes strictly: the
-    records must end exactly at the CRC trailer. Before, a version 2
-    manifest over 65,535 segments wrapped its count, passed the CRC and lost
-    the rest.
-
-Measured on the Mac (Darwin 25.3.0, arm64, 28 hardware threads, shared) with
-the in-memory fault host. One partition, 128 KiB seals, coalescing off (so S
-is the seal count), 400 B pad records, lockStats on:
-`bookkeeping_scale_S5k`. The base column is 0df6ef4 (its writer is
-14a3075's) with the same test. Each row is the 50,000-record window that ends
-at that S.
-
-| | S = 235, base | S = 235 | S = 5,188, base | S = 5,188 |
-|---|---|---|---|---|
-| commit round p99 | 0.328 ms | 0.229 ms | 100.7 ms | 0.115 ms |
-| maintenance step p99 | 0.082 ms | 0.049 ms | 100.7 ms | 0.328 ms |
-| summary refresh p99 (per commit that publishes it) | | 0.016 ms | | 0.004 ms |
-| candidate look p99 | | 0.033 ms | | 0.012 ms |
-| open (half, full: S = 2,594, 5,188) | | | 45.7 ms, 170 ms | 4.0 ms, 4.5 ms |
-| rec/s | 116,829 | 99,796 | 465 | 5,386 |
-
-Load was 39–60 for the base run and 22–30 for the new one. The same test on
-this change over d566293, at load 26–37: commit p99 0.393 → 0.229 ms,
-maintenance p99 0.066 → 0.786 ms, summary refresh 0.012 → 0.020 ms,
-candidate look 0.049 → 0.016 ms, open 6.0 ms at S = 5,188, rate 77,556 →
-3,363 rec/s.
-
-Over the same 200,000 records (S = 0 to 940), the process used 5.9–6.9 s of
-CPU against 9.2–10.3 s on 14a3075 (six alternating runs). Near S = 235 the new
-build's wall rate was lower than base's by about 7% in alternating runs
-(82,405 against 94,237 rec/s, load 30–37), while at S ≈ 11 the two were equal.
-With shorter commit rounds, the writer commits smaller batches (about 940
-commits per 50,000 records against 700) and waits idle for the test's single
-producer. The time is lost in the handshake, not in work.
-
-On ext4, in Docker's Linux VM on the same Mac, the audit's harness
-(`tb_segments_scaling`: fsync on, one partition, 128 KiB seals, 550,000
-records) was bound by the VM's shared virtual disk. Other lanes' containers
-were using it too, so both builds ran near 500 rec/s at S = 235:
-
-| build | S = 235 | S = 1,886 | S = 2,594 | reopen at S = 2,594 | whole run |
-|---|---|---|---|---|---|
-| 14a3075 | 475 rec/s | 211 rec/s | 356 rec/s | 21.0 s | 31.3 min |
-| this build | 522 rec/s | 795 rec/s | 781 rec/s | 3.6 s | 19.0 min |
-
-`bookkeeping_scale_S5k` itself on the same ext4 volume (`--dir`) is disk
-bound: commit rounds wait on fsync (p99 336 ms at S = 235, 470 ms at
-S = 5,188). The bookkeeping in them stays flat, though: the summary refresh
-p99 is 0.041 → 0.033 ms and the candidate look p99 0.066 → 0.029 ms, and
-open at S = 5,188 takes 134 ms. With `--dir` the test reports commit and
-maintenance p99 without gating them.
-
-The rate that remains decays with S because of B5: every record's CID dedupe
-probes the bloom of every L1 run of every segment (`committedPostings`,
-`partition_log.cpp`). `sample` at S ≈ 4,900 puts 94% of the writer's samples
-in `cidState` and about 1% in the paths this section changed: maintenance,
-commit rounds and reclamation together account for 184 of 12,272 samples.
-Per-partition levelled lookup indexes (B5) are the terabyte design's.
-
-What still costs O(S), and where it belongs:
-- A merge snapshots every segment into the manifest it rewrites (M3's delta
-  or two-level manifest). The maintenance p99 above (0.05 → 0.33 ms) is
-  that.
-- A SWAP writes a whole manifest and rebuilds the entry list.
-- A split partition's helpers reopen every run file per run set (B2's
-  handle LRU).
-
-Tests (`cpp/test/ps/bookkeeping_scale_test.cpp`):
-- `book_manifest_v3_codec`: exact round trips at 0, 1, 65,535, 65,536 and
-  70,001 segments; a wrapped v2 count, a stray byte, a bad v3 header and
-  version 4 refused; version 1 read.
-- `book_retire_valve_keeps_ingest_flowing`: 60,000 records at the default
-  60 s grace. 16,767 files retired, 14,299 unlinked by the valve, the
-  encoded set peaked at 2,113, 0 batches refused. With the valve off, the
-  same test refused 4,397 batches and one 5,000-record chunk took 59.5 s.
-- The valve test also reports the writer's memory, and none of it grows
-  with records. From 25,000 to 60,000 records:
-  - slab pool: 3.9 → 4.1 MB;
-  - ledger: 2,271 → 2,398 files (67 → 69 KB);
-  - RETIRE set: 2,145 → 2,217 items (160 KB);
-  - segment list: 54 → 68 entries (12 → 15 KB).
-  The process does grow: 1.47 GB at 25,000 records and 3.55 GB at 60,000
-  (3.4 GiB of wasm's 4 GiB). That is the in-memory test host, which keeps
-  every file it ever wrote (7,212 files, 1.45 GB; then 17,281 files,
-  3.52 GB) so that data calls need no lock. The rest of the heap
-  (13 → 25 MiB) grows by the host's 231 B per file. On wasm the test runs
-  25,000 records.
-- `book_equivalence_all_commit_kinds`: runs with `gBookCheck`, which checks
-  every ledger operation against the linear ledger it replaced, and every
-  segment lookup, summary refresh, candidate pick and split run-set
-  signature against a walk. A mismatch aborts. The run covers seals,
-  merges, SWAPs (dead-ratio, coalescing, requested, quota evictions),
-  RETIRE and UNLINKED, meta-segment retirement, a hot split, a clean
-  reopen and a kill -9.
-- `book_crash_every_op` (every 37th mutating call) and `_full` (every one:
-  9,416 crash points over seals, merges, SWAPs, retirement, unlinking and
-  A9, all five crash modes, 0 failures): after each reopen, the rebuilt
-  ledger names exactly the files on disk at `disk_bytes`, counters equal a
-  recount, and the engine carries on under `gBookCheck`.
-- `book_check_fast_suite` (slow): every fast test again with `gBookCheck`
-  (88 of 88 passed).
-- `bookkeeping_scale_S5k` (slow): the table above. It gates commit and
-  maintenance p99 under 10 ms at S ≥ 5,000, and the summary refresh and
-  candidate look within 2× (+50 µs) of their S = 235 cost. On the base
-  commit it fails both p99 gates.
-
-Sanitizers, on this build over d566293 (macOS, clang):
-- ThreadSanitizer reports nothing on eleven tests: the four book tests,
-  `quota_arrival_order_heads_spared_T3_3`,
-  `compaction_cat_supersede_plateau_T3_2`,
-  `orphan_crash_points_during_compaction_T3_4`, and the four fast hot-split
-  tests.
-- AddressSanitizer with UBSan reports nothing on the book tests,
-  `compaction_removes_dead_rows_keeps_live`,
-  `quota_arrival_order_heads_spared_T3_3`, the orphan harness,
-  `hot_split_equals_unsplit_reference_T3_5` and `crash_faults_T1_1`. It had
-  found one defect in this section, fixed: `std::min` bound a reference to a
-  packed counter.
-- The stage-1 race, before and after, on Docker linux/arm64 with gcc 13 and
-  on macOS:
-  - 14a3075 reports it in 3 of 5 hot-split runs (`hot_split_throughput_T3_5`,
-    and `hot_split_rebalance_stalled_helpers_A26` at 12 s, twice);
-  - this change reports it in none of 6 runs.
-  - A two-thread program (`ringWrite` against a helper's read of the same
-    bytes) shows it on Linux with a plain reader, and still shows it with
-    atomic loads against a plain `memcpy` write. It is silent only once both
-    sides are atomic.
-- Under ASan the equivalence test needs more than its default 60 s to settle
-  (it passes with `--eq-settle-s=600`).
-
-Mutations the checks caught:
-- a missing kill touch;
-- a SWAP input not touched;
-- a ledger update dropped;
-- the valve off.
-
-# Part IX: format levels and lane checkpoints
-
-## 41. Lanes past 1,170 and format levels (TB03)
-
-The terabyte design (stack `docs/architecture/flatsql-ps-terabyte.md` §2.9 K0,
-§3, §10 TB03) found that a partition stops committing past 1,170 live lanes.
-Past 32, every batch that changed a lane carried the whole live table (56 B a
-lane) in one LANE_CKPT ctl record. A u16 bounds that record, so a table past
-(65,535 − 4) / 56 = 1,170 lanes refused the batch, and every retry refused it
-too. SDN mints a lane per fetch, so a 3-hourly source whose history stays
-live crosses the cap in about 146 days. Below the cap each such batch still
-rewrote about 65 KB near 1,170 lanes. The RETIRE encoder also reserved room
-for every lane ever loaded.
-
-Measured before the change on 2026-09-30:
-- host-02's legacy store (read-only, `sdn_record_source_summary`): the
-  largest partition is MPE.fbs, celestrak-gp, at 66 live lanes. That is 5.6%
-  of the cap. It grows about 4.3 lanes a day, so it would reach 1,170 in
-  about 257 days. The next largest are RFB.fbs at 11 and OMM.fbs at 3.
-- The host-02 fixture migrated with SDN's store-migrate (4,364,873 records):
-  OMM has 53 lanes, MPE 52, CAT 2 and IQC 1.
-
-### Format levels
-
-`cpp/include/flatsql/ps/format_level.h` holds `kFormatMin` 2, `kFormatMax`
-3 and `kLevelLaneCkpt` 3. `STORE.format` is the store's level.
-`HeadPrefix.format` and MIGRATED stay 2, because SDN's Go head reader checks
-them.
-
-- **Accepted levels.** An engine opens `kFormatMin ≤ format ≤ kFormatMax`.
-  A valid STORE above that is refused ("STORE format N is newer than this
-  engine") before any file is created or written. So is a torn STORE whose
-  STORE.tmp (below) is above it. An intact STORE the engine opens is never
-  refused because of a higher STORE.tmp: that ratchet never reached step 2,
-  so nothing of its level exists, and the leftover is removed. Readers apply
-  the same rules: an intact STORE decides alone, and only a torn one reads
-  through STORE.tmp.
-- **writeFormat** (writer TLV 31, `EngineConfig::writeFormat`; 0 is
-  `kFormatMax`). A fresh store is created at it. At open, STORE ratchets up
-  to it, but only once `registry.fsl` is non-empty: an empty store can still
-  be recreated by an older engine. Nothing of a level is written before the
-  ratchet to it is durable. A host can pin a lower level for a staged
-  rollout, and a pinned host keeps its level: a STORE.tmp above the pin is
-  removed, not finished. A store never ratchets down.
-- **A full device.** When STORE.tmp cannot be created, written or synced
-  (step 1), the ratchet does not start: the leftover is removed, the store
-  opens at its level exactly as the level-2 open would, and the next open
-  tries again. A ratcheting engine on a full disk therefore never keeps a
-  host down that the older engine would start.
-- **The ratchet.** The I/O ABI has no rename (deviation 39), so the ratchet
-  takes three steps:
-  1. STORE.tmp (the new STORE) is written whole and synced; its directory
-     entry is durable from creation.
-  2. STORE is rewritten in place (64 bytes, one sector) and synced.
-  3. STORE.tmp is unlinked.
-
-  A STORE.tmp is this store's when every field but the format equals
-  STORE's. STORE is written once, and only the ratchet rewrites it, changing
-  only its format, so a STORE.tmp an older engine left beside the store it
-  went on writing still describes that store. An open finishes the ratchet
-  from STORE.tmp when STORE is torn (STORE.tmp is the one valid record), or
-  when STORE is intact and the open writes that level. Otherwise STORE.tmp is
-  removed and STORE stands. Level-3 files exist only after step 2.
-
-  The released 3.5.1 engine reads STORE only, run natively on each crash
-  state:
-
-  | State | 3.5.1 | Files |
-  |---|---|---|
-  | STORE 2, STORE.tmp 3 (step 1 done) | opens, writes level-2 data | changed |
-  | STORE torn, STORE.tmp 3 (inside step 2) | "STORE is corrupt" | unchanged |
-  | STORE 3, STORE.tmp 3 (step 2 done) | "STORE is corrupt" | unchanged |
-  | STORE 3 (finished) | "STORE is corrupt" | unchanged |
-
-  A level-3 open afterwards recovered all four at level 3, with the lanes
-  3.5.1's own reopen reports. In the first state, 3.5.1 writes level-2 data
-  into a level-2 store, which level 3 reads and converts.
-- **Rollback.** The ratchet is durable before the open reads a partition,
-  so a first level-3 open that then fails for another reason (a tail scan,
-  a manifest) also leaves the store at level 3, which 3.5.1 refuses. Rolling
-  back after the first start restores a snapshot of the store taken before
-  it, or re-syncs. SDN forwards TLV 31 as `SDN_F2_WRITE_FORMAT` for a host
-  held at level 2.
-- **Stats** (appended, entries 36–40): the store's level, `kFormatMax`, the
-  level this open raised STORE from (0: none; 1: STORE was torn inside a
-  ratchet this open finished, so its old level is unknown), lane
-  checkpoints cut, and their bytes.
-
-At level 3, manifest version 3 is the written version. Below level 3, v3 is
-written only past 65,535 segments (§40, deviation 38).
-
-### Lanes at level 3
-
-- **A batch carries only the lanes it changed.** That is its lane-delta
-  section: one 48 B LaneDelta per changed lane, counted by a u32 (deviation
-  40: this section is the design's `LANE_PAGE`, so no new ctl kind was
-  needed). The per-batch delta table is now indexed by lane id and has no
-  cap. It was 256, so a kill of a record with more than 256 tag instances
-  failed its batch for good.
-- **Up to 32 live lanes**, the head holds the table inline, as at level 2.
-- **The batch that takes a partition past 32** writes the table once as a
-  LANE_CKPT. In inline mode, staging stops before an entry once the batch
-  holds 64 lane deltas. An entry makes at most one lane live (a PUT or a
-  re-tag), so that table holds at most the live lanes plus 65, 97 lanes.
-- **From that batch on, the head names a LaneRef** (`nLanes` 0xFFFE,
-  48 bytes after the L0 directory): a base plus the batch position its
-  deltas replay from. The base is `lk-<gen>.fsl`, or the crossing
-  LANE_CKPT. The table is the base, plus the deltas of every batch from the
-  replay offset up to the head's `(mSeg, mEnd)`. Batches are walked by
-  their headers, and a SEAL moves to segment + 1.
-- **`lk-<gen:06x>.fsl`** is a 4 KiB header page (pid, gen, lane count,
-  `mintedThrough`, the cut position, CRC). Then come pages of up to 73
-  counters sorted by lane id, each page with a CRC. Count-0 lanes are
-  dropped. There is no size cap.
-- **Cuts.** A checkpoint is cut:
-  - after the crossing;
-  - when A9 wants to retire a meta segment at or above the ref's floor (its
-    replay segment, and a LANE_CKPT base's segment);
-  - once a fold would walk `laneCkptBatches` batches with lane deltas
-    (writer TLV 32, default 128), or four times that many batches in all.
-    A fold reads every batch it walks, and every `flatsql_lanes` statement
-    and every open folds, so this bounds their work. Batches without lane
-    deltas count a quarter, so the RETIRE and UNLINKED batches a cut itself
-    causes never make the next cut due.
-
-  The owner copies its live counters at a batch boundary (O(live lanes),
-  once per cut), and a maintenance helper writes and syncs the file
-  (deviation 41). The encoded file counts in the writer's committed memory
-  until it is written.
-- **Crash protocol**, as built:
-  1. The helper writes `lk-<g>` and syncs it. One cut is in flight per
-     partition, so g is always the ref's gen + 1.
-  2. The owner installs the ref and writes a DURABLE_CKPT head naming it.
-  3. Only once a durable head names it does a RETIRE list `lk-<g−1>`
-     (letter `L`), and A9 retire a meta segment below the new floor.
-  4. Open unlinks `lk-<gen + 1>`, a checkpoint no durable head names. An
-     `lk-<gen − 1>` whose RETIRE never committed goes after the open's
-     durable head.
-
-  No cut starts while a RETIRE that lists a replaced checkpoint has not
-  committed. Until it commits only the head names what open cleans up, so
-  the files on disk stay within `lk-<gen − 1>` to `lk-<gen + 1>`. Without
-  that wait, meta writes failing ENOSPC let the next cut install and a crash
-  left `lk-<gen − 2>` named by nothing, for good. Open also probes
-  `lk-<gen − 2>`.
-- **Torn heads.** Every batch that carries a RETIRE also carries the LaneRef
-  in force (ctl kind 13, LANE_REF). A torn-head rebuild from a later meta
-  segment folds the table from the last one.
-- **The RETIRE valve** reserves only what the batch's finalize step adds:
-  the LANE_REF in ref mode; in inline mode the table a crossing can write,
-  the live lanes plus 65; and the whole table at level 2, as before. With 32
-  or fewer live lanes the soft cap stays at 2,048 items, as at level 2.
-- **Readers** fold the same way (`LaneStore::laneCounters`) up to their
-  snapshot's head. A file retired since then answers SNAPSHOT_GONE.
-- **A level-2 head at a level-3 open.** A head that names a LANE_CKPT
-  becomes a LaneRef with that record as its base and the head position as
-  its replay offset. This holds because level 2 wrote a LANE_CKPT with every
-  batch that changed a lane past 32. A first checkpoint follows.
-- **In memory**, lanes are found by id through an index. It was a linear
-  search per delta at publish, replay and RECONCILE. Replay, readers and
-  checkpoints apply a delta by one rule (`laneApplyDelta`). A lane at count
-  0 carries no history: checkpoints and head tables drop it, so a delta that
-  makes it live again starts its counters afresh (`first_seen`, `max_pseq`,
-  `updated`). The writer's memory, a fold from any base and a replay then
-  agree whether or not a checkpoint dropped the lane. Before, a lane revived
-  after a checkpoint dropped it read its old `first_seen` until the next cut
-  and the new one after it, with no write in between.
-- **A failed batch that minted lanes** rolls `nextLaneId` back to the first
-  id it minted. The table is not in id order when l.fsl lost frames the
-  head still counts, and the old rule, the last lane's id + 1, could fall
-  below a live id.
-- **A LaneRef head in a store below level 3** (a partial snapshot restore)
-  quarantines that partition. It used to fail the whole open.
-
-### Live-only candidate caps (N2)
-
-Staging gathered at most a fixed number of postings per lookup and then
-dropped the dead ones. A key with more dead postings than the cap hid its
-live row:
-
-| Lookup | Old cap |
-|---|---|
-| supersede candidates | 8 |
-| CID candidates | 64 |
-| tag instances of one tuple | 64 |
-| live instances of a PUT | 256 |
-| licence and control supersedes | 8 |
-
-Only live rows count now. A key holds at most one live row of each kind:
-every PUT kills the live PUTs of its supersede keys whose CID differs, every
-control record every live row of its key, every licence the live licences
-of its key, and a CID is stored once per partition. A live control record
-is also older than any live PUT beside it. So a supersede or licence lookup
-ends at the key's newest live row, and a control record's at the live
-control record.
-
-The walk goes newest first through the postings' sources. The unmerged L0
-blocks and each segment's L1 runs hold disjoint, ascending pseq ranges,
-with every run below every block, so the sources are read from the newest,
-each one's postings sorted descending, and the walk stops at the end
-without reading older sources. Should the ranges not be in that order, all
-postings are gathered and sorted instead. A PUT of a hot key reads its
-newest version, not every dead version compaction has not dropped yet.
-CID and tag-instance lookups gather every posting and stop at the first
-live one. The lists grow outside the hot-path count.
-
-### Tests
-
-The tests are in `cpp/test/ps/lane_cap_test.cpp`. The Mac is an M3 Ultra
-with 28 cores, APFS, and the in-memory fault host, shared with other lanes
-(1-minute load 9–20 during the runs). Every crash sweep and trial checks,
-after each reopen, the lane table on disk against a recount from rows
-(count and bytes), and against the engine's own table in every counter
-field, for every live lane.
-
-| Test | Result |
-|---|---|
-| `lanecap_5000_live_lanes` | 5,000 lanes, then 500 re-tags into new lanes and 200 kills, all acked. The engine, `flatsql_lanes`, the on-disk fold and a recount from rows all agree (5,272 lanes); again after a reopen and 100 more lanes |
-| `lanecap_crash_trials_full` | 1,000 trials, 2 writers, helper-written checkpoints, file and journal mode, 114 s. Each crash lands after at least 5,000 live lanes: 160 left an unnamed checkpoint and 362 a replaced one pending. After every reopen the table equals a recount from rows and the engine's table, and no `lk` orphan is left. 0 failures |
-| `lanecap_ckpt_crash_every_op_full` | A crash at each of 2,912 mutating I/O calls of a workload that crosses 32 lanes, cuts 30 checkpoints, seals, and retires meta segments and replaced checkpoints. All five crash modes. Before open: 965 crashes left an unnamed checkpoint and 1,241 a replaced one pending. After open: lanes equal a recount and the engine's table, and the directory holds exactly the checkpoint the head names. 0 failures |
-| `lanecap_2000_lanes_retire_bearing` | 2,000 lanes with seals, merges, a coalescing SWAP, 97 files retired, 5 meta segments retired, 8 checkpoints: 0 batches refused, every lane correct |
-| `lanecap_batch_lane_bytes_proportional` | A batch that changes one lane writes 56 B of lane records at level 3, with 66 live lanes (host-02's largest partition) or 5,000. At level 2 the same batch writes 3,760 B at 66 lanes and 61,664 B at 1,100. At level 2, 1,180 lanes never ack |
-| `lanecap_no_cut_while_lk_retire_pending` | Meta writes fail ENOSPC for 300 steps: no cut starts while a RETIRE naming a replaced checkpoint waits (355 steps waited), and a crash then leaves exactly the named checkpoint after open. With the wait removed, 82 steps had a cut in flight |
-| `lanecap_install_head_nospace` | The head write naming a newly installed checkpoint fails ENOSPC (40 installs), then a crash in each of the five modes at four points after: every reopen agrees with the recount and the engine and keeps only the named checkpoint. 0 failures of 20 trials. Removing the replaced checkpoint's wait for a durable head is not caught here: this workload's checkpoint heads follow in the same step, and every RETIRE batch also carries the LaneRef in force |
-| `lanecap_fold_walk_bounded` | 1,500 one-lane batches on 100 lanes at the default cadence: a fold walks at most 128 batches (13 checkpoints); `flatsql_lanes` 0.3–1.0 ms |
-| `lanecap_revived_lane_counters_stable` | A lane killed to 0, dropped by a checkpoint and written again reads the same `first_seen` (the revival's) before the next cut, after it and after a reopen. Without the restart rule it flipped at the cut |
-| `lanecap_rollback_keeps_lane_ids_unique` | l.fsl loses 6 frames (the table is out of id order), a batch that minted a lane fails ENOSPC and retries: every lane id unique, the new lane's id past every live one. The old rule fails it |
-| `tb_supersede_candidate_cap`, `_autocompact` | 1 live version; 381 of 381 live. The old cap gives 12, and 392 of 381 |
-| `tb_supersede_hot_key_cost` | A CAT key with 400 versions among 19 static objects each, default compaction: its PUT costs 1.8x a new key's (618 vs 340 µs p50); 2.3x at 800 versions. Checking every dead version (the review's measurement: 12.8x at 800) fails it at 7.3x. What remains is the kill's TAG_OF prefix scan across every run, the same as 3.5.1's (TB12's prefix bloom) |
-| `lanecap_kill_record_with_300_instances` | A kill takes all 300 instances and lanes in one batch |
-| `lanecap_cid_candidates_past_64` | The 80th copy of a CID dedupes |
-| `lanecap_torn_heads_rebuild_from_lane_ref` | Both head slots torn: the table is rebuilt from LANE_REF |
-| `format_older_engine_refuses_ratcheted_store` | An engine built with `kFormatMax` 2 refuses a level-3 store, and this engine refuses a level-4 STORE; neither creates or changes a file |
-| `format_empty_registry_never_ratchets` | Opened three times, the empty level-2 store stays at 2; with a registration, the next open ratchets to 3 |
-| `format_ratchet_crash_every_io_call` | A crash at each of the ratcheting open's 13 mutating calls, in all five modes (65 trials). An engine built with `kFormatMax` 2 (this code with `testFormatMax` 2, not the released 3.5.1: see the table above) then opened the store 31 times and refused it 34 times, creating nothing when it refused. This engine then opens at level 3 with every record |
-| `format_ratchet_leftover_tmp_rules` | A STORE.tmp at 3 beside an intact STORE at 2: removed by a host pinned at 2 and by an engine whose `kFormatMax` is 2, which open at 2; finished by this engine (stats entry 38 says 2). One that differs from STORE in more than the format: removed. Beside a torn STORE: refused by the `kFormatMax`-2 engine with no file changed, finished by this one even pinned (entry 38 says 1) |
-| `format_ratchet_waits_on_a_full_device` | No room for STORE.tmp: the store opens at 2, as the level-2 open does, and the next open with room raises it |
-| `format_reader_store_rules` | A reader refuses a STORE at 4 beside a STORE.tmp at 3, reads a torn STORE through a STORE.tmp at 3, and refuses one through a STORE.tmp at 4 |
-| `format_fresh_store_at_write_format`, `format_manifest_v3_from_level_3`, `format_manifest_v3_on_swap` | Fresh stores at writeFormat. Manifests v3 from level 3 and v2 at level 2, from a merge and from a compaction SWAP |
-
-Mutations the checks catch: the old supersede cap (12 live, and 392 of
-381); checking every dead version (7.3x); no orphan cleanup at open; a cut
-while a replaced checkpoint's RETIRE waits; no restart of a revived lane;
-the old rollback rule; the old STORE.tmp rules in the writer and in
-readers; a ratchet that fails the open on a full device; the old cadence
-default.
-
-The native suite (118 fast tests), `crash_faults_T1_1_full` (10,000
-trials), `orphan_crash_points_during_compaction_T3_4_full` (2,501 trials),
-`fanout_randomized_vs_bruteforce_T2_2_full` (T2 #2) and
-`book_crash_every_op_full` (9,389 crash points) pass, 0 failures. In wasm32
-(wasi-sdk 30, the Node host, `scripts/ps-wasm-suite.mjs`) all 118 fast
-tests and `crash_faults_T1_1` with 1,000 trials pass. ThreadSanitizer
-reports nothing on the threaded `lanecap_` and `format_` tests, the
-supersede autocompaction test and the SWAP manifest test.
-
-Deviations:
-
-39. **The ratchet uses STORE.tmp and an in-place rewrite** (the design says
-    an atomic rename). The host I/O contract has seven imports and no
-    rename, and adding one would change every host. The three steps above
-    leave the old STORE, the new one, or a torn one that STORE.tmp repairs.
-    An engine that predates levels never misreads a ratcheted store. SDN
-    reads a torn STORE through STORE.tmp too (its `Migrated` and the update
-    guard), so neither the daemon's start nor the Apply/Rollback guard
-    stops short of the engine's repair.
-40. **No LANE_PAGE ctl kind.** The batch's lane-delta section already holds
-    exactly the changed lanes, and a u32 counts it.
-41. **The owner cuts the checkpoint from its in-memory table** (the design:
-    a helper streams the previous checkpoint plus the deltas since). The
-    writer holds every lane's counters until TB15b removes them. The copy
-    costs O(live lanes) once per cut (the review measured 0.055 ms at 5,000
-    lanes, 1.5 ms at 100,000 and 14 ms at 1,000,000), and the helper still
-    writes and syncs the file; the encoded bytes count in the writer's
-    committed memory until then. The copy equals a fold of the checkpoint
-    it replaces plus the deltas since because a lane at count 0 restarts
-    (above). TB15b switches the source when the writer stops holding the
-    table, before a partition can hold 10^5 lanes.
-
-Not built here:
-- A reader cache of folded tables. A reader folds at most 128 batches with
-  lane deltas (512 in all) per partition per `flatsql_lanes` statement.
-- `flatsql_lanes` still matches lanes to tuples in O(lanes²)
-  (`vtab_meta.cpp` `fillLanes`, the fan-out estimate): 15 ms per statement
-  at 5,000 lanes, 0.1 ms at 100. That is TB15a's (pushdown and a hash from
-  lane id to tuple); today's largest partition holds 66 lanes.
-- The LANE kind, the lane LRU and `flatsql_lanes` pushdown (TB15a, TB15b).
-- A kill's TAG_OF prefix scan still reads every run of the partition (the
-  cost left in `tb_supersede_hot_key_cost`); TB12's prefix bloom removes
-  it.