Files
aevolution/docs/engineering/M11_3_DELIVERY_PLAN.md
T
dingo c06ea9023d
Foundation / checks (checks) (push) Successful in 4s
Foundation / checks (client) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 4s
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (network) (push) Successful in 5s
Foundation / checks (postgres) (push) Successful in 5s
Foundation / checks (tsan) (push) Successful in 4s
Foundation / postgres-tools (push) Successful in 5s
Foundation / server-image (push) Successful in 5s
Foundation / image (push) Successful in 4s
Accept profile-4 first-life path
2026-10-11 00:08:41 -04:00

22 KiB

M11.3: Primitive locomotion, feeding and predation

This gate turns the funded, persistent primitive founder from a stationary life record into an organism that can act in a finite cellular habitat. The target is the exploratory hands-on check defined in ROADMAP.md: after 11.3 and before expanding mutation in 11.4. It is not a balance sign-off.

Authority and boundaries

Reviewed PROJECT_VISION, ENGINEERING_CONSTITUTION, SYSTEM_OVERVIEW, SIMULATION_ARCHITECTURE, REGION_DURABILITY, NETWORK_ARCHITECTURE, PERSISTENCE_ARCHITECTURE, ENERGY_MODEL, ENVIRONMENTAL_PROCESS, ENVIRONMENTAL_TRANSFERS, REPRODUCTION_MODEL, and ADRs 0031, 0032, 0053, 0089, 0098 and 0100. Inspected the public PrimitiveLives, PrimitiveRegionHost, RegionHost, EnvironmentalTransfers, metabolism, development, checkpoint and action-record interfaces and their lifecycle, transfer, QUIC and process tests.

The M6 EnvironmentalCommunity and EnvironmentalTransfers remain bounded fixtures. They do not become gameplay state, biological policy, or an implicit source of nutrients. The simulation and biology libraries remain independent of transport, PostgreSQL, graphics and Kubernetes. evo-server owns I/O, durable admission and scheduling; deterministic biological resolution receives explicit state and intentions.

ADR-0098 already selects movement and engulf intentions, phenotype-derived maintenance/movement/intake, channel-by-channel absorption, and conserved engulfment/corpses. This plan does not choose additional gameplay constants. Starting thresholds marked tunable stay versioned and visible to playtesters.

Contract gaps to close

  1. Persistent progression: checkpoint profile 3 currently closes only creation state. 11.3 must define a new versioned cellular checkpoint closure for position, tick, organism/genome, body/reserve, finite habitat fields, action/retry state and all implemented biological timers. Recovery must never supply defaults or advance biology while offline. Preserve profile-3 bytes and genesis compatibility.

  2. Atomic actions: the existing durable action record admits only the M10 no-effect probe kind, and its batch trace belongs to the environmental fixture. Define a versioned cellular intent and publication path that records the checkpoint and final outcomes together. Reuse the existing lease, control-generation and exact-retry guarantees; never duplicate an environmental debit or organism effect after an uncertain commit.

  3. Spatial habitat and perception: the shared world voxel pitch is 1 m (cell_pitch_mm = 1,000 mm), while the founder's body extent is 20 μm. M6 HabitatBox supports micrometre extents inside a voxel, but FieldStore permits only one site per voxel and environmental views sample that whole site's stocks. It cannot represent two independently stocked sub-meter food patches in one voxel. A cell could cross 50,000 body widths before reaching the next voxel, so wiring feeding directly to those field sites would make steering and local food choice meaningless. This is an architectural scale gap; do not change the shared world voxel contract to hide it.

    Resolution: ADR-0101 selects a new sparse, bounded two-dimensional microhabitat, with independently stocked 1,000 μm sites (50 founder extents), explicit finite per-channel openings and retained provenance. The pitch is a versioned tunable, not a final world rule. Its opening is provisioned as part of the region; it has no automatic replenishment. Later coupling to meter-scale world stores must be an explicit conserved transfer between scales. ADR-0102 now defines bounded non-wrapping motion and footprint contact. The cellular profile must still define perception range and resource visibility. Do not use the probe marker as an organism or expose unseen resources as client knowledge.

  4. Owner routing: 11.2 still lacks authenticated routing/reconnect when an account's life is in another region. Resolve the ADR-0100 protocol gap (v6 owning-region response plus authoritative endpoint lookup, or server-side routing) before claiming multi-region life control. A single-region local playtest may be prepared independently, but cannot close 11.2 or validate cross-region play.

