96 lines
5.4 KiB
Markdown
96 lines
5.4 KiB
Markdown
# ADR-0121: Durable cellular mutation selection
|
|
|
|
## Status
|
|
|
|
Accepted engineering contract for the first M11.4c implementation (2026-10-11),
|
|
subject to the append-only history and v3 migration in
|
|
[ADR-0122](0122-append-only-cellular-genome-revisions.md). This does not settle
|
|
mutation balance or client presentation. The 11.3 probe and 11.9 repeated-life
|
|
review may revise trial rules through a versioned decision.
|
|
|
|
## Context
|
|
|
|
ADR-0098 requires the player to choose among seeded, unranked candidates and
|
|
requires the funded transition to be authoritative. ADR-0118 defines the
|
|
channel-by-channel funding proposal, while ADR-0120 persists the earned offer.
|
|
Those pieces still stop before the successor genome, archive, body, reserve,
|
|
consumed offer and durable action result become one recoverable state change.
|
|
|
|
ADR-0122 resolves the archive conflict by retaining the birth binding and adding
|
|
an append-only revision chain. Cellular closure will compare current state to
|
|
that chain's final genome. Implementation requires the v3 owner snapshot,
|
|
version bundle and no-tick migration contract.
|
|
|
|
The existing cellular reliable action is movement/intake input. Extending its
|
|
frozen wire bytes or interpreting an ordinary tick action as a mutation would
|
|
make retries and recovery ambiguous. A successor genome and mutation event also
|
|
need a world-allocated identity that survives retry and cannot be reused after
|
|
a crash.
|
|
|
|
## Decision
|
|
|
|
- A mutation selection is a distinct reliable cellular action. Its canonical
|
|
input names the stable life, the exact outstanding offer `(life_id,
|
|
event_index, offer_tick)`, and one offered operator ID. It is bound to the
|
|
authenticated account and action ID by the existing durable action key.
|
|
Existing v1-v9 wire layouts and v7 movement/intake inputs remain frozen.
|
|
- The host accepts only the exact outstanding offer and an operator present in
|
|
that offer. It reserves one successor identity from the world allocator,
|
|
keyed idempotently by `(world, account, action_id)`. Repeating the same action
|
|
returns the same pending reservation; different bytes under the same action
|
|
ID conflict. Gaps after abandoned reservations are allowed; identities are
|
|
never reused. The reserved value names the successor genome and its origin
|
|
event in their separate namespaces. The life and organism identities do not
|
|
change.
|
|
- The accepted choice is scheduled for the next advancing cellular tick. The
|
|
trace records the complete selection and reserved identity, ordered by stable
|
|
life ID, alongside that tick's existing life intentions and births. Replay
|
|
applies the normal life step first, then resolves mutation selections for
|
|
surviving lives before births. Thus one committed tick contains the action;
|
|
mutation does not create a hidden or zero-time biological step. If the life
|
|
dies during that step, replay produces a durable no-effect result.
|
|
- At the selection boundary, the owner revalidates the stored offer, parent
|
|
genome, context and candidate, then derives the funded transition using the
|
|
post-step body and reserve and the offer's recorded growth/environment. On
|
|
success the same checkpoint atomically stores the successor genome and
|
|
ancestry, archive, body/reserve transfer, consumed offer, life revision,
|
|
allocator reservation binding and final action result. A deterministic
|
|
refusal leaves all biological state unchanged and records its final result
|
|
with the same checkpoint. No client value can supply a genome, digest,
|
|
identity, body, reserve or price.
|
|
- Add a new cellular replay-trace format and a separate canonical mutation-action
|
|
block. Keep existing trace/action formats decodable for earlier commits.
|
|
PostgreSQL validates ordering, bounds, action identity and trace/result
|
|
correspondence; an immutable migration adds fenced publication and lookup
|
|
for mutation selections. Recovery reloads the mutation block under the
|
|
region lease, matches it to the replay trace and durable action rows, and
|
|
compares the replayed complete checkpoint byte-for-byte with the committed
|
|
head.
|
|
- Exact retries, including an uncertain commit or process restart, return the
|
|
original action outcome and successor identity. Reusing an action ID with
|
|
changed selection bytes is refused. A stale/consumed offer cannot mutate and
|
|
cannot earn a replacement offer; a new choice requires a later earned offer.
|
|
|
|
## Alternatives
|
|
|
|
- **Change the v7 cellular input in place:** rejected because already deployed
|
|
action bytes and their SQL validation are durable contracts.
|
|
- **Publish a genome change outside the tick checkpoint:** rejected because
|
|
archive, body/reserve, offer consumption and action result could then recover
|
|
from different points.
|
|
- **Allocate a successor ID only in memory:** rejected because restart or an
|
|
uncertain publication could reuse an identity or generate a different
|
|
successor.
|
|
- **Run a mutation as a zero-tick publication:** rejected because it adds a
|
|
second state-changing publication boundary and complicates deterministic
|
|
replay without a player-visible benefit.
|
|
|
|
## Consequences
|
|
|
|
This adds a versioned archive history, cellular trace/action representation, a
|
|
fenced allocator reservation, SQL publication and recovery paths, and
|
|
crash/retry tests. The biology generator and funded-transition APIs remain pure.
|
|
Candidate ranking, automatic mutation, new-life creation, and presentation
|
|
belong to no part of this contract. The operation is not player-accessible until
|
|
the later 11.4d client action and review UI are complete.
|