4.4 KiB
ADR-0151: Census history from retained biological commits
Status
Accepted for scoped M12.6b implementation, 2026-10-18. This selects the existing append-only biological commit journal as the durable source for regional census history. No new SQL schema, biological format/rule or global extinction policy.
Context and decision
ADR-0150's census is a detached observation. Publishing an independent mutable summary after the biological transaction would create a second-write failure window and a second demographic truth. Every accepted biological publication already retains its exact manifest and complete payload in the immutable regional journal, atomically with its head. Paired migration records both endpoints in one transaction; uncommitted uploads and destination ghosts are not journal entries.
Use those committed cuts as canonical history events. Derive census projections on read from their verified payloads and existing semantic replay evidence, rather than storing duplicate census rows. A commit remains the event identity and its digest binds the complete census source. There is no extra post-commit write, backfill that invents observations, or new database write per simulation tick.
Add explicit historical raw/population recovery entry points that load an exact journal sequence and run the same manifest/build, strong object digest, complete restore, batch/no-tick/paired replay and outcome checks as current-head recovery. Historical recovery is read-only; it never changes the selected head, resumes an older owner or grants authority. Existing hosts continue to recover only the head. Replay validates each selected cut's complete batch/no-tick operation from retained predecessor checkpoints; it does not re-execute the entire world from genesis. Evidence loaders retain their current regional-lease requirements; reading a historical checkpoint is not proof of current ownership or world completeness.
Add bounded forward census pages, at most eight commits, pinned to a caller's exact regional watermark (frame, sequence, commit ID, manifest digest and tick). Validate that watermark against the immutable journal before and after reading. Append-only head advancement cannot move the requested upper cut. Advance by sequence, not tick: no-tick profile/format/migration commits remain distinct. Every returned entry retains its exact committed manifest and detached census. Require an idle connection at entry; reject all caller-owned transactions so a publishing connection cannot present its own uncommitted writes as durable cuts. The libpq adapter exposes read-only transaction status for this guard. Diagnostic historical recovery retains the existing caller-owned transaction semantics. Missing, unsupported, corrupt, unreplayable or foreign evidence fails the entire page; never skip a cut or return a zero census for unavailable history.
All point lookups use the existing unique regional sequence index. Payload/state work is one cut at a time, with at most eight bounded census projections retained. Timeouts retain existing per-I/O semantics, not a page-wide service latency promise. This is a backend read primitive, not a new endpoint or permission to expose it directly to clients.
Alternatives, costs and qualification
A separate mutable census table can disagree with the immutable biological source. Adding summary bytes to every publisher would version the same redundant truth through genesis, ordinary batches, profile/version transitions and paired commits. Retained exact checkpoints already provide atomic durable history, at the cost of object reads and semantic replay on query. No performance/capacity claim follows; a later cache/index must be derivable and preserve these evidence checks.
Require stable pagination after new publication, sequence-zero and no-tick cuts, raw/cohort restoration, historical migration ownership, exact retries without extra events, current lease replacement, missing/corrupt/false replay evidence, wrong cut/region/frame/build, bounded requests and unchanged heads/stock. Use private PostgreSQL, sanitizer, analysis and complete persistence regression.
This primitive is scoped to the connected database's regional history/frame. Its watermark is not a complete world watermark or an external recovery-branch identity. Cross-database/clone/rewind reconciliation, world region-set coverage, client presentation, actual multi-day ecology and terminal extinction remain M12.6/12.7 and later gates. No live database, World0 or deployment action.