Files
aevolution/docs/adr/0062-lineage-checkpoint-profile.md
2026-10-08 12:08:53 -04:00

4.8 KiB

[Reviewed]

ADR-0062: Lineage archive codec and history-capable checkpoint profile

Status

Accepted for M7.4b, 2026-09-28. With ADR-0061 this completes M7.4. Durable decision and history rows are still M7.5. The M7 retained-ancestry exit claim still needs M7.7/M7.9 process-kill recovery evidence.

Context

REGION_DURABILITY.md requires a history-capable profile before retained ancestry can be claimed. That profile must validate:

  • organism-to-genome bindings and parent closure;
  • lifecycle agreement between the simulation and the archive;
  • identity high-waters and archived dead members.

LineageArchive (ADR-0034) had no codec and deliberately has no assignment, so an older copy cannot be written back. The M6 environmental fixture has two organism accounts but no genome linkage, and it uses no randomness.

Decision

Archive codec v1 (LineageArchive::encode/decode, schemas/lineage-archive-v1.md):

  • Genome v1 records are ordered by (ancestry depth, id), so parents precede children. Organisms follow in id order, as 33-byte records.
  • A trailing FNV-1a64 detects corruption. The caps are the existing 4096 genomes and 65536 organisms, at most 3,219,496 bytes, checked before allocation.
  • Decoding constructs a new archive by replaying admit, record_birth and record_death, so retention, parent presence, death finality and tick order are re-established by the archive's own rules. A byte-identical re-encoding is required, so equal content has exactly one encoding.
  • Decoding never overwrites an existing archive. Refusing an older checkpoint is the committed chain's job (ADR-0061): recovery only ever loads the head.

LineageRegion (processes, headless) holds the environmental community, its archive, the binding of the producer and consumer accounts to archived organisms, and the next organism and genome identities.

Closure requires:

  • both bound organisms are recorded;
  • each terminal flag equals the archive's death state;
  • no birth or death is after the current tick;
  • the archive's living organisms are exactly the bound, non-terminal ones, so there is no unowned living state;
  • both high-waters are above every recorded identity.

advance records each terminal transition as an archive death at that tick. A checkpoint therefore cannot split a death from the state that caused it. The container is schemas/environmental-lineage-v1.md: header, binding, envelope, archive and FNV.

Checkpoint profile 2 is environmental-lineage-v1, with history profile 1 (archive 1 + genome schema 1). It uses the same nine version slots and zero RNG streams, and its payload cap is 72 + 1 MiB + 3,219,496 bytes. The manifest structure is unchanged, and profile and history profile must agree.

Schema v4 replaces the SQL parser to admit profile 2 with its cap. Publication additionally requires the predecessor's exact profile, RNG, history and durability declarations. Grants are unchanged. Linux adds provision/publish/recover_lineage_checkpoint on the same publication and recovery path as profile 1; each path refuses the other profile.

Alternatives Considered

  • Extending environmental-v1 with optional sections: forbidden, because empty sections cannot stand in for missing history.
  • Admission-order encoding: it is not recoverable from the archive and would make equal content encode differently.
  • Deaths recorded by the host after the tick could be split from the state across a checkpoint.
  • A separate history object would need its own atomic publication; one container shares the manifest's digest and fence.

Benefits

  • Retained genomes, ancestry and dead organisms now survive checkpoint recovery and must agree with the simulation state that references them.
  • Decode reuses the archive's invariants rather than duplicating them.
  • Existing environmental-v1 regions are unaffected.

Costs

  • The whole archive is rewritten with every batch. A full archive is about 2.5 MiB in the measured test, up to about 3.2 MiB.
  • Decode is O(genomes²) in the worst case because of sorted insertion.
  • Archive memory is bounded by the fixed caps rather than charged to a budget.

Risks

  • The environmental fixture has no reproduction, so births within a batch are not exercised. A reproducing profile needs its own closure rules.
  • Durable history rows (M7.5) must agree with the checkpoint's archive. Only the checkpoint side exists yet.
  • FNV is not authentication; SHA-256 at the manifest covers the payload.

Consequences

  • M7.5 adds death decisions, history rows and outbox rows derived from these transitions, in the same transaction.
  • M7.7 recovers this profile after a process kill.
  • M7.9 retains builds that can decode archive 1 and genome schema 1, and qualifies retained ancestry end to end.
  • A new genome schema or archive format needs a new history profile value and a migration.