Files
aevolution/docs/ROADMAP.md
T

12 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 biology/metabolism, world/resources 2.1 Energy enters only through named source; uptake bounded by resources Closed-box balance plus external source accounting Arbitrary growth subsidies
2.3 Add consumer intentions and ingestion biology/digestion, simulation/spatial 2.2, 1.7 Shared validated action path transfers matter/energy Predator/prey transfer and dead-action rejection Consuming twice in same tick
2.4 Death and decomposition biology/lifecycle, ecology 2.3 Active capability ends; corpse pool transfers conserved nutrients Death terminality, decomposition limits, ledger audit Nutrients double counted
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.

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.