Files
aevolution/migrations/0063_admin_commands.sql
T
dingoandClaude Opus 5.5 b1cc3b121b
Foundation / checks (checks) (push) Successful in 5s
Foundation / checks (client) (push) Successful in 5s
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 5s
Foundation / checks (network) (push) Successful in 4s
Foundation / checks (postgres) (push) Successful in 5s
Foundation / checks (tsan) (push) Successful in 5s
Foundation / postgres-tools (push) Successful in 30s
Foundation / server-image (push) Successful in 4m44s
Foundation / image (push) Successful in 5m33s
feat(admin): live admin commands in trace 5 (schema 63)
The admin portal can now spawn wildlife, add bubbles, add to or release the
spent pool, remove a cell and grant a cell's reserve on a running rules-13
region (ADR-0182 section 10). No new owner format or region opening.

- Trace 5: trace 4 plus 64-byte command records counted in the tick header's
  last word; a batch without commands stays trace 4 (older builds replay it).
  Bundle 15 admits trace 5.
- CellularLives::admin_candidate applies a tick's commands after its births,
  each on a copy kept only when it applies and closes: imports through the
  boundary ledger, removals into the spent pool with a new `removed` corpse
  cause, spawned roots via the ADR-0180 seed (now a shared helper) funded by
  an exact import. Refused commands change nothing.
- Schema 63: the immutable admin_commands queue (spawn identities from the
  life allocator), pending/history reads, and binding of every recorded
  command exactly once inside both cellular publishers; the SQL trace parsers
  read trace 5 through its trace-4 normal form.
- The region polls pending commands every 2 s and appends up to 16 per tick;
  the admin API and portal gain region actions, per-cell Remove/Grant and the
  command history.
- Fixes an existing test that did not advance its head after a tick commit.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-27 17:14:04 -04:00

342 lines
18 KiB
PL/PgSQL

-- 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');