Round shares down and ages up, so a round trip never pays

M4.4 turns whole members of a cohort back into identified individuals, and does
nothing else: no habitat transfer, no persistence, no resolution-equivalence
claim. Materialization is instantaneous at the cohort's current tick, because
advancing time is M4.3's interval.

The named risk is that re-materialization becomes free healing, and it has two
separable sources. The arithmetic one is closed outright. A drawn member gets its
class share by integer division rounded down, because rounding up would create
biomass, and a class drawn empty hands over everything it held because a class
with no members may keep no reserve. A residual is never drawable, so an expected
density cannot become an individual.

Age is taken as the oldest the class admits. The exact age is unrecoverable, so
the question is only which direction to be wrong in, and every other answer makes
oscillation profitable: a member re-materialized at the bottom of its class is
younger than it was, and repeating that is immortality. Taking the top means a
round trip can only age someone. Both of these are the risk rather than ordinary
validation, and both mutations are detected: rounding the share up, and drawing
the age from the class floor.

The second source is the declared resolution itself and is stated rather than
mitigated. Members inside a class are indistinguishable by construction, so
collapsing a starving member with a well-provisioned one and materializing both
returns two average members, healing the first at the second's expense. The tests
demonstrate both halves instead of only the flattering one: a round trip is exact
when each class holds one member, and a coarse class conserves the total while
averaging the individuals. Conservation of the total is not evidence that any
individual is right, and the mitigation is the caller's choice of classes when it
collapses, not anything this code can recover.

Materialization produces exactly the record a collapse consumes, so the two
compose and are tested against each other rather than described as inverses. The
oscillation test runs twelve cycles and asserts every cycle that the conserved
total never moves, nobody holds more than the richest starting member held, and
nobody is younger than last cycle; it ends by asserting everyone has been pushed
to a class ceiling, which records the cost of the age rule rather than claiming
it away.

Release 37/37, analysis, ASan 37/37 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 15:41:49 -04:00
co-authored by Claude Opus 5
parent cabada70c4
commit 380d609f06
10 changed files with 1095 additions and 3 deletions
+99
View File
@@ -0,0 +1,99 @@
#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,
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 empty, so no rejection can
// leave the cohort debited with nobody holding what it gave up.
[[nodiscard]] std::expected<std::vector<ActiveMember>, MaterializeError>
commit_materialize(accounting::Ledger& ledger, CohortRegistry& registry,
const MaterializePlan& plan);
} // namespace evo::ecology