Define durable cellular mutation history
This commit is contained in:
@@ -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.
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user