Binary DB v0: Server and Policy Records

This chapter covers repository-scoped remote workflow authority and the separate installation-scoped Repository registry. Numeric indexes are meaningful only in their declared roots; Worker Job identity and references stay inside the routed Repository authority.

Server Patchset Records#

TASK_PATCHSET_INDEX_RECORD_SIZE = 8

TaskPatchsetIndexRecord — task_patchset_index.bin:
u32 latest_patchset_index_plus1
u16 patchset_count
u16 reserved0

CHANGE_PATCHSET_INDEX_RECORD_SIZE = 8

ChangePatchsetIndexRecord — change_patchset_index.bin:
u32 latest_patchset_index_plus1
u16 patchset_count
u8  next_patch_ordinal
u8  reserved0

SERVER_PATCHSET_RECORD_SIZE = 65

ServerPatchsetRecord — patchset.bin:
u8  patchset_meta
u8  patch_ordinal
u8  change_ordinal
u8  reserved0
u32 change_index
u32 previous_task_patchset_index_plus1
u32 previous_change_patchset_index_plus1
u32 base_snapshot_index
u32 revision_snapshot_index
u64 created_at_s
u64 ci_completed_at_s
u32 ci_run_seq
u16 ci_selected_suite_count
u16 ci_suite_result_count
u16 ci_blocking_failure_count
u8  ci_status_bits
u64 summary_offset
u16 summary_len
u32 ci_worker_job_index_plus1

The first 51 bytes are the complete fixed Patchset/compact-CI region: its first 32 bytes are the widened Patchset identity prefix and its corrected compact CI tail is exactly 19 bytes. Those regions are the zero-extended forms of the u32-time-v0 predecessor's 28-byte identity prefix and 15-byte compact-CI tail. The appended summary locator is exactly ten bytes. The final Worker Job locator is exactly four bytes, producing the complete 65-byte record. None of these regions has implicit padding. summary_len is in 1..65535, and summary_offset points to exactly that many non-empty UTF-8 bytes in patchset_summary_payload.bin. Patchset summary is the human-authored description of this reviewable Patchset; it is not Task intent, Snapshot message, Tree diff statistics, Review text, or Policy output.

patch_ordinal is unique in (change_index, patch_ordinal). Values 0..63 render as P-01..P-64 under the full owning Change identity. ChangePatchsetIndexRecord.next_patch_ordinal is the one-past-greatest allocated ordinal and rejects allocation after 64; deletion or omission never reuses an ordinal. ChangePatchsetIndexRecord.latest_patchset_index_plus1 and previous_change_patchset_index_plus1 follow Change-scoped Patchset ordinal. TaskPatchsetIndexRecord is physical inventory only: its latest pointer and each previous_task_patchset_index_plus1 follow committed physical Patchset record order and do not allocate or imply a Task-scoped Patchset ordinal. Recovery rebuilds the Task inventory from committed record order and rebuilds each Change chain, count, and next ordinal from Change-scoped identity.

Patchset creation appends and fsyncs the summary bytes before appending the fixed Patchset commit record. Patchset identity, owner, ordinals, Snapshot references, creation time, and summary locator/bytes are immutable. Compact CI fields and ci_worker_job_index_plus1 may change only by complete-record replacement under the declared Worker Job mutation boundary. An interrupted append may leave only unreferenced trailing summary bytes, which recovery ignores. A committed missing, empty, overlapping, or invalid UTF-8 summary range is corruption.

ci_completed_at_s is a non-negative u64 Unix-second timestamp. ci_run_seq = 0 means no CI run has started. A non-zero ci_run_seq with ci_completed_at_s = 0 represents an in-flight run and requires all status and count fields to be zero. Completed evidence requires a non-zero completion time, a non-zero run sequence, and a non-none overall status.

ci_worker_job_index_plus1 = 0 means the Patchset has no selected Worker-Job-backed CI run; this includes legacy compact CI evidence and an inline CI run. A non-zero value resolves to index + 1 in worker_job.bin under the same server Repository authority as this Patchset. It must target a non-tombstoned Job whose exact type is patchset.ci and whose fixed patchset_index_plus1 resolves back to this exact Patchset. No Repository ID or Repository index participates in that same-root relationship.

The locator selects the greatest committed worker_job_index for this Patchset. A later rerun appends a new Job and replaces the complete Patchset record with that new local index; older Jobs remain Job history but cannot overwrite compact CI evidence after they are superseded. At terminal completion, compact CI fields may be replaced from a Job result only after revalidating that the completing Job is still the selected locator target.

ServerPatchsetRecord.ci_status_bits:
bits 0..1 overall_status
bits 2..3 tests_status
bits 4..5 lint_status
bits 6..7 reserved = 0

Each two-bit status:
00 none
01 pass
10 fail
11 error

ci_suite_result_count must not exceed ci_selected_suite_count, and ci_blocking_failure_count must not exceed ci_suite_result_count. Component statuses require completed overall evidence. These fields store only compact Patchset CI evidence. Queue state, attempts, fixed outcomes, and retry-error categories remain in the same Repository's fixed Worker Job family. Lease credentials, request materialization, detailed results, logs, artifacts, and scheduler configuration remain outside Binary DB v0.

