@consiliency/agent-board-schema 1.5.0 → 1.9.0

package/tests/agent_board_roomlink.test.sql

@@ -0,0 +1,364 @@
+-- ROOMLINK pgTAP: shareable board invite links (create/redeem/revoke) + the
+-- enroll-on-redeem binding. Exercises the panel's correctness invariants:
+--   * grantor-bounded mint; owner-preset forbidden; admin-preset requires a use cap
+--     and a <=7d TTL (R-LINK-3),
+--   * create actor-guard (_resolved_actor_agent_id),
+--   * atomic rank-max redemption that never downgrades a higher role (R-LINK-1),
+--   * idempotent replay of a maxed link (M1) + exhaustion + expiry + revoked
+--     (uniform 42501),
+--   * suspended-creator refusal (R-LINK-2) + creator-ceiling re-bind,
+--   * kicked-agent ('removed') refusal (R-LINK-7),
+--   * redeem actor fail-closed on null (suspended principal),
+--   * _redeem_invite_for_agent is NOT authenticated-callable,
+--   * enroll_federated_identity(...,p_invite_code) soft-honors a code
+--     (invite_redeemed=true) and soft-fails a bad one (enroll still succeeds).
+--
+-- Runs as the postgres db role; request.jwt.claim.role toggles _is_service_role()
+-- (''/service_role => true, 'authenticated' => false) and request.jwt.claim.sub picks
+-- the acting agent. Fixture style mirrors agent_board_roomown.test.sql. The two
+-- Ed25519 public keys + fingerprints are reused from agent_board_enroll_federated_identity.
+create extension if not exists pgtap with schema extensions;
+set search_path = extensions, public, agent_board;
+
+begin;
+
+select plan(34);
+
+create temp table _lf (
+  board uuid,
+  alice uuid, bob uuid, carol uuid, carol2 uuid, carol3 uuid,
+  dave uuid, erin uuid, frank uuid, gus uuid, grimm uuid, harry uuid, mallory uuid,
+  alice_user uuid, bob_user uuid, carol_user uuid, mallory_user uuid,
+  code_member text, code_maxed text, code_public text, code_mallory text,
+  code_harry text, code_revoke text, code_revoke_authz text, code_enroll text,
+  code_expired text,
+  prov_iss text, prov_sub text, prov_slug text,
+  pub1 text, fp1 text, pub2 text, fp2 text
+) on commit drop;
+
+create temp table _er (label text, agent_id uuid, invite_redeemed boolean) on commit drop;
+
+do $$
+declare
+  v_suffix text := replace(substr(gen_random_uuid()::text, 1, 8), '-', '');
+  v_alice_user uuid; v_bob_user uuid; v_carol_user uuid; v_mallory_user uuid;
+  v_alice uuid := gen_random_uuid();
+  v_bob uuid := gen_random_uuid();
+  v_carol uuid := gen_random_uuid();
+  v_carol2 uuid := gen_random_uuid();
+  v_carol3 uuid := gen_random_uuid();
+  v_dave uuid := gen_random_uuid();
+  v_erin uuid := gen_random_uuid();
+  v_frank uuid := gen_random_uuid();
+  v_gus uuid := gen_random_uuid();
+  v_grimm uuid := gen_random_uuid();
+  v_harry uuid := gen_random_uuid();
+  v_mallory uuid := gen_random_uuid();
+  v_board uuid;
+  v_code_member text; v_code_maxed text; v_code_public text; v_code_mallory text;
+  v_code_harry text; v_code_revoke text; v_code_revoke_authz text; v_code_enroll text;
+  v_code_expired text := 'expired-code-' || v_suffix;
+  v_prov_iss text := 'https://roomlink-fed-' || v_suffix || '.test';
+begin
+  v_alice_user := public.ensure_github_user('rl-alice-' || v_suffix, 'rl-alice-' || v_suffix || '@example.test', 'rl-alice-' || v_suffix, 'RL Alice');
+  v_bob_user := public.ensure_github_user('rl-bob-' || v_suffix, 'rl-bob-' || v_suffix || '@example.test', 'rl-bob-' || v_suffix, 'RL Bob');
+  v_carol_user := public.ensure_github_user('rl-carol-' || v_suffix, 'rl-carol-' || v_suffix || '@example.test', 'rl-carol-' || v_suffix, 'RL Carol');
+  v_mallory_user := public.ensure_github_user('rl-mallory-' || v_suffix, 'rl-mallory-' || v_suffix || '@example.test', 'rl-mallory-' || v_suffix, 'RL Mallory');
+
+  insert into agent_board.agents(id, agent_type, handle, display_name, status, auth_user_id, owner_user_id)
+  values
+    (v_alice, 'agent', 'rl-alice-' || v_suffix, 'RL Alice', 'active', v_alice_user, v_alice_user),
+    (v_bob, 'agent', 'rl-bob-' || v_suffix, 'RL Bob', 'active', v_bob_user, v_bob_user),
+    (v_carol, 'agent', 'rl-carol-' || v_suffix, 'RL Carol', 'active', v_carol_user, v_carol_user),
+    -- mallory is SUSPENDED but still holds an admin membership + a valid auth user:
+    -- current_agent_id() filters status='active' (fail-closed redeem), and R-LINK-2
+    -- refuses redeeming her outstanding link.
+    (v_mallory, 'agent', 'rl-mallory-' || v_suffix, 'RL Mallory', 'suspended', v_mallory_user, v_mallory_user),
+    (v_carol2, 'agent', 'rl-carol2-' || v_suffix, 'RL Carol2', 'active', null, null),
+    (v_carol3, 'agent', 'rl-carol3-' || v_suffix, 'RL Carol3', 'active', null, null),
+    (v_dave, 'agent', 'rl-dave-' || v_suffix, 'RL Dave', 'active', null, null),
+    (v_erin, 'agent', 'rl-erin-' || v_suffix, 'RL Erin', 'active', null, null),
+    (v_frank, 'agent', 'rl-frank-' || v_suffix, 'RL Frank', 'active', null, null),
+    (v_gus, 'agent', 'rl-gus-' || v_suffix, 'RL Gus', 'active', null, null),
+    (v_grimm, 'agent', 'rl-grimm-' || v_suffix, 'RL Grimm', 'active', null, null),
+    (v_harry, 'agent', 'rl-harry-' || v_suffix, 'RL Harry', 'active', null, null);
+
+  -- Alice creates board B (service_role null-actor -> supplied arg honored): create_board
+  -- seeds Alice's joined owner membership.
+  select board_id into v_board
+    from agent_board.create_board(v_alice, 'roomlink-board-' || v_suffix, 'ROOMLINK Board', 'roomlink test', '{}'::jsonb, 'private');
+
+  -- Pre-existing memberships used by the redemption cases.
+  insert into agent_board.board_memberships(board_id, agent_id, membership_state, created_by_agent_id, role)
+  values
+    (v_board, v_dave, 'joined', v_alice, 'admin'),      -- no-downgrade target
+    (v_board, v_grimm, 'joined', v_alice, 'observer'),  -- too-low to mint member links
+    (v_board, v_harry, 'joined', v_alice, 'admin'),     -- mints an admin link, later demoted
+    (v_board, v_mallory, 'joined', v_alice, 'admin');   -- mints a link, agent suspended
+  -- Erin was kicked (removed): the active partial index does not cover this row, so a
+  -- redeem must explicitly refuse rather than seat a fresh joined row.
+  insert into agent_board.board_memberships(board_id, agent_id, membership_state, created_by_agent_id, role, left_at)
+  values (v_board, v_erin, 'removed', v_alice, 'member', now());
+
+  -- Mint links (service_role context: default role '', session_user postgres).
+  select code into v_code_member
+    from agent_board.create_invite_link(v_board, 'member', 'joined', null, null, v_alice, '{}'::jsonb);
+  select code into v_code_maxed
+    from agent_board.create_invite_link(v_board, 'member', 'joined', 1, null, v_alice, '{}'::jsonb);
+  select code into v_code_public
+    from agent_board.create_invite_link(v_board, 'member', 'joined', null, null, v_alice, '{}'::jsonb);
+  select code into v_code_revoke
+    from agent_board.create_invite_link(v_board, 'member', 'joined', null, null, v_alice, '{}'::jsonb);
+  select code into v_code_revoke_authz
+    from agent_board.create_invite_link(v_board, 'member', 'joined', null, null, v_alice, '{}'::jsonb);
+  select code into v_code_enroll
+    from agent_board.create_invite_link(v_board, 'member', 'joined', null, null, v_alice, '{}'::jsonb);
+  -- Mallory (admin membership) mints a member link; her agent is suspended.
+  select code into v_code_mallory
+    from agent_board.create_invite_link(v_board, 'member', 'joined', null, null, v_mallory, '{}'::jsonb);
+  -- Harry (admin) mints an ADMIN link (use cap required); harry is then demoted.
+  select code into v_code_harry
+    from agent_board.create_invite_link(v_board, 'admin', 'joined', 2, null, v_harry, '{}'::jsonb);
+  update agent_board.board_memberships bm set role = 'member'
+   where bm.board_id = v_board and bm.agent_id = v_harry;
+
+  -- An already-expired token (direct insert; create_invite_link rejects a past TTL).
+  insert into agent_board.board_invite_tokens(code, board_id, preset_role, preset_membership_state, expires_at, created_by_agent_id)
+  values (v_code_expired, v_board, 'member', 'joined', now() - interval '1 day', v_alice);
+
+  -- Approved identity provider for the enroll-binding cases.
+  insert into agent_board.identity_providers
+    (issuer, audience, supported, policy_approved, allowed_scopes, allowed_board_scopes, allowed_agent_kinds)
+  values (v_prov_iss, 'message-board', true, true, '{}', '{}', '{agent,human}');
+
+  insert into _lf values (
+    v_board, v_alice, v_bob, v_carol, v_carol2, v_carol3, v_dave, v_erin, v_frank,
+    v_gus, v_grimm, v_harry, v_mallory,
+    v_alice_user, v_bob_user, v_carol_user, v_mallory_user,
+    v_code_member, v_code_maxed, v_code_public, v_code_mallory, v_code_harry,
+    v_code_revoke, v_code_revoke_authz, v_code_enroll, v_code_expired,
+    v_prov_iss, 'portal|' || v_suffix, 'rl-enrollee-' || v_suffix,
+    'eRHZmllEy_TZHAG2zB-Qe_a5BFLkaavMTazWWfaE3f0',
+    'sha256:z8d5LQPfBMYnfZfvu8wVz684_jkp578-SPDU2OMObS8',
+    'yd_DIFGWGusVg3SbktDJQ1bE5UWvtR33xln4b05JIhk',
+    'sha256:NeVC2vx1MbTY56jUwJcLLr6YwB4IKCERsXWbUwhf5pA'
+  );
+end
+$$;
+
+-- === A. create validation ============================================== (7)
+-- 1
+select throws_ok(
+  (select format($q$select agent_board.create_invite_link(%L::uuid, 'owner', 'joined', 1, null, %L::uuid)$q$, board, alice) from _lf),
+  '22023', 'owner presets are not invite-linkable',
+  'create_invite_link forbids the owner preset (R-LINK-3)');
+-- 2
+select throws_ok(
+  (select format($q$select agent_board.create_invite_link(%L::uuid, 'admin', 'joined', null, null, %L::uuid)$q$, board, alice) from _lf),
+  '22023', 'admin invite links require a bounded p_max_uses',
+  'admin preset requires a use cap (R-LINK-3)');
+-- 3
+select throws_ok(
+  (select format($q$select agent_board.create_invite_link(%L::uuid, 'admin', 'joined', 5, now() + interval '10 days', %L::uuid)$q$, board, alice) from _lf),
+  '22023', 'admin invite links require a TTL of at most 7 days',
+  'admin preset requires a <=7d TTL (R-LINK-3)');
+-- 4
+select throws_ok(
+  (select format($q$select agent_board.create_invite_link(%L::uuid, 'member', 'joined', null, null, %L::uuid)$q$, board, grimm) from _lf),
+  '42501', 'preset role exceeds creator role or board authority ceiling',
+  'create is grantor-bounded: an observer cannot mint a member link');
+-- 5
+select is((select length(code_member) from _lf), 43, 'the minted code is a 43-char base64url (256-bit) string');
+-- 6
+select is(
+  (select preset_role from agent_board.board_invite_tokens t join _lf f on t.code = f.code_member),
+  'member', 'the minted member link stores preset_role=member');
+-- 7
+select isnt((select code_member from _lf), (select code_maxed from _lf), 'distinct mints produce distinct codes (uniqueness)');
+
+-- === B. create actor-guard ============================================= (1)
+-- 8
+select set_config('request.jwt.claim.role', 'authenticated', true);
+select set_config('request.jwt.claim.sub', (select bob_user from _lf)::text, true);
+select throws_ok(
+  (select format($q$select agent_board.create_invite_link(%L::uuid, 'member', 'joined', null, null, %L::uuid)$q$, board, alice) from _lf),
+  '42501', 'p_created_by_agent_id must match current_agent_id()',
+  'actor-guard: authenticated Bob cannot mint a link as Alice');
+select set_config('request.jwt.claim.role', '', true);
+select set_config('request.jwt.claim.sub', '', true);
+
+-- === C. redeem basics ================================================== (3)
+-- 9
+select is(
+  (select role from agent_board._redeem_invite_for_agent((select code_member from _lf), (select carol from _lf))),
+  'member', 'redeem seats Carol with the member role');
+-- 10
+select is(
+  (select count(*)::int from agent_board.board_memberships bm join _lf f on bm.board_id = f.board and bm.agent_id = f.carol
+     where bm.membership_state in ('joined','subscribed')),
+  1, 'Carol holds exactly one active membership after redeem');
+-- 11
+select is(
+  (select uses_count from agent_board.board_invite_tokens t join _lf f on t.code = f.code_member),
+  1, 'the member link uses_count incremented to 1');
+
+-- === D. idempotency + exhaustion (maxed link) ========================== (5)
+-- 12
+select is(
+  (select role from agent_board._redeem_invite_for_agent((select code_maxed from _lf), (select frank from _lf))),
+  'member', 'first redeem of the maxed link seats Frank');
+-- 13
+select is(
+  (select uses_count from agent_board.board_invite_tokens t join _lf f on t.code = f.code_maxed),
+  1, 'the maxed link uses_count is 1 after Frank');
+-- 14
+select lives_ok(
+  (select format($q$select agent_board._redeem_invite_for_agent(%L, %L::uuid)$q$, code_maxed, frank) from _lf),
+  'replay by the same agent on a maxed link is an idempotent no-op (M1), not 42501');
+-- 15
+select is(
+  (select uses_count from agent_board.board_invite_tokens t join _lf f on t.code = f.code_maxed),
+  1, 'the idempotent replay did NOT inflate uses_count');
+-- 16
+select throws_ok(
+  (select format($q$select agent_board._redeem_invite_for_agent(%L, %L::uuid)$q$, code_maxed, gus) from _lf),
+  '42501', 'invite is not usable',
+  'a DIFFERENT agent redeeming the exhausted link is refused (uniform 42501)');
+
+-- === E. no-downgrade (rank-max) ======================================== (2)
+-- 17
+select is(
+  (select role from agent_board._redeem_invite_for_agent((select code_member from _lf), (select dave from _lf))),
+  'admin', 'redeeming a member link never downgrades Dave''s existing admin role (R-LINK-1)');
+-- 18
+select is(
+  (select role from agent_board.board_memberships bm join _lf f on bm.board_id = f.board and bm.agent_id = f.dave
+     where bm.membership_state in ('joined','subscribed')),
+  'admin', 'Dave''s stored membership role remains admin');
+
+-- === F. kicked-agent refusal (R-LINK-7) ================================ (1)
+-- 19
+select throws_ok(
+  (select format($q$select agent_board._redeem_invite_for_agent(%L, %L::uuid)$q$, code_member, erin) from _lf),
+  '42501', 'invite is not usable',
+  'a removed (kicked) agent cannot re-enter via an invite link (R-LINK-7)');
+
+-- === G. suspended-creator refusal (R-LINK-2) =========================== (1)
+-- 20
+select throws_ok(
+  (select format($q$select agent_board._redeem_invite_for_agent(%L, %L::uuid)$q$, code_mallory, carol2) from _lf),
+  '42501', 'invite is not usable',
+  'a suspended creator''s outstanding link stops minting (R-LINK-2)');
+
+-- === H. creator-ceiling re-bind ======================================== (1)
+-- 21
+select throws_ok(
+  (select format($q$select agent_board._redeem_invite_for_agent(%L, %L::uuid)$q$, code_harry, carol3) from _lf),
+  '42501', 'invite is not usable',
+  'a demoted creator''s admin link auto-degrades at redeem (re-bound ceiling)');
+
+-- === I. expired ======================================================== (1)
+-- 22
+select throws_ok(
+  (select format($q$select agent_board._redeem_invite_for_agent(%L, %L::uuid)$q$, code_expired, gus) from _lf),
+  '42501', 'invite is not usable',
+  'an expired link is refused (uniform 42501)');
+
+-- === J. revoke RPC ===================================================== (3)
+-- 23
+select set_config('request.jwt.claim.role', 'authenticated', true);
+select set_config('request.jwt.claim.sub', (select alice_user from _lf)::text, true);
+select lives_ok(
+  (select format($q$select agent_board.revoke_invite_link(%L)$q$, code_revoke) from _lf),
+  'the creator (Alice) revokes her own link');
+-- 24
+select ok(
+  (select revoked_at is not null from agent_board.board_invite_tokens t join _lf f on t.code = f.code_revoke),
+  'the revoked link carries a revoked_at timestamp');
+select set_config('request.jwt.claim.role', '', true);
+select set_config('request.jwt.claim.sub', '', true);
+-- 25
+select throws_ok(
+  (select format($q$select agent_board._redeem_invite_for_agent(%L, %L::uuid)$q$, code_revoke, carol2) from _lf),
+  '42501', 'invite is not usable',
+  'a revoked link is refused at redeem (uniform 42501)');
+
+-- === K. revoke authz =================================================== (1)
+-- 26
+select set_config('request.jwt.claim.role', 'authenticated', true);
+select set_config('request.jwt.claim.sub', (select carol_user from _lf)::text, true);
+select throws_ok(
+  (select format($q$select agent_board.revoke_invite_link(%L)$q$, code_revoke_authz) from _lf),
+  '42501', 'not authorized to revoke this invite',
+  'a plain member (Carol) cannot revoke someone else''s link');
+
+-- === L. public redeem happy path ======================================= (1)
+-- 27
+select is(
+  (select role from agent_board.redeem_invite_link((select code_public from _lf))),
+  'member', 'the public redeem_invite_link resolves the actor via current_agent_id() and seats Carol');
+select set_config('request.jwt.claim.role', '', true);
+select set_config('request.jwt.claim.sub', '', true);
+
+-- === M. redeem actor fail-closed ======================================= (1)
+-- 28
+select set_config('request.jwt.claim.role', 'authenticated', true);
+select set_config('request.jwt.claim.sub', (select mallory_user from _lf)::text, true);
+select throws_ok(
+  (select format($q$select agent_board.redeem_invite_link(%L)$q$, code_public) from _lf),
+  '42501', 'current agent principal not resolved',
+  'a suspended principal (current_agent_id() null) cannot redeem-as-nobody');
+select set_config('request.jwt.claim.role', '', true);
+select set_config('request.jwt.claim.sub', '', true);
+
+-- === N. internal core is not authenticated-callable ==================== (1)
+-- 29
+select function_privs_are(
+  'agent_board', '_redeem_invite_for_agent', array['text', 'uuid'],
+  'authenticated', array[]::text[],
+  '_redeem_invite_for_agent execute is revoked from authenticated (service_role-only core)');
+
+-- === O. enroll-on-redeem binding ======================================= (5)
+do $$
+declare v_aid uuid; v_red boolean;
+begin
+  -- Valid code: the enrollee lands in the board and invite_redeemed=true.
+  select e.agent_id, e.invite_redeemed into v_aid, v_red
+    from _lf f, agent_board.enroll_federated_identity(
+      f.prov_iss, 'message-board', f.prov_sub,
+      jsonb_build_object('sub', f.prov_sub), f.prov_slug,
+      f.pub1, 'raw_ed25519_base64url', f.fp1, true, null, 'agent', '{}', '{}', f.code_enroll) e;
+  insert into _er values ('X', v_aid, v_red);
+
+  -- Bad code: enrollment still succeeds, invite_redeemed=false, no membership.
+  select e.agent_id, e.invite_redeemed into v_aid, v_red
+    from _lf f, agent_board.enroll_federated_identity(
+      f.prov_iss, 'message-board', f.prov_sub || '-2',
+      jsonb_build_object('sub', f.prov_sub || '-2'), f.prov_slug || '-2',
+      f.pub2, 'raw_ed25519_base64url', f.fp2, true, null, 'agent', '{}', '{}', 'bogus-code-nonexistent') e;
+  insert into _er values ('Y', v_aid, v_red);
+end
+$$;
+-- 30
+select is((select invite_redeemed from _er where label = 'X'), true, 'enroll with a valid invite_code reports invite_redeemed=true');
+-- 31
+select is(
+  (select count(*)::int from agent_board.board_memberships bm, _lf f, _er r
+     where r.label = 'X' and bm.agent_id = r.agent_id and bm.board_id = f.board
+       and bm.membership_state in ('joined','subscribed')),
+  1, 'the enrollee was seated on the board by the redeemed code');
+-- 32
+select is(
+  (select status from agent_board.agents a join _er r on a.id = r.agent_id where r.label = 'Y'),
+  'active', 'enroll with a BAD invite_code still creates an active agent (soft-fail)');
+-- 33
+select is((select invite_redeemed from _er where label = 'Y'), false, 'a bad invite_code reports invite_redeemed=false');
+-- 34
+select is(
+  (select count(*)::int from agent_board.board_memberships bm, _lf f, _er r
+     where r.label = 'Y' and bm.agent_id = r.agent_id and bm.board_id = f.board),
+  0, 'the soft-failed enrollee gained no membership');
+
+select finish();
+
+rollback;

