test(depot): add branch history snapshot helper for exact retention assertions

[NathanFlurry]

No description provided.

[NathanFlurry]

Stack for rivet-dev/rivet

• docs(depot): add high-level depot SQLite overview, consolidate docs #5224 sxlkwqvz · 2026-06-11 21:13:04
• feat(depot): materialize capped database forks on bucket fork access #5223 uouzzvly · 2026-06-11 21:13:03
• fix(depot): teach doctor to diagnose reclaimed history via shard-seeded replay #5222 ulwkqwsz · 2026-06-11 21:13:02
• feat(depot): watermark-aligned delta reclaim and retention engine #5221 mkqlmnty · 2026-06-11 21:13:00
• test(depot): add branch history snapshot helper for exact retention assertions #5220 tlrrrnmu · 2026-06-11 21:12:58 👈
• main

Get stack: forklift get 5220
Push local edits: forklift submit
Merge when ready: forklift merge 5220

[railway-app]

🚅 Deployed to the rivet-pr-5220 environment in rivet-frontend

Service	Status	Web	Updated (UTC)
website	😴 Sleeping (View Logs)	Web	Jun 14, 2026 at 7:46 am
kitchen-sink	❌ Build Failed (View Logs)	Web	Jun 11, 2026 at 9:19 pm
frontend-inspector	❌ Build Failed (View Logs)	Web	Jun 11, 2026 at 9:15 pm
frontend-cloud	❌ Build Failed (View Logs)	Web	Jun 11, 2026 at 9:15 pm
ladle	❌ Build Failed (View Logs)	Web	Jun 11, 2026 at 9:14 pm
mcp-hub	✅ Success (View Logs)	Web	Jun 11, 2026 at 9:14 pm

[claude]

Code Review

Overview

This PR adds a BranchHistorySnapshot utility for asserting exact stored-history state of a database branch in tests — capturing delta txids, commits, VTX, PIDX, SHARD versions, PITR intervals, and DB pins in a single snapshot transaction. It also adds typed assertion helpers in tests/common/mod.rs and a self-contained smoke test.

The design is sound: using a snapshot-isolation transaction ensures partial deletes cannot hide behind in-process caches, and BTreeMap/BTreeSet provide stable ordering for deterministic assertions.

---

Issues

1. Redundant prefix computation inside loops (minor / performance)

In branch_history_snapshot_tx, the VTX, PIDX, and SHARD loops each call the prefix constructor twice: once as the scan_prefix argument and once inside the loop body for strip_prefix. Since these functions each allocate a new Vec<u8>, this allocates N+1 vecs per row set instead of 1. The fix is to hoist the prefix before the loop:

// Before (VTX loop):
for (key, value) in scan_prefix(tx, &keys::branch_vtx_prefix(branch_id)).await? {
    let prefix = keys::branch_vtx_prefix(branch_id); // re-allocated per entry
    ...
}

// After:
let vtx_prefix = keys::branch_vtx_prefix(branch_id);
for (key, value) in scan_prefix(tx, &vtx_prefix).await? {
    let suffix = key.strip_prefix(vtx_prefix.as_slice())...;
    ...
}

The same applies to the PIDX and SHARD loops.

2. history_snapshot is unconditionally compiled into production builds

The module doc says "Tests and tooling use this." Compare to fault, which is gated under #[cfg(feature = "test-faults")]. Consider #[cfg(any(test, feature = "test-helpers"))] or a dedicated feature so this scaffolding does not ship in production binaries.

---

Nits

3. Misleading comment on delta_chunk_rows assertion

// Two single-chunk deltas plus one for the far page commit.
assert_eq!(snapshot.delta_chunk_rows, 3);

All three commits produce single-chunk deltas; the comment implies only two are. Clearer: "Three commits, each producing one delta chunk row."

4. Assertion helpers repeat the same collect boilerplate five times

expected.into_iter().collect::<std::collections::BTreeSet<_>>() appears in five helpers. A small macro would reduce this, though at five sites it is a style nit.

---

What looks good

• Key layout parsing is correct: VTX (16 bytes), PIDX (4 bytes u32 BE), SHARD (4+1+8 with / at offset 4) all match the corresponding key constructors in keys.rs.
• Using Snapshot isolation for all reads in one transaction is the right approach.
• The branch_history_snapshot_tx variant lets callers compose the snapshot into a larger transaction.
• The test verifies PIDX ownership correctly: page 2 maps to txid 2, not txid 1 — the subtlety most likely to regress after compaction changes.
• No assertion helpers for PITR intervals or pins yet — that seems intentional; worth adding when compaction tests land.