# Cellular revamp build plan Status: approved for implementation, 2026-10-22. Builds the [cellular gameplay plan](Cellular_gameplay_plan.md) and its system plans: [mutation](Cellular_mutation_plan.md), [reproduction](Cellular_reproduction_plan.md), [feeding and energy](Cellular_feeding_energy_plan.md), [predation and defense](Cellular_predation_defense_plan.md) and [body and maintenance](Cellular_body_maintenance_plan.md). Decision record: [ADR-0179](docs/adr/0179-cellular-gameplay-revamp.md). Continues from phases 1-2 of the [region and movement plan](Cellular_Region_Movement_Plan.md), which shipped as rules 12. ## Approach - **Build every phase, then playtest once.** Each phase is committed and pushed with CI green (AGENTS.md), but nothing is deployed until the last phase. The playtest runs on a fresh DEV region opened with the new rules. - **New versions, disposable DEV worlds.** Rules 13, genome schema 7, development 7, founder 6, a new owner format, bundle and schema, and a fresh `cellular-v10` opening. No upgrade from existing rules-12 regions (ADR-0177). - **One revamp tuning file.** Every new tunable goes in `deploy/kubernetes/region/dev/tuning/cellular-revamp.tuning`, beside the rules-12 `cellular.tuning`, with the same format and validation. - **Client and server together** in every phase. - **Shared biology.** Derivations stay in the headless library, so the client predictor and the server agree. ## Phases ### Phase 1: genome and body (rules 13 foundation) Server: - Genome schema 7: every heritable value the plans name, in points (founder 100) unless stated: - size, density, membrane, body recipe (per thousand, C/N/P/O), upkeep efficiency, growth speed; - collection per channel (E/C/N/P/O), shared intake, burn efficiency per matter channel, energy kept per bubble (`energy_conversion`), light capture; - engulf capacity, kill absorption; - bud share, litter (founder 0), Adhesion flag; - the existing movement arrangement. - Development 7 and founder 6: size, density and recipe set mass, footprint and surface; upkeep = essential floor + adjustable part / efficiency; membrane mass from points; no legacy photosynthesis speed penalty. - Rules 13 owner skeleton (new owner format) and tuning keys for every body value. Client: none in this phase. Showing the new body values needs them on the wire, which session v14 adds in phase 2. Verify: founder 6 derives the same body as founder 5 where the plans say "today's value"; the essential floor holds; encode/decode and bound checks for schema 7. ### Phase 2: feeding, energy and predation Server: - Collection per channel with the shared intake limit; the membrane collection penalty. - Energy kept per bubble; the rest to heat. - Matter as energy: burn the largest non-excluded channel, upkeep overrides exclusions, death only when nothing can pay. - Region spent pool with a seeded drip back as bubbles; waits at the deposit limit. - Reserve matter in mass for handling and movement energy, not upkeep. - Engulf check with engulf capacity and `engulf_reserve_mass_percent`; kill absorption; the kill remainder split between bubbles and the spent pool. - Session v14 for the new perception fields and the exclusion control. Client: energy display including what matter can stand in for; channel exclusion toggles; spent-pool drips drawn like infall; hover and HUD show the phase 1 body values. Verify: conservation per channel and energy across burning, the pool, kills and drips; no burn of excluded matter except for upkeep; replay determinism. ### Phase 3: mutation offers Server: - Catalog of the 49 mutations as data: effect, eligibility, triggers, base weight, steps, cost and `enabled`, all from the tuning file. - Per-cell affinity scores, inherited at birth; activity counters for every trigger. - Chance allocation (`clamp(k x weight, floor, cap)`, summing to the option count) and a seeded systematic draw; the draw and chances are recorded so a retry never rerolls. - Offer cadence from the tuning file; one pending offer. - Cost paid from the reserve (matter may stand in for energy) and reclaimed as seeded random bubbles, merging into the farthest bubble at the deposit limit. Client: offer screen with name, pro, con, chance, cost and shortfall. Verify: chances sum to the option count and respect floor and cap; the draw's marginal frequencies match the chances over a seed ensemble; triggers fire as specified; costs conserve. ### Phase 4: reproduction Server: - On-demand bud with the control choice (stay or become the bud), the tunable fee and bud share; one-way control transfer (ADR-0163). - Mutation split: write the mutation into both plans, split body and reserve by `split_share`, the offspring expresses it, the player chooses the cell; refusals leave the offer pending. - Litter: guaranteed and chance extra offspring sharing one investment, limited by free spots and the region cap. - Wildlife buds from its own plan with litter; wildlife never mutates. Client: Bud with Stay / Become; offer options with Stay as founder / Become offspring; refusal reasons. Verify: control transfer is one way and exactly once across retries and restarts; splits and litters conserve; a refused split spends nothing. ### Phase 5: multicellular organisms and emergence Blocked on the maintainer's confirmation of the locked-requirement question in ADR-0179 (whole-organism mutations). Server: - Adhesion forms the organism at once. The organism is one life with a member count, one genome, one reserve and a body that is the sum of its members. - Internal buds add members; mutations are expressed by the whole organism; whole- organism engulfment by total mass; mass-scaled handling. - Emergence threshold (members, mass, reserve energy) and the Emerge action; the wildlife member limit as a safeguard. Client: organism drawn as its member cells; Emerge button at the threshold. Verify: one reserve and one genome across members; whole engulfment conserves; the Emerge action only at the threshold. ### Phase 6: wildlife, instrumentation and the playtest - Wildlife controller: matter-as-energy aware, budding with litter, engulfing with the new eligibility. - Play summary: first-birth time, time to Adhesion, deaths by cause, energy share paid by matter, offers seen and chosen, mutations held per lineage. - Mount `tuning/cellular-revamp.tuning` into the provision Job beside `cellular.tuning` (kustomize `configMapGenerator`) in the push that promotes the new images. Revamp keys live in that separate file so images from before rules 13 never read them. - Opening `cellular-v10` in a new DEV region; promote the images; full Argo sync. - Playtest. ## Open items | Item | Phase | | --- | --- | | Whole-organism mutations versus the locked "structural changes are expressed in offspring" requirement | 5 | | What Emerge does before the 3D world exists | 5 | | Retuning bubble energy or founder `energy_conversion` (keep 40% vs today's 100%) | 2 | ## Risks | Risk | Mitigation | | --- | --- | | Many new genome fields exceed the 256-byte genome bound | Measure in phase 1; widen the bound in schema 7 if needed. | | Matter-as-energy makes cells nearly unkillable by starvation | Burn rates and drip rate are tunable; instrument the matter share of energy paid. | | 49 triggers add per-tick work | Counters are integer and per cell; measure tick time in phase 6. | | Control transfer across retries duplicates or loses control | Durable action receipts, as for existing births. | | One deploy at the end hides integration problems | Every phase ships its client half and runs end to end in local tests. |