215 lines
20 KiB
Markdown
215 lines
20 KiB
Markdown
# 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.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](engineering/AGGREGATE_BUDGET.md). No automatic tier policy
|
||
qualified. M5 may proceed independently; production tier selection needs the
|
||
fidelity and target-host follow-ups listed in that report.
|