jonnify·persistence /echo-persistence/tigris+fence/log-head-recovery

Module 9 · Dive 9.3

Log-head recovery.

A fresh node with nothing on disk doesn’t download a database to come up. It reads the head object from the bucket to learn where the log ends, reads the commit chain and snapshot pointer to fix its position, and is then ready to serve — with zero pages loaded. Pages arrive lazily, faulted from segments only when something asks for them. Step the recovery, then fault a few pages.

§1

Read the head, fault the rest

interactive
Cold start from the remote. The node reads the head and chain from the bucket to become ready, then faults individual pages from segments on demand. “Ready” happens before any page is loaded. Step through, then fault pages.
cold node state: knows nothing head: ? pages resident: 0 / 8 Tigris · object storage head → LSN 8 snapshot ptr → LSN 5 segments/
step 0 · cold
step 0 · The node knows nothing. Step forward: it reads the head object (LSN 8), then the commit chain and snapshot pointer, and becomes ready — still 0 pages loaded. Then fault pages one at a time from segments.
§2

Why a cold node is ready in two reads { id="why" }

graft.design.md

The expensive thing in recovery is data; the cheap thing is knowing where you are. Log-head recovery separates them. To be correct, a node only needs the head — the latest commit object — and the snapshot pointer it descends from; both are tiny objects, so two reads make the node authoritative about the log’s end. It can then accept reads immediately, because a page it doesn’t hold is just a fault: find the segment that carries that page’s latest version (the rollup from Dive 9.1), fetch it, serve it, and keep it cached (the lazy Reader from Module 7). Nothing forces a full download — a node that only ever touches a hot working set only ever fetches that working set. This is what makes the remote a true floor rather than a backup: a brand-new replica, a restarted process, or a promoted standby all come up the same way, in two reads, and warm themselves on demand. It is the same fold the whole of Module 6 described, with its starting point — the head — read from the shared bucket. Chapter III is complete: one contract, two engines, one remote. Chapter IV turns to the platform around them.

§3

References & sources