Files
aevolution/docs/biology/ECOLOGY_MODEL.md
T

326 lines
18 KiB
Markdown

# Ecology and simulation fidelity
Locked: scalable tiers and independent persistent descendants. Contracts below
are recommended; population math, lineage/species classifications are experiments.
| Tier | Owned state |
|---|---|
| 1 active | Identified individuals, position, phenotype, reserve, lifecycle and interactions |
| 2 local | Genome/cohort, counts, demographic distributions, matter/composition/reserve |
| 3 regional | Genome/lineage density distributions, inventories and environmental coupling |
No inventory is spendable in two tiers. Representatives are either debited cohort
shares or read-only noninteractive visuals. Never average distinct genomes into
one genome. Controlled organisms cannot collapse into progressing populations;
offline state is separate. Carry uncertainty and approximation error explicitly.
```mermaid
flowchart LR
I[Individuals] -->|freeze / reserve| T[Conversion transaction]
T -->|commit inventory| P[Population]
P <-->|conservative allocation| E[Regional ecology]
P -->|reserve feasible share| T
T -->|install identities| I
S[Suspended inventory] --- A[World accounting]
T --> A
P --> A
I --> A
```
PopulationRecord proposes habitat/genome/lineage identity, representation version,
owner epoch, last simulated tick, demographic bins, count semantics, material/
element inventory, reserve, spatial support, uncertainty and conversion sequence.
Preserve reproductive state or exclude it until conversion is valid. Expected
fractional density differs from an available individual; integer materialization
uses a seeded rule/residual and remains bounded by funded biomass/energy.
| Contract | Invariant |
|---|---|
| PlanCollapse | Reject controlled/suspended/dead/unsettled members; group compatible states and total exact inventory |
| CommitCollapse | Remove active spending rights and install cohort once under current epoch |
| AdvancePopulation | Bounded flux proposals over a declared interval and environment view |
| PlanMaterialize | Reserve feasible count, composition, reserve and demographics |
| CommitMaterialize | Debit cohort/install active identities while retaining provenance |
| TransferPopulation | Source escrow, idempotent destination credit and durable settlement |
Prefer local deterministic transactions. At a tick boundary freeze the old
representation, reserve under conversion ID/epoch, validate conservation and
destination, commit source removal/destination installation recoverably, then
expose. Recovery replays the committed sample, never samples again. A timeout
cannot release remote reservations. Cross-worker bus delivery is not exactly-once
authority. Count escrow in global totals.
Keep IDs in initial fixtures. Later statistical representation needs an ADR for
retained individuals versus cohort representatives; never invent precise parentage
from statistical ancestry. Adversarial conversion cannot select only healthy/high
energy members or reset age/injury/fertility/incubation. Unsupported states stay
explicit until a valid conversion exists.
## Population math and timing experiments
`N_next = N + births - deaths + immigration - emigration`.
`B_next = B + assimilated_growth + immigrant_biomass - mortality_biomass -
predation_biomass - emigrant_biomass`.
Births redistribute funded investment, not independently created biomass.
Predation changes counts and transfers biomass once; death returns detritus.
Compare bounded flux, seeded stochastic cohort and deterministic expected-density
models. Reject/subdivide unstable intervals; never hide negative populations with
clamps. Operational capacity limits backpressure rather than ecologically cull.
Shared bounded perception/intention controllers are the initial AI proposal;
evolving behavior/learning and universal species definitions remain open.
Advance whole declared intervals and record last committed tick. One owner
integrates each interval; late transfers are not new production. Expose catch-up
backlog/freshness. Whole-world outage wall-time catch-up is an explicit later
policy, while offline controlled biology remains frozen either way. Exact seeded
repeatability does not imply exact fidelity to individual ecology: compare matched
ensembles and publish population/biomass/diversity error envelopes.
## Extinction and acceptance
Distinguish no active observation, ecological absence and terminal extinction.
Require a globally reconciled watermark covering active individuals, cohorts,
eggs/spores, in-flight transfers and every viable store. Suspended members make
absence differ from recoverable viability: extinction stays provisional until
policy acceptance. Rounding a density to zero cannot declare irreversible
extinction. Preserve genome/ancestry/origin/extinction evidence permanently;
census series may be summarized at declared resolution. Clones have isolated
IDs/event destinations and cannot publish into World0.
M4: collapse 100 funded compatible individuals, simulate 10,000 ticks, materialize
feasible representatives. Test conservation including flux/residual/escrow, genome
identity, deterministic replay, crashes at every conversion boundary, interval
uniqueness, mixed-genome diversity, repeated conversion attacks, extreme rates,
late migrations/censuses and suspended viability. Compare explicit individuals:
passing conservation alone is insufficient ecological evidence.
## Implemented M2.6 episode boundary
[ADR-0029](../adr/0029-ecosystem-driver-and-episodes.md) measures bounded episodes
of the synthetic community. It settles none of the contracts above. There is no
tier, no cohort, no conversion transaction, no representative materialization and
no habitat. Every process stays an identified individual for its whole life.
Extinction here is the narrow, local statement that an episode has no living
consumer, recorded with the tick it happened. It is not the globally reconciled
watermark this document requires: there are no suspended members, eggs, spores,
in-flight transfers or other viable stores to reconcile, and no policy acceptance.
Surviving lineage counts come from retained parent references, not from species
classification, and lineages differ only by founder strategy because no genome
exists yet.
The shared bounded controller proposal is exercised only as a measurement driver.
It has no perception, no learning and no evolving behavior, and its constants are
inputs rather than results. Population math, cohort collapse and resolution
equivalence remain M4 work.
## Implemented M4.1 cohort record
[ADR-0036](../adr/0036-cohort-state-and-ownership.md) defines the tier 2 record
and who may act on it. It settles nothing else above: there is no conversion
transaction, no population advance, no representative materialization and no
habitat geometry. `PlanCollapse`, `CommitCollapse`, `AdvancePopulation`,
`PlanMaterialize`, `CommitMaterialize` and `TransferPopulation` remain contracts
nothing implements.
A cohort is per genome, so distinct genomes are never averaged into one. Its age
classes each carry their own count and their own reserve, which is how the record
answers the risk that population averages hide viable outliers: a count with a
mean reserve cannot distinguish a provisioned cohort from one where half the
members hold nothing, and nothing later can recover that. Within one class members
are indistinguishable, and that is the declared resolution rather than an
oversight. No accessor returns a mean.
Lineage is not stored. It is resolved from the genome through the archive, so a
cohort cannot claim a parentage the archive would contradict and cannot invent
precise parentage from statistical membership. Totals are derived from the classes
rather than stored beside them.
Fractional members are carried per class as integer numerators over a declared
scale, strictly below one member. An expected fractional density is therefore
never mistaken for an available individual. Funding a residual against biomass,
and the seeded rule that turns one into a member, are M4.3 and M4.4.
`CohortRegistry` enforces that no inventory is spendable in two tiers by admitting
at most one record per habitat and genome, and by requiring a replacement to be a
strictly later view of the same record: same worker, no older epoch, an advancing
revision within an epoch, and an interval boundary that never runs backwards. An
epoch alone is too coarse, because an owner replaying its own earlier record
inside one epoch would restore inventory the installed record had already spent. This is a single-process invariant: epochs
make a stale writer fail locally and are not cross-worker fencing, which is M7 and
M10. The registry holds no lock, lease or quorum, and nothing is serialized.
Approximation error is a declared field that nothing computes or checks yet.
Carrying a bound is not meeting one; M4.5 is where resolution equivalence is
measured. Conservation between a cohort and the rest of the world is the ledger's
property and is not asserted by this type, which holds an inventory without
participating in any transfer.
## Implemented M4.2 collapse
[ADR-0037](../adr/0037-collapse-to-cohort.md) implements `PlanCollapse` and
`CommitCollapse` for a single habitat and genome in one process. It settles
nothing else: `AdvancePopulation`, `PlanMaterialize`, `CommitMaterialize` and
`TransferPopulation` remain contracts nothing implements, and the direction is
one-way until M4.4.
Collapse is two phases over one sample, so recovery replays a committed sample and
never samples again: the plan is immutable, carries an already-validated cohort,
and commit derives nothing. Members that are controlled, suspended, dead or
unsettled are rejected as this document requires, and rejection refuses the whole
plan rather than dropping the member. That is what makes adversarial selection
visible: a conversion cannot quietly exclude the unhealthy and still look honest.
Age, and the per-class reserve distribution, are carried through unchanged; a
member whose age fits no declared class refuses the plan rather than being moved
into one.
Exact inventory is totalled through the ledger, not alongside it. One atomic
transaction carries one leg per member, each moving that member's entire reserve,
so the conserved total is unchanged by construction and no remainder is left in a
second tier. The destination is proved available and empty before anything moves,
so a refusal cannot strand biomass in a reservoir nothing owns and a cohort's
recorded reserve is the whole of what backs it rather than a part sharing a
reservoir with inventory it never sampled. Every rejection leaves both the ledger
and the registry exactly as they were.
Two gaps are explicit. This cannot establish that the members offered were all the
members there were; completeness is the caller's obligation. And "remove active
spending rights" is implemented as emptying, because the ledger has no reservoir
removal: nothing prevents a later transfer crediting an emptied reservoir, and
only the registry's single-ownership rule bounds what that would mean. Durable
conversion sequence numbers, escrow and crash recovery across a process boundary
are M7 and M8; the before-and-after property proved here holds across a rejection
inside one process.
## Implemented M4.3 interval accounting
[ADR-0038](../adr/0038-interval-accounting.md) implements `AdvancePopulation` as
accounting rather than as a model. The population maths above stays an experiment:
no birth rate, mortality curve, functional response or carrying capacity is chosen
here, so none of the candidate models listed above has been made the only one.
What is enforced is the arithmetic around whichever model runs.
Nothing is clamped. A loss larger than what is present refuses the interval and
names whether it was the population or the biomass, so an unstable interval is
rejected and can be subdivided. Subtraction is checked against what is there
rather than performed and repaired, so a negative population is never constructed.
Counts carry whole members and owed fractions as one scaled quantity, so a density
below one member is still a number and rounding it to zero is not available as a
decision. A population that reaches exactly zero becomes a vacant record, which is
neither absence nor extinction: the genome, the habitat, the owner and the
provenance all remain and the record stays installed. Deleting it would have been
the false extinction this milestone is named against.
Births redistribute funded investment because there is no term by which a birth
could bring biomass in. Immigration draws from a reservoir that already held the
inventory, so a late transfer is not new production. Death returns detritus and
predation transfers once, each to a named counterparty, as one atomic ledger
transaction against the cohort's reservoir.
Three gaps are explicit. Closure is checked and stability is not, so an interval
whose arithmetic balances and whose ecology is nonsense is accepted; comparing
matched ensembles and publishing error envelopes is M4.5. The resulting age
structure is supplied by the caller and is not verified to be what ageing would
produce, because ageing across a class boundary needs the within-class
distribution the declared resolution discards. And emigration escrows into a
reservoir nothing settles with, because `TransferPopulation` does not exist.
## Implemented M4.4 materialization
[ADR-0039](../adr/0039-materialize-representatives.md) implements
`PlanMaterialize` and `CommitMaterialize` for one cohort in one process.
`TransferPopulation` remains a contract nothing implements, and no
resolution-equivalence claim is made here.
Representatives are debited cohort shares, as this document requires, and never
anything else. A drawn member receives its class share by integer division rounded
down; rounding up would create biomass. A class drawn empty hands over everything
it held, because a class with no members may keep no reserve. A residual is never
drawable, so an expected fractional density stays distinct from an available
individual.
Age is carried, not reset, in the only direction that is safe when the exact value
is unrecoverable: a member materializes at the oldest age its class admits. Every
other rule lets an adversary who chooses when to convert roll back towards youth,
and repeating that is immortality. A round trip can therefore only age someone, so
oscillation is strictly lossy rather than free. This is a defence, not a model of
ageing, and under repeated conversion it will make a population look older than it
is.
What the declared resolution discards is stated rather than mitigated. Within one
class members are indistinguishable, so collapsing a starving member together with
a well-provisioned one and materializing both returns two average members, healing
the first at the second's expense. Conservation of the total is not evidence that
any individual is right. A round trip is exact when each class holds one member,
and the mitigation available to a caller is to declare narrower classes when it
collapses; nothing here can recover what a coarse class threw away.
A destination reservoir must be unowned as well as empty. A vacant cohort, or one
holding nothing, still owns its store, so crediting it would put inventory there
that the owning record does not account for. This holds on both sides of the
conversion, and the registry is asked rather than inferred from what a reservoir
contains.
A habitat and genome holding a vacant record is repopulated rather than refused,
because this document requires the record to be retained and a retained record
would otherwise bar the lineage from ever returning. The repopulation continues the
retained record's ownership and revision series; it does not reset them, and a
record that still holds a population is never merged into silently.
A materialized member carries the cohort's genome, its habitat and a fresh
identity, and nothing else. It has no parentage, no history and no condition,
because a cohort never carried them, and none of that may later be invented from a
statistical membership.
## Implemented M4.5 resolution comparison
[ADR-0040](../adr/0040-resolution-equivalence.md) carries out the comparison this
document asks for: a hundred funded individuals collapsed, advanced over ten
thousand ticks and materialized, against the same hundred simulated explicitly. The
numbers are in
[resolution-equivalence-msvc1944.jsonl](../engineering/results/resolution-equivalence-msvc1944.jsonl).
One rule is written once and applied at both resolutions, and a control with one
member per class establishes that the two runs are the same rule before any gap is
blamed on resolution. Every state the aggregate run passes through is checked to be
a representable cohort, so the envelope describes this library rather than a model
it could not hold.
The claim this document warns against is not made. Nothing asserts the trajectories
agree; the tests assert that they differ, so equivalence cannot be read as identity,
and the word is not used for what was measured.
What was measured is two regimes rather than a gradient. At some class widths the
aggregate tracks the individuals within a few hundred parts per thousand. At others
it dies out entirely while the individuals persist, which is a false extinction
caused by resolution alone: a whole class starves the moment its average cannot pay
upkeep, where individuals starve a few at a time and the survivors keep the shared
per-capita share up. This is the "population averages hide viable outliers" risk
arriving as a measurable quantity.
The collapse is not monotone in class width: a narrower class is not reliably safer.
A tier policy therefore cannot be derived by assuming degradation worsens smoothly
as resolution coarsens, and the boundary between the regimes is not characterised
here.
Conservation held exactly at every tick of every run, including the ones whose
populations died out. That is this document's point about conservation being
insufficient ecological evidence, demonstrated rather than restated.
Not covered: one genome only, so the mixed-genome diversity case remains open; one
model, one scarce axis and one initial distribution, so the numbers describe this
fixture; interval-length error is unmeasured, because the aggregate run sub-steps at
one tick to keep the averaging error attributable; and nothing here is distributed
or persistent.
## M4.6 budget review
[ADR-0041](../adr/0041-aggregate-budget.md) and the
[measurement report](../engineering/AGGREGATE_BUDGET.md) evaluate cost together with
population, energy and matter errors. No tested width qualifies across the scarcity
sweep. Faster execution alone does not authorize a resolution switch; automatic
selection remains disabled. This fixture is not a production ecological model.