45 KiB
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 |
M5-M9 delivery gates
Status: planned, not implemented or deployed. These tasks expand the founding milestones without adopting new libraries, biological rules or production budgets. Module paths below are proposed boundaries; create them only when their task starts. Every row is an independently reviewable increment with buildable tests. Split a row further if its contract cannot be reviewed separately from its implementation.
M4.6 did not qualify an automatic tier policy. M5-M9 may use bounded active organisms and explicit test cohorts; they may not silently enable the failed aggregate model for live ecology. Reproduction cost semantics from ADR-0031/0032 remain a separate biology decision before claiming a biologically credible persistent ecosystem.
flowchart LR
M5[M5 sparse local world] --> M6[M6 conserved environment]
M6 --> M7[M7 durable region]
M7 --> M8D[M8 dev and stage recovery]
M8D --> M8W[M8 guarded World0 launch]
M7 --> M9[M9 custom 2D client]
M8D --> M9
M9 --> M10[M10 realtime multiplayer]
F[M4.6 fidelity follow-up] -. required before live aggregate selection .-> M10
The dotted dependency applies to using aggregate simulation, not to all M10 work. M9 local graphics experiments can begin after the M6 read-view contract; its server integration gate requires M7 and M8 dev/stage evidence, not premature World0 launch. No runtime service is added solely to match a diagram. Existing Gitea, Harbor and Argo setup is reused; image publication, Argo sync and successful workload execution are separate evidence.
Shared gate evidence
Each milestone closes with its ADR statuses, public contracts, reproducible commands, version changes, test results and remaining limits recorded in STATUS and VALIDATION. Tests run under NDEBUG; applicable Linux/Windows builds, format, tidy and sanitizer jobs must pass. Timing thresholds require a declared host and workload. A gate is not passed by an empty test, an image build, or a successful Kubernetes rollout alone. Changes to persisted rules/formats require compatibility and migration decisions.
M5 - Basic voxel world
Goal: a small, sparse, editable, headless 3D environmental volume, roughly the founding 100x100x100 test scale or a documented chunk equivalent. It must support deep/cavity edits without a surface-only assumption. Planet-scale geometry, spherical indexing, LOD solvers, meshing and a renderer remain outside this gate.
Entry: M4.6 report reviewed; WORLD_ARCHITECTURE and proposed ADR-0019 read. Scope and layout must be accepted in a new scoped ADR before implementing storage.
| ID / objective | Files/modules | Dependencies | Completion criteria | Tests / evidence | Risk |
|---|---|---|---|---|---|
| 5.1 Specify local world contract | docs/architecture/WORLD_ARCHITECTURE.md, docs/adr, include/evo/world | M4.6 | Define signed chunk addresses, voxel dimensions, local +Z-up frame, units, bounds and material/geometry representation; distinguish chunk, region and ecological cell | Address examples and independent round-trip oracle; rejected overflow cases | Accidentally choosing final planet topology |
| 5.2 Compare and select compact chunk layout | experiments/world, tests/benchmarks, ADR-0019 follow-up | 5.1 | Compare uniform/palette baseline and optional varying pages on uniform, mixed and excavated fixtures; pin initial chunk size and allocation limits from measurements | Resident/peak bytes including indexes, edit cost and encoded size; record rejected alternative | Compression overhead or dense hidden allocation |
| 5.3 Generate deterministic abiotic base | src/world/generation, include/evo/world, tests/world | 5.1-5.2 | Seed + address + generator/material versions yields identical chunks; adjacent chunks agree; generation creates no life | Frozen small fixtures, query-order independence, negative coordinates, boundary seams | Seeding depends on generation order |
| 5.4 Own sparse active chunks | src/world/chunks, tests/world | 5.2-5.3 | Absent chunks regenerate; bounded loading/eviction; immutable views carry revisions; dirty data cannot be silently evicted | Far-apart addresses, all-uniform worlds, memory cap/backpressure, stale view tests | Memory grows with address extent rather than touched data |
| 5.5 Apply transactional terrain edits | src/world/edits, schemas/world-edits, tests/world | 5.4 | Bounded edit commands with ID, request digest and expected revision; define multi-chunk atomic scope; account displaced volume/material into explicit destinations | Duplicate ID same/different payload, insufficient destination capacity, tunnel crossing seam, all-or-nothing rejection | Edits delete matter or partially publish |
| 5.6 Encode snapshots and edit journals | src/world/codec, schemas, tests/fuzz, apps/evo-tools | 5.3-5.5 | Canonical bounded format records address, base/generator/material versions, revision and covered edit sequence; restore base plus edits or compacted state | Round trip, malformed/truncated/oversized bytes, checksum/version errors, replay equality | Reinterpreting old chunks under new generator |
| 5.7 Compact and restore local state | src/world/journal, tools/world, tests/integration | 5.6 | Snapshot plus remaining journal reproduces uncompacted state; local-file publication has an explicit recovery contract; old source remains until verified replacement | Interrupted write/publish, corrupt candidate, missing sequence, disk-full injection | Treating uploaded/written bytes as committed state |
| 5.8 Close bounded world proof | docs/engineering, tests/benchmarks/world, apps/evo-tools | 5.1-5.7 | Reproduce create -> deep edit -> compact -> restart -> same hash and inventory; report memory/generation/edit/restore costs | Sparse/uniform/heavily modified workloads; unchanged-chunk regeneration; cross-platform golden checks | Small-volume result marketed as planet capacity |
Exit: headless sparse chunk proof is buildable and restorable with deterministic base/version retention and no unexplained material loss. M5 local files are not the M7 production durability path. Any simplified volume-to-matter mapping is explicitly versioned; M6 must reconcile it rather than invent a second inventory.
M5.1 is implemented under ADR-0042: see the local contract for exact units, address limits, negative seam examples and rejection rules. It does not allocate chunk storage. M5.2 is complete: ADR-0043 selects 16-cube uniform/palette/dense storage from the comparison. Next is 5.3: versioned deterministic abiotic generation.
Decisions still open: final spherical layout, region dimensions, adaptive LOD, field quantization beyond the initial experiment, hydrology and surface extraction. No Marching Cubes/Surface Nets/Dual Contouring selection is implied.
M6 - Environmental resources
Goal: organisms and a small voxel environment exchange finite resources through conserved accounting. Start with light/energy, water inventory with derived moisture, one or two named nutrients and organic matter. Full chemistry, atmospheric circulation, CFD, roots/canopies, erosion and 3D creature physics are later work.
Entry: M5 local world gate and ENERGY_MODEL reviewed. Resolve how microscopic 2D habitat area and effective depth map to environmental volume before connecting stores.
| ID / objective | Files/modules | Dependencies | Completion criteria | Tests / evidence | Risk |
|---|---|---|---|---|---|
| 6.1 Ratify resource and coupling units | docs/biology/ENERGY_MODEL.md, docs/world, docs/adr, include/evo/world | M5 | Name extensive inventories, derived concentrations/moisture, energy source/sink terms, rounding residuals and valid ranges; specify 2D-to-3D volume mapping | Dimensional examples, closed/open system equations and invalid conversions | Area or concentration silently creates mass |
| 6.2 Store optional environmental fields | src/world/fields, schemas/world-fields | 6.1, 5.2, 5.6 | Material defaults plus sparse water/nutrient/organic pages; material ID alone grants no extractable supply; snapshot/version fields | Uniform vs varying footprint, finite exhaustion, round trip, old-version rejection | Dozens of floats per voxel or duplicated baseline resources |
| 6.3 Publish read-only environment views | include/evo/world/environment, src/world/resources | 6.2 | Footprint query returns values with units, resolution, tick and chunk revisions; missing data is explicit, not zero/unlimited | Seams, unavailable chunks, stale revisions, deterministic query order | Stale reads authorize consumption |
| 6.4 Commit environmental transfers | src/world/transfers, src/accounting adapters | 6.1-6.3 | Plan against immutable view; single-owner commit atomically validates organism and environment debits/credits; command IDs and changed-payload rejection | Two organisms contend for last nutrient, duplicate transfer, rollback and source/destination ownership | Resource spendable in both voxel and organism store |
| 6.5 Couple one producer and consumer fixture | src/processes adapters, tests/ecosystem | 6.4, M2-M3 contracts | Defined source flux funds capture; growth consumes water/nutrients; feeding transfers existing biomass; no implicit maintenance or reproduction rule changes | Source-off/starvation, nutrient limitation, temperature/resource boundaries, seeded replay | Fixture constants become game rules |
| 6.6 Return dead biomass to environment | src/processes/decomposition, src/world/transfers | 6.5 | Terminal organisms cannot act; bounded decay returns exact matter and accounted energy; residuals survive ticks | Death during pending consumption, duplicate decay, partial decay and nutrient-fed regrowth | Corpse disappears or decomposition runs twice |
| 6.7 Schedule local environment intervals | src/simulation scheduling adapters, src/world/resources | 6.4-6.6 | Explicit fixed intervals and phase order; read/write revisions prevent double integration; bounded catch-up; no implicit cross-region exchange | Interval split/merge where mathematically valid, pause/resume, maximum backlog, stale boundary refusal | Different update rates manufacture resources |
| 6.8 Validate integrated environmental slice | tests/ecosystem, tests/integration, docs/engineering | 6.2-6.7 | Environment -> producer -> consumer -> death -> nutrients -> growth, with integrated snapshot/restore and explicit version bundle | Multi-seed long runs, independent per-channel conservation including reservoirs/residuals, restore/replay hashes and cost report | Conservation passes while ecology collapses |
Exit: one bounded microscopic habitat uses environmental inventories without cross-scale literal physics or resource duplication. Read views are suitable for a later client, but no rendering is required. Ecological results and failure regimes are reported separately from arithmetic. Unsupported distributed transfers remain rejected rather than simulated with untracked remote credits.
M7 - Persistent region server
Goal: a disposable authoritative headless process can recover a bounded region without losing acknowledged irreversible decisions. PostgreSQL is the preferred authority; object payloads sit behind a storage adapter. The library does not acquire SQL, network, Steam or Kubernetes dependencies.
Entry: M6 integrated state is serializable; inventory actual state still missing from snapshots, including lineage archive, genomes, RNG, residuals, pending commands and versions. No existing particle or genome codec is assumed to cover a full region. Follow PERSISTENCE_ARCHITECTURE and ADRs 0013/0016; the table adopts no client library.
| ID / objective | Files/modules | Dependencies | Completion criteria | Tests / evidence | Risk |
|---|---|---|---|---|---|
| 7.1 Define region durability contract | docs/adr, schemas/region, include/evo/persistence | M6 | Specify region identity, state closure, simulation/commit watermarks, batch limits, irreversible ACK semantics and recovery format; choose replay or explicit full checkpoint batches | State inventory audit and crash-point matrix; exact replay requirements identified | Semantic events omit movement/randomness needed for recovery |
| 7.2 Adopt storage dependencies and migrations | src/persistence/database, migrations, dependency manifests | 7.1, ADR-0013 | Evaluate/pin PostgreSQL client and server pair; parameterized SQL, typed adapter errors, I/O ownership and bounded connection/deadline rules; only needed tables | Real PostgreSQL clean migration, supported upgrade path, rollback-on-error and permission checks | Dependency exception/transaction behavior leaks into simulation |
| 7.3 Implement fenced region ownership | src/server/world_director, src/persistence/leases | 7.2 | Director suggests assignment; DB serializes holder/epoch/expiry; commits lock/check lease and predecessor; worker role cannot bypass guard | Two contenders, expired renewal, paused stale writer, partition and database-time tests | Lease field exists but writes bypass its fence |
| 7.4 Encode and publish committed checkpoints | src/persistence/snapshots, object adapter, schemas/region | 7.1-7.3 | Coherent state includes complete version/RNG/history references; immutable payload verified before fenced manifest publication; unreferenced uploads are orphans | Missing/corrupt objects, upload/manifest failure, size caps, retained generator/binary restore | Snapshot mixes speculative and committed state |
| 7.5 Commit replay batches and permanent outcomes | src/persistence/events, src/server/region_host | 7.3-7.4 | Contiguous replay/checkpoint chain, canonical command digests, idempotent decisions and transactional outbox; batch DB writes; irreversible outcomes final only after durable confirmation | Commit-before-ACK disconnect, changed retry payload, gap/reorder, partial batch and duplicate births/deaths | Ambiguous commit treated as rollback |
| 7.6 Host bounded authoritative ticks | apps/evo-server, src/server/region_host | 7.1, 7.5 | One simulation owner with bounded I/O queues; simulated vs committed tick exposed; pause region at pending irreversible outcome; drain/shutdown and fail-closed readiness | Store outage, queue saturation, renewal failure, SIGTERM/forced kill, tick-debt measurement | Dependent actions use uncommitted reproduction/death |
| 7.7 Recover and verify before readiness | src/persistence/recovery, tests/integration | 7.4-7.6 | Load verified committed checkpoint, replay complete tail, verify hash/inventories/history, acquire valid current authority before serving | Kill at every publication/ACK boundary; corrupt/missing tail quarantines region; no empty fallback world | Silent world reset or resumed stale owner |
| 7.8 Add operations endpoints and dev image | apps/evo-server, core telemetry adapters, deploy/docker | 7.6-7.7 | Separate liveness/readiness; metrics for debt, commit lag, lease safety, checkpoint age and queue bounds; non-root image with no embedded secrets | Real process probes, metric-label bounds, unavailable DB readiness, image smoke test | Healthy process mistaken for valid authority |
| 7.9 Clone, migrate and qualify durability | tools/world-clone, migrations, tests/recovery, docs/engineering | 7.7-7.8 | Consistent clone into isolated world identity; explicit rule/format rejection/migration; durable-history retention; measured recovery and batching latency | Clone cannot publish into source; baseline vs restored trajectory; migration failure and old-writer fencing | Clone shares production credentials or rules change on restore |
Exit: force-kill a real worker and recover through real storage with identical committed state, retained ancestry and unique durable authority. Zero lost acknowledged decisions under worker loss is required; the proposed 60-second recovery target is measured under a declared fixture, not a universal promise. Database failure withholds final outcomes and pauses before bounded pending/lease budgets expire.
Cross-region seamless handoff, distributed population transfer and public realtime multiplayer are not M7 acceptance claims. M7 lays their IDs/epochs/ownership contracts. A local recovery proof does not establish host-loss durability; that is the M8 launch gate.
M8 - Kubernetes dev/stage recovery and guarded World0
Goal: run the M7 server through the existing GitOps pipeline, then qualify durable World0 operation. Separate M8-dev/stage passed from M8-World0 launch passed. World0 is persistent state, never a disposable smoke-test namespace.
Entry: M7 recovery evidence and deployable digest. Reuse existing Gitea/Harbor/Argo configuration; inspect the actual cluster before selecting storage or replica counts. OPERATIONS and INFRASTRUCTURE_ARCHITECTURE govern protection and recovery semantics.
| ID / objective | Files/modules | Dependencies | Completion criteria | Tests / evidence | Risk |
|---|---|---|---|---|---|
| 8.1 Inventory host and establish budgets | docs/infrastructure/inventory, deploy environment values | M7 image; read-only cluster access | Record R730xd CPU/RAM/storage, CNI/CSI, reclaim policies, failure domains, DNS/TLS and available capacity; reserve OS/stores/observability/recovery headroom | Measured disk latency/capacity and workload tick/resource profile | Treating 128GB as simulation-only memory |
| 8.2 Isolate environments and secrets | deploy/kubernetes overlays, deploy/argocd | 8.1 | Dev/stage/world0 identities, accounts, quotas, secret references and deny-by-default flows; no secrets in Git; World0 pruning/deletion protections designed | RBAC negative tests, cross-environment denial, cleanup rejects World0; parent-app deletion protection | One permissive app or credential can destroy all worlds |
| 8.3 Provision durable stores in dev/stage | deploy storage manifests, migrations jobs, docs/runbooks | 8.1-8.2, 7.2 | Adopt supported PostgreSQL and maintained object-store deployment with pinned versions; verify PV retention and backup destination | Pod restart, missing volume refusal, object semantics/digests, credentials rotation, full disk | Local PV binds failover to lost node |
| 8.4 Deploy director and region host | deploy/kubernetes, deploy/argocd, .gitea/workflows | 8.3, 7.8 | Immutable image digest, measured resources, probes, security context and drain budget; actual Argo sync/workload evidence | Region ready only after lease/recovery; graceful rollout and forced worker deletion | Successful rollout hides failed region recovery |
| 8.5 Add observability and bounded background delivery | deploy monitoring, dashboards, optional bus ADR | 8.4 | Tick/lease/commit/storage/backup alerts and bounded logs; evaluate DB outbox before optional JetStream; no mandatory Redis/Kafka | Alert injection, backlog/retry/idempotency tests if bus adopted, telemetry cardinality/cost report | Broker redelivery changes authority or logs fill disk |
| 8.6 Exercise recovery under faults | deploy/workflows, tests/operations, runbooks | 8.4-8.5 | Dev/stage pod-kill restores committed world automatically; stale owner cannot resume; unavailable state never initializes fresh | Repeated pod kill, stale process, DB/object outage, partition, disk full; record RTO and zero lost ACKs | Happy-path pod restart mistaken for disaster recovery |
| 8.7 Verify off-host backup and clone restore | tools/backup, deploy/workflows, docs/infrastructure | 8.3, 7.9 | Coordinated manifest covers DB/WAL, objects, versions, binaries and in-flight state; restore on independent storage; retention/GC respects clone/backup pins | Rebuild isolated world from backup, corruption and missing-object failure, credential/key recovery | Backup exists but cannot reconstruct causal state |
| 8.8 Qualify World0 acknowledgment and promotion | docs/adr, deploy/world0 protections, operations runbook | 8.6-8.7 | Ratify measured RPO/RTO and host-loss causal durability before irreversible ACK; independent durable chain or keep launch blocked; explicit promotion of reviewed digest/state | Host-loss restore preserves deaths, offspring, inventory and ancestry; fence old environment; promotion audit | Old backup resurrects dead organisms or duplicates resources |
| 8.9 Prove upgrade and growth operations | deploy/workflows, node scheduling values, docs/engineering | 8.6-8.8 | Clone/migrate/accelerate/compare before world-wide rules change; label/affinity plan works on one node and admits added compute nodes | Dev/stage version-barrier rehearsal, failed migration recovery, additional-node scheduling where hardware exists | Mixed physical laws or assuming added CPU makes storage portable |
Dev/stage exit: a pinned M7 workload is observed running; pod termination yields automatic fenced recovery with measured costs and tested alerts. World0 launch exit: all independent recovery/acknowledgment, data-protection and explicit promotion gates pass. If no independent durable failure domain exists, dev/stage can proceed while World0 launch stays blocked; changing RPO silently is not a workaround. Do fault and prune drills in isolated clones, never by deleting World0's namespace or data.
Target recovery objectives in OPERATIONS remain proposals until measured and accepted. No multi-node HA claim is made for the single physical host. Optional JetStream is adopted only for a demonstrated delivery workload, not as lease authority.
M9 - Custom 2D engineering client
Goal: a native desktop cellular viewer/controller with input, camera, renderer, readable organism/environment views and a real development-server connection. It is an engineering client, not the M11 playable game or the M13 3D engine.
Entry: M6 view contracts; M7 durable authority for connection work and M8-dev/stage for deployment evidence. No Unreal/Unity, browser delivery, Steam dependency, 3D terrain meshing or procedural creature animation is required.
| ID / objective | Files/modules | Dependencies | Completion criteria | Tests / evidence | Risk |
|---|---|---|---|---|---|
| 9.1 Select scoped client dependencies | docs/adr, dependency manifests, CMake | M6 views, constitution | Evaluate SDL3 and Vulkan/thin alternatives for native 2D support, tooling, portability, maintenance/license/size; pin adopted subset; audio may be explicitly deferred | Minimal window/input/render probes on supported targets, reproducible acquisition and license records | Building a general renderer before validating cellular views |
| 9.2 Establish platform and render boundary | apps/evo-client, src/client/platform, src/render | 9.1 | Window/event loop, resize/DPI/focus handling, orderly resource ownership; renderer consumes immutable views; headless targets build without client dependencies | Open/close/recreate, minimized window, device/init failure, headless build with client disabled | GPU/window types leak into biological APIs |
| 9.3 Add camera and input intentions | src/client/input, src/client/camera | 9.2, M6 coordinate contract | Pan/zoom and world-screen mapping; bounded intentions carry sequence/tick; UI focus prevents accidental world input | DPI/resize/zoom round trips, focus loss, key release, invalid ranges | Pixels become authority coordinates or stuck movement |
| 9.4 Render microscopic environment | src/render/environment, src/client/views | 9.2-9.3, 6.3 | Resource fields and boundaries render from revision-tagged views; missing/stale data has explicit presentation; no unbounded geometry/texture growth | Synthetic known fields, camera seams, stale update and frame/resource profile | Rendering changes resource simulation or hides missing data |
| 9.5 Render organisms and debug views | src/render/organism, src/client/ui | 9.4, M3 phenotype contracts | Visual parameters derive from available biology; players/NPCs use identical biological rendering; optional ImGui stays engineering UI | Same phenotype renders identically across controller types; death/removal, dense scenes, no player/NPC/level labels | Debug ownership labels become gameplay UI |
| 9.6 Define a narrow secure dev-session protocol | docs/networking, schemas/view, src/network adapters | 7.8, 9.3, ADR-0017 | Versioned bounded view/intent envelope, session identity, epoch and commit watermark; choose maintained transport/crypto for this scope; test identity is explicitly dev-only | Codec fuzz/bounds, unsupported versions, auth/replay/rate rejection, no native-struct trust | A temporary unauthenticated protocol escapes into production |
| 9.7 Connect to one authoritative dev region | src/client/session, src/server/session adapter | 9.6, M8-dev/stage | Real desktop-to-server connection, snapshot display and minimal admitted intent; reconnect requests fresh baseline; final outcomes reflect durable server ACK | Disconnect/reconnect, stale epoch, server pod restart, rejected intention and duplicate session tests | Client state or reconnect becomes authority |
| 9.8 Validate presentation and package the client | tools/client packaging, tests/client, docs/engineering | 9.1-9.7 | Reproducible native artifact, bounded snapshot/render queues, frame/memory report and documented manual visual checks | Install/run on supported dev platforms; long session, resolution/DPI matrix, headless regression suite | Declaring FUN or multiplayer scalability from a viewer |
Exit: a packaged native client opens, renders an authoritative cellular development scene, submits a bounded test intention and recovers its view after the server restarts. The prototype session respects server authority and ownership epochs. M10 owns the full real-time datagram/reliability selection, prediction, reconciliation, interpolation, interest management and 20+ client acceptance. M9 may use a scoped secure reliable channel if its ADR documents the limits and preserves transport-neutral semantics. No renderer is needed for server tests; no client may decide energy, mutation, reproduction or death. Steam and final player UI remain later product work.
Later gates
| Milestone | Deliverable and acceptance gate |
|---|---|
| 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 selection, 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-to-multicellular-to-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.