Define M5.1 local voxel contract and expand M5-M9 gates

This commit is contained in:
dingo
2026-09-26 10:06:22 -04:00
parent c237e4da97
commit 69bbf364a9
14 changed files with 778 additions and 12 deletions
+203 -9
View File
@@ -188,25 +188,219 @@ stays open.
| 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.
Next is 5.2: benchmark compact representations and candidate edge lengths.
**Decisions still open:** final spherical layout, region dimensions, adaptive LOD,
field quantization beyond the initial experiment, hydrology and surface extraction.
No Marching Cubes/Surface Nets/Dual Contouring selection is implied.
## M6 - Environmental resources
**Goal:** organisms and a small voxel environment exchange finite resources through
conserved accounting. Start with light/energy, water inventory with derived moisture,
one or two named nutrients and organic matter. Full chemistry, atmospheric circulation,
CFD, roots/canopies, erosion and 3D creature physics are later work.
**Entry:** M5 local world gate and ENERGY_MODEL reviewed. Resolve how microscopic 2D
habitat area and effective depth map to environmental volume before connecting stores.
| ID / objective | Files/modules | Dependencies | Completion criteria | Tests / evidence | Risk |
|---|---|---|---|---|---|
| 6.1 Ratify resource and coupling units | docs/biology/ENERGY_MODEL.md, docs/world, docs/adr, include/evo/world | M5 | Name extensive inventories, derived concentrations/moisture, energy source/sink terms, rounding residuals and valid ranges; specify 2D-to-3D volume mapping | Dimensional examples, closed/open system equations and invalid conversions | Area or concentration silently creates mass |
| 6.2 Store optional environmental fields | src/world/fields, schemas/world-fields | 6.1, 5.2, 5.6 | Material defaults plus sparse water/nutrient/organic pages; material ID alone grants no extractable supply; snapshot/version fields | Uniform vs varying footprint, finite exhaustion, round trip, old-version rejection | Dozens of floats per voxel or duplicated baseline resources |
| 6.3 Publish read-only environment views | include/evo/world/environment, src/world/resources | 6.2 | Footprint query returns values with units, resolution, tick and chunk revisions; missing data is explicit, not zero/unlimited | Seams, unavailable chunks, stale revisions, deterministic query order | Stale reads authorize consumption |
| 6.4 Commit environmental transfers | src/world/transfers, src/accounting adapters | 6.1-6.3 | Plan against immutable view; single-owner commit atomically validates organism and environment debits/credits; command IDs and changed-payload rejection | Two organisms contend for last nutrient, duplicate transfer, rollback and source/destination ownership | Resource spendable in both voxel and organism store |
| 6.5 Couple one producer and consumer fixture | src/processes adapters, tests/ecosystem | 6.4, M2-M3 contracts | Defined source flux funds capture; growth consumes water/nutrients; feeding transfers existing biomass; no implicit maintenance or reproduction rule changes | Source-off/starvation, nutrient limitation, temperature/resource boundaries, seeded replay | Fixture constants become game rules |
| 6.6 Return dead biomass to environment | src/processes/decomposition, src/world/transfers | 6.5 | Terminal organisms cannot act; bounded decay returns exact matter and accounted energy; residuals survive ticks | Death during pending consumption, duplicate decay, partial decay and nutrient-fed regrowth | Corpse disappears or decomposition runs twice |
| 6.7 Schedule local environment intervals | src/simulation scheduling adapters, src/world/resources | 6.4-6.6 | Explicit fixed intervals and phase order; read/write revisions prevent double integration; bounded catch-up; no implicit cross-region exchange | Interval split/merge where mathematically valid, pause/resume, maximum backlog, stale boundary refusal | Different update rates manufacture resources |
| 6.8 Validate integrated environmental slice | tests/ecosystem, tests/integration, docs/engineering | 6.2-6.7 | Environment -> producer -> consumer -> death -> nutrients -> growth, with integrated snapshot/restore and explicit version bundle | Multi-seed long runs, independent per-channel conservation including reservoirs/residuals, restore/replay hashes and cost report | Conservation passes while ecology collapses |
**Exit:** one bounded microscopic habitat uses environmental inventories without
cross-scale literal physics or resource duplication. Read views are suitable for a
later client, but no rendering is required. Ecological results and failure regimes
are reported separately from arithmetic. Unsupported distributed transfers remain
rejected rather than simulated with untracked remote credits.
## M7 - Persistent region server
**Goal:** a disposable authoritative headless process can recover a bounded region
without losing acknowledged irreversible decisions. PostgreSQL is the preferred
authority; object payloads sit behind a storage adapter. The library does not acquire
SQL, network, Steam or Kubernetes dependencies.
**Entry:** M6 integrated state is serializable; inventory actual state still missing
from snapshots, including lineage archive, genomes, RNG, residuals, pending commands
and versions. No existing particle or genome codec is assumed to cover a full region.
Follow PERSISTENCE_ARCHITECTURE and ADRs 0013/0016; the table adopts no client library.
| ID / objective | Files/modules | Dependencies | Completion criteria | Tests / evidence | Risk |
|---|---|---|---|---|---|
| 7.1 Define region durability contract | docs/adr, schemas/region, include/evo/persistence | M6 | Specify region identity, state closure, simulation/commit watermarks, batch limits, irreversible ACK semantics and recovery format; choose replay or explicit full checkpoint batches | State inventory audit and crash-point matrix; exact replay requirements identified | Semantic events omit movement/randomness needed for recovery |
| 7.2 Adopt storage dependencies and migrations | src/persistence/database, migrations, dependency manifests | 7.1, ADR-0013 | Evaluate/pin PostgreSQL client and server pair; parameterized SQL, typed adapter errors, I/O ownership and bounded connection/deadline rules; only needed tables | Real PostgreSQL clean migration, supported upgrade path, rollback-on-error and permission checks | Dependency exception/transaction behavior leaks into simulation |
| 7.3 Implement fenced region ownership | src/server/world_director, src/persistence/leases | 7.2 | Director suggests assignment; DB serializes holder/epoch/expiry; commits lock/check lease and predecessor; worker role cannot bypass guard | Two contenders, expired renewal, paused stale writer, partition and database-time tests | Lease field exists but writes bypass its fence |
| 7.4 Encode and publish committed checkpoints | src/persistence/snapshots, object adapter, schemas/region | 7.1-7.3 | Coherent state includes complete version/RNG/history references; immutable payload verified before fenced manifest publication; unreferenced uploads are orphans | Missing/corrupt objects, upload/manifest failure, size caps, retained generator/binary restore | Snapshot mixes speculative and committed state |
| 7.5 Commit replay batches and permanent outcomes | src/persistence/events, src/server/region_host | 7.3-7.4 | Contiguous replay/checkpoint chain, canonical command digests, idempotent decisions and transactional outbox; batch DB writes; irreversible outcomes final only after durable confirmation | Commit-before-ACK disconnect, changed retry payload, gap/reorder, partial batch and duplicate births/deaths | Ambiguous commit treated as rollback |
| 7.6 Host bounded authoritative ticks | apps/evo-server, src/server/region_host | 7.1, 7.5 | One simulation owner with bounded I/O queues; simulated vs committed tick exposed; pause region at pending irreversible outcome; drain/shutdown and fail-closed readiness | Store outage, queue saturation, renewal failure, SIGTERM/forced kill, tick-debt measurement | Dependent actions use uncommitted reproduction/death |
| 7.7 Recover and verify before readiness | src/persistence/recovery, tests/integration | 7.4-7.6 | Load verified committed checkpoint, replay complete tail, verify hash/inventories/history, acquire valid current authority before serving | Kill at every publication/ACK boundary; corrupt/missing tail quarantines region; no empty fallback world | Silent world reset or resumed stale owner |
| 7.8 Add operations endpoints and dev image | apps/evo-server, core telemetry adapters, deploy/docker | 7.6-7.7 | Separate liveness/readiness; metrics for debt, commit lag, lease safety, checkpoint age and queue bounds; non-root image with no embedded secrets | Real process probes, metric-label bounds, unavailable DB readiness, image smoke test | Healthy process mistaken for valid authority |
| 7.9 Clone, migrate and qualify durability | tools/world-clone, migrations, tests/recovery, docs/engineering | 7.7-7.8 | Consistent clone into isolated world identity; explicit rule/format rejection/migration; durable-history retention; measured recovery and batching latency | Clone cannot publish into source; baseline vs restored trajectory; migration failure and old-writer fencing | Clone shares production credentials or rules change on restore |
**Exit:** force-kill a real worker and recover through real storage with identical
committed state, retained ancestry and unique durable authority. Zero lost acknowledged
decisions under worker loss is required; the proposed 60-second recovery target is
measured under a declared fixture, not a universal promise. Database failure withholds
final outcomes and pauses before bounded pending/lease budgets expire.
Cross-region seamless handoff, distributed population transfer and public realtime
multiplayer are not M7 acceptance claims. M7 lays their IDs/epochs/ownership contracts.
A local recovery proof does not establish host-loss durability; that is the M8 launch gate.
## M8 - Kubernetes dev/stage recovery and guarded World0
**Goal:** run the M7 server through the existing GitOps pipeline, then qualify durable
World0 operation. Separate **M8-dev/stage passed** from **M8-World0 launch passed**.
World0 is persistent state, never a disposable smoke-test namespace.
**Entry:** M7 recovery evidence and deployable digest. Reuse existing Gitea/Harbor/Argo
configuration; inspect the actual cluster before selecting storage or replica counts.
OPERATIONS and INFRASTRUCTURE_ARCHITECTURE govern protection and recovery semantics.
| ID / objective | Files/modules | Dependencies | Completion criteria | Tests / evidence | Risk |
|---|---|---|---|---|---|
| 8.1 Inventory host and establish budgets | docs/infrastructure/inventory, deploy environment values | M7 image; read-only cluster access | Record R730xd CPU/RAM/storage, CNI/CSI, reclaim policies, failure domains, DNS/TLS and available capacity; reserve OS/stores/observability/recovery headroom | Measured disk latency/capacity and workload tick/resource profile | Treating 128GB as simulation-only memory |
| 8.2 Isolate environments and secrets | deploy/kubernetes overlays, deploy/argocd | 8.1 | Dev/stage/world0 identities, accounts, quotas, secret references and deny-by-default flows; no secrets in Git; World0 pruning/deletion protections designed | RBAC negative tests, cross-environment denial, cleanup rejects World0; parent-app deletion protection | One permissive app or credential can destroy all worlds |
| 8.3 Provision durable stores in dev/stage | deploy storage manifests, migrations jobs, docs/runbooks | 8.1-8.2, 7.2 | Adopt supported PostgreSQL and maintained object-store deployment with pinned versions; verify PV retention and backup destination | Pod restart, missing volume refusal, object semantics/digests, credentials rotation, full disk | Local PV binds failover to lost node |
| 8.4 Deploy director and region host | deploy/kubernetes, deploy/argocd, .gitea/workflows | 8.3, 7.8 | Immutable image digest, measured resources, probes, security context and drain budget; actual Argo sync/workload evidence | Region ready only after lease/recovery; graceful rollout and forced worker deletion | Successful rollout hides failed region recovery |
| 8.5 Add observability and bounded background delivery | deploy monitoring, dashboards, optional bus ADR | 8.4 | Tick/lease/commit/storage/backup alerts and bounded logs; evaluate DB outbox before optional JetStream; no mandatory Redis/Kafka | Alert injection, backlog/retry/idempotency tests if bus adopted, telemetry cardinality/cost report | Broker redelivery changes authority or logs fill disk |
| 8.6 Exercise recovery under faults | deploy/workflows, tests/operations, runbooks | 8.4-8.5 | Dev/stage pod-kill restores committed world automatically; stale owner cannot resume; unavailable state never initializes fresh | Repeated pod kill, stale process, DB/object outage, partition, disk full; record RTO and zero lost ACKs | Happy-path pod restart mistaken for disaster recovery |
| 8.7 Verify off-host backup and clone restore | tools/backup, deploy/workflows, docs/infrastructure | 8.3, 7.9 | Coordinated manifest covers DB/WAL, objects, versions, binaries and in-flight state; restore on independent storage; retention/GC respects clone/backup pins | Rebuild isolated world from backup, corruption and missing-object failure, credential/key recovery | Backup exists but cannot reconstruct causal state |
| 8.8 Qualify World0 acknowledgment and promotion | docs/adr, deploy/world0 protections, operations runbook | 8.6-8.7 | Ratify measured RPO/RTO and host-loss causal durability before irreversible ACK; independent durable chain or keep launch blocked; explicit promotion of reviewed digest/state | Host-loss restore preserves deaths, offspring, inventory and ancestry; fence old environment; promotion audit | Old backup resurrects dead organisms or duplicates resources |
| 8.9 Prove upgrade and growth operations | deploy/workflows, node scheduling values, docs/engineering | 8.6-8.8 | Clone/migrate/accelerate/compare before world-wide rules change; label/affinity plan works on one node and admits added compute nodes | Dev/stage version-barrier rehearsal, failed migration recovery, additional-node scheduling where hardware exists | Mixed physical laws or assuming added CPU makes storage portable |
**Dev/stage exit:** a pinned M7 workload is observed running; pod termination yields
automatic fenced recovery with measured costs and tested alerts. **World0 launch exit:**
all independent recovery/acknowledgment, data-protection and explicit promotion gates
pass. If no independent durable failure domain exists, dev/stage can proceed while
World0 launch stays blocked; changing RPO silently is not a workaround. Do fault and
prune drills in isolated clones, never by deleting World0's namespace or data.
Target recovery objectives in OPERATIONS remain proposals until measured and
accepted. No multi-node HA claim is made for the single physical host. Optional
JetStream is adopted only for a demonstrated delivery workload, not as lease authority.
## M9 - Custom 2D engineering client
**Goal:** a native desktop cellular viewer/controller with input, camera, renderer,
readable organism/environment views and a real development-server connection.
It is an engineering client, not the M11 playable game or the M13 3D engine.
**Entry:** M6 view contracts; M7 durable authority for connection work and M8-dev/stage
for deployment evidence. No Unreal/Unity, browser delivery, Steam dependency, 3D
terrain meshing or procedural creature animation is required.
| ID / objective | Files/modules | Dependencies | Completion criteria | Tests / evidence | Risk |
|---|---|---|---|---|---|
| 9.1 Select scoped client dependencies | docs/adr, dependency manifests, CMake | M6 views, constitution | Evaluate SDL3 and Vulkan/thin alternatives for native 2D support, tooling, portability, maintenance/license/size; pin adopted subset; audio may be explicitly deferred | Minimal window/input/render probes on supported targets, reproducible acquisition and license records | Building a general renderer before validating cellular views |
| 9.2 Establish platform and render boundary | apps/evo-client, src/client/platform, src/render | 9.1 | Window/event loop, resize/DPI/focus handling, orderly resource ownership; renderer consumes immutable views; headless targets build without client dependencies | Open/close/recreate, minimized window, device/init failure, headless build with client disabled | GPU/window types leak into biological APIs |
| 9.3 Add camera and input intentions | src/client/input, src/client/camera | 9.2, M6 coordinate contract | Pan/zoom and world-screen mapping; bounded intentions carry sequence/tick; UI focus prevents accidental world input | DPI/resize/zoom round trips, focus loss, key release, invalid ranges | Pixels become authority coordinates or stuck movement |
| 9.4 Render microscopic environment | src/render/environment, src/client/views | 9.2-9.3, 6.3 | Resource fields and boundaries render from revision-tagged views; missing/stale data has explicit presentation; no unbounded geometry/texture growth | Synthetic known fields, camera seams, stale update and frame/resource profile | Rendering changes resource simulation or hides missing data |
| 9.5 Render organisms and debug views | src/render/organism, src/client/ui | 9.4, M3 phenotype contracts | Visual parameters derive from available biology; players/NPCs use identical biological rendering; optional ImGui stays engineering UI | Same phenotype renders identically across controller types; death/removal, dense scenes, no player/NPC/level labels | Debug ownership labels become gameplay UI |
| 9.6 Define a narrow secure dev-session protocol | docs/networking, schemas/view, src/network adapters | 7.8, 9.3, ADR-0017 | Versioned bounded view/intent envelope, session identity, epoch and commit watermark; choose maintained transport/crypto for this scope; test identity is explicitly dev-only | Codec fuzz/bounds, unsupported versions, auth/replay/rate rejection, no native-struct trust | A temporary unauthenticated protocol escapes into production |
| 9.7 Connect to one authoritative dev region | src/client/session, src/server/session adapter | 9.6, M8-dev/stage | Real desktop-to-server connection, snapshot display and minimal admitted intent; reconnect requests fresh baseline; final outcomes reflect durable server ACK | Disconnect/reconnect, stale epoch, server pod restart, rejected intention and duplicate session tests | Client state or reconnect becomes authority |
| 9.8 Validate presentation and package the client | tools/client packaging, tests/client, docs/engineering | 9.1-9.7 | Reproducible native artifact, bounded snapshot/render queues, frame/memory report and documented manual visual checks | Install/run on supported dev platforms; long session, resolution/DPI matrix, headless regression suite | Declaring FUN or multiplayer scalability from a viewer |
**Exit:** a packaged native client opens, renders an authoritative cellular development
scene, submits a bounded test intention and recovers its view after the server restarts.
The prototype session respects server authority and ownership epochs. M10 owns the
full real-time datagram/reliability selection, prediction, reconciliation, interpolation,
interest management and 20+ client acceptance. M9 may use a scoped secure reliable
channel if its ADR documents the limits and preserves transport-neutral semantics.
No renderer is needed for server tests; no client may decide energy, mutation,
reproduction or death. Steam and final player UI remain later product work.
## Later gates
| Milestone | Deliverable and acceptance gate |
|---|---|
| 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 |
| 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→multicellular→3D slice with conserved ecological coupling |
| 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.
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
+29 -2
View File
@@ -7,7 +7,7 @@ persistent simulation server. The founding vision remains unchanged.
## Completed implementation
- Vision, architectural pillars, risks, open-question register, architecture
diagrams, biological contracts, engineering constitution and 41 ADRs.
diagrams, biological contracts, engineering constitution and 42 ADRs.
Proposed/deferred choices remain distinct from accepted proof decisions.
- M0–M4 task breakdowns with dependencies, acceptance evidence and risks,
plus M5–M14 gates in [ROADMAP.md](ROADMAP.md).
@@ -61,7 +61,7 @@ for the bounded proof; the general production ECS remains a later measured choic
| Priority | Work | Completion evidence |
|---|---|---|
| 1 | M5 small sparse voxel prototype | Deterministic generation, modification, snapshot and restore; select scoped storage contract first |
| 1 | M5.2 compare compact chunk layouts | Benchmark uniform/palette and optional varying pages across the explicit edge candidates; select storage in a scoped ADR |
| Research | Improve aggregate fidelity and measure Linux/target-host costs | M4.6 found no qualifying width; see the aggregate budget report |
| 2 | Revisit the ADR-0031/0032 reproduction cost model | Reproduction is affordable only at the genome schema's floor; decide whether that is intended before M4 builds cohorts on it |
| Delivery gate | Add/update the dev workload when a deployable increment needs it; Argo is ready | Observe Job/pod completion separately from image publication; no World0 changes |
@@ -519,3 +519,30 @@ widths passes the proposed fidelity gate across supplies 240/300/360; automatic
selection remains disabled. The next implementation milestone is M5's sparse voxel
prototype; aggregate-model improvement and Linux/target-host measurement remain
prerequisites for a production tier policy. See VALIDATION.md for checks actually run.
## M5-M9 planning expansion - 2026-09-26
[ROADMAP.md](ROADMAP.md) now breaks M5-M9 into 42 reviewable tasks, each with
module boundaries, dependencies, completion criteria, tests and risks. These are
planned gates, not implementation or deployment claims. M8 dev/stage recovery is
separate from World0 launch; M9 client integration can use dev/stage without
premature World0 promotion. M4.6's failed fidelity gate remains explicit.
That expansion identified 5.1 as the next task; it is now implemented as recorded below. No library, service, cluster or dependency changed in this update.
## M5.1 - bounded local voxel contract (2026-09-26)
Implemented dependency-free `evo::world` coordinate and cell-sample utilities,
[ADR-0042](adr/0042-local-voxel-contract.md), and
[LOCAL_VOXEL_CONTRACT.md](world/LOCAL_VOXEL_CONTRACT.md). Signed floor mapping handles
negative chunk seams; all public operations reject invalid bounds before arithmetic.
The experiment uses a 1m cell pitch and explicit edge candidates 8/16/32/64; it
selects no storage layout, renderer, spherical topology or production world extent.
Logical fill describes volume fraction, not surface shape or consumable inventory.
Tests independently enumerate chunk intervals, exhaust 299,520 local ordinals, check
metric/domain corners and hostile signed/unsigned extrema, and validate fill/material
consistency. Existing simulation goldens/formats are unchanged. No world data or
service is deployed. Next: M5.2's measured layout/edge comparison; actual chunk
allocation and generator work follow its decision. See VALIDATION.md for checks.
+70
View File
@@ -0,0 +1,70 @@
# ADR-0042: Bounded local voxel addresses and logical cells
## Status
Accepted for M5.1 only. No chunk storage, generator, persistence, mesher, spherical
planet mapping or world-size choice is adopted. ADR-0019 remains proposed for those
choices. Existing particle coordinates and snapshot formats are unchanged.
## Context
M5.2 must compare layouts against a stable logical domain. C++ integer division
truncates toward zero, which assigns negative cells to the wrong chunk unless the
mapping explicitly uses floor division. Unbounded signed arithmetic also risks
undefined behavior before an invalid address can be rejected.
## Decision
Use a right-handed local Cartesian frame: +Z up and X cross Y = Z. Signed voxel
coordinates identify lower corners of half-open cells. All axes are in
[-1,048,576, 1,048,576); one cell spans 1,000 millimetres for this experiment. The
address envelope is an arithmetic guard, not allocated space or a planet extent.
The initial storage experiment should touch roughly 100 cells per axis.
Chunk edge is explicit, with candidates 8, 16, 32 and 64 cells. No default or
preferred candidate is selected before M5.2 measures them. All divide the domain
exactly. Chunk coordinates are floor(voxel/edge), local offsets are nonnegative
remainders. Join validates edge, chunk and local bounds before multiplication.
Logical ordinal order is X-fastest, then Y, then Z. It is an enumeration convention,
not a mandated physical layout. Mapping functions allocate nothing, perform no I/O,
and use checked integer bounds with typed recoverable errors.
A logical cell has a 16-bit material key and unsigned fill numerator over 65,535.
Material key zero means void and must have zero fill; a nonzero key requires positive
fill. The containing material table is versioned later; this layer validates only
structural consistency, not material existence. Fill denotes occupied volume fraction,
not a signed distance, density, chemical inventory, collision shape or mesh sample.
Sub-cell placement is unknown. A change in fill does not itself authorize matter
creation/destruction; edits must supply material accounting in M5.5/M6.
The coordinate contract is local version 1. A future world key must include world
and frame identity and all layout/generator/material versions. Changing edge or
resolution is an explicit repartition/migration, never reinterpretation of stored
chunk keys. Region ownership and ecological cell boundaries are separate mappings.
## Alternatives Considered
Truncating division breaks negative seams. Unsigned-only positions hide origin
crossings. Unbounded 64-bit addresses invite accidental overflow and imply unsupported
scope. Fixing edge 32 now would pre-empt M5.2's comparison. Signed distance fields
would bias future meshers; material-only blocks cannot express partial occupied
volume. Full chemistry or a generic dimensional algebra is outside this increment.
## Benefits
Negative boundaries and exact round trips are testable independently of storage.
Extreme input is rejected before arithmetic. Logical occupancy does not select a
renderer or a planetary topology; sparse layouts can share the same fixtures.
## Costs
Explicit edge arguments and validation cost a few integer operations. Full signed
input types carry values outside the valid domain. The bounded domain, candidate
edges and 1m pitch are experiments and need version review before extension.
## Risks
Fill alone cannot reconstruct smooth geometry or conserve constituent mass. Material
keys without their future table cannot be interpreted. Domain size must not be
mistaken for supported memory or production scale. Raw logical structs are not a
wire format and may not be serialized by copying native bytes.
## Consequences
Expose a dependency-free evo::world target. Test independent negative-floor oracles,
axis independence, signed extrema, bounds, all local ordinal positions, metric
corners, invalid edges and cell consistency in Release and sanitizers. No new
third-party dependency or existing simulation golden changes. M5.2 selects actual
storage and chunk dimensions through measured alternatives.
+2
View File
@@ -41,3 +41,5 @@ benchmarked. Primary sources were reviewed during the initial September 2026
design. No unadopted candidate is a link dependency of the proof.
- [ADR-0041: Aggregate cost and fidelity budget](0041-aggregate-budget.md) - M4.6 measurement only.
- [ADR-0042: Local voxel contract](0042-local-voxel-contract.md) - accepted for M5.1; layout and planet mapping deferred.
+1 -1
View File
@@ -23,7 +23,7 @@ person. ADR indexes distinguish scoped proof choices from production proposals.
| 15 | Multicellular transition | Physiological and ecological criteria unresolved | Design/biology; M14 |
| 16 | Population abstraction | Conservative cohort ledger + distributions, ensemble validation | Ecology; M4 |
| 17 | Region dimensions | Benchmark against interest, entities and migration overhead | Engine/platform; M7 |
| 18 | Planet coordinates | Hierarchical global address + local coordinates proposal | World; M5/M13 |
| 18 | Planet coordinates | M5.1 bounded local integer contract accepted (ADR-0042); global hierarchy remains proposed | World; M5/M13 |
| 19 | Spherical voxels | Prototype cubed sphere versus alternatives; no fixed topology yet | World; M13 |
| 20 | Voxel LOD | Sparse procedural base, aggregate fields, active chunks | World; M5/M13 |
| 21 | Surface meshing | Marching Cubes / Surface Nets / Dual Contouring comparison | Render/world; M13 |
+11
View File
@@ -103,3 +103,14 @@ duplicate edit idempotency; crash at every compaction boundary; oscillating LOD
without resource gain; stale halo invalidation; stalled transfer escrow; corrupt
objects/full disk rejection. No planet topology or smooth mesher is accepted
until its comparison demonstrates precision, seam correctness and bounded cost.
## Implemented M5.1 boundary
[ADR-0042](../adr/0042-local-voxel-contract.md) and the
[local voxel contract](../world/LOCAL_VOXEL_CONTRACT.md) implement pure signed
address mapping, logical ordinal enumeration, metric corners and cell-fill
validation in `evo::world`. The 1m pitch and bounded local domain are experiments;
8/16/32/64-cell chunk edges remain comparison candidates, not a selected layout.
No data allocation, terrain generation, material table, mass transfer, persistence,
meshing or planet mapping is implemented by this contract. M5.2 measures storage.
+27
View File
@@ -1398,3 +1398,30 @@ version changes. Existing contested-parent and round-trip controls remain active
The final exception-handler-only adjustment was compiled in analysis; Release and
ASan benchmark targets were then rebuilt and their resolution tests rerun. No
performance or model algorithm changed after the archived timing run.
## M5.1 local voxel contract - 2026-09-26
Added ADR-0042, the local voxel contract and dependency-free `evo::world`. No
existing simulation golden, codec or runtime dependency changed. The earlier
uncommitted M5-M9 roadmap expansion is preserved in the working tree.
Executed on Windows x64 / MSVC 19.44 with the repository helper:
- `tools/windows-check.ps1 -Preset release -Action check`: configure/build,
warnings-as-errors and 40/40 CTest passed.
- `tools/windows-check.ps1 -Preset analysis -Action check`: clang-tidy 19 build
and 40/40 CTest passed.
- `tools/windows-check.ps1 -Preset asan -Action check`: AddressSanitizer build
and 40/40 CTest passed. Native Windows ASan is not UBSan coverage.
- `tools/windows-check.ps1 -Preset release -Action format`: passed.
- `git diff --check`: passed.
New Release-active tests enumerate independent signed chunk intervals, all 299,520
logical cell ordinals across edges 8/16/32/64, envelope corners, each-axis invalid
bounds including INT64_MIN/MAX and UINT32_MAX, metric coordinates and all valid
positive fill numerators. Typed rejection is checked before reading expected values.
No allocation/terrain-generation/performance claim is made for the address envelope.
Linux GCC/Clang CI and UBSan have not been run for this increment. No container,
Argo or World0 deployment occurred. M5.2 storage benchmarks remain the next task.
+83
View File
@@ -0,0 +1,83 @@
# Local voxel contract v1 (M5.1)
This is the scoped experiment in [ADR-0042](../adr/0042-local-voxel-contract.md).
Public API: `include/evo/world/coordinates.hpp`. It implements pure address mapping
and logical cell validation, not a world container or a persistent file format.
## Frames and units
Right-handed Cartesian frame, +Z up, X cross Y = Z. `VoxelAddress` contains signed
cell indices, not metres. `ChunkAddress` contains signed chunk indices.
`LocalCell` contains unsigned cell offsets within a chunk. `MetricCorner` contains
named signed millimetres. No implicit conversion to the old periodic 2D particle
coordinates exists. The 2D habitat/effective-depth mapping waits for M6.1.
Per-axis voxel range is [-1,048,576, 1,048,576). Cell v owns the metric interval
[v*1000, (v+1)*1000) mm. The positive outer face exists geometrically but is not
another addressable cell. There is no wraparound or clamping. Negative Z is ordinary
volume, so the contract is not a surface heightfield. No origin shift is implicit.
## Mapping and failure contract
Callers explicitly pass edge N in {8,16,32,64}. M5.2 will compare those candidates;
there is no default chunk size. Valid chunk axes are [-1,048,576/N, 1,048,576/N).
Offsets satisfy 0 <= local < N. Each chunk covers exactly N cubed disjoint cells.
```
voxel --split(edge)--> {chunk, local} --join(edge)--> same voxel
local --ordinal(edge)--> x + N*(y + N*z) --local_from_ordinal(edge)--> same local
voxel --lower_corner_mm()--> signed metric corner
```
For edge 16, on any axis:
| Voxel | Chunk | Local |
|---:|---:|---:|
| -17 | -2 | 15 |
| -16 | -1 | 0 |
| -1 | -1 | 15 |
| 0 | 0 | 0 |
| 15 | 0 | 15 |
| 16 | 1 | 0 |
All functions return `std::expected` and leave arguments unchanged. Invalid edge
is reported before address validation; join checks chunk before local coordinates.
Metric conversion validates voxel bounds before multiplying. Accepted ordinal range
is [0,N cubed). Max N cubed is 262,144; all intermediate arithmetic is bounded.
Inputs at INT64_MIN/MAX and UINT32_MAX must fail safely, not overflow.
| Error | Meaning |
|---|---|
| invalid_edge | Candidate edge not supported |
| voxel_out_of_range | Any signed voxel axis outside the local envelope |
| chunk_out_of_range | Any signed chunk axis outside the edge-specific envelope |
| local_out_of_range | Any local offset >= edge |
| ordinal_out_of_range | Ordinal >= edge cubed |
| invalid_cell | Fill >65,535 or void/material-fill mismatch |
## Logical cell and identity boundaries
`CellSample::create(MaterialId, fill)` produces a validated value. Material zero
and fill zero denote void. Nonzero material requires positive fill. Fill/65,535 is
an exact rational fraction of the 1m-cubed cell; integer volume/mass conversion must
carry remainders under a later accounting contract. No geometry shape, material
density, light, moisture, nutrients or energy are inferred from this value.
An unknown nonzero material key is structurally valid here; M5.3's versioned table
must resolve it or reject it. Native sizeof/alignment is not an encoded layout.
Palette compression, uniform storage and varying pages belong to M5.2. Smooth
meshing needs additional geometry information and a separate comparison/ADR.
A chunk is storage addressing, a region is simulation authority, and an ecological
cell is a resource/model domain. They are not interchangeable IDs. M5.1 functions
operate in one caller-selected frame; no function compares coordinates from different
worlds or frames. Persisting/exchanging keys requires those identities and versions
in the enclosing schema. No coordinate or material key allocates resident data.
## Acceptance and next step
Tests must prove floor mapping against an independently constructed interval oracle,
not merely split(join(x)); exhaust every ordinal for every candidate edge; test all
axes, seams, envelope corners and invalid extremes. M5.1 is complete when those
contracts build and pass. M5.2 next compares compact chunk layouts and sizes; it must
not infer a preferred storage representation from these C++ value types.