Files
aevolution/docs/ROADMAP.md
T
dingoandClaude Opus 5 c84a701edf Add funded reproduction with retained lineage identity
Close the M2.5 fixture cycle. A bounded list of trusted reproduction
intents runs after feeding and before decomposition, so a consumer can
fund offspring from what it ingested and a process terminated in that
tick cannot reproduce. The intent names a withdrawal from the parent
reservoir; a fixed construction fraction endows the child and the
remainder becomes real heat and waste. Nothing is credited from outside
the community, so conserved totals are unchanged by a birth.

Reserved slots are pre-allocated at creation, so a birth never grows the
ledger and a full community rejects rather than funding a smaller child.
Slots never return to the unborn state, so process identities are never
reused, and a parent reference plus origin tick outlive both organisms
and survive decomposition. A child duplicates the configuration of its
parent because no genome exists yet; this is duplication, not heredity.

Default zero capacity leaves the M2.4 reservoir layout and every existing
result unchanged, including golden d61ad5bf0c928c76. Native Release,
clang-tidy analysis, ASan and format checks pass; Linux CI has not run
for this increment yet. This defines no reproductive strategy, fecundity
rule, mutation model, gestation, spatial placement or account ownership.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-21 20:36:49 -04:00

13 KiB
Raw Blame History

Engineering roadmap

Initial delivery: architecture, engineering standards, toolchain scaffold and a small deterministic state/restore proof. This is M0 plus a bounded M1 experiment; it is not a playable game or a completed universal kernel. Validation evidence belongs in VALIDATION.md. Tasks below are sized as independent reviews; dependent tasks begin after their contracts are settled.

M0 — Engineering foundation

