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>
7.7 KiB
Cohort record, representation version 1
Scope: the tier 2 record defined by
ADR-0036 and shaped by
ECOLOGY_MODEL.md. Its validator is
src/ecology/cohort.cpp.
There is no byte layout here and no encoder. Unlike the genome record, a cohort is not hashed, not a mutation context and not exchanged between processes yet, so a wire format would be a format nothing writes or reads. Durable storage and cross-version migration are M7 and M8, and the version field exists so a later schema can fail closed on records it does not understand rather than guess. What this document pins is the meaning of each field and the invariants a record must satisfy to exist at all.
Not a network protocol, a durable format, a habitat geometry, a conversion transaction or a population model. Nothing here advances, collapses or materializes anything.
Record
| Field | Type | Meaning |
|---|---|---|
| representation version | u32 | 1. Unknown versions fail closed |
| habitat | u64 | Where the cohort is. Nonzero. Carries no geometry in version 1 |
| genome | u64 | The genome every member carries. Nonzero |
| owner worker | u64 | Who integrates this cohort. Nonzero |
| owner epoch | u64 | Which epoch that ownership is held under. Nonzero |
| last tick | u64 | The last interval boundary integrated to. Never runs backwards |
| revision | u64 | Nonzero. Strictly increases with every replacement within an epoch |
| conversion | u64 | The conversion that produced this record. Nonzero provenance |
| reservoir | u32 | Nonzero. The ledger reservoir holding this cohort's reserve |
| age classes | 1 to 64 | Ordered, disjoint, each non-empty. See below |
| approximation bound | count + inventory | Declared, never computed here |
Lineage is deliberately absent. Ancestry is resolved from the genome through
LineageArchive, so a cohort cannot hold a parentage that contradicts the
archive's and cannot invent precise parentage from a statistical membership,
which ECOLOGY_MODEL forbids.
Totals are absent for the same reason. Count, reserve and residual are summed from the classes on demand; a stored total is a second tally that can disagree with what it summarises.
Age classes
| Field | Type | Meaning |
|---|---|---|
| age low | u64 | Ticks, inclusive |
| age high | u64 | Ticks, exclusive. Must exceed age low |
| count | u64 | Whole members in this class |
| reserve | inventory | Energy and four matter channels held by the class in total |
| residual | u64 | Fraction of a member owed, over residual_scale (1,000,000) |
Each class holds its own count and its own reserve, so the record stores a distribution and not a mean. This is the point of the record: a count with a mean reserve cannot distinguish a cohort where every member is provisioned from one where half hold nothing, and no later stage can recover what that discards.
Within one class members are indistinguishable. That is the record's declared resolution and a real loss. A caller needing finer structure declares narrower classes; it does not divide a total afterwards. No accessor returns a mean, because an average that is easy to reach becomes the authority.
A residual is owed and not yet present. It is not a count, is never added to one, and is strictly less than one member, because at one member it is a member. Funding a residual against biomass is M4.3.
Invariants
A record that breaks any of these does not exist; construction returns the named error instead.
| Rejected | Error |
|---|---|
| Representation version other than 1 | unsupported_version |
| Zero habitat, genome, owner worker, owner epoch, revision, conversion or reservoir | invalid_identity |
| No age classes | no_age_classes |
| More than 64 age classes | overflow |
age_high <= age_low, or a class overlapping or preceding the one before it |
unordered_age_classes |
| A class with no members and nothing owed | empty_age_class |
| A class holding reserve with no members to own it | unowned_reserve |
| A residual of one member or more | residual_out_of_range |
| Counts, residuals or any inventory channel that would overflow when summed | overflow |
Every quantity is unsigned, so a negative reserve is not representable. What is rejected is a declared state that would require one: reserve held by a class with no members. Arithmetic that could produce one does not exist in this version, because this version performs none.
Ownership
CohortRegistry holds at most one record per habitat and genome. Two records of
one genome in one habitat would be two places the same biomass could be spent,
which is what ECOLOGY_MODEL locks against; here it is unrepresentable rather than
forbidden by convention.
| Rejected | Error |
|---|---|
| Installing a second record for one habitat and genome | duplicate_cohort |
| Installing a record whose reservoir another record already uses | duplicate_cohort |
| Replacing with a record naming a different reservoir | unknown_cohort |
| Replacing a record that is not installed, or naming a different habitat or genome | unknown_cohort |
| Replacing under a different worker | wrong_owner |
| Replacing under an older epoch | stale_epoch |
| Replacing with a repeated or older revision inside one epoch | stale_revision |
| Replacing with an earlier interval boundary, under any epoch | backward_tick |
Installing beyond max_cohorts (4,096) |
registry_full |
A replacement has to be a strictly later view of the same record. An epoch alone cannot establish that, because two writes an owner makes inside one epoch are otherwise interchangeable and replaying the earlier one would restore inventory the installed record had already spent. The revision orders writes within an epoch; a newer epoch may restart the series, since re-acquiring ownership begins a new one. The interval boundary is checked independently of both, so neither advancing a revision nor re-acquiring ownership rewinds simulated time. A later revision at the same boundary is legitimate and accepted: it is a correction.
Epochs make a stale writer fail locally; they say nothing about fencing between workers, which is M7 and M10. The registry is in-memory, single-process and holds no lock, lease or quorum.
A cohort is copy-only. A moved-from record would keep its identities and lose its classes, which is the invalid state construction refuses, so the implicit moves are suppressed and a move decays to a copy.
Vacancy
A cohort whose population reached exactly zero has no classes, no members and no reserve. It is built by a separate factory, so vacancy is always deliberate: the ordinary constructor goes on refusing a draft that merely has no classes, which would otherwise become a vacant record by accident.
| Rejected | Error |
|---|---|
| Building a vacant record from a draft that has classes | not_vacant |
| Building an ordinary record from a draft with no classes | no_age_classes |
Vacancy exists because a population declining to exactly zero has to be representable. Without it a caller would have to clamp, which ECOLOGY_MODEL forbids, and rounding a density to zero would become a deletion. A vacant cohort is not an extinction and not an absence: the record, its genome, its habitat, its owner and its provenance all remain, and it stays installed in the registry.
Reservoir
A cohort records which ledger reservoir holds its reserve. The reservoir is bound to the record rather than supplied alongside it, because an advance would otherwise be able to run one cohort's fluxes against another cohort's store, and comparing balances cannot tell two equal reserves apart. The registry refuses two records sharing a reservoir, and a replacement may not move a record to a different one: that would be other inventory holding this cohort, not a later view of this one.