-- M10.8a probe records and their cross-region handoff (ADR-0096). EXPERIMENT: a probe is a -- non-biological engineering entity (ADR-0094) with a durable home, so that authority -- transfer between regions can be proven before organisms are controllable. Nothing here -- is a game rule. -- -- One row per (world, account) holds the probe and its single owning region, so ownership -- is unique and the test inventory is conserved by construction: a transfer never copies -- it, it moves the row's ownership in one transaction. A transfer is a durable state -- machine: prepared (source froze the probe at its final state) -> staged (destination -- validated and durably accepted it) -> committed (ownership switched) or aborted (before -- commit only; the source resumes). Every retry returns the recorded outcome. -- -- The runtime reaches both tables only through the functions below, each of which first -- requires the caller's exact unexpired region lease. Lock order (extends schema v11): -- upgrade lock (shared) -> the caller's region lease row -> probe record row -> transfer -- row. No function locks another region's lease row: a frozen record is what stops the -- source (under any epoch) from acting while a transfer is open. -- -- SQLSTATE: EVL13 probe fenced (not owned by the caller, wrong generation, frozen, or a -- transfer for another region); EVL14 unknown transfer; EVL15 transfer not staged by the -- caller's current epoch. CREATE TABLE evolution.probe_records ( world_id evolution.u64 NOT NULL, account_id uuid NOT NULL CHECK (account_id <> '00000000-0000-0000-0000-000000000000'), region_id evolution.u64 NOT NULL, generation evolution.u64 NOT NULL CHECK (generation > 0), x bigint NOT NULL, y bigint NOT NULL, z bigint NOT NULL, inventory evolution.u64 NOT NULL, transfer_id uuid, -- The open transfer while frozen; NULL while active. PRIMARY KEY (world_id, account_id) ); CREATE TABLE evolution.probe_transfers ( world_id evolution.u64 NOT NULL, transfer_id uuid NOT NULL CHECK (transfer_id <> '00000000-0000-0000-0000-000000000000'), account_id uuid NOT NULL, state text NOT NULL CHECK (state IN ('prepared', 'staged', 'committed', 'aborted')), generation evolution.u64 NOT NULL, -- The record's generation when prepared. source_region evolution.u64 NOT NULL, source_epoch evolution.u64 NOT NULL, destination_region evolution.u64 NOT NULL, destination_epoch evolution.u64, x bigint NOT NULL, y bigint NOT NULL, z bigint NOT NULL, inventory evolution.u64 NOT NULL, prepared_at timestamptz NOT NULL, decided_at timestamptz, PRIMARY KEY (world_id, transfer_id), CHECK (source_region <> destination_region), CHECK (state NOT IN ('staged', 'committed') OR destination_epoch IS NOT NULL), CHECK ((state IN ('committed', 'aborted')) = (decided_at IS NOT NULL)) ); -- At most one open transfer per probe. CREATE UNIQUE INDEX probe_transfers_open ON evolution.probe_transfers (world_id, account_id) WHERE state IN ('prepared', 'staged'); REVOKE ALL ON evolution.probe_records, evolution.probe_transfers FROM PUBLIC; -- The probe of `p_account`, created owned by the caller's region at the given position and -- inventory when the world has none yet (otherwise unchanged). The caller acts for it only -- when it owns it (region_id) and it is not frozen (transfer_id NULL). CREATE FUNCTION evolution.open_probe(p_world evolution.u64, p_region evolution.u64, p_holder uuid, p_epoch evolution.u64, p_account uuid, p_x bigint, p_y bigint, p_z bigint, p_inventory evolution.u64) RETURNS TABLE (owner_region evolution.u64, probe_generation evolution.u64, probe_x bigint, probe_y bigint, probe_z bigint, probe_inventory evolution.u64, open_transfer uuid) LANGUAGE plpgsql SECURITY DEFINER SET search_path = pg_catalog, pg_temp AS $$ DECLARE r evolution.probe_records%ROWTYPE; BEGIN IF p_account IS NULL OR p_account = '00000000-0000-0000-0000-000000000000' OR p_x IS NULL OR p_y IS NULL OR p_z IS NULL OR p_inventory IS NULL THEN RAISE EXCEPTION 'invalid probe request' USING ERRCODE = '22023'; END IF; PERFORM evolution.check_region_lease(p_world, p_region, p_holder, p_epoch); INSERT INTO evolution.probe_records(world_id, account_id, region_id, generation, x, y, z, inventory) VALUES (p_world, p_account, p_region, 1, p_x, p_y, p_z, p_inventory) ON CONFLICT DO NOTHING; SELECT * INTO r FROM evolution.probe_records p WHERE p.world_id = p_world AND p.account_id = p_account; RETURN QUERY SELECT r.region_id, r.generation, r.x, r.y, r.z, r.inventory, r.transfer_id; END $$; -- Records the active probe's position (session end, periodic); never per tick. CREATE FUNCTION evolution.save_probe(p_world evolution.u64, p_region evolution.u64, p_holder uuid, p_epoch evolution.u64, p_account uuid, p_generation evolution.u64, p_x bigint, p_y bigint, p_z bigint) RETURNS void LANGUAGE plpgsql SECURITY DEFINER SET search_path = pg_catalog, pg_temp AS $$ BEGIN IF p_account IS NULL OR p_generation IS NULL OR p_x IS NULL OR p_y IS NULL OR p_z IS NULL THEN RAISE EXCEPTION 'invalid probe request' USING ERRCODE = '22023'; END IF; PERFORM evolution.check_region_lease(p_world, p_region, p_holder, p_epoch); UPDATE evolution.probe_records p SET x = p_x, y = p_y, z = p_z WHERE p.world_id = p_world AND p.account_id = p_account AND p.region_id = p_region AND p.generation = p_generation AND p.transfer_id IS NULL; IF NOT FOUND THEN RAISE EXCEPTION 'probe fenced' USING ERRCODE = 'EVL13'; END IF; END $$; -- Columns every transfer function returns: the recorded transfer as it now stands. CREATE TYPE evolution.probe_transfer_row AS ( transfer_state text, transfer_account uuid, transfer_generation evolution.u64, transfer_source evolution.u64, transfer_destination evolution.u64, transfer_x bigint, transfer_y bigint, transfer_z bigint, transfer_inventory evolution.u64); CREATE FUNCTION evolution.probe_transfer_of(t evolution.probe_transfers) RETURNS evolution.probe_transfer_row LANGUAGE sql IMMUTABLE SET search_path = pg_catalog, pg_temp AS $$ SELECT ROW(t.state, t.account_id, t.generation, t.source_region, t.destination_region, t.x, t.y, t.z, t.inventory)::evolution.probe_transfer_row $$; -- Source: freezes its active probe at its final state under `p_transfer` for -- `p_destination`. A retry with the same transfer id returns it whatever its state. CREATE FUNCTION evolution.prepare_probe_transfer(p_world evolution.u64, p_region evolution.u64, p_holder uuid, p_epoch evolution.u64, p_account uuid, p_generation evolution.u64, p_transfer uuid, p_destination evolution.u64, p_x bigint, p_y bigint, p_z bigint) RETURNS SETOF evolution.probe_transfer_row LANGUAGE plpgsql SECURITY DEFINER SET search_path = pg_catalog, pg_temp AS $$ DECLARE r evolution.probe_records%ROWTYPE; t evolution.probe_transfers%ROWTYPE; now_t timestamptz; BEGIN IF p_account IS NULL OR p_generation IS NULL OR p_transfer IS NULL OR p_transfer = '00000000-0000-0000-0000-000000000000' OR p_destination IS NULL OR p_x IS NULL OR p_y IS NULL OR p_z IS NULL OR p_destination = p_region THEN RAISE EXCEPTION 'invalid probe request' USING ERRCODE = '22023'; END IF; now_t := evolution.check_region_lease(p_world, p_region, p_holder, p_epoch); SELECT * INTO r FROM evolution.probe_records p WHERE p.world_id = p_world AND p.account_id = p_account FOR UPDATE; SELECT * INTO t FROM evolution.probe_transfers x WHERE x.world_id = p_world AND x.transfer_id = p_transfer FOR UPDATE; IF FOUND THEN IF t.account_id <> p_account OR t.source_region <> p_region THEN RAISE EXCEPTION 'probe fenced' USING ERRCODE = 'EVL13'; END IF; RETURN NEXT evolution.probe_transfer_of(t); -- Retry: the recorded outcome. RETURN; END IF; IF r.account_id IS NULL OR r.region_id <> p_region OR r.generation <> p_generation OR r.transfer_id IS NOT NULL THEN RAISE EXCEPTION 'probe fenced' USING ERRCODE = 'EVL13'; END IF; -- The destination must be a provisioned region of the world. IF NOT EXISTS (SELECT 1 FROM evolution.region_leases l WHERE l.world_id = p_world AND l.region_id = p_destination) THEN RAISE EXCEPTION 'region not provisioned' USING ERRCODE = 'EVL04'; END IF; INSERT INTO evolution.probe_transfers(world_id, transfer_id, account_id, state, generation, source_region, source_epoch, destination_region, x, y, z, inventory, prepared_at) VALUES (p_world, p_transfer, p_account, 'prepared', r.generation, p_region, p_epoch, p_destination, p_x, p_y, p_z, r.inventory, now_t) RETURNING * INTO t; UPDATE evolution.probe_records p SET x = p_x, y = p_y, z = p_z, transfer_id = p_transfer WHERE p.world_id = p_world AND p.account_id = p_account; RETURN NEXT evolution.probe_transfer_of(t); END $$; -- Destination: durably accepts a prepared transfer under its current epoch (again after -- its own restart). Committed or aborted transfers are returned unchanged. CREATE FUNCTION evolution.stage_probe_transfer(p_world evolution.u64, p_region evolution.u64, p_holder uuid, p_epoch evolution.u64, p_transfer uuid) RETURNS SETOF evolution.probe_transfer_row LANGUAGE plpgsql SECURITY DEFINER SET search_path = pg_catalog, pg_temp AS $$ DECLARE t evolution.probe_transfers%ROWTYPE; BEGIN IF p_transfer IS NULL THEN RAISE EXCEPTION 'invalid probe request' USING ERRCODE = '22023'; END IF; PERFORM evolution.check_region_lease(p_world, p_region, p_holder, p_epoch); SELECT * INTO t FROM evolution.probe_transfers x WHERE x.world_id = p_world AND x.transfer_id = p_transfer FOR UPDATE; IF NOT FOUND THEN RAISE EXCEPTION 'unknown transfer' USING ERRCODE = 'EVL14'; END IF; IF t.destination_region <> p_region THEN RAISE EXCEPTION 'probe fenced' USING ERRCODE = 'EVL13'; END IF; IF t.state IN ('prepared', 'staged') THEN UPDATE evolution.probe_transfers x SET state = 'staged', destination_epoch = p_epoch WHERE x.world_id = p_world AND x.transfer_id = p_transfer RETURNING * INTO t; END IF; RETURN NEXT evolution.probe_transfer_of(t); END $$; -- Destination: the one authority switch. Requires the transfer staged by the caller's -- current epoch and the record still frozen under it; moves ownership (generation + 1) and -- the final state in one transaction. A retry returns the recorded outcome. CREATE FUNCTION evolution.commit_probe_transfer(p_world evolution.u64, p_region evolution.u64, p_holder uuid, p_epoch evolution.u64, p_transfer uuid) RETURNS SETOF evolution.probe_transfer_row LANGUAGE plpgsql SECURITY DEFINER SET search_path = pg_catalog, pg_temp AS $$ DECLARE r evolution.probe_records%ROWTYPE; t evolution.probe_transfers%ROWTYPE; now_t timestamptz; account uuid; BEGIN IF p_transfer IS NULL THEN RAISE EXCEPTION 'invalid probe request' USING ERRCODE = '22023'; END IF; now_t := evolution.check_region_lease(p_world, p_region, p_holder, p_epoch); SELECT x.account_id INTO account FROM evolution.probe_transfers x WHERE x.world_id = p_world AND x.transfer_id = p_transfer; IF NOT FOUND THEN RAISE EXCEPTION 'unknown transfer' USING ERRCODE = 'EVL14'; END IF; SELECT * INTO r FROM evolution.probe_records p WHERE p.world_id = p_world AND p.account_id = account FOR UPDATE; SELECT * INTO t FROM evolution.probe_transfers x WHERE x.world_id = p_world AND x.transfer_id = p_transfer FOR UPDATE; IF t.destination_region <> p_region THEN RAISE EXCEPTION 'probe fenced' USING ERRCODE = 'EVL13'; END IF; IF t.state IN ('committed', 'aborted') THEN RETURN NEXT evolution.probe_transfer_of(t); RETURN; END IF; IF t.state <> 'staged' OR t.destination_epoch <> p_epoch THEN RAISE EXCEPTION 'transfer not staged' USING ERRCODE = 'EVL15'; END IF; IF r.transfer_id IS DISTINCT FROM p_transfer OR r.region_id <> t.source_region OR r.generation <> t.generation THEN RAISE EXCEPTION 'probe fenced' USING ERRCODE = 'EVL13'; -- Unreachable by construction. END IF; IF r.generation = 18446744073709551615 THEN RAISE EXCEPTION 'probe generations exhausted' USING ERRCODE = 'EVL05'; END IF; UPDATE evolution.probe_records p SET region_id = p_region, generation = r.generation + 1, x = t.x, y = t.y, z = t.z, transfer_id = NULL WHERE p.world_id = p_world AND p.account_id = account; UPDATE evolution.probe_transfers x SET state = 'committed', decided_at = now_t WHERE x.world_id = p_world AND x.transfer_id = p_transfer RETURNING * INTO t; RETURN NEXT evolution.probe_transfer_of(t); END $$; -- Source or destination: abandons a transfer before its commit (durable); the probe is -- active again at its source. After a commit, the committed transfer is returned. CREATE FUNCTION evolution.abort_probe_transfer(p_world evolution.u64, p_region evolution.u64, p_holder uuid, p_epoch evolution.u64, p_transfer uuid) RETURNS SETOF evolution.probe_transfer_row LANGUAGE plpgsql SECURITY DEFINER SET search_path = pg_catalog, pg_temp AS $$ DECLARE t evolution.probe_transfers%ROWTYPE; now_t timestamptz; account uuid; BEGIN IF p_transfer IS NULL THEN RAISE EXCEPTION 'invalid probe request' USING ERRCODE = '22023'; END IF; now_t := evolution.check_region_lease(p_world, p_region, p_holder, p_epoch); SELECT x.account_id INTO account FROM evolution.probe_transfers x WHERE x.world_id = p_world AND x.transfer_id = p_transfer; IF NOT FOUND THEN RAISE EXCEPTION 'unknown transfer' USING ERRCODE = 'EVL14'; END IF; PERFORM 1 FROM evolution.probe_records p WHERE p.world_id = p_world AND p.account_id = account FOR UPDATE; SELECT * INTO t FROM evolution.probe_transfers x WHERE x.world_id = p_world AND x.transfer_id = p_transfer FOR UPDATE; IF p_region NOT IN (t.source_region, t.destination_region) THEN RAISE EXCEPTION 'probe fenced' USING ERRCODE = 'EVL13'; END IF; IF t.state IN ('prepared', 'staged') THEN UPDATE evolution.probe_records p SET transfer_id = NULL WHERE p.world_id = p_world AND p.account_id = account AND p.transfer_id = p_transfer; UPDATE evolution.probe_transfers x SET state = 'aborted', decided_at = now_t WHERE x.world_id = p_world AND x.transfer_id = p_transfer RETURNING * INTO t; END IF; RETURN NEXT evolution.probe_transfer_of(t); END $$; -- Any region of the world may read a transfer (recovery, routing); no row when unknown. CREATE FUNCTION evolution.find_probe_transfer(p_world evolution.u64, p_region evolution.u64, p_holder uuid, p_epoch evolution.u64, p_transfer uuid) RETURNS SETOF evolution.probe_transfer_row LANGUAGE plpgsql SECURITY DEFINER SET search_path = pg_catalog, pg_temp AS $$ DECLARE t evolution.probe_transfers%ROWTYPE; BEGIN IF p_transfer IS NULL THEN RAISE EXCEPTION 'invalid probe request' USING ERRCODE = '22023'; END IF; PERFORM evolution.check_region_lease(p_world, p_region, p_holder, p_epoch); SELECT * INTO t FROM evolution.probe_transfers x WHERE x.world_id = p_world AND x.transfer_id = p_transfer; IF FOUND THEN RETURN NEXT evolution.probe_transfer_of(t); END IF; END $$; -- Destination: takes the account's durable control (schema v10) for its session on the -- strength of a transfer committed to it, instead of a newer grant serial (a handoff ticket -- carries none). As for claims, another region's unexpired control must be outlived (the -- source releases its control when it prepares, so normally there is nothing to wait for). CREATE FUNCTION evolution.handoff_account_control(p_world evolution.u64, p_region evolution.u64, p_holder uuid, p_epoch evolution.u64, p_account uuid, p_transfer uuid, p_session evolution.u64, p_duration_ms integer) RETURNS TABLE (control_generation evolution.u64, wait_ms integer, granted_ms integer) LANGUAGE plpgsql SECURITY DEFINER SET search_path = pg_catalog, pg_temp AS $$ DECLARE c evolution.account_controls%ROWTYPE; t timestamptz; pending interval; BEGIN IF p_account IS NULL OR p_transfer IS NULL OR p_session IS NULL OR p_session = 0 OR p_duration_ms IS NULL OR p_duration_ms NOT BETWEEN 1000 AND 60000 THEN RAISE EXCEPTION 'invalid control request' USING ERRCODE = '22023'; END IF; PERFORM evolution.check_region_lease(p_world, p_region, p_holder, p_epoch); IF NOT EXISTS (SELECT 1 FROM evolution.probe_transfers x WHERE x.world_id = p_world AND x.transfer_id = p_transfer AND x.account_id = p_account AND x.destination_region = p_region AND x.state = 'committed') THEN RAISE EXCEPTION 'account control fenced' USING ERRCODE = 'EVL12'; END IF; SELECT * INTO c FROM evolution.account_controls a WHERE a.world_id = p_world AND a.account_id = p_account FOR UPDATE; IF NOT FOUND THEN -- The account never logged in with a grant: nothing to hand off. RAISE EXCEPTION 'account control fenced' USING ERRCODE = 'EVL12'; END IF; t := clock_timestamp(); IF c.generation = 18446744073709551615 THEN RAISE EXCEPTION 'control generations exhausted' USING ERRCODE = 'EVL05'; END IF; pending := CASE WHEN c.region_id IS NULL OR c.expires_at <= t THEN interval '0' WHEN c.region_id = p_region AND c.region_epoch <= p_epoch THEN interval '0' ELSE c.expires_at - t END; UPDATE evolution.account_controls a SET generation = c.generation + 1, region_id = p_region, region_epoch = p_epoch, session_id = p_session, expires_at = t + pending + p_duration_ms * interval '1 millisecond' WHERE a.world_id = p_world AND a.account_id = p_account RETURNING a.generation INTO control_generation; wait_ms := ceil(extract(epoch FROM pending) * 1000)::integer; granted_ms := p_duration_ms; RETURN NEXT; END $$; REVOKE ALL ON FUNCTION evolution.open_probe(evolution.u64, evolution.u64, uuid, evolution.u64, uuid, bigint, bigint, bigint, evolution.u64), evolution.save_probe(evolution.u64, evolution.u64, uuid, evolution.u64, uuid, evolution.u64, bigint, bigint, bigint), evolution.probe_transfer_of(evolution.probe_transfers), evolution.prepare_probe_transfer(evolution.u64, evolution.u64, uuid, evolution.u64, uuid, evolution.u64, uuid, evolution.u64, bigint, bigint, bigint), evolution.stage_probe_transfer(evolution.u64, evolution.u64, uuid, evolution.u64, uuid), evolution.commit_probe_transfer(evolution.u64, evolution.u64, uuid, evolution.u64, uuid), evolution.abort_probe_transfer(evolution.u64, evolution.u64, uuid, evolution.u64, uuid), evolution.find_probe_transfer(evolution.u64, evolution.u64, uuid, evolution.u64, uuid), evolution.handoff_account_control(evolution.u64, evolution.u64, uuid, evolution.u64, uuid, uuid, evolution.u64, integer) FROM PUBLIC; GRANT EXECUTE ON FUNCTION evolution.open_probe(evolution.u64, evolution.u64, uuid, evolution.u64, uuid, bigint, bigint, bigint, evolution.u64), evolution.save_probe(evolution.u64, evolution.u64, uuid, evolution.u64, uuid, evolution.u64, bigint, bigint, bigint), evolution.prepare_probe_transfer(evolution.u64, evolution.u64, uuid, evolution.u64, uuid, evolution.u64, uuid, evolution.u64, bigint, bigint, bigint), evolution.stage_probe_transfer(evolution.u64, evolution.u64, uuid, evolution.u64, uuid), evolution.commit_probe_transfer(evolution.u64, evolution.u64, uuid, evolution.u64, uuid), evolution.abort_probe_transfer(evolution.u64, evolution.u64, uuid, evolution.u64, uuid), evolution.find_probe_transfer(evolution.u64, evolution.u64, uuid, evolution.u64, uuid), evolution.handoff_account_control(evolution.u64, evolution.u64, uuid, evolution.u64, uuid, uuid, evolution.u64, integer) TO :"runtime_role"; INSERT INTO evolution.schema_migrations(version, sha256) VALUES (12, :'migration_sha_12');