Files
aevolution/docs/adr/0154-registered-world-census-coverage.md
T
dingo 709dfb9557
Foundation / checks (ecs) (push) Successful in 2m23s
Foundation / checks (deploy) (push) Successful in 4m10s
Foundation / checks (network) (push) Successful in 21m32s
Foundation / checks (client) (push) Successful in 22m14s
Foundation / checks (tsan) (push) Successful in 24m30s
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 41m43s
Foundation / checks (postgres) (push) Canceled after 41m39s
M12.7: bind census evidence to database history domains
2026-10-18 20:33:16 -04:00

74 lines
4.3 KiB
Markdown

# ADR-0154: Registered-world coverage for cellular census snapshots
## Status
Accepted for scoped M12.7a, 2026-10-18. Implements database-registered regional
coverage under ADR-0133/0153, not terminal extinction or external branch identity.
## Context and decision
A consistent snapshot of a caller-declared list can still omit an owner. The
existing durable `region_leases` registry is the source of region identity and
frame for all supported provisioning paths. Duplicating it in a separate census
catalog would create another enrollment truth and a failure window.
Schema 50 adds a least-privilege read function listing registered regions of one
world, ordered by region ID, with frame IDs. Read from the registry itself, without
joining/filtering on heads, profile, active holder, expiry, activity or living count.
A missing checkpoint or unsupported region must prevent evidence completion,
not disappear from the required list. Return at most 65 rows: the 65th detects
overflow of the existing 64-region query bound. This is not a selected world size.
No new table/index, registration write or biological codec/rule.
Add `load_registered_cellular_census_snapshot`. In ADR-0153's owned short read-only
repeatable-read transaction, read this registry before selecting any heads. Require
an exact match to the supplied region resources/grants, including frames. Empty
registry means unknown world coverage, not zero life. Over-limit worlds fail;
never truncate/paginate a subset and label it complete. Read every selected head
in the same database snapshot, close the metadata transaction, then use unchanged
exact-cut replay and scoped census validation. Return registry evidence alongside
the exact cuts and census. Existing caller-declared snapshots keep their semantics.
Concurrent enrollment after the registry read belongs to a later snapshot. The
current result covers the registered set as of its captured database view, not
the latest state at return. Uncommitted enrollment is not included. A registered
row without a recoverable head fails the whole result. No fallback or zero filling.
## Alternatives, benefits, costs and risks
Trusting a supplied list cannot prove coverage. Listing only checkpoint-bearing,
cellular, active or unexpired regions hides unavailable or unsupported owners.
A duplicate mutable catalog can disagree with the authority registry. Read the
existing durable registry through its `(world_id, region_id)` primary-key prefix;
the 65-row limit bounds listing work and detects oversized sets explicitly.
The new security-definer read function exposes only region/frame metadata to the
existing trusted runtime group. Fixed search path, PUBLIC revocation and the full
runtime privilege audit remain mandatory. It grants no table access, provisioning,
new client permission or cross-world biological authority. Old schemas fail the
new query instead of falling back to caller-declared coverage.
## Consequences and qualification
Test exact sets, omitted/extra/duplicate resources, unknown worlds, wrong frames,
expired/released holders, missing heads, unsupported profiles and 64/65 bounds.
Race committed and uncommitted enrollment with snapshot capture; current cuts
must retain their selected catalog and later reads must see new enrollment.
Repeat real raw/cohort atomic migration races under registered coverage. Retain
failure cleanup, TLS faults, object verification and no-partial-result behavior.
Run migration/no-op/checksum/permissions, full private persistence regression,
sanitizers, Clang analysis/format and default-build checks. Never alter prior
migration bytes or biological goldens.
This covers registered regions in one connected database view. A rewind can reuse
the world ID; external branch identity is still missing. Outside/unsupported stores,
viable reserves, durable accepted reconciliation records and global freshness remain
M12.7 work. No terminal-extinction outcome, client endpoint, live database,
deployment or World0 action.
Schema-51 follow-up: [ADR-0155](0155-database-history-domain.md) adds a database
history domain to registered results in the same metadata view and forks supported
restores with parent/exact-cut provenance. Cross-domain clone provenance and the
other reconciliation limits above remain open; registered coverage alone still
does not authorize terminal extinction.