Module segment 

On-disk index segments.

Each segment is a set of files:

• seg-N.fst - an FST mapping each trigram (3 bytes) to a packed value holding the posting-list byte offset and its cardinality (see [pack_entry]), so query planning can pick the rarest trigrams without touching the postings blob
• seg-N.post - concatenated roaring bitmaps (posting lists) at those offsets
• seg-N.docs - postcard-encoded Vec<DocMeta> (one per document)
• seg-N.syms - postcard-encoded Vec<SymbolEntry>
• seg-N.refs - postcard-encoded Vec<RefEntry> (call sites + imports)
• seg-N.live - a roaring bitmap of live (non-tombstoned) doc IDs

The FST and postings blob are mmap’d for zero-copy, page-cache-backed reads. Doc and symbol tables are small relative to content and loaded into memory.

Every segment file carries an 8-byte xxh3 checksum footer, verified at open so silent corruption surfaces as Error::Corrupt (triggering the self-healing rebuild) instead of garbage results or a panic. The FST additionally has its own internal checksum.

Everything except the live bitmap is immutable once written, so the loaded tables and derived lookup maps live in an Arc<SegmentData> that a reloading searcher can share instead of re-parsing (see Segment::reopen).

Structs

DocMeta

Metadata for one indexed document.

RawRef

A reference before a document id is assigned.

RawSymbol

A symbol before a document id is assigned.

RefEntry

A structural reference (call site or import) extracted from a document.

Segment

A read-only, mmap-backed view of a segment: shared immutable data plus this open’s snapshot of the live bitmap (the only part that changes on disk).

SegmentData

The immutable, shareable portion of an opened segment: mmaps, decoded side tables, and the derived lookup structures. Wrapped in an Arc so a daemon reloading its searcher after an incremental index can reuse unchanged segments instead of re-parsing and re-deriving everything.

SegmentWriter

Accumulates documents and builds a segment on disk.

SymbolEntry

A symbol definition extracted from a document.

Enums

RefKind

The kind of a structural reference. Stored as a 1-byte enum (rather than a heap String) since refs are the most numerous index records; serializes to the same "call"/"import" tokens on disk.