Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 2m33s
Foundation / checks (network) (push) Successful in 21m15s
Foundation / checks (client) (push) Successful in 22m8s
Foundation / checks (tsan) (push) Successful in 25m2s
Foundation / postgres-tools (push) Canceled after 0s
Foundation / server-image (push) Canceled after 0s
Foundation / image (push) Canceled after 0s
Foundation / checks (checks) (push) Canceled after 38m24s
Foundation / checks (postgres) (push) Canceled after 38m24s
170 lines
8.7 KiB
C++
170 lines
8.7 KiB
C++
#pragma once
|
|
|
|
#include "evo/biology/genome.hpp"
|
|
#include "evo/core/types.hpp"
|
|
|
|
#include <span>
|
|
|
|
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<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);
|
|
// 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<void, HistoryError>
|
|
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<Genome, HistoryError> find(std::uint64_t genome) const;
|
|
[[nodiscard]] std::expected<OrganismRecord, HistoryError>
|
|
organism(std::uint64_t identity) const;
|
|
[[nodiscard]] std::expected<std::uint64_t, HistoryError>
|
|
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<LineageArchive, HistoryError>
|
|
merge_living_from(const LineageArchive& source, std::span<const std::uint64_t> organisms) 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();
|
|
}
|
|
// Ascending immutable IDs, including zero-carrier ancestors. Successful
|
|
// genome admission invalidates this view; no removal or spending rights.
|
|
[[nodiscard]] std::span<const Genome> 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<std::uint64_t> living_organisms() const;
|
|
[[nodiscard]] std::span<const OrganismGenomeRevision> 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<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_;
|
|
std::vector<OrganismGenomeRevision> revisions_;
|
|
std::uint32_t format_version_{lineage_archive_format};
|
|
[[nodiscard]] std::expected<void, HistoryError>
|
|
append_revision(std::uint64_t organism, std::uint64_t previous, std::uint64_t successor,
|
|
std::uint64_t origin_event, Tick when);
|
|
};
|
|
} // namespace evo::biology
|