Files
aevolution/migrations/0003_region_checkpoints.sql
T
dingoandClaude Opus 5.5 5d4f59f901 Implement M7.4a checkpoint publication and verified recovery
ADR-0061 publishes environmental-v1 full checkpoints. Manifest v1 is a
fixed 280-byte record (identity, chain, lease, versions, build, zero
RNG/history declarations, durability policy, payload length/SHA-256)
that PostgreSQL parses and digests itself. Schema v3 adds region_commits
with a digest CHECK and a composite head FK, owner-managed retained
builds, fenced publish/load functions and owner-only genesis; it drops
the bare v2 head kernel and fails closed while v2 heads exist.

Linux evo::region_store adds OpenSSL SHA-256, an immutable
content-addressed filesystem object store (temp+fsync+link, no
overwrite/delete, O_NOFOLLOW exact-length verified reads), and
publication (validate -> upload -> read back -> fenced transaction ->
receipt check) and recovery (re-digest, allowlist, verify, full restore).
Portable evo::region_checkpoint holds the codec and payload validation.

Validated: Windows CTest 56/56; WSL Release, clang-tidy and ASan/UBSan
private-PostgreSQL suites; four SQL and one host mutation each caught.
M7.4 stays open for 7.4b (lineage archive codec and history binding).
No Docker/Gitea CI, remote store, process kill or deployment.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-28 15:25:27 -04:00

237 lines
12 KiB
PL/PgSQL

