Files
aevolution/docs/adr/0147-durable-cellular-migration-freeze.md
T
dingo c625a4cb68
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 2m24s
Foundation / checks (network) (push) Successful in 20m44s
Foundation / checks (client) (push) Successful in 22m3s
Foundation / checks (tsan) (push) Successful in 23m1s
Foundation / postgres-tools (push) Canceled after 0s
Foundation / server-image (push) Canceled after 0s
Foundation / image (push) Canceled after 0s
Foundation / checks (checks) (push) Canceled after 24m7s
Foundation / checks (postgres) (push) Canceled after 24m3s
M12.4: retain migration source freezes and explicit aborts
2026-10-18 09:08:50 -04:00

63 lines
3.7 KiB
Markdown

# ADR-0147: Durable biological migration preparation and source freeze
## Status
Accepted and qualified for scoped M12.4h implementation, 2026-10-18. Executed
evidence and limits are in [VALIDATION](../engineering/VALIDATION.md).
Destination staging, atomic paired publication and activation
remain subsequent segments. No deployment or automatic migration is selected.
## Decision
Prepare ADR-0144's exact raw/population pair against two digest-verified bundle-10
committed cuts, with the same representation, world/frame/tick and compatible
biology/geometry. Retain canonical migration trace 1 under its stable request
UUID. The source's current lease and exact head fence preparation. The destination
head is checked optimistically during preparation; it is neither locked nor
activated. This does not establish a simultaneous global cut at freeze commit.
Before preparation, copy and verify the destination predecessor payload into the
source's immutable object namespace. This is a read-only replay capsule, not an
owned population or additional spendable stock. Both manifests stay retained in
the shared commit journal. Recovery can verify the entire recorded pair from the
source namespace even if the destination later advances or is unavailable.
Schema 47 records immutable preparations and explicit source-authorized aborts,
plus one bounded pending pointer per source region. A prepared source retains all
its cells, inventory and history at its existing head. Coarsely freeze the whole
region: refuse new checkpoints, profile/version changes, interval admissions and
player mutation reservations until settlement. Preparation refuses pending
intervals and outstanding player choices; C++ requires fully suspended controlled
cells and an eligible complete wildlife group. No biological tick or transfer
occurs. Destination ghosts own nothing; this segment creates none.
The owning host pauses readiness and advancement during preparation uncertainty
or a recovered freeze. It retries the exact retained request, renews authority,
and restores/validates the capsule before resuming any work. Replacing a worker
or expiring a lease never releases the freeze. Explicit abort under current source
authority appends its immutable outcome and removes the pending pointer in one
transaction, leaving both biological heads unchanged. Exact preparation/abort
retries retain their outcome; retrying an aborted preparation never reopens it.
Timeout is not an abort. A replacement owner can explicitly abort without needing
destination authority, since no ownership has transferred.
Subsequent destination staging must recheck its exact captured head. A moved
destination requires an explicit source abort and a fresh workflow; do not rebase
the old trace silently. Future two-head commit must settle the source pointer
atomically with both exact results and immutable shared evidence. This segment
admits no migration result manifest and no destination activation.
## Alternatives, costs and qualification
An in-memory pause disappears after process death. Lease expiry is not an abort
decision. Copying cells into an active destination before paired commit duplicates
ownership. Keep the source authoritative and durably frozen instead. A whole
region pause is deliberately coarse; it is not a final ecological movement or
latency policy. Source-side capsule retention adds bounded storage and replay work.
Require real player-origin wildlife, both representations, complete replay and
stock equality, pending-work refusal, publication/admission bypass rejection,
duplicate/conflicting preparation, explicit abort, restart/new-epoch recovery,
ambiguous replies, process loss, missing/corrupt capsules and host readiness.
No elapsed-day, atlas, environmental coupling or multigeneration claim follows.