#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 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 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 plan_advance(const Cohort&, const AdvanceRequest&); AdvancePlan(const Cohort& before, const Cohort& after) : before_{before}, after_{after} {} Cohort before_; Cohort after_; std::vector 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 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 commit_advance(accounting::Ledger& ledger, CohortRegistry& registry, const AdvancePlan& plan); } // namespace evo::ecology