Files
aevolution/migrations/0035_cellular_mutation_publication.sql
dingoandClaude Opus 5.5 f59c8498b1 Admit v10 mutation choices through the cellular host and sessions
The region host checks a choice against the committed offer, reserves the
successor for the next tick, and publishes it with that tick's batch; the
owner's v10 session gets the receipt and final outcome. Schema v35 now
refuses a checkpoint that skips a reserved choice, and the host reloads
pending reservations after uncertainty, refusal or recovery (ADR-0121).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-13 19:45:23 -04:00

390 lines
20 KiB
PL/PgSQL

-- M11.4c, ADR-0121: publish mutation selections atomically with their checkpoint.
-- Each published selection binds its v29 reservation to the commit with a final
-- result (0 applied, 1 life died, 2 insufficient funding). The trace records the
-- complete selection; the separate block names the durable account/action keys.
-- Birth binding now admits mutation records in format-3 traces; their content is
-- validated by cellular_mutation_selections. Otherwise unchanged from schema v34.
CREATE OR REPLACE FUNCTION evolution.cellular_births(p_trace bytea, p_manifest bytea)
RETURNS TABLE(account_id uuid, request_id evolution.u64, generation evolution.u64,
identity evolution.u64, born evolution.u64)
LANGUAGE plpgsql IMMUTABLE SECURITY INVOKER SET search_path = pg_catalog, pg_temp AS $$
DECLARE
c evolution.checkpoint_manifest := evolution.parse_checkpoint_manifest(p_manifest);
revision boolean;
ticks numeric;
tick_index integer;
trace_format numeric;
tick_header_size integer;
intent_count numeric;
birth_count numeric;
mutation_count numeric;
off integer := 112;
account bytea;
previous_account bytea;
previous_request numeric;
BEGIN
revision := c.versions IN (
'\x020000000300000001000000010000000100000002000000010000000200000001000000'::bytea,
'\x030000000400000001000000010000000100000002000000010000000200000001000000'::bytea);
trace_format := evolution.manifest_uint(p_trace, 8, 4);
tick_header_size := CASE trace_format WHEN 2 THEN 8 WHEN 3 THEN 16 ELSE 0 END;
IF c.profile <> 4 OR c.commit_sequence = 0 OR p_trace IS NULL
OR octet_length(p_trace) <> c.trace_bytes OR sha256(p_trace) <> c.trace_sha256
OR substring(p_trace FROM 1 FOR 8) <> '\x45564c4342543031'
OR tick_header_size = 0
OR (revision AND trace_format <> 3)
OR (NOT revision AND trace_format <> 2)
OR evolution.manifest_uint(p_trace, 12, 4) <> 4
OR evolution.manifest_uint(p_trace, 16, 8) <> c.world_id
OR evolution.manifest_uint(p_trace, 24, 8) <> c.region_id
OR evolution.manifest_uint(p_trace, 32, 8) <> c.frame_id
OR encode(substring(p_trace FROM 41 FOR 16), 'hex')::uuid <> c.predecessor_commit
OR substring(p_trace FROM 57 FOR 32) <> c.predecessor_digest
OR evolution.manifest_uint(p_trace, 88, 8) <> c.begin_tick
OR evolution.manifest_uint(p_trace, 96, 8) <> c.end_tick THEN
RAISE EXCEPTION 'invalid cellular birth trace binding' USING ERRCODE = '22023';
END IF;
ticks := c.end_tick - c.begin_tick;
IF ticks < 1 OR ticks > 64 OR evolution.manifest_uint(p_trace, 104, 4) <> ticks
OR evolution.manifest_uint(p_trace, 108, 4) <> 0 THEN
RAISE EXCEPTION 'invalid cellular birth trace range' USING ERRCODE = '22023';
END IF;
FOR tick_index IN 0 .. ticks::integer - 1 LOOP
IF off + tick_header_size > octet_length(p_trace) THEN
RAISE EXCEPTION 'truncated cellular tick header' USING ERRCODE = '22023';
END IF;
intent_count := evolution.manifest_uint(p_trace, off, 4);
birth_count := evolution.manifest_uint(p_trace, off + 4, 4);
mutation_count := 0;
IF trace_format = 3 THEN
mutation_count := evolution.manifest_uint(p_trace, off + 8, 4);
IF evolution.manifest_uint(p_trace, off + 12, 4) <> 0 THEN
RAISE EXCEPTION 'invalid cellular tick reserved word' USING ERRCODE = '22023';
END IF;
END IF;
IF intent_count > 256 OR birth_count > 256 OR mutation_count > 256
OR off + tick_header_size + intent_count * 24 + birth_count * 40
+ mutation_count * 40 > octet_length(p_trace) THEN
RAISE EXCEPTION 'invalid cellular tick counts' USING ERRCODE = '22023';
END IF;
off := off + tick_header_size + intent_count::integer * 24;
previous_account := ''::bytea;
previous_request := -1;
FOR birth_index IN 0 .. birth_count::integer - 1 LOOP
account := substring(p_trace FROM off + 1 FOR 16);
account_id := encode(account, 'hex')::uuid;
request_id := evolution.manifest_uint(p_trace, off + 16, 8);
generation := evolution.manifest_uint(p_trace, off + 24, 8);
identity := evolution.manifest_uint(p_trace, off + 32, 8);
born := c.begin_tick + tick_index + 1;
IF account_id = '00000000-0000-0000-0000-000000000000' OR request_id = 0
OR generation = 0 OR identity = 0
OR (account, request_id) <= (previous_account, previous_request) THEN
RAISE EXCEPTION 'invalid cellular birth record' USING ERRCODE = '22023';
END IF;
previous_account := account;
previous_request := request_id;
off := off + 40;
RETURN NEXT;
END LOOP;
off := off + mutation_count::integer * 40;
END LOOP;
IF off <> octet_length(p_trace) THEN
RAISE EXCEPTION 'trailing cellular trace bytes' USING ERRCODE = '22023';
END IF;
END $$;
-- The trace's mutation selections with their tick, validated record by record.
CREATE FUNCTION evolution.cellular_mutation_selections(p_trace bytea, p_manifest bytea)
RETURNS TABLE(tick evolution.u64, life_id evolution.u64, event_index evolution.u64,
offer_tick evolution.u64, successor_identity evolution.u64, operator_id integer)
LANGUAGE plpgsql IMMUTABLE SECURITY INVOKER SET search_path = pg_catalog, pg_temp AS $$
DECLARE
c evolution.checkpoint_manifest := evolution.parse_checkpoint_manifest(p_manifest);
ticks integer;
off integer := 112;
intent_count integer;
birth_count integer;
mutation_count integer;
previous_life numeric;
BEGIN
PERFORM * FROM evolution.cellular_births(p_trace, p_manifest); -- Binding and structure.
IF evolution.manifest_uint(p_trace, 8, 4) <> 3 THEN
RETURN; -- Format 2 carries no selections.
END IF;
ticks := (c.end_tick - c.begin_tick)::integer;
FOR tick_index IN 0 .. ticks - 1 LOOP
intent_count := evolution.manifest_uint(p_trace, off, 4)::integer;
birth_count := evolution.manifest_uint(p_trace, off + 4, 4)::integer;
mutation_count := evolution.manifest_uint(p_trace, off + 8, 4)::integer;
off := off + 16 + intent_count * 24 + birth_count * 40;
previous_life := 0;
FOR mutation_index IN 0 .. mutation_count - 1 LOOP
tick := c.begin_tick + tick_index + 1;
life_id := evolution.manifest_uint(p_trace, off, 8);
event_index := evolution.manifest_uint(p_trace, off + 8, 8);
offer_tick := evolution.manifest_uint(p_trace, off + 16, 8);
successor_identity := evolution.manifest_uint(p_trace, off + 24, 8);
operator_id := evolution.manifest_uint(p_trace, off + 32, 2)::integer;
IF life_id = 0 OR life_id <= previous_life OR event_index = 0 OR offer_tick = 0
OR offer_tick >= tick OR successor_identity = 0 OR operator_id = 0
OR substring(p_trace FROM off + 35 FOR 6) <> '\x000000000000' THEN
RAISE EXCEPTION 'invalid cellular mutation selection' USING ERRCODE = '22023';
END IF;
previous_life := life_id;
off := off + 40;
RETURN NEXT;
END LOOP;
END LOOP;
END $$;
-- The mutation block (64-byte records: account, action id, the 34-byte reserved input,
-- six zero bytes) must be ordered by (tick, account, action), name exactly one reserved
-- choice of this region per trace selection, and carry a known result per record.
CREATE FUNCTION evolution.check_cellular_mutation_block(p_manifest bytea, p_trace bytea,
p_mutations bytea, p_results bytea)
RETURNS integer LANGUAGE plpgsql STABLE SECURITY INVOKER
SET search_path = pg_catalog, pg_temp AS $$
DECLARE
c evolution.checkpoint_manifest := evolution.parse_checkpoint_manifest(p_manifest);
n integer;
account uuid;
account_bytes bytea;
action numeric;
tick numeric;
input bytea;
previous_tick numeric := -1;
previous_account bytea := ''::bytea;
previous_action numeric := -1;
r evolution.cellular_mutation_reservations%ROWTYPE;
BEGIN
IF p_mutations IS NULL OR p_results IS NULL OR octet_length(p_mutations) = 0
OR octet_length(p_mutations) % 64 <> 0 OR octet_length(p_mutations) / 64 > 1024
OR octet_length(p_results) <> octet_length(p_mutations) / 64 THEN
RAISE EXCEPTION 'invalid cellular mutation block' USING ERRCODE = '22023';
END IF;
n := octet_length(p_mutations) / 64;
IF (SELECT count(*) FROM evolution.cellular_mutation_selections(p_trace, p_manifest)) <> n THEN
RAISE EXCEPTION 'cellular mutation block does not cover the trace' USING ERRCODE = '22023';
END IF;
FOR i IN 0 .. n - 1 LOOP
account_bytes := substring(p_mutations FROM 64 * i + 1 FOR 16);
account := encode(account_bytes, 'hex')::uuid;
action := evolution.manifest_uint(p_mutations, 64 * i + 16, 8);
input := substring(p_mutations FROM 64 * i + 25 FOR 34);
tick := evolution.manifest_uint(input, 0, 8);
IF account = '00000000-0000-0000-0000-000000000000' OR action = 0
OR NOT evolution.valid_cellular_mutation_input(input)
OR substring(p_mutations FROM 64 * i + 59 FOR 6) <> '\x000000000000'
OR get_byte(p_results, i) > 2
OR tick <= c.begin_tick OR tick > c.end_tick
OR (tick, account_bytes, action) <= (previous_tick, previous_account, previous_action) THEN
RAISE EXCEPTION 'invalid cellular mutation record' USING ERRCODE = '22023';
END IF;
previous_tick := tick;
previous_account := account_bytes;
previous_action := action;
SELECT * INTO r FROM evolution.cellular_mutation_reservations x
WHERE x.world_id = c.world_id AND x.account_id = account AND x.action_id = action;
IF NOT FOUND OR r.region_id <> c.region_id OR r.input_bytes <> input
OR r.target_tick <> evolution.manifest_uint(input, 0, 8) THEN
RAISE EXCEPTION 'cellular mutation reservation conflicts' USING ERRCODE = 'EVL16';
END IF;
IF NOT EXISTS (SELECT 1 FROM evolution.cellular_mutation_selections(p_trace, p_manifest) s
WHERE s.tick = r.target_tick AND s.successor_identity = r.successor_identity
AND s.life_id = evolution.manifest_uint(input, 8, 8)
AND s.event_index = evolution.manifest_uint(input, 16, 8)
AND s.offer_tick = evolution.manifest_uint(input, 24, 8)
AND s.operator_id = evolution.manifest_uint(input, 32, 2)) THEN
RAISE EXCEPTION 'cellular mutation differs from its trace' USING ERRCODE = '22023';
END IF;
END LOOP;
RETURN n;
END $$;
-- Choices of this region reserved for a tick in (begin, end] and not bound to another
-- commit. A checkpoint must carry every one of them: a reserved choice that a later
-- checkpoint skipped could never publish and would block its account's next choice.
CREATE INDEX cellular_mutation_reservations_by_tick
ON evolution.cellular_mutation_reservations(world_id, region_id, target_tick);
CREATE FUNCTION evolution.cellular_mutations_due(p_manifest bytea)
RETURNS integer LANGUAGE plpgsql STABLE SECURITY INVOKER
SET search_path = pg_catalog, pg_temp AS $$
DECLARE c evolution.checkpoint_manifest := evolution.parse_checkpoint_manifest(p_manifest);
BEGIN
RETURN (SELECT count(*) FROM evolution.cellular_mutation_reservations r
WHERE r.world_id = c.world_id AND r.region_id = c.region_id
AND r.target_tick > c.begin_tick AND r.target_tick <= c.end_tick
AND NOT EXISTS (SELECT 1 FROM evolution.cellular_mutation_action_publications p
WHERE p.world_id = r.world_id AND p.account_id = r.account_id
AND p.action_id = r.action_id AND p.commit_id <> c.commit_id));
END $$;
-- True when this commit already bound exactly these actions with these results.
CREATE FUNCTION evolution.cellular_mutation_publications_match(p_world evolution.u64,
p_commit uuid, p_mutations bytea, p_results bytea)
RETURNS boolean LANGUAGE plpgsql STABLE SECURITY INVOKER
SET search_path = pg_catalog, pg_temp AS $$
DECLARE n integer := octet_length(p_mutations) / 64;
BEGIN
IF (SELECT count(*) FROM evolution.cellular_mutation_action_publications p
WHERE p.world_id = p_world AND p.commit_id = p_commit) <> n THEN
RETURN false;
END IF;
FOR i IN 0 .. n - 1 LOOP
IF NOT EXISTS (SELECT 1 FROM evolution.cellular_mutation_action_publications p
WHERE p.world_id = p_world AND p.commit_id = p_commit
AND p.account_id = encode(substring(p_mutations FROM 64 * i + 1 FOR 16), 'hex')::uuid
AND p.action_id = evolution.manifest_uint(p_mutations, 64 * i + 16, 8)
AND p.result = get_byte(p_results, i)) THEN
RETURN false;
END IF;
END LOOP;
RETURN true;
END $$;
-- The existing four-argument publisher becomes internal; its runtime replacement refuses
-- traces with selections, which only the mutation publisher may bind.
ALTER FUNCTION evolution.publish_cellular_checkpoint(bytea, bytea, bytea, bytea)
RENAME TO publish_cellular_birth_checkpoint;
REVOKE ALL ON FUNCTION evolution.publish_cellular_birth_checkpoint(bytea, bytea, bytea, bytea)
FROM PUBLIC, :"runtime_role";
CREATE FUNCTION evolution.publish_cellular_checkpoint(p_manifest bytea, p_decisions bytea,
p_actions bytea, p_trace 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 $$
BEGIN
IF EXISTS (SELECT 1 FROM evolution.cellular_mutation_selections(p_trace, p_manifest)) THEN
RAISE EXCEPTION 'cellular mutation selections need their action block' USING ERRCODE = '22023';
END IF;
IF NOT EXISTS (SELECT 1 FROM evolution.region_commits x
WHERE x.commit_id = (evolution.parse_checkpoint_manifest(p_manifest)).commit_id)
AND evolution.cellular_mutations_due(p_manifest) <> 0 THEN
RAISE EXCEPTION 'cellular checkpoint omits a reserved mutation' USING ERRCODE = '22023';
END IF;
RETURN QUERY SELECT * FROM evolution.publish_cellular_birth_checkpoint(
p_manifest, p_decisions, p_actions, p_trace);
END $$;
CREATE FUNCTION evolution.publish_cellular_mutation_checkpoint(p_manifest bytea,
p_decisions bytea, p_actions bytea, p_trace bytea, p_mutations bytea, p_results 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);
n integer;
h record;
digest bytea;
BEGIN
IF c.profile <> 4 OR c.commit_sequence = 0 THEN
RAISE EXCEPTION 'invalid cellular publication' USING ERRCODE = '22023';
END IF;
n := evolution.check_cellular_mutation_block(p_manifest, p_trace, p_mutations, p_results);
IF EXISTS (SELECT 1 FROM evolution.region_commits x WHERE x.commit_id = c.commit_id) THEN
IF NOT evolution.cellular_mutation_publications_match(c.world_id, c.commit_id, p_mutations,
p_results) THEN
RAISE EXCEPTION 'cellular mutation evidence differs on retry' USING ERRCODE = 'EVL07';
END IF;
RETURN QUERY SELECT * FROM evolution.publish_cellular_birth_checkpoint(
p_manifest, p_decisions, p_actions, p_trace);
RETURN;
END IF;
IF evolution.cellular_mutations_due(p_manifest) <> n THEN
RAISE EXCEPTION 'cellular checkpoint omits a reserved mutation' USING ERRCODE = '22023';
END IF;
-- A choice binds to one commit only; another commit's binding is a reused identity.
FOR i IN 0 .. n - 1 LOOP
IF EXISTS (SELECT 1 FROM evolution.cellular_mutation_action_publications p
WHERE p.world_id = c.world_id AND p.commit_id <> c.commit_id
AND p.account_id = encode(substring(p_mutations FROM 64 * i + 1 FOR 16), 'hex')::uuid
AND p.action_id = evolution.manifest_uint(p_mutations, 64 * i + 16, 8)) THEN
RAISE EXCEPTION 'cellular mutation already published' USING ERRCODE = 'EVL07';
END IF;
END LOOP;
-- The birth publisher takes the lease lock and rechecks an uncertain first attempt.
SELECT * INTO h FROM evolution.publish_cellular_birth_checkpoint(
p_manifest, p_decisions, p_actions, p_trace);
IF NOT FOUND THEN
RAISE EXCEPTION 'publication returned no head' USING ERRCODE = 'XX000';
END IF;
IF evolution.cellular_mutation_publications_match(c.world_id, c.commit_id, p_mutations,
p_results) THEN
RETURN QUERY SELECT h.region_frame, h.head_sequence, h.head_commit, h.head_digest,
h.head_tick;
RETURN;
END IF;
SELECT x.commit_digest INTO digest FROM evolution.region_commits x
WHERE x.commit_id = c.commit_id;
FOR i IN 0 .. n - 1 LOOP
INSERT INTO evolution.cellular_mutation_action_publications(world_id, region_id,
account_id, action_id, commit_id, commit_digest, commit_sequence, result)
VALUES (c.world_id, c.region_id,
encode(substring(p_mutations FROM 64 * i + 1 FOR 16), 'hex')::uuid,
evolution.manifest_uint(p_mutations, 64 * i + 16, 8), c.commit_id, digest,
c.commit_sequence, get_byte(p_results, i));
END LOOP;
RETURN QUERY SELECT h.region_frame, h.head_sequence, h.head_commit, h.head_digest, h.head_tick;
END $$;
CREATE FUNCTION evolution.resolve_cellular_mutation_commit(p_world evolution.u64,
p_region evolution.u64, p_commit uuid, p_manifest bytea, p_decisions bytea,
p_actions bytea, p_trace bytea, p_mutations bytea, p_results 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 $$
DECLARE c evolution.checkpoint_manifest := evolution.parse_checkpoint_manifest(p_manifest);
BEGIN
IF c.world_id <> p_world OR c.region_id <> p_region OR c.commit_id <> p_commit THEN
RAISE EXCEPTION 'invalid cellular resolution request' USING ERRCODE = '22023';
END IF;
PERFORM evolution.check_cellular_mutation_block(p_manifest, p_trace, p_mutations, p_results);
IF EXISTS (SELECT 1 FROM evolution.region_commits x WHERE x.commit_id = p_commit)
AND NOT evolution.cellular_mutation_publications_match(p_world, p_commit, p_mutations,
p_results) 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_cellular_region_commit(
p_world, p_region, p_commit, p_manifest, p_decisions, p_actions, p_trace);
END $$;
-- Recovery: the account/action keys, reserved inputs and results bound to one commit.
CREATE FUNCTION evolution.load_cellular_mutation_publications(p_world evolution.u64,
p_region evolution.u64, p_holder uuid, p_epoch evolution.u64, p_commit uuid)
RETURNS TABLE(account_id uuid, action_id evolution.u64, input_bytes bytea, result smallint)
LANGUAGE plpgsql SECURITY DEFINER SET search_path = pg_catalog, pg_temp AS $$
BEGIN
PERFORM evolution.check_region_lease(p_world, p_region, p_holder, p_epoch);
RETURN QUERY SELECT p.account_id, p.action_id, r.input_bytes, p.result
FROM evolution.cellular_mutation_action_publications p
JOIN evolution.cellular_mutation_reservations r USING (world_id, account_id, action_id)
WHERE p.world_id = p_world AND p.region_id = p_region AND p.commit_id = p_commit
ORDER BY r.target_tick, p.account_id, p.action_id;
END $$;
REVOKE ALL ON FUNCTION evolution.cellular_mutation_selections(bytea, bytea),
evolution.cellular_mutations_due(bytea),
evolution.check_cellular_mutation_block(bytea, bytea, bytea, bytea),
evolution.cellular_mutation_publications_match(evolution.u64, uuid, bytea, bytea),
evolution.publish_cellular_checkpoint(bytea, bytea, bytea, bytea),
evolution.publish_cellular_mutation_checkpoint(bytea, bytea, bytea, bytea, bytea, bytea),
evolution.resolve_cellular_mutation_commit(evolution.u64, evolution.u64, uuid, bytea, bytea,
bytea, bytea, bytea, bytea),
evolution.load_cellular_mutation_publications(evolution.u64, evolution.u64, uuid,
evolution.u64, uuid)
FROM PUBLIC;
GRANT EXECUTE ON FUNCTION
evolution.publish_cellular_checkpoint(bytea, bytea, bytea, bytea),
evolution.publish_cellular_mutation_checkpoint(bytea, bytea, bytea, bytea, bytea, bytea),
evolution.resolve_cellular_mutation_commit(evolution.u64, evolution.u64, uuid, bytea, bytea,
bytea, bytea, bytea, bytea),
evolution.load_cellular_mutation_publications(evolution.u64, evolution.u64, uuid,
evolution.u64, uuid)
TO :"runtime_role";
INSERT INTO evolution.schema_migrations(version, sha256) VALUES (35, :'migration_sha_35');