5.6 KiB
ADR-0155: Database history domains for census and restore evidence
Status
Accepted for scoped M12.7b, 2026-10-18. Extends ADR-0133/0153/0154 and the supported ADR-0074/0075 restore workflow. This is an evidence namespace, not a new biological identity, codec, simulation version or terminal-extinction rule.
Context and decision
World IDs and exact immutable commits can be reused by a database restored from a backup. Independently initialized databases can also use the same world IDs. Neither a connection address nor an object path establishes evolutionary history.
Schema 51 adopts one random, nonzero UUID history domain per database, using
PostgreSQL's built-in UUID generator. External evidence identifies a world by
(history_domain, world_id). Adoption means this database's retained history as
observed at migration; it does not reconstruct an unknown earlier namespace.
Unchanged migrations preserve the domain. Different worlds remain distinct within
the domain. No per-tick writes, payload changes, extension or new dependency.
Keep owner-controlled history_domains events, one current_history_domain row,
and history_domain_cuts for restore provenance. The trusted runtime receives only
the fixed-search-path security-definer load_history_domain_v1() read function;
neither table access nor the ability to fork. The migration privilege audit includes
both the new required read grant and denial of the owner-only function.
Registered cellular snapshots capture the domain before registry/head reads in the same short read-only repeatable-read transaction. Return it with registry, exact cuts and fully replayed census. Missing/zero/malformed context fails the whole result; a legacy schema fails rather than inferring a domain. Existing caller-declared snapshots and low-level diagnostic history queries retain their local semantics; they do not acquire an external-history guarantee implicitly. Concurrent context changes belong to a later metadata view. Context identifies captured evidence, not current authority or a freshness guarantee at return.
Supported restores and legacy backups
For either isolated or explicitly authorized dev/stage in-place restore, the
existing install transaction first restores the dump, retires all builds and
clears holders. Before committing that still-quarantined install, call the new
owner-only fork_restored_history_v1(restore_claim_uuid) when present. It locks
the singleton domain row, refuses any admitted build or held lease, creates a
fresh domain whose parent is the restored domain, retains the request, and copies
all restored heads' world/region/frame/sequence/commit/digest/tick as fork cuts
before switching the current domain. Rollback removes the whole fork. Same-request
retries return the same current domain without duplicating records; a request from
an older fork refuses instead of switching backwards. Lost install receipts keep
the existing restore-claim resolution. Biological heads, ancestry and retained
objects stay byte-identical. Readmission still waits for head/history verification
and, in-place, the full runtime privilege audit.
A backup predating schema 51 has no source domain. Its restore skips the absent
function; later migration adopts a fresh domain with unknown original context.
Do not fabricate a parent or exact external branch ancestry. New-schema backups
retain the event/cut tables because they dump the entire evolution schema.
Backup-of-restore forks preserve their known namespace ancestry and exact fork
cuts; they do not rewrite biological clone origins or old payloads.
The operator is trusted and the replacement database must remain isolated during
installation/verification. Owner-only SQL is not a new public online branch API.
Arbitrary direct pg_restore, copying a running database, privileged edits, or
readmitting builds outside the supported workflow can copy/forge a domain. No
database UUID can detect such a bypass. This contract does not secure an
untrusted owner or change fencing, backup durability, deployment or World0 gates.
Alternatives, benefits, costs and risks
Per-world enrollment tables would duplicate the authority registry and complicate legacy adoption. Host/database names are mutable routing, and manifest digests can survive a rewind. Embedding new domains in all biological codecs would change deterministic bytes without changing biology. A database namespace keeps those contracts intact and makes restore provenance explicit at metadata cost proportional to the restored regional head count, once per restore.
Random UUID uniqueness is probabilistic, using the existing supported PostgreSQL runtime. Trusted workflows must rotate consistently; no claim is made for a copied database outside those workflows. Initial adoption cannot recover missing external history. Retention/GC must preserve these records; no deletion feature is added.
Qualification and remaining scope
Test no-op adoption, quarantine refusal, rollback, exact cuts, idempotent and stale requests, runtime privileges, missing context, concurrent snapshot capture, isolated restore and in-place rewind. Run full persistence/backup/DR/migration checks, sanitizers, analysis/format and the default build. No biological golden changes.
Cross-domain clone-origin provenance is still incomplete: ADR-0067 commits the source biological cut but does not encode its external history domain. A domain alone cannot supply that missing ancestry. Durable accepted reconciliation must later bind domain, exact cuts, registered coverage, other viable/in-flight stores and acceptance freshness; no terminal extinction or complete M12 gate is claimed.