@consiliency/agent-board-schema 1.64.0 → 1.74.0

package/migrations/20261015000400_agent_board_resolution_authority.sql

@@ -0,0 +1,146 @@
+-- Consiliency/message-board#668: resolution uses the pending reader's flat authority gate.
+--
+-- Consiliency/message-board#665 (integration): this migration sorts after
+-- 20261015000100_agent_board_session_provenance, so on every fresh apply THIS body is the one
+-- that survives. It therefore carries #665's session-derived attribution as well: both sink calls
+-- (the redundant-pending retirement and the resolution write) pass v_actor, never the caller's
+-- p_created_by_agent_id, which is retained for signature compatibility only. Because the gate
+-- below refuses an unresolved principal (including an unresolved service-role session), v_actor
+-- is always a resolved owner/admin when a sink is reached.
+
+create or replace function agent_board.resolve_board_request(
+  p_board_id uuid,
+  p_agent_id uuid,
+  p_membership_state text,
+  p_created_by_agent_id uuid,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(membership_id uuid, board_id uuid, agent_id uuid, membership_state text, left_at timestamp with time zone, updated_at timestamp with time zone)
+language plpgsql
+security definer
+set search_path to 'agent_board', 'public'
+as $function$
+declare
+  v_effective_state text;
+  v_board agent_board.boards%rowtype;
+  v_membership_id uuid;
+  v_active_id uuid;
+  v_membership agent_board.board_memberships%rowtype;
+  v_actor uuid := agent_board.current_agent_id();
+begin
+  if v_actor is null and not agent_board._is_service_role() then
+    raise exception 'current agent principal not resolved' using errcode = '42501';
+  end if;
+
+  if p_membership_state not in ('joined', 'subscribed', 'removed') then
+    raise exception 'resolve_board_request only accepts joined, subscribed, or removed' using errcode = '22023';
+  end if;
+  select * into v_board from agent_board.boards where id = p_board_id and status = 'active';
+  if v_board.id is null then
+    raise exception 'board not found' using errcode = 'P0002';
+  end if;
+  if v_actor is null or not exists (
+    select 1 from agent_board.board_memberships bm
+     where bm.board_id = p_board_id
+       and bm.agent_id = v_actor
+       and bm.membership_state in ('joined', 'subscribed')
+       and bm.role in ('owner', 'admin')
+  ) then
+    raise exception 'board request resolution requires owner or admin role' using errcode = '42501';
+  end if;
+
+  -- Lock the WHOLE (board, agent) set first so a concurrent self-withdrawal on ANY physical row
+  -- serialises behind this resolution (#109's race is per-(board,agent), not per-row).
+  perform 1
+     from agent_board.board_memberships bm
+    where bm.board_id = p_board_id
+      and bm.agent_id = p_agent_id
+    order by bm.id
+      for update;
+
+  -- Select the PENDING row explicitly (not the total-order winner). B2 (#116): with TWO pending
+  -- rows (a requested AND an invited) for one subject this resolves the NEWEST; the older dangles.
+  -- Inherent to the multi-row model — resolution is one act on one row.
+  select bm.id
+    into v_membership_id
+    from agent_board.board_memberships bm
+   where bm.board_id = p_board_id
+     and bm.agent_id = p_agent_id
+     and bm.membership_state in ('requested', 'invited')
+   order by bm.created_at desc, bm.id desc
+   limit 1;
+
+  select bm.id
+    into v_active_id
+    from agent_board.board_memberships bm
+   where bm.board_id = p_board_id
+     and bm.agent_id = p_agent_id
+     and bm.membership_state in ('joined', 'subscribed')
+   order by bm.created_at desc, bm.id desc
+   limit 1;
+
+  if v_membership_id is null then
+    raise exception 'pending board membership not found' using errcode = 'P0002';
+  end if;
+
+  -- OPTION 1 FALLBACK (#109 A3): approving a subject who is ALREADY active is a no-op success,
+  -- not a promotion of the pending row into collision with the active one. Return the active row
+  -- untouched. Rejection still falls through to act on the pending row.
+  --
+  -- B4 (#116): the no-op path intentionally IGNORES the requested target state and p_metadata —
+  -- approving with target 'subscribed' a 'joined' active row returns 'joined' (a self-toggle
+  -- belongs to update_board_membership, which is where the old path coupled the metadata write to
+  -- a demotion). Nothing legitimate is lost.
+  if p_membership_state in ('joined', 'subscribed') and v_active_id is not null then
+    -- B1 (#116): retire the redundant pending row so it stops showing in pending listings. The
+    -- subject is already active via v_active_id (untouched); route the retire through the sink so
+    -- the write EMITS (the emission-completeness invariant requires every membership write to hit
+    -- the ledger) — a board-authored 'left' event, which is NEUTRAL for consent (not the subject's
+    -- own act) and does not affect the subject's consent-present status carried by the active row.
+    -- 'left' is recoverable. Previously only a reject cleared this, leaving an owner-visible
+    -- dangling request after a no-op approve.
+    perform agent_board._upsert_board_membership_state(
+      p_board_id, p_agent_id, 'left', v_actor, p_metadata, v_membership_id, 'noop_superseded'
+    );
+
+    return query
+    select bm.id, bm.board_id, bm.agent_id, bm.membership_state, bm.left_at, bm.updated_at
+      from agent_board.board_memberships bm
+     where bm.id = v_active_id;
+    return;
+  end if;
+
+  -- REJECTSEM (#89): a rejection is NOT an eviction — resolve only acts on a PENDING row, so a
+  -- refusal lands on 'left' (recoverable), never 'removed' (which bars self-re-entry). Applied to
+  -- both requested and invited origins.
+  v_effective_state := case when p_membership_state = 'removed' then 'left'
+                            else p_membership_state end;
+
+  -- #82: promotion into an active state requires the subject's own consent act (the sole
+  -- consent-predicate read site). Every accepted session, including service-role operators,
+  -- has a resolved owner/admin principal after the authority gate above; there is no exemption.
+  if v_actor is not null
+     and v_effective_state in ('joined', 'subscribed')
+     and not agent_board._membership_consent_present(p_board_id, p_agent_id) then
+    raise exception 'admitting % requires an act by that agent', p_agent_id
+      using errcode = '42501';
+  end if;
+
+  v_membership := agent_board._upsert_board_membership_state(
+    p_board_id,
+    p_agent_id,
+    v_effective_state,
+    v_actor,
+    p_metadata,
+    v_membership_id,
+    case when p_membership_state = 'removed' then 'reject_withdrawn' else null end
+  );
+
+  return query
+  select v_membership.id, v_membership.board_id, v_membership.agent_id, v_membership.membership_state, v_membership.left_at, v_membership.updated_at;
+end;
+$function$;
+
+revoke all on function agent_board.resolve_board_request(uuid,uuid,text,uuid,jsonb) from public, anon;
+grant execute on function agent_board.resolve_board_request(uuid,uuid,text,uuid,jsonb) to authenticated, service_role;
+comment on function agent_board.resolve_board_request(uuid,uuid,text,uuid,jsonb) is 'Resolves pending memberships only for a resolved active owner/admin principal, independent of role_gate_enforced and creator identity. Matches list_board_pending_memberships, including refusal of an unresolved service-role session. Consent, rejection mapping and redundant-request retirement remain in force. Membership attribution is derived from current_agent_id(); p_created_by_agent_id is retained for signature compatibility only.';