Source author_mode, the published/superseded portion of publish_state, and the pending/non-pending Policy cache state are encoded in patchset_meta as defined below. A source selected-for-landing projection is normalized under the Remote Change pointer rules and is not Patchset state. Source diff_stats is not stored: it is recomputed by exact comparison of the base and revision Snapshot Trees. Except for the exact named legacy all-zero gate under Bin-to-Bin Conversion Acceptance, a converter must reject a supplied value that disagrees with that comparison. A non-pending evaluation_state is the latest live Policy Decision kind; the Patchset pending bit distinguishes a newly created or invalidated cache from an older non-pending decision. No Patchset JSON payload is authoritative.

Patchset storage is server-authoritative. Local workflow authority defines no Patchset files.

Server Attestation Records#

TASK_ATTEST_INDEX_RECORD_SIZE = 8

TaskAttestIndexRecord — task_attest_index.bin:
u32 latest_attest_index_plus1
u16 attest_count
u8  next_attest_ordinal
u8  reserved0

PATCHSET_ATTEST_INDEX_RECORD_SIZE = 8

PatchsetAttestIndexRecord — patchset_attest_index.bin:
u32 latest_attest_index_plus1
u16 attest_count
u16 reserved0

SERVER_ATTEST_RECORD_SIZE = 24

ServerAttestationRecord — attest.bin:
u8  attest_meta
u8  attest_ordinal
u8  patch_ordinal
u8  change_ordinal
u32 patchset_index
u32 previous_task_attest_index_plus1
u32 previous_patchset_attest_index_plus1
u64 created_at_s

The four finite Attestation requirement values are stored in attest_meta bits 3 through 6, never payload. A source compact Attestation whose time and requirement bits are all zero is absent and emits no v0 record. A present source compact Attestation is Change-scoped mutable source state; the legacy format does not persist selected-Patchset history at attested_at_s. While holding one coherent locked source snapshot, conversion resolves the row through its owning Change's authoritative current selected_patchset_number and emits one v0 Attestation whose patchset_index references that exact Patchset. The ordinal-to-target-index lookup is converter-local state and creates no historical selection field, record, bin, or payload. This lookup does not make current Change selection transient: the same source pointer independently populates the existing RemoteChangeRecord.selected_patchset_index_plus1 authority defined above. A missing, invalid, non-owned, or non-unique current selected pointer fails closed. Any source Attestation author mode must equal the bound Patchset author mode because v0 does not duplicate it.

Actor And Review Records#

ACTOR_RECORD_SIZE = 36

ActorRecord — actor.bin:
u8  actor_meta
u8  reserved0
u16 payload_len
u64 payload_offset
u64 actor_key_hash
u64 created_at_s
u64 last_seen_at_s

For bin-to-bin conversion, this existing fixed record and the existing ActorPayload are the complete Actor schema; no conversion-only Actor bin or generic payload exists. Each distinct non-empty source reviewer identity is stored byte-for-byte as ActorPayload.user_name_bytes, with user_id_len = 0, email_len = 0, and empty memo. The converter does not trim, case-fold, or parse a display string such as Name <email> into invented components. The Actor kind is unknown unless a structured source field proves another kind. A non-empty identity supplied through requested_groups is structured team evidence and uses kind team. Equal kind plus equal identity bytes reuse one Actor; different bytes remain different Actors.

The required payload is identity authority and collision evidence, not an optional Review annotation. Its length must fit the existing u8 user_name_len and u16 payload_len; overflow or invalid UTF-8 fails closed. actor_key_hash is FNV-1a-64 over the exact user_name_bytes:

actor_key_hash = fnv1a64(user_name_bytes)
offset_basis   = 0xcbf29ce484222325
prime          = 0x00000100000001b3

The ActorLookupIndexRecord may return hash-collision candidates. A lookup accepts a candidate only after exact actor_kind and ActorPayload byte comparison; the hash alone never merges identities. created_at_s is the minimum source ReviewRecord.created_at_s that references the Actor, and last_seen_at_s is the maximum. When the admitted legacy source format has no Review time, both fields are zero, meaning unknown historical times. Supplied valid times are preserved for the derivation and invalid supplied times fail closed; conversion time is never substituted.

TASK_REVIEW_INDEX_RECORD_SIZE = 8

TaskReviewIndexRecord — task_review_index.bin:
u32 latest_review_index_plus1
u16 review_count
u16 reserved0

PATCHSET_REVIEW_INDEX_RECORD_SIZE = 8

PatchsetReviewIndexRecord — patchset_review_index.bin:
u32 latest_review_index_plus1
u16 review_count
u8  next_review_ordinal
u8  reserved0

SERVER_REVIEW_RECORD_SIZE = 40

ServerReviewRecord — review.bin:
u8  review_meta
u8  review_ordinal
u8  patch_ordinal
u8  change_ordinal
u32 actor_index_plus1
u32 patchset_index
u32 previous_task_review_index_plus1
u32 previous_patchset_review_index_plus1
u64 payload_offset
u16 payload_len
u16 reserved0
u64 created_at_s

Review action variants use one base action plus the fixed modifiers in review_meta. The exact source mappings are:

request              -> request
comment              -> comment
task_comment         -> comment + task_lane
code_review_summary  -> comment + code_review_summary
approve              -> approve
task_approve         -> approve + task_lane
request_changes      -> request_changes
task_request_changes -> request_changes + task_lane
defer                -> comment + defer
task_defer           -> comment + task_lane + defer
dismiss              -> dismiss

