Module header 

Page-0 file header — encode / decode.

The on-disk layout is described byte-by-byte in docs/format.md; this module is its reference implementation. Field offsets and sizes are encoded as const items rather than magic numbers in the function bodies so a reviewer can audit the layout against the spec at a glance.

At milestone M2 the header’s header_crc32c field is reserved (written as four zero bytes, not verified on read). Issue #6 wires the CRC32C algorithm; this module is structured so that change is a one-line edit to encode_header and decode_header.

Structs

FileHeader

In-memory representation of the page-0 file header.

Constants

FEATURE_FLAGS_KNOWN

Mask of all feature_flags bits this build understands. Any bit set in the on-disk header but NOT in this mask is rejected at open time with Error::InvalidFormat: an unknown flag might change how subsequent bytes are interpreted, and a reader that does not know what it means MUST refuse to guess.

FEATURE_FLAG_COMPRESSION

feature_flags bit indicating the file uses per-page LZ4 compression (Phase 3 issue #8). Set on creation by a Pager opened with Config::compression_mode = CompressionMode::Lz4.

FEATURE_FLAG_ENCRYPTION

feature_flags bit indicating the file uses per-page XChaCha20-Poly1305 encryption (Phase 4 issue #9). Set on creation by a Pager whose Config::encryption_key is Some(_). When this bit is set, every non-header page on disk is 4096 + 24 + 16 = 4136 bytes physical (ciphertext plus nonce plus Poly1305 tag), and the page-0 kdf_salt field (offset 72..104) carries the 32-byte HKDF-SHA256 salt used to derive the per-file page encryption key from the caller’s user key.

FORMAT_MAJOR

Format major version implemented by this build.

FORMAT_MINOR

Format minor version implemented by this build.

MAGIC

File magic. ASCII OBJF.

Functions

decode_header

Decode the page-0 header from the given page buffer. Validates magic, page-size, major version, the per-major format_minor constraint, and the header_crc32c field.

encode_header

Encode header into page. Power-of-ten Rule 5: invariants the caller is supposed to uphold are documented via debug_assert!.