Files
aevolution/docs/adr/0153-consistent-cellular-census-snapshots.md
T
dingo 7631f9d2e2
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 2m20s
Foundation / checks (network) (push) Successful in 21m3s
Foundation / checks (client) (push) Successful in 22m14s
Foundation / checks (tsan) (push) Successful in 24m52s
Foundation / checks (postgres) (push) Failing after 36m19s
Foundation / checks (checks) (push) Successful in 1h10m25s
Foundation / postgres-tools (push) Skipped
Foundation / server-image (push) Skipped
Foundation / image (push) Skipped
M12.6: capture consistent regional census snapshots
2026-10-18 15:56:58 -04:00

67 lines
3.8 KiB
Markdown

# ADR-0153: Consistent database cuts for scoped cellular census queries
## Status
Accepted for M12.6d, 2026-10-18. Backend read adapter under ADR-0151/0152;
no durable world catalog, external branch identity or extinction acceptance.
## Context and decision
Equal-tick regional observations can straddle an atomic migration. A source-after
and destination-before selection can omit stock without duplicating an organism.
The scoped portable query cannot detect that omission from detached totals alone.
Capture the current committed heads of 1..64 declared regions in one explicitly
owned PostgreSQL `REPEATABLE READ READ ONLY` transaction on an idle connection.
Requests are nonzero, distinct, ascending region IDs in one world, with object
stores and grants for the existing replay readers. Keep exact head/manifest pairs,
then commit the short metadata transaction before reading biological objects.
An atomic migration committed between head reads is either visible at both
endpoints or neither when both are in the declared set.
After capture, use ADR-0151's existing exact-cut history reader for each selected
head. Verify the returned head and manifest still match the captured cut. Complete
semantic replay, object hashes and fenced evidence checks remain mandatory; no
cached census or older-head fallback. Combine observations through ADR-0152's
coverage/boundary/genome/resident checks. Different head ticks fail rather than
advancing biology or silently selecting an older common tick. Return exact cuts
alongside the scoped census only after every step succeeds.
The adapter refuses all caller-owned transactions, including read-only ones.
It rolls back failed metadata capture; failed completion/cleanup closes the
connection. An exception during capture also closes the connection immediately,
releasing server resources when disconnect is observed. Add an explicit noexcept
disconnect method to the libpq owner for this cleanup. No automatic retry.
Per-I/O deadlines retain existing semantics, not a whole-query latency guarantee.
## Alternatives, benefits, costs and risks
Independent head reads can mix the sides of a paired publication. Holding one
transaction through full recovery is unnecessarily long, and existing fenced
evidence functions take lease row locks that a read-only transaction forbids.
Short read-only metadata capture plus immutable replay avoids that coupling.
Ordinary replay still briefly takes existing per-call lease locks; this does not
eliminate all contention or establish a deployment capacity claim.
Capture uses indexed regional head lookups. Work and retained observations remain
bounded by 64 regions; full replay/object cost is inherited from ADR-0151. A long
metadata snapshot can retain old database versions until completion. No new SQL
objects, cache/index, durable writes, biological rule/codec or dependency.
## Consequences and qualification
Require an actual paired migration on an independent connection between the first
and second head reads: both captured cuts must remain before the pair while a
later snapshot sees both after it. Recover the earlier cuts after publication,
compare exact census stock, and repeat for raw/cohort histories. Missing regions,
stale/missing/corrupt replay evidence, mismatched boundaries, invalid/over-bound
requests and caller-owned transactions must return no partial census. Confirm
transaction cleanup/connection closure, unchanged heads and no object writes.
This is one connected database's consistent committed cut for a caller-declared
region set. It neither proves that the list includes every world owner nor
reconciles branches, outside transfers, dormant/reserve viability or global
freshness. Current grants support recovery, not new observation authority. No
terminal-extinction outcome or public client permission follows. Durable
world/branch coverage and complete M12.7 reconciliation remain open.