Files
aevolution/docs/engineering/M11_3_DELIVERY_PLAN.md
T
dingo fe03a0f8e4
Foundation / checks (deploy) (push) Successful in 6s
Foundation / checks (checks) (push) Failing after 40s
Foundation / checks (ecs) (push) Successful in 1m57s
Foundation / checks (postgres) (push) Failing after 53s
Foundation / checks (tsan) (push) Failing after 32s
Foundation / checks (network) (push) Failing after 3m1s
Foundation / checks (client) (push) Failing after 4m26s
Foundation / postgres-tools (push) Skipped
Foundation / server-image (push) Skipped
Foundation / image (push) Skipped
Define cellular owner diagnostics v9
2026-10-11 01:52:33 -04:00

28 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: ADR-0116 selects server-side routing when an account's durable life belongs to another region. The 11.2 implementation now resolves the owner before control claim and redirects through an operator-provisioned --life-route catalog. Migration, process-kill and client-follow tests are pushed; Linux/PostgreSQL CI remains unconfirmed. Do not claim multi-region control until those tests pass. A single-region playtest may proceed independently after its cellular route catalog and v8 build are verified.

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.
  • 11.3d-7g: CellularLives now builds a detached profile-4 birth candidate from an allocator-reserved request after the current tick. The owner derives primitive founder biology, selects the first unoccupied provisioned site, funds body/reserve/construction from nursery inventory, records the birth in a copied archive, and preserves energy/matter closure. Refusals leave the committed owner unchanged. Focused tests cover funding, placement, duplicate account, identity/tick validation, canonical restore and first action on the following tick. This remains in-memory: canonical birth trace, durable publication/recovery and session scheduling remain open, so 11.3e is not playable yet.
  • 11.3d-7h: profile-4 replay trace format 2 adds canonically ordered bounded birth records after each tick's existing-life intentions. Replay applies each birth at the end tick, derives all biology and placement from the predecessor, and verifies that request identity, generation and allocator identity are nonzero and unique. The decoder still accepts format-1 traces. C++ manifest validation and migration 22 raise the profile-4 trace ceiling; PostgreSQL and end-to-end birth publication tests are still pending, so this is not yet a durable birth path or a playable 11.3e slice.
  • 11.3d-7i: migration 23 adds the cellular birth-trace parser and requires the current account-control generation plus exact profile-4 life reservation before the checkpoint can publish. Reservation bindings and the checkpoint commit are one transaction; exact retries compare those bindings against the trace. Recovery loads the commit's birth bindings and matches account, request, identity and born tick before accepting replay. A PostgreSQL integration test covers empty-genesis birth, durable request outcome and restart recovery. CI/PostgreSQL execution remains pending, and the live v5 request scheduler still has to feed these records before 11.3e is playable.
  • 11.3d-7j: CellularSessionBatchBuilder::append now accepts reserved birth records, sorts and validates them, applies the tick's existing-life inputs, then builds each birth on a detached candidate at the end tick. A failed birth leaves the builder unchanged. Tests cover empty-region birth replay and duplicate request refusal. The server still needs to route v5 requests into this queue and run/publish the scheduler tick.
  • 11.3d-7k: region sessions can now enable the reliable v5 life-request callbacks and v7 cellular action ledger together. Admission remains per negotiated connection; unsupported v5/v6/v7 modes still fail closed. QUIC coverage opens v5 and v7 clients against one configured region session host.
  • 11.3d-7l: CellularRegionHost now serves v5 create/query callbacks using the durable allocator and preserves exact reservations in a deduplicated queue until their birth record is confirmed in a cellular commit. Its PostgreSQL test now exercises request, exact retry, queue, publication and final query through the host API. PostgreSQL CI remains pending.
  • 11.3d-7m: v7 sessions can now receive replicated snapshots and change their interest, in addition to committing cellular actions. QUIC coverage confirms a v7 client can receive a cell entity and move its focus. The process-level cellular tick loop and resource patch view are still required before 11.3e.
  • 11.3d-7n: evo-server --profile cellular now has a profile-4 serve path, durable v5/v7 sessions, 50 ms host ticks, checkpointed carried actions and live-cell replication. It pauses when no living account is connected and does not accumulate catch-up ticks while offline. The path has not been compiled with the Linux/PostgreSQL CMake preset or run against a region. Exact patch perception and the engineering-client controls/view are still required for the exploratory 11.3e playtest.
  • 11.3e-1: ADR-0115 defines a frozen v8 stream message for the existing owner-filtered ADR-0103 patch view. The codec accepts a bounded canonical address-ordered inventory list and keeps v1-v7 layouts unchanged. The server still needs to route each view to its authenticated owner; the client needs cellular input and presentation before the hands-on probe.
  • 11.3e-2: v8 sessions can receive the exact perceived patch list through an account-keyed reliable unicast; v7 and other accounts are excluded, and a zero-life view clears stale client state. The QUIC regression test exercises that boundary. The profile bridge now projects authoritative CellularLives perception each tick. Client controls and an on-screen view remain to be connected before the hands-on probe.
  • 11.3e-3: the engineering client now has a cellular-trial connect mode, sends reliable v8 movement/feed actions at the authoritative tick rate, requests the first allocator-backed life with a stable retry ID, draws visible patch markers, lists their exact perceived stocks, and lets the player select a patch for continuous feeding. The client build and live-region probe still need verification before this segment can be called playable.
  • 11.3e-4: the probe checklist records startup, controls, scope limits and the human feedback needed to decide whether the cellular loop merits further investment. It is ready for use after CI confirms the v8 server/client build.
  • Readiness update (2026-10-11): the maintainer reports that the Git checks passed, evo-region is running, and the client connects. This is operator confirmation of checks and connectivity; it does not establish that the v8 cellular path was selected or that life creation, movement, feeding and the on-screen perception work in a hands-on session. Those outcomes and the exploratory notes remain the 11.3e exit evidence. The 11.4 mutation expansion stays behind that probe so its feedback can affect the next design decisions.
  • 11.3e-5: the engineering client now translates cellular admission refusals and durable action results into readable messages instead of numeric wire codes. A committed action directs the player to inspect authoritative position and patch-stock changes. This clarifies transport/scheduling failures; the protocol still does not report per-tick reserve or itemized maintenance/movement costs, so resource-cost legibility remains an open probe limitation.
  • 11.3e-6a: ADR-0117 defines owner-only protocol v9 diagnostics for current reserve and the latest committed tick's maintenance, movement and intake result. The v9 codec keeps v8 bytes frozen and rejects malformed status combinations; standalone MSVC NDEBUG protocol tests pass. Server report projection and the client display remain the next parts of this subsection, with CI still pending.

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.