# 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](engineering/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 now drives the whole cycle without a caller (ADR-0029). Two limits shape it: retained identities and capped slots mean one community is not a population, and with no maintenance cost an uneaten consumer never dies. It therefore measures many bounded episodes, with mortality from predation and a configured lifespan, rather than one continuous run. Over a million ticks conserve exactly, which demonstrates arithmetic, not ecology. M3 replaces duplicated strategies with heritable developmental capabilities. ## 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.