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

93 lines
5.6 KiB
Markdown

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