Account for the interval a model proposes; never clamp it
M4.3 advances a cohort over one declared interval and deliberately does not model one. ECOLOGY_MODEL keeps population maths an experiment and asks for several candidates to be compared, so choosing one here would turn a recommendation into a locked rule. A model proposes fluxes; this checks the declared result is exactly what they imply, for counts and for every inventory channel. Nothing is clamped. A loss larger than what is there refuses the interval and says whether it was the population or the biomass, so a caller can subdivide; subtraction is checked against what is present rather than performed and repaired, so a negative population is never constructed. That is the answer to the named risk: a clamp is how an interval a model could not integrate becomes a plausible result, and how a false extinction arrives. Both clamp mutations are detected by the tests. Counts carry whole members and owed fractions as one quantity, so a population below one member is a number rather than a rounding decision. Biomass has no birth term at all, so a birth cannot bring inventory in and newborns are necessarily funded from what the cohort holds. Immigration draws from a reservoir that already held it, so a late transfer is not new production. Conservation runs through the ledger as one atomic transaction; an interval where nothing moves submits none. Two amendments to M4.1 were forced, not chosen. A cohort records the reservoir backing it, because an advance cannot otherwise know where the inventory is and passing it alongside would let a caller advance one cohort against another's store, which comparing balances cannot detect between equal reserves; the registry now refuses two cohorts sharing one. And a cohort may be vacant, through a separate factory so vacancy stays deliberate, because a decline to exactly zero was otherwise unrepresentable and the only way through would have been the clamp this milestone exists to refuse. A vacant cohort is not an extinction: the record, its genome, its habitat and its provenance remain and it stays installed. Fourteen guards confirmed load-bearing by removing each and rerunning. Two of my own expectations were wrong rather than the code: escrow arithmetic in the migration test, and a dwindling case that shed all but one femtogram while declaring a result holding none. The second surfaced a real tension now recorded in ADR-0038 rather than worked around: a class reduced to a fraction of a member may hold no reserve, because reserve belongs to members and a fraction is not one yet, so that biomass has to go somewhere the same interval. Closure is checked and stability is not, so an interval whose arithmetic balances and whose ecology is nonsense is accepted. The declared age structure is not verified to be what ageing would produce, because that needs the within-class distribution the record discards. Release 36/36, analysis, ASan 36/36 and clang-format all ran and passed here. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
@@ -73,6 +73,11 @@ struct CohortDraft {
|
||||
std::uint64_t revision{};
|
||||
// The conversion that produced this record, kept as provenance.
|
||||
std::uint64_t conversion{};
|
||||
// Where this cohort's reserve actually is. Bound to the record rather than
|
||||
// passed alongside it: a caller could otherwise advance one cohort against
|
||||
// another's reservoir, and comparing balances cannot tell two equal reserves
|
||||
// apart. Amended in M4.2/M4.3; see ADR-0036.
|
||||
accounting::ReservoirId reservoir{};
|
||||
std::vector<AgeClass> classes;
|
||||
ApproximationBound bound{};
|
||||
};
|
||||
@@ -86,6 +91,7 @@ enum class CohortError : std::uint8_t {
|
||||
unowned_reserve,
|
||||
residual_out_of_range,
|
||||
overflow,
|
||||
not_vacant,
|
||||
duplicate_cohort,
|
||||
unknown_cohort,
|
||||
wrong_owner,
|
||||
@@ -104,6 +110,13 @@ inline constexpr std::size_t max_cohorts = 4'096;
|
||||
class Cohort {
|
||||
public:
|
||||
[[nodiscard]] static std::expected<Cohort, CohortError> create(CohortDraft draft);
|
||||
// A cohort whose population reached exactly zero. It is a separate factory so
|
||||
// vacancy is always deliberate: `create` goes on refusing a draft that simply
|
||||
// has no classes, which would otherwise become a vacant record by accident.
|
||||
// Without this a decline to zero would be unrepresentable and a caller would
|
||||
// have to clamp, which ECOLOGY_MODEL forbids. A vacant cohort is not
|
||||
// extinction: the record, its genome and its habitat are all still here.
|
||||
[[nodiscard]] static std::expected<Cohort, CohortError> vacant(const CohortDraft& draft);
|
||||
// Copy-only on purpose. A moved-from record would keep its habitat, genome,
|
||||
// owner and totals while losing its age classes, which is precisely the
|
||||
// invalid cohort `create` refuses to build; the registry would then accept
|
||||
@@ -134,6 +147,12 @@ class Cohort {
|
||||
[[nodiscard]] std::uint64_t conversion() const noexcept {
|
||||
return conversion_;
|
||||
}
|
||||
[[nodiscard]] accounting::ReservoirId reservoir() const noexcept {
|
||||
return reservoir_;
|
||||
}
|
||||
[[nodiscard]] bool is_vacant() const noexcept {
|
||||
return classes_.empty();
|
||||
}
|
||||
[[nodiscard]] std::span<const AgeClass> classes() const noexcept {
|
||||
return classes_;
|
||||
}
|
||||
@@ -149,6 +168,10 @@ class Cohort {
|
||||
// Total owed fraction, in units of residual_scale. May exceed one member once
|
||||
// summed across classes; the per-class bound is what is invariant.
|
||||
[[nodiscard]] std::uint64_t residual() const noexcept;
|
||||
// Whole members and owed fractions as one quantity, in units of
|
||||
// residual_scale, so a population that has fallen below one member is still a
|
||||
// number and not a rounding decision. Bounded at construction.
|
||||
[[nodiscard]] std::uint64_t population() const noexcept;
|
||||
// Deliberately no mean age and no per-member reserve. An average that is easy
|
||||
// to reach is an average that gets used as the authority.
|
||||
|
||||
@@ -163,6 +186,7 @@ class Cohort {
|
||||
Tick last_tick_{};
|
||||
std::uint64_t revision_{};
|
||||
std::uint64_t conversion_{};
|
||||
accounting::ReservoirId reservoir_{};
|
||||
std::vector<AgeClass> classes_;
|
||||
ApproximationBound bound_{};
|
||||
};
|
||||
@@ -173,6 +197,9 @@ class Cohort {
|
||||
// forbidden. Nothing is serialized and no cross-worker protocol is implied.
|
||||
class CohortRegistry {
|
||||
public:
|
||||
// Also refuses a cohort whose reservoir another cohort already uses: one
|
||||
// reservoir backing two records is the same inventory in two places, which is
|
||||
// the invariant this registry exists for.
|
||||
[[nodiscard]] std::expected<void, CohortError> install(const Cohort& cohort);
|
||||
// Refused unless it is a strictly later view of the same record by the same
|
||||
// owner: the habitat and genome must match, the epoch must not be older, the
|
||||
|
||||
@@ -0,0 +1,122 @@
|
||||
#pragma once
|
||||
|
||||
#include "evo/ecology/cohort.hpp"
|
||||
|
||||
namespace evo::ecology {
|
||||
// What a model proposes happened to a cohort over one declared interval. This
|
||||
// library does not decide any of it. ECOLOGY_MODEL keeps population maths an
|
||||
// experiment and lists several candidate models, so choosing one here would turn
|
||||
// a recommendation into a locked rule. What is a contract is that a proposal
|
||||
// balances: these are fluxes to be accounted for, not a model to be believed.
|
||||
//
|
||||
// Counts are in units of `residual_scale`, so a fraction of a member is a number
|
||||
// rather than a rounding decision, and a population below one member is still a
|
||||
// population. Births carry no biomass term on purpose: ECOLOGY_MODEL requires
|
||||
// that births redistribute funded investment rather than create biomass, so
|
||||
// there is nowhere for a birth to bring any in.
|
||||
struct IntervalFlux {
|
||||
std::uint64_t births{};
|
||||
std::uint64_t immigration{};
|
||||
std::uint64_t deaths{};
|
||||
std::uint64_t predation{};
|
||||
std::uint64_t emigration{};
|
||||
// Biomass leaving the cohort, by where it goes. Death returns detritus,
|
||||
// predation transfers once, emigration is escrowed for a destination this
|
||||
// milestone does not settle with.
|
||||
accounting::Inventory to_detritus{};
|
||||
accounting::Inventory to_predators{};
|
||||
accounting::Inventory to_elsewhere{};
|
||||
// Biomass arriving with immigrants. A late transfer is not new production:
|
||||
// it comes out of a reservoir that already held it.
|
||||
accounting::Inventory from_elsewhere{};
|
||||
auto operator<=>(const IntervalFlux&) const = default;
|
||||
};
|
||||
|
||||
struct AdvanceRequest {
|
||||
// The end of the interval. The start is the cohort's own last tick, so
|
||||
// intervals cannot overlap or leave a gap.
|
||||
Tick to{};
|
||||
Owner owner{};
|
||||
std::uint64_t revision{};
|
||||
// The age structure the model says results. This library cannot derive it:
|
||||
// ageing across a class boundary needs the within-class distribution that
|
||||
// ADR-0036's declared resolution deliberately does not keep.
|
||||
std::vector<AgeClass> after;
|
||||
IntervalFlux flux;
|
||||
accounting::ReservoirId detritus{};
|
||||
accounting::ReservoirId predators{};
|
||||
accounting::ReservoirId elsewhere{};
|
||||
ApproximationBound bound{};
|
||||
};
|
||||
|
||||
enum class PopulationError : std::uint8_t {
|
||||
invalid_request,
|
||||
empty_interval,
|
||||
wrong_owner,
|
||||
stale_revision,
|
||||
// A proposal that would take the population or the reserve below zero. It is
|
||||
// refused and never clamped: ECOLOGY_MODEL requires that an interval which
|
||||
// does not balance be rejected or subdivided, because a clamp would hide a
|
||||
// model that has gone unstable and would manufacture a false extinction.
|
||||
negative_population,
|
||||
negative_biomass,
|
||||
// The declared result does not equal what the fluxes imply.
|
||||
population_mismatch,
|
||||
biomass_mismatch,
|
||||
overflow,
|
||||
invalid_cohort,
|
||||
not_installed,
|
||||
stale_plan,
|
||||
ledger_failure
|
||||
};
|
||||
|
||||
// The accounted interval, decided once. Copy-only for the reason a cohort is: a
|
||||
// moved-from plan would keep its identities while losing its legs.
|
||||
class AdvancePlan {
|
||||
public:
|
||||
AdvancePlan(const AdvancePlan&) = default;
|
||||
AdvancePlan& operator=(const AdvancePlan&) = default;
|
||||
|
||||
[[nodiscard]] const Cohort& before() const noexcept {
|
||||
return before_;
|
||||
}
|
||||
[[nodiscard]] const Cohort& after() const noexcept {
|
||||
return after_;
|
||||
}
|
||||
[[nodiscard]] std::span<const accounting::Transfer> legs() const noexcept {
|
||||
return legs_;
|
||||
}
|
||||
[[nodiscard]] const IntervalFlux& flux() const noexcept {
|
||||
return flux_;
|
||||
}
|
||||
// Ticks covered. A model that has to subdivide an interval is told how long
|
||||
// the one it proposed was.
|
||||
[[nodiscard]] std::uint64_t span() const noexcept {
|
||||
return after_.last_tick().value - before_.last_tick().value;
|
||||
}
|
||||
|
||||
auto operator<=>(const AdvancePlan&) const = default;
|
||||
|
||||
private:
|
||||
friend std::expected<AdvancePlan, PopulationError> plan_advance(const Cohort&,
|
||||
const AdvanceRequest&);
|
||||
AdvancePlan(const Cohort& before, const Cohort& after) : before_{before}, after_{after} {}
|
||||
Cohort before_;
|
||||
Cohort after_;
|
||||
std::vector<accounting::Transfer> legs_;
|
||||
IntervalFlux flux_{};
|
||||
};
|
||||
|
||||
// Accounts for one proposed interval without touching any ledger or registry.
|
||||
// It checks that the declared result is exactly what the fluxes imply, and that
|
||||
// neither the population nor any inventory channel would go below zero.
|
||||
[[nodiscard]] std::expected<AdvancePlan, PopulationError>
|
||||
plan_advance(const Cohort& before, const AdvanceRequest& request);
|
||||
|
||||
// Applies exactly that plan. The installed record must still be the one the plan
|
||||
// started from, and the cohort's reservoir must still hold what it held, so a
|
||||
// proposal computed against a stale view is refused rather than applied. Every
|
||||
// rejection leaves the ledger and the registry as they were.
|
||||
[[nodiscard]] std::expected<Cohort, PopulationError>
|
||||
commit_advance(accounting::Ledger& ledger, CohortRegistry& registry, const AdvancePlan& plan);
|
||||
} // namespace evo::ecology
|
||||
Reference in New Issue
Block a user