Files
aevolution/docs/adr/0156-census-pending-migration-evidence.md
T
dingo 27ec5729bf
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 2m26s
Foundation / checks (network) (push) Successful in 21m1s
Foundation / checks (client) (push) Successful in 22m9s
Foundation / checks (tsan) (push) Successful in 24m36s
Foundation / postgres-tools (push) Canceled after 0s
Foundation / server-image (push) Canceled after 0s
Foundation / image (push) Canceled after 0s
Foundation / checks (postgres) (push) Canceled after 33m38s
Foundation / checks (checks) (push) Canceled after 33m49s
M12.7: reconcile pending migration evidence in census snapshots
2026-10-18 21:14:53 -04:00

69 lines
4.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# ADR-0156: Pending migration evidence in registered census snapshots
## Status
Accepted for scoped M12.7c, 2026-10-18. Extends ADR-0133/0147–0149/0153–0155.
No biological format, rule, activation workflow or terminal-extinction decision.
## Decision
A registered census must expose its pending biological handoffs, rather than
letting a caller mistake a staged ghost for additional owned life or infer that
no transfer exists. Schema 52 reads the union of source/destination pending
pointers for one world, ordered by request UUID, at most 65 requests. The 65th
detects overflow of the 64-request work bound; never truncate a complete result.
This is the existing active-pointer inventory, not an audit of all historical
preparations or a new source of ownership. No duplicate state table/write.
Capture it in the same read-only repeatable-read view as domain, registry and
heads. Keep both retained predecessor manifests, canonical trace and, when staged,
ghost digest/length. Require internally coherent pointers, un-aborted/uncommitted
state and metadata identities; malformed/missing evidence fails the entire query.
Both predecessor builds must belong to the caller's retained build allowlist,
including an optimistic destination predecessor that is no longer its current head.
Every endpoint must be registered. The source predecessor must equal its selected
head; a staged destination must also equal its selected predecessor. A merely
prepared destination is an optimistic observation and may have advanced, as
ADR-0147 permits. Common census-boundary checks still apply independently.
After metadata capture ends, fully replay every captured handoff from its retained
source-side predecessor/capsule objects. For a stage, independently replay the
destination-side capsules and compare the complete derived ghost bytes with the
verified staged object. Reuse the existing migration codec, binding and paired
replay logic. Missing/corrupt/false capsules or ghosts fail with no partial census.
This is historical evidence verification, not a fenced live-owner lookup; a
concurrent abort/commit does not invalidate an already captured immutable view.
Return verified trace/member/material evidence and a staged flag alongside the
registered census. Source stock is already counted at its unchanged committed
head. Capsules and ghosts add **zero** census stock. After atomic commit, the next
view sees settled heads and no pending pointers; abort clears both pointers with
unchanged heads. Neither timeout nor lease expiry settles a workflow.
## Alternatives, costs and risks
Reading current fenced loaders after capture could combine newer pointer state
with older heads and also needs write locks. Reading inside the read-only view
cannot use those locking functions. Capture immutable evidence references without
locks, close the metadata transaction, then replay exactly those references.
Counting a ghost twice breaks conservation; ignoring unavailable evidence hides
uncertainty. The conservative error is an unavailable registered result.
This adds one bounded metadata read and complete pair/ghost replay per pending
request, plus transient bounded evidence buffers. No whole-query latency promise,
new cache, aggregate speedup, dependency or target-host capacity claim. The trusted
owner can bypass table invariants; this does not authenticate an untrusted owner
or invent stock outside the current committed owner model.
## Qualification and remaining scope
Test raw/population prepare/stage/abort/commit, unchanged census stock, corrupt or
unavailable source capsules/ghosts, malformed pointers, bounds, expired authority,
and capture interleavings with settlement/new preparation. Run full persistence,
backup/DR, migration/privilege checks, sanitizers, analysis and default CTest.
Prior migrations and biological goldens remain unchanged.
This reconciles the existing pending migration evidence with registered owner
cuts. Cross-domain clone ancestry, other viable-store coverage, accepted durable
global reconciliation/freshness, coupled ecology and actual days remain open.