zrocks — Project Report

The goal & what was built

The whole project is the migration: re-implement RocksDB as a pure-Zig 0.16 LSM key-value engine, built bottom-up under strict TDD, and finish by making byte-exact RocksDB the only on-disk format zrocks emits — proven by having a real librocksdb v11.4.0 binary open zrocks's flush, compaction, range-delete and WAL output through a verify_open oracle.

The result is a working, durable, crash-recoverable, leveled-compacting LSM store with a CLI: foundation (slice/status/coding/comparator/arena/CRC32C/options) → Env over std.Io → WAL · skiplist · memtable · WriteBatch → block-based SST (builder/reader, bloom, footer) → LRU cache → iterators → VersionEdit/VersionSet/MANIFEST → recovery → flush + leveled/universal/FIFO compaction → snapshots → column families, merge operator, prefix seek, compaction filter, range delete, transactions, checkpoints → then the format migration to byte-exact RocksDB.

Timeline

Times are CEST. Blue = core engine build (Phases 0–7); violet = RocksDB-only format migration.

• 05-28 08:15  Phase 0 — Foundation: build/harness, Slice/Status, coding (varint+fixed), comparator, arena, options, CRC32C (M0.0–M0.6).
• 05-28 08:32  Phase 1 — Environment: Env over std.Io + MemEnv (M1.0).
• 05-28 08:43  Phase 2 — Write durability core: InternalKey, WriteBatch, WAL, skiplist, memtable (M2.0–M2.4).
• 05-28 09:06  Phase 3 — Block-based SST: block builder/reader, bloom + filter block, footer, TableBuilder/Reader, LRU cache (M3.0–M3.5).
• 05-28 09:41  Phase 4 — Iterators & in-memory DB: merging/two-level iterators, Put/Get/Delete/Write/iter (M4.0–M4.1).
• 05-28 18:09  Phase 5 — Persistence: VersionEdit, VersionSet/MANIFEST, recovery + durable open (M5.0–M5.2).
• 05-28 18:50  Phase 6 — Compaction → embedded KV store: SST read path, flush, leveled compaction, snapshots + CLI. GATE: LevelDB-equivalent core (M6.0–M6.3).
• 05-28 22:09  Phase 7 — RocksDB extensions: column families, merge operator, prefix bloom/seek, universal+FIFO, compaction filter, DeleteRange, transactions, checkpoints (M7.0–M7.7). READ-interop with real RocksDB v11.4.0 + Chromium LevelDB.
• 05-29 16:26  Migration — interop tooling: real RocksDB v11.4.0 fixture + built-from-source oracle; verify_open widened to point-Get + Seek/range-scan + absent-key.
• 05-29 20:04 → 23:52  RocksDB-only migration (8 branches): properties-always → SST-default-flip → manifest-rocksdb-exact (kNewFile4 tag 103 + seqnos) → filter-rocksdb-only (FastLocalBloom) → range-del-rocksdb → partitioned-index-drop → remove-native-and-tests. Native/clean formats deleted.
• 05-30 10:46  Done — "End of Opus 4.8 run." Directive fulfilled: byte-exact RocksDB is the only format. Part II below dissects this final phase.

Token usage

Across all 125 transcripts (1 main session + 3 helper sessions + 121 subagent/workflow runs). Cache reads dominate because every agent turn re-reads its cached context cheaply; the real generation cost is the output column. "Total" sums input+output+cache-create+cache-read.

By day

Day 1 (28th) built the entire Phases 0–7 core; day 2 (29th) drove the most tool-heavy work — read-interop tooling plus the RocksDB-only migration.

Tool usage

Tool failure analysis

128 errored tool results out of 6,383 — an overall 2.0% failure rate. Breakdown by tool and by cause below.

What the failures actually were

• StructuredOutput (40, the biggest bucket) — workflow agents whose first JSON didn't satisfy the required schema, e.g. must have required property 'verdict_note' / 'already_rocksdb_exact'. These are self-correcting retries: the harness rejects the output and the agent re-emits a valid object. No work was lost; they inflate the count without being real failures.
• EnterWorktree (4, 100%) — a subagent tried to call EnterWorktree while already running with a cwd/worktree override: "cannot be called from a subagent with a cwd override." A harness guardrail, not a code bug; the orchestrator owns worktree creation.
• Bash (65, ~2%) — dominated by expected failures: zig build test exiting non-zero on the red step of red→green TDD, plus a handful of cat on a not-yet-existing MEMORY.md and two transient "claude-opus-4-7 is temporarily unavailable" auto-permission stalls.
• Edit (15, ~1.4%) — "File has been modified since read… Read it again" and "Found 2 matches… set replace_all." Standard edit-contract hiccups, immediately retried.
• Read / Write (3) — one EISDIR (read a directory as a file), one missing file, one write-before-read. All recovered on the next call.

Process: TDD cadence & orchestration

Headline numbers

Token total = design workflow (1,581,977) + execute workflow (1,071,431). Wall clock (5h 14m) < workflow CPU time (5h 19m) because the design phase had agents running in parallel.

Two-phase structure

Phase 1 fanned out 9 design agents (one per format component) and 9 adversarial verifiers in parallel, then a single synthesizer produced the sequenced plan (28 min, 183 k tokens by itself). Phase 2 ran the 9 plan milestones sequentially on the shared repo (each had to commit before the next started, because they all touch src/format/ and src/db/).

Per-milestone breakdown (execution phase)

Oracle column = result of /home/ghpu/rocksdb-interop/verify_open <db> on the milestone’s gate fixture (a full flush+compaction+range-del+WAL DB). Intermediate dips to 5 / 8 are expected — each step proves its own component opens in isolation while later steps still emit native formats for the others. The final 34 means the final fixture is richer (more keys + multi-level + tombstones) and reads end-to-end.

17 files changed
+1,320 insertions
-1,810 deletions
net −490 LoC
21 commits to main

Failure analysis (migration)

The migration completed with 0 retries and 0 quarantined milestones. Every one of the 28 subagents finished on its first attempt; every one of the 9 execute milestones merged to main. The execute workflow’s pre-commit gate (full zig build test + the real-RocksDB verify_open oracle) was the safety net that made retries unnecessary — an agent that broke the gate would have been quarantined and its dependents skipped, but none did.

What the migration deleted

• Options.sst_output enum + field (forced single output format)
• Native single-level SST index path (write side)
• Two-level partitioned SST index (src/format/partitioned_index.zig, 373 LoC + 3 tests + Options.IndexType)
• Block-based-bloom write path (read path retained for LevelDB interop)
• Bespoke range-tombstone serialization (replaced by rocksdb.range_del)
• kColumnFamilyTag=0x10 WAL prefix (replaced by RocksDB CF value-type bytes)
• Per-CF MANIFEST snapshot path emitting legacy kNewFile=7

Evidence on disk (post-migration)

$ zrocks /tmp/demo put keyN value-from-zrocks-N   # via the zrocks CLI
$ ls /tmp/demo
000002.log  CURRENT  MANIFEST-000003

$ /home/ghpu/rocksdb-interop/verify_open /tmp/demo   # the REAL librocksdb binary
OPEN_OK count=10
key0=value-from-zrocks-0
…
key9=value-from-zrocks-9

Plus the CI self-consistency gate tests/rocksdb_write_interop_test.zig, which on every zig build test asserts on the raw bytes that footer is format_version=5 / crc32c, metaindex carries rocksdb.properties, and MANIFEST uses kNewFile4 with no stray kColumnFamilyAdd.