Files
aevolution/include/evo/biology/lineage.hpp
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

126 lines
6.3 KiB
C++

#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;
// Whole-archive codec v1 (schemas/lineage-archive-v1.md, ADR-0062).
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::size_t archived_organism_bytes = 33;
inline constexpr std::size_t max_archive_bytes =
32 + (max_archived_genomes * (2 + max_genome_bytes)) +
(max_archived_organisms * archived_organism_bytes) + 8;
// 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<void, HistoryError> admit(const Genome& genome);
[[nodiscard]] std::expected<void, HistoryError> 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<void, HistoryError> record_death(std::uint64_t organism, Tick when);
[[nodiscard]] std::expected<Genome, HistoryError> find(std::uint64_t genome) const;
[[nodiscard]] std::expected<OrganismRecord, HistoryError>
organism(std::uint64_t identity) const;
// Oldest first, ending at the founder. Still resolves after every carrier dies.
[[nodiscard]] std::expected<std::vector<std::uint64_t>, HistoryError>
ancestry(std::uint64_t genome) const;
[[nodiscard]] std::expected<std::vector<std::uint64_t>, HistoryError>
children(std::uint64_t genome) const;
// Zero when the two descend from different founders.
[[nodiscard]] std::expected<std::uint64_t, HistoryError>
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<std::uint64_t, HistoryError>
living_carriers(std::uint64_t genome) const;
[[nodiscard]] std::expected<LineageStatus, HistoryError> 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();
}
// Ascending identities of organisms not yet recorded dead.
[[nodiscard]] std::vector<std::uint64_t> living_organisms() const;
// 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<std::uint8_t> 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<LineageArchive, ArchiveCodecError>
decode(std::span<const std::uint8_t> 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<Genome> genomes_;
std::vector<ArchivedOrganism> organisms_;
};
} // namespace evo::biology