Struct UrnaFileBuilder 

pub struct UrnaFileBuilder { /* private fields */ }

High-level builder. Accepts canonical chunks plus an optional provenance blob. Computes chunk_ids, lays out the file, writes deterministic bytes.

Implementations

impl UrnaFileBuilder

pub fn build_bytes(self) -> Result<Vec<u8>>

Build the file in memory. Pure computation - no I/O.

impl UrnaFileBuilder

pub fn new(manifest: Manifest) -> Self

pub fn add_chunk(self, c: ChunkInput) -> Self

pub fn add_chunks<I: IntoIterator<Item = ChunkInput>>(self, chunks: I) -> Self

pub fn with_provenance(self, v: Value) -> Self

pub fn reproducible(self, on: bool) -> Self

Reproducible build mode. When enabled, the writer overrides the manifest’s created timestamp to REPRODUCIBLE_CREATED so that two builds with identical inputs produce byte-identical output. Provenance JSON is not rewritten - callers are responsible for keeping provenance deterministic if they want bit-for-bit equality.

pub fn text_encoding(self, enc: SectionEncoding) -> Self

Encoding for text-heavy sections (chunks_canonical, original_spans, provenance, search_contract). Zstd shrinks PT-BR text by ~3-5× in practice. chunk_ids stays raw because it is high-entropy and almost incompressible.

pub fn embedding_dtype(self, dt: EmbeddingDType) -> Self

Embedding dtype + on-disk encoding. Mutates the manifest’s dtype to match. Quantized variants (Float16, Int8) are lossy; the runtime always accumulates dot products in f32.

pub fn hnsw_index(self, payload: Vec<u8>) -> Self

Attach an HNSW index payload (already encoded by urna-engine). Sets index_type=hnsw, rerank_policy=exact, supports_ann=true.

pub fn bm25_index(self, payload: Vec<u8>) -> Self

Attach a BM25 index payload.

pub fn graph_adjacency(self, payload: Vec<u8>) -> Self

Attach a graph_adjacency (0x0C) csr payload (chunk-to-chunk edges, already encoded by encode_graph_adjacency). Sets the additive capabilities_ext.graph_present = Some(true) flag so the runtime opens the section behind a capability, exactly like hnsw/bm25. The section is EXCLUDED from content_hash, so adding a graph never invalidates a urna:// citation. Emitted raw, like hnsw.

pub fn blob_refs(self, payload: Vec<u8>) -> Self

Attach a blob_refs (0x14) payload (already encoded by encode_blob_refs): the content-hash reference table for source media blobs. Sets the additive capabilities_ext.blobs_present flag so the runtime opens the section behind a capability, exactly like hnsw/bm25/graph. The section is EXCLUDED from content_hash, so a self-contained media corpus keeps the content_hash (and the urna:// citations) of its text-only twin. Emitted raw, like hnsw.

pub fn blob_data(self, payload: Vec<u8>) -> Self

Attach a blob_data (0x17) payload (already encoded by encode_blob_data): the inlined media bytes whose offset table parallels the 0x14 record order, making the file self-contained with no media sidecar. additive and EXCLUDED from content_hash; implies blobs_present (the table indexes the 0x14 records).

pub fn blob_span_overlay(self, payload: Vec<u8>) -> Self

Attach a blob_span_overlay (0x16) payload (already encoded by encode_blob_span_overlay): per-chunk blob-relative spans that the runtime prefers over chunks_original_spans (0x03) for cite/retrieve, so 0x03 never has to carry an ordinal disguised as a byte range. additive and EXCLUDED from content_hash; also implies blobs_present (the overlay indexes the 0x14 table).

pub fn space_table(self, payload: Vec<u8>) -> Self

Attach a space_table (0x15) payload (already encoded by encode_space_table): the multimodal per-space directory. Sets the additive capabilities_ext.supports_multimodal flag so the runtime opens the space bands behind a capability, exactly like the other optional sections. EXCLUDED from content_hash, so a multimodal corpus keeps the citations of its text-only twin. Emitted raw.

pub fn space_band( self, space_index: u8, encoding: u32, payload: Vec<u8>, ) -> Self

Attach one per-space vector band: the fixed-stride slab at section 0x20 + space_index. encoding is the dtype encoding (SECTION_ENCODING_RAW for f32, or float16/int8/int4), NEVER zstd (the reader rejects it for band ids). EXCLUDED from content_hash; also implies supports_multimodal (a band without a table is still a multimodal file, though the runtime only opens listed spaces).

pub fn hybrid(self) -> Self

Mark the search path as hybrid (BM25 + cosine). Requires both an HNSW or exact path and a BM25 index. Caller is responsible for declaring score_type=hybrid_rrf if they want that, otherwise score_type stays “cosine”.

pub fn write_to_path(self, path: impl AsRef<Path>) -> Result<()>