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

104 lines
3.9 KiB
C++

#pragma once
#include "evo/ecology/collapse.hpp"
namespace evo::ecology {
// How many whole members to draw from one class. A residual is a fraction that is
// owed and not present, so it is never drawable: an expected density is not an
// available individual.
struct ClassDraw {
std::size_t age_class{};
std::uint64_t count{};
auto operator<=>(const ClassDraw&) const = default;
};
struct MaterializeRequest {
Owner owner{};
std::uint64_t revision{};
std::vector<ClassDraw> draws;
// Identities are assigned in draw order from here. Materialization invents
// identity and nothing else: no parentage, no history, no condition.
std::uint64_t first_identity{};
// One per member to be drawn, in draw order. Each must be empty when the plan
// is committed, so a member's reserve is the whole of what backs it rather
// than a part sharing a store with inventory nobody counted.
std::vector<accounting::ReservoirId> reservoirs;
ApproximationBound bound{};
};
enum class MaterializeError : std::uint8_t {
invalid_request,
nothing_drawn,
unknown_age_class,
duplicate_age_class,
insufficient_members,
reservoir_mismatch,
duplicate_reservoir,
wrong_owner,
stale_revision,
overflow,
invalid_cohort,
not_installed,
stale_plan,
reservoir_not_empty,
// An empty reservoir is not an available one: a vacant cohort, or one holding
// nothing, still owns its store.
reservoir_owned,
ledger_failure
};
// The draw, decided once. Copy-only for the reason a cohort is: a moved-from plan
// would keep its identities while losing its legs and its members.
class MaterializePlan {
public:
MaterializePlan(const MaterializePlan&) = default;
MaterializePlan& operator=(const MaterializePlan&) = default;
[[nodiscard]] const Cohort& before() const noexcept {
return before_;
}
// The cohort after the draw is debited. Vacant if every member was taken and
// nothing is owed: vacancy is not extinction, and the record stays.
[[nodiscard]] const Cohort& after() const noexcept {
return after_;
}
// Exactly what a collapse consumes, so the two compose and can be checked
// against each other rather than only described as inverses.
[[nodiscard]] std::span<const ActiveMember> members() const noexcept {
return members_;
}
[[nodiscard]] std::span<const accounting::Transfer> legs() const noexcept {
return legs_;
}
[[nodiscard]] accounting::Inventory withdrawn() const noexcept {
return withdrawn_;
}
auto operator<=>(const MaterializePlan&) const = default;
private:
friend std::expected<MaterializePlan, MaterializeError>
plan_materialize(const Cohort&, const MaterializeRequest&);
MaterializePlan(const Cohort& before, const Cohort& after) : before_{before}, after_{after} {}
Cohort before_;
Cohort after_;
std::vector<ActiveMember> members_;
std::vector<accounting::Transfer> legs_;
accounting::Inventory withdrawn_{};
};
// Decides the whole draw without touching any ledger or registry. Instantaneous:
// it happens at the cohort's current tick and never advances it, because
// advancing time is ADR-0038's interval and this is not one.
[[nodiscard]] std::expected<MaterializePlan, MaterializeError>
plan_materialize(const Cohort& before, const MaterializeRequest& request);
// Applies exactly that plan. The installed record must still be the one the plan
// started from, and every destination reservoir must be both empty and unowned, so
// no rejection can leave the cohort debited with nobody holding what it gave up and
// no credit can land in a store some other record already accounts for.
[[nodiscard]] std::expected<std::vector<ActiveMember>, MaterializeError>
commit_materialize(accounting::Ledger& ledger, CohortRegistry& registry,
const MaterializePlan& plan);
} // namespace evo::ecology