package/tests/agent_board_roomuiapi.test.sql

@@ -0,0 +1,225 @@
+-- ROOMUIAPI pgTAP: owner/admin-gated list_board_pending_memberships reader +
+-- SECURITY INVOKER resolve_agent_handle resolver.
+--
+-- Runs as the postgres db role; request.jwt.claim.role toggles _is_service_role()
+-- ('authenticated' => false) and request.jwt.claim.sub picks the acting agent.
+-- Fixture style mirrors agent_board_roomdeleg.test.sql (ensure_github_user,
+-- set_config role/sub, suspended-agent-as-null-actor trick).
+--
+-- Pending fixture rows (requested/invited/admin/board-B/dedup/demote-leave) are
+-- seeded by DIRECT INSERT into board_memberships (runs as postgres, bypassing RLS +
+-- the owner-gate coupling of request_join_board/invite_board_member). The owner
+-- membership comes from create_board's ROOMOWN seed.
+--
+-- HAND-COUNTED plan: R1,R2,R3,R4,R5,R6,R7,R8,U-4,H1,H2,H3 = 12 assertions, one each.
+create extension if not exists pgtap with schema extensions;
+set search_path = extensions, public, agent_board;
+
+begin;
+
+select plan(12);
+
+create temp table _roomuiapi_fixture (
+  board_a uuid,
+  board_b uuid,
+  alice uuid,            -- creator, seeded owner of board A (and B)
+  admin uuid,            -- role 'admin' on board A
+  plainmember uuid,      -- role 'member', joined on board A (PRIVACY CRUX actor)
+  nomember uuid,         -- active agent, no membership on board A
+  suspended uuid,        -- suspended agent WITH a valid auth user (null actor)
+  demoteleave uuid,      -- current row role=member/state=left (U-4 gate reject)
+  requester uuid,        -- pending 'requested' on board A
+  invitee uuid,          -- pending 'invited' on board A
+  dedup uuid,            -- older 'requested' + newer 'joined' (R8: not returned)
+  boardb_requester uuid, -- pending 'requested' on board B (R7 isolation)
+  requester_handle text,
+  suspended_handle text,
+  alice_user uuid,
+  admin_user uuid,
+  plainmember_user uuid,
+  nomember_user uuid,
+  suspended_user uuid,
+  demoteleave_user uuid
+) on commit drop;
+
+do $$
+declare
+  v_suffix text := replace(substr(gen_random_uuid()::text, 1, 8), '-', '');
+  v_alice_user uuid;
+  v_admin_user uuid;
+  v_plainmember_user uuid;
+  v_nomember_user uuid;
+  v_suspended_user uuid;
+  v_demoteleave_user uuid;
+  v_alice uuid := gen_random_uuid();
+  v_admin uuid := gen_random_uuid();
+  v_plainmember uuid := gen_random_uuid();
+  v_nomember uuid := gen_random_uuid();
+  v_suspended uuid := gen_random_uuid();
+  v_demoteleave uuid := gen_random_uuid();
+  v_requester uuid := gen_random_uuid();
+  v_invitee uuid := gen_random_uuid();
+  v_dedup uuid := gen_random_uuid();
+  v_boardb_requester uuid := gen_random_uuid();
+  v_board_a uuid;
+  v_board_b uuid;
+begin
+  v_alice_user := public.ensure_github_user('ru-alice-' || v_suffix, 'ru-alice-' || v_suffix || '@example.test', 'ru-alice-' || v_suffix, 'RU Alice');
+  v_admin_user := public.ensure_github_user('ru-admin-' || v_suffix, 'ru-admin-' || v_suffix || '@example.test', 'ru-admin-' || v_suffix, 'RU Admin');
+  v_plainmember_user := public.ensure_github_user('ru-member-' || v_suffix, 'ru-member-' || v_suffix || '@example.test', 'ru-member-' || v_suffix, 'RU Member');
+  v_nomember_user := public.ensure_github_user('ru-nomember-' || v_suffix, 'ru-nomember-' || v_suffix || '@example.test', 'ru-nomember-' || v_suffix, 'RU NoMember');
+  v_suspended_user := public.ensure_github_user('ru-susp-' || v_suffix, 'ru-susp-' || v_suffix || '@example.test', 'ru-susp-' || v_suffix, 'RU Suspended');
+  v_demoteleave_user := public.ensure_github_user('ru-demo-' || v_suffix, 'ru-demo-' || v_suffix || '@example.test', 'ru-demo-' || v_suffix, 'RU DemoteLeave');
+
+  insert into agent_board.agents(id, agent_type, handle, display_name, status, auth_user_id, owner_user_id)
+  values
+    (v_alice, 'agent', 'ru-alice-' || v_suffix, 'RU Alice', 'active', v_alice_user, v_alice_user),
+    (v_admin, 'agent', 'ru-admin-' || v_suffix, 'RU Admin', 'active', v_admin_user, v_admin_user),
+    (v_plainmember, 'agent', 'ru-member-' || v_suffix, 'RU Member', 'active', v_plainmember_user, v_plainmember_user),
+    (v_nomember, 'agent', 'ru-nomember-' || v_suffix, 'RU NoMember', 'active', v_nomember_user, v_nomember_user),
+    -- Suspended agent WITH a valid auth user: current_agent_id() filters status='active'
+    -- so it resolves to null while auth.uid() still maps (fail-closed test).
+    (v_suspended, 'agent', 'ru-susp-' || v_suffix, 'RU Suspended', 'suspended', v_suspended_user, v_suspended_user),
+    (v_demoteleave, 'agent', 'ru-demo-' || v_suffix, 'RU DemoteLeave', 'active', v_demoteleave_user, v_demoteleave_user),
+    (v_requester, 'agent', 'ru-requester-' || v_suffix, 'RU Requester', 'active', null, null),
+    (v_invitee, 'agent', 'ru-invitee-' || v_suffix, 'RU Invitee', 'active', null, null),
+    (v_dedup, 'agent', 'ru-dedup-' || v_suffix, 'RU Dedup', 'active', null, null),
+    (v_boardb_requester, 'agent', 'ru-brequester-' || v_suffix, 'RU BRequester', 'active', null, null);
+
+  -- Alice creates both boards (service_role null-actor here -> supplied arg honored);
+  -- create_board seeds Alice's joined owner membership (ROOMOWN) on each.
+  select board_id into v_board_a
+    from agent_board.create_board(v_alice, 'roomuiapi-a-' || v_suffix, 'ROOMUIAPI Board A', 'reader test', '{}'::jsonb, 'private');
+  select board_id into v_board_b
+    from agent_board.create_board(v_alice, 'roomuiapi-b-' || v_suffix, 'ROOMUIAPI Board B', 'isolation', '{}'::jsonb, 'private');
+
+  -- Direct-insert the remaining board A memberships (bypasses RLS + owner-gate).
+  insert into agent_board.board_memberships(board_id, agent_id, membership_state, created_by_agent_id, role)
+  values
+    (v_board_a, v_admin, 'joined', v_alice, 'admin'),
+    (v_board_a, v_plainmember, 'joined', v_alice, 'member'),
+    (v_board_a, v_requester, 'requested', v_requester, 'member'),
+    (v_board_a, v_invitee, 'invited', v_alice, 'member');
+
+  -- U-4: demote-and-leave. Under in-place upsert an agent keeps ONE row; here the
+  -- current row is role=member/state=left, so the plain-exists owner/admin gate must
+  -- reject it (no stale owner/joined row lingers to falsely satisfy exists()).
+  insert into agent_board.board_memberships(board_id, agent_id, membership_state, created_by_agent_id, role, left_at)
+  values
+    (v_board_a, v_demoteleave, 'left', v_alice, 'member', now());
+
+  -- R8 dedup: EXPLICIT distinct created_at (the whole suite runs in one begin; so
+  -- default now() is constant). Older 'requested' + newer 'joined' -> latest row is
+  -- 'joined' -> the reader's distinct-on-latest drops this agent from the pending set.
+  insert into agent_board.board_memberships(board_id, agent_id, membership_state, created_by_agent_id, role, created_at)
+  values
+    (v_board_a, v_dedup, 'requested', v_dedup, 'member', now() - interval '1 hour'),
+    (v_board_a, v_dedup, 'joined', v_alice, 'member', now());
+
+  -- Board B: its own pending requester (R7 cross-board isolation).
+  insert into agent_board.board_memberships(board_id, agent_id, membership_state, created_by_agent_id, role)
+  values
+    (v_board_b, v_boardb_requester, 'requested', v_boardb_requester, 'member');
+
+  insert into _roomuiapi_fixture values
+    (v_board_a, v_board_b, v_alice, v_admin, v_plainmember, v_nomember, v_suspended,
+     v_demoteleave, v_requester, v_invitee, v_dedup, v_boardb_requester,
+     'ru-requester-' || v_suffix, 'ru-susp-' || v_suffix,
+     v_alice_user, v_admin_user, v_plainmember_user, v_nomember_user, v_suspended_user, v_demoteleave_user);
+end
+$$;
+
+select set_config('request.jwt.claim.role', 'authenticated', true);
+
+-- === list_board_pending_memberships ===============================================
+-- R1: owner (Alice) reads board A -> exactly the 2 pending rows (requested+invited).
+select set_config('request.jwt.claim.sub', (select alice_user from _roomuiapi_fixture)::text, true);
+select is(
+  (select count(*)::int from agent_board.list_board_pending_memberships((select board_a from _roomuiapi_fixture))),
+  2, 'R1: the owner sees exactly the two pending memberships (requested + invited)');
+
+-- R2: admin reads board A -> same 2 pending rows.
+select set_config('request.jwt.claim.sub', (select admin_user from _roomuiapi_fixture)::text, true);
+select is(
+  (select count(*)::int from agent_board.list_board_pending_memberships((select board_a from _roomuiapi_fixture))),
+  2, 'R2: an admin sees the two pending memberships');
+
+-- R3: the owner sees the requester's handle (content, not just count).
+select set_config('request.jwt.claim.sub', (select alice_user from _roomuiapi_fixture)::text, true);
+select is(
+  (select p.handle
+     from agent_board.list_board_pending_memberships((select board_a from _roomuiapi_fixture)) p
+    where p.agent_id = (select requester from _roomuiapi_fixture)),
+  (select requester_handle from _roomuiapi_fixture),
+  'R3: the owner sees the requester''s handle in the pending row');
+
+-- R4: a plain joined member is rejected -> 42501 (PRIVACY CRUX).
+select set_config('request.jwt.claim.sub', (select plainmember_user from _roomuiapi_fixture)::text, true);
+select throws_ok(
+  (select format($q$select agent_board.list_board_pending_memberships(%L::uuid)$q$, board_a) from _roomuiapi_fixture),
+  '42501', 'only a board owner or admin may list pending memberships',
+  'R4: a plain joined member cannot enumerate pending memberships');
+
+-- R5: a non-member (unmapped sub) is rejected -> 42501.
+select set_config('request.jwt.claim.sub', gen_random_uuid()::text, true);
+select throws_ok(
+  (select format($q$select agent_board.list_board_pending_memberships(%L::uuid)$q$, board_a) from _roomuiapi_fixture),
+  '42501', 'only a board owner or admin may list pending memberships',
+  'R5: a non-member is rejected');
+
+-- R6: a suspended principal (current_agent_id() null) is rejected -> 42501 (fail-closed).
+select set_config('request.jwt.claim.sub', (select suspended_user from _roomuiapi_fixture)::text, true);
+select throws_ok(
+  (select format($q$select agent_board.list_board_pending_memberships(%L::uuid)$q$, board_a) from _roomuiapi_fixture),
+  '42501', 'only a board owner or admin may list pending memberships',
+  'R6: a suspended principal (null actor) is rejected (fail-closed)');
+
+-- R7: owner of A reading board A does NOT see board B's requester (cross-board isolation).
+select set_config('request.jwt.claim.sub', (select alice_user from _roomuiapi_fixture)::text, true);
+select is(
+  (select count(*)::int
+     from agent_board.list_board_pending_memberships((select board_a from _roomuiapi_fixture)) p
+    where p.agent_id = (select boardb_requester from _roomuiapi_fixture)),
+  0, 'R7: board B''s requester is absent from board A''s pending list (cross-board isolation)');
+
+-- R8: the dedup agent (latest row 'joined', older 'requested') is NOT returned.
+select is(
+  (select count(*)::int
+     from agent_board.list_board_pending_memberships((select board_a from _roomuiapi_fixture)) p
+    where p.agent_id = (select dedup from _roomuiapi_fixture)),
+  0, 'R8: an agent whose latest row is joined (older requested) is not returned (dedup)');
+
+-- U-4: demote-and-leave actor (current row role=member/state=left) is rejected -> 42501.
+select set_config('request.jwt.claim.sub', (select demoteleave_user from _roomuiapi_fixture)::text, true);
+select throws_ok(
+  (select format($q$select agent_board.list_board_pending_memberships(%L::uuid)$q$, board_a) from _roomuiapi_fixture),
+  '42501', 'only a board owner or admin may list pending memberships',
+  'U-4: a demoted-and-left actor (latest row member/left) is rejected by the gate');
+
+-- === resolve_agent_handle (SECURITY INVOKER) ======================================
+-- H1: exact active handle -> the agent_id.
+select set_config('request.jwt.claim.sub', (select alice_user from _roomuiapi_fixture)::text, true);
+select is(
+  (select r.agent_id
+     from agent_board.resolve_agent_handle((select requester_handle from _roomuiapi_fixture)) r),
+  (select requester from _roomuiapi_fixture),
+  'H1: the resolver maps an exact active handle to the agent_id');
+
+-- H2: unknown handle -> 0 rows.
+select is(
+  (select count(*)::int
+     from agent_board.resolve_agent_handle('ru-does-not-exist-' || gen_random_uuid()::text)),
+  0, 'H2: an unknown handle resolves to zero rows');
+
+-- H3: a suspended agent's handle -> 0 rows (status='active' filter).
+select is(
+  (select count(*)::int
+     from agent_board.resolve_agent_handle((select suspended_handle from _roomuiapi_fixture))),
+  0, 'H3: a suspended agent''s handle resolves to zero rows (active filter)');
+
+select set_config('request.jwt.claim.role', '', true);
+select set_config('request.jwt.claim.sub', '', true);
+
+select finish();
+
+rollback;