Module layout 

.urna binary file layout (v1)

File structure:

[0 .. 128)                  UrnaHeader (128 bytes)
[128 .. 128+count*32)       SectionTable (32 bytes per entry)
[manifest_offset .. ...)    Manifest JSON (JCS canonical)
[sections ...]              Required sections, each starting at a
                            64-byte aligned offset; padding before
                            each section is zero and is NOT part of
                            the section's checksum
[file_size-40 .. file_size) Footer (40 bytes)

All multi-byte integers are little-endian, unsigned unless noted.

Structs

SectionEntry

UrnaFooter

UrnaHeader

Constants

CANONICAL_SECTIONS

Canonical order for content_hash. Sorted alphabetically by name; this order is fixed by spec so adding new section IDs cannot reshuffle the hash. Keep this list and section IDs in sync.

LEGACY_MAGIC

magic written by releases up to 0.4.0, before the project was renamed. the reader accepts it (same layout, same hashes); the writer never emits it.

OPTIONAL_SECTIONS

Optional sections - present when their corresponding capability is advertised in the manifest. They do NOT participate in content_hash (which is over the canonical six only) so adding an optional section to a corpus does not invalidate citations.

REQUIRED_SECTIONS

Required sections for a v1 .urna file. A reader rejects any file missing one of these with MissingRequiredSection.

SECTION_ALIGNMENT

Every section’s offset is aligned to this many bytes. Padding before each section is zero and is NOT covered by the section’s checksum. Chosen to match common SIMD widths so embeddings can be loaded directly from mmap.

SECTION_BLOB_DATA

SECTION_BLOB_REFS

SECTION_BLOB_SPAN_OVERLAY

SECTION_BM25_INDEX

SECTION_CHUNKS_CANONICAL

SECTION_CHUNKS_ORIGINAL_SPANS

SECTION_CHUNK_IDS

SECTION_CHUNK_SCALARS

SECTION_DEDUP_MAP

SECTION_DICTIONARY

SECTION_EDIT_JOURNAL

SECTION_EMBEDDINGS

SECTION_EMBEDDINGS_FP

SECTION_ENCODING_FLOAT16

SECTION_ENCODING_FRONTCODE

SECTION_ENCODING_FSST

SECTION_ENCODING_INT4

SECTION_ENCODING_INT8

SECTION_ENCODING_INTPACK

SECTION_ENCODING_RABITQ

SECTION_ENCODING_RAW

Section payload encoding.

SECTION_ENCODING_TXT_STREAMS

10 = txt_streams: the chunks_canonical (0x02) section’s COMPRESSED form re-laid-out from one concatenated zstd-19 blob into N independently zstd-encoded streams (one per canonical string) behind an intpack offset table (O(1) single-chunk seek/reopen). decodes BYTE-IDENTICALLY to the raw chunks_canonical payload, so content_hash and urna:// citations are unchanged. only valid for non-embedding sections. this is the named prerequisite layout for the dict(5)/fsst(9) text levers; a per-chunk frame loses cross-chunk LZ context (small ratio cost today) but is where a trained dict/fsst can beat one big zstd-19 blob.

SECTION_ENCODING_ZSTD

SECTION_ENCODING_ZSTD_DICT

SECTION_GRAPH_ADJACENCY

SECTION_GRAPH_EDGE_PROPS

SECTION_GRAPH_ENTITY_MAP

SECTION_GRAPH_NODES

SECTION_HNSW_INDEX

SECTION_PAYLOAD_PREFIX_SIZE

Common prefix for all internal section payloads (12 bytes): u32 version (LE) u64 entry_count (LE)

SECTION_PAYLOAD_VERSION

SECTION_PROVENANCE

SECTION_REPRO_MANIFEST

SECTION_SEARCH_CONTRACT

SECTION_SPACE_EMBEDDINGS_BASE

SECTION_SPACE_EMBEDDINGS_FP_BASE

SECTION_SPACE_TABLE

SECTION_TOKENIZER_MODEL

SPACE_BAND_LEN

URNA_FOOTER_SIZE

URNA_FORMAT_VERSION

Format version of the binary layout. Bumped when the on-disk container changes (header/footer/section table layout).

URNA_HEADER_SIZE

URNA_MAGIC

URNA_SCHEMA_VERSION

Schema version of the manifest/contract. Bumped when manifest fields or required section semantics change.

URNA_SECTION_ENTRY_SIZE

URNA_VERSION_MAJOR

URNA_VERSION_MINOR

Functions

align_up

Round n up to the next multiple of a. a must be a power of two.

section_name