Files
aevolution/docs/adr/0119-cellular-profile-version-migration.md
T
dingo d652291126
Foundation / checks (deploy) (push) Successful in 6s
Foundation / checks (ecs) (push) Successful in 1m56s
Foundation / checks (postgres) (push) Canceled after 0s
Foundation / checks (tsan) (push) Canceled after 0s
Foundation / postgres-tools (push) Canceled after 0s
Foundation / server-image (push) Canceled after 0s
Foundation / image (push) Canceled after 0s
Foundation / checks (network) (push) Canceled after 5m28s
Foundation / checks (checks) (push) Canceled after 7m39s
Foundation / checks (client) (push) Canceled after 7m39s
Persist fed mutation offers in cellular v2
2026-10-11 04:51:55 -04:00

90 lines
4.9 KiB
Markdown

# ADR-0119: No-tick migration for cellular profile versions
## Status
Accepted for M11.4b (2026-10-11) under the maintainer's instruction to proceed
with the recommended existing-region migration. This is a storage/versioning
decision; it does not ratify mutation thresholds, cadence or balance.
## Context
ADR-0108 requires ordinary commits to preserve their predecessor's exact profile
and version bundle. The live profile-4 envelope v1 has no durable fields for
mutation eligibility or a stable outstanding offer. Those values cannot be
reconstructed from its reserves, habitat or lineage archive. Adding them to v1
would reinterpret old canonical bytes; ordinary envelope-v2 successors would
violate the existing version-chain contract.
The engineering region already has identities and conserved inventories worth
retaining. Starting a new region would abandon that state and require separate
identity/world provisioning. M11 needs a narrow, auditable transition that
changes only the durable representation while biology is stopped.
## Decision
- Keep checkpoint profile 4 and its history profile. Introduce the exact v2
cellular version bundle `(rules=2, envelope=2, habitat=1, coordinate=1,
genome=1, development=2, founder=1, archive=1, mutation_state=1)`. The ninth
manifest version slot, zero in v1, pins the new mutation-state section. Keep
all profile-4 v1 decoders so retained history and recovery can read the
predecessor bytes.
- Permit one first-class, operator-authorized **profile migration commit** from
a current profile-4 v1 head to v2. It uses the same world, region, frame,
account/life/organism/genome/event identities and a new sequence; its begin
and end ticks are equal to the predecessor tick. It is fenced by the current
region lease and advances no simulation tick.
- The v2 checkpoint is made by fully restoring and validating v1, then copying
the region closure exactly. Habitat and patch provenance, opening totals,
nursery, heat, all life positions/growth/body/reserve/timers, corpses and
lineage archive remain equal. New per-life mutation state starts with zero
earned eligibility, event index zero and no outstanding offer. The migration
creates no birth, death, action, resource transfer, history event or outbox
record.
- Bind the source commit and manifest digest, source payload digest and version
bundle to the target commit, manifest digest, payload digest and version
bundle in an immutable migration record, created atomically with the new
head. The target manifest names the source as its predecessor. Exact retry
returns the committed receipt; reuse with any different source, target,
manifest or payload is a conflict. Unknown database results are resolved by
that same immutable identity. Stale head or lease fails closed.
- Ordinary commits before and after the migration continue to require exact
profile, version bundle, tick quantum and history profile equality. The
normal cellular publisher cannot publish a zero-tick commit or change a
version bundle. Only the dedicated migration publisher may do so, and only
for the supported v1-to-v2 pair.
- Recovery validates the migration record and both immutable manifests/digests,
restores the v1 predecessor and v2 target independently, and compares every
carried biological and accounting field. The replay stream records the
migration as a representation transition with an empty biological trace.
Corrupt, partial or unsupported pairs reject readiness; recovery never
invents eligibility.
## Alternatives
- **Write new fields under profile-4 v1:** rejected because it changes the
meaning of canonical bytes already retained by the region.
- **Start a separate v2 region:** rejected for this increment because it loses
the current region's live identities and state and requires cross-world
cellular identity remapping.
- **Allow ordinary successor commits to change versions:** rejected because
any worker could reinterpret a durable head during routine stepping.
- **Advance one biological tick during conversion:** rejected because it would
mix a representation upgrade with gameplay and could change inventories or
eligibility at deployment time.
## Benefits and costs
The existing region can continue into M11.4 while its old history stays
immutable and auditable. The extra migration API, durable link table, dual
decoder support and crash/retry tests enlarge persistence and recovery code.
Operators must explicitly schedule the one migration before a v2 build can
resume mutation-enabled simulation.
## Consequences
Update the profile-4 C++ manifest validator/builder, v2 checkpoint codec,
PostgreSQL parser and dedicated transactional migration publisher, durable
recovery/replay, schema documentation and tests together. Keep the migration
administrative path disabled for ordinary ticks. Mutation eligibility values
and offer cadence remain M11 trial rules and require separate evidence.