Complete M7.9a region clones and retained-history audit
Clone a verified committed head into an isolated world and database (ADR-0067): world re-identification with a proven byte round trip, a schema v7 clone genesis naming the source commit and digest with digested inherited outcomes, a read-only source session, an owner-only atomic target transaction and the evo-world-clone tool. audit_region_history re-verifies every retained link. Real-process tests cover trajectory equality after the cut, source isolation, killed clones and retention. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -584,3 +584,12 @@ M7.8 implemented and locally qualified (2026-09-28), under ADR-0066.
|
||||
- The `server-runtime` image is non-root with no secrets; a CI smoke job and a
|
||||
Kubernetes example are included.
|
||||
Next: M7.9 clone, migrate and qualify durability.
|
||||
|
||||
M7.9a implemented and locally qualified (2026-09-29), under ADR-0067:
|
||||
- a verified committed head is cloned into another world and database, as a
|
||||
re-identified clone genesis that names its source cut;
|
||||
- outcomes and ancestry are inherited;
|
||||
- the source session is read-only, and clone failures are atomic;
|
||||
- a full-chain retention audit is added.
|
||||
Next: M7.9b, covering the upgrade barrier and old-writer fencing, migration
|
||||
failure while serving, and measured recovery and batching latency.
|
||||
|
||||
@@ -901,3 +901,30 @@ Linux ran 59/59 in four configurations; the PostgreSQL suites passed in three.
|
||||
|
||||
Docker itself was not run locally; an emulated image layout was checked instead.
|
||||
Next: M7.9.
|
||||
|
||||
## M7.9a region clones and retained history (2026-09-29)
|
||||
|
||||
ADR-0067 adds a consistent clone into an isolated world:
|
||||
- **Re-identification:** `rebind_world` changes only the recorded world, and the
|
||||
byte round trip is proven.
|
||||
- **Schema v7 clone genesis:** it starts at the source tick, names the source
|
||||
commit and digest, and digests the inherited outcomes.
|
||||
- **`evo-world-clone clone`:** it reads the source read-only, requires a separate
|
||||
database and user, and writes the target in one owner transaction.
|
||||
|
||||
`audit_region_history` (also `evo-world-clone audit`) re-verifies every retained
|
||||
link.
|
||||
|
||||
Real processes showed:
|
||||
- after re-identification, the clone and its source followed a byte-identical
|
||||
trajectory;
|
||||
- the clone cannot write its source;
|
||||
- a killed clone left the source untouched and the target not ready;
|
||||
- a missing historical trace is detected even when head recovery succeeds.
|
||||
|
||||
Five mutations were caught. Windows ran 59/59; Linux ran 59/59 in four
|
||||
configurations; the PostgreSQL suites passed in three.
|
||||
|
||||
Next: M7.9b, covering the upgrade barrier and old-writer fencing, schema
|
||||
migration failure while a host is serving, and measured recovery and batching
|
||||
latency.
|
||||
|
||||
@@ -0,0 +1,111 @@
|
||||
# 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_heads` constraint becomes "sequence 0 or tick > 0".
|
||||
- `region_origins` holds one immutable row per clone region.
|
||||
- The parser accepts clone genesis. `provision_region_checkpoint` refuses origins
|
||||
and clone worlds.
|
||||
- The owner-only `provision_region_clone` enforces:
|
||||
- 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).**
|
||||
1. Refuse a zero ID or the source world.
|
||||
2. Switch the source session to read-only transactions, and confirm it.
|
||||
3. Recover the source head exactly as readiness does: manifest, payload, tail
|
||||
replay and outcomes.
|
||||
4. Re-identify the payload. Restore it as the target, rebind it back, and require
|
||||
the verified source bytes.
|
||||
5. Upload to the target store with verified read-back.
|
||||
6. 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.
|
||||
@@ -77,3 +77,4 @@ design. No unadopted candidate is a link dependency of the proof.
|
||||
- [ADR-0064: Region host](0064-region-host.md) - accepted for M7.6 single-owner host state machine, bounded admission, final-only-after-commit and evo-server process.
|
||||
- [ADR-0065: Recovery before readiness](0065-recovery-before-readiness.md) - accepted for M7.7 head tail replay verification, schema v6 commit lookup and real kill-boundary tests.
|
||||
- [ADR-0066: Operations endpoints](0066-operations-endpoints.md) - accepted for M7.8 liveness vs authority readiness, bounded metrics, dependency-free responder and the server image.
|
||||
- [ADR-0067: Region clones and retained-history audit](0067-region-clones.md) - accepted for M7.9a re-identified clone genesis naming its source cut, isolated clone databases and full-chain retention audit.
|
||||
|
||||
@@ -220,3 +220,18 @@ after commit but before acknowledgement, and after acknowledgement.
|
||||
A SIGSTOPped owner resumed fenced: it was not ready, refused admission and
|
||||
acknowledged nothing new. Corrupt payloads and missing traces quarantined with
|
||||
no fallback. Host loss and clone or migration remain M8 and M7.9.
|
||||
|
||||
M7.9a (ADR-0067) clones a verified committed head into another world and
|
||||
database:
|
||||
- The payload is re-identified, and the byte round trip is proven.
|
||||
- The clone genesis names the source commit and digest, and inherits the source's
|
||||
outcomes and ancestry.
|
||||
- The source session is read-only.
|
||||
- A clone killed before its target transaction left the source untouched and the
|
||||
target unprovisioned (it quarantined rather than serve), and a retry completed.
|
||||
- The same inputs from the cut reproduced the source trajectory exactly.
|
||||
|
||||
`audit_region_history` re-verifies every retained link across owners and kills.
|
||||
It names the exact link whose evidence is missing, even though head recovery
|
||||
still succeeds. Migration, fencing of old writers, and measured recovery and
|
||||
batching latency are still M7.9b.
|
||||
|
||||
@@ -2422,3 +2422,66 @@ Only clean-to-v1 and exact-v1 restart are supported migration paths at this gate
|
||||
the workflow YAML parses; `bash -n` passed for the smoke script.
|
||||
- Not executed: the container build and smoke, the Gitea job, cluster apply,
|
||||
Prometheus scraping, and TSan.
|
||||
|
||||
## M7.9a region clones and retained history - 2026-09-29
|
||||
|
||||
- Windows MSVC Release CTest passed 59/59. `lineage-region-contracts` now covers
|
||||
rebinding: only the new identity restores, continuation matches, and rebinding
|
||||
back is byte-exact. `region-checkpoint-contracts` covers the clone-genesis
|
||||
manifest rules.
|
||||
- WSL Linux `checks` set (GCC14 Debug and Release, clang19 analysis, clang19
|
||||
ASan/UBSan) passed CTest 59/59 each. The format check passed.
|
||||
- The PostgreSQL suites passed in GCC Release, clang-tidy analysis and ASan/UBSan.
|
||||
These runs used a second database, `evo_clone`, with its own runtime group and
|
||||
login. clang-tidy first flagged branch-clone in the tool's option parsing and
|
||||
optional access in the new tests; both were fixed, then the suites were rebuilt
|
||||
and rerun.
|
||||
- Harness additions:
|
||||
- A populated v6 database (a v2 genesis) upgrades in place to v7. The replaced
|
||||
head constraint is `region_heads_published_tick`, and the v7 parser reads the
|
||||
stored genesis.
|
||||
- Upgrade paths now end at 1..7.
|
||||
- Version and checksum drift checks now include v7.
|
||||
- Clone tests (real `evo-server` and `evo-world-clone` processes):
|
||||
- Trajectory: world 7 was run to tick 30, with a death at tick 20, then cloned
|
||||
to world 8 in `evo_clone`. The clone recovered under the clone runtime at
|
||||
tick 30, with the inherited death and retained ancestry, and the audit found
|
||||
one clone link naming the source cut. Both worlds then ran inputs 31..90; after
|
||||
rebinding the clone to world 7, the snapshots were byte-identical.
|
||||
- Isolation:
|
||||
- A same-world target was refused as `identity`.
|
||||
- A world that already holds an original region was refused (22023).
|
||||
- A forged origin was refused (22023).
|
||||
- The runtime role cannot provision a clone (42501).
|
||||
- A clone world refuses an original region.
|
||||
- Origins are immutable (EVL09).
|
||||
- The source session is read-only (25006, even through SECURITY DEFINER).
|
||||
- A clone lease publishing a successor to the source is fenced.
|
||||
- The clone runtime login cannot reach the source's functions (42501).
|
||||
- The source head and decisions were unchanged afterwards.
|
||||
- Failure: a SIGKILL before the target transaction left the source unchanged,
|
||||
the target unprovisioned with one orphan object, and a target server that
|
||||
quarantined (exit 4) without becoming ready. The tool refused a same
|
||||
database or same user (exit 2) and a same world (exit 4). The retry
|
||||
succeeded and reused the same object. A source with a damaged head payload
|
||||
was refused (exit 3), and its target stayed untouched.
|
||||
- Retention: an owner was SIGKILLed after acknowledging tick 100, and its
|
||||
successor continued to tick 200. The audit verified every link, and the tool
|
||||
printed the same result. A lower `max_commits` returned `bounds`. Removing the
|
||||
first link's trace made the audit report `tail` at sequence 1 while head
|
||||
recovery still succeeded; restoring the trace made the audit pass again.
|
||||
- Environmental profile: a clone inherited the tick-20 death. Moving that
|
||||
durable row to tick 19 (triggers disabled as break-glass) made recovery
|
||||
report `history` and the audit report `history` at sequence 0. Moving it back
|
||||
made recovery pass.
|
||||
- Mutations (each restored and rebuilt afterwards). Each was caught by its
|
||||
intended check:
|
||||
- dropping the isolated-world refusal;
|
||||
- dropping the origin check;
|
||||
- a read-write source session;
|
||||
- skipping the inherited-outcome digest;
|
||||
- skipping the audit's per-link tail verification.
|
||||
The first attempt at the inherited-outcome mutation did not compile, so its
|
||||
stale-binary run was discarded and the mutation was rerun.
|
||||
- Not executed: clones across separate PostgreSQL clusters or hosts, Docker, the
|
||||
Gitea CI, and cluster runs.
|
||||
|
||||
@@ -124,8 +124,29 @@ else. Upgrading a v3/v4 database that has published checkpoints (not just
|
||||
genesis) is refused with EVL10 and leaves it unchanged: re-provision those regions,
|
||||
or wait for an explicit legacy-history conversion.
|
||||
|
||||
There is no operator CLI for provisioning yet, and no real world has been
|
||||
provisioned. Migrating v2→v3 fails closed if any v2 head exists, because v2 heads
|
||||
Schema v7 (ADR-0067) adds clones:
|
||||
- `region_origins`, immutable (EVL09);
|
||||
- the owner-only `provision_region_clone`;
|
||||
- clone-genesis parsing, and a head constraint that allows sequence 0 at the
|
||||
cloned tick.
|
||||
The runtime function set is unchanged.
|
||||
|
||||
Clone with `evo-world-clone clone`:
|
||||
- Use a **separate target database** with its own runtime group and login, and
|
||||
migrate it with that group as `EVO_PG_RUNTIME_ROLE`.
|
||||
- Retain the source's build identity in the target before cloning.
|
||||
- The source connection is the source runtime login (read functions only). It is
|
||||
switched to read-only transactions.
|
||||
- The target connection is the target owner.
|
||||
- The tool refuses the same database or the same user on both sides.
|
||||
|
||||
A clone world never receives original regions, and an original world never
|
||||
receives clones. `evo-world-clone audit` verifies a region's whole retained
|
||||
history; it is read-only and needs only runtime read access. Never point a clone
|
||||
target at a production database or World0.
|
||||
|
||||
There is no operator CLI for provisioning original regions yet, and no real world
|
||||
has been provisioned. Migrating v2→v3 fails closed if any v2 head exists, because v2 heads
|
||||
have no payload.
|
||||
|
||||
## Host lease discipline
|
||||
|
||||
Reference in New Issue
Block a user