Files
aevolution/docs/adr/0122-append-only-cellular-genome-revisions.md

4.0 KiB

ADR-0122: Append-only cellular genome revisions

Status

Accepted engineering amendment for M11.4c (2026-10-11). It refines ADR-0034 and ADR-0062 for in-life mutation in cellular lives. It adds no mutation balance or NPC rule.

Context

ADR-0098 requires a living organism to keep its life and organism identities while its genome advances to an immutable successor. The lineage archive currently records the genome assigned at birth and exposes no later genome revision. CellularLives additionally requires that the archive's birth genome equal the live owner's current genome. Without a history amendment, a successor genome cannot be admitted without either losing the birth fact or breaking checkpoint closure.

Decision

  • Keep each OrganismRecord's genome as its immutable birth genome. Add an append-only organism genome-revision record containing organism ID, previous genome ID, successor genome ID, origin event ID and effective tick. It records no selecting account or other actor. The successor genome is already admitted to the same archive, names the previous genome as its parent, and its origin_event equals the recorded event. Revisions apply only to living organisms, after birth and before terminal death, and at most one revision per organism per tick.
  • Add current_genome(organism) to resolve the birth genome followed by the append-only revision chain. Birth identity and history remain queryable; current cellular lives and corpses validate against the final revision at the relevant checkpoint. An organism's life and organism IDs never change during mutation.
  • Extend the archive codec to format 2, preserving canonical format-1 decode and bytes for archives with no genome revisions. The new revision operation and the explicit cellular-v2-to-v3 migration upgrade an archive instance to format 2; format 2 encodes immutable birth records and ordered revision records, then validates by replay and byte-identical re-encoding. No removal or assignment operation is added.
  • Keep all existing environmental-lineage, primitive and cellular-v2 checkpoints on their existing version bundles and format-1 archive bytes. Introduce a cellular-v3 envelope/history profile for the format-2 archive and revised owner closure. It has a fenced no-tick v2-to-v3 migration that preserves all state, including outstanding fed-energy offers, initializes an empty revision list and does not advance biology. New mutation publications use v3 only; previous bundles remain readable and immutable.
  • Recovery replays each mutation event in trace order, admitting the successor genome and appending its revision before validating the resulting owner and archive closure. The replayed head must match its complete committed bytes.

Alternatives

  • Overwrite OrganismRecord.genome: rejected because it erases the birth fact and makes historical organism/genome linkage depend on a mutable value.
  • Track only the current genome in CellularOwnedLife: rejected because the archive could no longer establish every genome an organism carried or replay the history from a checkpoint.
  • Store actor identity in the lineage archive: rejected because the archive records biological origin, while authenticated account and action identity belong to the durable action ledger.
  • Rewrite old archive bytes or profile-4 heads in place: rejected because committed checkpoint payloads and archive encodings are immutable. A leased, no-tick successor commit provides an explicit conversion boundary.

Consequences

This changes the archive public API and codec, cellular owner closure and snapshot version, checkpoint manifest version bundle, migration schema and replay tests. Environmental and primitive checkpoint behavior remains frozen. The added history is bounded by the existing archive genome cap; admission refuses when that cap is reached. Mutation still requires the separate durable selection/publication contract in ADR-0121 and the later client choice work in 11.4d.