@consiliency/agent-board-schema 1.10.0 → 1.22.0

package/migrations/20260801000100_agent_board_leaveidem_terminal_noop.sql

@@ -0,0 +1,317 @@
+-- LEAVEIDEM — terminal membership states are TRUE no-ops, and departure time is not
+-- caller-controlled. Closes message-board#81.
+--
+-- THEME (one invariant, two functions): re-asserting a terminal membership state must not mutate
+-- the row, and `left_at` / the reserved `ops_*` metadata namespace must not be writable by the
+-- agent whose retention they govern.
+--
+-- DEFECT 1 — leave_board is no longer idempotent (a regression introduced by MEMBSTATE, #77).
+-- `leave_board` (20260512000002:154-158) delegates into update_board_membership(..., 'left').
+-- MEMBSTATE's self-branch permits 'left' only FROM joined|subscribed|invited|requested, so a
+-- SECOND leave_board raises 42501 'self membership change not permitted'. Proven live. A naturally
+-- idempotent operation now hard-fails, and defensive client retries surface an authorization error.
+-- The 'removed' exclusion in that branch was correct and is PRESERVED — a kicked agent still may
+-- not erase its own kick marker (#79). Only the same-state terminal case is opened.
+--
+-- DEFECT 2 — `left_at` is caller-restampable, and it is the retention sweep's cutoff key.
+-- `_upsert_board_membership_state` unconditionally sets
+--     left_at = case when p_membership_state in ('left','removed') then now() else null end
+-- on EVERY call, so any repeat call into a terminal state moves the departure timestamp forward.
+-- `mark_retention_metadata` sweeps board_memberships on `left_at < cutoff`
+-- (20260513000001:115-121), so an agent able to restamp its own `left_at` can postpone its own
+-- row's retention indefinitely. This is NOT limited to the double-leave path: an owner re-kicking
+-- an already-`removed` member resets that row's clock too. Fixed at the mutator so every caller
+-- benefits: the FIRST departure time is preserved via coalesce(bm.left_at, now()).
+-- (Transitions back to a non-terminal state still NULL `left_at` — required by the
+-- board_memberships state/left_at CHECK, 20260515000000:18-25 — and that is correct: a
+-- re-activated membership has no departure time.)
+--
+-- DEFECT 3 — the reserved `ops_*` metadata namespace is caller-writable.
+-- The mutator merges caller-supplied p_metadata verbatim on every path. The retention sweep SKIPS
+-- rows whose `metadata->>'ops_retained_at'` is non-empty (20260513000001:122). So any caller that
+-- can reach the mutator — join_board, request_join_board, invite_board_member,
+-- resolve_board_request, update_board_membership/leave_board — can write that key and exclude the
+-- row from retention permanently. Note this is reachable on a FIRST leave, so the no-op fix alone
+-- would not close it. Caller-supplied keys in the reserved `ops_` namespace are now stripped
+-- before the merge; operational writers set them directly (mark_retention_metadata writes the
+-- column, it does not go through this mutator).
+--
+-- AUTHZ PLACEMENT (deliberate divergence from the review's suggestion). The panel proposed the
+-- early return sit between the existence check and the authorization block. That would hand an
+-- UNAUTHORIZED caller a successful no-op instead of 42501, turning the RPC into a membership-state
+-- oracle for arbitrary (board, agent) pairs. Instead the self-branch permits the same-state
+-- terminal call, and the no-op return happens AFTER the authorization block — so authority is
+-- still required, the 42501 posture for unauthorized callers is unchanged, and the caller who is
+-- entitled to act simply gets an unchanged row back.
+--
+-- Additive, forward-only. No signature change (so no PostgREST reload and no client/mcp/cli
+-- surface change); leave_board inherits the fix automatically through its delegation. Writes no
+-- agent_board.schema_version (stays 8).
+
+-- 1. Mutator: preserve the first departure time; strip the reserved ops_ namespace. -------------
+create or replace function agent_board._upsert_board_membership_state(
+  p_board_id uuid,
+  p_agent_id uuid,
+  p_membership_state text,
+  p_created_by_agent_id uuid default null,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns agent_board.board_memberships
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_membership agent_board.board_memberships%rowtype;
+  v_metadata jsonb;
+begin
+  if p_membership_state not in ('requested', 'invited', 'joined', 'subscribed', 'left', 'removed') then
+    raise exception 'invalid board membership state' using errcode = '22023';
+  end if;
+
+  -- Metadata must be a JSON OBJECT. Previously a scalar/array was stored verbatim on insert and
+  -- concatenated on update; the reserved-key strip below iterates keys, so a non-object would raise
+  -- an opaque internal error. Fail explicitly instead. Reachable from the CLI `--metadata`, which
+  -- parses arbitrary JSON — this is a deliberate, declared behavior change for ALL mutator callers.
+  if jsonb_typeof(coalesce(p_metadata, '{}'::jsonb)) <> 'object' then
+    raise exception 'board membership metadata must be a JSON object' using errcode = '22023';
+  end if;
+
+  -- Reserved namespace: `ops_*` keys are operational state (the retention sweep's skip marker
+  -- `ops_retained_at`, read for board_memberships at 20260513000001:122) and must never be writable
+  -- by a caller whose own row they govern. Strip them from caller input; operational writers set
+  -- the column directly.
+  select coalesce(jsonb_object_agg(e.key, e.value), '{}'::jsonb)
+    into v_metadata
+    from jsonb_each(coalesce(p_metadata, '{}'::jsonb)) as e(key, value)
+   where e.key not like 'ops\_%';
+
+  select *
+    into v_membership
+    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
+   limit 1
+   for update;
+
+  if v_membership.id is null then
+    insert into agent_board.board_memberships(board_id, agent_id, membership_state, created_by_agent_id, left_at, metadata)
+    values (
+      p_board_id,
+      p_agent_id,
+      p_membership_state,
+      p_created_by_agent_id,
+      case when p_membership_state in ('left', 'removed') then now() else null end,
+      v_metadata
+    )
+    returning * into v_membership;
+  else
+    update agent_board.board_memberships bm
+       set membership_state = p_membership_state,
+           created_by_agent_id = coalesce(p_created_by_agent_id, bm.created_by_agent_id),
+           -- PRESERVE the first departure time. Restamping it would let the departing agent (or a
+           -- re-kicking owner) push its own row past the retention cutoff (20260513000001:121).
+           left_at = case
+                       when p_membership_state in ('left', 'removed') then
+                         case
+                           -- SAME terminal state re-asserted: preserve the FIRST departure time so a
+                           -- repeat call cannot push the retention cutoff forward.
+                           when v_membership.membership_state = p_membership_state
+                             then coalesce(v_membership.left_at, now())
+                           -- GENUINE transition (notably left -> removed, an owner barring
+                           -- invite-link re-entry for an already-departed agent) stamps NOW. R-LINK-7
+                           -- deliberately does not block voluntary 'left' (20260724000100:321-322),
+                           -- so this is the real kick moment; inheriting the earlier departure would
+                           -- both lose the audit answer and make the marker row retention-eligible
+                           -- prematurely.
+                           else now()
+                         end
+                       else null
+                     end,
+           metadata = coalesce(bm.metadata, '{}'::jsonb) || v_metadata,
+           updated_at = now()
+     where bm.id = v_membership.id
+     returning * into v_membership;
+  end if;
+
+  return v_membership;
+end;
+$$;
+
+comment on function agent_board._upsert_board_membership_state(uuid, uuid, text, uuid, jsonb) is
+  'UNAUTHORIZED PRIMITIVE — accepts any membership state and never writes `role`; every caller '
+  'MUST gate. LEAVEIDEM (#81): preserves the FIRST left_at across repeated terminal transitions '
+  '(the retention sweep keys on left_at, 20260513000001:121) and strips the reserved `ops_*` '
+  'metadata namespace from caller input (the sweep skips rows carrying ops_retained_at).';
+
+-- 2. update_board_membership: same-state terminal calls are true no-ops, AFTER authorization. ---
+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 timestamptz, updated_at timestamptz)
+language plpgsql
+security definer
+set search_path = 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.
+  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 bm.created_at 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.
+      if agent_board._role_rank(v_actor_role)
+         <= agent_board._role_rank(coalesce(v_target_role, '')) then
+        raise exception 'board membership change requires a higher board role than the target'
+          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
+    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 bm.created_at 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;
+$$;
+
+comment on function agent_board.update_board_membership(uuid, uuid, text, jsonb) is
+  'Updates a board membership state. MEMBSTATE (#75): service_role retains full '
+  'modify-on-behalf-of; an authenticated caller with an unresolved actor fails closed (42501); a '
+  'caller acting on its OWN membership may only leave or toggle joined<->subscribed (promotion '
+  'into a board belongs to the join/approval path, so a requested/invited/left/removed principal '
+  'cannot self-approve or re-enter); a caller acting on ANOTHER agent''s membership must hold an '
+  'active owner/admin membership AND strictly higher board rank than the target. LEAVEIDEM (#81): '
+  'a same-state terminal call (left->left, removed->removed) is a TRUE no-op returned unchanged '
+  'AFTER authorization — leave_board is idempotent again and left_at is never restamped.';
+
+-- Re-assert grants (create or replace preserves them, but be explicit so a fresh replay is
+-- order-independent) — house convention, 20260725000100:229-232.
+revoke all on function agent_board._upsert_board_membership_state(uuid, uuid, text, uuid, jsonb)
+  from public, anon, authenticated;
+grant execute on function agent_board._upsert_board_membership_state(uuid, uuid, text, uuid, jsonb)
+  to service_role;
+revoke all on function agent_board.update_board_membership(uuid, uuid, text, jsonb) from public, anon;
+grant execute on function agent_board.update_board_membership(uuid, uuid, text, jsonb)
+  to authenticated, service_role;

package/migrations/20260802000100_agent_board_rolereset_reentry_clamp.sql

@@ -0,0 +1,237 @@
+-- MBROLERESET — role is not identity across membership re-entry. Closes message-board#79.
+--
+-- THEME: an elevated board role must not survive a non-active -> active transition. Today
+-- `_upsert_board_membership_state` never writes `role` (INSERT omits it; UPDATE omits it), so
+-- a removed/left/requested/invited row that re-enters as joined|subscribed keeps whatever role
+-- was last written — including a prior admin/owner, and including grants applied while the row
+-- was still non-active (the re-arm half of #79). Separately, `grant_board_role` matches any
+-- membership row by board_id+agent_id alone, so a grant onto a removed row succeeds and parks
+-- the elevated role for the next re-entry.
+--
+-- CHANGE 1 — re-entry role clamp in `_upsert_board_membership_state` (UPDATE branch only).
+-- When the target state is joined|subscribed AND the pre-read origin is NOT already
+-- joined|subscribed, set role = 'member' (the table default at 20260717000100:13-15). Hardcoded
+-- — do not read information_schema.columns.column_default at runtime (it returns the quoted
+-- expression '''member''::text', not the value, and assigning it trips the CHECK). The INSERT
+-- branch is intentionally untouched: no-prior-row entry already omits role and takes the table
+-- default. Active -> active (joined <-> subscribed) preserves role, including owner.
+--
+-- This clamp is NECESSARY but NOT a chokepoint. Four raw-INSERT writers bypass
+-- `_upsert_board_membership_state` entirely and are deferred to a follow-up phase (MBROWID):
+--   * create_board owner seed          (20260723000100:103-106)
+--   * bootstrap_board_owner_memberships (20260723000100:149-152)
+--   * _redeem_invite_for_agent         (20260724000100:345-360)
+--   * _fedsession_autojoin_default_board (20260729000100:319-330)
+-- Those paths intentionally write non-default roles (owner / preset admin). A trigger on
+-- board_memberships is FORBIDDEN for the same reason: a BEFORE INSERT/UPDATE trigger would
+-- also fire for those four seeders and erase their intentional roles. The clamp lives in the
+-- mutator only.
+--
+-- No service_role exemption. An operator re-activating an evicted agent gets the default role;
+-- elevation is an explicit subsequent grant_board_role call.
+--
+-- CHANGE 2 — active-membership filter in `grant_board_role` (pre-check AND UPDATE).
+-- Both places gain `and bm.membership_state in ('joined','subscribed')`. Pre-check alone leaves
+-- a TOCTOU window (eviction between check and UPDATE); UPDATE alone leaves v_updated NULL so
+-- RETURN QUERY emits a bogus all-null row. Error message and errcode stay exactly
+-- 'grantee has no membership on this board' / P0002. Grantor binding
+-- (_resolved_actor_agent_id) and _grant_within_ceiling are unchanged — no privilege-escalation
+-- regression.
+--
+-- SOLE-OWNER LOCKOUT (documented limitation, not a defect of this migration): a sole owner who
+-- self-leaves is clamped to 'member' on rejoin, and grant_board_role CANNOT restore them --
+-- it checks _grant_within_ceiling unconditionally with no service_role bypass, so an operator
+-- must nominate a grantor that already holds rank, and by construction none exists.
+-- Recovery DOES exist and is an RPC: leave again (so the creator holds no ACTIVE membership),
+-- then call bootstrap_board_owner_memberships(), which raw-inserts a joined/owner row for a
+-- creator lacking one (20260723000100:138-166). Exercised end-to-end by assertion 23 of
+-- tests/agent_board_rolereset.test.sql. An earlier draft of this header claimed there was NO
+-- RPC recovery; that was refuted during review and is corrected here rather than shipped into
+-- immutable released bytes.
+--
+-- Additive, forward-only. No signature change. Last-definer rule: bodies are copied forward from
+-- 20260801000100 (_upsert) and 20260723000200 (grant_board_role) and modified in place.
+
+-- 1. _upsert_board_membership_state: re-entry role clamp on the UPDATE branch only ------------
+create or replace function agent_board._upsert_board_membership_state(
+  p_board_id uuid,
+  p_agent_id uuid,
+  p_membership_state text,
+  p_created_by_agent_id uuid default null,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns agent_board.board_memberships
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_membership agent_board.board_memberships%rowtype;
+  v_metadata jsonb;
+begin
+  if p_membership_state not in ('requested', 'invited', 'joined', 'subscribed', 'left', 'removed') then
+    raise exception 'invalid board membership state' using errcode = '22023';
+  end if;
+
+  -- Metadata must be a JSON OBJECT. Previously a scalar/array was stored verbatim on insert and
+  -- concatenated on update; the reserved-key strip below iterates keys, so a non-object would raise
+  -- an opaque internal error. Fail explicitly instead. Reachable from the CLI `--metadata`, which
+  -- parses arbitrary JSON — this is a deliberate, declared behavior change for ALL mutator callers.
+  if jsonb_typeof(coalesce(p_metadata, '{}'::jsonb)) <> 'object' then
+    raise exception 'board membership metadata must be a JSON object' using errcode = '22023';
+  end if;
+
+  -- Reserved namespace: `ops_*` keys are operational state (the retention sweep's skip marker
+  -- `ops_retained_at`, read for board_memberships at 20260513000001:122) and must never be writable
+  -- by a caller whose own row they govern. Strip them from caller input; operational writers set
+  -- the column directly.
+  select coalesce(jsonb_object_agg(e.key, e.value), '{}'::jsonb)
+    into v_metadata
+    from jsonb_each(coalesce(p_metadata, '{}'::jsonb)) as e(key, value)
+   where e.key not like 'ops\_%';
+
+  select *
+    into v_membership
+    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
+   limit 1
+   for update;
+
+  if v_membership.id is null then
+    -- INSERT branch intentionally omits `role` so a no-prior-row entry takes the table default
+    -- (20260717000100:13-15). Do not write role here — an explicit write is wrong.
+    insert into agent_board.board_memberships(board_id, agent_id, membership_state, created_by_agent_id, left_at, metadata)
+    values (
+      p_board_id,
+      p_agent_id,
+      p_membership_state,
+      p_created_by_agent_id,
+      case when p_membership_state in ('left', 'removed') then now() else null end,
+      v_metadata
+    )
+    returning * into v_membership;
+  else
+    update agent_board.board_memberships bm
+       set membership_state = p_membership_state,
+           created_by_agent_id = coalesce(p_created_by_agent_id, bm.created_by_agent_id),
+           -- PRESERVE the first departure time. Restamping it would let the departing agent (or a
+           -- re-kicking owner) push its own row past the retention cutoff (20260513000001:121).
+           left_at = case
+                       when p_membership_state in ('left', 'removed') then
+                         case
+                           -- SAME terminal state re-asserted: preserve the FIRST departure time so a
+                           -- repeat call cannot push the retention cutoff forward.
+                           when v_membership.membership_state = p_membership_state
+                             then coalesce(v_membership.left_at, now())
+                           -- GENUINE transition (notably left -> removed, an owner barring
+                           -- invite-link re-entry for an already-departed agent) stamps NOW. R-LINK-7
+                           -- deliberately does not block voluntary 'left' (20260724000100:321-322),
+                           -- so this is the real kick moment; inheriting the earlier departure would
+                           -- both lose the audit answer and make the marker row retention-eligible
+                           -- prematurely.
+                           else now()
+                         end
+                       else null
+                     end,
+           -- ROLERESET (#79): clamp role to the table default on non-active -> active re-entry.
+           -- Hardcoded 'member' (column default at 20260717000100:13-15); do not read
+           -- information_schema at runtime. Active -> active preserves bm.role (including owner).
+           -- Unconditional — no service_role exemption.
+           role = case
+                    when p_membership_state in ('joined', 'subscribed')
+                     and v_membership.membership_state not in ('joined', 'subscribed')
+                    then 'member'
+                    else bm.role
+                  end,
+           metadata = coalesce(bm.metadata, '{}'::jsonb) || v_metadata,
+           updated_at = now()
+     where bm.id = v_membership.id
+     returning * into v_membership;
+  end if;
+
+  return v_membership;
+end;
+$$;
+
+comment on function agent_board._upsert_board_membership_state(uuid, uuid, text, uuid, jsonb) is
+  'UNAUTHORIZED PRIMITIVE — accepts any membership state; every caller MUST gate. ROLERESET '
+  '(#79): on the UPDATE path only, clamps role to the table default (''member'', '
+  '20260717000100:13-15) when transitioning from a non-active origin into joined|subscribed; '
+  'INSERT omits role and takes the table default. Active->active preserves role. LEAVEIDEM '
+  '(#81): preserves the FIRST left_at across repeated terminal transitions (the retention sweep '
+  'keys on left_at, 20260513000001:121) and strips the reserved `ops_*` metadata namespace from '
+  'caller input (the sweep skips rows carrying ops_retained_at). Not a chokepoint — raw-INSERT '
+  'seeders (create_board owner, bootstrap, invite redeem, fedsession autojoin) bypass this '
+  'function and are out of scope (MBROWID).';
+
+-- 2. grant_board_role: refuse grants onto non-active memberships (pre-check + UPDATE) ---------
+create or replace function agent_board.grant_board_role(
+  p_board_id uuid,
+  p_agent_id uuid,
+  p_grantee_role text,
+  p_grantor_agent_id uuid default null
+)
+returns table(board_id uuid, agent_id uuid, role text, updated_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_grantor uuid;
+  v_updated agent_board.board_memberships%rowtype;
+begin
+  if p_grantee_role not in ('owner', 'admin', 'member', 'observer') then
+    raise exception 'invalid grantee role' using errcode = '22023';
+  end if;
+
+  -- Grantor is the RESOLVED actor. service_role -> supplied arg; authenticated ->
+  -- current_agent_id() and raises 42501 if null (suspended/unmapped) or if the
+  -- supplied arg <> current_agent_id(). This closes the single-principal escalation.
+  v_grantor := agent_board._resolved_actor_agent_id(p_grantor_agent_id, 'p_grantor_agent_id');
+
+  if 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')
+  ) then
+    raise exception 'grantee has no membership on this board' using errcode = 'P0002';
+  end if;
+
+  -- Ceiling consumption: grantee-bounded against min(grantor role, board ceiling).
+  if not agent_board._grant_within_ceiling(v_grantor, p_board_id, p_grantee_role) then
+    raise exception 'grant exceeds grantor role or board authority ceiling' using errcode = '42501';
+  end if;
+
+  update agent_board.board_memberships bm
+     set role = p_grantee_role,
+         updated_at = now()
+   where bm.board_id = p_board_id
+     and bm.agent_id = p_agent_id
+     and bm.membership_state in ('joined', 'subscribed')
+   returning * into v_updated;
+
+  -- CR finding: the state predicate above closes the unauthorized WRITE, but on its own it
+  -- CREATES a false-success path. If an eviction commits between the pre-check and this
+  -- UPDATE (the TOCTOU window the mirrored predicate exists for), the UPDATE matches zero
+  -- rows, v_updated stays NULL, and the RETURN QUERY below would emit ONE ALL-NULL ROW with
+  -- no error -- a caller that checks "did I get a row back?" reads that as a completed grant.
+  -- Fail closed with the same P0002 the pre-check raises, so the serial and racing cases are
+  -- indistinguishable to the caller.
+  if not found then
+    raise exception 'grantee has no membership on this board' using errcode = 'P0002';
+  end if;
+
+  return query
+  select v_updated.board_id, v_updated.agent_id, v_updated.role, v_updated.updated_at;
+end;
+$$;
+
+comment on function agent_board.grant_board_role(uuid, uuid, text, uuid) is
+  'Live board-role grant chokepoint. Grantor is the resolved actor (_resolved_actor_agent_id: '
+  'service_role uses the supplied arg, authenticated uses current_agent_id() and fails closed on '
+  'null/mismatch). Requires an ACTIVE grantee membership (joined|subscribed; P0002 otherwise) — '
+  'predicate on both the pre-check and the UPDATE (TOCTOU). Then enforces '
+  '_grant_within_ceiling(grantor, board, grantee_role) before setting board_memberships.role. '
+  'ROLERESET (#79): non-active rows cannot be re-armed with an elevated role.';