Files
aevolution/Cellular_Region_Movement_Plan.md
dingoandClaude Opus 5.5 34f544942f docs: cellular region and movement redesign with ADR-0177 and implementation plan
Records the maintainer's region decisions: regions linked to a world area rather
than a voxel, currents and a world-derived thermal map as conditions rather than
stock, capped regions, fresh-life region choice, scaled emergence and a protected
logout anchor. ADR-0098, 0172 and 0173 note the amendments. Adds the movement
draft decisions (fixed-point motion state, player-dropped 007 anchor) and the
phased implementation plan with a Git tuning file and bubble merging.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-21 16:13:20 -04:00

269 lines
15 KiB
Markdown

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