@consiliency/agent-board-schema 1.12.0 → 1.23.0

package/migrations/20260808000100_agent_board_rejectsem.sql

@@ -0,0 +1,145 @@
+-- =============================================================================
+-- MBCONSENT-B(i) — REJECTSEM: a refusal is not an eviction (message-board#89)
+-- =============================================================================
+-- Reproduced on main before designing the fix, as the phase plan requires:
+--   subject requests to join an OPEN board -> owner rejects with `removed`
+--   -> subject can no longer join it: "board is not joinable by this agent"
+-- One refusal was a permanent, self-unrecoverable bar on a board open to anyone.
+--
+-- resolve_board_request is the REFUSAL path, not an eviction path -- update_board_membership
+-- is the schema's only eviction path. So `removed` from this RPC always mislabelled a refusal
+-- as a removal. It now writes `left`, which is recoverable.
+--
+-- CORRECTED CLAIM, and the reason it matters. An earlier draft of this header asserted that
+-- this RPC "only ever acts on a pending row". That is FALSE, and review caught it: the
+-- resolver reads the pending row, but the shared sink independently reselects with
+-- ACTIVE-ROW PREFERENCE and does not revalidate that its pick is still pending. With a legal
+-- active-plus-pending duplicate -- permitted, because the uniqueness index covers only ACTIVE
+-- rows -- rejecting the pending request downgrades the ACTIVE membership instead.
+--
+-- That defect is PRE-EXISTING and not introduced here: before this change the same sequence
+-- set the active row to `removed`, which is strictly worse because `removed` also bars
+-- re-entry. It is filed separately and belongs with the locking work, which will make the
+-- resolver select and lock its own row rather than delegating the choice to the sink. This
+-- migration does not claim to fix it.
+--
+-- The API is unchanged: callers still pass `removed` to reject. The rewrite is server-side, so
+-- no client needs to know -- and a client that passed `left` instead would be REFUSED, because
+-- this RPC's enum does not accept it.
+--
+-- The refusal remains fully durable in the ledger: this changes the membership STATE, not the
+-- record that a rejection happened. schema_version stays 8.
+-- =============================================================================
+
+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 $$
+declare
+  v_effective_state text;
+  v_board agent_board.boards%rowtype;
+  v_existing_state text;
+  v_membership agent_board.board_memberships%rowtype;
+  v_actor uuid := agent_board.current_agent_id();
+begin
+  -- GATENULL (#58): only service_role may proceed with an unresolved actor.
+  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 not null then
+    if v_board.role_gate_enforced then
+      -- Gate ON: NO creator exemption. Every actor (including a demoted creator)
+      -- must hold an active owner/admin membership.
+      if 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;
+    elsif v_actor <> v_board.created_by_agent_id then
+      -- Gate OFF: creator bypasses; any other actor needs an active membership.
+      if 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')
+      ) then
+        raise exception 'board request resolution requires active membership' using errcode = '42501';
+      end if;
+    end if;
+  end if;
+
+  select bm.membership_state
+    into v_existing_state
+    from agent_board.board_memberships bm
+   where bm.board_id = p_board_id
+     and bm.agent_id = p_agent_id
+   order by bm.created_at desc, bm.id desc
+   limit 1;
+
+  -- NULLFIX (CR): same NULL-falsy hazard — with NO membership row v_existing_state is NULL and
+  -- `NULL not in (...)` is NULL, so the raise never fired and a caller could "resolve" an agent
+  -- that had never requested or been invited STRAIGHT to joined, bypassing the whole request path
+  -- (reachable by any active member on a gate-OFF board, incl. via `rooms approve --agent-id`).
+  if coalesce(v_existing_state, '') not in ('requested', 'invited') then
+    raise exception 'pending board membership not found' using errcode = 'P0002';
+  end if;
+
+  -- REJECTSEM (#89). A rejection is NOT an eviction. resolve_board_request only ever acts on a
+  -- PENDING row (requested|invited) -- update_board_membership is the schema's only eviction
+  -- path -- so writing `removed` here mislabels a refusal as a removal, and `removed` bars
+  -- self-re-entry. Reproduced before fixing: request an OPEN board, owner rejects, and the
+  -- subject can no longer join a board open to anyone ("board is not joinable by this agent").
+  -- One refusal became a permanent, self-unrecoverable bar.
+  --
+  -- Applied to BOTH pending origins, not just `requested`. Cancelling an INVITATION had the
+  -- identical trap, and fixing only the named instance is how several defects in this work
+  -- survived a round.
+  --
+  -- `left` is recoverable: the subject may act again. The refusal is still durable in the
+  -- ledger -- this changes the membership STATE, not the record that it happened.
+  v_effective_state := case when p_membership_state = 'removed' then 'left'
+                            else p_membership_state end;
+
+  v_membership := agent_board._upsert_board_membership_state(
+    p_board_id,
+    p_agent_id,
+    v_effective_state,
+    p_created_by_agent_id,
+    p_metadata
+  );
+
+  -- NOT relabelled here, deliberately. An earlier revision UPDATEd the freshly-emitted
+  -- ledger row to `reject_withdrawn`, so the history would say a REFUSAL rather than an
+  -- eviction. It worked -- and that is the problem. board_membership_events is append-only by
+  -- GRANT: service_role holds SELECT and INSERT and no UPDATE. The write succeeded only
+  -- because this function is SECURITY DEFINER and runs as the owner, bypassing grants
+  -- entirely. Fixing a descriptive label by punching through the property that makes the
+  -- ledger trustworthy is a worse trade than the label being wrong.
+  --
+  -- The row must instead be written with the right kind the FIRST time, which means threading
+  -- a kind through the shared sink. That changes a signature every membership route calls, so
+  -- it belongs in the gating change that is already modifying the sink -- reviewed in context,
+  -- not bolted onto this one. Filed; until then a refusal records as `eviction`. The membership
+  -- STATE is correct and recoverable, which is what #89 is about; only the label is wrong.
+
+
+  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;
+$$;

package/migrations/20260809000100_agent_board_consent_gating.sql

@@ -0,0 +1,492 @@
+-- =============================================================================
+-- MBCONSENT-B(ii) — ROUTE GATING (message-board#82) + the paired widening (#108)
+-- =============================================================================
+-- The change that actually closes the hole. Everything before it was preparation: the ledger
+-- exists (#101), every writer records to it (#104), and a refusal no longer bans (#107).
+-- Nothing read the record. This makes it authoritative.
+--
+-- This migration is NOT inert. Calls that succeed today begin failing -- that is the point --
+-- so every gate ships with a paired assertion that the legitimate path still works. A gate
+-- that refuses everything passes every force-join test.
+--
+-- FIVE user-callable routes reach an active membership, not four. Every prior document said
+-- four; redeem_invite_link was missed because it reaches membership through a different
+-- internal function. It needs NO change here -- verified: it takes no target parameter and
+-- passes current_agent_id(), so it is already self-only and cannot name a victim.
+--
+--   join_board              creator exemption REMOVED (#82) + invitation admits on any
+--                           visibility (#108)
+--   resolve_board_request   promotion to active requires consent on the ledger
+--   update_board_membership other-agent promotion into active refused
+--   redeem_invite_link      unchanged -- already self-only
+--   create_board            unchanged -- the actor IS the subject
+--
+-- NOT gated, verified rather than assumed: invite_board_member writes only `invited`,
+-- request_join_board only `requested`, leave_board only `left`, and grant_board_role requires
+-- an already-active membership and never SETs membership_state.
+--
+-- THE OPERATOR CARVE-OUT IS PRESERVED AND IS DELIBERATE. Every gate is conditioned on
+-- `v_actor is not null` -- authenticated callers. service_role may still place agents, recorded
+-- as operator-designated with a null actor and never laundered as consent. Writing the gates as
+-- "authenticated is blocked" rather than "the actor must be the subject" would mean a caller
+-- misclassified as operator OPENS the hole rather than closing it.
+--
+-- KNOWN LIMITATION, stated so the gate is not mistaken for airtight: both admission paths
+-- CHECK CONSENT BEFORE THE ROW IS LOCKED. The sink locks only when it writes, so a subject who
+-- withdraws between the check and the write can still be admitted -- a check-then-write race.
+--
+-- This narrows an open hole to a race window rather than leaving it open: before this
+-- migration an owner could admit anyone unconditionally, with no race required. It is not
+-- fully closed until the locking phase, which makes the resolver select and lock its own row
+-- before reading consent. That phase also carries #109 (rejecting a pending request can
+-- downgrade an ACTIVE membership, because the sink reselects with active-row preference) and
+-- #110 (a refusal records as an eviction) -- all three are the same shared-function change and
+-- are reviewed together rather than three passes over the same code.
+--
+-- schema_version stays 8: additive.
+-- =============================================================================
+
+create or replace function agent_board.join_board(p_board_id uuid, p_agent_id uuid, p_membership_state text DEFAULT 'joined'::text, p_created_by_agent_id uuid DEFAULT NULL::uuid, p_metadata jsonb DEFAULT '{}'::jsonb)
+ RETURNS TABLE(membership_id uuid, board_id uuid, agent_id uuid, membership_state text, created_at timestamp with time zone, updated_at timestamp with time zone)
+ LANGUAGE plpgsql
+ SECURITY DEFINER
+ SET search_path TO 'agent_board', 'public'
+as $$
+declare
+  v_board agent_board.boards%rowtype;
+  v_existing_state text;
+  v_membership agent_board.board_memberships%rowtype;
+  v_actor uuid := agent_board.current_agent_id();
+begin
+  -- GATENULL (#58): only service_role may proceed with an unresolved actor.
+  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') then
+    raise exception 'join_board only accepts joined or subscribed' using errcode = '22023';
+  end if;
+  if not exists (select 1 from agent_board.agents where id = p_agent_id) then
+    raise exception 'agent not found' using errcode = 'P0002';
+  end if;
+  if p_created_by_agent_id is not null and not exists (select 1 from agent_board.agents where id = p_created_by_agent_id) then
+    raise exception 'creator agent not found' using errcode = 'P0002';
+  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;
+
+  -- MBROWID (3a): prefer ACTIVE standing for joinability / idempotent-join. A bare
+  -- total-order can surface a high-id REMOVED row while a low-id JOINED row exists,
+  -- locking an active member out of their own private / invite_only board (P0002).
+  select bm.membership_state
+    into v_existing_state
+    from agent_board.board_memberships bm
+   where bm.board_id = p_board_id
+     and bm.agent_id = p_agent_id
+   order by
+     case when bm.membership_state in ('joined', 'subscribed') then 0 else 1 end,
+     bm.created_at desc,
+     bm.id desc
+   limit 1;
+
+  -- #82: the CREATOR EXEMPTION IS REMOVED. Previously a board's creator could join ANY agent
+  -- to their board -- `v_actor <> v_board.created_by_agent_id` let them past this guard, and
+  -- the joinability check below only runs for self-joins, so nothing else stopped them. That
+  -- is the force-join hole. Creating a board does not entitle you to place other people in it.
+  --
+  -- Only the subject may join the subject. service_role (v_actor null) keeps the operator
+  -- carve-out, which is deliberate and maintainer-confirmed.
+  if v_actor is not null and v_actor <> p_agent_id then
+    raise exception 'board membership actor mismatch' using errcode = '42501';
+  end if;
+
+  -- NULLFIX (CR): v_existing_state is NULL when the caller has NO membership row, and the original
+  -- guard then evaluated to NULL — `not (false or false or NULL)` is NULL, not TRUE — so `if NULL
+  -- then` never fired and ANY resolvable actor self-joined ANY board, private ones included. That
+  -- (not the null-actor bypass) was the true root cause of the live "joined a private invite_only
+  -- board with no invite" finding, and it is reachable by an ACTIVE agent, which the GATENULL guard
+  -- above cannot touch. coalesce() makes the absent-row case FALSE so the raise fires.
+  --
+  -- MBROWID (3b): a 'removed' agent is excluded from self-joining even an OPEN board via the
+  -- R-LINK-7 SET predicate (exists removed AND no active), not a single latest-row state.
+  -- Total-ordering the latest-row read alone is insufficient: a removed+left pair with equal
+  -- created_at can surface 'left' as the total-order winner while standing is still removed
+  -- (mutator + grant_board_role already use set-based rules). The three defenses must agree.
+  if v_actor is not null
+     and v_actor = p_agent_id
+     and v_board.created_by_agent_id <> v_actor
+     and not (
+       not (
+         exists (
+           select 1 from agent_board.board_memberships bm
+            where bm.board_id = p_board_id
+              and bm.agent_id = p_agent_id
+              and bm.membership_state = 'removed'
+         ) and not exists (
+           select 1 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')
+         )
+       )
+       and (
+         v_board.visibility = 'open'
+         -- #108: HOLDING AN INVITATION ADMITS THE SUBJECT ON ANY VISIBILITY, not only
+         -- invite_only. Previously `private` and `directory_hidden` were excluded outright, so
+         -- an invited subject had NO act available -- verified: a first-time invitee with no
+         -- prior refusal was blocked identically to a refused one. Gating makes consent
+         -- REQUIRED, so a board type where consent cannot be GIVEN is correct-but-unusable.
+         --
+         -- This is the narrowest widening that makes consent exercisable. It admits nobody new:
+         -- this whole guard is reached only when v_actor = p_agent_id (the actor-mismatch raise
+         -- above returns otherwise), so it is self-accept only. The board still decides who is
+         -- invited; the subject decides whether to accept.
+         or coalesce(v_existing_state, '') = 'invited'
+         or coalesce(v_existing_state, '') in ('joined', 'subscribed')
+       )
+     ) then
+    raise exception 'board is not joinable by this agent' using errcode = 'P0002';
+  end if;
+
+  v_membership := agent_board._upsert_board_membership_state(
+    p_board_id,
+    p_agent_id,
+    p_membership_state,
+    coalesce(p_created_by_agent_id, p_agent_id),
+    p_metadata
+  );
+
+  return query
+  select v_membership.id, v_membership.board_id, v_membership.agent_id, v_membership.membership_state, v_membership.created_at, v_membership.updated_at;
+end;
+$$;
+
+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 $$
+declare
+  v_effective_state text;
+  v_board agent_board.boards%rowtype;
+  v_existing_state text;
+  v_membership agent_board.board_memberships%rowtype;
+  v_actor uuid := agent_board.current_agent_id();
+begin
+  -- GATENULL (#58): only service_role may proceed with an unresolved actor.
+  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 not null then
+    if v_board.role_gate_enforced then
+      -- Gate ON: NO creator exemption. Every actor (including a demoted creator)
+      -- must hold an active owner/admin membership.
+      if 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;
+    elsif v_actor <> v_board.created_by_agent_id then
+      -- Gate OFF: creator bypasses; any other actor needs an active membership.
+      if 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')
+      ) then
+        raise exception 'board request resolution requires active membership' using errcode = '42501';
+      end if;
+    end if;
+  end if;
+
+  select bm.membership_state
+    into v_existing_state
+    from agent_board.board_memberships bm
+   where bm.board_id = p_board_id
+     and bm.agent_id = p_agent_id
+   order by bm.created_at desc, bm.id desc
+   limit 1;
+
+  -- NULLFIX (CR): same NULL-falsy hazard — with NO membership row v_existing_state is NULL and
+  -- `NULL not in (...)` is NULL, so the raise never fired and a caller could "resolve" an agent
+  -- that had never requested or been invited STRAIGHT to joined, bypassing the whole request path
+  -- (reachable by any active member on a gate-OFF board, incl. via `rooms approve --agent-id`).
+  if coalesce(v_existing_state, '') not in ('requested', 'invited') then
+    raise exception 'pending board membership not found' using errcode = 'P0002';
+  end if;
+
+  -- REJECTSEM (#89). A rejection is NOT an eviction. resolve_board_request only ever acts on a
+  -- PENDING row (requested|invited) -- update_board_membership is the schema's only eviction
+  -- path -- so writing `removed` here mislabels a refusal as a removal, and `removed` bars
+  -- self-re-entry. Reproduced before fixing: request an OPEN board, owner rejects, and the
+  -- subject can no longer join a board open to anyone ("board is not joinable by this agent").
+  -- One refusal became a permanent, self-unrecoverable bar.
+  --
+  -- Applied to BOTH pending origins, not just `requested`. Cancelling an INVITATION had the
+  -- identical trap, and fixing only the named instance is how several defects in this work
+  -- survived a round.
+  --
+  -- `left` is recoverable: the subject may act again. The refusal is still durable in the
+  -- ledger -- this changes the membership STATE, not the record that it happened.
+  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 ACT. This is the sole
+  -- consent-predicate read site. An owner resolving a pending row to joined|subscribed is a
+  -- BOARD act; it admits the subject only if the subject has already consented -- by requesting
+  -- (target-authored) or by an operator placement. A board-authored `invited` or a manufactured
+  -- `requested` is NEUTRAL on the ledger and does not admit anyone.
+  --
+  -- Authenticated only. service_role keeps the operator carve-out.
+  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,
+    p_created_by_agent_id,
+    p_metadata
+  );
+
+  -- NOT relabelled here, deliberately. An earlier revision UPDATEd the freshly-emitted
+  -- ledger row to `reject_withdrawn`, so the history would say a REFUSAL rather than an
+  -- eviction. It worked -- and that is the problem. board_membership_events is append-only by
+  -- GRANT: service_role holds SELECT and INSERT and no UPDATE. The write succeeded only
+  -- because this function is SECURITY DEFINER and runs as the owner, bypassing grants
+  -- entirely. Fixing a descriptive label by punching through the property that makes the
+  -- ledger trustworthy is a worse trade than the label being wrong.
+  --
+  -- The row must instead be written with the right kind the FIRST time, which means threading
+  -- a kind through the shared sink. That changes a signature every membership route calls, so
+  -- it belongs in the gating change that is already modifying the sink -- reviewed in context,
+  -- not bolted onto this one. Filed; until then a refusal records as `eviction`. The membership
+  -- STATE is correct and recoverable, which is what #89 is about; only the label is wrong.
+
+
+  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;
+$$;
+
+create or replace function agent_board.update_board_membership(p_board_id uuid, p_agent_id uuid, p_membership_state text, 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 $$
+declare
+  v_membership agent_board.board_memberships%rowtype;
+  v_board agent_board.boards%rowtype;
+  v_actor uuid := agent_board.current_agent_id();
+  v_is_service boolean := agent_board._is_service_role();
+  v_existing_state text;
+  v_target_role text;
+  v_actor_role text;
+begin
+  -- (1) Unresolved principal fails closed (GATENULL #58 posture). Raised before any lookup so this
+  -- cannot be used as a membership-existence oracle.
+  if v_actor is null and not v_is_service then
+    raise exception 'current agent principal not resolved' using errcode = '42501';
+  end if;
+
+  -- (2) AUTHORITY BEFORE DISCLOSURE. For a caller acting on ANOTHER agent's row the owner/admin
+  -- check runs BEFORE the membership lookup, so an unauthorized caller cannot distinguish
+  -- P0002 'board membership not found' from 42501 and thus cannot probe whether an arbitrary
+  -- (board_id, agent_id) pair has a membership row. (The self branch legitimately learns about its
+  -- own membership, and the service path is the operator.)
+  if not v_is_service and v_actor <> p_agent_id then
+    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;
+    select bm.role
+      into v_actor_role
+      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')
+     limit 1;
+    if v_actor_role is null or v_actor_role not in ('owner', 'admin') then
+      raise exception 'board membership change requires owner or admin role'
+        using errcode = '42501';
+    end if;
+  end if;
+
+  -- (3) Pre-existing precondition, preserved. Also captures the target's CURRENT role for the
+  -- rank check below.
+  -- MBROWID (3a): prefer ACTIVE standing. Bare total-order can surface a high-id REMOVED
+  -- row while a low-id JOINED row exists, so self-service would reject a legitimate
+  -- joined->joined toggle with 42501 'self membership change not permitted'.
+  select bm.membership_state, bm.role
+    into v_existing_state, v_target_role
+    from agent_board.board_memberships bm
+   where bm.board_id = p_board_id
+     and bm.agent_id = p_agent_id
+   order by
+     case when bm.membership_state in ('joined', 'subscribed') then 0 else 1 end,
+     bm.created_at desc,
+     bm.id desc
+   limit 1;
+  if v_existing_state is null then
+    raise exception 'board membership not found' using errcode = 'P0002';
+  end if;
+
+  -- (4) MEMBSTATE authorization. Skipped ONLY for a genuine service_role/operator caller; every
+  -- authenticated caller (whose actor is guaranteed non-null by step 1) is gated.
+  if not v_is_service then
+    if v_actor = p_agent_id then
+      -- SELF-SERVICE. Deliberately NO board lookup on this branch: the board row is only needed
+      -- for the authority checks below, and requiring an ACTIVE board here would strand an agent
+      -- holding a live membership on an ARCHIVED board with no way to leave it (leave_board
+      -- delegates straight into this RPC, 20260512000002:154-158).
+      --
+      -- Leaving is permitted only FROM a live/pending state, and joined<->subscribed may be
+      -- toggled. Promotion INTO the board is NOT permitted — that belongs to the approval path.
+      -- The 'removed' exclusion is load-bearing: allowing removed -> left would let a kicked agent
+      -- erase the 'removed' marker (memberships are updated IN PLACE, so the row IS the record),
+      -- which is exactly the marker _redeem_invite_for_agent's R-LINK-7 defense reads
+      -- (20260724000100:323-335) — i.e. it would launder a kick into invite-link re-entry.
+      --
+      -- LEAVEIDEM (#81): a same-state TERMINAL call is additionally permitted. It is a no-op
+      -- (returned unchanged at step 5), so it neither erases nor refreshes the marker — it simply
+      -- restores idempotence to leave_board without widening the transition set.
+      if not (
+        (p_membership_state = 'left'
+         and v_existing_state in ('joined', 'subscribed', 'invited', 'requested'))
+        or (p_membership_state in ('joined', 'subscribed')
+            and v_existing_state in ('joined', 'subscribed'))
+        or (p_membership_state = v_existing_state
+            and p_membership_state in ('left', 'removed'))
+      ) then
+        raise exception 'self membership change not permitted; use the join/approval path'
+          using errcode = '42501';
+      end if;
+    else
+      -- ACTING ON ANOTHER AGENT'S MEMBERSHIP. The board-active check and the ACTIVE owner/admin
+      -- requirement already ran in step (2) (authority before disclosure). This RPC is the
+      -- schema's only eviction path — no sibling can move a JOINED member to removed
+      -- (resolve_board_request only resolves requested/invited, 20260725000100:212) — so it is
+      -- gated more strictly than its siblings, with NO creator exemption: a bare
+      -- created_by_agent_id is deliberately NOT sufficient. ROOMOWN seeds the creator's owner
+      -- membership at create_board time (20260723000100), so a legitimate creator holds one, while
+      -- a DEMOTED or REMOVED creator must not retain eviction power (the R-DELEG-1 lesson).
+      --
+      -- STRICT RANK SUPERIORITY (owner=4 > admin=3 > member=2 > observer=1). Without it an admin
+      -- could evict the OWNER, or admins could evict each other.
+      -- The rank comparison must use the EFFECTIVE POST-TRANSITION role, not the stale retained
+      -- one. Roles are preserved on a `left`/`removed` row, and the sink CLAMPS any
+      -- non-active -> active admission back to 'member' (MBROLERESET). So a departed OWNER who
+      -- genuinely requests re-entry was compared at rank owner <= owner and refused -- while the
+      -- role they would actually receive is `member`. That blocked a CONSENTING subject from
+      -- being re-admitted, which is this phase's own EC-2, and it is the allow-side failure the
+      -- deny side cannot see.
+      --
+      -- For an admission the effective role is what the clamp will produce; for every other
+      -- transition the retained role stands, so eviction and demotion still require strict rank
+      -- superiority over the role the target actually holds.
+      if agent_board._role_rank(v_actor_role)
+         <= agent_board._role_rank(
+              case
+                when p_membership_state in ('joined', 'subscribed')
+                 and coalesce(v_existing_state, '') not in ('joined', 'subscribed')
+                then 'member'
+                else coalesce(v_target_role, '')
+              end) then
+        raise exception 'board membership change requires a higher board role than the target'
+          using errcode = '42501';
+      end if;
+
+      -- #82: an owner or admin may EVICT or demote another agent, but may not ADMIT one.
+      -- Moving someone into joined|subscribed is exactly the force-join this phase closes, and
+      -- no authority short of the subject's own act permits it. Manufacturing a `requested` row
+      -- stays allowed -- it is neutral on the ledger and admits nobody, and the promotion that
+      -- would follow is refused at resolve_board_request's predicate read.
+      --
+      -- service_role retains update-other promotion as an operator placement.
+      -- The rule is ADMISSION REQUIRES CONSENT, not "no promotion ever". Three cases:
+      --
+      --   * already ACTIVE -> active (joined <-> subscribed): NOT an admission. The subject is
+      --     already a member and consented to be; changing which active state they hold admits
+      --     nobody. Refusing it broke a legitimate owner flow.
+      --   * NOT active -> active WITH consent on the ledger: allowed. The subject asked, or an
+      --     operator placed them. An owner acting on that is an approval, not a force-join.
+      --   * NOT active -> active WITHOUT consent: refused. This is #82.
+      --
+      -- An earlier revision refused ALL other-agent promotion regardless of consent or origin.
+      -- That contradicted this phase's own acceptance criterion (an owner may promote a
+      -- CONSENTING subject) and over-blocked active->active. Deny-side correctness is worthless
+      -- if it takes the allow side with it.
+      if p_membership_state in ('joined', 'subscribed')
+         and coalesce(v_existing_state, '') not 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;
+    end if;
+  end if;
+
+  -- (5) LEAVEIDEM (#81): a same-state TERMINAL call is a TRUE no-op — return the row untouched
+  -- rather than re-entering the mutator, which would restamp left_at and re-merge metadata.
+  -- Placed AFTER the authorization block on purpose: returning early before step (2)/(4) would
+  -- hand an UNAUTHORIZED caller a successful no-op instead of 42501, turning this RPC into a
+  -- membership-state oracle for arbitrary (board, agent) pairs. Authority is still required; the
+  -- entitled caller simply gets an unchanged row.
+  -- Scoped to the AUTHENTICATED path on purpose: a service_role/operator caller re-asserting a
+  -- terminal state may legitimately be attaching an annotation via p_metadata (CLI --metadata), and
+  -- silently dropping it would be a lossy success. The operator falls through to the mutator, which
+  -- now preserves left_at for an UNCHANGED terminal state anyway — so the operator keeps the
+  -- metadata merge without reacquiring the restamp defect.
+  if not v_is_service
+     and p_membership_state = v_existing_state
+     and p_membership_state in ('left', 'removed') then
+    -- MBROWID (3a): same active-preferring total-order as the authz pre-read above so
+    -- the no-op return row agrees with the state used for authorization.
+    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.board_id = p_board_id
+       and bm.agent_id = p_agent_id
+     order by
+       case when bm.membership_state in ('joined', 'subscribed') then 0 else 1 end,
+       bm.created_at desc,
+       bm.id desc
+     limit 1;
+    return;
+  end if;
+
+  select * into v_membership
+    from agent_board._upsert_board_membership_state(
+      p_board_id,
+      p_agent_id,
+      p_membership_state,
+      null,
+      p_metadata
+    );
+
+  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;
+$$;