Files
aevolution/docs/engineering/M11_3_DELIVERY_PLAN.md
T
dingo 0b607bae53
Foundation / checks (client) (push) Successful in 4s
Foundation / checks (checks) (push) Successful in 4s
Foundation / checks (deploy) (push) Successful in 4s
Foundation / checks (ecs) (push) Successful in 4s
Foundation / checks (network) (push) Successful in 4s
Foundation / checks (postgres) (push) Successful in 4s
Foundation / checks (tsan) (push) Successful in 4s
Foundation / postgres-tools (push) Successful in 5s
Foundation / image (push) Successful in 5s
Foundation / server-image (push) Successful in 5s
Define bounded cellular motion trial
2026-10-10 21:01:19 -04:00

7.8 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.

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 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.