# Aeternalis Evolution A custom-engine persistent evolutionary MMO. The world retains its biological history; each player life begins as a primitive cell and ends permanently. This repository starts with architecture and a headless engineering proof: deterministic synthetic particles, component lifecycle, explicit PRNG streams, canonical snapshots and restored execution. It contains no gameplay, renderer, network service. Dev verification manifests are separate from the simulation. ## Start here - [Project vision and locked requirements](docs/PROJECT_VISION.md) - [System overview and module boundaries](docs/architecture/SYSTEM_OVERVIEW.md) - [Engineering constitution](docs/engineering/ENGINEERING_CONSTITUTION.md) - [Architecture decisions and proposals](docs/adr/README.md) - [Actionable milestones 0–4 and later gates](docs/ROADMAP.md) - [Open design questions](docs/architecture/OPEN_QUESTIONS.md) - [World snapshots and edit journals](docs/world/WORLD_CODEC.md) - [Local file publication manifest](schemas/local-world-manifest.md) - [Transactional terrain excavation](docs/world/TERRAIN_EDITS.md) - [Bounded chunk ownership](docs/world/CHUNK_OWNERSHIP.md) - [Versioned abiotic base generation](docs/world/BASE_GENERATION.md) - [Actual validation results](docs/engineering/VALIDATION.md) - [Current delivery status and next steps](docs/STATUS.md) - [Region durability and state-closure contract](docs/architecture/REGION_DURABILITY.md) - [Bounded environmental intervals and resume](docs/architecture/ENVIRONMENTAL_SCHEDULING.md) - [Opt-in ECS evaluation and measurements](docs/engineering/ECS_EVALUATION.md) - [Sequential command scheduling and recovery](docs/architecture/SCHEDULER_CONTRACT.md) - [Local periodic spatial queries](docs/architecture/SPATIAL_CONTRACT.md) - [Energy/matter model and implemented ledger boundary](docs/biology/ENERGY_MODEL.md) - [Environmental units and habitat coupling](docs/world/ENVIRONMENTAL_UNITS.md) - [Optional finite environmental fields and snapshot format](docs/world/ENVIRONMENTAL_FIELDS.md) - [Read-only environment footprints and freshness](docs/world/ENVIRONMENT_VIEWS.md) - [Genome model and implemented v1 record](docs/biology/GENOME_MODEL.md) Read [AGENTS.md](AGENTS.md) before changing code. Architecture and contracts are authoritative over implementation. No external runtime library is needed for the initial proof. C++23 support is checked during configuration. ## Build and run Requires CMake 3.28+, Ninja and a C++23 compiler/standard library supporting `std::expected`. GCC 14 is the initial Linux CI target; MSVC 19.44 or newer is the Windows target. Detailed verified tool versions are in the validation report. ```sh cmake --preset debug cmake --build --preset debug ctest --preset debug ./build/debug/evo-sim --seed 123456 --entities 8 --ticks 1000 --verify-replay ``` On Windows use a Visual Studio x64 developer shell, or the repository's `tools/windows-check.ps1` helper. Executables have `.exe` suffix on Windows. ```sh ./build/debug/evo-sim --seed 123456 --entities 8 --ticks 500 --save state.evo ./build/debug/evo-sim --load state.evo --ticks 500 --output results.json ``` ```sh ./build/release/evo-sim --ecosystem --seed 0 --episodes 3000 ``` Ecosystem mode measures seeded bounded episodes of the synthetic feeding community and reports ticks, births, both mortality paths, extinctions and a fingerprint. It shares no state, snapshot or particle metric with the proof run, and its strategy constants are measurement inputs rather than simulation rules. See [ADR-0029](docs/adr/0029-ecosystem-driver-and-episodes.md) for scope. ```sh ./build/release/evo-sim --ensemble --seed 0 --seeds-per-cell 4 --strategies 3 --tick-limit 400 ``` Ensemble mode derives strategies from genomes instead of writing them, then runs them on that same driver over a resource and temperature gradient. Each cell's seeds are split in half and both halves are reported separately and never merged, so a difference that appears in one half only is visible as the seed artifact it is. Options belong to exactly one mode: `--episodes` counts episodes and is rejected here, `--seeds-per-cell` counts seeds and is rejected in ecosystem mode. A cell's numbers are not fitness, adaptation or balance, and the resource axis is deliberately not monotonic. Lifetimes are censored: an organism still alive when an episode stops is reported as a survivor with the time it was watched, never as a death, so `lived_ticks` and `observed_ticks` answer different questions. See [ADR-0035](docs/adr/0035-genome-ecology-ensembles.md) for scope and for why. The second command continues saved PRNG/component state. `--verify-replay` compares an uninterrupted run to a midpoint serialization/restore run. JSON reports the seed, ticks, active entities and canonical state hash. Snapshots are bounded local test files; they are not crash-consistent production storage. ## Checks and measurements ```sh cmake --build --preset debug --target format-check cmake --preset analysis cmake --build --preset analysis cmake --preset asan cmake --build --preset asan ctest --preset asan cmake --preset release cmake --build --preset release ctest --preset release ./build/release/evo-benchmark ./build/release/evo-spatial-benchmark ./build/release/evo-resolution-benchmark ./build/release/evo-cellular-reference --verify ./build/release/evo-cellular-cohorts --verify ./build/release/evo-chunk-layout ``` ASan uses UBSan too on supported Linux compilers. TSan has a separate `tsan` preset and is never combined with ASan. clang-format/tidy major 19 is the initial analysis baseline. The optional Clang libFuzzer target exercises snapshot restore. See [testing strategy](docs/engineering/TEST_STRATEGY.md) and [deployment scaffold](deploy/README.md) for scope and commands. ## Repository boundaries `include/evo` exposes core values and the headless simulation API. `src/simulation` implements component state, tick ordering and local snapshot codec. `src/accounting` provides the independent finite-inventory ledger; it is not yet part of particle snapshots. `src/processes` holds the synthetic producer, feeding, reproduction and episode fixtures built on that ledger; they are bounded experiments, not organism biology. `src/biology` holds the immutable genome record, the deterministic development that derives a phenotype from it and the metabolic budgets that give capability a cost, and the seeded mutation catalog that proposes successors and the archive that keeps them. Synthetic process fixtures remain separate from organism biology. [Regional cellular census](schemas/ecology/regional-cellular-census-v1.md) provides read-only local resident/presence/cohort and exact/descendant observations from current cellular owners. Retained departed history is excluded from owned stock. [Projection 2](schemas/ecology/regional-cellular-census-v2.md) additionally observes raw and portable exact-population offspring plans separately from expressed organisms and inventory; old projection-1 plan measures remain unobserved. [Committed regional history](schemas/ecology/committed-cellular-history-v1.md) now derives bounded, fully replayed census pages from the existing atomic biological journal. [Scoped multi-region queries](schemas/ecology/scoped-cellular-census-set-v1.md) require exact declared coverage/boundaries, consistent immutable genomes and disjoint resident identities before summing. [Consistent scoped snapshots](schemas/ecology/consistent-cellular-census-snapshot-v1.md) capture declared current heads in one short database snapshot, then fully replay the immutable cuts; concurrent atomic migration cannot split a selected pair. Schema 50's [registered-region coverage](schemas/ecology/registered-world-census-coverage-v1.md) requires every region in the durable authority registry, including unavailable owners, within the same selected database view. Schema 51's [history domain](schemas/ecology/database-history-domain-v1.md) identifies that database history and forks supported restores with parent/exact-cut provenance. Schema 52 also returns [verified pending handoffs](schemas/ecology/census-pending-migrations-v1.md) from that same view; staged ghosts never add census stock. Complete world/branch reconciliation, client queries and terminal extinction remain later gates. `apps/evo-sim` owns CLI/file I/O and reporting. `tests` holds contract, fuzz and measurement programs. `src/server/lifecycle` owns funded primitive founder creation and an in-memory cellular tick owner over the finite habitat. The cellular owner has durable profile-4 recovery/publication and the cellular worker/session path. Opt-in exact population profile 5 is described in [M12 durable populations](docs/engineering/M12_DURABLE_POPULATIONS.md); `--cellular-populations on|off` defaults to off. Its [owned intervals](docs/engineering/M12_OWNED_POPULATION_INTERVALS.md) survive replacement owners; biological migration, environmental coupling and production qualification remain in progress. The portable [biological transfer candidates](docs/engineering/M12_EXACT_BIOLOGICAL_TRANSFER.md) preserve exact identity/history and regional boundary budgets. Their scoped durable preparation/staging, atomic paired publication and verified recovery are implemented; [TLS transport fault checks](docs/engineering/M12_MIGRATION_TRANSPORT_FAULTS.md) cover independent local path loss and owner replacement. Linked ecology and deployment qualification remain open. Portable opt-in [rules-9 maturation](docs/adr/0157-funded-cellular-maturation.md) now funds real juveniles through adulthood and budding in the same raw/cohort kernel. [Schema 53's explicit durable upgrade](schemas/cellular-maturation-upgrade.md) retains both representations and their full recovery evidence. [Rules-9 census](docs/adr/0159-maturing-cellular-census.md) observes exact growing stock through verified history and registered snapshots; mixed rule cuts fail. [Portable rules-9 transfers](schemas/cellular-migration-trace-v2.md) retain exact growing bodies under a distinct replay version. [Schema 54](docs/adr/0161-durable-maturing-wildlife-transfer.md) admits those exact pairs through fenced freeze/stage/paired publication and verified recovery/census. Autonomous ecological and deployment qualification remain open. The microscope client is the M11 playtest path. `evo::simulation` remains graphics-, network- and database-independent. World0 is persistent state. No normal configure, build, test or CI job may create, reset, deploy to or delete it. Gitea builds the proof image for Harbor; a bounded dev verification Job and manual Argo templates are in [deploy/](deploy/README.md). Persistent-world deployment still requires storage, ownership and backup gates. The project license has not been selected. Do not infer an open-source license from a public dependency's license. M4.6 reproduction, measurements and limits: [aggregate budget report](docs/engineering/AGGREGATE_BUDGET.md). M12.2c's [current cellular reference](docs/engineering/M12_CELLULAR_REFERENCE.md) checks rules-8 encoded replay and offline closure. `evo-cellular-reference --verify` runs the short CTest matrix; without arguments it runs the full research matrix with local cost observations. This is an exact control, not production aggregation. [Unscripted generations](docs/engineering/M12_UNSCRIPTED_GENERATIONS.md) uses real funded player-origin offspring under the unchanged controller. Build `evo-cellular-generations`; `--verify` runs the short CTest contract and `--qualify` runs the declared 80,000-tick development/hold-out matrix with raw/cohort equality, whole-genome conversions, restores and resource controls. This is bounded ecology evidence, not actual-days or product acceptance. The opt-in [retained offspring-plan owner](docs/adr/0165-retained-cellular-offspring-plans.md) keeps parent anatomy separate from earned inherited changes and repeatedly funds offspring from the saved plan. Build `evo-cellular-inheritance-tests`; CTest `cellular-inherited-plans` and `cellular-inheritance-process-restart` cover its portable contract. [Format 8](schemas/cellular-lives-v8.md) is not admitted to existing durable bundles or live entry. Control succession and behavior/UI integration remain pending. [Inherited-plan replay](schemas/cellular-region-batch-v4.md) uses explicit raw trace 4 with owner 8/rules 10; old defaults remain trace 3. Build `evo-cellular-inheritance-replay-tests`; CTest `cellular-inherited-replay` and `cellular-inherited-replay-process-restart` compare recorded inputs and complete results with direct execution, including same-tick selection/birth. This is a portable prerequisite for durable admission. The [portable inheritance checkpoint upgrade](schemas/cellular-inheritance-upgrade.md) defines raw bundle 12 and an exact no-tick transformation from bundle 11. Build `evo-cellular-inheritance-checkpoint-tests`; CTest covers the manifest/payload contract and its separate-process reproduction. SQL publication and population support remain subsequent work. M5.1 local voxel/address API and scope: [local voxel contract](docs/world/LOCAL_VOXEL_CONTRACT.md). M5.8 process restart proof and measured costs: [world proof](docs/engineering/WORLD_PROOF.md). M6.4: [atomic environmental transfers](docs/world/ENVIRONMENTAL_TRANSFERS.md) own finite field and organism resource compartments together. Biology integration is next (M6.5); coupled snapshot/recovery remains M6.8. M6.5c: [persisted producer/consumer fixture](docs/biology/ENVIRONMENTAL_PROCESS.md), with finite source capture, tagged growth/feeding and complete rate/lifecycle snapshots. It is a library/test fixture; existing CLI modes and M2/M3 rules are unchanged. For the M6.5 boundary/seeded suite and local cost report, run `build/release/evo-environmental-qualification --long` (add `.exe` on Windows). See [environmental qualification](docs/engineering/ENVIRONMENTAL_QUALIFICATION.md) for parameters, coverage and limitations. The shorter suite runs through CTest. ## PostgreSQL bootstrap (M7.2) See [PostgreSQL setup](docs/infrastructure/POSTGRESQL.md) for the optional Linux adapter, isolated integration checks and Kubernetes Secret/migration instructions. The default simulation build does not require PostgreSQL. ## Native client dependency probe (M9.1) The optional SDL3 probe is separate from the headless targets. See [client dependency preparation and checks](docs/engineering/CLIENT_DEPENDENCIES.md). M9.2 supplies the [native engineering client](docs/engineering/CLIENT.md), with an immutable frame boundary and tested window/resource lifecycle. M9.3 adds [camera navigation and input intentions](docs/engineering/CAMERA_INPUT.md), with explicit UI capture and no authoritative movement or network connection. M9.4 renders [revision-tagged environment views](docs/engineering/ENVIRONMENT_RENDERING.md) with explicit missing/stale presentation from a local in-memory fixture authority. M9.5 adds [biology-derived organism rendering](docs/engineering/ORGANISM_RENDERING.md) with no player/NPC labels and an opt-in engineering inspector. ## Dev session protocol (M9.6) Opt-in and separate from headless targets. Prepare the pinned TLS library, then build and test: ```sh cmake -P tools/prepare-mbedtls.cmake cmake --preset network cmake --build --preset network ctest --preset network ``` See [DEV_SESSION_PROTOCOL](docs/networking/DEV_SESSION_PROTOCOL.md) and ADR-0082. `evo-client` (preset `client-network`, which includes QUIC) connects to a dev region over M10 sessions; see [M10_CLIENT_SESSIONS](docs/networking/M10_CLIENT_SESSIONS.md). The M9.7 path ([DEV_SESSION_OPERATIONS](docs/networking/DEV_SESSION_OPERATIONS.md)) is no longer used by the client. Windows: `tools/windows-check.ps1 -Preset network -Action check`. M9.8a engineering UI compatibility probe (does not change evo-client yet): ```sh cmake -P tools/prepare-sdl3.cmake cmake -P tools/prepare-imgui.cmake cmake --preset client-probe -DEVO_BUILD_UI_PROBE=ON cmake --build build/client-probe --target evo-ui-probe ctest --test-dir build/client-probe -R ui-probe --output-on-failure ``` Use an MSVC developer shell on Windows. See ADR-0084 and [the M9.8 plan](docs/engineering/M9_8_DELIVERY_PLAN.md) for the remaining low-spec qualification work. M9.8e Windows x64 tester ZIP (static runtime, notices, identity, checksums; ADR-0086): `tools\client\package-windows.ps1`, then `tools\client\verify-windows-package.ps1 -Zip build\packages\.zip`. See [CLIENT_PACKAGING](docs/engineering/CLIENT_PACKAGING.md). M10.2 QUIC transport (ADR-0090, opt-in): `cmake -P tools/prepare-mbedtls.cmake`, `cmake -P tools/prepare-msquic.cmake`, then preset `quic` (`cmake --preset quic && cmake --build --preset quic && ctest --preset quic`). Windows needs Strawberry Perl and NASM for the OpenSSL build; use `tools/windows-check.ps1 -Preset quic`.