Foundation / checks (checks) (push) Successful in 5s
Foundation / checks (client) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 4s
Foundation / checks (network) (push) Successful in 5s
Foundation / checks (postgres) (push) Successful in 4s
Foundation / checks (tsan) (push) Successful in 4s
Foundation / checks (deploy) (push) Successful in 4m24s
Foundation / postgres-tools (push) Successful in 1m31s
Foundation / server-image (push) Successful in 4m25s
Foundation / image (push) Successful in 4m50s
A mutation choice's reserved tick is now the earliest tick it may bind at, not the only one (ADR-0121 amendment). With write-behind commits, a choice reserved for head + 1 landed in ticks already being simulated or committed: the batch was refused, or the reservation was orphaned for a past tick and stalled the region. Schema 59: a bound record carries the tick it applied at and the rest of its input must equal the reservation's; the "omits a reserved mutation" refusals are removed. Existing rows are unchanged, so an orphaned reservation binds at the next commit that carries it. The host keeps every unbound reservation queued and the open batch binds those the commit in flight does not carry, at its next tick; the earlier hold on new choices is removed. A choice that outlives its life binds as life_died (owner, trace matching and recovery accept it when no life with that ID remains). Recovery takes a bound choice's tick from its trace. Tests: a choice skipped by one checkpoint binds a tick late and recovers; builder late binding, refusal before the earliest tick, and a departed life's life_died outcome. Full local PostgreSQL qualification passes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
159 lines
9.5 KiB
Markdown
159 lines
9.5 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.
|
|
|
|
## Implementation notes
|
|
|
|
- 11.4c-1 (schema v35): a checkpoint whose trace carries selections publishes
|
|
only through `publish_cellular_mutation_checkpoint`, with the canonical
|
|
64-byte mutation block and one result byte per choice, taken from the
|
|
publisher's own replay. Recovery reloads the bound choices and requires the
|
|
replay's results to equal them.
|
|
- 11.4c-2 (host and session admission, 2026-10-13): the region host admits a
|
|
v10 `CellularMutationAction` only when it names the account's living cell,
|
|
its exact outstanding offer (event index and offer tick) and one of the
|
|
offered operators, checked against the committed state. It reserves the
|
|
successor for the next tick (head + 1), queues the reservation, and the
|
|
scheduler includes it in that tick's batch. Exact repeats are idempotent;
|
|
a second choice while one waits is refused as `too_many_unresolved`, and a
|
|
changed reuse of an action ID as `invalid_action`. The receipt names the
|
|
publishing tick; once published, the owner receives an `ActionOutcome`:
|
|
`committed` when applied, `committed_no_effect` for a durable refusal (life
|
|
died, insufficient funding). A repeat after publication returns the same
|
|
outcome (`duplicate`) while the host remembers it.
|
|
- A reserved choice must never be skipped: schema v35 also refuses any
|
|
checkpoint whose tick range contains an unbound reservation of the region
|
|
that the checkpoint does not carry. Without this, an uncertain reservation
|
|
(the reply was lost but the row committed) could pass its tick unpublished
|
|
and block its account's next choice forever. The host treats an uncertain
|
|
reservation, a refused publication or a recovery as "reload pending
|
|
reservations under the current lease before the next publication".
|
|
- The wire `tick` of the choice is the client's latest simulated tick (after
|
|
the offer); the server, not the client, chooses the publishing tick.
|
|
- 11.4d server half (2026-10-13): v10 adds message type 26, the owner's
|
|
outstanding offer with its unranked candidates in operator order and each
|
|
successor's capability value, maintenance and total mass, so the choice can
|
|
be shown with its actual tradeoffs. The server sends it to the owner's v10
|
|
session when the offer or the session changes and clears it when the offer is
|
|
consumed; the engineering client keeps the latest offer for its UI. Type 26
|
|
extends v10 before any v10 server reaches DEV; v1-v9 are unchanged.
|
|
- Remaining after this: the client choice and review UI (maintainer) and the
|
|
11.4d playtest notes.
|
|
|
|
## Amendment: durable mutation queue (schema 59, 2026-10-22)
|
|
|
|
The exact-tick rule above assumed that reserving a choice and committing a batch were
|
|
serialized on one connection, one tick at a time. Rules-12 regions commit a batch of
|
|
ticks on a background thread while the next batch is simulated (ADR-0178 follow-up), so
|
|
a choice reserved for "head + 1" could land in ticks already simulated or being
|
|
committed. The batch was then refused (losing its ticks), or, when the commit's check ran
|
|
before the reservation committed, the reservation was left for a tick that had passed
|
|
and stalled the region on DEV (tick 9752).
|
|
|
|
- A reservation's tick is now the earliest tick the choice may bind at. The region
|
|
binds a queued choice at the first tick it simulates after admitting it; the
|
|
mutation record carries the tick it bound at, and the rest of its input must equal
|
|
the reservation's. Stored rows are unchanged, so a reservation whose tick already
|
|
passed binds at the next commit that carries it.
|
|
- The "omits a reserved mutation" refusals are removed: an unbound reservation waits in
|
|
the queue. The host keeps every unbound reservation queued (and reloads them on
|
|
recovery), and the open batch binds those the commit in flight does not carry.
|
|
- A choice can outlive its life while it waits. Its selection then names a life that is
|
|
gone; the owner records `life_died` and changes nothing, and trace matching and
|
|
recovery accept such a selection when no life with its ID remains.
|
|
- Recovery takes each bound choice's tick from its trace selection, not from the stored
|
|
input.
|
|
- Births still enter only a fresh batch on the durable head.
|