jonnify·persistence /echo-persistence/mvcc-time-travel/checkout-and-gc

Module 5 · Dive 5.3

Checkout & GC.

Each LSN named a root, so opening the Volume at any LSN is just picking that root — checkout-at-LSN, the move behind the change feed and replica catch-up. But kept versions accumulate, so a retention policy reclaims old roots. The one rule garbage collection must obey: never reclaim a version a reader still pins. Scrub to a version, pin one, then run GC.

§1

Open any LSN; keep what’s pinned

interactive
Version timeline. Six committed roots by LSN. Scrub to check one out (open it); pin it to protect it; then run GC — versions older than the retention window are reclaimed, unless a pin holds them.
retention: keep last 3 →
readout · Scrub to open a version — you read the root that was current at that LSN. Pin one to stand in for a live reader, then run GC: the old, unpinned roots are reclaimed; the pinned one is kept no matter its age.
§2

Why GC follows the pins

graft.design.md

Checkout is free for the reason Dive 5.1 gave: the root and its nodes are still in the pool. Retention is the counterweight — without it the diffs pile up forever — so GC reclaims nodes that no retained or pinned version can reach, the on-disk job compaction (Dive 4.3) actually performs. The safety rule is the whole point: a reader pinned at an old LSN keeps that root and everything it reaches alive, so GC computes liveness from the active pins plus the retention window, never from age alone. Reclaim a pinned version and a reader would fault on a missing page; respect the pins and time travel stays sound. This is the machinery the change feed and replica catch-up sit directly on top of — and where Chapter III picks up, with the engines that turn these roots into replicated pages.

§3

References & sources