#pragma once #include "evo/ecology/cohort.hpp" namespace evo::ecology { // What a member is doing when a conversion reaches it. Only an active, settled // member may be converted; every other state refuses the whole plan rather than // being skipped, so a conversion cannot quietly leave out whoever was // inconvenient and still look like an honest one. enum class MemberState : std::uint8_t { active, controlled, // a player holds it; ECOLOGY_MODEL keeps these out of populations suspended, // offline or parked, so its viability is not this tier's to decide dead, // its inventory belongs to decomposition, not to a cohort unsettled // has an obligation in flight and is not whole yet }; // One identified individual offered to a conversion. This is an explicit record a // caller fills in, not a view of any live representation: the ecology library // stays independent of whatever is simulating individuals. struct ActiveMember { std::uint64_t identity{}; std::uint64_t genome{}; HabitatId habitat{}; std::uint64_t age{}; // ticks; carried into a class, never reset accounting::ReservoirId reservoir{}; // What that reservoir holds. Checked against the ledger again at commit, so a // sample that has gone stale is refused rather than applied. accounting::Inventory reserve{}; MemberState state{}; auto operator<=>(const ActiveMember&) const = default; }; // Half-open age class bounds, declared by the caller. This is the resolution // decision ADR-0036 leaves to whoever builds the record. struct AgeBound { std::uint64_t low{}; std::uint64_t high{}; auto operator<=>(const AgeBound&) const = default; }; struct CollapseRequest { std::uint64_t conversion{}; Owner owner{}; HabitatId habitat{}; std::uint64_t genome{}; Tick tick{}; std::uint64_t revision{}; // Where the members' inventory is gathered. Must not be a member's own, and // must be empty when the plan is committed, so the cohort's recorded reserve // is the whole of what its reservoir holds. accounting::ReservoirId destination{}; std::vector bounds; ApproximationBound bound{}; }; enum class CollapseError : std::uint8_t { invalid_request, invalid_bounds, no_members, too_many_members, duplicate_member, foreign_member, ineligible_member, unclassified_age, overflow, invalid_cohort, stale_plan, destination_occupied, destination_not_empty, destination_owned, destination_unavailable, ledger_failure }; // The sample, taken once. ECOLOGY_MODEL requires that recovery replays a // committed sample rather than sampling again, so this carries everything commit // needs and commit derives nothing: the cohort is already built and validated, // and the legs already say what each member is expected to hold. class CollapsePlan { public: // Copy-only, for the reason ADR-0036 makes a cohort copy-only: a moved-from // plan would keep its identities while losing its legs, and committing it // would move nothing while appearing to convert everyone. CollapsePlan(const CollapsePlan&) = default; CollapsePlan& operator=(const CollapsePlan&) = default; [[nodiscard]] const Cohort& cohort() const noexcept { return cohort_; } // One leg per member, in the order the members were offered. Each moves that // member's whole reserve, so nothing is left behind in a second tier. [[nodiscard]] std::span legs() const noexcept { return legs_; } [[nodiscard]] std::span members() const noexcept { return members_; } [[nodiscard]] accounting::Inventory total() const noexcept { return total_; } [[nodiscard]] accounting::ReservoirId destination() const noexcept { return destination_; } auto operator<=>(const CollapsePlan&) const = default; private: friend std::expected plan_collapse(std::span, const CollapseRequest&); // Taken by reference: a cohort is copy-only, so a by-value parameter would // be one copy more and a move that does nothing. explicit CollapsePlan(const Cohort& cohort) : cohort_{cohort} {} Cohort cohort_; std::vector legs_; std::vector members_; accounting::Inventory total_{}; accounting::ReservoirId destination_{}; }; // Reads the members once and decides everything. Pure: it touches no ledger and // no registry, so a plan can be inspected before anything is committed. [[nodiscard]] std::expected plan_collapse(std::span members, const CollapseRequest& request); // Applies exactly that plan. The destination is proved available and empty before // anything moves, so no rejection can strand inventory in a reservoir nothing owns // and the cohort's reserve is exactly what its reservoir holds: every failure // leaves the ledger and the registry as they were. // // Where the habitat and genome already hold a vacant record, this repopulates it // rather than refusing. ADR-0036 keeps a record whose population reached zero, // because absence is not extinction, so without this a habitat could never be // recolonised by the lineage that had been there. The retained record's ownership // and revision series continue: the plan has to be a strictly later view of it, // which is the same rule any other replacement obeys. [[nodiscard]] std::expected commit_collapse(accounting::Ledger& ledger, CohortRegistry& registry, const CollapsePlan& plan); } // namespace evo::ecology