Refuse the whole conversion rather than drop the inconvenient member

M4.2 moves individuals into the M4.1 record and does only that: no advance, no
materialization back, no transfer between habitats, no persistence.

Collapse is two phases over one sample. plan_collapse reads the members once and
returns an immutable plan that already carries a validated cohort; commit applies
exactly that plan and derives nothing, so replaying a committed sample cannot
resample, and a record that would not validate fails during planning rather than
after the ledger has moved.

A controlled, suspended, dead or unsettled member refuses the whole plan instead
of being skipped. Filtering would let a caller obtain a plan by omitting whoever
was inconvenient, and the result would be indistinguishable from an honest
conversion, which is the adversarial selection the model forbids. Ages are
carried into declared classes and a member fitting none refuses the plan, so
nobody is quietly moved or dropped for having nowhere to go. Reserves are summed
per class and never redistributed, so the distribution M4.1 exists to keep
survives the move.

Conservation runs through the ledger rather than beside it: one atomic
transaction, one leg per member, each moving that member's entire reserve, so the
conserved total is unchanged by construction. Dual representation is closed from
both ends. A member must be emptied exactly, and a reservoir holding anything
other than what was sampled makes the plan stale rather than partly applicable.
The destination is proved available before anything moves, so no rejection can
strand biomass in a reservoir nothing owns. Reversing that order is detected by
the tests, which is the point: the ordering prevents the failure rather than a
comment claiming it cannot happen.

Two gaps are stated rather than implied covered. This cannot tell whether the
members offered were all there were, so completeness is the caller's obligation.
And emptying a reservoir is not withdrawing the right to use it, because the
ledger has no removal.

ReservoirId and Transfer gain the defaulted comparisons every other value type
here already has, so a plan's legs can be compared. Additive, and ADR-0037 says
so rather than claiming no M1 change.

All ten guards were confirmed load-bearing by removing each and rerunning. One of
my own expectations was wrong rather than the code: a replayed commit reported
stale_plan where I expected destination_occupied. Both are pure checks made
before anything moves, so only the diagnosis differed; the destination check runs
first now, because "this already happened" says more about a replay.

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

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
dingo
2026-09-24 09:45:09 -04:00
co-authored by Claude Opus 5
parent 5a4c34a903
commit 1a59b63c7a
11 changed files with 932 additions and 3 deletions
+2
View File
@@ -26,11 +26,13 @@ struct Inventory {
};
struct ReservoirId {
std::uint32_t value{};
auto operator<=>(const ReservoirId&) const = default;
};
struct Transfer {
ReservoirId from;
ReservoirId to;
Inventory amount;
auto operator<=>(const Transfer&) const = default;
};
enum class LedgerError : std::uint8_t {
reservoir_limit,
+127
View File
@@ -0,0 +1,127 @@
#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.
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_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 before anything
// moves, so no rejection can strand inventory in a reservoir nothing owns: every
// failure leaves the ledger and the registry as they were.
[[nodiscard]] std::expected<Cohort, CollapseError>
commit_collapse(accounting::Ledger& ledger, CohortRegistry& registry, const CollapsePlan& plan);
} // namespace evo::ecology