-- M7.4 committed checkpoint publication (ADR-0061). The database parses the
-- canonical manifest v1 bytes itself, so no separately supplied field can disagree
-- with the digested record. Payload bytes live in the object store; the database
-- records their length and SHA-256 and never parses them.
DO $$
BEGIN
-- Schema v2 heads carry no payload binding and cannot be migrated into a chain.
IF EXISTS (SELECT 1 FROM evolution.region_heads) THEN
RAISE EXCEPTION 'v2 region heads have no checkpoint payload; re-provision under v3';
END IF;
END $$;
DROP FUNCTION evolution.advance_region_head(evolution.u64, evolution.u64, uuid, evolution.u64,
evolution.u64, uuid, bytea, uuid, bytea, evolution.u64);
DROP FUNCTION evolution.provision_region(evolution.u64, evolution.u64, evolution.u64, uuid, bytea);
-- Immutable build artifacts retained for recovery; owner-managed on promotion.
CREATE TABLE evolution.retained_builds (
build_identity bytea PRIMARY KEY CHECK (octet_length(build_identity) = 32),
retained_at timestamptz NOT NULL DEFAULT clock_timestamp()
);
CREATE TABLE evolution.region_commits (
world_id evolution.u64 NOT NULL,
region_id evolution.u64 NOT NULL,
commit_sequence evolution.u64 NOT NULL,
commit_id uuid NOT NULL UNIQUE,
commit_digest bytea NOT NULL CHECK (octet_length(commit_digest) = 32),
manifest bytea NOT NULL CHECK (octet_length(manifest) = 280),
begin_tick evolution.u64 NOT NULL,
end_tick evolution.u64 NOT NULL,
published_epoch evolution.u64 NOT NULL,
tick_microseconds evolution.u64 NOT NULL,
versions bytea NOT NULL CHECK (octet_length(versions) = 36),
build_identity bytea NOT NULL REFERENCES evolution.retained_builds,
payload_bytes evolution.u64 NOT NULL,
payload_sha256 bytea NOT NULL CHECK (octet_length(payload_sha256) = 32),
committed_at timestamptz NOT NULL DEFAULT clock_timestamp(),
PRIMARY KEY (world_id, region_id, commit_sequence),
UNIQUE (world_id, region_id, commit_sequence, commit_id, commit_digest),
FOREIGN KEY (world_id, region_id) REFERENCES evolution.region_leases,
CONSTRAINT region_commits_manifest_digest CHECK (commit_digest = sha256(manifest))
);
-- The head can only name an existing commit with the same identity and digest.
ALTER TABLE evolution.region_heads
ADD FOREIGN KEY (world_id, region_id, commit_sequence, commit_id, digest)
REFERENCES evolution.region_commits (world_id, region_id, commit_sequence, commit_id,
commit_digest);
REVOKE ALL ON evolution.retained_builds, evolution.region_commits FROM PUBLIC;
CREATE TYPE evolution.checkpoint_manifest AS (
world_id evolution.u64, region_id evolution.u64, frame_id evolution.u64, commit_id uuid,
commit_sequence evolution.u64, predecessor_commit uuid, predecessor_digest bytea,
begin_tick evolution.u64, end_tick evolution.u64, holder uuid, epoch evolution.u64,
tick_microseconds evolution.u64, versions bytea, build_identity bytea,
payload_bytes evolution.u64, payload_sha256 bytea
);
CREATE FUNCTION evolution.manifest_uint(m bytea, off integer, width integer)
RETURNS numeric LANGUAGE plpgsql IMMUTABLE STRICT SET search_path = pg_catalog, pg_temp AS $$
DECLARE
v numeric := 0;
BEGIN
FOR i IN REVERSE width - 1 .. 0 LOOP
v := v * 256 + get_byte(m, off + i);
END LOOP;
RETURN v;
END $$;
-- Mirrors decode_manifest + supported() in src/persistence/region_checkpoint.cpp.
-- 22023: malformed; EVL06: parsable but unsupported by this schema.
CREATE 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');
BEGIN
IF m IS NULL OR octet_length(m) <> 280 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) <> 1 OR evolution.manifest_uint(m, 12, 4) <> 1
OR substring(m FROM 161 FOR 36) <> '\x020000000200000001000000010000000100000001000000010000000100000001000000'
OR evolution.manifest_uint(m, 228, 4) <> 0 OR evolution.manifest_uint(m, 232, 4) <> 0
OR evolution.manifest_uint(m, 236, 4) <> 1 THEN
RAISE EXCEPTION 'unsupported checkpoint manifest' USING ERRCODE = 'EVL06';
END IF;
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);
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 NOT BETWEEN 1 AND 1048576
OR r.payload_sha256 = zero32 THEN
RAISE EXCEPTION 'malformed checkpoint manifest' USING ERRCODE = '22023';
END IF;
IF r.commit_sequence = 0 THEN
IF substring(m FROM 65 FOR 16) <> zero16 OR r.predecessor_digest <> zero32
OR r.begin_tick <> 0 OR r.end_tick <> 0 OR substring(m FROM 129 FOR 16) <> zero16
OR r.epoch <> 0 THEN
RAISE EXCEPTION 'malformed checkpoint manifest' USING ERRCODE = '22023';
END IF;
r.predecessor_commit := NULL;
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 THEN
RAISE EXCEPTION 'malformed checkpoint manifest' USING ERRCODE = '22023';
END IF;
RETURN r;
END $$;
-- Owner-only: genesis is an explicit authorized opening payload, never recovery.
CREATE 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 THEN
RAISE EXCEPTION 'genesis manifest required' 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 $$;
-- Fenced publication: lease row lock and database-time check, then the head lock;
-- the manifest must be the exact successor of the committed head. One statement:
-- a rejection inserts nothing. A verified orphan payload stays unreferenced.
CREATE FUNCTION evolution.publish_region_checkpoint(p_manifest bytea)
RETURNS TABLE (region_frame evolution.u64, head_sequence evolution.u64, head_commit uuid,
head_digest text, head_tick evolution.u64)
LANGUAGE plpgsql SECURITY DEFINER SET search_path = pg_catalog, pg_temp AS $$
DECLARE
c evolution.checkpoint_manifest := evolution.parse_checkpoint_manifest(p_manifest);
h evolution.region_heads%ROWTYPE;
p evolution.region_commits%ROWTYPE;
frame evolution.u64;
d bytea := sha256(p_manifest);
BEGIN
IF c.commit_sequence = 0 THEN
RAISE EXCEPTION 'genesis is provisioned, not published' USING ERRCODE = '22023';
END IF;
PERFORM evolution.check_region_lease(c.world_id, c.region_id, c.holder, c.epoch);
SELECT * INTO h FROM evolution.region_heads r
WHERE r.world_id = c.world_id AND r.region_id = c.region_id FOR UPDATE;
IF NOT FOUND THEN
RAISE EXCEPTION 'region not provisioned' USING ERRCODE = 'EVL04';
END IF;
IF h.commit_sequence = 18446744073709551615 THEN
RAISE EXCEPTION 'commit sequences exhausted' USING ERRCODE = 'EVL05';
END IF;
IF c.commit_sequence <> h.commit_sequence + 1 OR c.predecessor_commit <> h.commit_id
OR c.predecessor_digest <> h.digest OR c.begin_tick <> h.end_tick THEN
RAISE EXCEPTION 'region head moved' USING ERRCODE = 'EVL03';
END IF;
SELECT l.frame_id INTO frame FROM evolution.region_leases l
WHERE l.world_id = c.world_id AND l.region_id = c.region_id;
IF c.frame_id <> frame THEN
RAISE EXCEPTION 'foreign frame' USING ERRCODE = '22023';
END IF;
SELECT * INTO p FROM evolution.region_commits r
WHERE r.world_id = c.world_id AND r.region_id = c.region_id
AND r.commit_sequence = h.commit_sequence;
-- Rules, formats and quantum are fixed for a region; changing them is a migration.
IF c.versions <> p.versions OR c.tick_microseconds <> p.tick_microseconds
OR NOT EXISTS (SELECT 1 FROM evolution.retained_builds b
WHERE b.build_identity = c.build_identity) THEN
RAISE EXCEPTION 'unsupported checkpoint' USING ERRCODE = 'EVL06';
END IF;
IF EXISTS (SELECT 1 FROM evolution.region_commits r WHERE r.commit_id = c.commit_id) THEN
RAISE EXCEPTION 'commit identity reused' USING ERRCODE = 'EVL07';
END IF;
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 (c.world_id, c.region_id, c.commit_sequence, c.commit_id, d, p_manifest,
c.begin_tick, c.end_tick, c.epoch, c.tick_microseconds, c.versions,
c.build_identity, c.payload_bytes, c.payload_sha256);
UPDATE evolution.region_heads r
SET commit_sequence = c.commit_sequence, commit_id = c.commit_id, digest = d,
end_tick = c.end_tick, published_epoch = c.epoch
WHERE r.world_id = c.world_id AND r.region_id = c.region_id;
RETURN QUERY SELECT frame, c.commit_sequence, c.commit_id, encode(d, 'hex'), c.end_tick;
END $$;
-- Committed head plus its exact manifest bytes, for recovery verification.
CREATE FUNCTION evolution.load_region_checkpoint(p_world evolution.u64, p_region evolution.u64)
RETURNS TABLE (region_frame evolution.u64, head_sequence evolution.u64, head_commit uuid,
head_digest text, head_tick evolution.u64, head_manifest text)
LANGUAGE plpgsql STABLE SECURITY DEFINER SET search_path = pg_catalog, pg_temp AS $$
BEGIN
RETURN QUERY SELECT l.frame_id, h.commit_sequence, h.commit_id, encode(h.digest, 'hex'),
h.end_tick, encode(c.manifest, 'hex')
FROM evolution.region_heads h
JOIN evolution.region_leases l USING (world_id, region_id)
JOIN evolution.region_commits c USING (world_id, region_id, commit_sequence)
WHERE h.world_id = p_world AND h.region_id = p_region;
IF NOT FOUND THEN
RAISE EXCEPTION 'region not provisioned' USING ERRCODE = 'EVL04';
END IF;
END $$;
REVOKE ALL ON FUNCTION
evolution.manifest_uint(bytea, integer, integer),
evolution.parse_checkpoint_manifest(bytea),
evolution.provision_region_checkpoint(bytea),
evolution.publish_region_checkpoint(bytea),
evolution.load_region_checkpoint(evolution.u64, evolution.u64)
FROM PUBLIC;
GRANT EXECUTE ON FUNCTION
evolution.publish_region_checkpoint(bytea),
evolution.load_region_checkpoint(evolution.u64, evolution.u64)
TO :"runtime_role";
INSERT INTO evolution.schema_migrations(version, sha256) VALUES (3, :'migration_sha_3');