From 20cbe034147e98fc4bae3c9c5e38702bf5065193 Mon Sep 17 00:00:00 2001 From: dingo Date: Sat, 10 Oct 2026 20:57:01 -0400 Subject: [PATCH] Plan primitive cellular gameplay gate --- docs/engineering/M11_3_DELIVERY_PLAN.md | 95 +++++++++++++++++++++++++ 1 file changed, 95 insertions(+) create mode 100644 docs/engineering/M11_3_DELIVERY_PLAN.md diff --git a/docs/engineering/M11_3_DELIVERY_PLAN.md b/docs/engineering/M11_3_DELIVERY_PLAN.md new file mode 100644 index 0000000..e69aa8b --- /dev/null +++ b/docs/engineering/M11_3_DELIVERY_PLAN.md @@ -0,0 +1,95 @@ +# 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](../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.