Persist fed mutation offers in cellular v2
Foundation / checks (deploy) (push) Successful in 6s
Foundation / checks (ecs) (push) Successful in 1m56s
Foundation / checks (postgres) (push) Canceled after 0s
Foundation / checks (tsan) (push) Canceled after 0s
Foundation / postgres-tools (push) Canceled after 0s
Foundation / server-image (push) Canceled after 0s
Foundation / image (push) Canceled after 0s
Foundation / checks (network) (push) Canceled after 5m28s
Foundation / checks (checks) (push) Canceled after 7m39s
Foundation / checks (client) (push) Canceled after 7m39s

This commit is contained in:
dingo
2026-10-11 04:51:55 -04:00
parent 3548f2eacf
commit d652291126
21 changed files with 772 additions and 75 deletions
@@ -42,7 +42,8 @@ Binary fission, eggs, cohorts and spores stay open.
### 2. Mutation: earned during life, funded
A player's living organism can change its genome during its life:
- Eligibility is earned by surplus that has been fed and retained. The exact trigger
is part of 11.4's contract.
is the versioned, playtestable M11.4 trial in
[ADR-0120](0120-cellular-mutation-eligibility-trial.md), not a final balance rule.
- The player is offered seeded candidates, using the M3.4 generator (ADR-0033): stable
context, no free rerolls, and stale offers rejected.
- A chosen candidate is applied through funded development (ADR-0031/0032). It
+6 -4
View File
@@ -19,10 +19,12 @@ together, and ADR-0107 additionally produces corpses and a heat transfer.
## Decision
- Add a distinct `cellular-lives-v1` checkpoint profile (profile value 4) with
its own canonical envelope and restore path. Profile 3 bytes, cap, versions,
genesis rules and SQL behavior remain unchanged. A region's successor keeps
the exact profile and version bundle of its predecessor.
- Add a distinct cellular checkpoint profile (profile value 4) with its own
canonical envelope and restore path. Profile 3 bytes, cap, versions, genesis
rules and SQL behavior remain unchanged. A region's ordinary successor keeps
the exact profile and version bundle of its predecessor; the only exception
is the explicit no-tick profile-4 migration defined by
[ADR-0119](0119-cellular-profile-version-migration.md).
- The envelope is a complete single-region state closure, not a tick delta. It
binds world, region, frame, the current 50 ms simulation tick and the cellular
rule/version bundle. It contains the finite habitat and its explicit
@@ -0,0 +1,89 @@
# ADR-0119: No-tick migration for cellular profile versions
## Status
Accepted for M11.4b (2026-10-11) under the maintainer's instruction to proceed
with the recommended existing-region migration. This is a storage/versioning
decision; it does not ratify mutation thresholds, cadence or balance.
## Context
ADR-0108 requires ordinary commits to preserve their predecessor's exact profile
and version bundle. The live profile-4 envelope v1 has no durable fields for
mutation eligibility or a stable outstanding offer. Those values cannot be
reconstructed from its reserves, habitat or lineage archive. Adding them to v1
would reinterpret old canonical bytes; ordinary envelope-v2 successors would
violate the existing version-chain contract.
The engineering region already has identities and conserved inventories worth
retaining. Starting a new region would abandon that state and require separate
identity/world provisioning. M11 needs a narrow, auditable transition that
changes only the durable representation while biology is stopped.
## Decision
- Keep checkpoint profile 4 and its history profile. Introduce the exact v2
cellular version bundle `(rules=2, envelope=2, habitat=1, coordinate=1,
genome=1, development=2, founder=1, archive=1, mutation_state=1)`. The ninth
manifest version slot, zero in v1, pins the new mutation-state section. Keep
all profile-4 v1 decoders so retained history and recovery can read the
predecessor bytes.
- Permit one first-class, operator-authorized **profile migration commit** from
a current profile-4 v1 head to v2. It uses the same world, region, frame,
account/life/organism/genome/event identities and a new sequence; its begin
and end ticks are equal to the predecessor tick. It is fenced by the current
region lease and advances no simulation tick.
- The v2 checkpoint is made by fully restoring and validating v1, then copying
the region closure exactly. Habitat and patch provenance, opening totals,
nursery, heat, all life positions/growth/body/reserve/timers, corpses and
lineage archive remain equal. New per-life mutation state starts with zero
earned eligibility, event index zero and no outstanding offer. The migration
creates no birth, death, action, resource transfer, history event or outbox
record.
- Bind the source commit and manifest digest, source payload digest and version
bundle to the target commit, manifest digest, payload digest and version
bundle in an immutable migration record, created atomically with the new
head. The target manifest names the source as its predecessor. Exact retry
returns the committed receipt; reuse with any different source, target,
manifest or payload is a conflict. Unknown database results are resolved by
that same immutable identity. Stale head or lease fails closed.
- Ordinary commits before and after the migration continue to require exact
profile, version bundle, tick quantum and history profile equality. The
normal cellular publisher cannot publish a zero-tick commit or change a
version bundle. Only the dedicated migration publisher may do so, and only
for the supported v1-to-v2 pair.
- Recovery validates the migration record and both immutable manifests/digests,
restores the v1 predecessor and v2 target independently, and compares every
carried biological and accounting field. The replay stream records the
migration as a representation transition with an empty biological trace.
Corrupt, partial or unsupported pairs reject readiness; recovery never
invents eligibility.
## Alternatives
- **Write new fields under profile-4 v1:** rejected because it changes the
meaning of canonical bytes already retained by the region.
- **Start a separate v2 region:** rejected for this increment because it loses
the current region's live identities and state and requires cross-world
cellular identity remapping.
- **Allow ordinary successor commits to change versions:** rejected because
any worker could reinterpret a durable head during routine stepping.
- **Advance one biological tick during conversion:** rejected because it would
mix a representation upgrade with gameplay and could change inventories or
eligibility at deployment time.
## Benefits and costs
The existing region can continue into M11.4 while its old history stays
immutable and auditable. The extra migration API, durable link table, dual
decoder support and crash/retry tests enlarge persistence and recovery code.
Operators must explicitly schedule the one migration before a v2 build can
resume mutation-enabled simulation.
## Consequences
Update the profile-4 C++ manifest validator/builder, v2 checkpoint codec,
PostgreSQL parser and dedicated transactional migration publisher, durable
recovery/replay, schema documentation and tests together. Keep the migration
administrative path disabled for ordinary ticks. Mutation eligibility values
and offer cadence remain M11 trial rules and require separate evidence.
@@ -0,0 +1,80 @@
# ADR-0120: Cellular mutation eligibility trial
## Status
Accepted for the first M11.4 implementation (2026-10-11). The threshold and
candidate count are versioned trial values for early playtesting, not balance
sign-off. Review them with the exploratory check and again in 11.9.
## Context
ADR-0098 requires mutation eligibility to come from fed surplus retained during
a life, with seeded M3 candidates, stable retries and stale-selection refusal.
ADR-0118 defines the exact funded transition. The current cellular tick records
successful patch uptake after charging maintenance and movement, but the life
checkpoint does not retain an earned surplus counter or an offer identity.
Without those fields, opening reserve could be mistaken for feeding and recovery
could create a free reroll.
## Decision
- Credit only energy successfully acquired from a provisioned environmental
food patch by a living cell and retained in that same tick's reserve. Do not
credit its opening reserve, energy merely held, movement, external grants or
energy returned by another owner. One committed tick credits its intake once;
publication retry cannot credit it again. Corpse/predation intake is outside
this M11.4 trial and needs an explicit rule before it can earn credit.
- Start with one mutation event per **60 seconds of the life's current
per-second maintenance cost** in credited energy. Derive the threshold from
the current genome, growth and environment using checked integer arithmetic.
Carry any remainder. If several events are earned while an offer is open,
retain them as earned credit; issue at most one offer at a time. This starting
interval is a tunable, versioned trial value.
- An offer asks the M3 generator for three candidates; it may return fewer when
the genome has fewer eligible operators. An empty result does not consume the
accumulated credit or event index. Its context records the life,
parent genome identity/digest, event index, offer tick, seed/stream, candidate
count, growth and recorded environment. Event indices advance only when an
earned event becomes an offer. The generator order is canonical, never a
ranking. Re-reading or retrying the same offer regenerates identical bytes.
- Identify an offer by `(life_id, event_index, offer_tick)`. A selection names
that identity and is revalidated against the stored parent and context. A
wrong or consumed offer identity, changed genome or changed recorded context
is stale. Advancing ordinary simulation ticks alone does not expire an open
offer; the offer tick is an identity component the client must echo, not a
50 ms decision deadline. A stale or declined offer earns no replacement; a
later offer needs new retained feeding credit.
- Store the fed-energy remainder, event index and complete outstanding offer
context in profile-4 v2. They are life state and restore exactly. The no-tick
v1-to-v2 migration initializes all credit and event indices to zero and has
no outstanding offer. Offer selection and genome publication remain in the
later atomic path; 11.4b does not publish a chosen mutation.
## Alternatives
- **Use total reserve as eligibility:** rejected because an opening founder
balance would earn mutation without feeding.
- **Reroll whenever context changes or a player asks:** rejected because it
rewards movement through contexts or repeated requests with unearned draws.
- **Expire an offer after one simulation tick:** rejected because a 50 ms
decision window would not leave a practical opportunity to read and choose.
- **Rank or filter to only affordable candidates:** rejected because that hides
the actual tradeoffs and would change the seeded candidate set. Funding
failure remains visible and atomic under ADR-0118.
## Benefits and costs
The checkpoint can prove that offers were earned by feeding, retries reproduce
the same offer, and choices remain readable across several live ticks. This adds
per-life durable state, a profile migration and explicit stale-offer handling.
The 60-second threshold may feel too frequent or too slow; the early M11 check
and repeated-life evidence must guide a versioned adjustment.
## Consequences
Implement the accounting in the authoritative cellular owner, store it in the
v2 checkpoint, expose only the owner's offer through the session boundary, and
test exact retry, stale identity/context, credit carry, no opening-reserve
credit, checkpoint restore and `NDEBUG`. The durable mutation selection and its
genome/archive/resource publication remain a later segment. No ranked score,
class tree, NPC mutation or automatic reroll is introduced.
+3
View File
@@ -18,6 +18,9 @@
- [ADR-0115: Owner-filtered cellular perception protocol v8](0115-cellular-owner-perception-v8.md) - carries the existing exact sensor view only to its authenticated owner without changing v1-v7 behavior.
- [ADR-0116: Cellular life-owner routing](0116-cellular-life-owner-routing.md) - reuses authenticated SessionRedirect with an operator-provisioned per-world region route catalog; owner lookup happens before account-control claim.
- [ADR-0117: Owner-only cellular tick diagnostics protocol v9](0117-cellular-owner-tick-diagnostics-v9.md) - adds the live cell's authoritative reserve and latest committed maintenance, movement and intake result to its owner-filtered view; v1-v8 stay frozen and no gameplay rule changes.
- [ADR-0118: Funded cellular mutation transitions](0118-funded-cellular-mutation-transition.md) - accepted M11 trial contract for exact channel-funded genome transitions; eligibility cadence remains open.
- [ADR-0119: No-tick migration for cellular profile versions](0119-cellular-profile-version-migration.md) - permits an explicit leased, auditable profile-4 v1-to-v2 representation transition while ordinary commits retain exact versions.
- [ADR-0120: Cellular mutation eligibility trial](0120-cellular-mutation-eligibility-trial.md) - starts with 60 seconds of retained fed energy per unranked offer requesting up to three candidates; the threshold remains open to playtest review.
- [ADR-0058: Region durability contract](0058-region-durability-contract.md) - accepted M7.1 full checkpoint batches and explicit state closure; storage implementation follows.
+13 -4
View File
@@ -27,7 +27,7 @@ pending; no gameplay balance is treated as final by this plan.
| Segment | Affected modules | Acceptance evidence |
|---|---|---|
| 11.4a: funded transition proposal | Biology mutation/development public API and implementation; mutation tests; ADR-0118 | Deterministic selection revalidation; exact per-channel body/reserve closure; construction energy charge; insufficient-channel refusal with no partial result; `NDEBUG` tests |
| 11.4b: earned eligibility and offer identity | Cellular life state, tick intake accounting, offer context, profile-4 codec/schema | Offers require retained fed surplus; exact retry returns the same offer; changed genome/context/tick refuses stale selection; no free rerolls; checkpoint restore preserves eligibility and action identity |
| 11.4b: earned eligibility and offer identity | Cellular life state, tick intake accounting, offer context, profile-4 v2 codec/schema | One offer per 60 seconds of retained fed energy (trial), requesting up to three unranked candidates; exact retry returns the same offer; mismatched offer identity or changed genome/context refuses stale selection; ordinary ticks do not expire an offer; no free rerolls; restore preserves eligibility and offer identity |
| 11.4c: durable mutation publication | Cellular host/session, SQL migration/action parser, replay, crash tests | One action atomically publishes debit, genome successor, organism revision, archive and result; duplicate retry is exact; uncertain commit and process restart have one outcome |
| 11.4d: player choice and review | Engineering client trial UI, replication, playtest notes | Owner sees unranked candidates and actual tradeoffs; choice/refusal/recovery is readable; playtest verifies the choice follows useful feeding rather than appearing at spawn |
@@ -46,6 +46,15 @@ pending; no gameplay balance is treated as final by this plan.
## Progress
- 11.4a implementation is in progress: `fund_mutation` returns a detached,
channel-conserving transition under ADR-0118. Session offers, eligibility,
durable publication and UI remain open.
- 11.4a implementation is complete locally: `fund_mutation` returns a detached,
channel-conserving transition under ADR-0118. Its full CI run is pending.
- The ADR-0108 profile-version conflict is resolved by
[ADR-0119](../adr/0119-cellular-profile-version-migration.md): an explicit,
leased, no-tick v1-to-v2 representation migration initializes mutation state
empty and preserves the complete existing region closure. [ADR-0120](../adr/0120-cellular-mutation-eligibility-trial.md)
defines the first versioned eligibility/offer trial. Their owner and persistence
implementation is the current 11.4b work after the 11.4a CI gate.
- The current 11.4b slice adds version-2 owner snapshots, fed-energy eligibility,
stable offers and manifest/schema admission. The no-tick migration publisher,
immutable migration record, and migration-aware recovery/replay are still open;
11.4b is not complete until those durable paths and PostgreSQL CI pass.