Module directory 

The optional DIRECTORY record: a bounded, advisory seek directory.

The directory is a self-describing, little-endian, versioned payload written as the first record (fixed offset 64) with [FLAG_OPTIONAL]. It lets a seek reader jump to the records a query needs instead of reading the whole descriptor. It is advisory, never authority: every locator is cross-checked against the record framing, and a decoder that ignores the record still fully materializes the source exactly.

seek_directory_v1 :=
    version:u8 = 1
    section_flags:u8            # bit0 LOCATORS, bit1 CLASS_INDEX, bit2 CHANNEL_LENGTHS
    entry_count:u32 LE          # if bit0
    entry[entry_count]          # tag:u8 | offset:u64 | payload_len:u32
    class_count:u8              # if bit1
    class_entry[class_count]    # tag:u8 | first:u32 | count:u32
    channel_count:u32 LE        # if bit2
    channel_decoded_len[channel_count]:u64 LE

LOCATORS lists every record in file order, including the DIRECTORY itself (entry 0, at offset HEADER_LEN), so offset contiguity is checkable against the actual framing. CLASS_INDEX gives the first/count of each repeating class (OBJECT, ENTROPY_CHANNEL, MODEL) and each singleton (GRAPH, OBSERVATION_INDEX, INTEGRITY, TRAILER) into entry[]. CHANNEL_LENGTHS carries each entropy channel’s decoded length in table order.

Unknown version or section flags fail closed. All arithmetic is checked.

Structs

ClassEntry

One class index entry: the first locator index of tag and how many consecutive locators carry it.

DirectoryEntry

One record locator: where a record’s tag byte sits and its declared payload length. offset is absolute from the start of the descriptor.

RecordSite

The on-disk location of one record, used to cross-check a directory against the actual framing.

SeekDirectory

A decoded DIRECTORY record payload.

Constants

CLASS_ENTRY_LEN

Encoded size of one class entry: tag u8 | first u32 | count u32.

CLASS_INDEX_TAGS

The record classes that receive a CLASS_INDEX entry, in emission order.

DIRECTORY_ENTRY_LEN

Encoded size of one locator entry: tag u8 | offset u64 | payload_len u32.

SECTION_CHANNEL_LENGTHS

Section flag: the channel decoded-length table (bit 2) is present.

SECTION_CLASS_INDEX

Section flag: the class index (bit 1) is present.

SECTION_LOCATORS

Section flag: the locator table (bit 0) is present.

SEEK_DIRECTORY_ALL_SECTIONS

The section set emitted by this build’s encoder.

SEEK_DIRECTORY_KNOWN_SECTION_FLAGS

Every section flag this version understands. Any other bit fails closed.

SEEK_DIRECTORY_VERSION

Wire version of the seek directory implemented by this build.

Functions

class_index

Build a canonical class index from a locator table: one entry per class in CLASS_INDEX_TAGS that appears, with its first index and total count.