Files
aevolution/docs/adr/0155-database-history-domain.md
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

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.