# Cellular region and movement implementation plan Status: approved for implementation, 2026-10-21. Implements [Cellular region changes](Cellular_Region_Changes.md), [Cellular movement draft](Cellular_movement_draft.md) and [ADR-0177](docs/adr/0177-cellular-regions-world-linkage.md). Movement mutation weights and timing start from the values chosen here and are tuned through the tuning file; the separate [mutation review](Cellular_mutation_draft.md) can replace them later. ## Approach - **Test on the live DEV system.** Every phase ends in a deployable image and a new DEV region opened with the new rules, then a playtest. No local-simulation gate. - **Fast pushes (Phase 0, done).** A push to `main` gates only on the deploy policy suite, then builds and publishes images. The full check matrix runs nightly, on pull requests and on manual dispatch. - **Disposable DEV worlds (ADR-0177).** New rules get new versions and a fresh opening. No upgrade paths from existing bundles, checkpoints or envelopes. - **One tuning file in Git.** Every tunable value lives in one file; see [Tuning file](#tuning-file). Retuning is a Git change and a full Argo sync; no image build. - **Client and server together.** Each phase ships its client half, so every DEV deploy is playable. - **One shared motion step.** The same integer code runs on the server and in the client predictor. ## Current code this plan changes | Area | Today | File(s) | | --- | --- | --- | | Motion | Stateless per-tick proposal: position from intent x speed, cost proportional to distance, instant stop. | `include/evo/biology/cellular_motion.hpp`, `src/biology/cellular_motion.cpp` | | Life step | Maintenance, then movement, then intake (ADR-0104). | `src/biology/cellular_step.cpp` | | Region step | Lives in life-id order, shared deposit contention, engulfment, corpses become bubbles. | `src/biology/cellular_region_step.cpp` | | Food | Habitat format 2: up to 4,096 static deposits, ordered and updated by address. | `include/evo/biology/cellular_habitat.hpp`, `src/biology/cellular_habitat.cpp` | | Environment | Joint owner `AEVOCEN1`: one ambient temperature, infall, heat export. | `src/server/lifecycle/cellular_environment.cpp` | | Lives and population | Owners 7/8, rules up to 11, bundle 13, schema 57. | `src/server/lifecycle/cellular_lives.cpp`, `cellular_population*.cpp` | | Wildlife | Shared controller choosing intents. | `src/server/lifecycle/wildlife_controller.cpp` | | Sessions | Session v12 perception lists in-range deposits by id (max 512, 26 bytes each). | `src/network/protocol/session_protocol.cpp`, `src/server/session/region_sessions.cpp` | | Client | Probe-style own-marker predictor and interpolation. | `src/client/prediction/*.cpp`, `src/client/views/*.cpp` | | Opening | `cellular-v8`: 30 x 30 mm, 9 pools, 1,800 bubbles, 20 C ambient. | `apps/evo-world-clone/main.cpp`, `deploy/kubernetes/region/dev/region-values.yaml` | The world has no thermal map yet: each cellular region has one ambient temperature. Phase 3 adds a seeded world thermal field for regions to sample. ## Tuning file - **Location:** `deploy/kubernetes/region/dev/tuning/cellular.tuning`, mounted into the region pod by a kustomize `configMapGenerator`, so a change restarts the region through a normal Argo sync. - **Format:** plain `key = value` lines with `#` comments; units in key names (for example `founder.thrust_um_per_s2 = 400`). Integer values only, matching the simulation. No new dependency. - **Validation:** unknown keys, missing keys, duplicates and out-of-range values are refused at startup, so a typo fails the sync visibly instead of running with a default. The file carries a `tuning.version` key. - **Determinism:** the region persists the tuning values with its checkpoint. When a restarted region finds different values, it records a tuning change at the next tick boundary and uses the new values from that tick. Replay of earlier intervals uses the values in force at the time. - **Scope:** every value in [v0 trial values](#v0-trial-values) plus movement mutation weights, offer timing and future tunables as they are added. Values that only shape a new region (size, current routes, seed) apply when a region opens; the rest apply on restart. ## v0 trial values Starting values for the tuning file, none locked. | Quantity | v0 value | Reasoning | | --- | --- | --- | | Region size | 60 x 60 mm | Founder crosses in about 5 min; room for 2-4 routes and quiet pockets. Within the existing 1,000,000 um axis limit. | | Perception radius | 5 mm (unchanged) | About 25 s of founder travel. | | Founder top speed | 200 um/s (unchanged) | Top speed = thrust / drag. | | Founder drag | k = 2 /s (95,163 ppm per tick) | 0.5 s time constant: responsive, coasts about 100 um from top speed. | | Founder thrust | 400 um/s^2 | Gives the 200 um/s top speed at k = 2. Reverse thrust equal. | | Founder turn rate | 1 turn/s | Responsive founder handling. | | Currents | 2-4 per region, 3-6 mm wide, 60-300 um/s | 0.3x-1.5x founder speed (accepted). | | Flow grid pitch | 250 um | Smooth at cell scale, 240 x 240 grid. | | Ambient range | 5-40 C across the region | Gradual gradients; extremes optional. | | Founder preferred | 20 C, comfort band +/- 5 C | Matches today's 20 C ambient. | | Body response | tau = 20 s | Readable lag; gives warning before lethal. | | Lethal (body temperature) | <= 0 C or >= 45 C | Applied to body, not ambient. | | Thermal multiplier | `min(8, exp(0.08 * off_pref_C + 0.04 * transition_C))` | Two costs from the region draft, capped. | | Region organism cap | 2,000 | Above today's population; tune from census. | | Deposit limit | 8,192 | Larger region; raises the 4,096 limit. | | Merged bubble cap | 8x a scattered bubble's stock | Bounds clumping; see moving food. | | Visible moving bubbles | 256 per update, nearest first | Fits the snapshot budget with velocities. | | Logout delay | 10 s | Same as the existing linger. | | Movement mutation step | +/- 5 reference points, paired -/+ 2 | From the movement draft. | | Recovery weight | `max(0.10, (index/100)^2)` below 100 | From the movement draft. | | Offer cadence | 25 s of productive active play, 3 options per offer | Midpoint of the draft's 20-30 s. | ## Moving food - **Merging.** When two bubbles touch, they become one bubble holding both inventories. Its radius follows its total stock, and it keeps the lower id. Bubbles at the merged-size cap stop merging, so currents cannot collapse all food into a few huge bubbles. Merging is conserved by construction (one inventory sum) and resolved in id order for determinism. - **Multi-channel bubbles.** A merged bubble can hold several channels; contact feeding already drains per channel. The client draws a merged bubble with its channel colors. - **Update limit.** Each update carries at most the configured number of moving bubbles, nearest first. Farther ones are dropped from that update; the client keeps advancing them with the shared flow field until a later update corrects them. Bubbles overlapping on screen are indistinguishable, so this is not visible. ## Phases Each phase lists server and client deliverables, then what is verified on DEV. ### Phase 0: pipeline (done) - `.gitea/workflows/build.yaml`: on push only the deploy suite runs before the image jobs; the full matrix runs nightly (09:00 UTC), on pull requests and on dispatch. Nightly runs have their own concurrency group so pushes do not cancel them. ### Phase 1: motion core and tuning file Server: - `CellularMotionState`: Q10 velocity, 16-bit heading, sub-micrometre accumulator. - Checked-in integer sine/cosine table with golden tests. - Per-tick step from the movement draft's numeric representation: turn, funded thrust, drag toward exactly zero, add flow, displacement with carried remainder. - Cost proportional to thrust used, divided by efficiency, not to distance. Unfundable thrust is not applied; the cell coasts. Maintenance failure still kills (existing behavior). - Swept contact against deposits and cells, subdividing so no step exceeds half the smallest contact radius, with a fixed work bound per tick. - `CellularMovementProfile` derived from the genome: thrust, efficiency, burst capacity and reserve, turn rate, forward and lateral drag, reverse thrust, anchor capacity, colony drive. Ten fields for 001-010. - Genome schema 6 with movement records at reference 100 for the founder; founder version 5; development version 6. - Tuning file parser and validation, shared by the server and `evo-world-clone`. Client: - Shared motion step linked into the client; the cell predictor uses it. - Brake and reverse controls (rebindable, ADR-0085); movement-state indicator. Verify: golden trajectories, decay to zero, no tunneling at 2x the top current speed, equal results across restore points, thrust-cost properties, tuning file refusals. ### Phase 2: currents, moving food and persistence Server: - Habitat format 3: deposits keyed and updated by stable id (not address), each with Q10 velocity for induced drift; a fixed-pitch spatial bucket index for contact; deposit limit from tuning. - Seeded current generator: 2-n looping routes with width, direction and speed, rasterized to the Q10 flow grid. Intersections add as vectors and are clamped to the larger route speed. - Bubbles move with the flow each tick in id order, merge on contact (see moving food), and deflect along solid edges so nothing piles up. - Induced drift from passing cells: radius, falloff, decay and maximum speed from tuning; contributions combine in life-id order. - Region step tick order: maintenance, turn and thrust, motion and swept contact, deposit advection, induced drift and merging, contact feeding, engulfment, deaths, births. - Persistence: rules 12, owner format 10, population envelope 4 and joint envelope format 2 carry motion state, deposit velocities and current configuration; durable bundle 14 and schema 58, entered only by a fresh `cellular-v9` opening. Joint batch 2 re-derives currents from configuration. - Opening `cellular-v9` in a new DEV region (`evo-world-clone`). Client: - Session v13: own-life motion state; deposits with velocity under the update limit; current configuration sent once at admission so the client builds the same grid. - Bubbles advanced with the flow field between updates; merged bubbles drawn with their channel colors. - Flow cues: trails and drifting specks that are clearly not food. Verify on DEV: food circulates and merges without loss or piles; founder handling in and across currents; restart resumes identical trajectories; tick time against the load governor (ADR-0097). ### Phase 3: thermal map and thermal biology Server: - World thermal field: seeded and coarse per world, sampled over the region's world area and scaled down to the habitat (ADR-0177). The region configuration stores the world-area reference and scale. - Per-cell thermal state: body temperature (mK) and acclimation offset. - Genome thermal fields: preferred temperature, comfort band, tau, lethal cold and heat limits; the parameters thermal mutations (091-095, 097) edit. - Integer exp table (Q16) for the capped multiplier on survival E. A body-temperature lethal check feeds the existing corpse-to-bubbles path with a new death cause. Client: - Heat-map terrain; compass; temperature gauge showing ambient, body and preferred band; contours or patterns for stressful and lethal areas, not color alone. - Thermal death shown as its own cause on the end-of-life screen. Verify on DEV: costs rise and settle as expected crossing gradients; lethal areas are reached only by choice; first-birth time stays near 3 minutes. ### Phase 4: movement mutations 001-010 Server: - Operators for all ten as fixed-reference percentage edits on the Phase 1 fields, including acquisition and shedding for 003, 007, 009 and 010. - 007 anchor: a player-triggered drop that fixes the cell at the point it hits until released; holding capacity against flow load. - 009 and 010 are offered only where colony attachment makes them meaningful. - Offer weights, recovery factor and cadence from the tuning file. Client: - Offer screen previews: before and after movement profile at matched conditions. - Anchor drop/release control and anchored state. - Visual body changes from the movement draft's tentative indicators (001-006), shared by NPCs and players. Verify on DEV: each option changes handling in the expected direction. ### Phase 5: wildlife - The wildlife controller plans with inertia (brakes before targets), uses currents (rides toward food), avoids lethal temperatures, seeks its preferred range and drops its anchor when it has one. Same rules as players. - Verify on DEV: wildlife survives and reproduces in the new regions without collapsing into one site. ### Phase 6: logout, capacity and region choice Server: - Logout: a delay with the cell vulnerable, then anchored, protected, and with metabolism and thermal response frozen; resume restores frozen motion state. Replaces the ADR-0098 linger for rules 12. - Region cap: births refused at the cap with a recorded reason; the wildlife controller stops attempting them. - Admin culling: an operator endpoint on the existing ops HTTP server (`src/server/ops_http.cpp`) that records each cull as an operator action. - Fresh-life region choice: list a world's regions with open capacity at admission, and route the new life through the existing redirect and handoff path (ADR-0096). Client: - Region choice screen for a fresh life; logout countdown; a notice when a birth is refused because the region is full. Verify on DEV: cannot escape a closing predator by logging out; a capped region refuses births and reopens after deaths; two accounts choose the same region. ### Later: emergence Emergence (scaled export, candidate selection, bulk queue) needs multicellularity and the 3D world. This plan keeps it possible: the region's world-area link and the thermal field from Phase 3 are what emergence targeting will use. ## Instrumentation for every playtest Extend `src/server/lifecycle/cellular_play_summary.cpp` with first-birth time, solitary-stage length, deaths by cause (starved, engulfed, thermal), time spent in currents versus quiet water versus anchored, propulsion E share of total E, bubble merges, and per-tick region work. These answer whether the 3-minute and 30-60-minute targets hold. ## Risks | Risk | Mitigation | | --- | --- | | Moving deposits raise tick cost | Spatial bucket index and merging reduce work; measure against the load governor in Phase 2. | | Merging collapses food into few large bubbles | Merged-size cap from tuning; watch merge counts. | | Prediction feels rubbery | Shared motion code in the client; measure prediction error on DEV. | | Ten movement parameters interact badly | Instrumentation plus removal of options that do not fit, as decided. | | Determinism drift between server and client | One library, golden trajectory tests in both builds. | | Less CI on pushes lets regressions reach DEV | Nightly full matrix; fix red nightly runs before the next phase. |