Enum IntegrityFailure 

#[non_exhaustive]
pub enum IntegrityFailure {
    ChecksumMismatch {
        page_id: u64,
    },
    OrphanPage {
        page_id: u64,
    },
    OrphanIndexEntry {
        collection: String,
        index: String,
        id: u64,
    },
    MissingIndexEntry {
        collection: String,
        index: String,
        id: u64,
    },
    BTreeSortViolation {
        page_id: u64,
    },
    BTreeSiblingChainBroken {
        tree: String,
        page_id: u64,
    },
    BTreeDepthExceeded {
        tree: String,
        limit: usize,
    },
    BTreeLevelInvariantViolated {
        tree: String,
        page_id: u64,
    },
    DanglingCatalogPointer {
        collection: String,
        index: Option<String>,
        page_id: u64,
    },
    FreelistChainBroken {
        page_id: u64,
    },
}

Categorical reasons an integrity walk records a failure. Every variant carries the locus of the problem (page id, collection, index name, document id) so an operator can root-cause without re-running the check.

The integrity walker accumulates a Vec<IntegrityFailure> and returns it inside an IntegrityReport — every failure here is recoverable in the sense that the check completed; the caller decides whether to repair the file or refuse to open it. I/O failures during the walk surface as an outer Result::Err instead (the walk could not finish).

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

ChecksumMismatch

A page’s CRC32C trailer did not verify. The page-id is the locus; page 0 would be a header CRC failure (the file header carries its own CRC, not a page trailer — this variant is emitted for any page whose trailer fails the per-page integrity check).

Fields

page_id: u64

Page where the corruption was detected.

OrphanPage

A page in 1..page_count is not reachable from any root the walker recognises (catalog, freelist, any primary or index B-tree). Indicates either a leaked page (allocated, never linked) or a corrupted root pointer somewhere upstream.

Fields

page_id: u64

The unreferenced page id.

OrphanIndexEntry

An index B-tree entry references a primary id that does NOT exist in the collection’s primary B-tree. Indicates the index is out-of-sync (likely a partial write that survived recovery, or a forensic mutation outside obj).

Fields

collection: String

Owning collection name.

index: String

Owning index name.

id: u64

Primary id the index entry pointed at.

MissingIndexEntry

A primary B-tree entry has no matching entry in one of the collection’s Active indexes. The walker checks the per-index (id-suffix-or-value → at-least-one-entry) invariant; an Each index with an empty sequence is NOT reported (legal: the doc contributes no keys). For Standard / Unique / Composite the absence of any matching entry is a violation.

Fields

collection: String

Owning collection name.

index: String

Owning index name.

id: u64

Primary id with no matching index entry.

BTreeSortViolation

A B+tree node failed the sort invariant: a key was followed by a strictly-lesser-or-equal key inside the same node.

Fields

page_id: u64

Page where the violation was detected.

BTreeSiblingChainBroken

A B+tree’s child-pointer graph contains a cycle — the same page is reachable as the child of two distinct ancestors (or of itself). The tree field names the containing B-tree by a human-readable label ("catalog", "primary:<collection>", "index:<collection>.<index>").

Historically this variant also covered leaf next_sibling chain breakage; the chain check was removed in M11 because CoW deliberately leaves left-neighbour next_sibling pointers stale (see crates/obj-core/src/btree/range.rs lines 16-31). The variant name is preserved for compatibility — it now signals only the descent-graph cycle path.

Fields

tree: String

Label identifying which B-tree the violation surfaced on.

page_id: u64

Page where the cycle was detected.

BTreeDepthExceeded

A B+tree’s depth exceeded crate::btree::MAX_BTREE_DEPTH. Indicates a runaway tree shape — by construction the obj writer cannot produce one; surfacing here means the file was mutated outside obj.

Fields

tree: String

Label identifying which B-tree tripped the depth bound.

limit: usize

The bound that was exceeded.

BTreeLevelInvariantViolated

A B+tree node’s level value was inconsistent with its kind — leaves must be level 0, internals strictly positive, and the level must decrease by exactly 1 when descending from an internal node to its child.

Fields

tree: String

Label identifying the B-tree.

page_id: u64

Page where the violation was detected.

DanglingCatalogPointer

A CollectionDescriptor carried a primary_root or IndexDescriptor.root_page_id that does not point at a page id in 1..page_count — the catalog references a page the file does not contain.

Fields

collection: String

Owning collection name.

index: Option<String>

Optional index name when the dangling pointer is on an index descriptor; None when it is the primary_root itself.

page_id: u64

The out-of-range page id.

FreelistChainBroken

The freelist chain was broken — a next link pointed at a non-freelist page (or a freelist page failed to decode), at a page id past page_count, or the chain looped.

Fields

page_id: u64

Page id where the broken link was detected.

Trait Implementations

impl Clone for IntegrityFailure

fn clone(&self) -> IntegrityFailure

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for IntegrityFailure

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq for IntegrityFailure

fn eq(&self, other: &IntegrityFailure) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for IntegrityFailure

impl StructuralPartialEq for IntegrityFailure