Files
aevolution/docs/adr/0034-lineage-archive.md
T
dingoandClaude Opus 5.5 a2c4543df2 Complete M7.4b lineage checkpoint profile; M7.4 done
ADR-0062 adds a canonical LineageArchive codec (parents before children,
organisms by id, FNV) that decodes by replaying admit/record_birth/
record_death and requires byte-identical re-encoding; it never overwrites
an existing archive. LineageRegion binds the environmental producer and
consumer accounts to archived organisms with identity high-waters,
enforces closure (lifecycle vs deaths, exact living set, tick bounds)
and records deaths in the tick that causes them.

Checkpoint profile 2 (environmental-lineage-v1, history profile 1)
publishes that container; schema v4 admits it with a 4,268,144-byte cap
and requires each commit to keep its predecessor's profile, RNG, history
and durability declarations. Linux adds provision/publish/recover for
the profile on the shared publication path.

Qualification found WSL2 stepping CLOCK_REALTIME back ~0.5 s every ~32 s,
which made two 1 s-lease tests flaky under ASan. Tests now wait on
database-time expiry; ADR-0060 records the slewed-clock requirement.

Validated: Windows CTest 57/57; Linux GCC Debug/Release, clang-tidy and
ASan/UBSan CTest 57/57 each; PostgreSQL suites 2x Release, 2x analysis,
5x ASan; SQL and C++ mutations each caught. No Docker/Gitea CI, remote
store, process kill or deployment.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-28 16:43:10 -04:00

121 lines
6.5 KiB
Markdown

# ADR-0034: Permanent lineage archive and provisional absence
## Status
Adopted for M3.5. ADR-0062 (M7.4b) adds the whole-archive codec, which
decodes by replaying these same admission, birth and death rules and never
overwrites an existing archive. It does not settle NPC mutation, which the roadmap lists as a
dependency and OPEN_QUESTIONS leaves open until M12: the archive records an origin
event and never an actor, so whether an NPC may diverge changes nothing here.
Durable storage, retention tiers and cross-version migration remain M7 and M8.
## Context
M3.4 can produce a successor genome, but nothing keeps it. Three documents agree
on what keeping must mean. GENOME_MODEL: keep extinct genomes and ancestry
indefinitely. REPRODUCTION_MODEL: death is terminal for the organism ID, and
genome, ancestry, origin and extinction evidence are preserved permanently.
ECOLOGY_MODEL is the sharpest: distinguish no active observation from ecological
absence from terminal extinction, require a globally reconciled watermark before
claiming the last, and never let a density rounded to zero declare irreversible
extinction.
The named risk is deleting extinct genomes. The quieter one is calling something
extinct that is merely unobserved.
## Decision
Add `LineageArchive`, which retains genomes and the organisms that carried them.
It has no removal operation at all. Not a guarded one, not a private one: the
type offers no way to forget, so no caller and no later change can delete a record
by choosing to. Retention is a property of the interface rather than a rule
someone has to remember.
Forgetting has forms that are not named like removal, so the copy and move policy
is part of that interface rather than left to the defaults. Assignment discards
every record the target holds, which is deletion however it is spelled, and it
would also allow a copy taken earlier to be written back, restoring an organism
the archive had already recorded as dead. Both forms of assignment are therefore
deleted, which also makes the archive unswappable, since swapping needs them.
Declaring the copy constructor suppresses the implicit moves, so a move decays to
a copy and a moved-from archive still holds every record rather than being emptied
the way a moved-from container would be. Copying itself stays available: a clone
takes nothing from the original, and GENOME_MODEL expects migrations to be
rehearsed on cloned worlds.
A genome is admitted only if its parent is already present, so ancestry is always
walkable and no link dangles. That ordering also makes the parent graph acyclic by
construction: admitting a cycle would require one of its members to be admitted
before itself. Duplicate genome IDs are refused rather than overwriting, because
overwriting is deletion wearing another name.
Organism identity and genome identity stay separate, as REPRODUCTION_MODEL
requires. Many organisms may carry one genome; a birth names both, a death names
only the organism. Death is terminal: a dead organism cannot act, die twice or be
reborn. Nothing about a death touches the genome it carried.
The archive therefore reports a lineage as living or absent, and has no third
answer. Absent means no organism now carries it, which is a fact the archive can
establish about itself. Terminal extinction is a policy judgement over a
reconciled world watermark covering suspended members, eggs, spores and in-flight
transfers, none of which exist yet and none of which this type can see. Calling
absence extinction would be exactly the failure ECOLOGY_MODEL names, so the word
does not appear in the API.
Divergence is answered by a most recent common ancestor over the retained parent
links, which is meaningful precisely because nothing was ever removed.
Capacity is bounded and admission fails loudly when it is reached. Refusing to
record is not deleting, and a silent drop would be. Real retention, tiering and
durability are M7 and M8 work, and this bound is a fixture limit, not a policy.
## Alternatives Considered
Leaving the copy and move policy to the defaults was the original mistake here:
the type had no method named like removal and still forgot everything on
assignment. Deleting the move constructor as well would have been stricter but
would stop an archive being returned from a function, so it is left to decay to a
copy. Forbidding copies entirely would block the cloned-world rehearsal the
documents call for while preventing nothing, since a copy removes nothing.
Pruning lineages with no living carrier is the named risk, and is wrong even as an
optimisation: an absent lineage is the evidence that something happened. A
`extinct` status would claim a conclusion the archive cannot support. Allowing a
genome to be re-admitted under an existing ID would silently destroy the earlier
record. Letting a child be admitted before its parent would leave ancestry walks
dangling and would permit a cycle. Storing a mutating actor alongside the origin
event would settle NPC mutation by implication. An unbounded archive would fail by
exhaustion rather than by saying so.
## Benefits
Ancestry survives every death by construction rather than by discipline. A
lineage can be walked to its founder, its descendants enumerated and two lineages
compared, all from records nothing can remove. Absence is reported honestly and
separately from a conclusion nobody is yet entitled to draw.
## Costs
The archive only grows, so a long run holds every genome it ever made. Ancestry
walks are linear in depth and descendant queries linear in the archive, which is
fine at fixture scale and is not an index. Organism records are in memory only:
nothing is serialized, so nothing survives a process.
## Risks
Do not read absence as extinction, in code or in a report. Do not read the
capacity bound as a retention policy. The archive says nothing about who caused a
mutation, whether NPCs may mutate, what an organism was doing, or whether a
lineage was viable; a lineage with no living carrier may have been perfectly
viable and merely unlucky. Nothing here is durable, and nothing replays.
## Consequences
Test that a genome outlives every organism that carried it, that ancestry and
descendants still resolve after all carriers die, that branching lineages resolve
their common ancestor, that admission refuses a duplicate ID, an unknown parent
and a full archive, that death is terminal and cannot be repeated or undone, that
a lineage with no living carrier reports absent rather than extinct, and that the
type exposes no operation that removes anything. No genome schema, mutation
catalog, ledger, fixture, renderer or deployment changes.