Crate sqlite_core

Expand description

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), including the page-1 header field offsets (reserved-space 20, in-header DB-size 28, freelist-count 36, text-encoding 56) promoted there in §3.1. Index-b-tree LEAF reading is a foundation (Database::index_leaf_cells, roadmap §1.4) — the second substrate for a table’s data and the storage of WITHOUT ROWID rows; carving DELETED index entries and following index-key overflow remain follow-ups. (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.
LocalStorageValue: A WebKit/Chrome Local Storage ItemTable.value decoded to text, plus whether the decode was lossy. lossy is a struct field, not a side-channel warning, so a caller cannot render a lossy value as if it were faithfully recovered (secure by design).
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.
WithoutRowidTable: A WITHOUT ROWID user table’s live rows, produced by Database::without_rowid_table_rows. Such a table’s data lives entirely in an index b-tree (there is no rowid), so rows holds the decoded index records in the table’s declared column order, in index (primary-key) order.

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.
PageBytes: A page image handed back by the byte source: a slice borrowed from an in-memory buffer, or a reference-counted page from the paged LRU cache. Derefs to [u8] so callers treat it as a page slice regardless of origin.
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§

decode_localstorage_value: Decode a WebKit/Chromium Local Storage ItemTable.value BLOB to a String.
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.
is_local_storage_item_table: Recognize the WebKit/Chromium Local Storage ItemTable(key TEXT, value BLOB) table, so a caller knows when decode_localstorage_value applies to a dumped table’s value column.