server/paged_file library

Bounded page cache over a fixed-size-page file, with an undo journal for crash-safe commits.

This is the foundation of the engine's out-of-core storage layer: it lets a table that is much larger than RAM keep only a bounded set of hot pages resident, faulting cold pages in from disk on demand and evicting clean pages under LRU.

File layout

The data file is an integer multiple of pageSize bytes long. Page numbers are 0-indexed; page n lives at byte offset n * pageSize. There is no in-file header — higher layers (heap, btree) own their own metadata pages.

Crash safety (undo / rollback journal)

On the first dirty write of a transaction we open a sibling <path>.journal file and copy the original bytes of every page we are about to modify into it, fsyncing the journal before touching the data file. commit then writes the dirty pages into the data file, fsyncs it, and finally deletes the journal. The journal's presence on disk therefore means "the last transaction did not finish" — PagedFile.open replays it page-by-page to restore the pre-transaction image, then deletes it.

This is the same protocol SQLite uses for its rollback-journal mode and gives atomic, durable commits without depending on the OS for anything beyond fsync + rename.