6.5 KiB
[Reviewed]
ADR-0067: Region clones and retained-history audit
Status
Accepted for M7.9a, 2026-09-29. It builds on ADR-0058 (durability contract), ADR-0061/0062/0063 (checkpoints, lineage, batches) and ADR-0065 (recovery). Region migration, sealing and durability qualification are M7.9b.
Context
M7.9 requires a consistent clone into an isolated world identity, retained durable history and a baseline-versus-restored trajectory. The named risks are a clone that shares production credentials and rules that change on restore. OPERATIONS.md says a clone gets isolated world and runtime identities while keeping source provenance. ADR-0044 already makes generated content depend on descriptors, not the world ID.
Every payload records its world ID in nested codecs: the envelope configuration, the transfer header, the field store and the terrain snapshot. Recovery restores it under the manifest's world. A clone into another world therefore has to re-identify the payload; copying bytes is not enough. Sequence 0 used to require tick 0, so a cut at tick N had no representation.
Decision
Re-identification (portable). EnvironmentalCommunity::rebind_world and
LineageRegion::rebind_world change only the recorded world ID and keep the
frame. That ID lives in the configuration and the field store; terrain snapshots
take it from the field store. The archive, binding, histories and every quantity
are identity-free, and no rule reads the world ID. Tests show that:
- only the new identity restores the rebound bytes;
- continuation reports match;
- rebinding back yields the original bytes exactly.
Clone genesis (manifest v2, schema v7). A clone is sequence 0 of the target region in another world.
- It starts at the source tick:
begin = end = source end tick. - Its predecessor fields name the source commit and the SHA-256 of its manifest.
- Its decision count and digest cover the inherited permanent outcomes. It has no trace, holder or epoch.
- Profile, versions, quantum, frame and build are inherited. A clone never converts versions.
A provisioned genesis is unchanged (tick 0, no origin, no outcomes), and manifest v1 cannot carry an origin. Earlier builds refuse clone manifests as malformed, so they fail closed. Every later link chains from the clone genesis, so the whole clone history transitively commits to the source cut.
Database (migration 0007).
- The
region_headsconstraint becomes "sequence 0 or tick > 0". region_originsholds one immutable row per clone region.- The parser accepts clone genesis.
provision_region_checkpointrefuses origins and clone worlds. - The owner-only
provision_region_cloneenforces:- the target world differs from the source world;
- a world is either original or a clone of exactly one source world;
- when the source is in the same database, the origin is exactly its committed link (sequence, commit, digest, tick, versions, quantum, profile);
- inherited outcomes match the manifest digest, with each actor dying at most once.
- It records the outcomes as sequence-0 decisions with no outbox rows: the source already delivered them, and a clone has no production integrations.
- The runtime role gains nothing.
Clone (clone_region, Linux).
- Refuse a zero ID or the source world.
- Switch the source session to read-only transactions, and confirm it.
- Recover the source head exactly as readiness does: manifest, payload, tail replay and outcomes.
- Re-identify the payload. Restore it as the target, rebind it back, and require the verified source bytes.
- Upload to the target store with verified read-back.
- Provision in one owner transaction, then compare the receipt.
A failure before step 6 leaves at most target orphans. The source is never written. A cut read without a lease ignores outcomes of links committed after the head was read; recovery applies the same rule.
Tool (evo-world-clone). Subcommands clone and audit. The source and
target need different databases and different users. The source user needs only
the runtime read functions. The target user is the target database's owner. An
optional full history audit runs first. The --crash-at before-transaction flag
is for tests only.
Retention audit (audit_region_history). Verifies every link from genesis to
the head:
- the digest, position and chain;
- the retained build;
- that the payload is present and restores;
- that the trace replays the predecessor's payload to exactly this link's bytes;
- that the outcomes are exactly those derived;
- that the head state agrees with all outcomes.
It is read-only, needs no lease, and is bounded by max_commits. Head recovery
alone does not prove retention; the audit does.
Consequences
- Tests covered clones between separate databases with separate runtime roles. The same-database path is checked by the database too.
- History is still never deleted. Garbage collection must later treat clone origins, heads and audit reachability as pins.
- Clone throughput and history-audit cost grow with payload size and chain length; M7.9b measures them.
- A clone of a clone is allowed; each origin names its immediate source.
Alternatives rejected
- Copying the whole source chain into the new world. Every manifest digest would change, so the copy would not be the source's history. Holders and epochs would also leak across authority domains.
- Keeping the source world ID and separating the durable namespace. That needs a new manifest field. Two worlds with one simulation identity also defeats isolation.
- Recording provenance only in a table. The chain would not commit to its origin, and cross-database clones could not verify it.
Amendment: serialized world classification (schema v9, 2026-09-29 review)
The rule "original, or a clone of exactly one source" was enforced by unlocked existence checks. Two concurrent clones of different sources into different regions of one world could therefore both commit (reproduced by review). Schema v9 fixes this:
- Both provisioning functions take a per-world advisory lock, keyed by a hash of the world ID, after the shared upgrade lock (ADR-0068 amendment).
- They then check the classification. Because the checks run after the lock wait, they see every committed provisioning of that world.
- Unrelated worlds provision in parallel. A hash collision only adds waiting.
Regression tests race different-source clones, and an original region against a clone, into one world, and expect exactly one to succeed. Same-source clones into different regions both succeed.