Module page 

One page format for the whole file.

Layout, all little-endian: 0 magic u32 0x53454B32 4 version u16 6 kind u16 8 tree_id u16 10 nentries u16 12 page_no u32 its own number — proves this is the page asked for 16 free_ptr u16 lowest payload byte in use; payloads grow downward 18 format u16 THE DISK-FORMAT STAMP: FORMAT_VERSION, 2 on every page this build creates or rewrites. Zero in an e4 pre-release file, which is why a value other than 2 is refused rather than read. See docs/core/FORMAT_V2.md. 20 next_leaf u32 LEAF: right sibling. INTERIOR: leftmost child (child0). 0 = none. 24 lsn u64 RESERVED. Always 0 in Phase 1 — every production call site passes finalise(0). The field exists so the format need not change when it is wired up, and for no other reason. Two hazards attach to it, both real: (1) nothing may compare a page’s lsn against a WAL record’s to skip replay — log sequence numbers restart after a rotation unless the superblock’s floor is applied (see Task 4); (2) recovery may not use it to choose between two leaves claiming the same key — a bulk-packed page and an insert-built page both carry 0. A field documented as meaning something it does not is the same defect as a durability label that does not correspond to behaviour. 32 reserved2 u32 36 crc32c u32 over [0..36] ++ [40..PAGE_SIZE] 40 slot directory: (u16 offset, u16 len) per entry, growing forward … free space … payloads, growing backward from PAGE_SIZE

SACRIFICE (Law 4): 8 bytes of every page are identity and checksum, and every read pays a CRC over 4 KiB. Bought: no damaged page is ever decoded and served, and no page can be silently substituted for another.

Structs

PageMut

PageRef

Enums

PageKind

Constants

FORMAT_VERSION

The sekejap disk format, stamped into bytes 18-19 of every page.

HEADER_LEN

MAX_RECORD_LEN

The largest a leaf record (BTree’s key+value encoding, SLOT_LEN bytes of directory overhead included) can be and still fit an empty leaf. BTree::insert enforces exactly this bound; it is public so a caller that wants to reject an oversized record BEFORE doing anything consequential with it – Store::put logging it to the WAL, say – can check against the identical number instead of a second copy that could drift (Task 17 re-review, R1: a record the WAL logged and the tree then refused is exactly how a legitimate frame ended up sitting in the log with nothing there to apply it, which is not a case any reader should have to characterise after the fact).

PAGE_SIZE

Functions

checksum

Checksum over everything except the checksum field itself.

format_version

The disk-format stamp a page image carries, read straight from bytes 18-19. Public so a test, a repair tool or an inspector can ask what a page claims WITHOUT opening it – PageRef::open refuses anything but FORMAT_VERSION, so by then the answer is already known.

seal

Stamp the checksum over current contents. Called by the pool immediately before write_at, and nowhere else: checksummed going to the medium, verified coming back, in between it is just memory (DuckDB: block manager; SQLite: cksumvfs – both at the I/O boundary, never per pin). Stamp the publishing generation into the (formerly reserved) lsn field, then checksum. Called at the ONLY two places bytes leave for disk (flush_all, eviction), so every on-disk page carries the generation of the epoch that wrote it – the ordering signal recovery’s duplicate-key collapse needs once page numbers are recycled (2n). In-memory finalise(0) call sites are untouched: the stamp happens on the way out.