-- Admin commands (ADR-0182, 2026-10-27). The admin portal queues operator commands for a -- region: remove a cell, grant a reserve, add bubbles, add to or release the spent pool, and -- spawn wildlife. The region applies each once, after a tick's births, and records it in the -- trace (format 5: trace 4 plus 64-byte command records counted in the tick header's last -- word), so replay and recovery reproduce it. Publication binds every recorded command to -- its queue row exactly once. A bundle-15 trace without commands stays trace 4; the existing -- parsers read a trace 5 through its trace-4 normal form, so nothing else changes. -- u64 values as little-endian bytes. CREATE FUNCTION evolution.le_bytes(v numeric, n integer) RETURNS bytea LANGUAGE plpgsql IMMUTABLE SET search_path = pg_catalog, pg_temp AS $$ DECLARE out bytea := ''::bytea; x numeric := v; BEGIN FOR i IN 1 .. n LOOP out := out || set_byte('\x00'::bytea, 0, (x % 256)::integer); x := floor(x / 256); END LOOP; RETURN out; END $$; REVOKE ALL ON FUNCTION evolution.le_bytes(numeric, integer) FROM PUBLIC; -- The trace-4 normal form of a trace 5: version 4, command counts zero, records dropped. CREATE FUNCTION evolution.cellular_trace_without_admin(t bytea) RETURNS bytea LANGUAGE plpgsql IMMUTABLE SET search_path = pg_catalog, pg_temp AS $$ DECLARE ticks integer; off integer := 112; out bytea; records integer; admin integer; BEGIN IF t IS NULL OR octet_length(t) < 112 OR evolution.manifest_uint(t, 8, 4) <> 5 THEN RETURN t; END IF; ticks := evolution.manifest_uint(t, 104, 4)::integer; out := overlay(substring(t FROM 1 FOR 112) PLACING '\x04000000'::bytea FROM 9 FOR 4); FOR i IN 1 .. ticks LOOP IF octet_length(t) < off + 16 THEN RAISE EXCEPTION 'invalid admin trace' USING ERRCODE = '22023'; END IF; records := evolution.manifest_uint(t, off, 4)::integer * 24 + evolution.manifest_uint(t, off + 4, 4)::integer * 40 + evolution.manifest_uint(t, off + 8, 4)::integer * 40; admin := evolution.manifest_uint(t, off + 12, 4)::integer; IF admin > 16 OR octet_length(t) < off + 16 + records + admin * 64 THEN RAISE EXCEPTION 'invalid admin trace' USING ERRCODE = '22023'; END IF; out := out || substring(t FROM off + 1 FOR 12) || '\x00000000'::bytea || substring(t FROM off + 17 FOR records); off := off + 16 + records + admin * 64; END LOOP; IF off <> octet_length(t) THEN RAISE EXCEPTION 'invalid admin trace' USING ERRCODE = '22023'; END IF; RETURN out; END $$; REVOKE ALL ON FUNCTION evolution.cellular_trace_without_admin(bytea) FROM PUBLIC; -- A trace 5's command records with the tick each applies at, in trace order. CREATE FUNCTION evolution.cellular_trace_admin(t bytea, m bytea) RETURNS TABLE (tick evolution.u64, command_id bigint, kind integer, cell_count integer, target evolution.u64, energy evolution.u64, carbon evolution.u64, nitrogen evolution.u64, phosphorus evolution.u64, other evolution.u64) LANGUAGE plpgsql IMMUTABLE SET search_path = pg_catalog, pg_temp AS $$ DECLARE c evolution.checkpoint_manifest := evolution.parse_checkpoint_manifest(m); ticks integer; off integer := 112; records integer; admin integer; previous numeric; BEGIN IF t IS NULL OR octet_length(t) < 112 OR evolution.manifest_uint(t, 8, 4) <> 5 THEN RETURN; END IF; ticks := evolution.manifest_uint(t, 104, 4)::integer; FOR tick_index IN 0 .. ticks - 1 LOOP records := evolution.manifest_uint(t, off, 4)::integer * 24 + evolution.manifest_uint(t, off + 4, 4)::integer * 40 + evolution.manifest_uint(t, off + 8, 4)::integer * 40; admin := evolution.manifest_uint(t, off + 12, 4)::integer; off := off + 16 + records; previous := 0; FOR i IN 1 .. admin LOOP tick := c.begin_tick + tick_index + 1; command_id := evolution.manifest_uint(t, off, 8)::bigint; kind := evolution.manifest_uint(t, off + 8, 2)::integer; cell_count := evolution.manifest_uint(t, off + 10, 2)::integer; target := evolution.manifest_uint(t, off + 16, 8); energy := evolution.manifest_uint(t, off + 24, 8); carbon := evolution.manifest_uint(t, off + 32, 8); nitrogen := evolution.manifest_uint(t, off + 40, 8); phosphorus := evolution.manifest_uint(t, off + 48, 8); other := evolution.manifest_uint(t, off + 56, 8); IF command_id <= previous OR substring(t FROM off + 13 FOR 4) <> '\x00000000'::bytea THEN RAISE EXCEPTION 'invalid admin trace' USING ERRCODE = '22023'; END IF; previous := command_id; off := off + 64; RETURN NEXT; END LOOP; END LOOP; END $$; REVOKE ALL ON FUNCTION evolution.cellular_trace_admin(bytea, bytea) FROM PUBLIC; -- The trace parsers read a bundle-15 trace 5 through its normal form, after binding the real -- trace to the manifest (as schema 55 did for retained plans). CREATE FUNCTION evolution.cellular_trace_normal(INOUT t bytea, INOUT m bytea) LANGUAGE plpgsql IMMUTABLE SET search_path = pg_catalog, pg_temp AS $$ DECLARE c evolution.checkpoint_manifest := evolution.parse_checkpoint_manifest(m); b15 constant bytea := '\x0d0000000b00000002000000010000000100000007000000060000000200000001000000'; BEGIN IF t IS NULL OR octet_length(t) < 12 OR evolution.manifest_uint(t, 8, 4) <> 5 THEN RETURN; END IF; IF c.versions <> b15 OR octet_length(t) <> c.trace_bytes OR sha256(t) <> c.trace_sha256 THEN RAISE EXCEPTION 'invalid admin trace binding' USING ERRCODE = '22023'; END IF; t := evolution.cellular_trace_without_admin(t); m := overlay(m PLACING evolution.le_bytes(octet_length(t), 8) FROM 281 FOR 8); m := overlay(m PLACING sha256(t) FROM 289 FOR 32); END $$; REVOKE ALL ON FUNCTION evolution.cellular_trace_normal(bytea, bytea) FROM PUBLIC; ALTER FUNCTION evolution.cellular_births(bytea,bytea) RENAME TO cellular_births_v62; REVOKE ALL ON FUNCTION evolution.cellular_births_v62(bytea,bytea) FROM PUBLIC, :"runtime_role"; CREATE FUNCTION evolution.cellular_births(t bytea, m bytea) RETURNS TABLE(account_id uuid, request_id evolution.u64, generation evolution.u64, identity evolution.u64, born evolution.u64) LANGUAGE plpgsql IMMUTABLE SET search_path = pg_catalog, pg_temp AS $$ DECLARE n record := evolution.cellular_trace_normal(t, m); BEGIN RETURN QUERY SELECT * FROM evolution.cellular_births_v62(n.t, n.m); END $$; REVOKE ALL ON FUNCTION evolution.cellular_births(bytea,bytea) FROM PUBLIC; ALTER FUNCTION evolution.cellular_mutation_selections(bytea,bytea) RENAME TO cellular_mutation_selections_v62; REVOKE ALL ON FUNCTION evolution.cellular_mutation_selections_v62(bytea,bytea) FROM PUBLIC, :"runtime_role"; 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 n record := evolution.cellular_trace_normal(p_trace, p_manifest); BEGIN RETURN QUERY SELECT * FROM evolution.cellular_mutation_selections_v62(n.t, n.m); END $$; REVOKE ALL ON FUNCTION evolution.cellular_mutation_selections(bytea,bytea) FROM PUBLIC; -- The queue. A row is the operator's exact command; its application is recorded separately. CREATE TABLE evolution.admin_commands ( command_id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY, world_id evolution.u64 NOT NULL, region_id evolution.u64 NOT NULL, kind smallint NOT NULL CHECK (kind BETWEEN 1 AND 6), cell_count integer NOT NULL CHECK (cell_count BETWEEN 0 AND 256), target evolution.u64 NOT NULL, energy evolution.u64 NOT NULL, carbon evolution.u64 NOT NULL, nitrogen evolution.u64 NOT NULL, phosphorus evolution.u64 NOT NULL, other evolution.u64 NOT NULL, author_subject text NOT NULL CHECK (octet_length(author_subject) BETWEEN 1 AND 255), reason text NOT NULL DEFAULT '' CHECK (octet_length(reason) <= 500), created_at timestamptz NOT NULL DEFAULT clock_timestamp(), FOREIGN KEY (world_id, region_id) REFERENCES evolution.region_leases ); CREATE TRIGGER admin_commands_immutable BEFORE UPDATE OR DELETE ON evolution.admin_commands FOR EACH ROW EXECUTE FUNCTION evolution.refuse_history_rewrite(); CREATE TRIGGER admin_commands_no_truncate BEFORE TRUNCATE ON evolution.admin_commands FOR EACH STATEMENT EXECUTE FUNCTION evolution.refuse_history_rewrite(); CREATE TABLE evolution.admin_command_applications ( command_id bigint PRIMARY KEY REFERENCES evolution.admin_commands, commit_id uuid NOT NULL, commit_sequence evolution.u64 NOT NULL, tick evolution.u64 NOT NULL ); CREATE TRIGGER admin_command_applications_immutable BEFORE UPDATE OR DELETE ON evolution.admin_command_applications FOR EACH ROW EXECUTE FUNCTION evolution.refuse_history_rewrite(); -- Queues a command (the same shapes the owner accepts). Spawning takes its identities from the -- world's life allocator, so they never meet a player's. CREATE FUNCTION evolution.admin_enqueue_command_v1(p_world evolution.u64, p_region evolution.u64, p_kind integer, p_count integer, p_target evolution.u64, p_energy evolution.u64, p_carbon evolution.u64, p_nitrogen evolution.u64, p_phosphorus evolution.u64, p_other evolution.u64, p_subject text, p_reason text) RETURNS TABLE (command_id bigint, target evolution.u64) LANGUAGE plpgsql SECURITY DEFINER SET search_path = pg_catalog, pg_temp AS $$ #variable_conflict use_column DECLARE has_amount boolean := p_energy + p_carbon + p_nitrogen + p_phosphorus + p_other > 0; first numeric := p_target; BEGIN IF NOT ((p_kind IN (1, 2) AND p_target > 0 AND p_count = 0 AND has_amount = (p_kind = 2)) OR (p_kind IN (3, 5) AND p_target = 0 AND p_count BETWEEN 1 AND 256 AND has_amount) OR (p_kind = 4 AND p_target = 0 AND p_count = 0 AND has_amount) OR (p_kind = 6 AND p_count BETWEEN 1 AND 64 AND NOT has_amount)) THEN RAISE EXCEPTION 'invalid admin command' USING ERRCODE = '22023'; END IF; IF NOT EXISTS (SELECT 1 FROM evolution.region_leases l WHERE l.world_id = p_world AND l.region_id = p_region) THEN RAISE EXCEPTION 'unknown region' USING ERRCODE = '22023'; END IF; IF p_kind = 6 THEN SELECT a.next_identity INTO first FROM evolution.life_allocators a WHERE a.world_id = p_world FOR UPDATE; IF first IS NULL OR first + p_count > 9223372036854775808 THEN RAISE EXCEPTION 'no identities for wildlife' USING ERRCODE = '22023'; END IF; UPDATE evolution.life_allocators SET next_identity = first + p_count WHERE world_id = p_world; END IF; RETURN QUERY WITH queued AS ( INSERT INTO evolution.admin_commands AS q(world_id, region_id, kind, cell_count, target, energy, carbon, nitrogen, phosphorus, other, author_subject, reason) VALUES (p_world, p_region, p_kind, p_count, first, p_energy, p_carbon, p_nitrogen, p_phosphorus, p_other, p_subject, coalesce(p_reason, '')) RETURNING q.command_id, q.target) SELECT queued.command_id, queued.target FROM queued; END $$; REVOKE ALL ON FUNCTION evolution.admin_enqueue_command_v1(evolution.u64, evolution.u64, integer, integer, evolution.u64, evolution.u64, evolution.u64, evolution.u64, evolution.u64, evolution.u64, text, text) FROM PUBLIC; -- The region's commands not yet published, oldest first. CREATE FUNCTION evolution.load_pending_admin_commands_v1(p_world evolution.u64, p_region evolution.u64) RETURNS TABLE (command_id bigint, kind integer, cell_count integer, target evolution.u64, energy evolution.u64, carbon evolution.u64, nitrogen evolution.u64, phosphorus evolution.u64, other evolution.u64) LANGUAGE sql STABLE SECURITY DEFINER SET search_path = pg_catalog, pg_temp AS $$ SELECT q.command_id, q.kind, q.cell_count, q.target, q.energy, q.carbon, q.nitrogen, q.phosphorus, q.other FROM evolution.admin_commands q WHERE q.world_id = p_world AND q.region_id = p_region AND NOT EXISTS (SELECT 1 FROM evolution.admin_command_applications a WHERE a.command_id = q.command_id) ORDER BY q.command_id LIMIT 64 $$; REVOKE ALL ON FUNCTION evolution.load_pending_admin_commands_v1(evolution.u64, evolution.u64) FROM PUBLIC; GRANT EXECUTE ON FUNCTION evolution.load_pending_admin_commands_v1(evolution.u64, evolution.u64) TO :"runtime_role"; -- The region's last 100 commands, newest first, with the tick each applied at. CREATE FUNCTION evolution.admin_commands_v1(p_world evolution.u64, p_region evolution.u64) RETURNS TABLE (command_id bigint, kind integer, cell_count integer, target evolution.u64, energy evolution.u64, carbon evolution.u64, nitrogen evolution.u64, phosphorus evolution.u64, other evolution.u64, author_subject text, reason text, created_at timestamptz, applied_tick evolution.u64) LANGUAGE sql STABLE SECURITY DEFINER SET search_path = pg_catalog, pg_temp AS $$ SELECT q.command_id, q.kind, q.cell_count, q.target, q.energy, q.carbon, q.nitrogen, q.phosphorus, q.other, q.author_subject, q.reason, q.created_at, a.tick FROM evolution.admin_commands q LEFT JOIN evolution.admin_command_applications a ON a.command_id = q.command_id WHERE q.world_id = p_world AND q.region_id = p_region ORDER BY q.command_id DESC LIMIT 100 $$; REVOKE ALL ON FUNCTION evolution.admin_commands_v1(evolution.u64, evolution.u64) FROM PUBLIC; -- Every command recorded in a published trace is exactly its queue row and applies once. CREATE FUNCTION evolution.bind_cellular_admin_commands(p_manifest bytea, p_trace bytea) RETURNS void LANGUAGE plpgsql SECURITY INVOKER SET search_path = pg_catalog, pg_temp AS $$ DECLARE c evolution.checkpoint_manifest := evolution.parse_checkpoint_manifest(p_manifest); r record; BEGIN FOR r IN SELECT * FROM evolution.cellular_trace_admin(p_trace, p_manifest) LOOP IF NOT EXISTS (SELECT 1 FROM evolution.admin_commands q WHERE q.command_id = r.command_id AND q.world_id = c.world_id AND q.region_id = c.region_id AND q.kind = r.kind AND q.cell_count = r.cell_count AND q.target = r.target AND q.energy = r.energy AND q.carbon = r.carbon AND q.nitrogen = r.nitrogen AND q.phosphorus = r.phosphorus AND q.other = r.other) THEN RAISE EXCEPTION 'admin command differs from its queue' USING ERRCODE = '22023'; END IF; IF EXISTS (SELECT 1 FROM evolution.admin_command_applications a WHERE a.command_id = r.command_id AND (a.commit_id <> c.commit_id OR a.tick <> r.tick)) THEN RAISE EXCEPTION 'admin command already applied' USING ERRCODE = 'EVL07'; END IF; INSERT INTO evolution.admin_command_applications(command_id, commit_id, commit_sequence, tick) VALUES (r.command_id, c.commit_id, c.commit_sequence, r.tick) ON CONFLICT (command_id) DO NOTHING; END LOOP; END $$; REVOKE ALL ON FUNCTION evolution.bind_cellular_admin_commands(bytea, bytea) FROM PUBLIC; -- Schema 59's publishers, binding admin commands in the same transaction. ALTER FUNCTION evolution.publish_cellular_checkpoint(bytea,bytea,bytea,bytea) RENAME TO publish_cellular_checkpoint_v62; REVOKE ALL ON FUNCTION evolution.publish_cellular_checkpoint_v62(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 $$ DECLARE h record; BEGIN SELECT * INTO h FROM evolution.publish_cellular_checkpoint_v62(p_manifest, p_decisions, p_actions, p_trace); IF NOT FOUND THEN RAISE EXCEPTION 'publication returned no head' USING ERRCODE = 'XX000'; END IF; PERFORM evolution.bind_cellular_admin_commands(p_manifest, p_trace); RETURN QUERY SELECT h.region_frame, h.head_sequence, h.head_commit, h.head_digest, h.head_tick; END $$; REVOKE ALL ON FUNCTION evolution.publish_cellular_checkpoint(bytea,bytea,bytea,bytea) FROM PUBLIC; GRANT EXECUTE ON FUNCTION evolution.publish_cellular_checkpoint(bytea,bytea,bytea,bytea) TO :"runtime_role"; ALTER FUNCTION evolution.publish_cellular_mutation_checkpoint(bytea,bytea,bytea,bytea,bytea,bytea) RENAME TO publish_cellular_mutation_checkpoint_v62; REVOKE ALL ON FUNCTION evolution.publish_cellular_mutation_checkpoint_v62(bytea,bytea,bytea,bytea, bytea,bytea) FROM PUBLIC, :"runtime_role"; 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 h record; BEGIN SELECT * INTO h FROM evolution.publish_cellular_mutation_checkpoint_v62(p_manifest, p_decisions, p_actions, p_trace, p_mutations, p_results); IF NOT FOUND THEN RAISE EXCEPTION 'publication returned no head' USING ERRCODE = 'XX000'; END IF; PERFORM evolution.bind_cellular_admin_commands(p_manifest, p_trace); RETURN QUERY SELECT h.region_frame, h.head_sequence, h.head_commit, h.head_digest, h.head_tick; END $$; REVOKE ALL ON FUNCTION evolution.publish_cellular_mutation_checkpoint(bytea,bytea,bytea,bytea, bytea,bytea) FROM PUBLIC; GRANT EXECUTE ON FUNCTION evolution.publish_cellular_mutation_checkpoint(bytea,bytea,bytea,bytea, bytea,bytea) TO :"runtime_role"; INSERT INTO evolution.schema_migrations(version,sha256) VALUES(63,:'migration_sha_63');