No new dependency or renderer is required. If the selected spatial, checkpoint, or publication design conflicts with accepted architecture, stop that affected implementation and resolve the contract first.

ADR-0108/0109/0110 and schemas/cellular-lives-v1.md define an additive profile-4 state closure with region-wide channel conservation and a realizable 16 MiB bound while preserving profile 3. The in-memory cellular owner now has a bounded canonical snapshot/restore codec. SQL allowlisting, durable tick publication, session execution and crash-recovery evidence are still required before the first hands-on cellular probe.

Delivery segments

For each segment, name affected modules, run its applicable tests and checks, record unavailable environments in VALIDATION.md, then commit and push the scoped change before starting the next segment.

Segment Affected modules Acceptance evidence
11.3a: cellular state and spatial contract Biology public values; server lifecycle; checkpoint profile; schemas and architecture docs Implement ADR-0101/0102 microhabitat, movement and contact; define perception range, resource visibility, units, tick order and version allowlist; bounded canonical codec; hostile/truncated inputs refused before allocation; profile-3 compatibility; exact restore of every state field
11.3b: server-authoritative movement and perception Biology adapter; spatial query; intent validation; network protocol/client session Clients send only bounded movement/engulf intentions; server decides speed, position, contact and visible environment; range/speed forgery and stale intent tests; deterministic replay
11.3c: metabolism and finite transfers Biology metabolism/development adapters; cellular field ledger; corpse/predation resolution Intake and costs derived from phenotype; each resource channel conserves independently; contested stock has one winner; engulfed inventory moves once with excess detritus; starvation and death preserve all inventory
11.3d: durable tick publication and recovery Cellular region host; persistence adapter/schema; reliable v7 input and action outcomes; process tests Checkpoint, habitat changes, terminal outcome and final action results publish atomically; exact retry after uncertain commit; kill/restart at publication boundaries; no offline progress; Linux/PostgreSQL CI qualification
11.3e: exploratory playtest slice Server view replication; existing engineering client input/view; playtest notes One player can spawn, see what the cell perceives, steer, seek and feed in a finite habitat; show movement/resource costs and failure states; capture reproducible trace and human notes; no mutation or reproduction implied

Required checks

  • Unit/property coverage for position bounds, spatial contact, intention ordering, metabolism, transfer conservation and adversarial inputs.
  • Deterministic multi-seed traces, simultaneous resource contention, speed/range forgery, starvation, engulfment, corpse recovery and closed-box conservation.
  • Canonical encode/restore under NDEBUG, old profile/golden regressions, Linux ASan+UBSan, clang-format, clang-tidy and applicable Windows network tests.
  • Real PostgreSQL process tests for uncertain publication, SIGKILL and restart; CI evidence is required where the local Windows environment cannot run them.
  • A short hands-on probe before 11.4 that records agency, confusion, useful feeding choices, cost legibility and reasons to continue. One session is exploratory feedback, not evidence that the product is fun.

