Binary DB v0: Format and Authority

This chapter is the entry point to the complete active Binary DB v0 technical schema. It explains how every fixed record, payload, and index is addressed and which storage root owns it.

Unassigned behavior remains reserved and fails closed: an implementation must not invent an extended-handle encoding, silently widen a field, or select a new canonical payload encoding outside a declared layout conversion.

Global File Format#

Every persisted Binary DB .bin file and every rebuildable .idx file starts with one four-byte header:

BIN_HEADER_SIZE = 4
INDEX_HEADER_SIZE = 4

BinHeader / IndexHeader:
u32 layout_id = 1     # little-endian

The file path determines record kind, namespace, authority scope, and whether the file is authoritative storage, payload storage, object data, or an optional cache. The header contains no magic, record count, checksum, authority name, generation token, or duplicate file kind.

For fixed-record files:

record_count  = (file_size - BIN_HEADER_SIZE) / record_size
record_offset = BIN_HEADER_SIZE + record_index * record_size

file_size must be at least four bytes and the record area must be exactly divisible by the selected record size. One file must never mix records from different layouts. Record codecs use the declared byte offsets and do not rely on Rust struct layout, host alignment, or implicit padding.

Payload offsets are u64 file addresses measured from byte zero of the owning payload file. The first payload normally begins at offset BIN_HEADER_SIZE. Payload and fixed-record integer fields use the repository's fixed byte order. Reserved bits and fields are written as zero.

Unless a field is the separately declared signed Git identity timestamp, every active fixed-record *_at_s field is a little-endian unsigned u64 count of whole seconds since the Unix epoch. Pre-epoch input fails closed. Zero retains the exact absent or unknown meaning declared for that field. No ordering or uniqueness is inferred from timestamp precision.

*_index_plus1 = 0 means absent; non-zero values encode index + 1 because record index zero is valid. An index field without the plus1 suffix stores a direct record index and may legitimately contain zero.

Authority Scopes#

The same filename may use a different record layout when its authority root is different:

• Local workflow authority owns local Task, Change, Line, Tag, Stash, Land, Land-target-Line, task-snapshot-link, and Plan state.
• One ait-server repository authority owns remote Task, Change, Line, Land, Land-target-Line, task-snapshot-link, Plan, Patchset, Worker Job and its ready/state indexes, Attestation, Actor, Review, Policy, and Waiver state.
• One ait-server installation owns a distinct server-global operational authority root only for the Repository registry and its namespace lookup index. A repository_index points to that root's repository.bin and routes to one server Repository authority. A Worker Job identity is meaningful only as (repository_index, worker_job_index); the second component is the permanent physical record index local to the routed Repository authority.
• Shared content authority owns content Snapshot, ordered Snapshot-parent, Tree, normalized Tree-entry-range, Blob, and object-pack metadata.
• Optional local Git interoperability authority owns Git import/export repository identities, generations, immutable mappings, and resumable checkpoints. It is an escape-hatch mapping authority, not primary AIT workflow or content authority.
• A task worktree owns disposable .ait-worktree/cursor.bin state.
• Optional local content caches own manifest/file lookup acceleration.
• An optional local remote-mirror root may mirror server snapshot links while preserving server indexes.

Equal numeric indexes in different authority roots are not the same identity. Local writers never allocate server indexes.