Any other spelling or invalid base/modifier combination fails closed. The independent blocking bit is preserved for every mapping. A normal Review's actor_index_plus1 references its reviewer Actor. A review request with exactly one requested_groups value uses action request and references the corresponding team Actor; the active v0 schema cannot encode multiple groups in one Review. Its source reviewer may be absent or may contain the exact same UTF-8 bytes as that sole non-empty group. In the equal case it is only a redundant legacy projection: conversion creates or reuses the one team Actor and stores one actor_index_plus1; it does not create a second Actor or Review. A converter presented with a different reviewer, an empty identity, zero groups, or more than one requested group for a request fails closed instead of inventing Review rows or payload. Review comment or request-note text remains in ReviewPayload.

review_ordinal is unique in (patchset_index, review_ordinal). Values 0..63 render as R-01..R-64 under the full owning Patchset identity. An admitted legacy Change-scoped Review ID retains its exact numeric suffix when it moves under that Review's exact Patchset; gaps inside one Patchset are valid, but duplicate ordinals are not. PatchsetReviewIndexRecord owns next-ordinal allocation and its latest/previous links follow Patchset-scoped Review ordinal. TaskReviewIndexRecord and previous_task_review_index_plus1 retain physical Task inventory only. Recovery rebuilds each Patchset chain, count, and next ordinal without renumbering source Review identities.

Policy And Waiver Records#

TASK_POLICY_INDEX_RECORD_SIZE = 8

TaskPolicyIndexRecord — task_policy_index.bin:
u32 latest_policy_index_plus1
u16 policy_count
u16 reserved0

PATCHSET_POLICY_INDEX_RECORD_SIZE = 8

PatchsetPolicyIndexRecord — patchset_policy_index.bin:
u32 latest_policy_index_plus1
u16 policy_count
u8  next_policy_ordinal
u8  reserved0

POLICY_DECISION_RECORD_SIZE = 32

PolicyDecisionRecord — policy.bin:
u8  policy_meta
u8  policy_ordinal
u8  patch_ordinal
u8  change_ordinal
u32 patchset_index
u32 previous_task_policy_index_plus1
u32 previous_patchset_policy_index_plus1
u32 first_check_index_plus1
u16 check_count
u16 reserved0
u64 created_at_s

policy_ordinal is unique in (patchset_index, policy_ordinal), not in the owning Task. Values 0..63 render as K-01..K-64 under the full owning Patchset identity. PatchsetPolicyIndexRecord.next_policy_ordinal is the one-past-greatest allocated ordinal and rejects allocation after 64; deletion or tombstoning never reuses an ordinal. A Task may therefore own more than 64 Policy Decisions across multiple Patchsets, subject to its u16 policy_count capacity, while each Patchset remains capped at 64.

PatchsetPolicyIndexRecord.latest_policy_index_plus1 and previous_patchset_policy_index_plus1 follow Patchset-scoped Policy ordinal. TaskPolicyIndexRecord retains the complete Task inventory only: its latest pointer and each previous_task_policy_index_plus1 follow committed physical Policy record order and do not allocate or imply a Task-scoped Policy ordinal. Recovery rebuilds the Task inventory from committed record order and rebuilds each Patchset chain, count, and next ordinal from Patchset-scoped identity.

POLICY_CHECK_RECORD_SIZE = 8

PolicyCheckRecord — policy_check.bin:
u8  check_kind
u8  check_status
u16 subject_ordinal
u32 detail_flags

The rows beginning at first_check_index_plus1 preserve source check order and are the complete fixed Policy-check authority. subject_ordinal and detail_flags have these exact meanings:

check_kind 0..7:
  subject_ordinal = 0
  detail_flags = 0

check_kind 8 ci_rollout_phase:
  subject_ordinal = exact rollout phase in 0..65535
  detail_flags = 0

check_kind 9 ci_patchset_suite:
  subject_ordinal = one-based position of the exact suite ID in the
                    normalized UTF-8-byte-sorted exact Policy tuple catalog
  detail_flags bit 0 = blocking suite
  detail_flags bit 1 = informational suite
  detail_flags bits 2..31 = 0

ci_rollout_phase is the numeric rollout phase of CI enforcement policy. It is not Task, Change, Patchset, or Land lifecycle state, and it does not itself name a CI suite. For every admitted legacy phase-0 projection, the source check name is exactly ci_rollout_phase; conversion writes check_kind = 8, preserves the source check status, writes subject_ordinal = 0, and writes detail_flags = 0.

Legacy conversion accepts only the following exact (catalog, blocking set, informational set, phase message) tuples. Catalog comparison uses normalized UTF-8 byte order. A suite in the blocking set receives detail bit 0; a suite in the informational set receives detail bit 1.

catalog = [rust_core]
blocking = [rust_core]
informational = []
message = CI rollout phase 0 blocks `rust_core` and keeps none visible as non-blocking surfaces.

catalog = [full_repo_contract]
blocking = [full_repo_contract]
informational = []
message = CI rollout phase 0 blocks `full_repo_contract` and keeps none visible as non-blocking surfaces.

catalog = [full_repo_contract]
blocking = [full_repo_contract]
informational = []
message = CI rollout phase 0 blocks `full_repo_contract` and keeps none visible as non-blocking surfaces. Future promotions are modeled as phase1: `full_repo`.

catalog = [package_smoke, preflight, recent_regression, stable_smoke]
blocking = [package_smoke, preflight, stable_smoke]
informational = [recent_regression]
message = CI rollout phase 0 blocks `package_smoke`, `preflight`, `stable_smoke` and keeps `recent_regression` visible as non-blocking surfaces.

