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

4.3 KiB

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 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.