Files
aevolution/README.md
T
dingo 5e168d67c3
Foundation / checks (ecs) (push) Successful in 2m26s
Foundation / checks (deploy) (push) Successful in 4m12s
Foundation / checks (network) (push) Successful in 20m57s
Foundation / checks (client) (push) Successful in 22m9s
Foundation / checks (tsan) (push) Successful in 28m49s
Foundation / checks (postgres) (push) Successful in 1h5m2s
Foundation / checks (checks) (push) Successful in 1h17m42s
Foundation / postgres-tools (push) Successful in 1m10s
Foundation / server-image (push) Successful in 3m51s
Foundation / image (push) Successful in 4m54s
feat(lifecycle): qualify portable maturing wildlife transfers
2026-10-19 09:09:15 -04:00

275 lines
14 KiB
Markdown

# 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.
[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. Durable rules-9 migration and
autonomous ecological qualification remain separate gates.
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.
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\<name>.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`.