Files
aevolution/migrations/0007_region_clones.sql
dingoandClaude Opus 5.5 703f67834f 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>
2026-09-29 06:47:45 -04:00

248 lines
13 KiB
PL/PgSQL

-- M7.9 region clones (ADR-0067). A clone is sequence 0 of a region in another,
-- isolated world: its genesis manifest names the source commit and manifest digest
-- (so every later link transitively commits to the source cut), starts at the source
-- tick and digests the inherited permanent outcomes. Only the owner provisions it;
-- the runtime role gains nothing. A world is either original or a clone of exactly
-- one source world, and origins are immutable.
-- Sequence 0 may now sit at the cloned tick; a published link still ends after 0.
DO $$
DECLARE
c name;
BEGIN
SELECT k.conname INTO c FROM pg_catalog.pg_constraint k
WHERE k.conrelid = 'evolution.region_heads'::regclass AND k.contype = 'c'
AND pg_catalog.pg_get_constraintdef(k.oid) LIKE '%end_tick%';
IF c IS NULL THEN
RAISE EXCEPTION 'region_heads tick constraint not found';
END IF;
EXECUTE pg_catalog.format('ALTER TABLE evolution.region_heads DROP CONSTRAINT %I', c);
END $$;
ALTER TABLE evolution.region_heads
ADD CONSTRAINT region_heads_published_tick CHECK (commit_sequence = 0 OR end_tick > 0);
CREATE TABLE evolution.region_origins (
world_id evolution.u64 NOT NULL,
region_id evolution.u64 NOT NULL,
source_world evolution.u64 NOT NULL,
source_region evolution.u64 NOT NULL,
source_sequence evolution.u64 NOT NULL,
source_commit uuid NOT NULL,
source_digest bytea NOT NULL CHECK (octet_length(source_digest) = 32),
source_tick evolution.u64 NOT NULL,
cloned_at timestamptz NOT NULL DEFAULT clock_timestamp(),
PRIMARY KEY (world_id, region_id),
FOREIGN KEY (world_id, region_id) REFERENCES evolution.region_leases,
CHECK (source_world <> world_id)
);
REVOKE ALL ON evolution.region_origins FROM PUBLIC;
CREATE TRIGGER region_origins_immutable BEFORE UPDATE OR DELETE ON evolution.region_origins
FOR EACH ROW EXECUTE FUNCTION evolution.refuse_history_rewrite();
CREATE TRIGGER region_origins_no_truncate BEFORE TRUNCATE ON evolution.region_origins
FOR EACH STATEMENT EXECUTE FUNCTION evolution.refuse_history_rewrite();
-- Mirrors decode_manifest + supported() in src/persistence/region_checkpoint.cpp.
-- Changed from v5 only in the sequence-0 rules: a clone genesis keeps its origin.
CREATE OR REPLACE FUNCTION evolution.parse_checkpoint_manifest(m bytea)
RETURNS evolution.checkpoint_manifest LANGUAGE plpgsql IMMUTABLE
SET search_path = pg_catalog, pg_temp AS $$
DECLARE
r evolution.checkpoint_manifest;
zero16 constant bytea := '\x00000000000000000000000000000000';
zero32 constant bytea := decode(repeat('00', 32), 'hex');
history numeric;
cap numeric;
BEGIN
IF m IS NULL OR octet_length(m) < 12 OR substring(m FROM 1 FOR 8) <> '\x4145564f52434d31' THEN
RAISE EXCEPTION 'malformed checkpoint manifest' USING ERRCODE = '22023';
END IF;
IF evolution.manifest_uint(m, 8, 4) <> 2 THEN
RAISE EXCEPTION 'unsupported checkpoint manifest' USING ERRCODE = 'EVL06';
END IF;
IF octet_length(m) <> 360 THEN
RAISE EXCEPTION 'malformed checkpoint manifest' USING ERRCODE = '22023';
END IF;
r.profile := evolution.manifest_uint(m, 12, 4);
history := evolution.manifest_uint(m, 232, 4);
IF NOT ((r.profile = 1 AND history = 0) OR (r.profile = 2 AND history = 1))
OR substring(m FROM 161 FOR 36) <> '\x020000000200000001000000010000000100000001000000010000000100000001000000'
OR evolution.manifest_uint(m, 228, 4) <> 0 OR evolution.manifest_uint(m, 236, 4) <> 1 THEN
RAISE EXCEPTION 'unsupported checkpoint manifest' USING ERRCODE = 'EVL06';
END IF;
-- Payload caps: 1 MiB envelope; 72 + 1 MiB + lineage archive cap (3219496) container.
cap := CASE r.profile WHEN 1 THEN 1048576 ELSE 4268144 END;
r.world_id := evolution.manifest_uint(m, 16, 8);
r.region_id := evolution.manifest_uint(m, 24, 8);
r.frame_id := evolution.manifest_uint(m, 32, 8);
r.commit_id := encode(substring(m FROM 41 FOR 16), 'hex')::uuid;
r.commit_sequence := evolution.manifest_uint(m, 56, 8);
r.predecessor_commit := encode(substring(m FROM 65 FOR 16), 'hex')::uuid;
r.predecessor_digest := substring(m FROM 81 FOR 32);
r.begin_tick := evolution.manifest_uint(m, 112, 8);
r.end_tick := evolution.manifest_uint(m, 120, 8);
r.holder := encode(substring(m FROM 129 FOR 16), 'hex')::uuid;
r.epoch := evolution.manifest_uint(m, 144, 8);
r.tick_microseconds := evolution.manifest_uint(m, 152, 8);
r.versions := substring(m FROM 161 FOR 36);
r.build_identity := substring(m FROM 197 FOR 32);
r.payload_bytes := evolution.manifest_uint(m, 240, 8);
r.payload_sha256 := substring(m FROM 249 FOR 32);
r.trace_bytes := evolution.manifest_uint(m, 280, 8);
r.trace_sha256 := substring(m FROM 289 FOR 32);
r.decision_count := evolution.manifest_uint(m, 320, 4);
r.decisions_sha256 := substring(m FROM 329 FOR 32);
IF r.world_id = 0 OR r.region_id = 0 OR r.frame_id = 0
OR substring(m FROM 41 FOR 16) = zero16 OR r.tick_microseconds = 0
OR r.build_identity = zero32 OR r.payload_bytes < 1 OR r.payload_bytes > cap
OR r.payload_sha256 = zero32 OR evolution.manifest_uint(m, 324, 4) <> 0 THEN
RAISE EXCEPTION 'malformed checkpoint manifest' USING ERRCODE = '22023';
END IF;
IF r.commit_sequence = 0 THEN
IF substring(m FROM 129 FOR 16) <> zero16 OR r.epoch <> 0 OR r.begin_tick <> r.end_tick
OR r.trace_bytes <> 0 OR r.trace_sha256 <> zero32 THEN
RAISE EXCEPTION 'malformed checkpoint manifest' USING ERRCODE = '22023';
END IF;
IF substring(m FROM 65 FOR 16) = zero16 AND r.predecessor_digest = zero32 THEN
-- Provisioned genesis: tick 0, no origin, no outcomes.
IF r.end_tick <> 0 OR r.decision_count <> 0 OR r.decisions_sha256 <> zero32 THEN
RAISE EXCEPTION 'malformed checkpoint manifest' USING ERRCODE = '22023';
END IF;
r.predecessor_commit := NULL;
ELSIF substring(m FROM 65 FOR 16) = zero16 OR r.predecessor_digest = zero32
OR r.predecessor_commit = r.commit_id OR r.decision_count > 8
OR (r.decision_count = 0) <> (r.decisions_sha256 = zero32) THEN
RAISE EXCEPTION 'malformed checkpoint manifest' USING ERRCODE = '22023';
END IF;
r.holder := NULL;
ELSIF substring(m FROM 65 FOR 16) = zero16 OR r.predecessor_commit = r.commit_id
OR r.predecessor_digest = zero32 OR substring(m FROM 129 FOR 16) = zero16
OR r.epoch = 0 OR r.end_tick <= r.begin_tick OR r.end_tick - r.begin_tick > 64
-- One 304-byte trace step per tick after a 96-byte header.
OR r.trace_bytes <> 96 + 304 * (r.end_tick - r.begin_tick) OR r.trace_sha256 = zero32
OR r.decision_count > 8 OR (r.decision_count = 0) <> (r.decisions_sha256 = zero32) THEN
RAISE EXCEPTION 'malformed checkpoint manifest' USING ERRCODE = '22023';
END IF;
RETURN r;
END $$;
-- Owner-only genesis of an original region; never in a clone world, never an origin.
CREATE OR REPLACE FUNCTION evolution.provision_region_checkpoint(p_manifest bytea)
RETURNS void LANGUAGE plpgsql SECURITY INVOKER SET search_path = pg_catalog, pg_temp AS $$
DECLARE
g evolution.checkpoint_manifest := evolution.parse_checkpoint_manifest(p_manifest);
d bytea := sha256(p_manifest);
BEGIN
IF g.commit_sequence <> 0 OR g.predecessor_commit IS NOT NULL THEN
RAISE EXCEPTION 'genesis manifest required' USING ERRCODE = '22023';
END IF;
IF EXISTS (SELECT 1 FROM evolution.region_origins o WHERE o.world_id = g.world_id) THEN
RAISE EXCEPTION 'world holds clones' USING ERRCODE = '22023';
END IF;
INSERT INTO evolution.region_leases(world_id, region_id, frame_id)
VALUES (g.world_id, g.region_id, g.frame_id);
INSERT INTO evolution.region_commits(world_id, region_id, commit_sequence, commit_id,
commit_digest, manifest, begin_tick, end_tick, published_epoch, tick_microseconds,
versions, build_identity, payload_bytes, payload_sha256)
VALUES (g.world_id, g.region_id, 0, g.commit_id, d, p_manifest, 0, 0, 0,
g.tick_microseconds, g.versions, g.build_identity, g.payload_bytes,
g.payload_sha256);
INSERT INTO evolution.region_heads(world_id, region_id, commit_sequence, commit_id, digest,
end_tick, published_epoch)
VALUES (g.world_id, g.region_id, 0, g.commit_id, d, 0, 0);
END $$;
-- Owner-only clone genesis. The source may live in another database; when it is
-- present here, the origin must be exactly its committed link. Inherited outcomes
-- are recorded as decisions of sequence 0 without outbox rows: the source already
-- delivered them, and a clone has no production integrations.
CREATE FUNCTION evolution.provision_region_clone(p_manifest bytea, p_source_world evolution.u64,
p_source_region evolution.u64, p_source_sequence evolution.u64, p_decisions bytea)
RETURNS void LANGUAGE plpgsql SECURITY INVOKER SET search_path = pg_catalog, pg_temp AS $$
DECLARE
g evolution.checkpoint_manifest := evolution.parse_checkpoint_manifest(p_manifest);
d bytea := sha256(p_manifest);
tick numeric;
actor numeric;
outcome numeric;
organism numeric;
last_tick numeric := -1;
last_actor numeric := -1;
actors integer[] := '{}';
BEGIN
IF g.commit_sequence <> 0 OR g.predecessor_commit IS NULL THEN
RAISE EXCEPTION 'clone genesis manifest required' USING ERRCODE = '22023';
END IF;
IF p_source_world IS NULL OR p_source_region IS NULL OR p_source_sequence IS NULL
OR p_decisions IS NULL THEN
RAISE EXCEPTION 'invalid clone request' USING ERRCODE = '22023';
END IF;
IF p_source_world = g.world_id THEN
RAISE EXCEPTION 'clone requires an isolated world' USING ERRCODE = '22023';
END IF;
IF EXISTS (SELECT 1 FROM evolution.region_leases l
WHERE l.world_id = g.world_id
AND NOT EXISTS (SELECT 1 FROM evolution.region_origins o
WHERE o.world_id = l.world_id AND o.region_id = l.region_id))
OR EXISTS (SELECT 1 FROM evolution.region_origins o
WHERE o.world_id = g.world_id AND o.source_world <> p_source_world) THEN
RAISE EXCEPTION 'target world is not an isolated clone of this source' USING ERRCODE = '22023';
END IF;
IF EXISTS (SELECT 1 FROM evolution.region_leases l
WHERE l.world_id = p_source_world AND l.region_id = p_source_region)
AND NOT EXISTS (SELECT 1 FROM evolution.region_commits c
WHERE c.world_id = p_source_world AND c.region_id = p_source_region
AND c.commit_sequence = p_source_sequence
AND c.commit_id = g.predecessor_commit
AND c.commit_digest = g.predecessor_digest AND c.end_tick = g.end_tick
AND c.versions = g.versions
AND c.tick_microseconds = g.tick_microseconds
AND substring(c.manifest FROM 13 FOR 4) = substring(p_manifest FROM 13 FOR 4)) THEN
RAISE EXCEPTION 'origin is not the committed source link' USING ERRCODE = '22023';
END IF;
IF octet_length(p_decisions) <> 24 * g.decision_count
OR (g.decision_count > 0 AND sha256(p_decisions) <> g.decisions_sha256) THEN
RAISE EXCEPTION 'inherited outcomes do not match manifest' USING ERRCODE = '22023';
END IF;
FOR i IN 0 .. g.decision_count - 1 LOOP
tick := evolution.manifest_uint(p_decisions, 24 * i, 8);
actor := evolution.manifest_uint(p_decisions, 24 * i + 8, 4);
outcome := evolution.manifest_uint(p_decisions, 24 * i + 12, 4);
organism := evolution.manifest_uint(p_decisions, 24 * i + 16, 8);
IF outcome <> 1 OR actor NOT IN (0, 1) OR tick < 1 OR tick > g.end_tick
OR tick < last_tick OR (tick = last_tick AND actor <= last_actor)
OR actor::integer = ANY (actors) OR (g.profile = 1) <> (organism = 0) THEN
RAISE EXCEPTION 'invalid inherited outcome' USING ERRCODE = '22023';
END IF;
actors := actors || actor::integer;
last_tick := tick;
last_actor := actor;
END LOOP;
INSERT INTO evolution.region_leases(world_id, region_id, frame_id)
VALUES (g.world_id, g.region_id, g.frame_id);
INSERT INTO evolution.region_origins(world_id, region_id, source_world, source_region,
source_sequence, source_commit, source_digest, source_tick)
VALUES (g.world_id, g.region_id, p_source_world, p_source_region, p_source_sequence,
g.predecessor_commit, g.predecessor_digest, g.end_tick);
INSERT INTO evolution.region_commits(world_id, region_id, commit_sequence, commit_id,
commit_digest, manifest, begin_tick, end_tick, published_epoch, tick_microseconds,
versions, build_identity, payload_bytes, payload_sha256, decisions)
VALUES (g.world_id, g.region_id, 0, g.commit_id, d, p_manifest, g.end_tick, g.end_tick, 0,
g.tick_microseconds, g.versions, g.build_identity, g.payload_bytes,
g.payload_sha256, p_decisions);
INSERT INTO evolution.region_heads(world_id, region_id, commit_sequence, commit_id, digest,
end_tick, published_epoch)
VALUES (g.world_id, g.region_id, 0, g.commit_id, d, g.end_tick, 0);
FOR i IN 0 .. g.decision_count - 1 LOOP
INSERT INTO evolution.region_decisions(world_id, region_id, outcome, actor, tick, organism,
commit_sequence)
VALUES (g.world_id, g.region_id, 1, evolution.manifest_uint(p_decisions, 24 * i + 8, 4),
evolution.manifest_uint(p_decisions, 24 * i, 8),
evolution.manifest_uint(p_decisions, 24 * i + 16, 8), 0);
END LOOP;
END $$;
REVOKE ALL ON FUNCTION
evolution.provision_region_clone(bytea, evolution.u64, evolution.u64, evolution.u64, bytea)
FROM PUBLIC;
INSERT INTO evolution.schema_migrations(version, sha256) VALUES (7, :'migration_sha_7');