Struct MmapUrnaFile 

pub struct MmapUrnaFile { /* private fields */ }

Implementations

impl MmapUrnaFile

pub fn has_blob_data(&self) -> bool

Whether this file carries its media bytes inline (0x17 present).

pub fn blob_bytes(&self, index: usize) -> Result<&[u8], RuntimeError>

Slice blob index’s bytes lazily off the mmap. Errors typed: no 0x17 section, an out-of-range index, or a record that is not inlined (its table entry is the (0, 0) gap).

impl MmapUrnaFile

pub fn canonical_texts(&self) -> Result<Vec<String>, RuntimeError>

Decode the stored canonical text for every chunk, in file order. this is the TIER-1 citation text, the same bytes urna cite returns, NOT the original source bytes. re-parses the mmap and decodes the chunks_canonical (0x02) section (handles zstd / txt_streams / dict / fsst transparently). used by the agent-native retrieve() to attach cited text to each hit.

pub fn chunk_ids(&self) -> &[String]

The per-chunk ids in file order, parallel to canonical_texts(). lets a caller build a chunk_id -> canonical-text map without re-reading the file (the ids are already decoded and held at open time).

pub fn inspect_json(&self) -> Result<String, RuntimeError>

Re-parse the mmap and return a JSON document mirroring urna inspect: header fields, section table entries, manifest, hashes, and the runtime SIMD backend.

impl MmapUrnaFile

pub fn madvise_cold(&self)

Hint to the OS that the mmap pages won’t be needed soon. The next read will fault them back in from disk.

Caveat: this is posix_madvise(MADV_DONTNEED) - an approximation of cold cache, NOT a guarantee. The OS may ignore the hint, keep pages around for prefetch, or return them from the kernel’s page cache anyway. Use it for “madvise-cold” benchmarks (a useful upper bound on the warm case) but don’t claim it’s equivalent to a fresh boot. Real cold-cache benchmarks need purge (macOS) or echo 3 > /proc/sys/vm/drop_caches (Linux), both of which require privileged operations.

impl MmapUrnaFile

pub fn open(path: &Path) -> Result<Self, RuntimeError>

pub fn embedding_dim(&self) -> usize

pub fn n_embeddings(&self) -> usize

pub fn dtype(&self) -> DType

pub fn file_hash(&self) -> &str

pub fn content_hash(&self) -> &str

pub fn simd_backend(&self) -> SimdBackend

pub fn declared_index_type(&self) -> &str

pub fn model_hash(&self) -> &str

Manifest model_hash (the model fingerprint the corpus was built with). Callers embed the query with their own model and compare.

pub fn declared_score_type(&self) -> &str

pub fn has_ann(&self) -> bool

pub fn ann_ef_floor(&self) -> Option<usize>

the hnsw beam floor (the file’s ef_construction, 400 for python builds): search_ann(_, _, ef) searches max(ef, k, floor) candidates, so an ef below the floor changes nothing. None without an hnsw section.

pub fn has_bm25(&self) -> bool

pub fn has_graph(&self) -> bool

pub fn has_blobs(&self) -> bool

pub fn blob_refs(&self) -> Option<&[BlobRefRecord]>

The blob_refs (0x14) table, when the file declares blobs_present: content-hash references to the source media blobs, in table order (the overlay’s blob_ref_index addresses this slice).

pub fn has_spaces(&self) -> bool

pub fn space_names(&self) -> Vec<&str>

Names of the multimodal spaces listed in the space_table (empty when the file has no supports_multimodal capability).

pub fn revalidate(&self) -> Result<(), RuntimeError>

Re-run all reader-side validation. The file was already validated at open() time, but callers can invoke this explicitly to detect tampering after the fact (e.g. the mmap pages got swapped under the runtime).

impl MmapUrnaFile

pub fn search( &self, query: &[f32], k: i32, ) -> Result<SearchResult, RuntimeError>

Exact flat search. The recall=1.0 ground truth.

pub fn search_ann( &self, query: &[f32], k: i32, ef_search: usize, ) -> Result<SearchResult, RuntimeError>

ANN search. Pulls max(ef_search, k, ann_ef_floor) candidates from HNSW (the file’s ef_construction is the floor a caller cannot go under), reranks with the exact dot product, returns top-k. Falls back to search() if no ANN section is present.

pub fn search_graph( &self, query: &[f32], k: i32, hops: usize, ef: usize, ) -> Result<SearchResult, RuntimeError>

Graph search: seed from the exact-cosine top-ef, expand a bounded bfs over the chunk-to-chunk csr, union seed + frontier, then run the SAME mandatory exact rerank on the union. the graph ONLY generates candidates; the returned score is real cosine, identical contract to search_ann. falls back to search() when no graph section is present. recall stays f32::NAN (we never lie).

pub fn search_hybrid( &self, query_vec: &[f32], query_text: &str, k: i32, candidates_per_path: usize, ) -> Result<SearchResult, RuntimeError>

Hybrid search: BM25 candidates ∪ ANN (or exact) candidates, reciprocal-rank fusion, then exact cosine rerank on the union. Final score is the real cosine.

pub fn search_routed( &self, query: &[f32], query_text: Option<&str>, k: i32, candidates: usize, ) -> Result<SearchResult, RuntimeError>

Route by what the file carries, the one order ask, retrieve and search-text share: hybrid when a BM25 section is present and the caller has the query text, hnsw when an HNSW section is present, exact otherwise. the manifest’s index_type names the vector index only; the lexical index is the supports_bm25 capability, so a file built with the hybrid preset (index_type = "hnsw", a BM25 section) takes the hybrid route here. the graph is never routed to automatically; search_graph is its entry point. candidates is the hnsw beam, or the per-path shortlist size on the hybrid route.

impl MmapUrnaFile

pub fn search_space( &self, name: &str, query: &[f32], k: i32, expected_model_hash: Option<&str>, ) -> Result<SearchResult, RuntimeError>

Exact flat search over one named multimodal space (e.g. “vision”). the query must be embedded with the model the space’s model_hash fingerprints and have the space’s dim; both are checked up front (the per-space honesty gate), so a text-tower query fails loudly instead of silently scoring the vision band. recall is 1.0: this is the exact ground truth over that space.