Files
aevolution/migrations/0011_region_actions.sql
T
dingoandClaude Opus 5.5 69f3ad7cf8
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 1m47s
Foundation / checks (network) (push) Successful in 9m30s
Foundation / checks (client) (push) Successful in 12m19s
Foundation / checks (tsan) (push) Successful in 7m43s
Foundation / checks (checks) (push) Successful in 31m29s
Foundation / checks (postgres) (push) Successful in 36m39s
Foundation / postgres-tools (push) Successful in 19s
Foundation / image (push) Successful in 2m15s
Foundation / server-image (push) Successful in 20m37s
Add M10.4b durable action records (schema v11)
Each batch's actions are recorded in the same statement as its checkpoint: one
region_actions row per (world, account, action id) and the block in an append-only
table, compared on exact retries and resolution. The region host attaches actions to
the ticks they ride and reports acknowledgements and drops, keeping unknown-outcome
batches unresolved. Outcomes come from the durable record via ActionLedger, so
crashes before or after a commit, unknown publications and cross-region moves all
resolve to one answer; a repeated id keeps its first record instead of stalling a
region. ADR-0092.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-03 22:53:38 -04:00

171 lines
8.6 KiB
PL/PgSQL

-- M10.4b durable action records (ADR-0092). An action rides the batch that simulates its
-- tick and becomes durable in the same statement as that batch's checkpoint. The action
-- block is part of the commit's identity: an exact retry must repeat it byte for byte.
--
-- Action block: N records of 34 bytes, strictly ascending by (tick, account, action id):
-- account uuid (16 raw bytes), action id u64 LE (nonzero), tick u64 LE in
-- (begin_tick, end_tick], kind u16 LE (1 = probe). At most 1024 records.
-- (world, account, action id) is unique across the world: an id is recorded once, by the
-- first commit that carries it. A later batch carrying the same id (an account that moved
-- regions while its action was pending in the old one) commits normally without a second
-- record; the session layer reports outcomes from the record, never from the batch.
-- Committed history stays immutable: each commit's block is kept in its own append-only
-- table (a commit without a row has an empty block).
CREATE TABLE evolution.region_commit_actions (
commit_id uuid PRIMARY KEY REFERENCES evolution.region_commits(commit_id),
actions bytea NOT NULL CHECK (octet_length(actions) > 0)
);
REVOKE ALL ON evolution.region_commit_actions FROM PUBLIC;
CREATE TABLE evolution.region_actions (
world_id evolution.u64 NOT NULL,
account_id uuid NOT NULL CHECK (account_id <> '00000000-0000-0000-0000-000000000000'),
action_id evolution.u64 NOT NULL CHECK (action_id > 0),
region_id evolution.u64 NOT NULL,
tick evolution.u64 NOT NULL CHECK (tick > 0),
kind smallint NOT NULL CHECK (kind = 1),
commit_sequence evolution.u64 NOT NULL CHECK (commit_sequence > 0),
PRIMARY KEY (world_id, account_id, action_id)
);
REVOKE ALL ON evolution.region_actions FROM PUBLIC;
-- The action block a commit was published with (empty when none).
CREATE FUNCTION evolution.commit_actions(p_commit uuid)
RETURNS bytea LANGUAGE sql STABLE SECURITY INVOKER SET search_path = pg_catalog, pg_temp AS $$
SELECT coalesce((SELECT a.actions FROM evolution.region_commit_actions a
WHERE a.commit_id = p_commit), ''::bytea);
$$;
-- Validates an action block against a manifest's tick range; returns the record count.
CREATE FUNCTION evolution.check_action_block(p_actions bytea, p_begin numeric, p_end numeric)
RETURNS integer LANGUAGE plpgsql IMMUTABLE SECURITY INVOKER
SET search_path = pg_catalog, pg_temp AS $$
DECLARE
n integer := coalesce(octet_length(p_actions), -1);
account bytea;
id numeric;
tick numeric;
kind numeric;
prev_tick numeric := -1;
prev_account bytea := ''::bytea;
prev_id numeric := -1;
seen text[] := '{}';
BEGIN
IF n < 0 OR n % 34 <> 0 OR n / 34 > 1024 THEN
RAISE EXCEPTION 'invalid action block' USING ERRCODE = '22023';
END IF;
FOR i IN 0 .. n / 34 - 1 LOOP
account := substring(p_actions FROM 34 * i + 1 FOR 16);
id := evolution.manifest_uint(p_actions, 34 * i + 16, 8);
tick := evolution.manifest_uint(p_actions, 34 * i + 24, 8);
kind := evolution.manifest_uint(p_actions, 34 * i + 32, 2);
-- Canonical order: strictly ascending (tick, account bytes, id); no duplicates.
IF account = decode(repeat('00', 16), 'hex') OR id = 0 OR kind <> 1
OR tick <= p_begin OR tick > p_end
OR (tick, account, id) <= (prev_tick, prev_account, prev_id) THEN
RAISE EXCEPTION 'invalid action record' USING ERRCODE = '22023';
END IF;
-- An action id appears once in a block, whatever its tick.
IF encode(account, 'hex') || ':' || id::text = ANY (seen) THEN
RAISE EXCEPTION 'invalid action record' USING ERRCODE = '22023';
END IF;
seen := seen || (encode(account, 'hex') || ':' || id::text);
prev_tick := tick;
prev_account := account;
prev_id := id;
END LOOP;
RETURN n / 34;
END $$;
CREATE FUNCTION evolution.publish_region_checkpoint(p_manifest bytea, p_decisions bytea,
p_actions 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);
existing boolean;
r record;
n integer;
BEGIN
n := evolution.check_action_block(p_actions, c.begin_tick, c.end_tick);
-- An exact retry repeats the actions too; any difference is a reused identity.
existing := EXISTS (SELECT 1 FROM evolution.region_commits x WHERE x.commit_id = c.commit_id);
IF existing AND evolution.commit_actions(c.commit_id) <> p_actions THEN
RAISE EXCEPTION 'commit identity reused' USING ERRCODE = 'EVL07';
END IF;
-- The checkpoint itself: lease, head, decisions and exact-retry receipt (schema v5).
SELECT * INTO r FROM evolution.publish_region_checkpoint(p_manifest, p_decisions);
IF NOT FOUND THEN
RAISE EXCEPTION 'publication returned no head' USING ERRCODE = 'XX000';
END IF;
IF NOT existing THEN -- First publication, not a retry: record the actions.
FOR i IN 0 .. n - 1 LOOP
INSERT INTO evolution.region_actions(world_id, account_id, action_id, region_id, tick,
kind, commit_sequence)
VALUES (c.world_id, encode(substring(p_actions FROM 34 * i + 1 FOR 16), 'hex')::uuid,
evolution.manifest_uint(p_actions, 34 * i + 16, 8), c.region_id,
evolution.manifest_uint(p_actions, 34 * i + 24, 8), 1, c.commit_sequence)
ON CONFLICT (world_id, account_id, action_id) DO NOTHING;
END LOOP;
IF n > 0 THEN
INSERT INTO evolution.region_commit_actions(commit_id, actions)
VALUES (c.commit_id, p_actions);
END IF;
END IF;
RETURN QUERY SELECT r.region_frame, r.head_sequence, r.head_commit, r.head_digest,
r.head_tick;
END $$;
-- Resolution after an ambiguous publication, including the action block.
CREATE FUNCTION evolution.resolve_region_commit(p_world evolution.u64, p_region evolution.u64,
p_commit uuid, p_manifest bytea, p_decisions bytea, p_actions bytea)
RETURNS TABLE (status text, region_frame evolution.u64, head_sequence evolution.u64,
head_commit uuid, head_digest text, head_tick evolution.u64)
LANGUAGE plpgsql STABLE SECURITY DEFINER SET search_path = pg_catalog, pg_temp AS $$
BEGIN
IF p_actions IS NULL THEN
RAISE EXCEPTION 'invalid resolution request' USING ERRCODE = '22023';
END IF;
IF EXISTS (SELECT 1 FROM evolution.region_commits x WHERE x.commit_id = p_commit)
AND evolution.commit_actions(p_commit) <> p_actions THEN
RETURN QUERY SELECT 'conflict'::text, NULL::evolution.u64, NULL::evolution.u64, NULL::uuid,
NULL::text, NULL::evolution.u64;
RETURN;
END IF;
RETURN QUERY SELECT * FROM evolution.resolve_region_commit(p_world, p_region, p_commit,
p_manifest, p_decisions);
END $$;
-- The committed record of one action of an account in the caller's world, under the
-- caller's exact region lease. No row: the action is not committed (and, once the caller's
-- authority is recovered and ready, never was by an earlier epoch).
CREATE FUNCTION evolution.find_region_action(p_world evolution.u64, p_region evolution.u64,
p_holder uuid, p_epoch evolution.u64, p_account uuid, p_action evolution.u64)
RETURNS TABLE (action_region evolution.u64, action_tick evolution.u64,
action_commit evolution.u64)
LANGUAGE plpgsql SECURITY DEFINER SET search_path = pg_catalog, pg_temp AS $$
BEGIN
IF p_account IS NULL OR p_action IS NULL THEN
RAISE EXCEPTION 'invalid action request' USING ERRCODE = '22023';
END IF;
PERFORM evolution.check_region_lease(p_world, p_region, p_holder, p_epoch);
RETURN QUERY SELECT a.region_id, a.tick, a.commit_sequence FROM evolution.region_actions a
WHERE a.world_id = p_world AND a.account_id = p_account AND a.action_id = p_action;
END $$;
REVOKE ALL ON FUNCTION evolution.check_action_block(bytea, numeric, numeric),
evolution.commit_actions(uuid),
evolution.publish_region_checkpoint(bytea, bytea, bytea),
evolution.resolve_region_commit(evolution.u64, evolution.u64, uuid, bytea, bytea, bytea),
evolution.find_region_action(evolution.u64, evolution.u64, uuid, evolution.u64, uuid,
evolution.u64)
FROM PUBLIC;
GRANT EXECUTE ON FUNCTION
evolution.publish_region_checkpoint(bytea, bytea, bytea),
evolution.resolve_region_commit(evolution.u64, evolution.u64, uuid, bytea, bytea, bytea),
evolution.find_region_action(evolution.u64, evolution.u64, uuid, evolution.u64, uuid,
evolution.u64)
TO :"runtime_role";
INSERT INTO evolution.schema_migrations(version, sha256) VALUES (11, :'migration_sha_11');