Files
aevolution/docs/adr/0038-interval-accounting.md
T
2026-10-08 12:08:53 -04:00

8.4 KiB

[Reviewed]

ADR-0038: Accounting a proposed interval without choosing an ecology

Status

Adopted for M4.3. It accounts for one declared interval on one cohort and does not model one: no birth rate, no mortality curve, no functional response and no carrying capacity is chosen here. Materialization back into individuals is M4.4 and resolution equivalence is M4.5. It amends ADR-0036 in two ways, both forced by this milestone and described below. No M1 to M3 contract changes.

Context

ECOLOGY_MODEL is explicit that the population maths is an experiment: it lists N_next = N + births - deaths + immigration - emigration, the matching biomass identity, and then says to compare bounded flux, seeded stochastic and deterministic expected-density models. Picking one of those here would turn a recommendation into a locked game rule, which the working agreement forbids.

What the same document does lock is the arithmetic around whichever model runs: never hide negative populations with clamps, reject or subdivide unstable intervals, births redistribute funded investment rather than creating biomass, predation transfers biomass once and death returns detritus, one owner integrates each interval, late transfers are not new production, and rounding a density to zero cannot declare extinction. Those are the contract. The named risk is numerical instability and false extinctions, and a clamp is exactly how both arrive: it turns an interval the model could not integrate into a plausible looking result, and it manufactures an extinction nobody proposed.

Decision

A model proposes fluxes and this library accounts for them. plan_advance takes the cohort, the interval end, the declared fluxes and the declared resulting age structure, and checks that the result is exactly what the fluxes imply. It never computes the result itself, because computing it would mean choosing the model.

Nothing is clamped. A loss larger than what is there refuses the interval and names whether it was the population or the biomass, so a caller can subdivide and retry. Subtraction is checked against what is present rather than performed and repaired afterwards, so a negative value is never constructed in the first place.

Counts are carried in units of residual_scale, whole members and owed fractions together. A population below one member is then a number, not a rounding decision, and a density falling towards zero stays a density.

Biomass has no birth term at all. A birth cannot bring inventory in because there is no field by which it could, so newborns are necessarily funded from what the cohort already holds. This is ECOLOGY_MODEL's rule made structural rather than documented. Immigration does have a term, and it draws from a reservoir that already held the inventory, so a late transfer is not new production either.

Conservation runs through the ledger, as in ADR-0037. Each non-empty outflow and inflow becomes one leg of a single atomic transaction against the cohort's reservoir, so the conserved total is unchanged by construction. An interval in which nothing moves submits no transaction at all rather than an empty one.

Commit refuses a proposal computed against a stale view. The installed record must still be exactly the one the plan started from, down to the revision, and the reservoir must still hold what the plan counted. Ownership and ordering are then the registry's existing rules, so one owner integrates each interval and a late writer cannot install an older view.

This milestone amends ADR-0036 twice, and both amendments are corrections rather than additions. A cohort now 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 while a balance comparison could not tell two equal reserves apart. The registry accordingly refuses two cohorts sharing a reservoir. A cohort may also now be vacant, holding no classes, no members and no reserve, through a separate factory so vacancy is always deliberate and create goes on refusing a draft that merely has no classes. Without that, a population declining to exactly zero would be unrepresentable and a caller would be forced to clamp, which is the thing this ADR exists to prevent. A vacant cohort is not an extinction: the record, its genome, its habitat and its provenance all remain.

Alternatives Considered

Computing the fluxes here from rates would be a model, and would make one of the candidates ECOLOGY_MODEL wants compared into the only one that exists. Clamping at zero and reporting a warning was rejected because a warning is not a refusal and the result would still propagate. Deriving the resulting age structure by ageing the classes is impossible without the within-class distribution ADR-0036 deliberately discards; asking the caller for it is honest about what the record knows. Keeping counts in whole members would make a population below one member round to zero, which the model forbids being read as extinction. Deleting a cohort that reaches zero would destroy the genome and habitat association that makes absence recoverable, and is the false extinction named in the risk column. Threading the reservoir through each request instead of binding it to the record was rejected above. Letting the advance perform several ledger transactions would give up atomicity for no gain, since one transaction holds all four legs.

Benefits

Whatever model runs above this, its arithmetic has to close, and an interval it cannot integrate fails loudly with enough information to subdivide. Conservation is the ledger's property rather than a claim. Births cannot create biomass because there is no way to express it. A population can shrink below one member, and reach zero, without anything being deleted or declared extinct.

Costs

The caller supplies the resulting age structure, which is more work than being handed one and is a modelling decision it must make. Four fluxes plus a structure is a wide request. A plan holds copies of both cohorts. An interval is accounted for as a whole, so a caller that needs finer granularity subdivides and pays for several plans. The residual carried by a class that has fallen below one member cannot hold reserve, because ADR-0036 gives reserve to members and a fraction is not one yet; that biomass has to go somewhere the same interval.

Risks

Accounting is not fidelity. Nothing here says the proposed fluxes are ecologically reasonable, and a model that conserves exactly can still be wrong in every other way; M4.5 is where resolution equivalence is measured. The interval is not checked for stability, only for closure, so a caller can propose a long interval whose arithmetic closes and whose ecology is nonsense. The declared age structure is not verified to be what ageing would produce, because that cannot be checked without the distribution the record does not keep. Emigration escrows into a reservoir this milestone does not settle with, so a destination cohort receiving it is TransferPopulation and does not exist. Ownership remains a single-process invariant. Nothing is serialized.

Consequences

Test that an interval with no flux still advances the clock and submits no ledger transaction, that births change the population and leave the reserve untouched, and that death, predation, immigration and emigration each move biomass once to the right counterparty with the conserved total unchanged. Test that a loss exceeding the population or any one inventory channel is refused rather than clamped, at the boundary of a single millionth of a member, and that taking exactly everything is vacancy rather than refusal. Test that a population below one member is still a population and that its record stays installed. Test that a declared result which does not match the fluxes is refused, in both directions, for counts and for biomass. Test that an empty or backward interval, a foreign owner and a repeated revision are refused. Test that a commit against a record that has moved on, or a reservoir that no longer holds what was counted, changes nothing in either the ledger or the registry, and that one plan cannot be committed twice. Test over many seeded interval sequences that the conserved total never moves, that the cohort's reservoir always equals its recorded reserve, and that both the accepted and the refused paths actually occur. No genome schema, mutation catalog, archive, ledger, episode driver, ensemble, renderer or deployment changes.