Crate sqlite_core 

sqlite-core — native, read-only, panic-free SQLite file-format reader.

Parses the 100-byte file header (magic + page size), walks table b-trees (interior + leaf) yielding rows as typed Values, reassembles overflow-page chains for large payloads, walks the freelist (Database::freelist_pages), and applies a read-only -wal overlay (Database::open_with_wal) — all bounds-checked and panic-free on crafted input. Database::carve_cells recognizes record-shaped cells in free/unallocated space for the analyzer’s deleted-record recovery. The bespoke WalTimeline (Database::wal_timeline) models a -wal as a salt-bounded segment of materializable CommitSnapshots for “carve all snapshots”.

Format constants are consumed from forensicnomicon::sqlite (the KNOWLEDGE leaf) where exposed; a few not-yet-promoted offsets (reserved-space 20, in-header DB-size 28, freelist-count 36) are held locally and flagged for promotion. Still out of scope: index b-trees, WITHOUT ROWID tables, UTF-16 text, and WAL frame-checksum verification.

Structs

CarvedCell

A record-shaped cell recovered from unallocated / free space by Database::carve_cells. Carries the decoded row plus enough provenance for the analyzer to grade it as a “consistent with a deleted row” observation.

CellFragment

A partial deleted record salvaged from a freed-cell reconstruction that failed full-row validation: the maximal decodable column prefix at a structural anchor Database::reconstruct_freeblock_records already trusts.

ChainBreak

A freed overflow-page chain could not be followed to a complete, trustworthy payload (task #73): a chain page that is not a freelist leaf (live / trunk / unreachable), a cycle, a premature terminator with bytes still owed, an out-of-range page, or a declared payload exceeding the freelist’s capacity. Carries no detail by design — any break is a uniform “this chain is not recoverable as a Tier-1 row”, and the candidate degrades to a Tier-2 fragment.

CommitId

Address of a materializable database state: the replay of all valid frames up to a COMMIT frame. CommitId = (segment, commit_frame_index, db_size_after_commit).

CommitSnapshot

A materializable database state: the replay of all valid frames up to a COMMIT.

CommittedPageVersion

One page’s image at a particular CommitSnapshot.

Database

A read-only view over the raw bytes of a SQLite database file.

Header

Parsed 100-byte SQLite file header.

Row

One table row: its rowid plus decoded column values, in column order.

SpilledCell

A freed table-leaf cell whose declared payload spills onto an overflow-page chain (task #73). Recognized by [try_carve_spilled_cell_at] from the cell’s intact local prefix; the chain itself is resolved separately (Database::read_freed_overflow_chain) because that needs whole-database access. A SpilledCell is deliberately NOT a CarvedCell: until its chain is walked and validated it cannot masquerade as a recovered row (secure by design — the type system keeps an unresolved spill out of the full-row output).

WalDiff

A page-level delta between two materialized states.

WalFramePage

One committed WAL frame’s full page image plus its provenance, exposed by Database::wal_frame_pages so the deleted-record carver can scan the uncheckpointed WAL frames the main file does not yet reflect.

WalLsn

The salt-qualified log-sequence identity of a WAL position — the seam the future state-history-forensic [H] adapter maps onto LsnKind::SqliteWal.

WalResidue

A stale WAL tail surfaced for forensics — NOT committed history.

WalSegment

One salt epoch of a -wal file — a single bounded segment.

WalSegmentId

Identity of one salt epoch within a -wal file: its 0-based segment ordinal. A fresh segment begins at file start and after every checkpoint salt reset.

WalTimeline

The bespoke, format-exact temporal model of a -wal sidecar.

Enums

CohortTopology

Topology of the temporal cohort the WAL exposes — the shape the [H] adapter maps to state-history-forensic::CohortTopology.

Error

Errors that can arise while reading a SQLite database, all recoverable — the reader never panics on malformed input.

MaterializationSafety

Validation tier a WAL has cleared — strictly increasing assurance.

ResidueReason

Why a WAL tail is WalResidue (an invalidated-frame candidate), not history.

TextEncoding

Database text encoding (file-format §1.3, header byte 56). Determines how TEXT column bytes are decoded; a fixed property set at database creation.

Value

A single decoded column value from a table row. Mirrors SQLite’s storage classes.

WalValidationError

A WAL that cannot be admitted to the timeline at all (physical-validation hard stops). Distinct from “no committed snapshot”, which is a valid empty timeline.