catalog = [package_smoke, preflight, recent_regression, stable_smoke, task_batch]
blocking = [package_smoke, preflight, stable_smoke]
informational = [recent_regression, task_batch]
message = CI rollout phase 0 blocks `preflight`, `stable_smoke`, `package_smoke` and keeps `recent_regression`, `task_batch` visible as non-blocking surfaces. Future promotions are modeled as phase1: `recent_regression`, `task_batch`, phase2: `full_repo`.

catalog = [package_smoke, preflight, recent_regression, stable_smoke, task_batch, tg1_required]
blocking = [package_smoke, preflight, stable_smoke, tg1_required]
informational = [recent_regression, task_batch]
message = CI rollout phase 0 blocks `preflight`, `stable_smoke`, `package_smoke`, `tg1_required` and keeps `recent_regression`, `task_batch` visible as non-blocking surfaces. Future promotions are modeled as phase1: `recent_regression`, `task_batch`, phase2: `full_repo`.

catalog = [package_smoke, preflight, recent_regression, stable_smoke, task_batch, tg1_required]
blocking = [package_smoke, preflight, stable_smoke]
informational = [recent_regression, task_batch, tg1_required]
message = CI rollout phase 0 blocks `preflight`, `stable_smoke`, `package_smoke` and keeps `recent_regression`, `task_batch`, `tg1_required` visible as non-blocking surfaces. Future promotions are modeled as phase1: `recent_regression`, `task_batch`, phase2: `full_repo`.

catalog = [package_smoke, preflight, recent_regression, stable_smoke, task_batch, tg1_required]
blocking = [package_smoke, preflight, stable_smoke]
informational = [recent_regression, task_batch, tg1_required]
message = CI rollout phase 0 blocks `preflight`, `stable_smoke`, `package_smoke` and keeps `tg1_required`, `recent_regression`, `task_batch` visible as non-blocking surfaces. Future promotions are modeled as phase1: `recent_regression`, `task_batch`, phase2: `full_repo`.

catalog = [package_smoke, preflight, recent_regression, stable_smoke, tg1_required]
blocking = [package_smoke, preflight, stable_smoke]
informational = [recent_regression, tg1_required]
message = CI rollout phase 0 blocks `package_smoke`, `preflight`, `stable_smoke` and keeps `recent_regression`, `tg1_required` visible as non-blocking surfaces. Future promotions are modeled as phase1: `recent_regression`, `task_batch`, phase2: `full_repo`.

catalog = [package_smoke, preflight, recent_regression, stable_smoke, tg1_required]
blocking = [package_smoke, preflight, stable_smoke, tg1_required]
informational = [recent_regression]
message = CI rollout phase 0 blocks `package_smoke`, `preflight`, `stable_smoke`, `tg1_required` and keeps `recent_regression` visible as non-blocking surfaces. Future promotions are modeled as phase1: `recent_regression`, `task_batch`, phase2: `full_repo`.

The phase check, exact suite-name checks, catalog, blocking/informational partition, and message must agree with one tuple. Labels remain derived presentation and are not persisted. A different or ambiguous representation fails closed; the converter never parses a phase number or suite assignment out of free-form text. Native v0 writers may use another numeric phase only with an explicit Policy configuration that supplies the fixed fields directly.

Exactly one of the two suite detail bits is set for check_kind = 9. Within one Policy, suite ordinals are non-zero, unique, complete, and no greater than that Policy's exact tuple catalog length. They are not bounded by the owning Patchset's ci_selected_suite_count: the Patchset field is compact evidence for one CI run, while immutable Policy rows retain historical evaluations that may precede that evidence or use a different admitted blocking/informational projection. Conversion resolves a source ci_patchset_suite_<suite-id> name against the exact Policy tuple catalog; missing, duplicate, incomplete, or ambiguous suite identity fails closed. Policy check label and message are presentation projections and are not stored. An unknown check name/status fails closed rather than becoming text payload. Source input_fingerprint is cache metadata, not Policy authority; v0 recomputes it from the fixed Patchset, Attestation, Review, Waiver, CI, and Policy inputs and does not persist the source cache key.

TASK_WAIVER_INDEX_RECORD_SIZE = 8

TaskWaiverIndexRecord — task_waiver_index.bin:
u32 latest_waiver_index_plus1
u16 waiver_count
u8  next_waiver_ordinal
u8  reserved0

PATCHSET_WAIVER_INDEX_RECORD_SIZE = 8

PatchsetWaiverIndexRecord — patchset_waiver_index.bin:
u32 latest_waiver_index_plus1
u16 waiver_count
u16 reserved0

WAIVER_RECORD_SIZE = 44

WaiverRecord — waiver.bin:
u8  waiver_meta
u8  waiver_ordinal
u8  patch_ordinal
u8  change_ordinal
u32 patchset_index
u32 previous_task_waiver_index_plus1
u32 previous_patchset_waiver_index_plus1
u64 payload_offset
u16 payload_len
u16 rule_code
u64 created_at_s
u64 expires_at_s

Plan Records#

PLAN_RECORD_SIZE = 48

PlanRecord — plan.bin:
u8  plan_meta
u8  reserved0
u16 payload_len
u64 payload_offset
u32 latest_revision_index_plus1
u32 published_plan_index_plus1
u32 published_latest_revision_index_plus1
u64 created_at_s
u64 updated_at_s
u64 published_at_s

