Files
aevolution/docs/ROADMAP.md
T

20 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 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.1 now supplies that record (ADR-0030): seven versioned capability kinds with units, ranges, declared and mandated developmental edges, immutable ancestry and a canonical bounded encoding. It is validated once at the boundary and coupled to nothing. M3.2 now derives a phenotype from it (ADR-0031): mass, a declared cube geometry, maintenance and enabled components, as pure integer functions of genome, growth and environment, with a bounded plan reporting what further growth would require. Growth and damage are runtime state that never reach the genome. Nothing is spent yet. M3.3 now attaches those parameters to budgets (ADR-0032): body composition, maintenance, movement, construction, intake and reproduction investment, each derived from a different phenotype quantity so one parameter moves some budgets and not others. consumer_for is the first path from a genome into the M2 fixtures, and mass splits conserve exactly so a derived body can be spent through the ledger. M3.4 now proposes successors (ADR-0033): a bounded operator catalog whose eligibility is the M3.1 validation itself, drawn uniformly without replacement from a recorded context and returned in canonical order with nothing ranked. Selection regenerates the offer and refuses a changed context rather than substituting. Candidate count, mutation cost as a game rule, inherited versus acquired expression, NPC mutation and recombination stay open, and no organism mutates yet. M3.5 keeps what M3.4 produces (ADR-0034): an archive with no removal operation at all, so retention is a property of the interface rather than a rule. A genome outlives every organism that carried it, ancestry and descendants resolve through dead links, and a lineage with no living carrier is reported absent and never extinct, because terminal extinction needs a reconciled watermark this type cannot see. NPC mutation stays undecided: the archive records an origin event and never an actor. M4.1 opens M4 (ADR-0036): a validated Cohort holding age classes that each carry their own count and reserve, so the record stores a distribution rather than the mean the named risk warns about, with totals derived from those classes and no stored tally that could disagree. Lineage is absent by design, because ancestry is the archive's answer resolved from the genome. Residuals are integer fractions strictly below one member. CohortRegistry admits one record per habitat and genome and refuses replacement under a wrong worker or an older epoch, so ECOLOGY_MODEL's "no inventory spendable in two tiers" is enforced rather than described. No collapse, advance or materialization exists yet.

M4.2 moves individuals into that record (ADR-0037). Collapse is two phases over one sample: plan_collapse reads the members once and returns an immutable plan carrying an already-validated cohort, and commit_collapse applies exactly that plan without deriving anything, so a replay cannot resample. A controlled, suspended, dead or unsettled member refuses the whole plan instead of being skipped, because filtering would make adversarial selection indistinguishable from honest use. Ages are carried into declared classes and a member that fits none refuses the plan rather than being moved. Conservation runs through the ledger as one atomic transaction of one leg per member, each moving that member's whole reserve, and the destination is proved available before anything moves, so every rejection leaves both the ledger and the registry exactly as they were. What this cannot check is that the caller offered every member it had.

M4.3 advances a cohort over one declared interval (ADR-0038) without choosing an ecology: a model proposes fluxes and this accounts for them, checking that the declared result is exactly what they imply. Nothing is clamped, because a clamp is how an interval a model could not integrate becomes a plausible result and how a false extinction arrives; a loss larger than what is there refuses the interval and says whether it was the population or the biomass. Counts carry whole members and owed fractions together, so a population below one member is still a number. Biomass has no birth term at all, so newborns are necessarily funded from what the cohort already holds. It amends ADR-0036 twice: a cohort records the reservoir backing it, and may be vacant, because a decline to exactly zero had to be representable.

M4.4 turns whole members back into individuals (ADR-0039). A drawn member gets its class share by integer division rounded down, because rounding up would create biomass, and a class drawn empty hands over everything it held rather than leaving a reserve nobody owns. A residual is never drawable: an expected density is not an available individual. Age is taken as the oldest the class admits, so a round trip can only age someone and oscillation is strictly lossy rather than a way to reset age. The smoothing the declared resolution causes is demonstrated rather than hidden: a round trip is exact when each class holds one member and averages within a coarse class, and the mitigation is the caller's choice of classes.

M4.5 closes M4 by measuring what the aggregation costs (ADR-0040), and adds no library code: one rule is written once and applied at both resolutions, with a one-member-per-class control proving the two runs are the same rule before any divergence is attributed to resolution. The measurement is reported, not smoothed. At class widths of ten and fifty the aggregate population survives ten thousand ticks within 375 parts per thousand on population; at twenty-five, one hundred and two hundred it dies out entirely while the individual run sustains seventy-five members, which is a false extinction caused by resolution alone. The collapse is not monotone in width, so a resolution cannot be chosen by assuming degradation worsens smoothly. Conservation was exact at every tick in every run, including the ones that died out, which is precisely why conservation is not sufficient evidence. The comparison also found a real defect in M4.3: arrivals are now the first ledger leg, because an interval affordable as a whole was being refused leg by leg.

M3.6 closes M3 by making the pieces meet (ADR-0035): strategy_for turns a genome into the StrategyConfig the M2.6 driver already takes, founders are pre-diverged variants of one ancestor admitted to the archive, and evo-sim --ensemble runs them over a resource and temperature grid with every cell's seeds split in half and reported separately. The driver is untouched, so the M2.6 fingerprint still holds. Two findings are recorded rather than smoothed over: resource level never reaches strategy derivation, because a mature founder has an empty construction transition, and the resource axis is not monotonic, because feeding caps community income at one producer bite per tick. Nothing mutates during an episode, so NPC mutation stays open.

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.

M4.6 completed as measurement tooling and a policy review on 2026-09-26; see aggregate budget report. No automatic tier policy qualified. M5 may proceed independently; production tier selection needs the fidelity and target-host follow-ups listed in that report.