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>
126 lines
6.3 KiB
C++
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
|