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:
dingo
2026-09-29 06:47:45 -04:00
co-authored by Claude Opus 5.5
parent 7aec68db8e
commit 703f67834f
28 changed files with 2206 additions and 266 deletions
+9
View File
@@ -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.
+27
View File
@@ -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.
+111
View File
@@ -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.
+1
View File
@@ -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.
+15
View File
@@ -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.
+63
View File
@@ -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.
+23 -2
View File
@@ -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