PLAN_REVISION_RECORD_SIZE = 56

PlanRevisionRecord — plan_revision.bin:
u8  revision_meta
u8  reserved0
u16 payload_len
u16 revision_number
u16 item_count
u64 payload_offset
u32 plan_index
u32 previous_revision_index_plus1
u32 item_start_index
u32 published_revision_index_plus1
u32 root_tree_pack_index_plus1
u32 root_entry_ordinal
u64 created_at_s
u64 published_at_s

PLAN_ITEM_RECORD_SIZE = 16

PlanItemRecord — plan_item.bin:
u8  item_meta
u8  reserved0
u16 payload_len
u64 payload_offset
u32 line_number

Plan revision history is a linear chain:

PlanRecord.latest_revision_index_plus1
  -> PlanRevisionRecord.previous_revision_index_plus1
  -> ...
  -> 0

Task-to-Plan binding uses the Task record's numeric revision and item indexes. Exact taskability still requires comparison with PlanItemPayload.plan_item_ref_bytes.

Server-Global Repository Registry Authority#

The server-global Repository registry is one installation-scoped Binary DB root. It is never nested inside a repository authority and is never copied into a local repository. Every file explicitly assigned to this root uses the global four-byte layout_id = 1 header. A required empty family is a header-only file. Equal physical indexes in this root and another authority root have no relationship.

Every repository_index below is a direct dense index into this root's repository.bin and is that Repository's sole primary key. Index zero is valid. Repository records are append-only: an assigned index is never renumbered, removed, reused, or transferred to another Repository. A *_index_plus1 uses the global absent encoding. This root never persists a numeric index into repository workflow, Worker Job, or shared-content authority.

The first four Repository indexes are fixed:

0 ait-core
1 ait-server
2 ait-python
3 ait-node

Every later Repository appends at the next record ordinal starting from four. All server routing, configuration, and operational relationships identify a Repository by repository_index, never by Repository name.

The active server-global fixed-family inventory is exactly repository.bin. Its active typed-payload inventory is exactly repository_payload.bin, and its only active index is repository_namespace.idx. operational_public_sequence.bin, every Worker Job fixed file, and every Worker Job index are forbidden in this global root. Worker Job files are required in each numeric server Repository authority as declared below. Any other operational .bin, payload, or .idx file fails activation.

Operational timestamps are non-negative u64 Unix seconds. A required timestamp is non-zero. An optional timestamp is zero when absent and otherwise non-zero. Admitted RFC 3339 timestamps are normalized to UTC; for a non-negative value, any fractional second is deliberately discarded before the whole-second value is range-checked and stored. A pre-Unix-epoch value, whole-second value greater than u64::MAX, or unparseable text fails closed. Repository and Job updated_at_s are not earlier than their created_at_s. When a Job is locked, created_at_s <= locked_at_s <= updated_at_s.

Repository Registry Records#

The registry is the installation-scoped authority for Repository identity and routing metadata. It is independent of every repository-scoped workflow and content root.

OPERATIONAL_REPOSITORY_RECORD_SIZE = 33

OperationalRepositoryRecord — repository.bin:
u8  repository_meta
u8  lifecycle_kind
u8  namespace_ascii[2]
u8  policy_flags
u32 payload_len
u64 payload_offset
u64 created_at_s
u64 updated_at_s

The Repository primary key is the record's physical repository_index; it is not duplicated inside the record or payload. Repository names are non-empty immutable UTF-8 display metadata and may repeat without limit. A name is never accepted as identity or routing authority. A non-empty namespace_ascii value is unique among active and retiring records; empty is valid and has no namespace-index row. Historical purged identities may share a namespace with a later live Repository, so namespace lookup may return candidates and must verify lifecycle plus the exact two fixed bytes. repo_name and created_at_s are immutable after creation. Policy, namespace, lifecycle, and updated_at_s mutate only by complete-record replacement under the registry lock.

An activated root has at least four Repository records. Records zero through three have exact payload names ait-core, ait-server, ait-python, and ait-node respectively and are never tombstoned; retirement uses the retained lifecycle_kind = purged record instead. A later record may repeat any of those names without acquiring the reserved record's identity.

The logical Repository default Line is always exact UTF-8 main. It is a schema constant, has no fixed or payload field, and is synthesized at an API boundary that exposes a default-Line value. Native creation cannot select a different default Line.

Repository Authority Directory Routing#

The configured server Repository-authority parent uses the canonical unsigned base-10 repository_index as each Repository directory basename:

<server-repository-authority-parent>/
  0/  # ait-core
  1/  # ait-server
  2/  # ait-python
  3/  # ait-node
  4/
  ...

Zero is written exactly as 0; every other basename has no leading zero, sign, whitespace, suffix, prefix, or alternate numeric spelling. Repository name never appears in an authoritative directory name. The directory is the routing container for that Repository's workflow, content, Plan, and Worker Job authority families. The directory itself adds no .bin record; the Worker Job child layouts are declared below.

An active parent contains exactly one real, non-symlink directory for every non-tombstoned Repository record and no textual alias directory. Resolving a directory parses its basename as u32, verifies that the corresponding repository.bin record exists and is not tombstoned, and never scans by Repository name. Compaction preserves every Repository directory basename because it preserves every repository_index.

Repository-Scoped Worker Job Records#

