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
90 lines
4.9 KiB
Markdown
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.
|