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>
123 lines
5.0 KiB
C++
123 lines
5.0 KiB
C++
#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
|