Each canonical numeric server Repository authority contains exactly one worker_job.bin operational queue authority. A required empty file is header-only. This file is Remote Binary input for that one Repository: it is not copied into a local Repository, is not the excluded generic job.bin, is not Patchset compact-CI evidence, and is not a queue projection. Active v0 defines no Worker Job payload file.

SERVER_WORKER_JOB_RECORD_SIZE = 52

ServerWorkerJobRecord — worker_job.bin:
u8  job_meta
u8  job_kind
u8  state_kind
u8  outcome_kind
u16 attempt_count
u16 max_attempts
u16 error_kind
u16 reserved0
u32 patchset_index_plus1
u32 snapshot_index_plus1
u64 available_at_s
u64 locked_at_s
u64 created_at_s
u64 updated_at_s

The owning Repository is implicit in the canonical numeric authority directory. Neither Repository ID nor repository_index is duplicated in the fixed record. The direct physical worker_job_index record ordinal is the sole Worker Job primary key inside that Repository. Records are append-only: an assigned index is never renumbered, removed, reused, or transferred. A tombstone retains its exact slot.

The complete installation identity is (repository_index, worker_job_index). A bare worker_job_index has no meaning outside its routed Repository authority, and v0 stores no separate public or global Job ID. attempt_count <= max_attempts; both must fit u16, and max_attempts is non-zero. job_kind is fixed authority; an API job_type string is synthesized from it and is never persisted as Job bytes. available_at_s, created_at_s, and updated_at_s are required. Only running has a non-zero locked_at_s; every other state has locked_at_s = 0.

The two fixed domain-reference fields have the exact Job-kind interpretation below. +1 retains zero for absence. Every non-zero reference resolves inside the same numeric Repository authority as the Job:

job_kind = 1 is unassigned in active v0. agent.turn.submit requires an opaque turn request that is not represented by existing Repository domain authority, so it is not a durable Worker Job until a typed agent-turn schema exists. Every other job_kind, non-zero field not assigned by this table, wrong-family target, cross-Repository target, or tombstoned target fails closed. land.process derives its Change and revision Snapshot from the resolved Patchset. The Job is committed before any Land exists; execution creates the Land against logical main with the fixed server-default direct mode. Patchset-related Change and Snapshot data otherwise derive from the resolved Patchset closure. main-seed.refresh uses logical main and freezes only an independently required prior Snapshot. Native repo.ci freezes its selected Snapshot before committing the Job and also operates on logical main; neither kind persists a Line index or defers its Snapshot identity to a mutable Repository head.

No variable Worker Job request or input bytes exist. job_kind and the two fixed references are the complete durable execution selector. A writer may commit a Job only after every execution-affecting selection has been committed to those fields or to the referenced existing domain authority. Trigger labels, transport labels, scheduler resource keys, priority, retry delay, runner context, and materialized runtime payload are reconstructed runtime data and cannot alter that durable selection. Content-maintenance and Repository-reconciliation kinds invoke their one server-owned kind-level operation with no per-Job override. Patchset CI and aggregation derive their suite closure from the selected Patchset and its validated Policy/CI authority. Repository CI operates on the selected Snapshot and logical main using the server-owned Repository CI contract. If a requested operation cannot be reconstructed exactly under these rules, enqueue fails before allocating a worker_job_index.

Operational Repository Payload File#

The server-global root and every server Repository authority have no shared string pool and no operational_payload.bin. The Repository registry locator addresses the global repository_payload.bin. Worker Jobs have no payload locator or payload file.

OperationalRepositoryPayload — repository_payload.bin:
u16 repo_name_len
u8  repo_name_bytes[repo_name_len]

Repository payload_len is non-zero and payload_offset is at or after BIN_HEADER_SIZE; it is exactly 2 + repo_name_len, with no padding or trailing field. Repository names are exact valid UTF-8. The complete Repository payload is at most 65,537 bytes.

Rebuildable Registry And Worker Job Indexes#

All indexes in this subsection are optional rebuildable accelerators. A file uses exactly the authority root and target family implied by its filename. repository_namespace.idx belongs to the server-global registry. The two Worker Job indexes belong separately to every numeric server Repository authority. Persistent rows sort by all fields in declaration order.

OPERATIONAL_NAMESPACE_INDEX_RECORD_SIZE = 8

OperationalNamespaceIndexRecord — repository_namespace.idx:
u8  namespace_ascii[2]
u16 reserved0
u32 repository_index_plus1

Empty namespace bytes [0x00, 0x00] have no index row. Non-empty exact-byte namespace candidates may include more than one historical purged identity but at most one active or retiring identity.

SERVER_WORKER_READY_INDEX_RECORD_SIZE = 12

ServerWorkerReadyIndexRecord — worker_ready.idx:
u64 available_at_s
u32 worker_job_index_plus1

SERVER_WORKER_STATE_INDEX_RECORD_SIZE = 8

ServerWorkerStateIndexRecord — worker_state.idx:
u8  state_kind
u8  reserved0
u16 reserved1
u32 worker_job_index_plus1

worker_ready.idx contains live queued rows only. Queue claiming verifies the local Job index, authoritative state, exact available_at_s, attempt budget, and absence of a live runtime lease after lookup. worker_state.idx contains every live Job. In both files, worker_job_index_plus1 resolves only inside the same Repository authority that owns the index.

No .idx row is written for a tombstoned record. Missing, stale, duplicated, or corrupt indexes are discarded and rebuilt from that authority's worker_job.bin. Indexes never repair or override the fixed record.