Progress

  • 11.3a contract direction: ADR-0101 selects finite 1 mm cellular food patches; ADR-0102 defines bounded non-wrapping movement and footprint contact. The complete living-set checkpoint and server profile remain open; ADR-0103 now defines the perception trial contract.
  • 11.3b-1: pure phenotype-derived movement proposal and square-footprint contact helper are implemented and locally tested. Session inputs, server state, replication and durable movement publication remain open.
  • 11.3c-1: pure channel-limited uptake proposal is implemented and locally tested. A finite patch map and canonical habitat-only codec are implemented; atomic update of patch, life reserve and durable action outcome remains open.
  • 11.3a-2: ADR-0103 and the habitat's pure perception projection implement the 5 mm footprint-gap trial radius and exact in-range stock view. Live authenticated server replication and the complete cellular checkpoint remain open.
  • 11.3c-2: habitat uptake proposals now require an authoritative in-bounds cell footprint and refuse a patch outside contact. Atomic patch/life publication, competing-life resolution and tick ordering remain open.
  • 11.3b-2: funded motion now returns one detached position/reserve/heat candidate and refuses underfunded or overflowing movement without partial debit. Live intent admission, tick publication and recovery remain open.
  • 11.3c-3: ADR-0104 and a single-life tick resolver compose maintenance, affordable movement and one targeted contact intake into a detached candidate. Shared-stock contention, starvation/death closure, owner commit and checkpoint recovery remain open; this helper is not yet a multi-life tick.
  • 11.3b-3: ADR-0105 and the v6 codec define cellular intention bytes for movement and an optional food-patch target. Server admission, durable simulation and client presentation are still open.
  • 11.3b-4: v6 intentions reuse the existing bounded session/epoch/tick/sequence admission rules and expose a deterministic read-only schedule until the host advances its simulated watermark. RegionSessions and a durable cellular host still do not consume this schedule.
  • 11.3b-5: the opt-in v6 RegionSessions path admits cellular datagrams and exposes the scheduled input to the host; the session client can send v6 movement and a requested patch address. V6 currently has no M10 probe view. Biology ownership, durable publication and perceived cell views remain open.
  • 11.3b-6: the cellular owner now exposes a life-scoped exact patch view using its authoritative footprint and ADR-0103's fixed range. V7 action-to-life binding refuses a requested patch unless it is in that cell's current view; source provenance and unseen stock remain private. Network view replication and client presentation remain open.
  • 11.3c-4: ADR-0106 defines stable life-identity arbitration for same-tick patch contention. A detached multi-life candidate resolves all claims against each patch's remaining per-channel stock; starvation still refuses the candidate pending same-tick death/corpse closure.
  • 11.3c-5: ADR-0107 closes unaffordable maintenance in the same tick, moving body and reserve into a corpse candidate and accumulated heat to an explicit output. The durable heat owner and lineage/checkpoint publication remain open.
  • 11.3c-6: server::CellularLives adopts funded profile-3 founders into one in-memory cellular owner, applies shared-habitat ticks atomically, records starvation corpses/deaths and enforces region-wide conservation. Checkpoint encoding, durable publication and online session execution remain open.
  • 11.3d contract: ADR-0108/0109/0110 and schemas/cellular-lives-v1.md define a separate profile-4 checkpoint closure for lives, habitat, corpses, heat and lineage.
  • 11.3d-1: CellularLives::snapshot/restore now canonically encodes that complete in-memory closure, verifies nested habitat and lineage, recomputes phenotype and inventory invariants, and rejects malformed, wrong-identity, wrong-tick, corrupt, unsupported and noncanonical state. Durable profile admission, publication and recovery remain open.
  • 11.3d-2: portable manifest v2 now assigns profile 4, pins the cellular rule, envelope, habitat, coordinate, genome, development, founder and archive versions, applies the 16 MiB cap, restores through the owner codec, and refuses profile-4 cloning. PostgreSQL admission and durable publication remain open.
  • 11.3d-3: PostgreSQL migration 18 recognizes the same profile-4 version bundle and payload cap, rejects clone genesis, and fail-closes progressing profile-4 commits until their dedicated atomic publication path is installed. CI still needs to execute the migration/parser checks.
  • 11.3d-4 contract audit: v6 cellular datagrams have per-session sequence IDs and only provisional receipts, so they cannot satisfy ADR-0108's exact retry requirement after reconnect. ADR-0111 keeps v6 frozen and specifies a reliable v7 action with stable account/action identity and commit-bound input/result bytes. The codec is now implemented; durable input records, recovery and atomic publication remain required before the host may consume it.
  • 11.3d-5a: protocol v7 now defines a reliable 48-byte cellular action carrying stable per-account action identity, plus a distinct committed-cellular result. The strict codec and round-trip/refusal tests are implemented; admission, durable input records and atomic tick publication remain open.
  • 11.3d-5b contract audit: the existing durable ledger omits canonical input, so it cannot reject changed bytes for a retried id after restart. ADR-0112 defines a 24-byte canonical biological input, profile-4 commit action block, and isolated cellular publisher. V7 server admission remains refused until this input-aware ledger and exact-retry resolution are implemented.
  • 11.3d-5c: the protocol library now exposes canonical 24-byte cellular input encode/decode, excluding reconnect-specific session and epoch values. Focused tests verify identical retry bytes and reject zero ticks, malformed flags, reserved bytes and noncanonical absent-target addresses. Durable lookup and publication remain open.
  • 11.3d-5d: ActionLedger now has input-aware single and batch record queries. Its compatibility implementation exposes legacy outcomes without cellular bytes, which is insufficient to admit v7 retries and therefore fails closed. PostgreSQL overrides, exact-byte admission comparison and publication remain open.
  • 11.3d-5e: migration 19 extends durable action rows with input/result fields, adds a lease-fenced input-aware lookup, and preserves legacy probe records. The C++ persistence and PostgresActionLedger adapters parse single and batched records, rejecting malformed cellular evidence. CI/PostgreSQL execution is pending; no cellular writer exists yet.
  • 11.3d-5f: IntentAdmission accepts v7 cellular actions, carries their canonical input bytes with the scheduled action and rejects changed bytes on a reused id while the action is pending or final in memory. Debug and Release/NDEBUG focused tests pass. RegionSessions still refuses v7 until publication and restart recovery are complete.
  • 11.3d-6a: migration 20 adds the isolated profile-4 publisher and ambiguous commit resolver. It moves the shared checkpoint transaction into a private helper while preserving the existing profile-1/2/3 wrapper. A private immutable row gates progressing profile-4 commits; canonical 48-byte action records and result rows are inserted atomically with the checkpoint, and exact retries must match their original block. Runtime grants expose only the public wrappers, not the private helper, evidence table, or parser. Migration-chain, privilege-audit, and parser tests are added. PostgreSQL CI is pending; the C++ writer, full process recovery, and RegionSessions v7 enablement remain open.
  • 11.3d-6b: the persistence API now has separately named cellular publish and ambiguous-commit resolution calls. Both pass canonical action bytes to the profile-4 SQL wrappers and validate the returned receipt/status using the existing store error contract. Focused PostgreSQL adapter tests cover malformed calls; CI execution is pending. Payload preparation, replay validation, and a cellular region host remain open.
  • 11.3d-6c: ADR-0113 and the portable CellularBatch codec define bounded per-life inputs for every tick. Replay clones the committed predecessor, applies the exact living-set intentions through CellularLives, and returns a state to compare byte for byte with the durable head. Migration 21 adjusts only profile-4 trace bounds and adds lease-fenced loading of the immutable action block. Codec, migration, and store-adapter tests are added; CI execution is pending. Action-to-life reconciliation and process recovery remain open.
  • 11.3d-6d: a portable 48-byte cellular action-block codec now matches the PostgreSQL representation. It validates canonical input/order and proves each durable action names a life in the predecessor and exactly matches that life's per-tick replay intention. Tests cover successful matching and changed-input refusal. Durable action result reconciliation and full checkpoint recovery remain open; CI execution is pending.
  • 11.3d-6e: a dedicated persistence adapter now replays a cellular batch from the verified predecessor, binds durable actions to those replay inputs, checks byte-identical candidate state, uploads and reads back payload/trace objects, and publishes through the isolated profile-4 SQL wrapper. Prepared retry and ambiguity resolution retain the exact trace and action bytes. The portable manifest validator now applies ADR-0113's variable cellular trace bounds, matching migration 21. Result-row reconciliation and full restart recovery, host integration, and CI execution remain open.
  • 11.3d-6f: the cellular recovery adapter now verifies the committed payload, current tail trace and predecessor link, loads the immutable action block under the lease, replays the batch and checks every action's persisted kind, result, tick, sequence and canonical input bytes. A PostgreSQL integration test covers funded-founder genesis, one committed neutral action, publication and restart-style recovery. CI execution is pending; action conflicts and process fault recovery remain.
  • 11.3d-7a: CellularRegionHost now owns a fenced profile-4 lease, recovers before readiness, replays submitted cellular batches, publishes only through the profile-4 adapter, pauses on ambiguous commits and resolves/retries the exact prepared bytes. It exposes final action acknowledgements only after a confirmed receipt. A real-PostgreSQL test exercises host publication followed by a new host instance recovering the result.
  • 11.3d-7b: the QUIC client and region-session host can negotiate the reliable v7 cellular action path. Admission requires both durable control and action ledgers, and the server keeps v7 off the M10 probe/view datagrams. Actions retain canonical biological input bytes through carry and can be retried after reconnect; the session test covers durable duplicate-result recovery and changed-input refusal. The caller still needs to own the live scheduler and join admitted actions to the profile-4 host publication loop. Process kill tests and CI execution remain open.
  • 11.3d-7c: a bounded adapter now overlays carried v7 actions onto the scheduler-supplied complete living-set inputs. It binds each action by authenticated account to exactly one live life, preserves the canonical 24 bytes for the atomic action block, and refuses stale, malformed, duplicate or unowned actions. Other life inputs remain scheduler-owned. The application scheduler, profile-4 genesis tooling, process kill tests and CI execution remain open.
  • 11.3d-7d: CellularSessionBatchBuilder now copies the verified committed cellular state, binds the replay trace to its exact predecessor commit and digest, and accumulates up to the existing bounded batch limits. Each appended tick is validated by the same CellularLives rules; tests compare the built candidate with independent trace replay and cover cross-tick action-ID reuse. The service loop, profile-4 genesis tooling, process kill tests and CI execution remain open.
  • 11.3d-7e contract resolution: a playable cellular stage needs a player life, but ADR-0100 requires empty genesis and allocator-issued identities, while ADR-0108 keeps profile 3 immutable and leaves profile-4 conversion/cloning unsupported. ADR-0114 now directs an allocator-backed profile-4 birth using the existing reliable v5 request. Its canonical birth record follows the existing-life inputs at the end of a normal tick and publishes with that checkpoint; this does not seed genesis or add a birth-only tick. The durable birth trace, publisher, recovery, host, session and restart tests remain open; 11.3e is not playable yet.
  • 11.3d-7f: the owner persistence API and evo-world-clone provision --opening cellular-v1 now create only an empty profile-4 genesis. The CLI requires explicit arena dimensions, temperature, nursery funding, ordered spawn sites, finite patch stocks and a stable commit ID; the owner helper verifies the payload, provisions sequence 0/tick 0, resolves an exact genesis retry and refuses nonempty founder/archive state or conflicting reuse. A PostgreSQL integration check covers exact restore and retry behavior. This does not provide a player spawn or make 11.3e playable.

Exit boundary

11.3 closes only when all five segments have evidence and the player-facing single-region probe works against the authoritative server. 11.2 owner routing must also be closed before M11 claims persistent control across regions. Mutation, funded budding, complete permadeath, logout/resume and repeated-life playtesting remain later gates; the 11.3 probe does not pretend those paths exist.