Define durable cellular mutation history

This commit is contained in:
dingo
2026-10-11 05:55:42 -04:00
parent 15ad04f22d
commit 66ffdc1cad
5 changed files with 191 additions and 4 deletions
@@ -0,0 +1,95 @@
# 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.
@@ -0,0 +1,73 @@
# ADR-0122: Append-only cellular genome revisions
## Status
Accepted engineering amendment for M11.4c (2026-10-11). It refines
[ADR-0034](0034-lineage-archive.md) and [ADR-0062](0062-lineage-checkpoint-profile.md)
for in-life mutation in cellular lives. It adds no mutation balance or NPC rule.
## Context
ADR-0098 requires a living organism to keep its life and organism identities
while its genome advances to an immutable successor. The lineage archive
currently records the genome assigned at birth and exposes no later genome
revision. `CellularLives` additionally requires that the archive's birth genome
equal the live owner's current genome. Without a history amendment, a successor
genome cannot be admitted without either losing the birth fact or breaking
checkpoint closure.
## Decision
- Keep each `OrganismRecord`'s genome as its immutable birth genome. Add an
append-only organism genome-revision record containing organism ID, previous
genome ID, successor genome ID, origin event ID and effective tick. It records
no selecting account or other actor. The successor genome is already admitted
to the same archive, names the previous genome as its parent, and its
`origin_event` equals the recorded event. Revisions apply only to living
organisms, after birth and before terminal death, and at most one revision per
organism per tick.
- Add `current_genome(organism)` to resolve the birth genome followed by the
append-only revision chain. Birth identity and history remain queryable;
current cellular lives and corpses validate against the final revision at the
relevant checkpoint. An organism's life and organism IDs never change during
mutation.
- Extend the archive codec to format 2, preserving canonical format-1 decode
and bytes for archives with no genome revisions. The new revision operation
and the explicit cellular-v2-to-v3 migration upgrade an archive instance to
format 2; format 2 encodes immutable birth records and ordered revision
records, then validates by replay and byte-identical re-encoding. No removal
or assignment operation is added.
- Keep all existing environmental-lineage, primitive and cellular-v2
checkpoints on their existing version bundles and format-1 archive bytes.
Introduce a cellular-v3 envelope/history profile for the format-2 archive and
revised owner closure. It has a fenced no-tick v2-to-v3 migration that
preserves all state, including outstanding fed-energy offers, initializes an
empty revision list and does not advance biology. New mutation publications
use v3 only; previous bundles remain readable and immutable.
- Recovery replays each mutation event in trace order, admitting the successor
genome and appending its revision before validating the resulting owner and
archive closure. The replayed head must match its complete committed bytes.
## Alternatives
- **Overwrite `OrganismRecord.genome`:** rejected because it erases the birth
fact and makes historical organism/genome linkage depend on a mutable value.
- **Track only the current genome in `CellularOwnedLife`:** rejected because
the archive could no longer establish every genome an organism carried or
replay the history from a checkpoint.
- **Store actor identity in the lineage archive:** rejected because the archive
records biological origin, while authenticated account and action identity
belong to the durable action ledger.
- **Rewrite old archive bytes or profile-4 heads in place:** rejected because
committed checkpoint payloads and archive encodings are immutable. A leased,
no-tick successor commit provides an explicit conversion boundary.
## Consequences
This changes the archive public API and codec, cellular owner closure and
snapshot version, checkpoint manifest version bundle, migration schema and
replay tests. Environmental and primitive checkpoint behavior remains frozen.
The added history is bounded by the existing archive genome cap; admission
refuses when that cap is reached. Mutation still requires the separate durable
selection/publication contract in ADR-0121 and the later client choice work in
11.4d.
+2
View File
@@ -21,6 +21,8 @@
- [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-0121: Durable cellular mutation selection](0121-durable-cellular-mutation-selection.md) - specifies a distinct reliable action, allocator identity, tick-bound replay and atomic publication for M11.4c.
- [ADR-0122: Append-only cellular genome revisions](0122-append-only-cellular-genome-revisions.md) - preserves immutable birth-genome links while adding a versioned revision chain and no-tick cellular-v3 migration.
- [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
@@ -54,7 +54,16 @@ pending; no gameplay balance is treated as final by this plan.
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.
- 11.4b implementation now includes version-2 owner snapshots, fed-energy
eligibility, stable offers, manifest/schema admission, the no-tick migration
publisher, immutable migration record, and migration-aware recovery/replay.
The final full CI run is not verified yet: Actions and the repository host
returned HTTP 503 while run #261 was in progress. Do not mark 11.4b validated
until a successful full run is observed.
- [ADR-0122](../adr/0122-append-only-cellular-genome-revisions.md) resolves the
archive/current-genome conflict with an append-only revision chain, preserving
birth-genome history, and a cellular-v3 no-tick migration. [ADR-0121](../adr/0121-durable-cellular-mutation-selection.md)
then defines selection and atomic publication. Affected modules are biology
archive API/codec, cellular life owner/snapshot, checkpoint version
bundle/migration, replay trace, SQL action publication, host/session and
crash/retry tests. Implementation starts from this versioned history boundary.
+8
View File
@@ -6763,3 +6763,11 @@ explicit optional value accessor after the checked guard, the size expression
widens before multiplication, and the cleared record initializes all fields.
Windows Debug owner/step tests, protocol test, session-server target build and
format check passed locally. Full CI follow-up is pending.
Run 261 was triggered for commit `15ad04f` after the bounded-perception fixtures
were formatted. At the last successful Actions query, client, deploy and network
jobs had passed, while checks, ECS and PostgreSQL were still running; TSan and
the dependent image jobs had not started. The Gitea host then returned HTTP 503
for the run page, workflow page and a Git remote dry-run. The final result could
not be verified in this environment. No full-CI pass is claimed for the 11.4b
migration/recovery work; rerun or inspect this gate when the host is available.