Three defects from review of 89ad95b.
An organism still alive when an episode stopped was recorded dead. A one-tick
run reported no extinctions while writing terminal records for founders that had
not died, and their watched time was added to the same total as completed
lifetimes. Observation ending is a fact about the run, not about the organism,
and ADR-0034 makes a recorded death terminal, so there was nothing to be
terminal about. Survivors stay living now and are counted apart, with their
watched time as the lower bound it is; lived_ticks and observed_ticks answer
different questions and are never summed together.
A genome without the reproduction capability derives a zero investment, which
the driver refused outright, so seeds 10, 12 and 15 failed the whole run.
Filtering those variants out before sampling would have been the worse repair:
the measured set would then be the fertile subset a guard approved of, and being
unable to reproduce is a result rather than grounds for exclusion. The driver
runs such a strategy and proposes no birth for it. ADR-0029 is amended rather
than quietly contradicted.
A half's thermal shortfall was assigned where it was documented as a total, so
two episodes at 15,000 reported 15,000.
Only configurations the driver already rejected behave differently, so the M2.6
pin 2cd4a15f9fbe9949 was checked rather than assumed and still holds. The
ensemble pin moved because the reported facts changed, not to pass a test; the
reason sits beside it. Each fix was confirmed load-bearing by reverting it alone.
Release 33/33, analysis, ASan 33/33 and clang-format all ran and passed here.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
129 lines
6.1 KiB
Markdown
129 lines
6.1 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)
|
||
- [Actual validation results](docs/engineering/VALIDATION.md)
|
||
- [Current delivery status and next steps](docs/STATUS.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)
|
||
- [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
|
||
```
|
||
|
||
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. No fixture reads
|
||
a genome yet.
|
||
`apps/evo-sim` owns CLI/file I/O
|
||
and reporting. `tests` holds contract,
|
||
fuzz and measurement programs. Future biology, world, networking and persistence
|
||
modules are documented boundaries; they are added when they have real behavior.
|
||
|
||
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.
|