Foundation / checks (deploy) (push) Successful in 6s
Foundation / checks (ecs) (push) Successful in 1m59s
Foundation / checks (client) (push) Successful in 12m44s
Foundation / checks (network) (push) Successful in 12m45s
Foundation / checks (tsan) (push) Successful in 8m5s
Foundation / checks (checks) (push) Successful in 32m4s
Foundation / postgres-tools (push) Canceled after 0s
Foundation / server-image (push) Canceled after 0s
Foundation / image (push) Canceled after 0s
Foundation / checks (postgres) (push) Canceled after 21m38s
ADR-0095 (presentation only): a drift-corrected monotonic tick clock that never runs more than one tick past the newest observation; remote probe markers shown 2-6 ticks behind (adaptive to snapshot gaps), interpolated, extrapolated for at most 2 ticks and then marked stale; appearance and removal at their snapshot ticks; organisms never extrapolated; sub-tick own-marker prediction. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
934 lines
95 KiB
Markdown
934 lines
95 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 |
|
||
|
||
## 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.
|
||
|
||
```mermaid
|
||
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](adr/0042-local-voxel-contract.md): see
|
||
[the local contract](world/LOCAL_VOXEL_CONTRACT.md) for exact units, address limits,
|
||
negative seam examples and rejection rules. It does not allocate chunk storage.
|
||
M5.2 is complete: [ADR-0043](adr/0043-chunk-layout.md) selects 16-cube
|
||
uniform/palette/dense storage from the [comparison](engineering/CHUNK_LAYOUT_EVALUATION.md).
|
||
M5.3 is complete under [ADR-0044](adr/0044-abiotic-generation.md):
|
||
[versioned abiotic generation](world/BASE_GENERATION.md) with frozen reference fixtures.
|
||
M5.4 is complete under [ADR-0045](adr/0045-bounded-chunk-ownership.md):
|
||
[bounded ownership](world/CHUNK_OWNERSHIP.md), compact storage, validated revision tokens
|
||
and dirty eviction refusal. M5.5 now implements [atomic excavation](world/TERRAIN_EDITS.md)
|
||
with per-material volume conservation under [ADR-0046](adr/0046-transactional-excavation.md).
|
||
M5.6 is complete under [ADR-0047](adr/0047-world-codec.md):
|
||
[canonical snapshots and edit journals](world/WORLD_CODEC.md) validate geometry, debris
|
||
and retry state together. M5.7 implements [single-writer local publication](adr/0048-local-publication.md):
|
||
two alternating manifest slots, immutable snapshot/journal payloads, verified detached
|
||
recovery, journal replay, checkpoint compaction and injected pre/post-commit interruption.
|
||
This is not a production multi-host durability or ownership service. M5.8 implements the [bounded world proof](engineering/WORLD_PROOF.md): separate
|
||
prepare/compact/verify processes, conservation oracles, frozen hashes and measured costs.
|
||
|
||
**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.
|
||
|
||
M6.1 ratifies [environmental units and coupling](world/ENVIRONMENTAL_UNITS.md)
|
||
under ADR-0050. Pure checked habitat/ratio/energy-integration helpers and dimensional
|
||
tests are implemented. No environmental stock, field codec, source scheduler or
|
||
terrain-to-biological-mass converter is implemented by this gate. Next: M6.2.
|
||
|
||
M6.2 implements [optional finite field storage](world/ENVIRONMENTAL_FIELDS.md),
|
||
material capacity defaults, bounded sparse pages, same-field local relocation and
|
||
canonical field snapshot v1 under ADR-0051. Rate-driven sources and combined
|
||
terrain/biology persistence are not provided by this independent codec. Next: M6.3.
|
||
|
||
M6.3 implements [read-only environment views](world/ENVIRONMENT_VIEWS.md) under
|
||
ADR-0052: bounded canonical voxel footprints, exact typed derived values, explicit
|
||
absence and tick/field/chunk freshness checks. No implicit terrain load or inventory
|
||
authorization occurs in views alone. M6.4 now implements [coordinated transfers](world/ENVIRONMENTAL_TRANSFERS.md) under ADR-0053: tagged resource accounts, atomic staged batches, capacity and ownership checks, and bounded exact retries. Coupled persistence remains M6.8. Next: M6.5 producer/consumer biology adapters.
|
||
|
||
## 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
|
||
|
||
**M9.1 status (2026-10-01):** implemented and locally validated; scoped SDL3
|
||
decision in ADR-0077, explicit pinned preparation, Windows native and Linux X11
|
||
software probes. Evidence and platform limits are in engineering/VALIDATION.md.
|
||
The added Gitea client job awaits remote verification.
|
||
|
||
**M9.2 status (2026-10-01):** native application, immutable frame boundary and
|
||
surface/resource lifecycle implemented under ADR-0078; Windows/Linux tests,
|
||
analysis, ASan/UBSan and headless replay evidence in engineering/VALIDATION.md.
|
||
Physical DPI/input and real GPU loss remain hardware qualification, not claims
|
||
from injected events.
|
||
|
||
**M9.3 status (2026-10-01):** local-mm camera, logical/drawable conversion,
|
||
cursor-anchored zoom, bounded sequence/tick intentions and focus/UI/backlog
|
||
suppression implemented under ADR-0079. Camera round trips and native event
|
||
regressions are recorded in engineering/VALIDATION.md. The app uses local
|
||
fixture ticks, not server time.
|
||
|
||
**M9.4 status (2026-10-01):** owned revision-tagged environment presentations,
|
||
ordered freshness (none/current/stale) and bounded camera-projected rendering
|
||
with explicit missing, unrequested, present-zero and undefined encodings under
|
||
ADR-0080. A local in-memory fixture authority stands in for server views until
|
||
M9.7. Evidence in engineering/VALIDATION.md.
|
||
|
||
**M9.5 status (2026-10-01):** biology-derived organism presentations with no
|
||
controller/ownership fields, identical rendering for identical phenotypes,
|
||
alive/dead/removed handling, budgeted detail with explicit truncation, and an
|
||
opt-in rectangle-only engineering inspector under ADR-0081. ImGui is not adopted.
|
||
Evidence in engineering/VALIDATION.md.
|
||
|
||
**M9.6 status (2026-10-01):** dev session protocol v1 (versioned bounded frames,
|
||
session/epoch/commit watermark, explicit little-endian codec), session admission
|
||
(scope, single-use grants, one session per subject, epoch, replay, tick window,
|
||
rate) and dev-only HMAC grants refused outside `dev`, over a TLS 1.3-only channel
|
||
with pinned Mbed TLS 4.1.1 LTS under ADR-0082. Sockets and region integration are
|
||
M9.7. Evidence in engineering/VALIDATION.md.
|
||
|
||
**M9.7 status (2026-10-01):** implemented and locally qualified under ADR-0083,
|
||
proceeding with the maintainer's agreement although M8-dev/stage is not yet passed.
|
||
Real TLS sessions inside evo-server: views from the region's own stores (explicitly
|
||
no individual organisms), admitted intentions ride synthetic inputs and return
|
||
durable no-effect outcomes, reconnect requests a fresh baseline, stale epochs and
|
||
duplicate sessions are refused. Evidence: Windows/Linux loopback suites and real
|
||
evo-server + PostgreSQL process tests including SIGKILL and a successor on the same
|
||
port. The in-cluster session drill (pod restart) awaits an operator with dev cluster
|
||
access. Next gate: M9.8.
|
||
|
||
**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 |
|
||
|
||
**M9.8a (2026-10-02):** isolated Dear ImGui 1.92.9b probe qualified on Windows/Linux;
|
||
M9.8b adds bounded UI state, protected external input capture and bounded session
|
||
event delivery. M9.8c integrates the launcher, legend, labelled inspector, click
|
||
selection and session panel. M9.8d adds rebindable controls (ADR-0085). M9.8e
|
||
packages a local Windows x64 ZIP (ADR-0086). M9.8f designs the dev session route,
|
||
committed disabled (ADR-0087). ADR-0084 records the toolkit scopes.
|
||
|
||
**M9.8 planning (2026-10-02):** user-confirmed Windows ZIP, temporary Gitea Actions
|
||
artifacts, labelled engineering UI/launcher and control rebinding. See the
|
||
[delivery segments](engineering/M9_8_DELIVERY_PLAN.md) and ADR-0084.
|
||
Low-spec VM qualification and live cluster evidence remain outstanding; neither
|
||
is implied by packaging completion.
|
||
|
||
**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.
|
||
|
||
## M10-M14 delivery gates
|
||
|
||
Status: **planned**. These gates extend the founding milestones; they do not mark
|
||
features implemented or ratify unresolved game rules. Each row uses the same
|
||
objective, boundary, dependency, acceptance, evidence and risk contract as M5-M9.
|
||
The shared gate evidence above applies, including version/migration review and
|
||
updates to STATUS and VALIDATION. Split implementation rows into contract and
|
||
implementation reviews when needed. Module paths are proposed, not instructions
|
||
to create empty frameworks. New dependencies require scoped ADRs and evidence.
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
M9[M9 native engineering client] --> M10[M10 authoritative multiplayer]
|
||
M10 --> M11[M11 playable cellular loop]
|
||
M11 --> M12[M12 persistent ecology]
|
||
F[M4.6 fidelity follow-up] --> Q[M12 qualified tier policy]
|
||
Q --> M12
|
||
M11 --> P[Cellular playability review]
|
||
M12 --> P
|
||
P --> M13[M13 isolated 3D research]
|
||
M13 --> M14[M14 multicellular slice]
|
||
M12 --> M14
|
||
W[M8 independent durability and promotion] -. required for World0 launch .-> L[Live World0]
|
||
M12 -. product readiness evidence .-> L
|
||
```
|
||
|
||
Dev/stage experiments can proceed while World0 launch is blocked by ADR-0075.
|
||
Passing a later feature gate does not lift that block or authorize promotion.
|
||
Bounded active-only tests can precede aggregate qualification; live automatic
|
||
aggregation cannot. M13 starts only after the cellular product is judged compelling,
|
||
not merely after its infrastructure tests pass. M14 is a bounded transition slice,
|
||
not a commitment to every body plan, planetary solver or locomotion mode.
|
||
|
||
## M10 - Real-time multiplayer cell simulation
|
||
|
||
**Goal:** responsive, authenticated, server-authoritative cellular sessions with
|
||
bounded replication and recovery under loss, overload and region transfer.
|
||
|
||
**Status (2026-10-03):** 10.1 ratified (ADR-0089, schemas/network/m10-budgets-v1.md,
|
||
networking/M10_TIMING_TRACES.md); targets are not yet qualified on the reference
|
||
hardware (10.9). 10.2 split: 10.2a selection, pins and build of msquic/OpenSSL done
|
||
(ADR-0090); 10.2b bounded channels, exact CA pinning and the impairment relay done;
|
||
10.2c loss/head-of-line measurements done (networking/M10_TRANSPORT_MEASUREMENTS.md).
|
||
10.3 split (ADR-0091): 10.3a account ids, ECDSA grants, identity adapter and region
|
||
session control done; 10.3b QUIC session login (schemas/network/session-v1.md) done;
|
||
10.3c durable per-world account control (schema v10) done. 10.4 split (ADR-0092):
|
||
10.4a intention/action protocol and admission done; 10.4b durable action records
|
||
(schema v11, same transaction as the checkpoint) done; 10.4c evo-server QUIC listener and
|
||
headless client with process kill tests done. 10.5 split (ADR-0093): 10.5a session
|
||
protocol v2 and the replication core done; 10.5b wiring (sessions, evo-server, client,
|
||
probe) with process evidence done; 10.5c engineering client switched to M10 sessions
|
||
(snapshot views, camera interest, grant bundles, msquic.dll in the Windows package) done.
|
||
10.6 split (ADR-0094, EXPERIMENT probe marker, not an organism movement rule): 10.6a shared
|
||
probe-motion-v1 rule, server markers, session protocol v3 marker records and the client
|
||
predictor done; 10.6b wiring (sessions, evo-server, probe, GUI marker) done; 10.6c impaired
|
||
traces done (networking/M10_PREDICTION_TRACES.md). 10.7 split (ADR-0095): 10.7a tick clock,
|
||
remote-marker interpolation and fractional prediction done; 10.7b client wiring, loss view
|
||
and two-client trace follow. 10.8-10.9 planned.
|
||
|
||
**Entry:** M9 client/session evidence and M7/M8 dev/stage durability. Read
|
||
NETWORK_ARCHITECTURE, PERSISTENCE_ARCHITECTURE and ADR-0017. The M9 transport is
|
||
not automatically the production selection; proof tick and region sizes remain
|
||
scoped experiments until measured here.
|
||
|
||
| ID / objective | Files/modules | Dependencies | Completion criteria | Tests / evidence | Risk |
|
||
|---|---|---|---|---|---|
|
||
| 10.1 Ratify protocol, timing and workload budgets | docs/networking, docs/adr, schemas/network | M9, M7 authority contracts | Define input scheduling window, tick/snapshot cadence, sequence wrap, session/epoch identity, baseline lifetime, queue/byte/work limits and target latency on named hardware | Trace-based timing experiments and explicit exact/tolerant determinism contract | Proof constants silently become game rules |
|
||
| 10.2 Select secure transport and implement bounded channels | src/network/transport, dependency manifests, CMake | 10.1, ADR-0017 evaluation | Compare maintained secure datagram/reliability options; pin selected library/crypto with license/maintenance evidence; separate superseding state from reliable actions; define MTU, congestion and timeout behavior | Loss/reorder/duplication/fragmentation and head-of-line comparison; codec fuzz, platform builds, malformed peer tests | Custom cryptography or retransmission amplification |
|
||
| 10.3 Bind sessions to accounts and control authority | src/server/session, src/client/session, backend identity adapter | 10.2, M9 dev identity boundary | Short-lived scoped grants, authenticated reconnect and unique organism control; provider-independent account IDs; dev identities cannot authenticate to production | Expiry, replay, foreign world/region, duplicate login, stolen stale grant, rate limiting and credential redaction | Two sessions control one life or test auth escapes dev |
|
||
| 10.4 Admit intentions and return durable outcomes | src/network/protocol, src/server admission, schemas/network | 10.1-10.3, M7 batch outcomes | Validate tick/sequence/ranges/targets under current authority; receipt, simulated-input and durable-outcome ACKs are distinct; stable action IDs resolve retries and unknown outcomes | Fabricated position/energy, future inputs, stale epochs, repeated action, lost ACK and crash before/after commit | An input ACK is mistaken for final biological success |
|
||
| 10.5 Replicate bounded snapshots and spatial interest | src/network/replication, src/network/interest, client views | 10.4, M6 views | Versioned baselines/deltas, entity removal and fresh-baseline recovery; spatial filter plus perception extension boundary; transmit no unnecessary hidden state or controller labels | Baseline eviction, sequence wrap, dense interest sets, information-leak assertions, bandwidth/memory report | Filtering only in the renderer leaks concealed organisms |
|
||
| 10.6 Predict and reconcile local movement | src/client/prediction, shared movement adapter | 10.4-10.5, movement experiment ADR | Replay bounded pending inputs from authoritative ACK state; smooth presentation separately; no predicted reproduction, mutation, energy grant or final death | Latency/jitter/loss traces, correction error distribution, rejected movement and restart resync | Prediction becomes authoritative or an unbounded replay queue |
|
||
| 10.7 Interpolate remote views and handle session loss | src/client/interpolation, src/client/session | 10.5-10.6 | Bounded interpolation/extrapolation, stale-view presentation and fresh reconnect baseline; no invented remote outcomes; disconnect stops admission without granting offline progression | Long gaps, reordered snapshots, death/removal, clock drift, reconnect to newer epoch | Extrapolation displays dead or nonexistent organisms as actionable |
|
||
| 10.8 Transfer authority between two regions | src/server/handoff, persistence transfer records, src/network/routing | 10.3-10.7, persistence handoff ADR ratified | Non-authoritative ghost, frozen source, durable staged destination and one committed authority switch; route session without a loading screen; in-flight inventories and retries recover once | Crash/partition at each transition, stale owner, duplicate transfer, crossing back, failed destination; unique owner and conservation checks | Region crossing duplicates inventory or leaves two active copies |
|
||
| 10.9 Qualify multiplayer load and abuse resistance | tests/network, tests/load, tools/network traces, docs/engineering | 10.1-10.8 | At least 20 simultaneous simulated clients plus native-client observation; then ramp beyond 20 to measured saturation; declare sustainable workload and overload response | Packet fuzz, floods, slow peers, lease loss, disconnect storms; tick/RTT/correction/bandwidth/CPU/memory distributions and sanitizer evidence | Bot throughput hides poor responsiveness or starvation |
|
||
|
||
**Exit:** the native client remains responsive against an authoritative server;
|
||
20+ clients and a two-region handoff pass reproducible network/fault scenarios.
|
||
All queues and per-tick work are bounded, rejected inputs cannot alter biology,
|
||
and final outcomes survive the declared dev/stage failure model. This does not
|
||
claim Internet-scale capacity, Steam readiness or a complete cellular game.
|
||
|
||
## M11 - Actual cellular gameplay
|
||
|
||
**Goal:** the first product judged primarily on FUN: repeated primitive-cell lives
|
||
with meaningful feeding, predation, mutation, reproduction and absolute death.
|
||
|
||
**Entry:** M10 authority and responsiveness; M3 genotype/development/phenotype and
|
||
M6 accounting contracts. Read GENOME_MODEL, ENERGY_MODEL and REPRODUCTION_MODEL.
|
||
Synthetic fixtures are test oracles, not accepted gameplay balance. Ratify the
|
||
offline lifecycle before enabling persistent player lives.
|
||
|
||
| ID / objective | Files/modules | Dependencies | Completion criteria | Tests / evidence | Risk |
|
||
|---|---|---|---|---|---|
|
||
| 11.1 Ratify cellular life and design decisions | docs/biology, docs/networking, docs/adr | M10, founding requirements | Decide bounded first-loop movement/feeding/reproduction rules, mutation timing/cost and heredity; resolve reproduction-cost semantics from ADR-0031/0032; document offline freeze/resume fairness and friend recognition or explicit social-feature deferral | State diagrams, adversarial logout scenarios, worked energy/matter budgets, review against locked vision | Fixture behavior or convenience invents permanent game rules |
|
||
| 11.2 Create primitive lives and persistent control | src/server/lifecycle, persistence life records, client session | 11.1, 10.3-10.4 | Every new life uses the same primitive founder rules with funded inventory/provenance; stable account/life separation; life state closes over timers, reserves and retries | Old/new account equivalence, concurrent spawn, failed allocation, restart/retry; no inherited biological power | Historical account data grants a stronger start |
|
||
| 11.3 Connect locomotion, feeding and predation | src/biology adapters, simulation interaction, client input | 11.1-11.2, M6 transfers | Server resolves spatial contact, perception, motion and intake; phenotype-derived maintenance/locomotion/defense costs; finite resources and corpse transfers | Range/speed cheats, contention, starvation/predation, closed-box conservation; movement playtest traces | Attractive motion hides free energy or arbitrary RPG modifiers |
|
||
| 11.4 Apply earned mutation choices through development | src/biology/mutation, development, client mutation UI | 11.1, 11.3, M3 candidates/archive | Reproducible contextual offers; stale selections rejected; prerequisites and funded development enforced; immutable genome ancestry; no visible linear class tree | Same context/seed offers, stale offer after resource change, failure rollback, restart during choice, multi-system tradeoffs | Mutation UI bypasses costs or implies a guaranteed progression |
|
||
| 11.5 Reproduce funded autonomous descendants | src/biology/reproduction, src/server wildlife controllers, archive | 11.1, 11.3-11.4 | One bounded accepted reproductive strategy; parent investment funds descendants and records ancestry durably; descendants use shared biological intentions, are unowned wildlife and survive parent death/logout | Insufficient resources, duplicate request/ACK loss, birth/death races, deterministic bounded AI, genetic vulnerability comparisons | Free offspring, player ownership, or special NPC biological rules |
|
||
| 11.6 Commit permadeath and complete restart | src/server/lifecycle, persistence history, client death flow | 11.2-11.5 | Death terminal across reconnect/recovery; corpse inventory preserved; next life is primitive; existing descendants/history remain; no resurrection or corpse-retrieval shortcut | Death versus mutation/birth/logout races, crash at commit, old session replay, repeated-life independence | Recovery or UI restart resurrects a dead life |
|
||
| 11.7 Freeze offline organisms and resume uniquely | src/server/lifecycle, persistence suspended state, client session | 11.1-11.6 | Implement ratified detectable-disconnect/logout boundary; no movement, feeding, growth, mutation, reproduction or timer progression after freeze; suspended inventory accounted separately; safe unique resume | Long offline interval, repeated disconnect, suspended worker recovery, death at freeze boundary, duplicate resume and wildlife continuation | Logout becomes an escape exploit or offline farm |
|
||
| 11.8 Deliver readable cellular gameplay UI | src/client/ui, organism/environment presentation, client packaging | 11.3-11.7, M9 | Energy/resource needs, mutation tradeoffs and death causes understandable; shared phenotype visuals for players/NPCs; separate authorized friend mechanism only if ratified; debug tools separated | First-session observation, input/accessibility checks, phenotype visual parity, sensory information-leak tests | Engineering UI or controller labels become the player experience |
|
||
| 11.9 Run repeated-life playtests and close the loop | tools/playtest telemetry, docs/engineering/playtests, tests/gameplay | 11.2-11.8 | Predeclare playtest questions and participant/session sample; assess movement, food decisions, predation, tradeoffs, descendants and variety over multiple lives; record issues and retest changes | Human feedback plus bounded consent-aware telemetry, death causes/build diversity, full-loop replay and crash regression | Engineering success mistaken for fun or tuning to one seed |
|
||
|
||
**Exit:** players can complete repeated lives from primitive spawn through feeding,
|
||
reproduction/mutation and permanent death. Descendants remain wildlife and offline
|
||
players do not progress. A recorded product review accepts the cellular loop or
|
||
keeps iteration open; no invented retention percentage substitutes for that review.
|
||
M12 supplies sustained world ecology rather than short-session evidence alone.
|
||
|
||
## M12 - Persistent ecology
|
||
|
||
**Goal:** player-derived lineages and ecological consequences survive player absence
|
||
for days, with defensible aggregation, ancestry and extinction records.
|
||
|
||
**Entry:** M11 playable loop and durable wildlife; M4.6's failed fidelity cases must
|
||
be resolved before automatic tier selection. Read ECOLOGY_MODEL and the aggregate
|
||
budget report. Neither conservation alone nor exact replay proves ecological fidelity.
|
||
|
||
| ID / objective | Files/modules | Dependencies | Completion criteria | Tests / evidence | Risk |
|
||
|---|---|---|---|---|---|
|
||
| 12.1 Ratify ecological identity and time policies | docs/biology, docs/adr, schemas/ecology | M11, M4.6 evidence | Define lineage/species distinction, extinction evidence, viable reserves, outage catch-up and uncertainty; decide NPC mutation/heredity and whether behavior can evolve, including explicit deferral | Worked histories with dormant cells/eggs/spores/transfers; no fixed plant/animal classes or mandatory intelligence | Classification becomes a class tree or absence is called extinction |
|
||
| 12.2 Qualify a population model and tier policy | experiments/resolution, src/ecology, docs/engineering | 12.1, M4.6 follow-up, M11 rules | Repair or replace unqualified model; paired active/cohort ensembles meet declared demographic/biomass/diversity error bounds on target host; document unsupported states and active fallback budgets | Reproduce known false extinctions, hold-out seeds/regimes, interval/bin sensitivity, cost/error curves | Faster aggregation silently destroys otherwise viable lineages |
|
||
| 12.3 Persist automatic tier transitions | src/ecology/conversion, region scheduling, persistence codecs | 12.2, M7 recovery | Atomic collapse/materialize with deterministic committed samples, one spendable representation, retained genome identity, demographic state and residuals; controlled/suspended organisms excluded | Crashes at conversion boundaries, oscillation/cherry-picking, no healing/age reset, inventory and ancestry audits | LOD switching creates resources or fictitious exact parentage |
|
||
| 12.4 Schedule unattended ecology and migration | src/server/ecology_worker, src/ecology/flux, persistence transfers | 12.1-12.3, 10.8 | Owned bounded intervals, backlog/freshness reporting and idempotent cross-region escrow; regional aggregates only where fidelity qualifies; no silent skipped intervals or ecological culling on overload | Player-free advance, worker loss, delayed boundary data, partitioned migration, overload/catch-up; count in-transit stock | Background replay spends an interval twice or timeout duplicates migrants |
|
||
| 12.5 Couple ecological and environmental budgets | src/ecology, src/world/resources, regional fields | 12.2-12.4, M6 | Producers/consumers/decay share finite resources; scoped regional atmosphere/water exchanges use conserved inventories, explicit boundaries and versioned coefficients | Closed/open budgets, nutrient exhaustion, oxygen/carbon response, slow/fast interval comparisons | Implicit infinite nutrients or unsupported global climate realism |
|
||
| 12.6 Retain genealogy and historical queries | src/biology/archive, backend history, migrations, client codex | 12.1, 12.3-12.4 | Parent/child genomes and lineage divergence retained after extinction; population history queryable; statistical ancestry distinguished from known individual ancestry; account history grants no power | Restore archived extinct genomes, common-ancestor fixtures, idempotent events, bounded large-tree queries | Compaction discards history or invented genealogy appears precise |
|
||
| 12.7 Reconcile extinction from complete world evidence | src/ecology/reconciliation, backend history, persistence watermarks | 12.1, 12.4, 12.6 | Durable watermark covers active/cohort, dormant/suspended, viable reproductive and in-flight stores; incomplete evidence reports unknown/absent; terminal extinction follows accepted semantics | Last-member migration, disconnected worker, dormant survivor, residual viable stock, late duplicate event and restored world | One empty region falsely declares a lineage globally extinct |
|
||
| 12.8 Soak diverse worlds and close ecological risks | tools/soak, tests/ecosystem, deploy/workflows, docs/engineering | 12.2-12.7, M8 clone/restore | Run reproducible multi-seed worlds unattended for days with real worker restarts; accelerated runs supplement wall-time evidence; measure diversity, monopolies, collapse, cycles, ancestry growth and costs | Seed/regime matrix, no-player versus returning-player scenarios, full conservation/retention audit, clone rule-change comparison | A stable but biologically empty or monopolized world passes |
|
||
| 12.9 Review cellular product and expansion readiness | docs/STATUS, docs/engineering/playtests, docs/ROADMAP | 11.9, 12.8 | Returning players encounter changed player-derived ecology; record remaining exploit/fidelity/cost limits; explicit go/no-go for 3D R&D and separate World0 promotion review | Repeated-session playtests and reproducible soak evidence; confirm M8 World0 block remains unless independently lifted | 3D work displaces unresolved core gameplay and ecology |
|
||
|
||
**Exit:** unattended ecology, player absence, worker recovery and historical queries
|
||
are demonstrated together. Extinction follows reconciled biological evidence;
|
||
lineages never disappear merely because their player died. Capacity limits cause
|
||
documented admission/backpressure, not fabricated natural selection. World0 launch
|
||
still requires the independent durability and promotion evidence from M8.
|
||
|
||
## M13 - 3D technology R&D
|
||
|
||
**Goal:** choose feasible 3D techniques through isolated, measured prototypes before
|
||
integrating them into the persistent cellular product.
|
||
|
||
**Entry:** 12.9 accepts cellular playability/ecology and authorizes the research scope.
|
||
Read WORLD_ARCHITECTURE and GENOME_MODEL. Every experiment declares workloads,
|
||
budgets and go/no-go criteria before comparison. Prototype output is disposable;
|
||
accepted formats/algorithms require ADRs. No planet-wide dense allocation.
|
||
|
||
| ID / objective | Files/modules | Dependencies | Completion criteria | Tests / evidence | Risk |
|
||
|---|---|---|---|---|---|
|
||
| 13.1 Bound research and evaluation workloads | docs/adr, experiments/3d, docs/engineering | 12.9, M5/M6 constraints | Define representative terrain edits, body graphs, habitats and locomotion families; target hardware, accuracy/frame/CPU/memory budgets and experiment exit criteria | Review matrix with comparable inputs, reference outputs and headless/client boundaries | Attractive demos set architecture without representative measurements |
|
||
| 13.2 Compare planet coordinates and sparse LOD | experiments/planet, src/world contracts | 13.1, M5 coordinates | Compare spherical indexing strategies; region-local precision, seam/deep-edit addressing and sparse refinement with inventory partition rules | Pole/seam/address round trips, deep-to-core sampled edits, refine/coarsen conservation, bounded residency | Global float error, seam cracks or detailed resources created by refinement |
|
||
| 13.3 Compare smooth surface extraction | experiments/meshing, docs/adr | 13.1-13.2, M5 codecs | Compare Marching Cubes, Surface Nets and Dual Contouring on shared datasets; assess topology, edits, sharp/smooth features, LOD seams and collision derivation before selection | Thin surfaces/caves, neighbor revisions, dirty rebuild latency, mesh memory and visual/collision checks | Selecting a mesher from appearance alone |
|
||
| 13.4 Prototype 3D rendering and streamed caches | experiments/render3d, src/render boundary | 13.2-13.3, M9 renderer | Bounded immutable-view streaming, origin shifts and stale mesh discard; meshes/collision caches regenerable from versioned source; headless simulation remains independent | Camera travel, cache pressure, device failure, terrain edits and frame-time distributions | Renderer owns world state or stale geometry becomes authoritative |
|
||
| 13.5 Define developmental body graphs and constraints | experiments/body_graph, docs/biology, schemas proposals | 13.1, M3 development | Typed tissues/organs/attachments/joints/vascular/neural dependencies; genome limits legal structures; funded construction derives mass, maintenance and vulnerable structures | Invalid/disconnected/cyclic graphs as appropriate, symmetry/range tests, material budgets, canonical graph round trips | Arbitrary mesh editor bypasses evolved developmental capability |
|
||
| 13.6 Derive meshes and physics from phenotype | experiments/organism_mesh, experiments/physics, docs/adr | 13.5, 13.4 for visuals | Compare specialized physics/library options for the scoped bodies; derive skin, collisions, mass/inertia and damage mapping from one phenotype; document determinism tolerances | Diverse/sessile/mobile graphs, degenerate bodies, joint stability, damage consistency and CPU/memory comparison | Rendered anatomy and simulated mass disagree |
|
||
| 13.7 Prototype procedural locomotion under damage | experiments/locomotion, body/physics adapters | 13.5-13.6 | Compare feasible crawling/swimming/walking techniques on evolved bodies; costed propulsion and center-of-mass control; scoped limb-loss compensation; record unsupported flight/other modes | Shape/limb-count sweep, terrain contact, missing limb, solver stability and energy/force bounds | Hand-authored animation or free motion becomes the foundational solution |
|
||
| 13.8 Prototype conservative micro/macro exchange | experiments/ecological_coupling, docs/world, schemas proposals | 13.2, 12.3-12.5 | Explicit habitat depth/units and disjoint owned stocks; microbial biomass funds macro food density and corpse transfers fund micro nutrients; durable idempotent transfer design | Closed-box bidirectional cycle, concurrent consumption, delayed exchange, restart/retry and LOD oscillation | Same biomass is edible independently in both domains |
|
||
| 13.9 Select the bounded integration path | docs/adr, docs/engineering, dependency manifests | 13.2-13.8 | Publish comparison evidence and accepted/deferred choices; pin only adopted dependencies; document migrations and M14 body/habitat limits; reject failed experiments explicitly | Reproducible benchmark corpus, headless regression, review against predeclared budgets | Research prototypes silently become production systems |
|
||
|
||
**Exit:** measured choices support one constrained multicellular slice. Unsupported
|
||
locomotion, planet solvers and morphology remain documented R&D, not placeholders
|
||
in the live simulation. Full hydrology, atmosphere, flight and arbitrary creatures
|
||
are not prerequisites unless the selected slice explicitly needs them.
|
||
|
||
## M14 - Multicellular transition
|
||
|
||
**Goal:** one persistent life can develop from a primitive cell into a funded
|
||
multicellular organism and enter a bounded 3D habitat without losing authority,
|
||
history or conservation. Remaining unicellular must remain a viable strategy.
|
||
|
||
**Entry:** M12 persistent cellular ecology and M13 accepted prototypes. Ratify the
|
||
transition criteria; no automatic stage ladder, account-age shortcut or intelligence
|
||
requirement. Existing worlds require clone/migration/ecological comparison before
|
||
the new rules can be promoted.
|
||
|
||
| ID / objective | Files/modules | Dependencies | Completion criteria | Tests / evidence | Risk |
|
||
|---|---|---|---|---|---|
|
||
| 14.1 Ratify transition biology and life identity | docs/biology, docs/world, docs/adr | 12.9, 13.9 | Decide physiological/developmental/environmental prerequisites, investment, timing, failure behavior and continuity of organism identity; distinguish growth from reproduction; define bounded supported body/habitat scope | Worked conservation/ancestry examples, cellular alternatives, failure/death/logout scenarios | Multicellularity becomes a mandatory level checkpoint |
|
||
| 14.2 Implement funded multicellular development | src/biology/development, phenotype/body graph, persistence codecs | 14.1, 13.5-13.6 | Validated genome develops supported tissues/body graph; construction, maintenance and growth consume real budgets; developmental intermediates persist and remain vulnerable by ratified rules | Insufficient material/oxygen/energy, invalid anatomy, deterministic plan/replay, partial growth restore, mutation incompatibility | Transition grants a free mature body |
|
||
| 14.3 Implement atomic domain transfer | src/server/domain_transition, persistence transfer records, schemas | 14.1-14.2, 10.8, 13.8 | Source freezes and escrows complete life state; destination stages valid 3D state; one durable authority transfer preserves inventory, genome, ancestry, timers and action history; no literal cross-scale physics | Crash/partition at every phase, repeated transition, capacity rejection, stale epoch, death/logout race, rollback only before committed switch | Two living copies, lost life or new attempt duplicates resources |
|
||
| 14.4 Integrate a bounded authoritative 3D habitat | src/world, src/server region adapter, src/network views | 14.3, 13.2-13.4, M10 | Stream sparse terrain and accepted collision/physics; validate movement and interactions on server; maintain epoch/perception/baseline semantics with bounded interest and physics cost | Seam crossing, stale collision revision, terrain edit, speed/range abuse, resource pressure and restart | 3D client or disposable mesh becomes authoritative |
|
||
| 14.5 Activate conservative cross-domain ecology | src/ecology coupling, src/world/resources, persistence journals | 14.3-14.4, 13.8, 12.4-12.5 | Disjoint microbial/population/macro stocks with explicit transfer intervals and residuals; producers fund food density, consumption debits it, death/decomposition returns nutrients | Repeated closed-cycle budgets, simultaneous consumers, stale fields, delayed transfers, recovery with escrow | Ecological bridge creates biomass or couples incompatible timesteps |
|
||
| 14.6 Expose genome-constrained morphology and motion | src/client morphology UI, render organism, procedural locomotion | 14.2, 14.4, 13.5-13.7 | Player edits only developable structures; server validates/funds changes; renderer and locomotion derive from phenotype; preview is non-authoritative; no mandatory humanoid/intelligent form | Forged edit, unavailable tissue, unaffordable design, limb loss, alternate valid morphology, visual/physics parity | Cosmetic editing changes biology for free |
|
||
| 14.7 Preserve life, offspring and offline invariants in 3D | src/server/lifecycle, biology/reproduction, history | 14.3-14.6, M11/M12 | Ratified reproduction yields autonomous funded descendants; player death is permanent and next life primitive; suspension freezes every 3D biological timer; genealogy spans domains without invented parentage | Death during transfer/growth, reconnect after death, offspring persist, offline gestation/growth freeze, same-account fresh start | 3D arrival becomes a checkpoint or inherited power |
|
||
| 14.8 Qualify save formats and ecosystem upgrades | migrations, tools/world-clone, tests/recovery, docs/engineering | 14.2-14.7, M8 upgrade gates | Version complete terrain/body/coupling/life state; clone old world, migrate, accelerate and compare; retain required generators/builds; failed migration leaves source intact; no mixed adjacent physical laws | Old/unsupported format refusal, corruption, transfer-in-flight restore, full history audit, ecological pre/post distributions | Valid schema migration catastrophically changes the living world |
|
||
| 14.9 Playtest and accept the first transition slice | tests/end_to_end, tools/playtest, docs/STATUS, docs/engineering | 14.4-14.8 | Native client demonstrates primitive cell → funded multicellular body → 3D habitat → death → primitive restart; cellular players/descendants continue in same ecological world; measured fun, clarity and costs | Multiple seeds/lives/body variants, uninterrupted versus recovered runs, human playtests and scoped load profile | One scripted transformation is mistaken for an evolvable persistent system |
|
||
|
||
**Exit:** the integrated transition is playable, conserves resources, survives
|
||
recovery and preserves absolute permadeath. The result supports only its declared
|
||
morphologies, habitats and load envelope. Further expansion requires measured
|
||
gates; neither civilization nor a predetermined species ladder is implied.
|
||
|
||
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.
|
||
|
||
M6.5 sequencing review: [ADR-0054](adr/0054-m65-source-persistence-prerequisite.md)
|
||
is proposed because ADR-0051 requires persistence before rates while ADR-0053 defers
|
||
coupled persistence to M6.8. Its recommended prerequisite and task breakdown are
|
||
pending scope confirmation; the M6.5 completion criteria above remain unchanged.
|
||
|
||
Accepted 2026-09-27: ADR-0054 brings coupled snapshot/restore into M6.5. M6.5a's
|
||
resource codec is implemented; the earlier pending-scope statement is superseded.
|
||
Next are 6.5b conversions, 6.5c complete rate/biology persistence and fixture, and
|
||
6.5d qualification. M6.8 retains the full decomposition/regrowth ecology gate.
|
||
|
||
M6.5b design complete (2026-09-27): [ADR-0055](adr/0055-environmental-process-contract.md)
|
||
and the [process contract](biology/ENVIRONMENTAL_PROCESS.md) specify conversions,
|
||
source residual policy, temperature gates, synthetic depletion and private resource
|
||
checkpoints with process retry history. Next: M6.5c implementation/persistence,
|
||
then M6.5d qualification. No rate-enabled runtime exists yet.
|
||
|
||
M6.5c implemented: complete process envelope and atomic environmental fixture.
|
||
Source rates, residuals, last funded interval, lifecycle and exact retry reports now
|
||
restore together; retained history is replay-validated against an audit anchor.
|
||
Next M6.5d: broader boundary/long-run qualification; M6.5 remains open until it passes.
|
||
|
||
M6.5d native qualification complete: [report](engineering/ENVIRONMENTAL_QUALIFICATION.md)
|
||
records boundary/malformed-state tests, 16-seed paired restore runs, more than a
|
||
million logical ticks and cost evidence. M6.5 is implemented and natively qualified;
|
||
Linux CI is separately pending verification. Next: M6.6 corpse/decay integration.
|
||
|
||
M6.6 implemented (2026-09-27): [ADR-0056](adr/0056-environmental-terminal-decay.md)
|
||
adds explicit terminal facts, retained corpse accounts, shared integer decay caps,
|
||
N/P mineralization and organic-energy heat release. Rules/envelope v2 restore
|
||
partial inventory, lifecycle and retry reports together; v1 stays byte-compatible.
|
||
Tests cover rollback, water headroom, shared caps, restored exact retries, history
|
||
eviction, malformed v2 envelopes and next-tick nutrient-fed growth. Next: M6.7
|
||
fixed environment interval scheduling; M6.8 retains the full integration proof.
|
||
|
||
M6.7 implemented (2026-09-27): ADR-0057 adds a stateless adapter for at most 64
|
||
explicit process ticks. World/frame, quantum and completed resource/process
|
||
revision are checked before work. Per-tick phases remain unchanged; a later tick
|
||
failure returns its committed prefix explicitly. Pause/resume needs no second
|
||
clock or snapshot format. Tests compare 1/3/17/64-wide batches to direct execution
|
||
for rules 1 and 2, restore between batches, partial failures and u64 boundaries.
|
||
Next: M6.8 integrated multi-seed ecosystem qualification and cost evidence.
|
||
|
||
M6.8 implemented and natively qualified: the integrated driver runs five regimes,
|
||
16 seeds and independent full-cycle episodes. Baseline demonstrates capture,
|
||
growth, feeding, consumer death, bounded nutrient return and two regrowth units;
|
||
negative regimes distinguish energy/nutrient/temperature/decay limitations.
|
||
Direct execution matches scheduled restore/retry continuation. Extended run:
|
||
5120 episodes, 655360 logical ticks, exact inventories and stable residency.
|
||
See engineering/ENVIRONMENTAL_SLICE_QUALIFICATION.md for costs and scope limits.
|
||
Next: M7.1 region durability contract; M6 does not claim durable worker recovery.
|
||
|
||
M7.1 design complete (2026-09-27): ADR-0058 chooses full checkpoint batches and
|
||
publishes REGION_DURABILITY.md plus schemas/region-commit.md. State closure,
|
||
watermarks, bounds, immutable candidate publication, exact retry reconciliation,
|
||
permanent ACKs and the crash-point matrix are explicit. This is a contract gate,
|
||
not a running database/server. M6 environmental state is complete only within its
|
||
profile; M7.4 must add archive serialization and organism/genome binding before
|
||
M7.9 can claim retained ancestry. The M7 exit criteria remain unchanged.
|
||
Next: M7.2 evaluate/pin storage dependencies and implement/test migrations.
|
||
|
||
M7.2 implemented and locally qualified (2026-09-28). ADR-0059 adopts the pinned
|
||
server/libpq pair, optional persistence adapter and transactional schema v1.
|
||
Private PostgreSQL integration checks passed in Release, analysis and ASan/UBSan;
|
||
container/cluster verification remains separate. Secret provisioning instructions
|
||
are in infrastructure/POSTGRESQL.md. Next: M7.3 fenced region ownership.
|
||
|
||
M7.3 implemented and locally qualified (2026-09-28). ADR-0060 adds schema v2:
|
||
database-time leases, DB-generated holders, never-reused epochs and a fenced head
|
||
advance that checks lease then predecessor under one row lock. The runtime role
|
||
gets EXECUTE only; table writes, provisioning and object creation are denied.
|
||
Real-PostgreSQL tests cover the scenarios the roadmap row requires:
|
||
- 64 two-contender acquisition rounds and 32 racing advances;
|
||
- expired renewal and a paused stale writer;
|
||
- a writer queued past expiry, which is judged by post-lock database time;
|
||
- an unknown renewal that fences locally.
|
||
|
||
Timings were selected and measured locally. The director is intentionally deferred
|
||
because it has no authority and would be a placeholder. Next: M7.4 checkpoint
|
||
codecs/publication. It must also revoke runtime EXECUTE on the bare head kernel.
|
||
|
||
M7.4 split into 7.4a (environmental-v1 publication) and 7.4b (lineage archive
|
||
codec and history-capable binding). M7.4a is implemented and locally qualified
|
||
(2026-09-28) under ADR-0061:
|
||
- Manifest v1 is 280 bytes and is parsed by the database itself.
|
||
- Schema v3 adds a commit chain with digest and head constraints, retained
|
||
builds, and fenced publication. The bare v2 kernel is dropped.
|
||
- SHA-256 comes from OpenSSL, and payloads go to an immutable filesystem store.
|
||
- Publication validates, uploads, verifies, then commits. Recovery re-digests and
|
||
verifies.
|
||
- Missing or corrupt objects, upload and manifest failures, orphans, size caps,
|
||
retained-build allowlists and restored-trajectory equality are covered.
|
||
|
||
Next: M7.4b. M7.4 stays open until it passes.
|
||
|
||
M7.4b implemented and locally qualified (2026-09-28); M7.4 is complete. ADR-0062
|
||
adds:
|
||
- A canonical lineage archive codec that decodes by replaying the archive's own
|
||
rules.
|
||
- `LineageRegion`, which binds the environmental accounts to archived organisms,
|
||
keeps identity high-waters, enforces closure, and records deaths in the
|
||
causing tick.
|
||
- Checkpoint profile 2, and schema v4 (profile-specific caps; the profile is
|
||
fixed per region).
|
||
Recovery restores retained genomes, ancestry and dead organisms, and continues
|
||
identically. Next: M7.5 durable decisions, history and outbox rows in the same
|
||
transaction, and commit-ID resolution.
|
||
|
||
M7.5 implemented and locally qualified (2026-09-28), under ADR-0063.
|
||
- Manifest v2 binds a per-tick validation trace and the decision block.
|
||
- Staging replays the trace from the committed predecessor payload.
|
||
- `RegionBatch` seals at a death or at 64 ticks and pauses until the commit is
|
||
confirmed.
|
||
- Schema v5 stores decisions and outbox rows atomically with each checkpoint,
|
||
with one terminal outcome per actor and immutable history.
|
||
- Exact retries return the original receipt; read-only resolution covers
|
||
ambiguous outcomes.
|
||
- Recovery reconciles decisions with the restored state.
|
||
Next: M7.6 hosts bounded authoritative ticks (apps/evo-server, region_host).
|
||
|
||
M7.6 implemented and locally qualified (2026-09-28), under ADR-0064.
|
||
- `RegionHost` is a single-owner state machine: acquire and recover, run,
|
||
resolve, drain and stop, or quarantine.
|
||
- Admission is bounded (64 inputs, 64 KiB) with backpressure, and
|
||
acknowledgements become final only after a confirmed commit.
|
||
- Tick debt is measured with bounded catch-up.
|
||
- A death pauses the region until it is durable.
|
||
- Readiness fails closed; storage outages, unknown outcomes and fences each have
|
||
a defined recovery.
|
||
- `evo-server` passed real SIGTERM drain and SIGKILL tests, with successor
|
||
recovery.
|
||
Next: M7.7 recovery verification at every kill boundary.
|
||
|
||
M7.7 implemented and locally qualified (2026-09-28), under ADR-0065.
|
||
- Before readiness, recovery replays the head's trace from its predecessor's
|
||
verified payload, requires the exact head bytes and decisions, and
|
||
quarantines on any missing or corrupt tail. Schema v6 adds the read-only
|
||
commit lookup.
|
||
- Real SIGKILL at five boundaries, a resumed SIGSTOPped owner, and damaged heads
|
||
all behave as the crash matrix requires.
|
||
Next: M7.8 operations endpoints and dev image.
|
||
|
||
M7.8 implemented and locally qualified (2026-09-28), under ADR-0066.
|
||
- `evo-server --ops-listen` serves `/livez` (loop alive), `/readyz` (current
|
||
authority only) and `/metrics` (30 fixed series with bounded labels).
|
||
- The responder is dependency-free, single-threaded and bounded.
|
||
- The `server-runtime` image is non-root with no secrets; a CI smoke job and a
|
||
Kubernetes example are included.
|
||
Next: M7.9 clone, migrate and qualify durability.
|
||
|
||
M7.9a implemented and locally qualified (2026-09-29), under ADR-0067:
|
||
- a verified committed head is cloned into another world and database, as a
|
||
re-identified clone genesis that names its source cut;
|
||
- outcomes and ancestry are inherited;
|
||
- the source session is read-only, and clone failures are atomic;
|
||
- a full-chain retention audit is added.
|
||
Next: M7.9b, covering the upgrade barrier and old-writer fencing, migration
|
||
failure while serving, and measured recovery and batching latency.
|
||
|
||
M7.9b implemented and locally qualified (2026-09-29), under ADR-0068:
|
||
- build-bound authority, and an upgrade barrier that retires a build and fences
|
||
old writers;
|
||
- a failed migration leaves the previous schema exactly, while writers continue;
|
||
- rule and format changes are refused explicitly;
|
||
- measured recovery (19.6 s against a 60 s target) and batching latency.
|
||
M7 is complete locally. Next: M8.1, the host inventory and budgets.
|
||
|
||
M8.1 complete (2026-09-29): docs/infrastructure/INVENTORY.md records the cluster,
|
||
the separate PostgreSQL VM, the measured workload profile and a per-worker
|
||
`local-path` storage probe. Storage figures are provisional until the planned RAID
|
||
and storage change. Next: M8.2, environment isolation and secrets.
|
||
|
||
M8.2 designed and checked offline (2026-09-29), under ADR-0069:
|
||
- dev, stage and World0 namespaces, each with its own guardrails, identities and
|
||
secret references;
|
||
- a native admission policy that protects World0 from every requester except a
|
||
break-glass group;
|
||
- scoped Argo projects, and a cleanup tool that refuses World0;
|
||
- an offline policy check in CI, and a live isolation check.
|
||
The live checks run once the maintainer applies the platform layer. Next: M8.3,
|
||
durable stores in dev and stage.
|
||
|
||
M8.3 implemented and locally qualified (2026-09-29), under ADR-0070:
|
||
- each environment's database lives on the external PostgreSQL VM;
|
||
- object volumes are node-local and use the Retain class;
|
||
- a free-space reserve with a distinct full-volume refusal;
|
||
- `evo-world-clone check-store` for in-cluster qualification.
|
||
The in-cluster evidence and the backup destination wait on the maintainer
|
||
(docs/BACKLOG.md).
|
||
|
||
M8.3 delivered through Argo CD by the maintainer (2026-09-29): the dev, stage and
|
||
platform applications are synced and connected to PostgreSQL.
|
||
|
||
M8.4 implemented and locally qualified (2026-09-29), under ADR-0071:
|
||
- one `evo-region` host per environment, with the Recreate strategy and the image
|
||
digest as its build identity;
|
||
- an idempotent provisioning hook from the development opening;
|
||
- `region-drill.sh` for rollout and forced-deletion evidence.
|
||
The in-cluster sync and drill wait on the maintainer. No director yet: assignment
|
||
is static and lives in Git.
|
||
|
||
M8.5 implemented and locally qualified (2026-09-30), under ADR-0072:
|
||
- AEvolution-only Prometheus 3.13.3 and Alertmanager 0.34.1, pinned by digest;
|
||
- 16 alert rules, tested by injection with promtool in CI;
|
||
- object volume capacity metrics;
|
||
- the database outbox kept (no broker);
|
||
- bounded logs, and a cardinality and cost report.
|
||
Alert delivery waits on the maintainer's choice of receiver.
|
||
|
||
M8.6 implemented and locally qualified (2026-09-30), under ADR-0073:
|
||
- a drill-only synthetic input driver;
|
||
- `fault-drill.sh`, covering repeated forced kills, a full volume, an empty volume
|
||
and an operator-driven database outage;
|
||
- RTO and zero-lost-acknowledgement checks.
|
||
The in-cluster drill results wait on the maintainer.
|
||
|
||
M8.7 implemented and locally qualified (2026-09-30), under ADR-0074:
|
||
- online, snapshot-consistent world bundles (database dump, immutable objects,
|
||
MANIFEST of versions, builds and heads, checksums);
|
||
- a fail-closed restore that audits every region's full history on independent
|
||
storage, and an isolated rebuild through clones that serves under load;
|
||
- corruption, missing-object, tampered-manifest and non-empty-target refusals;
|
||
- an operator-run in-cluster backup to a directory off the cluster.
|
||
Pending the maintainer's destination: encryption, schedule, retention and WAL
|
||
archiving (docs/BACKLOG.md). In-cluster bundle evidence waits on a run.
|
||
|
||
M8.8 decided (2026-09-30), under ADR-0075: dev/stage objectives ratified from
|
||
measurements (worker loss RPO 0 / RTO <= 60 s; host loss = explicit rewind to the
|
||
last verified bundle); **World0 launch stays blocked** because no independent
|
||
durable failure domain exists, enforced by the deploy policy check; host-loss
|
||
restore in place with barrier fencing of the superseded database rehearsed
|
||
locally; promotion only of stage-pinned digests. **M8-World0 launch not passed**
|
||
(blocked by design). M8-dev/stage is implemented and locally qualified, not yet
|
||
passed: see "M8 gate status" below.
|
||
|
||
M8.9 implemented and locally qualified (2026-09-30), under ADR-0076: accelerated
|
||
clone runs of the current and candidate builds compared state-for-state and
|
||
outcome-for-outcome (`evo-world-clone compare`); failed-migration recovery and the
|
||
version barrier rehearsed with real hosts; `upgrade-barrier.sh` for dev/stage;
|
||
stores/compute node labels with policy-checked placement and `scheduling-check.sh`.
|
||
Rules changes stay refused until a converter ADR. In-cluster barrier and
|
||
additional-node evidence wait on the maintainer.
|
||
|
||
**M8 gate status (2026-09-30, after the M8.1–M8.9 review).** Implementation and
|
||
local qualification are complete; these live gates are still open, so M8-dev/stage
|
||
is **not passed**:
|
||
- M8.6: a valid dev database-outage run, and a re-run of full/empty with the new
|
||
image (positive quarantine evidence, RTO asserted against 60 s);
|
||
- M8.7: an in-cluster `cluster-backup.sh` bundle restore-tested off the host; the
|
||
destination, schedule, retention, encryption and WAL archiving (backlog);
|
||
- M8.5: an alert receiver and kubelet log-rotation check (backlog);
|
||
- M8.9: `upgrade-barrier.sh` on dev and `scheduling-check.sh` with a second labelled
|
||
node;
|
||
- M8.1/M8.3: storage re-measured after the RAID rework.
|
||
M8-World0 launch stays blocked by ADR-0075.
|