Files
aevolution/docs/ROADMAP.md
T
dingoandClaude Opus 5 1a59b63c7a Refuse the whole conversion rather than drop the inconvenient member
M4.2 moves individuals into the M4.1 record and does only that: no advance, no
materialization back, no transfer between habitats, no persistence.

Collapse is two phases over one sample. plan_collapse reads the members once and
returns an immutable plan that already carries a validated cohort; commit applies
exactly that plan and derives nothing, so replaying a committed sample cannot
resample, and a record that would not validate fails during planning rather than
after the ledger has moved.

A controlled, suspended, dead or unsettled member refuses the whole plan instead
of being skipped. Filtering would let a caller obtain a plan by omitting whoever
was inconvenient, and the result would be indistinguishable from an honest
conversion, which is the adversarial selection the model forbids. Ages are
carried into declared classes and a member fitting none refuses the plan, so
nobody is quietly moved or dropped for having nowhere to go. Reserves are summed
per class and never redistributed, so the distribution M4.1 exists to keep
survives the move.

Conservation runs through the ledger rather than beside it: one atomic
transaction, one leg per member, each moving that member's entire reserve, so the
conserved total is unchanged by construction. Dual representation is closed from
both ends. A member must be emptied exactly, and a reservoir holding anything
other than what was sampled makes the plan stale rather than partly applicable.
The destination is proved available before anything moves, so no rejection can
strand biomass in a reservoir nothing owns. Reversing that order is detected by
the tests, which is the point: the ordering prevents the failure rather than a
comment claiming it cannot happen.

Two gaps are stated rather than implied covered. This cannot tell whether the
members offered were all there were, so completeness is the caller's obligation.
And emptying a reservoir is not withdrawing the right to use it, because the
ledger has no removal.

ReservoirId and Transfer gain the defaulted comparisons every other value type
here already has, so a plan's legs can be compared. Additive, and ADR-0037 says
so rather than claiming no M1 change.

All ten guards were confirmed load-bearing by removing each and rerunning. One of
my own expectations was wrong rather than the code: a replayed commit reported
stale_plan where I expected destination_occupied. Both are pure checks made
before anything moves, so only the diagnosis differed; the destination check runs
first now, because "this already happened" says more about a replay.

Release 35/35, analysis, ASan 35/35 and clang-format all ran and passed here.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-24 09:45:09 -04:00

