Schema v8 binds authority to builds (ADR-0068): acquisition names the host build and only retained, unretired builds may hold a lease; no commit may name a retired build; upgrade_barrier retires a build and fences every holder in one transaction, while build-less pre-v8 hosts keep working until the first barrier. Tests cover a writer surviving a failed and then a real online migration, old-writer fencing on every path, whole-history recovery by the new build, and the M7 qualification fixture (19.6 s SIGKILL-to-ready under the production lease, no lost acknowledgements). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
604 lines
57 KiB
Markdown
604 lines
57 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
|
||
|
||
**Goal:** a native desktop cellular viewer/controller with input, camera, renderer,
|
||
readable organism/environment views and a real development-server connection.
|
||
It is an engineering client, not the M11 playable game or the M13 3D engine.
|
||
|
||
**Entry:** M6 view contracts; M7 durable authority for connection work and M8-dev/stage
|
||
for deployment evidence. No Unreal/Unity, browser delivery, Steam dependency, 3D
|
||
terrain meshing or procedural creature animation is required.
|
||
|
||
| ID / objective | Files/modules | Dependencies | Completion criteria | Tests / evidence | Risk |
|
||
|---|---|---|---|---|---|
|
||
| 9.1 Select scoped client dependencies | docs/adr, dependency manifests, CMake | M6 views, constitution | Evaluate SDL3 and Vulkan/thin alternatives for native 2D support, tooling, portability, maintenance/license/size; pin adopted subset; audio may be explicitly deferred | Minimal window/input/render probes on supported targets, reproducible acquisition and license records | Building a general renderer before validating cellular views |
|
||
| 9.2 Establish platform and render boundary | apps/evo-client, src/client/platform, src/render | 9.1 | Window/event loop, resize/DPI/focus handling, orderly resource ownership; renderer consumes immutable views; headless targets build without client dependencies | Open/close/recreate, minimized window, device/init failure, headless build with client disabled | GPU/window types leak into biological APIs |
|
||
| 9.3 Add camera and input intentions | src/client/input, src/client/camera | 9.2, M6 coordinate contract | Pan/zoom and world-screen mapping; bounded intentions carry sequence/tick; UI focus prevents accidental world input | DPI/resize/zoom round trips, focus loss, key release, invalid ranges | Pixels become authority coordinates or stuck movement |
|
||
| 9.4 Render microscopic environment | src/render/environment, src/client/views | 9.2-9.3, 6.3 | Resource fields and boundaries render from revision-tagged views; missing/stale data has explicit presentation; no unbounded geometry/texture growth | Synthetic known fields, camera seams, stale update and frame/resource profile | Rendering changes resource simulation or hides missing data |
|
||
| 9.5 Render organisms and debug views | src/render/organism, src/client/ui | 9.4, M3 phenotype contracts | Visual parameters derive from available biology; players/NPCs use identical biological rendering; optional ImGui stays engineering UI | Same phenotype renders identically across controller types; death/removal, dense scenes, no player/NPC/level labels | Debug ownership labels become gameplay UI |
|
||
| 9.6 Define a narrow secure dev-session protocol | docs/networking, schemas/view, src/network adapters | 7.8, 9.3, ADR-0017 | Versioned bounded view/intent envelope, session identity, epoch and commit watermark; choose maintained transport/crypto for this scope; test identity is explicitly dev-only | Codec fuzz/bounds, unsupported versions, auth/replay/rate rejection, no native-struct trust | A temporary unauthenticated protocol escapes into production |
|
||
| 9.7 Connect to one authoritative dev region | src/client/session, src/server/session adapter | 9.6, M8-dev/stage | Real desktop-to-server connection, snapshot display and minimal admitted intent; reconnect requests fresh baseline; final outcomes reflect durable server ACK | Disconnect/reconnect, stale epoch, server pod restart, rejected intention and duplicate session tests | Client state or reconnect becomes authority |
|
||
| 9.8 Validate presentation and package the client | tools/client packaging, tests/client, docs/engineering | 9.1-9.7 | Reproducible native artifact, bounded snapshot/render queues, frame/memory report and documented manual visual checks | Install/run on supported dev platforms; long session, resolution/DPI matrix, headless regression suite | Declaring FUN or multiplayer scalability from a viewer |
|
||
|
||
**Exit:** a packaged native client opens, renders an authoritative cellular development
|
||
scene, submits a bounded test intention and recovers its view after the server restarts.
|
||
The prototype session respects server authority and ownership epochs. M10 owns the
|
||
full real-time datagram/reliability selection, prediction, reconciliation, interpolation,
|
||
interest management and 20+ client acceptance. M9 may use a scoped secure reliable
|
||
channel if its ADR documents the limits and preserves transport-neutral semantics.
|
||
No renderer is needed for server tests; no client may decide energy, mutation,
|
||
reproduction or death. Steam and final player UI remain later product work.
|
||
|
||
## Later gates
|
||
|
||
| Milestone | Deliverable and acceptance gate |
|
||
|---|---|
|
||
| M10 Realtime multiplayer | Authenticated intentions, reliable outcomes, prediction/reconciliation/interpolation and interest; 20+ bot clients then measured scaling/fault tests |
|
||
| M11 Cellular gameplay | Movement, feeding, predation, mutation selection, reproduction, descendants, total restart; playtest FUN and repeated-life variety |
|
||
| M12 Persistent ecology | Days-long unattended worlds, genealogy, extinction evidence, player absence and diverse strategies; analyze collapse/runaway lineages |
|
||
| M13 3D R&D | Isolated smooth meshing, body graph, procedural skin/physics/locomotion comparisons with measured exit criteria |
|
||
| M14 Multicellular transition | Ratified biological transition and first cell-to-multicellular-to-3D slice with conserved ecological coupling |
|
||
|
||
No date or production capacity is promised without staffing and benchmark data.
|
||
Every release records simulation/world/network versions; biological upgrades use
|
||
production snapshot -> clone -> migrate -> accelerated comparison -> approval.
|
||
|
||
M4.6 completed as measurement tooling and a policy review on 2026-09-26; see
|
||
[aggregate budget report](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.
|