Files
dingoandClaude Opus 5 14e0c1af5e An empty reservoir is not an unowned one
Two defects from review of 380d609.

Materialization treated an empty reservoir as available. A vacant cohort, or one
holding nothing, still owns its store, so a draw could credit it while the owning
record went on recording nothing: the same inventory in two places, reached from
the opposite direction to the destination defect in 1a59b63. Destinations are
checked against the registry's ownership now, not just their balance, and the
registry answers whether a reservoir is used rather than callers inferring it from
what the reservoir contains.

The same hole existed on the collapse side in a worse form, found by asking
whether the reported defect had a sibling. Nothing verified the destination was
unowned, so the shared-reservoir rule added in M4.3 would have refused the install
only after the transfer had run, leaving the members emptied and their biomass in
a reservoir nothing accounted for. That is exactly the stranding the M4.2 ordering
was chosen to prevent, defeated by a check that ran too late. Whichever registry
step follows a transfer is now proved to succeed before it, through may_install
and may_replace queries that install and replace delegate to, so there is one rule
and not a restatement that can drift.

The second finding was a functional gap the oscillation test hid by discarding its
registry each cycle. A full draw leaves a vacant record, which ADR-0036 retains
because absence is not extinction, and collapse then refused that habitat and
genome as occupied: a full materialization was a one-way door out of a habitat and
the lineage could never return. Collapse repopulates a vacant record in place now,
continuing its ownership and revision series rather than restarting them, and a
record still holding a population is refused, because merging two silently is not
a conversion. The test keeps one registry for all twelve cycles and asserts the
revision continues.

Four of the five new guards are load-bearing. The fifth is not and is recorded as
such: the may_replace pre-check in commit_materialize is unreachable given the
checks before it, since the installed record is already proved equal to the plan's
origin and the result differs only by a later revision. It is kept because it is
the right place for the guard and its collapse-side sibling is genuinely
reachable, not because it is exercised.

Release 37/37, analysis, ASan 37/37 and clang-format all ran and passed here.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-24 17:47:37 -04:00

140 lines
5.7 KiB
C++

#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<AgeBound> 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<const accounting::Transfer> legs() const noexcept {
return legs_;
}
[[nodiscard]] std::span<const std::uint64_t> 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<CollapsePlan, CollapseError> plan_collapse(std::span<const ActiveMember>,
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<accounting::Transfer> legs_;
std::vector<std::uint64_t> 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<CollapsePlan, CollapseError>
plan_collapse(std::span<const ActiveMember> 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<Cohort, CollapseError>
commit_collapse(accounting::Ledger& ledger, CohortRegistry& registry, const CollapsePlan& plan);
} // namespace evo::ecology