Struct MappedBase 

pub struct MappedBase { /* private fields */ }

A read-only V8 snapshot backed by an mmap or owned bytes.

Small sections (IDS, SYMS, META, RULES_META, VIEWS) are CRC-checked on first access. Large sections (TOPOLOGY, COLUMNS, EDGE_PROPS, HNSW, PROVENANCE, IVF_STATE) skip automatic CRC; their rkyv accessors use rkyv::access_unchecked (O(1) root-pointer lookup, no full-section walk). Full integrity audit is available via mushroomdb verify.

Implementations

impl MappedBase

pub fn map(path: &Path) -> Result<Self>

Open and mmap a V8 snapshot file at path.

Validates the 4KB header (magic, version, section directory, whole-header CRC32). Per-section CRC validation is deferred until first access.

pub fn from_bytes(bytes: Vec<u8>) -> Result<Self>

Construct a MappedBase from an owned byte buffer (no file required).

Used when the Fs implementation returns bytes directly (e.g. the in-memory MemFs used in unit tests or the generic open_with(fs) path that only exposes Fs::read).

pub fn validate_section_bounds(&self) -> Result<()>

Check that every section listed in the directory fits within the backing buffer, and that the four large rkyv sections carry enough bytes for their rkyv root struct. Pure pointer arithmetic — no bytes are read, no CRCs are computed, and no page faults are triggered.

Used by restore_v8_base to detect truncated or corrupt snapshots eagerly at open time before the expensive section content reads are deferred.

The minimum-size check closes the gap between validate_section_bounds (which only verifies (offset, len) fit in the file) and the individual accessor checks in topology() / columns() / edge_props_section() / hnsw_section(). Without this check a crafted snapshot with len = 1 for the TOPOLOGY section would pass bounds validation and then panic inside topology().expect(...) on the first query. After this check all “bounds validated at open” expects become true post-validation invariants.

pub fn verify_integrity( &self, ) -> Vec<(u8, &'static str, usize, Result<(), String>)>

Validate the CRC32 of every section and check rkyv-accessible sections for structural integrity.

This is the on-demand integrity check exposed by mushroomdb verify. Large sections skip automatic CRC during normal operation; this method runs it explicitly.

Returns one entry per directory section: (section_id, section_name, bytes_checked, Ok(()) | Err(msg)).

pub fn topology(&self) -> Result<&ArchivedCsr>

Zero-copy access to the archived topology (CSR).

Uses rkyv::access_unchecked to avoid the O(section-size) pointer validation walk that rkyv::access performs. Section bounds are verified at open by validate_section_bounds; all CSR field accesses in seam.rs go through Rust bounds-checked slice indexing. File corruption is caught by mushroomdb verify (explicit full CRC32).

pub fn mixed_cache(&self) -> &MixedCache

The memo for this base’s Mixed columns.

Pair it with columns via ColumnsView::with_base_cached; the two always describe the same immutable mapping, so a memo can never outlive or mismatch its blobs.

pub fn columns(&self) -> Result<&ArchivedColumns>

Zero-copy access to the archived column store.

Uses rkyv::access_unchecked; see topology() for the full safety rationale. Per-field accesses in ColumnsView go through bounds-checked slice indexing and explicit length guards.

pub fn string_table(&self) -> Option<Result<&ArchivedStringTable>>

Zero-copy access to the shared string table (section 12).

None when the snapshot predates the shared section (pre-V9): every ColumnData::Str carries its own copy and that copy is authoritative. Some(Err(..)) only when the section is present but unreadable, which must not be silently treated as “absent” — that would hand the caller the empty per-column tables a V9 snapshot writes and lose every string.

Uses rkyv::access_unchecked; see topology() for the full safety rationale. Reads in ColumnsView/archived_to_columnstore are bounds-checked against the returned slice.

pub fn ids(&self) -> Result<&ArchivedIdMap>

Zero-copy access to the archived id map.

pub fn syms(&self) -> Result<&ArchivedInterner>

Zero-copy access to the archived symbol interner.

pub fn meta_bytes(&self) -> Result<&[u8]>

Raw bytes for the bincode meta section.

pub fn edge_props_section(&self) -> Result<&ArchivedEdgeProps>

Zero-copy access to the archived edge properties (section 5).

Uses rkyv::access_unchecked; see topology() for the full safety rationale. Per-edge property reads in EdgePropsView go through bounds-checked slice indexing.

pub fn hnsw_section(&self) -> Result<&ArchivedHnsw>

Zero-copy access to the archived HNSW section (section 6).

Uses rkyv::access_unchecked; see topology() for the full safety rationale. Called once at first-use to load HNSW state into the engine.

pub fn validate_hot_sections(&self) -> Result<()>

Structurally validate the sections that the hot path reads via access_unchecked (topology, columns, edge_props, hnsw, and — from V9 on — the shared string table), using rkyv’s checked access (bytecheck). This walks every relative pointer and rejects out-of-bounds / malformed archives — the defense the hot path deliberately skips for speed.

Unlike CRC32 (which an attacker who controls the bytes can recompute), this catches a maliciously crafted snapshot whose pointers would otherwise trigger UB in access_unchecked. It is O(section size) and touches every page, so it is intended for a pre-flight check (mushroomdb verify), not the per-query read path. Returns the first section that fails to validate.

pub fn rules_meta_section(&self) -> Result<&ArchivedRulesMeta>

Zero-copy access to the archived rules meta (section 8).

pub fn views_section(&self) -> Result<&ArchivedViews>

Zero-copy access to the archived views (section 9).

pub fn ivf_bytes(&self) -> Result<&[u8]>

Raw bytes for the IVF-state section (section 10).

The caller retains these bytes without decoding until first use. Returns Ok(&[]) when the section is absent from the directory (pre-T5 stores migrated from V5–V7 have no IVF section; treat as empty). Any other error (truncation, CRC mismatch) is propagated so that torn writes are detected rather than silently returning an empty map.

pub fn last_change_bytes(&self) -> Result<&[u8]>

Raw bytes for the last-change section (section 11).

Returns Ok(&[]) when the section is absent from the directory (pre-Task-3 snapshots have no LAST_CHANGE section; treat as empty map). Any other error (truncation, CRC mismatch) is propagated.

pub fn edge_props_raw_bytes(&self) -> Result<&[u8]>

Raw bytes for the edge-props section (section 5). Used for byte-identical passthrough when the overlay has no changes.

pub fn provenance_raw_bytes(&self) -> Result<&[u8]>

Raw bytes for the provenance section (section 7). Retained without decoding until first provenance access.