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; +}