Files
aevolution/migrations/0009_serialized_authority.sql
dingoandClaude Opus 5.5 168c90d5b2 Serialize build retirement and clone classification, bound ops accepts
Review fixes for M7.6-M7.9. Schema v9 applies one lock order: the
barrier takes a database-wide upgrade lock exclusively, while
acquisitions, lease checks, provisioning and the retired-build trigger
take it shared first, so a queued acquisition can no longer regain
authority for a just-retired build and concurrent barriers cannot
retire the last current build. Provisioning takes a per-world lock
before classifying a world as original or a clone of one source. The
operations listener makes at most four accept attempts per serve().
Race regressions prove each contender is blocked before commit.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 08:38:13 -04:00

236 lines
12 KiB
PL/PgSQL

-- M7.9 review fixes (ADR-0067/0068): one locking protocol for authority, build
-- retirement and world classification. Replaces function bodies only.
--
-- Lock order, everywhere: upgrade lock (advisory 71420002) -> world classification
-- lock (advisory 71420003, hashtext(world)) -> lease row -> head/commit rows.
-- upgrade_barrier takes the upgrade lock exclusively before anything else; every
-- acquisition, lease check (so publication, renewal and release), provisioning and
-- the retired-build trigger take it shared first. A retirement therefore cannot
-- commit between an acquisition's eligibility check and its grant, a commit naming
-- a build cannot straddle its retirement, and concurrent barriers serialize. The
-- per-world lock serializes original/clone classification of one target world
-- while unrelated worlds provision in parallel. Callers use READ COMMITTED
-- statements (as the adapter does), so each check after a wait sees committed rows.
CREATE OR REPLACE FUNCTION evolution.check_region_lease(p_world evolution.u64,
p_region evolution.u64, p_holder uuid, p_epoch evolution.u64)
RETURNS timestamptz LANGUAGE plpgsql SECURITY INVOKER
SET search_path = pg_catalog, pg_temp AS $$
DECLARE
l evolution.region_leases%ROWTYPE;
t timestamptz;
BEGIN
IF p_world IS NULL OR p_region IS NULL OR p_holder IS NULL OR p_epoch IS NULL THEN
RAISE EXCEPTION 'invalid lease request' USING ERRCODE = '22023';
END IF;
PERFORM pg_catalog.pg_advisory_xact_lock_shared(71420002);
SELECT * INTO l FROM evolution.region_leases r
WHERE r.world_id = p_world AND r.region_id = p_region FOR UPDATE;
IF NOT FOUND THEN
RAISE EXCEPTION 'region not provisioned' USING ERRCODE = 'EVL04';
END IF;
-- Read after the lock wait: a queued stale writer sees current database time.
t := clock_timestamp();
IF l.holder IS DISTINCT FROM p_holder OR l.epoch <> p_epoch OR l.expires_at <= t THEN
RAISE EXCEPTION 'region lease fenced' USING ERRCODE = 'EVL02';
END IF;
RETURN t;
END $$;
CREATE OR REPLACE FUNCTION evolution.acquire_region_lease(p_world evolution.u64,
p_region evolution.u64, p_duration_ms integer, p_build bytea)
RETURNS TABLE (lease_holder uuid, lease_epoch evolution.u64, region_frame evolution.u64,
granted_ms integer)
LANGUAGE plpgsql SECURITY DEFINER SET search_path = pg_catalog, pg_temp AS $$
BEGIN
IF p_build IS NULL OR octet_length(p_build) <> 32 THEN
RAISE EXCEPTION 'invalid lease request' USING ERRCODE = '22023';
END IF;
-- Eligibility is decided under the upgrade lock and held through the grant.
PERFORM pg_catalog.pg_advisory_xact_lock_shared(71420002);
IF NOT EXISTS (SELECT 1 FROM evolution.retained_builds b
WHERE b.build_identity = p_build AND b.retired_at IS NULL) THEN
RAISE EXCEPTION 'build not current' USING ERRCODE = 'EVL06';
END IF;
RETURN QUERY SELECT * FROM evolution.grant_region_lease(p_world, p_region, p_duration_ms);
END $$;
CREATE OR REPLACE FUNCTION evolution.acquire_region_lease(p_world evolution.u64,
p_region evolution.u64, p_duration_ms integer)
RETURNS TABLE (lease_holder uuid, lease_epoch evolution.u64, region_frame evolution.u64,
granted_ms integer)
LANGUAGE plpgsql SECURITY DEFINER SET search_path = pg_catalog, pg_temp AS $$
BEGIN
PERFORM pg_catalog.pg_advisory_xact_lock_shared(71420002);
IF EXISTS (SELECT 1 FROM evolution.retained_builds b WHERE b.retired_at IS NOT NULL) THEN
RAISE EXCEPTION 'build-less acquisition ended by an upgrade barrier' USING ERRCODE = 'EVL06';
END IF;
RETURN QUERY SELECT * FROM evolution.grant_region_lease(p_world, p_region, p_duration_ms);
END $$;
CREATE OR REPLACE FUNCTION evolution.refuse_retired_build() RETURNS trigger LANGUAGE plpgsql
SET search_path = pg_catalog, pg_temp AS $$
BEGIN
-- Normally already held by the inserting function (same order); re-entrant.
PERFORM pg_catalog.pg_advisory_xact_lock_shared(71420002);
IF EXISTS (SELECT 1 FROM evolution.retained_builds b
WHERE b.build_identity = NEW.build_identity AND b.retired_at IS NOT NULL) THEN
RAISE EXCEPTION 'build retired from publication' USING ERRCODE = 'EVL06';
END IF;
RETURN NEW;
END $$;
CREATE OR REPLACE FUNCTION evolution.upgrade_barrier(p_retire bytea)
RETURNS integer LANGUAGE plpgsql SECURITY INVOKER SET search_path = pg_catalog, pg_temp AS $$
DECLARE
fenced integer;
BEGIN
IF p_retire IS NULL OR octet_length(p_retire) <> 32 THEN
RAISE EXCEPTION 'invalid build identity' USING ERRCODE = '22023';
END IF;
-- First: waits out every in-flight acquisition, lease check and provisioning,
-- and serializes barriers so the last-current-build check cannot be raced.
PERFORM pg_catalog.pg_advisory_xact_lock(71420002);
PERFORM 1 FROM evolution.retained_builds b WHERE b.build_identity = p_retire FOR UPDATE;
IF NOT FOUND THEN
RAISE EXCEPTION 'build not retained' USING ERRCODE = '22023';
END IF;
IF NOT EXISTS (SELECT 1 FROM evolution.retained_builds b
WHERE b.build_identity <> p_retire AND b.retired_at IS NULL) THEN
RAISE EXCEPTION 'no current build would remain' USING ERRCODE = '22023';
END IF;
UPDATE evolution.retained_builds b SET retired_at = coalesce(b.retired_at, clock_timestamp())
WHERE b.build_identity = p_retire;
UPDATE evolution.region_leases l SET holder = NULL, expires_at = NULL
WHERE l.holder IS NOT NULL;
GET DIAGNOSTICS fenced = ROW_COUNT;
RETURN fenced;
END $$;
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;
-- Upgrade lock (shared), then this world's classification lock; both checks
-- below run after the waits, so they see every committed provisioning.
PERFORM pg_catalog.pg_advisory_xact_lock_shared(71420002);
PERFORM pg_catalog.pg_advisory_xact_lock(71420003, pg_catalog.hashtext(g.world_id::text));
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 OR REPLACE 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;
-- Upgrade lock (shared), then this world's classification lock; both checks
-- below run after the waits, so they see every committed provisioning.
PERFORM pg_catalog.pg_advisory_xact_lock_shared(71420002);
PERFORM pg_catalog.pg_advisory_xact_lock(71420003, pg_catalog.hashtext(g.world_id::text));
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 $$;
INSERT INTO evolution.schema_migrations(version, sha256) VALUES (9, :'migration_sha_9');