Files
aevolution/docs/biology/ECOLOGY_MODEL.md
T
dingoandClaude Opus 5 d5b4bd068e Initial commit: architecture docs and headless engineering proof
Aeternalis Evolution, a custom-engine persistent evolutionary MMO.

This first commit establishes the project skeleton:

- Architecture and design docs: project vision, system overview,
  engineering constitution, roadmap, 19 ADRs, and the simulation,
  world, network, persistence and infrastructure architectures.
- Headless engineering proof: deterministic synthetic particles,
  component lifecycle, explicit PRNG streams, canonical snapshots
  and restored execution.
- Build and tooling: CMake 3.28+ / Ninja presets, C++23 feature
  check, clang-format and clang-tidy config, format check script,
  Windows check script, and a Docker build context.
- Tests: unit tests, benchmarks, a snapshot fuzz target and CLI
  integration wiring.

No gameplay, renderer, network service or running deployment yet.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-14 15:44:41 -04:00

5.3 KiB

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.

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.