Files
dingo da39fc8095
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
M12.6: add bounded regional cellular census and lineage queries
2026-10-18 13:57:52 -04:00

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