Files
aevolution/Cellular_Revamp_Build_Plan.md
T
dingoandClaude Opus 5.5 4bc5d5eee7
Foundation / checks (checks) (push) Successful in 5s
Foundation / checks (client) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 4s
Foundation / checks (postgres) (push) Successful in 5s
Foundation / checks (network) (push) Successful in 5s
Foundation / checks (tsan) (push) Successful in 5s
Foundation / checks (deploy) (push) Successful in 4m29s
Foundation / postgres-tools (push) Successful in 24s
Foundation / server-image (push) Successful in 4m33s
Foundation / image (push) Successful in 4m59s
feat(cellular): session v14, bundle 15 and rules-13 wildlife
Session v14 carries the rules-13 revamp: a body block in the owner's view
(members, emergence threshold, exclusions, Emerge open, payable energy,
mass and the 20 traits), become, emerge and channel exclusions on actions,
become on mutation choices, catalog offers (id, chance, cost) and the
emerged ending. Older sessions never see a v14 field. The client shows
Stay / Become offspring offers named from the shared catalog, continuing
as a bud, the organism and its Emerge button, kept channels, the body and
the emerged end screen.

Bundle 15 (rules 13 on owner format 11) is durable: schema 60 admits it
raw-only, stores become as bit 15 of the choice's operator, widens the
action input and mutation results, and publishes the 14 -> 15 revamp
profile migration. evo-world-clone opens cellular-v10 (cellular-v9 plus the
revamp upgrade from --revamp-tuning), resumable and recoverable.

Wildlife counts reserve matter as energy, waits for the bud fee, grows
organisms one short of emerging, and hunts by the region step's rules-13
engulf test. The play summary adds organisms, offers and the spent pool.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-26 07:31:32 -04:00

203 lines
10 KiB
Markdown

# 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.
- **Server phases first, then one session version.** Phases 1-5 build and test the
server halves. The wire changes in every one of them (body values, offers, bud
choices, organisms), so session v14 and the client screens for all of them are one
step after phase 5, rather than a protocol revision per phase. Nothing deploys before
that step anyway.
- **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) - done
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: in the session v14 step.
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 done
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.
- Channel exclusions are a 4-bit step intent field, carried in the trace's byte 14.
Client (session v14 step): 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 done
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.
Until phase 4, a chosen mutation edits the offspring plan (as rules 10-12 do); phase 4
turns the choice into the split.
Client (session v14 step): 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 done
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 - server done
Unblocked 2026-10-23: the maintainer accepted whole-organism mutations and the
playtest form of Emerge (ADR-0179).
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.
As built:
- An organism develops as its genome with the target size times its members, so mass,
footprint, upkeep, intake and engulf mass all follow from it. Its corpse records the
single-cell extent.
- Adhesion ends the single cell's life as `merged` (an empty corpse) and starts the
organism as a new life (bud identity, two members) holding the whole body and reserve,
at the cell's spot and with its account, affinity and progress.
- An organism's mutation is recorded as a direct expression (no split); its changed
tissue is paid from the reserve with construction energy. Unaffordable keeps the offer.
- An organism's bud pays the bud fee and adds litter members at the current growth.
Wildlife organisms stop one member short of the threshold. An organism cannot become
its bud.
- Handling adds `organism.load_per_mille` of the extra members' mass as load.
- Emerge (intent bit, exclusive with bud, engulf, intake and frozen) at the threshold
exports the body and reserve through the boundary ledger and ends the life as
`emerged`. Below the threshold the request is ignored.
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.
### Session v14 and the client - done
- Session v14: the phase 1 body values in perception; payable energy; the exclusion
control; named offers with pro, con, chance, cost and Stay / Become; the bud choice;
organisms and the Emerge action.
- Client screens for all of the above.
As built ([schema](schemas/network/session-v14-cellular-revamp.md)): a 64-byte body block
(members, threshold, exclusions, Emerge open, payable energy, mass, the 20 traits); become,
emerge and exclusions on actions; become on choices; catalog offers (id, chance, cost) named
by the client from the shared catalog; the emerged ending. The client shows Stay / Become
offspring on each offer (one Choose for an organism or Adhesion), "Continue as the bud",
the organism's size and the Emerge button, the channels kept from burning, the body, and the
emerged end screen.
### Durable plumbing - done
Bundle 15, schema 60 and the `cellular-v10` opening (ADR-0179 "Durable form"): the
14 -> 15 revamp profile migration with recovery, become stored as bit 15 of the durable
choice's operator, the action input's new bits, and mutation results 0-6.
### Phase 6: wildlife, instrumentation and the playtest
- Wildlife controller: matter-as-energy aware, budding with litter, engulfing with the
new eligibility. Done: hunger counts payable energy, buds wait for the bud fee (litter is
the owner's), an organism adds members until one short of the threshold, and hunting uses
the region step's rules-13 engulf test (reserve share, capacity, membrane in nanometres).
- 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 |
| --- | --- |
| Retuning bubble energy or founder `energy_conversion` (keep 40% vs today's 100%) | 2 |
| Organism pace: in tests a two-member organism at half growth swims about 7.5 µm per tick and needed about 5,000 ticks on a rich mote to fund one internal member | 6 |
| Region migration does not carry rules-13 per-life state (affinity, members); an organism's move would be refused | 6 |
## 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. |