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

4.9 KiB

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.