An installation-wide scheduler enumerates active and retiring Repository indexes from the registry, reads exact-verified candidates from each local worker_ready.idx, and merges them in memory by (available_at_s, repository_index, worker_job_index). That in-memory merge is disposable and is never persisted as a global Job index, sequence, or identity authority.

Operational Metadata And State Encodings#

Except where overridden below, a mutable operational *_meta byte uses:

bits 0..6 reserved = 0
bit 7 tombstoned

A tombstoned record is retained history, is omitted from indexes, and cannot be the target of a live relationship. Source conversion writes no tombstones.

Repository metadata is:

repository_meta:
bits 0..6 reserved = 0
bit 7 tombstoned

lifecycle_kind:
1 active
2 retiring
3 purged

namespace_ascii[2]:
[0x00, 0x00] empty
[x,    0x00] one-byte namespace
[x,    y   ] two-byte namespace

policy_flags:
bit 0 require_attestation
bit 1 require_tests
bit 2 require_lint
bit 3 require_security_scan
bit 4 require_license_scan
bit 5 require_ai_provenance
bit 6 require_code_review_summary
bit 7 docs_only_relaxed_checks

Each x or y is one non-zero ASCII alphanumeric, _, or - byte. [0x00, y], an embedded zero, a control/non-ASCII byte, and an input longer than two bytes are invalid. Case and bytes are exact; readers perform no trimming, folding, or Unicode normalization. The logical namespace length is derived from the trailing zero and is never stored.

Bits 0 through 6 are the Repository's default requirements. When bit 7 is set and the effective content class is docs_only, tests, lint, security scan, and license scan are all not required; attestation, AI provenance, and code-review summary retain their default bits. The logical policy ID and version are fixed to prototype and 1 and are not persisted. An API that exposes Repository policy JSON synthesizes the canonical logical object from policy_flags.

Every non-tombstoned Repository requires a non-empty name, one valid namespace_ascii[2] value, and one policy_flags byte. Duplicate names are valid. active -> retiring -> purged and retiring -> active are the only lifecycle transitions. A purged Repository has no live Worker Jobs and cannot be the owner of a new Job. Purged identity, Repository payload bytes, and retained Repository-local Job history remain exact until offline compaction; they are never reconstructed from another domain.

Worker Job state is:

state_kind:
1 queued
2 running
3 succeeded
4 failed

outcome_kind:
0 none
1 completed
2 skipped
3 attached
4 superseded
5 failed

error_kind:
0 none
1 retryable_execution
2 terminal_execution
3 lease_expired

Every live Job is stored under the numeric authority directory of an active or retiring Repository. queued and running require outcome_kind = none; succeeded requires completed, skipped, attached, or superseded; and failed requires outcome_kind = failed. A new queued Job has error_kind = none. A queued retry or running retry may retain retryable_execution or lease_expired. succeeded requires error_kind = none; failed requires terminal_execution or lease_expired.

attached and superseded preserve only why this Job performed no independent successful work. They do not identify another Job. Any active-equivalent or later-successful Job identity used while deduplicating is runtime/projection data and is not Worker Job authority.

Lease credentials are not Binary DB authority. On claim the server creates a cryptographically random 16-byte lease_token, keeps the live entry in memory, and mirrors it to a crash-recovery temporary Binary outside every activated global or Repository authority root. The runtime entry is keyed by (repository_index, worker_job_index, attempt_count) and carries the token, latest heartbeat time, expiry time, and torn-write detection. It is valid only while the fixed Job is running, its attempt_count matches exactly, the presented token exact-matches, and the runtime expiry has not passed.

The temporary Binary is a disposable runtime replica, not a layout-1 file family. It is excluded from authority manifests, conversion output, Remote Binary transfer, offline compaction, and domain recovery. It cannot make a queued Job running, repair worker_job.bin, or supply Job identity. A missing, corrupt, stale, mismatched, or expired entry invalidates the lease; under the Repository queue lock the server requeues or terminally fails the Job according to its attempt budget, clears locked_at_s, and records lease_expired. Claim returns the token only after the running Job record and runtime mirror are durable. Heartbeat, completion, and failure require the same token while holding the queue lock. Worker identity is diagnostic runtime data and is not stored in either Worker Job authority or the lease token.

Every numeric state, outcome, or error value not assigned here is reserved and fails closed. Full successful result objects belong to the domain records they mutate. Full failure messages belong to the excluded tracing/log or diagnostic projection boundary. Neither is Worker Job authority.

Operational Mutation And Recovery Boundary#

These global and Repository-scoped operational families add no authoritative WAL, journal, transaction ID, or generic generation record. Lock files, temporary replacement files, and fsync bookkeeping are operational filesystem metadata and are not .bin authority. If one mutation needs multiple domain locks, writers acquire the server-global registry lock first, followed by Repository-local queue locks in ascending repository_index, and release them in reverse:

<server-global-registry-root>/01-registry.lock
<server-repository-authority-parent>/<repository_index>/worker-queue.lock

Lock acquisition rejects symlinks and a lock owned by another activated root. A Repository lifecycle transition that inspects or tombstones Jobs acquires the registry lock and its own Repository queue lock in the declared order. A Job mutation acquires only its owning Repository's queue lock. That local lock orders the Worker Job fixed family, the non-authoritative runtime lease replica, both local Job indexes, and each Patchset ci_worker_job_index_plus1 or compact-CI replacement. Readers hold the corresponding shared lock while resolving fixed records; writers hold it exclusively through the domain commit point.

