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 and WITHOUT ROWID tables. (UTF-16 text decoding and WAL frame-checksum verification are implemented.)

Modules

attribution

Best-effort, dependency-free attribution primitives that reconnect a carved deleted row to the live table it most plausibly belonged to.

rebuild

Pure-Rust writer that rebuilds a valid SQLite database file from carved deleted records (the inverse of the reader in crate).

row_history

Per-table, per-rowid VERSION HISTORY over a SQLite database’s WAL temporal model — the evidence-based “row history” (Phase 1 of the WAL-temporal work).

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.

JournalPageImage

One pre-transaction page image recovered from a rollback journal (design §5).

LiveTableDump

A live user table dumped for export: its name, the column header to present, and every live row in rowid order. Produced by Database::live_table_rows.

PriorSnapshot

A read-only, page-addressable image of the database AS IT WAS BEFORE the last transaction (design §4/§5). The temporal inverse of CommitSnapshot: prior[pgno] is the rollback-journal image where present, else the live main page. Diffing this against the current database yields the last transaction’s deletions (rowid present here, absent now) and modifications (present in both, values differ — the journal carries the OLD value).

RollbackJournal

A parsed rollback journal: its header tier plus the ordered, first-wins page images (design §3/§5). The temporal inverse of the WAL overlay — these images are the database as it was BEFORE the last transaction.

Row

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

SnapshotTable

One user table as of a CommitSnapshot — its schema parsed from the snapshot’s OWN materialized page 1, NOT from the live database. A rootpage can be dropped and reused by a different table across commits, so reading the schema from the snapshot is the only correct way to interpret its b-trees.

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.

JournalHeader

Parsed (or reconstructed) rollback-journal header (design §5).

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.

Functions

is_autoincrement

Whether create_sql declares an ordinary rowid table with an INTEGER PRIMARY KEY AUTOINCREMENT column — the only form for which SQLite maintains a monotonic sqlite_sequence high-water mark.