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
93 lines
5.6 KiB
Markdown
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.
|