#pragma once #include "evo/biology/genome.hpp" #include "evo/core/types.hpp" #include 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, invalid_revision }; inline constexpr std::size_t max_archived_genomes = 4'096; inline constexpr std::size_t max_archived_organisms = 65'536; // Whole-archive codecs v1/v2 (schemas/lineage-archive-v1.md and -v2.md). enum class ArchiveCodecError : std::uint8_t { format, // Magic, lengths or field forms. version, // Unknown archive format or genome schema. checksum, // Trailing FNV-1a64 mismatch (corruption, not forgery). bounds, // Counts or bytes above the archive caps; checked before allocation. genome, // A record fails Genome v1 validation. history, // Admission/birth/death invariants refuse the record sequence. noncanonical, // Valid content in a non-canonical order or form. }; inline constexpr std::uint32_t lineage_archive_format = 1; inline constexpr std::uint32_t lineage_archive_revision_format = 2; inline constexpr std::size_t archived_organism_bytes = 33; inline constexpr std::size_t archived_genome_revision_bytes = 40; inline constexpr std::size_t max_archive_legacy_bytes = 32 + (max_archived_genomes * (2 + max_genome_bytes)) + (max_archived_organisms * archived_organism_bytes) + 8; inline constexpr std::size_t max_archive_bytes = 40 + (max_archived_genomes * (2 + max_genome_bytes)) + (max_archived_organisms * archived_organism_bytes) + (max_archived_genomes * archived_genome_revision_bytes) + 8; struct OrganismGenomeRevision { std::uint64_t organism{}, previous_genome{}, successor_genome{}, origin_event{}; Tick at{}; auto operator<=>(const OrganismGenomeRevision&) const = default; }; // 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: LineageArchive() = default; // Copyable: cloning an archive takes nothing away from the original, and // GENOME_MODEL expects migrations to be rehearsed on cloned worlds. // Declaring the copy constructor also suppresses the implicit moves, so a // move decays to a copy and a moved-from archive still holds every record. LineageArchive(const LineageArchive&) = default; // Not assignable, in either form. Assignment is a removal operation that is // simply not named like one: it discards every record the target holds. It // would also let a copy taken earlier be written back, restoring an organism // already recorded as dead, and death is terminal. LineageArchive& operator=(const LineageArchive&) = delete; LineageArchive& operator=(LineageArchive&&) = delete; // 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); // Adds a successor genome and binds it as the next genome carried by a living // organism. Birth records remain immutable; the revision chain is append-only. [[nodiscard]] std::expected record_mutation(std::uint64_t organism, const Genome& successor, Tick when); // Explicitly upgrades a revision-free archive during a cellular profile migration. void upgrade_to_revision_format() noexcept; [[nodiscard]] std::expected find(std::uint64_t genome) const; [[nodiscard]] std::expected organism(std::uint64_t identity) const; [[nodiscard]] std::expected current_genome(std::uint64_t organism) const; // Detached append-only merge for exact ownership transfer. Imports selected // living organisms, their immutable births/revisions and all genome parents. // IDs must be sorted/unique. Existing death or conflicting history refuses // the whole result; both input archives remain unchanged. [[nodiscard]] std::expected merge_living_from(const LineageArchive& source, std::span organisms) 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(); } // Ascending immutable IDs, including zero-carrier ancestors. Successful // genome admission invalidates this view; no removal or spending rights. [[nodiscard]] std::span genomes() const noexcept { return genomes_; } [[nodiscard]] std::uint32_t format_version() const noexcept { return format_version_; } [[nodiscard]] std::size_t recorded() const noexcept { return organisms_.size(); } // Ascending identities of organisms not yet recorded dead. [[nodiscard]] std::vector living_organisms() const; [[nodiscard]] std::span revisions() const noexcept { return revisions_; } // Largest recorded identities, zero when none: allocator high-water checks. [[nodiscard]] std::uint64_t highest_genome() const noexcept; [[nodiscard]] std::uint64_t highest_organism() const noexcept; // Canonical bytes: genomes by (ancestry depth, id), so parents precede children, // then organisms by id. Equal archives encode identically whatever order their // records were admitted in. [[nodiscard]] std::vector encode() const; // Constructs a new archive by replaying admit/record_birth/record_death, so // every retention invariant is re-established, then requires a byte-identical // re-encoding. It never overwrites an existing archive; refusing stale older // copies is the durable commit chain's job (ADR-0061/0062). [[nodiscard]] static std::expected decode(std::span bytes); 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_; std::vector revisions_; std::uint32_t format_version_{lineage_archive_format}; [[nodiscard]] std::expected append_revision(std::uint64_t organism, std::uint64_t previous, std::uint64_t successor, std::uint64_t origin_event, Tick when); }; } // namespace evo::biology