For append creation, the complete fixed detail record is appended and fsynced. The fixed record is the commit point. Rebuildable indexes are written last. The committed record's physical ordinal becomes its permanent worker_job_index; no separate allocator, sequence head, reservation record, payload append, or reusable uncommitted identity exists.

An overwrite uses the existing v0 transaction-layer contract: preserve the complete before-image in non-authoritative recovery storage, write one complete fixed record with reserved bytes zero, fsync it, then discard the before-image. Recovery restores the full before-image unless the replacement reached its domain commit point. Fields inside one fixed record are never independently observable.

Additional domain commit rules are:

• Repository creation stages and fsyncs the real numeric authority directory at the next never-used repository_index, then appends the Repository record and commits at repository.bin. An interrupted pre-commit directory is unreachable staging and is never activated by name. Policy flags, namespace bytes, lifecycle, and update-time changes commit by replacing the complete Repository record.
• Job creation derives the next worker_job_index from the complete committed record count and commits at worker_job.bin inside the owning numeric Repository authority. A non-patchset.ci Job is complete at that point. For patchset.ci, the same queue-locked mutation then replaces the complete owning Patchset record to select the new worker_job_index; that Patchset replacement is the relationship commit point. Interruption before it may leave a valid unselected Job, which cannot supply compact CI evidence.
• A claim increments attempt_count, creates the new runtime lease entry, writes state_kind = running and locked_at_s, and commits authority by replacing the complete Job record. A pre-commit runtime entry is ignored unless the fixed state and attempt count match it exactly. A committed running Job without its valid runtime entry is lease-lost and is requeued or failed under the attempt rule. The token is returned only after both writes are fsynced. Heartbeat exact-compares the token and attempt count, persists the later runtime heartbeat/expiry, and replaces the complete fixed Job record with the same later locked_at_s. Failure invalidates the runtime entry, clears locked_at_s, records the fixed error kind, and either requeues or writes the terminal failed outcome.
• A successful execution commits its result to the existing owning domain authority before replacing the Job with state_kind = succeeded and its fixed outcome and locked_at_s = 0, then invalidates the runtime lease entry. Selected patchset.ci compact evidence is therefore committed by complete Patchset replacement while that Job remains selected before the Job success marker is written. An interrupted domain-first completion is retried idempotently. attached and superseded commit only that terminal outcome; no second Job identity is persisted. A stale runtime entry cannot revive a terminal Job. Queue indexes and scheduling views are repairable.
• A Repository transition to purged first clears every Patchset ci_worker_job_index_plus1 by complete-record replacement while preserving compact CI evidence, then tombstones every live owned Job, and finally commits the complete Repository lifecycle replacement. Interruption before that final replacement restores both Patchset and Job before-images.

Recovery first validates headers, exact record divisibility, reserved zeros, the four fixed Repository slots, Repository UTF-8, namespace bytes, policy flags, timestamps, outcomes, errors, and all fixed-reference invariants. It exact-validates the numeric Repository-directory closure before opening every repository-scoped Worker Job authority. It then builds the full source-index graph and rejects any live reference to an absent, tombstoned, or wrong-owner record; conflicting live non-empty namespaces; or a non-zero Patchset Job locator that does not exact-verify a same-root job_kind = 7 Job whose patchset_index_plus1 selects that Patchset. Duplicate Repository names and equal local Worker Job indexes in different Repository roots are never recovery conflicts.

Only after authority validates may recovery rebuild the registry namespace index and each Repository's local Job indexes. Mutable Repository metadata, Patchset selection, and Job state are never inferred from a later row or an index. Recovery then loads the runtime lease replica; an absent replica is an empty replica. Each entry must exact-match one running Job and its attempt count and must be unexpired; otherwise the entry is discarded and the Job follows the lease-lost rule. An incomplete trailing fixed record is corruption unless the transaction layer proves it is the sole interrupted append. Interior malformed bytes never receive truncation repair.

Operational Capacity And Compaction#

Every fixed family and rebuildable index is limited to u32::MAX - 1 live target indexes because non-zero *_index_plus1 must remain representable. That fixed-family limit applies independently to worker_job.bin in each Repository; no persisted global Job family imposes an additional installation-wide Job-count limit. Because Worker Job tombstones retain their PK slots, its capacity check uses total committed record count rather than live Job count. Direct u32 source values and counts are preflighted before writing. Repository payload offsets and file sizes must fit u64; every offset + length calculation uses checked arithmetic.

Offline compaction writes a new inactive registry root and Repository generation, preserving every exact repository_index and worker_job_index, Repository names, namespace bytes, policy flags, state, kind, fixed references, outcomes, errors, and times. It never reorders, removes, or renumbers a repository.bin or worker_job.bin record; both Repository and Worker Job tombstones retain their slots and no later identity may reuse them. Other physical families may be densely renumbered only after rewriting their complete reference and index closure. Compaction rebuilds the two local Job indexes without changing Job record order or Patchset locators. It does not read, copy, or create the temporary runtime lease replica and validates the complete target before atomic activation.

Changing a fixed width, state assignment, payload grammar, file family, primary-key rule, conversion source boundary, or capacity requires a new layout conversion and compatible readers and writers. An unchanged layout_id does not permit the change.