Module wal 

Write-Ahead Log (WAL) file format.

Phase 4b introduces the .sqlrite-wal sidecar file. Writes don’t go to the main .sqlrite file anymore once the WAL is wired in (Phase 4c); instead they append frames to this log, and a periodic checkpoint (Phase 4d) applies frames back into the main file.

This module is the format layer — header, frame, codec, reader, writer. It doesn’t know anything about the Pager yet; that wiring is the next slice.

On-disk layout

  byte 0..32   WAL header
                  0..8    magic "SQLRWAL\0"
                  8..12   format version (u32 LE) = 1
                 12..16   page size     (u32 LE) = 4096
                 16..20   salt          (u32 LE) — random on create,
                                                   re-rolled per checkpoint
                 20..24   checkpoint seq (u32 LE) — bumps per checkpoint
                 24..32   reserved / zero

  byte 32..    sequence of frames, each `FRAME_SIZE` bytes:
                  0..4    page number           (u32 LE)
                  4..8    commit-page-count     (u32 LE)
                            0 = dirty frame (part of an open write)
                           >0 = commit frame; value = page count at commit
                  8..12   salt (u32 LE)         — copied from WAL header,
                                                   detects truncation / file swap
                 12..16   checksum (u32 LE)     — rolling sum over the
                                                   frame header bytes
                                                   [0..12] + the payload
                 16..16+PAGE_SIZE  page bytes

Checksum. A rolling rotate_left(1) + byte sum over the concatenation of the frame’s first 12 header bytes (page_num, commit-page-count, salt) and its PAGE_SIZE body. Catches bit flips and most multi-byte corruption without pulling in a dep. The 13th through 16th header bytes (the checksum field itself) are excluded from the computation, obviously.

Torn-write recovery. On open, the reader walks frames from the start and verifies each checksum. The first invalid or incomplete frame marks where the WAL effectively ends; anything past it is treated as if it doesn’t exist. Callers learn what’s committed vs what’s speculative from Wal::last_commit_offset / the is_commit flag of each scanned frame.

Structs

FrameHeader

Parsed per-frame header (everything but the page body).

Wal

WalHeader

Parsed WAL header. page_size is redundant with the engine’s compile- time constant; we persist it for forward-compat and reject anything that doesn’t match at open time.

Constants

FRAME_HEADER_SIZE

FRAME_SIZE

WAL_FORMAT_VERSION

WAL_HEADER_SIZE

WAL_MAGIC