Files
aevolution/docs/engineering/M11_3_DELIVERY_PLAN.md
T
dingo 20cbe03414
Foundation / checks (checks) (push) Successful in 5s
Foundation / checks (client) (push) Successful in 4s
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 5s
Foundation / checks (network) (push) Successful in 4s
Foundation / checks (postgres) (push) Successful in 5s
Foundation / checks (tsan) (push) Successful in 5s
Foundation / postgres-tools (push) Successful in 5s
Foundation / server-image (push) Successful in 4s
Foundation / image (push) Successful in 4s
Plan primitive cellular gameplay gate
2026-10-10 20:57:01 -04:00

6.6 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: specify a bounded region-local domain, its boundary policy, contact/perception query and finite per-channel stock for this version. Do not use the probe marker as an organism or expose unseen resources as client knowledge. Persist the habitat opening and exact environmental changes.
  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.

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 Explicit units, tick order, spatial bounds 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 Primitive region host; persistence adapter/schema; session 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.

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.