ID / objective Files/modules Dependencies Completion criteria Tests / evidence Risk
0.1 Preserve vision and constraints docs/PROJECT_VISION.md, architecture/* Founding brief Locked vs proposed explicit; all open questions indexed Requirement-to-document review Silent game-rule invention
0.2 Select scoped toolchain and practices docs/adr/, engineering/, AGENTS.md 0.1 Dependency/ownership/error/determinism contracts agreed for proof C++23 expected feature probe Library support differs by compiler
0.3 Build minimal library and CLI CMakeLists.txt, cmake/, include/evo/, apps/evo-sim/ 0.2 Out-of-source configure/build on available toolchain; kernel dependency-free Debug + Release configure/build Accidental platform coupling
0.4 Add owned-code checks .clang-format, .clang-tidy, CMake presets 0.3 Format and static analysis runnable; warnings-as-errors scoped Run format/tidy and record tool versions Noisy analysis can cause ignored warnings
0.5 Add test and measurement harness tests/, benchmarks/, core/telemetry 0.3 Release-safe checks, CTest, benchmark metadata and bounded structured logs Deliberate invalid data fails; benchmark completes Home-grown harness grows into framework
0.6 Add sanitizers and fuzz entry CMake options, tests/fuzz/ 0.4–0.5 ASan/UBSan, separate TSan configs, bounded codec fuzz target Instrumented test jobs; fuzz smoke where toolchain supports it Platform sanitizer gaps
0.7 Container and CI skeleton deploy/docker/, .gitea/workflows/, tools/ 0.3–0.6 Build/test/analyze/container workflow; stateless dev Job via reviewed GitOps Local checks; Gitea container jobs; dev Job evidence separately Unpinned images, CI mistaken for executed validation
0.8 Close foundation increment README.md, engineering/VALIDATION.md 0.1–0.7 Exact tested/untested status, commands and next task recorded Reproduce from clean build Claiming production readiness prematurely

M1 — Universal simulation kernel

ID / objective Files/modules Dependencies Completion criteria Tests / evidence Risk
1.1 Implement fixed tick + PRNG proof core/random.hpp, simulation/world.* 0.2–0.5 Tick count and per-entity streams explicit; no wall clock Golden vectors, same-seed equality, different-seed divergence Draw-order drift
1.2 Implement minimal component lifecycle simulation/world.* 1.1, ADR-0005 Stable IDs, bounded creation/removal, read-only views Duplicate/stale ID, capacity and ordering tests ID reuse or reference invalidation
1.3 Canonical local snapshot and restore simulation/snapshot.cpp, schemas/proof-snapshot.md 1.2, ADR-0008 Bounded versioned byte format; validate before publish Round trip, corruption, overflow, truncation, version rejection Unsafe parsing, native padding
1.4 Freeze deterministic reference result tests/simulation_tests.cpp 1.3 Continuous and restored runs match agreed fingerprint Golden fingerprint and seeded property ensembles Test only comparing same broken implementation
1.5 Evaluate mature ECS adoption experiments/ecs/, ADR-0005, ADR-0021 1.2, biological component workload sketch Measured iteration/lifecycle/serialization cost and scoped choice Opt-in row/EnTT sparse/dense/churn comparison with canonical equality; production decision needs richer biology Premature general framework
1.6 Establish scheduler and input phases simulation/scheduler.*, ADR-0022 1.4–1.5 Sequential phase DAG, one writer, immutable bounded commands and atomic commit; parallel jobs deferred Permuted delivery gives equal state; admission, rollback and recovery tests Hidden ordering and partial mutation
1.7 Add spatial contract simulation/spatial/, units ADR 1.5–1.6 Local coordinates and bounded neighborhood queries Boundary/wrap/precision properties and brute-force comparison Planet precision leaking into local physics

The first increment implements 1.1–1.4 as a proof. M1.5 now has an isolated comparison and scoped recommendation; see engineering/ECS_EVALUATION.md for measured versus still-unmeasured coverage. M1.6 implements the sequential command boundary in ADR-0022; no parallel job execution is claimed. M1.7 spatial queries now have an exact linear-scan baseline, periodic-image oracle tests and a measured workload (ADR-0023). A generic ECS or job framework is not required to complete this proof. Production indexing awaits actual interaction workloads.

M2 — Minimal energy ecosystem

ID / objective Files/modules Dependencies Completion criteria Tests / evidence Risk
2.1 Ratify accounting units and ledger accounting/ledger.*, ENERGY_MODEL, ADR-0024 M1, units ADR Exact local units/ranges, finite inventories and atomic ordered transfers Unit-type separation, rollback/overflow/replay, million-transaction independent balance checks Mistaking conservation for valid biology
2.2 Add abiotic source and producer processes/producer.*, ADR-0025 2.1 Finite source capture, whole growth recipes, carried rate remainders and atomic owned ledger Closed-box audit, independent fractional reference, finite-resource and arithmetic limits Confusing synthetic process with organism biology
2.3 Add consumer intentions and ingestion processes/feeding.*, ADR-0026 2.2 Shared ledger and atomic tick; capped ordered feeding with heat/waste outputs Predation, contention, rollback, terminal depletion, replay/conservation Fixture rules becoming gameplay; spatial validation remains separate
2.4 Death and decomposition processes/feeding.*, ADR-0027 2.3 Terminal events preserve corpse inventory; corpses/waste share decay budget Terminality, rollback, cap sharing, mixed channels, nutrient regrowth and conservation Confusing fixture transfer rules with microbial chemistry
2.5 Reproduction and wildlife identity biology/reproduction, genome identity 2.4, reproduction contract Sufficient resources required; child consumes parent budget Insufficient investment, unique ID and ancestry tests Free offspring or implicit player ownership
2.6 Long-run ecosystem fixture apps/evo-sim, tests/ecosystem, metrics 2.2–2.5 Producer→consumer→death→nutrients cycle; report over million ticks Many seeds, nonnegative balances, measured extinction/diversity Passing invariants despite uninteresting ecology

M2 founder fixtures explicitly identify synthetic test-player origins; they do not introduce unrelated wildlife into persistent worlds. Morphology is absent. M2.1's transfer-only ledger is implemented separately from the particle world. M2.2 must define finite source flux, process-specific restrictions, rate residuals and the atomic boundary between biological state and its inventories. Snapshot integration requires its own versioned format; it is not provided by M1's codec. M2.2 now supplies the isolated synthetic process contract and implementation. M2.3 must establish interacting process ownership before introducing consumers; the existing fixture is not itself a complete ecosystem or an organism model. M2.3 now supplies this bounded shared ownership and ingestion fixture. M2.4 must retain remaining inventory on death and implement explicit corpse/decomposition flows, rather than relying on M2.3's zero-inventory depletion trigger. M2.4 now implements that terminal-inventory and bounded-return contract. M2.5 now supplies funded budding, bounded pre-allocated slot capacity and retained parent/origin identity (ADR-0028); offspring are paid for out of parent inventory and no trait varies between generations. M2.6 must exercise the whole cycle over seeded long runs; a closed conservation proof is not yet an interesting ecology.

M3 — Genome v0.1

ID / objective Files/modules Dependencies Completion criteria Tests / evidence Risk
3.1 Immutable genome schema and ancestry biology/genome, schemas, docs/biology M2, genome/heredity decisions Versioned developmental capability data; immutable parent references Canonical encoding, invalid graph and range tests Literal-DNA scope or class tree
3.2 Development pipeline biology/development, phenotype 3.1 Genome + environment develops explicit physical parameters Same input yields same phenotype; material/capability prerequisites Genome confused with runtime damage
3.3 Derive energetic components metabolism/movement/membrane adapters 3.2, M2 Size/membrane/movement tradeoffs affect several budgets Thicker structure costs matter and maintenance RPG modifiers reintroduced
3.4 Seeded mutation candidates biology/mutation 3.1–3.3, design decision Bounded reproducible candidates conditioned by legitimate context Prerequisite, cost, invalid-choice, fixed-seed tests Hidden deterministic best build or biased adaptation
3.5 Heredity/divergence history reproduction/genome/history contract 3.4, NPC-mutation decision Reproduction persists parent/child links; genome identity survives death Branching lineage fixtures and terminal organism tests Deleting extinct genomes
3.6 Genome ecology ensembles tests/ecosystem, tools/reports 3.5 Compare strategies under resource/temperature gradients Statistical distributions, conservation, diversity report Tuning one seed overfits

M4 — Population abstraction

ID / objective Files/modules Dependencies Completion criteria Tests / evidence Risk
4.1 Define cohort state and ownership biology/ecology, schemas/population M3, ECOLOGY_MODEL Genome/lineage, counts, age, reserves, residuals and ownership explicit Invalid cohort/negative reserve rejection Population averages hide viable outliers
4.2 Collapse active individuals ecology/conversion 4.1 Transfer IDs/reserves to one aggregate representation atomically Exact ledger conservation and crash-before/after commit tests Dual representation
4.3 Advance local cohorts ecology/population 4.2 Conservative birth/death/predation/migration accounting per interval Nonnegative counts, energy bounds, seeded ensembles Numerical instability / false extinctions
4.4 Materialize representatives ecology/materialization 4.3 Withdraw exact shares and residuals; preserve genome identity Repeated round trips, scarcity and adversarial oscillation Re-materialization becomes free healing
4.5 Validate resolution equivalence tests/ecosystem, benchmarks 4.4 100 individuals → aggregate → 10,000 ticks → representatives Conservation exactly; ecological distributions within documented tolerance Claiming identical trajectories at different resolution
4.6 Budget and review aggregate model docs/adr, simulation metrics 4.5 CPU/memory and error bounds justify tier policy Active/aggregate benchmark and ecological sensitivity report Premature world-scale claims

Later gates

Milestone Deliverable and acceptance gate
M5 Basic voxel world Sparse small-volume generation + modifications + restore; deterministic base and bounded delta tests; mesher remains an experiment
M6 Environmental resources Light/moisture/limited nutrients connected through conserved transfers; no full chemistry simulation
M7 Persistent region Unique fenced authority, durable outcomes, snapshots/replay, health/metrics, process-kill recovery; migrations before real data
M8 Kubernetes World0 Inventory actual host, provision dev/stage/world0 with guarded promotion and backups; delete worker pod and restore automatically; restore on independent storage verified
M9 Custom 2D client ADRs for SDL3, renderer and audio; usable window/input/camera, biological presentation, no NPC labels
M10 Realtime multiplayer Authenticated intentions, reliable outcomes, prediction/reconciliation/interpolation and interest; 20+ bot clients then measured scaling/fault tests
M11 Cellular gameplay Movement, feeding, predation, mutation, reproduction, descendants, total restart; playtest FUN and repeated-life variety
M12 Persistent ecology Days-long unattended worlds, genealogy, extinction evidence, player absence and diverse strategies; analyze collapse/runaway lineages
M13 3D R&D Isolated smooth meshing, body graph, procedural skin/physics/locomotion comparisons with measured exit criteria
M14 Multicellular transition Ratified biological transition and first cell→multicellular→3D slice with conserved ecological coupling

No date or production capacity is promised without staffing and benchmark data. Every release records simulation/world/network versions; biological upgrades use production snapshot → clone → migrate → accelerated comparison → approval.