From 8020347f9b2d16ea8026b68060363374c14acfd1 Mon Sep 17 00:00:00 2001 From: dingo Date: Wed, 23 Sep 2026 16:55:36 -0400 Subject: [PATCH] Keep every lineage, and never call absence extinction M3.5 retains the genomes M3.4 produces and the organisms that carried them. The named risk is deleting extinct genomes, so the answer is structural: LineageArchive has no removal operation at all, not a guarded one and not a private one. Retention is a property of the interface rather than a rule someone has to remember, which is the only form of "keep extinct genomes indefinitely" that a later change cannot quietly undo. Four concepts assert that, with a positive control so the check is known to be live rather than vacuous. Admission requires the parent to be present, so ancestry never dangles and the parent graph is acyclic by construction: a cycle would need one of its members admitted before itself. A duplicate identity is refused rather than overwritten, because overwriting is deletion renamed. Organism identity and genome identity stay separate. A death is terminal for the organism and touches nothing about the genome it carried; ancestry, descendants and divergence all resolve afterwards. The quieter risk is calling something extinct that is merely unobserved. The archive reports living or absent and has no third answer: terminal extinction is a policy judgement over a reconciled watermark covering suspended members, eggs, spores and in-flight transfers, none of which this type can see, so the word does not appear in the API. Absence is also reversible, and a test shows a lineage regaining a carrier. Capacity is bounded and admission fails loudly at the limit, since refusing to record is not deleting but a silent drop would be. The roadmap lists an NPC-mutation decision as a dependency, and OPEN_QUESTIONS leaves it open until M12. It stays open: the archive records an origin event and never an actor, so whether an NPC may diverge changes nothing here. Two clang-tidy findings were fixed rather than suppressed. std::map members made the archive's move potentially throwing, because MSVC's map move constructor allocates; sorted vectors replaced them. A wrapper struct holding a Genome by value had the same problem, since ADR-0030 made Genome copy-only, so genomes are stored directly under their own id(). The redundant carrier tally went with it: carriers are counted from the organism records, so no second tally can drift. Native Release, clang-tidy analysis, ASan and format checks pass 21/21. Co-Authored-By: Claude Opus 5 --- CMakeLists.txt | 7 +- README.md | 3 +- docs/ROADMAP.md | 8 +- docs/STATUS.md | 23 +++- docs/adr/0034-lineage-archive.md | 99 +++++++++++++ docs/adr/README.md | 1 + docs/biology/GENOME_MODEL.md | 33 ++++- docs/engineering/VALIDATION.md | 45 ++++++ include/evo/biology/lineage.hpp | 81 +++++++++++ src/biology/lineage.cpp | 173 +++++++++++++++++++++++ tests/lineage_tests.cpp | 230 +++++++++++++++++++++++++++++++ 11 files changed, 696 insertions(+), 7 deletions(-) create mode 100644 docs/adr/0034-lineage-archive.md create mode 100644 include/evo/biology/lineage.hpp create mode 100644 src/biology/lineage.cpp create mode 100644 tests/lineage_tests.cpp diff --git a/CMakeLists.txt b/CMakeLists.txt index dd2f85e..4f0fd71 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -40,7 +40,7 @@ target_include_directories(evo_accounting PUBLIC "${CMAKE_CURRENT_SOURCE_DIR}/in target_compile_features(evo_accounting PUBLIC cxx_std_23) evo_owned_target(evo_accounting) -add_library(evo_biology STATIC src/biology/genome.cpp src/biology/development.cpp src/biology/metabolism.cpp src/biology/mutation.cpp) +add_library(evo_biology STATIC src/biology/genome.cpp src/biology/development.cpp src/biology/metabolism.cpp src/biology/mutation.cpp src/biology/lineage.cpp) add_library(evo::biology ALIAS evo_biology) target_include_directories(evo_biology PUBLIC "${CMAKE_CURRENT_SOURCE_DIR}/include") target_link_libraries(evo_biology PUBLIC evo::accounting) @@ -88,6 +88,11 @@ if(BUILD_TESTING) evo_owned_target(evo-mutation-tests) add_test(NAME mutation-contracts COMMAND evo-mutation-tests) set_tests_properties(mutation-contracts PROPERTIES TIMEOUT 120) + add_executable(evo-lineage-tests tests/lineage_tests.cpp) + target_link_libraries(evo-lineage-tests PRIVATE evo::biology) + evo_owned_target(evo-lineage-tests) + add_test(NAME lineage-contracts COMMAND evo-lineage-tests) + set_tests_properties(lineage-contracts PROPERTIES TIMEOUT 120) add_executable(evo-producer-tests tests/producer_tests.cpp) target_link_libraries(evo-producer-tests PRIVATE evo::processes) evo_owned_target(evo-producer-tests) diff --git a/README.md b/README.md index f064c23..d83a004 100644 --- a/README.md +++ b/README.md @@ -96,7 +96,8 @@ producer, feeding, reproduction and episode fixtures built on that ledger; they are bounded experiments, not organism biology. `src/biology` holds the immutable genome record, the deterministic development that derives a phenotype from it and the metabolic budgets that give capability a cost, and the seeded mutation -catalog that proposes successors. No fixture reads a genome yet. +catalog that proposes successors and the archive that keeps them. No fixture reads +a genome yet. `apps/evo-sim` owns CLI/file I/O and reporting. `tests` holds contract, fuzz and measurement programs. Future biology, world, networking and persistence diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index d275431..7547d96 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -89,7 +89,13 @@ itself, drawn uniformly without replacement from a recorded context and returned in canonical order with nothing ranked. Selection regenerates the offer and refuses a changed context rather than substituting. Candidate count, mutation cost as a game rule, inherited versus acquired expression, NPC mutation and -recombination stay open, and no organism mutates yet. +recombination stay open, and no organism mutates yet. M3.5 keeps what M3.4 +produces (ADR-0034): an archive with no removal operation at all, so retention is +a property of the interface rather than a rule. A genome outlives every organism +that carried it, ancestry and descendants resolve through dead links, and a +lineage with no living carrier is reported absent and never extinct, because +terminal extinction needs a reconciled watermark this type cannot see. NPC +mutation stays undecided: the archive records an origin event and never an actor. ## M3 — Genome v0.1 diff --git a/docs/STATUS.md b/docs/STATUS.md index 6ff90bf..1c2e37d 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -7,7 +7,7 @@ persistent simulation server. The founding vision remains unchanged. ## Completed implementation - Vision, architectural pillars, risks, open-question register, architecture - diagrams, biological contracts, engineering constitution and 33 ADRs. + diagrams, biological contracts, engineering constitution and 34 ADRs. Proposed/deferred choices remain distinct from accepted proof decisions. - M0–M4 task breakdowns with dependencies, acceptance evidence and risks, plus M5–M14 gates in [ROADMAP.md](ROADMAP.md). @@ -61,8 +61,8 @@ for the bounded proof; the general production ECS remains a later measured choic | Priority | Work | Completion evidence | |---|---|---| -| 1 | M3.5 heredity and divergence history | Reproduction persists parent/child links; genome identity survives death; extinct genomes are never deleted | -| 2 | M3.6 genome ecology ensembles | Strategies compared under resource and temperature gradients, with conservation and a diversity report | +| 1 | M3.6 genome ecology ensembles | Strategies compared under resource and temperature gradients, with conservation and a diversity report; closes M3 | +| 2 | M4.1 cohort state and ownership | Genome, lineage, counts, age, reserves, residuals and ownership made explicit | | Delivery gate | Add/update the dev workload when a deployable increment needs it; Argo is ready | Observe Job/pod completion separately from image publication; no World0 changes | M1.6 now implements [the sequential scheduler contract](architecture/SCHEDULER_CONTRACT.md): @@ -225,6 +225,23 @@ inherited versus acquired expression, NPC mutation and recombination stay open; no organism mutates. Native Release, analysis, ASan and formatting passed 20/20; Linux CI has not run yet. +M3.5 keeps what M3.4 produces (ADR-0034). `LineageArchive` has no removal +operation at all, so retention is a property of the interface rather than a rule +someone has to remember, which is the only form of "keep extinct genomes +indefinitely" a later change cannot quietly undo. Admission requires the parent to +be present, so ancestry never dangles and the parent graph is acyclic by +construction; a duplicate identity is refused rather than overwritten. Organism +and genome identity stay separate: a death is terminal for the organism and +touches nothing about the genome, and ancestry, descendants and divergence all +resolve after every carrier has died. A lineage with no living carrier is reported +absent, never extinct, because terminal extinction needs a reconciled watermark +covering suspended members, eggs and in-flight transfers that this type cannot +see; absence is also reversible. Capacity is bounded and admission fails loudly, +since refusing to record is not deleting. NPC mutation stays undecided: the +archive records an origin event and never an actor. Nothing is serialized, so +durable retention and migration remain M7 and M8. Native Release, analysis, ASan +and formatting passed 21/21; Linux CI has not run yet. + Before biology, resolve the relevant heredity and energetic contracts rather than treating proof particles as organisms. Exact game tick rate, NPC mutation, logout treatment, species/extinction rules and multicellular transition remain diff --git a/docs/adr/0034-lineage-archive.md b/docs/adr/0034-lineage-archive.md new file mode 100644 index 0000000..e743b3c --- /dev/null +++ b/docs/adr/0034-lineage-archive.md @@ -0,0 +1,99 @@ +# ADR-0034: Permanent lineage archive and provisional absence + +## Status + +Adopted for M3.5. 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. + +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 + +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. diff --git a/docs/adr/README.md b/docs/adr/README.md index fdf0173..0bebf52 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -26,6 +26,7 @@ Each record has the eight required sections. 0031 adopts deterministic development, derived phenotype and bounded plans. 0032 derives non-uniform metabolic budgets and the first genome/ledger path. 0033 adopts the bounded mutation catalog and uniform seeded candidate draws. +0034 adopts the permanent lineage archive and absence that is never extinction. Every dependency adoption records exact version/commit and integrity hash, transitive license obligations, maintenance/security review, owner and removal diff --git a/docs/biology/GENOME_MODEL.md b/docs/biology/GENOME_MODEL.md index 4a1a165..44f9b8c 100644 --- a/docs/biology/GENOME_MODEL.md +++ b/docs/biology/GENOME_MODEL.md @@ -230,4 +230,35 @@ Uniform offering is not a claim about real mutation rates, and the catalog is no a claim about which mutations are possible in biology. Candidate count, context window, mutation cost as a game rule, inherited versus acquired expression, NPC mutation and recombination all remain open, exactly as stated above. No organism -mutates, no fixture calls any of this, and heredity history is M3.5. +mutates, and no fixture calls any of this. + +## Implemented M3.5 lineage retention + +[ADR-0034](../adr/0034-lineage-archive.md) keeps what M3.4 produces. `LineageArchive` +has no removal operation: not a guarded one, not a private one. Retention is a +property of the interface rather than a rule anyone has to remember, which is the +only form of "keep extinct genomes indefinitely" that a later change cannot quietly +undo. + +A genome is admitted only if its parent is already present, so ancestry never +dangles and the parent graph is acyclic by construction: a cycle would need one of +its members admitted before itself. Duplicate identities are refused rather than +overwritten, because overwriting is deletion wearing another name. + +Organism identity and genome identity stay separate. Many organisms may carry one +genome; a birth names both, a death names only the organism, and death is terminal +for that organism and touches nothing about the genome. Ancestry, descendants and +divergence all resolve after every carrier has died. + +The archive reports a lineage as living or absent, and has no third answer. +Absence means no organism now carries it, which the archive can establish about +itself. Terminal extinction is a policy judgement over a reconciled watermark +covering suspended members, eggs, spores and in-flight transfers, none of which +exist yet and none of which this type can see, so the word does not appear in the +API. Absence is also reversible: a lineage with no carrier can gain one again. + +Capacity is bounded and admission fails loudly at the limit. Refusing to record is +not deleting; a silent drop would be. Durable storage, retention tiers and +cross-version migration are M7 and M8 work, and nothing here is serialized. NPC +mutation stays undecided, because the archive records an origin event and never an +actor. diff --git a/docs/engineering/VALIDATION.md b/docs/engineering/VALIDATION.md index 095958a..5d94834 100644 --- a/docs/engineering/VALIDATION.md +++ b/docs/engineering/VALIDATION.md @@ -643,3 +643,48 @@ mutation and recombination remain open and are not settled here. Golden `d61ad5bf0c928c76`, ecosystem fingerprint `2cd4a15f9fbe9949` and the frozen genome fixture are unchanged. No deployment manifest or image pin changed. Linux validation is pending; no Gitea result is claimed since `b01a824`. + + +## M3.5 lineage retention (2026-09-23) + +Native Release, analysis and MSVC ASan each passed 21/21 CTests; formatting +passed. Commands: `tools/windows-check.ps1 -Preset +-Action check` and debug `-Action format`. `lineage-contracts` is the one new +CTest case, in the existing `evo::biology` library. No existing suite changed. + +Retention is asserted as a property of the type, not only of its behaviour: four +concepts check that the archive offers no `erase`, `remove`, `clear` or `prune`, +with a std::map positive control so the checks are known to be live rather than +vacuously true. An earlier attempt used bare requires-expressions, which MSVC +diagnoses eagerly for a non-dependent type, and a std::vector control, which was +wrong because `vector::erase` takes an iterator rather than a key; the concept +correctly reported false and the control was corrected rather than the assertion +weakened. + +A branching fixture of five genomes over three generations is used throughout. +Tests cover a genome outliving both organisms that carried it with its record, +ancestry, children and organism terminal ticks intact; ancestry and descendants +resolving through a genome whose only carrier died; common ancestors for +siblings, cousins, a genome against itself and two separate founders; refusal of +a duplicate identity, a child admitted before its parent and a full archive; +death being terminal against repeat, reversal and rebirth; and absence being +reported for every lineage that has no living carrier, including one that gains a +carrier again afterwards. The capacity case admits the full 4,096 genomes as one +chain, checks that the refusal leaves every earlier record intact, and walks the +4,096-deep ancestry. + +The implementation was changed twice under clang-tidy rather than suppressed. +`std::map` members made the archive's move potentially throwing, because MSVC's +map move constructor allocates a sentinel node; sorted vectors replaced them, +which also matches the rest of the codebase. A wrapper struct holding a `Genome` +by value then had the same problem, because ADR-0030 made `Genome` copy-only, so +genomes are now stored directly and identified by their own `id()`. The redundant +per-genome carrier tally was dropped in the same change: carriers are counted from +the organism records, so there is no second tally that could drift. + +Nothing is serialized, so no history survives a process, and no fixture calls any +of this. Terminal extinction is not claimed anywhere, durable retention and +migration are M7 and M8, and NPC mutation remains undecided. Golden +`d61ad5bf0c928c76`, ecosystem fingerprint `2cd4a15f9fbe9949` and the frozen genome +fixture are unchanged. No deployment manifest or image pin changed. Linux +validation is pending; no Gitea result is claimed since `b01a824`. diff --git a/include/evo/biology/lineage.hpp b/include/evo/biology/lineage.hpp new file mode 100644 index 0000000..e6e8d74 --- /dev/null +++ b/include/evo/biology/lineage.hpp @@ -0,0 +1,81 @@ +#pragma once + +#include "evo/biology/genome.hpp" +#include "evo/core/types.hpp" + +namespace evo::biology { +// What the archive can establish about itself. There is deliberately no third +// value: terminal extinction is a policy judgement over a reconciled world +// watermark covering suspended members, eggs, spores and in-flight transfers, +// none of which this type can see. Absence is not extinction. +enum class LineageStatus : std::uint8_t { living, absent }; +struct OrganismRecord { + std::uint64_t genome; + Tick born; + Tick died; // meaningful only once alive is false + bool alive; // death is terminal; this never returns to true + auto operator<=>(const OrganismRecord&) const = default; +}; +enum class HistoryError : std::uint8_t { + duplicate_genome, + unknown_genome, + unknown_parent, + archive_full, + duplicate_organism, + unknown_organism, + already_dead, + invalid_identity, + invalid_tick +}; +inline constexpr std::size_t max_archived_genomes = 4'096; +inline constexpr std::size_t max_archived_organisms = 65'536; + +// Retains genomes and the organisms that carried them. There is no removal +// operation: not a guarded one, not a private one. Retention is a property of +// this interface rather than a rule a caller has to remember. +class LineageArchive { + public: + // A parent must already be present, so ancestry never dangles and the parent + // graph cannot contain a cycle: a cycle would need a member admitted first. + [[nodiscard]] std::expected admit(const Genome& genome); + [[nodiscard]] std::expected record_birth(std::uint64_t organism, + std::uint64_t genome, Tick when); + // Terminal for the organism, and nothing to do with the genome it carried. + [[nodiscard]] std::expected record_death(std::uint64_t organism, Tick when); + + [[nodiscard]] std::expected find(std::uint64_t genome) const; + [[nodiscard]] std::expected + organism(std::uint64_t identity) const; + // Oldest first, ending at the founder. Still resolves after every carrier dies. + [[nodiscard]] std::expected, HistoryError> + ancestry(std::uint64_t genome) const; + [[nodiscard]] std::expected, HistoryError> + children(std::uint64_t genome) const; + // Zero when the two descend from different founders. + [[nodiscard]] std::expected + common_ancestor(std::uint64_t left, std::uint64_t right) const; + // Counted from the organism records themselves rather than kept alongside + // them, so there is no second tally that could drift out of agreement. + [[nodiscard]] std::expected + living_carriers(std::uint64_t genome) const; + [[nodiscard]] std::expected status(std::uint64_t genome) const; + [[nodiscard]] std::size_t archived() const noexcept { + return genomes_.size(); + } + [[nodiscard]] std::size_t recorded() const noexcept { + return organisms_.size(); + } + + private: + struct ArchivedOrganism { + std::uint64_t id; + OrganismRecord record; + }; + // Held sorted by identity, so a lookup is a binary search and the archive + // keeps one record of each thing and no index that could disagree. Genomes + // are stored directly rather than in a wrapper: a genome is copy-only by + // ADR-0030, so an aggregate holding one would have a throwing move. + std::vector genomes_; + std::vector organisms_; +}; +} // namespace evo::biology diff --git a/src/biology/lineage.cpp b/src/biology/lineage.cpp new file mode 100644 index 0000000..0534229 --- /dev/null +++ b/src/biology/lineage.cpp @@ -0,0 +1,173 @@ +#include "evo/biology/lineage.hpp" + +#include + +namespace evo::biology { +namespace { +constexpr auto by_organism = [](const auto& entry) { return entry.id; }; +constexpr auto by_genome = [](const Genome& record) { return record.id(); }; + +template +auto locate(Records& records, std::uint64_t identity, Identify identify) { + return std::ranges::lower_bound(records, identity, {}, identify); +} +template +bool holds(const Records& records, std::uint64_t identity, Identify identify) { + const auto found = locate(records, identity, identify); + return found != records.end() && identify(*found) == identity; +} +} // namespace + +std::expected LineageArchive::admit(const Genome& genome) { + if (genomes_.size() >= max_archived_genomes) { + // Refusing to record is not deleting; a silent drop would be. + return std::unexpected{HistoryError::archive_full}; + } + const auto slot = locate(genomes_, genome.id(), by_genome); + // Overwriting an existing record is deletion wearing another name. + if (slot != genomes_.end() && slot->id() == genome.id()) { + return std::unexpected{HistoryError::duplicate_genome}; + } + for (const auto parent : genome.parents()) { + if (!holds(genomes_, parent, by_genome)) { + return std::unexpected{HistoryError::unknown_parent}; + } + } + genomes_.insert(slot, genome); + return {}; +} + +std::expected LineageArchive::record_birth(std::uint64_t organism, + std::uint64_t genome, Tick when) { + if (organism == 0) { + return std::unexpected{HistoryError::invalid_identity}; + } + if (organisms_.size() >= max_archived_organisms) { + return std::unexpected{HistoryError::archive_full}; + } + if (!holds(genomes_, genome, by_genome)) { + return std::unexpected{HistoryError::unknown_genome}; + } + const auto slot = locate(organisms_, organism, by_organism); + // An identity is never reused, alive or dead, so this is not a search for a + // free slot: a repeat is a mistake and is reported as one. + if (slot != organisms_.end() && slot->id == organism) { + return std::unexpected{HistoryError::duplicate_organism}; + } + organisms_.insert(slot, ArchivedOrganism{organism, OrganismRecord{genome, when, {}, true}}); + return {}; +} + +std::expected LineageArchive::record_death(std::uint64_t organism, Tick when) { + const auto found = locate(organisms_, organism, by_organism); + if (found == organisms_.end() || found->id != organism) { + return std::unexpected{HistoryError::unknown_organism}; + } + if (!found->record.alive) { + return std::unexpected{HistoryError::already_dead}; + } + if (when < found->record.born) { + return std::unexpected{HistoryError::invalid_tick}; + } + found->record.alive = false; + found->record.died = when; + // The organism is gone. Its genome, ancestry and origin are untouched. + return {}; +} + +std::expected LineageArchive::find(std::uint64_t genome) const { + const auto found = locate(genomes_, genome, by_genome); + if (found == genomes_.end() || found->id() != genome) { + return std::unexpected{HistoryError::unknown_genome}; + } + return *found; +} + +std::expected LineageArchive::organism(std::uint64_t identity) const { + const auto found = locate(organisms_, identity, by_organism); + if (found == organisms_.end() || found->id != identity) { + return std::unexpected{HistoryError::unknown_organism}; + } + return found->record; +} + +std::expected, HistoryError> +LineageArchive::ancestry(std::uint64_t genome) const { + if (!holds(genomes_, genome, by_genome)) { + return std::unexpected{HistoryError::unknown_genome}; + } + // Admission order makes the parent graph acyclic, so this terminates. + std::vector line; + auto current = genome; + while (true) { + line.push_back(current); + const auto& record = *locate(genomes_, current, by_genome); + if (record.parents().empty()) { + break; + } + current = record.parents()[0]; + } + std::ranges::reverse(line); // Founder first. + return line; +} + +std::expected, HistoryError> +LineageArchive::children(std::uint64_t genome) const { + if (!holds(genomes_, genome, by_genome)) { + return std::unexpected{HistoryError::unknown_genome}; + } + std::vector descendants; + for (const auto& record : genomes_) { + if (!record.parents().empty() && record.parents()[0] == genome) { + descendants.push_back(record.id()); + } + } + return descendants; +} + +std::expected +LineageArchive::common_ancestor(std::uint64_t left, std::uint64_t right) const { + const auto one = ancestry(left); + if (!one) { + return std::unexpected{one.error()}; + } + const auto other = ancestry(right); + if (!other) { + return std::unexpected{other.error()}; + } + // Both lines start at their founder, so the last shared prefix entry is the + // most recent common ancestor. Zero when the founders differ. + std::uint64_t shared = 0; + for (std::size_t index = 0; index < one->size() && index < other->size(); ++index) { + if ((*one)[index] != (*other)[index]) { + break; + } + shared = (*one)[index]; + } + return shared; +} + +std::expected +LineageArchive::living_carriers(std::uint64_t genome) const { + if (!holds(genomes_, genome, by_genome)) { + return std::unexpected{HistoryError::unknown_genome}; + } + std::uint64_t carrying = 0; + for (const auto& entry : organisms_) { + if (entry.record.alive && entry.record.genome == genome) { + ++carrying; + } + } + return carrying; +} + +std::expected LineageArchive::status(std::uint64_t genome) const { + const auto carrying = living_carriers(genome); + if (!carrying) { + return std::unexpected{carrying.error()}; + } + // Absent, never extinct: this type cannot see the world watermark that a + // claim of terminal extinction would require. + return *carrying == 0 ? LineageStatus::absent : LineageStatus::living; +} +} // namespace evo::biology diff --git a/tests/lineage_tests.cpp b/tests/lineage_tests.cpp new file mode 100644 index 0000000..ad345a2 --- /dev/null +++ b/tests/lineage_tests.cpp @@ -0,0 +1,230 @@ +#include "evo/biology/lineage.hpp" + +#include +#include +#include +#include +#include +#include +#include +#include + +namespace { +using namespace evo::biology; +void check(bool condition, std::source_location location = std::source_location::current()) { + if (!condition) { + throw std::runtime_error("lineage line " + std::to_string(location.line())); + } +} +#define CHECK(expression) check(static_cast(expression)) +Genome descend(std::uint64_t id, std::uint64_t parent, std::uint32_t conversion = 400) { + GenomeDraft source; + source.id = id; + source.origin_event = id; + source.development_version = 1; + if (parent != 0) { + source.parents = {parent}; + } + source.capabilities = {{Capability::energy_conversion, conversion, 0}, + {Capability::membrane, 120, 0}, + {Capability::target_size, 8'000'000, 0}}; + const auto genome = Genome::create(source); + check(genome.has_value()); + return *genome; +} +// A founder with two branches, one of which branches again: +// 1 -> 2 -> 4, 5 +// -> 3 +LineageArchive branching() { + LineageArchive archive; + check(archive.admit(descend(1, 0, 400)).has_value()); + check(archive.admit(descend(2, 1, 409)).has_value()); + check(archive.admit(descend(3, 1, 391)).has_value()); + check(archive.admit(descend(4, 2, 418)).has_value()); + check(archive.admit(descend(5, 2, 400)).has_value()); + return archive; +} + +void a_genome_outlives_every_organism_that_carried_it() { + auto archive = branching(); + CHECK(archive.record_birth(100, 4, evo::Tick{10})); + CHECK(archive.record_birth(101, 4, evo::Tick{12})); + CHECK(archive.living_carriers(4) && *archive.living_carriers(4) == 2); + CHECK(*archive.status(4) == LineageStatus::living); + CHECK(archive.record_death(100, evo::Tick{30})); + CHECK(*archive.living_carriers(4) == 1 && *archive.status(4) == LineageStatus::living); + CHECK(archive.record_death(101, evo::Tick{31})); + // No organism carries it now. Everything about the genome is still here. + CHECK(*archive.living_carriers(4) == 0); + CHECK(*archive.status(4) == LineageStatus::absent); + const auto kept = archive.find(4); + CHECK(kept && kept->id() == 4 && kept->parents()[0] == 2); + CHECK(*kept == descend(4, 2, 418)); + const auto line = archive.ancestry(4); + CHECK(line && (*line == std::vector{1, 2, 4})); + CHECK(archive.children(2) && archive.children(2)->size() == 2); + // The organisms themselves are still on record, with their terminal ticks. + const auto first = archive.organism(100); + CHECK(first && !first->alive && first->genome == 4); + CHECK(first->born.value == 10 && first->died.value == 30); +} + +void ancestry_and_descendants_resolve_through_a_dead_middle() { + auto archive = branching(); + // Every carrier of the middle genome dies; its children are untouched. + CHECK(archive.record_birth(200, 2, evo::Tick{5})); + CHECK(archive.record_birth(201, 4, evo::Tick{6})); + CHECK(archive.record_death(200, evo::Tick{20})); + CHECK(*archive.status(2) == LineageStatus::absent); + CHECK(*archive.status(4) == LineageStatus::living); + const auto through = archive.ancestry(4); + CHECK(through && (*through == std::vector{1, 2, 4})); + const auto kids = archive.children(2); + CHECK(kids && (*kids == std::vector{4, 5})); + // The founder has no living carrier either, and is equally intact. + CHECK(*archive.status(1) == LineageStatus::absent); + CHECK(archive.find(1) && archive.find(1)->parents().empty()); + CHECK(archive.ancestry(1) && archive.ancestry(1)->size() == 1); +} + +void branching_lineages_resolve_their_divergence() { + auto archive = branching(); + CHECK(archive.common_ancestor(4, 5) && *archive.common_ancestor(4, 5) == 2); + CHECK(*archive.common_ancestor(4, 3) == 1); + CHECK(*archive.common_ancestor(2, 3) == 1); + CHECK(*archive.common_ancestor(4, 2) == 2); // An ancestor of itself. + CHECK(*archive.common_ancestor(4, 4) == 4); + CHECK(*archive.common_ancestor(1, 5) == 1); + // A separate founder shares nothing. + CHECK(archive.admit(descend(9, 0, 500))); + CHECK(archive.common_ancestor(4, 9) && *archive.common_ancestor(4, 9) == 0); + const auto unknown = archive.common_ancestor(4, 77); + CHECK(!unknown && unknown.error() == HistoryError::unknown_genome); +} + +void admission_refuses_duplicates_and_dangling_parents() { + LineageArchive archive; + CHECK(archive.admit(descend(1, 0))); + // Re-admitting an ID would destroy the earlier record. + const auto repeated = archive.admit(descend(1, 0, 500)); + CHECK(!repeated && repeated.error() == HistoryError::duplicate_genome); + CHECK(archive.find(1) && archive.find(1)->content_digest() == descend(1, 0).content_digest()); + // A child before its parent would leave ancestry dangling, and would be the + // only way to build a cycle. + const auto orphan = archive.admit(descend(5, 4)); + CHECK(!orphan && orphan.error() == HistoryError::unknown_parent); + CHECK(archive.archived() == 1); + const auto missing = archive.ancestry(4); + CHECK(!missing && missing.error() == HistoryError::unknown_genome); + // Admitting in order is fine, and the graph stays acyclic by that order. + CHECK(archive.admit(descend(4, 1))); + CHECK(archive.admit(descend(5, 4))); + CHECK(archive.ancestry(5) && (*archive.ancestry(5) == std::vector{1, 4, 5})); +} + +void death_is_terminal_and_births_are_unique() { + auto archive = branching(); + const auto nobody = archive.record_death(500, evo::Tick{1}); + CHECK(!nobody && nobody.error() == HistoryError::unknown_organism); + const auto nowhere = archive.record_birth(300, 77, evo::Tick{1}); + CHECK(!nowhere && nowhere.error() == HistoryError::unknown_genome); + const auto anonymous = archive.record_birth(0, 1, evo::Tick{1}); + CHECK(!anonymous && anonymous.error() == HistoryError::invalid_identity); + CHECK(archive.record_birth(300, 3, evo::Tick{8})); + // An identity is never reused, whether its holder lives or not. + const auto twice = archive.record_birth(300, 5, evo::Tick{9}); + CHECK(!twice && twice.error() == HistoryError::duplicate_organism); + const auto backwards = archive.record_death(300, evo::Tick{7}); + CHECK(!backwards && backwards.error() == HistoryError::invalid_tick); + CHECK(archive.record_death(300, evo::Tick{40})); + const auto again = archive.record_death(300, evo::Tick{41}); + CHECK(!again && again.error() == HistoryError::already_dead); + // Nothing brings it back, and its record keeps the first terminal tick. + const auto reborn = archive.record_birth(300, 3, evo::Tick{50}); + CHECK(!reborn && reborn.error() == HistoryError::duplicate_organism); + const auto record = archive.organism(300); + CHECK(record && !record->alive && record->died.value == 40); + CHECK(*archive.status(3) == LineageStatus::absent); +} + +void absence_is_never_reported_as_extinction() { + auto archive = branching(); + // Nothing was ever born: every lineage is absent, and none is extinct. + for (const std::uint64_t genome : {1, 2, 3, 4, 5}) { + CHECK(*archive.status(genome) == LineageStatus::absent); + CHECK(*archive.living_carriers(genome) == 0); + CHECK(archive.find(genome)); // Still retained regardless. + } + // The enumeration itself offers no way to say extinct. + CHECK(static_cast(LineageStatus::living) != static_cast(LineageStatus::absent)); + // A lineage can return from absence: absence is about carriers, not the + // record, and the archive never claimed the lineage was finished. + CHECK(archive.record_birth(400, 5, evo::Tick{1})); + CHECK(*archive.status(5) == LineageStatus::living); + CHECK(archive.record_death(400, evo::Tick{2})); + CHECK(*archive.status(5) == LineageStatus::absent); + CHECK(archive.record_birth(401, 5, evo::Tick{3})); + CHECK(*archive.status(5) == LineageStatus::living); +} + +// Retention is a property of the interface: the type offers no removal +// operation, so no caller can choose to delete a record. Written as concepts +// rather than bare requires-expressions so the check is a substitution failure +// instead of a hard error. +template +concept erases = requires(Archive& archive, std::uint64_t id) { archive.erase(id); }; +template +concept removes = requires(Archive& archive, std::uint64_t id) { archive.remove(id); }; +template +concept clears = requires(Archive& archive) { archive.clear(); }; +template +concept prunes = requires(Archive& archive) { archive.prune(); }; + +void the_archive_offers_no_way_to_forget() { + static_assert(!erases); + static_assert(!removes); + static_assert(!clears); + static_assert(!prunes); + // The check itself is live: a container that does erase by key is detected. + static_assert(erases>); + static_assert(clears>); + auto archive = branching(); + const auto before = archive.archived(); + CHECK(archive.record_birth(700, 1, evo::Tick{1})); + CHECK(archive.record_death(700, evo::Tick{2})); + // Death changed nothing about how much is retained. + CHECK(archive.archived() == before && archive.recorded() == 1); +} + +void capacity_refuses_loudly_rather_than_dropping() { + LineageArchive archive; + CHECK(archive.admit(descend(1, 0))); + for (std::uint64_t id = 2; id <= max_archived_genomes; ++id) { + CHECK(archive.admit(descend(id, id - 1))); + } + CHECK(archive.archived() == max_archived_genomes); + const auto overflowing = archive.admit(descend(max_archived_genomes + 1, max_archived_genomes)); + CHECK(!overflowing && overflowing.error() == HistoryError::archive_full); + // Refusing to record is not deleting: everything admitted is still here. + CHECK(archive.archived() == max_archived_genomes); + CHECK(archive.find(1) && archive.find(max_archived_genomes)); + const auto deep = archive.ancestry(max_archived_genomes); + CHECK(deep && deep->size() == max_archived_genomes); + CHECK(deep->front() == 1 && deep->back() == max_archived_genomes); + CHECK(*archive.common_ancestor(max_archived_genomes, 1) == 1); +} +} // namespace +int main() try { + a_genome_outlives_every_organism_that_carried_it(); + ancestry_and_descendants_resolve_through_a_dead_middle(); + branching_lineages_resolve_their_divergence(); + admission_refuses_duplicates_and_dangling_parents(); + death_is_terminal_and_births_are_unique(); + absence_is_never_reported_as_extinction(); + the_archive_offers_no_way_to_forget(); + capacity_refuses_loudly_rather_than_dropping(); + std::cout << "PASS lineage retention, branching ancestry and provisional absence\n"; + return 0; +} catch (...) { + return 1; +}