173 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.
M3.6 closes M3 by making the pieces meet (ADR-0035): `strategy_for` turns a genome
into the `StrategyConfig` the M2.6 driver already takes, founders are pre-diverged
variants of one ancestor admitted to the archive, and `evo-sim --ensemble` runs
them over a resource and temperature grid with every cell's seeds split in half and
reported separately. The driver is untouched, so the M2.6 fingerprint still holds.
Two findings are recorded rather than smoothed over: resource level never reaches
strategy derivation, because a mature founder has an empty construction transition,
and the resource axis is not monotonic, because feeding caps community income at
one producer bite per tick. Nothing mutates during an episode, so NPC mutation
stays open.
## M3 — Genome v0.1
| ID / objective | Files/modules | Dependencies | Completion criteria | Tests / evidence | Risk |
|---|---|---|---|---|---|
| 3.1 Immutable genome schema and ancestry | biology/genome, schemas, docs/biology | M2, genome/heredity decisions | Versioned developmental capability data; immutable parent references | Canonical encoding, invalid graph and range tests | Literal-DNA scope or class tree |
| 3.2 Development pipeline | biology/development, phenotype | 3.1 | Genome + environment develops explicit physical parameters | Same input yields same phenotype; material/capability prerequisites | Genome confused with runtime damage |
| 3.3 Derive energetic components | metabolism/movement/membrane adapters | 3.2, M2 | Size/membrane/movement tradeoffs affect several budgets | Thicker structure costs matter and maintenance | RPG modifiers reintroduced |
| 3.4 Seeded mutation candidates | biology/mutation | 3.1–3.3, design decision | Bounded reproducible candidates conditioned by legitimate context | Prerequisite, cost, invalid-choice, fixed-seed tests | Hidden deterministic best build or biased adaptation |
| 3.5 Heredity/divergence history | reproduction/genome/history contract | 3.4, NPC-mutation decision | Reproduction persists parent/child links; genome identity survives death | Branching lineage fixtures and terminal organism tests | Deleting extinct genomes |
| 3.6 Genome ecology ensembles | tests/ecosystem, tools/reports | 3.5 | Compare strategies under resource/temperature gradients | Statistical distributions, conservation, diversity report | Tuning one seed overfits |
## M4 — Population abstraction
| ID / objective | Files/modules | Dependencies | Completion criteria | Tests / evidence | Risk |
|---|---|---|---|---|---|
| 4.1 Define cohort state and ownership | biology/ecology, schemas/population | M3, ECOLOGY_MODEL | Genome/lineage, counts, age, reserves, residuals and ownership explicit | Invalid cohort/negative reserve rejection | Population averages hide viable outliers |
| 4.2 Collapse active individuals | ecology/conversion | 4.1 | Transfer IDs/reserves to one aggregate representation atomically | Exact ledger conservation and crash-before/after commit tests | Dual representation |
| 4.3 Advance local cohorts | ecology/population | 4.2 | Conservative birth/death/predation/migration accounting per interval | Nonnegative counts, energy bounds, seeded ensembles | Numerical instability / false extinctions |
| 4.4 Materialize representatives | ecology/materialization | 4.3 | Withdraw exact shares and residuals; preserve genome identity | Repeated round trips, scarcity and adversarial oscillation | Re-materialization becomes free healing |
| 4.5 Validate resolution equivalence | tests/ecosystem, benchmarks | 4.4 | 100 individuals → aggregate → 10,000 ticks → representatives | Conservation exactly; ecological distributions within documented tolerance | Claiming identical trajectories at different resolution |
| 4.6 Budget and review aggregate model | docs/adr, simulation metrics | 4.5 | CPU/memory and error bounds justify tier policy | Active/aggregate benchmark and ecological sensitivity report | Premature world-scale claims |
## Later gates
| Milestone | Deliverable and acceptance gate |
|---|---|
| M5 Basic voxel world | Sparse small-volume generation + modifications + restore; deterministic base and bounded delta tests; mesher remains an experiment |
| M6 Environmental resources | Light/moisture/limited nutrients connected through conserved transfers; no full chemistry simulation |
| M7 Persistent region | Unique fenced authority, durable outcomes, snapshots/replay, health/metrics, process-kill recovery; migrations before real data |
| M8 Kubernetes World0 | Inventory actual host, provision dev/stage/world0 with guarded promotion and backups; delete worker pod and restore automatically; restore on independent storage verified |
| M9 Custom 2D client | ADRs for SDL3, renderer and audio; usable window/input/camera, biological presentation, no NPC labels |
| M10 Realtime multiplayer | Authenticated intentions, reliable outcomes, prediction/reconciliation/interpolation and interest; 20+ bot clients then measured scaling/fault tests |
| M11 Cellular gameplay | Movement, feeding, predation, mutation, reproduction, descendants, total restart; playtest FUN and repeated-life variety |
| M12 Persistent ecology | Days-long unattended worlds, genealogy, extinction evidence, player absence and diverse strategies; analyze collapse/runaway lineages |
| M13 3D R&D | Isolated smooth meshing, body graph, procedural skin/physics/locomotion comparisons with measured exit criteria |
| M14 Multicellular transition | Ratified biological transition and first cell→multicellular→3D slice with conserved ecological coupling |
No date or production capacity is promised without staffing and benchmark data.
Every release records simulation/world/network versions; biological upgrades use
production snapshot → clone → migrate → accelerated comparison → approval.