From 66ffdc1cad691877ea7ded16e2f0ca1b0e9ca95b Mon Sep 17 00:00:00 2001 From: dingo Date: Sun, 11 Oct 2026 05:53:37 -0400 Subject: [PATCH] Define durable cellular mutation history --- ...121-durable-cellular-mutation-selection.md | 95 +++++++++++++++++++ ...2-append-only-cellular-genome-revisions.md | 73 ++++++++++++++ docs/adr/README.md | 2 + docs/engineering/M11_4_DELIVERY_PLAN.md | 17 +++- docs/engineering/VALIDATION.md | 8 ++ 5 files changed, 191 insertions(+), 4 deletions(-) create mode 100644 docs/adr/0121-durable-cellular-mutation-selection.md create mode 100644 docs/adr/0122-append-only-cellular-genome-revisions.md diff --git a/docs/adr/0121-durable-cellular-mutation-selection.md b/docs/adr/0121-durable-cellular-mutation-selection.md new file mode 100644 index 0000000..6f2b3d9 --- /dev/null +++ b/docs/adr/0121-durable-cellular-mutation-selection.md @@ -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. diff --git a/docs/adr/0122-append-only-cellular-genome-revisions.md b/docs/adr/0122-append-only-cellular-genome-revisions.md new file mode 100644 index 0000000..09ccb90 --- /dev/null +++ b/docs/adr/0122-append-only-cellular-genome-revisions.md @@ -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. diff --git a/docs/adr/README.md b/docs/adr/README.md index 582c550..0346e44 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -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. diff --git a/docs/engineering/M11_4_DELIVERY_PLAN.md b/docs/engineering/M11_4_DELIVERY_PLAN.md index 842e43b..967bf0d 100644 --- a/docs/engineering/M11_4_DELIVERY_PLAN.md +++ b/docs/engineering/M11_4_DELIVERY_PLAN.md @@ -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. diff --git a/docs/engineering/VALIDATION.md b/docs/engineering/VALIDATION.md index 0fba7c9..c3e6008 100644 --- a/docs/engineering/VALIDATION.md +++ b/docs/engineering/VALIDATION.md @@ -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.