@consiliency/agent-board-schema 1.60.0 → 1.64.0

package/migrations/20261012000100_agent_board_sidowner.sql

@@ -0,0 +1,209 @@
+-- SIDOWNER: safe, scoped session-identity inspection.  These reads deliberately
+-- expose only the normalized state an owner/ancestor needs to diagnose and approve.
+
+create function agent_board._session_identity_read_allowed(p_identity_agent_id uuid)
+returns boolean
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  with recursive lineage(agent_id, parent_agent_id) as (
+    select si.agent_id, si.parent_agent_id
+      from agent_board.session_identities si
+     where si.agent_id = p_identity_agent_id
+    union all
+    select parent.agent_id, parent.parent_agent_id
+      from agent_board.session_identities parent
+      join lineage child on child.parent_agent_id = parent.agent_id
+  )
+  select agent_board.current_agent_id() is not null
+     and (agent_board._session_identity_owner(p_identity_agent_id)
+      or exists (
+        select 1 from lineage where agent_id = agent_board.current_agent_id()
+      ));
+$$;
+revoke all on function agent_board._session_identity_read_allowed(uuid) from public, anon, authenticated;
+grant execute on function agent_board._session_identity_read_allowed(uuid) to service_role;
+comment on function agent_board._session_identity_read_allowed(uuid) is 'Internal SIDOWNER read predicate. A verified active human root owner, the selected identity, or its strict lineage ancestor may inspect its normalized identity state. It never treats a sibling or another root as an ancestor.';
+
+create function agent_board.get_session_identity_state(p_identity_agent_id uuid)
+returns table(
+  agent_id uuid,
+  parent_agent_id uuid,
+  root_agent_id uuid,
+  handle text,
+  depth smallint,
+  harness text,
+  lease_state text,
+  resolution_state text,
+  fingerprint_resolution text,
+  current_risky_digest text,
+  approved_risky_digest text,
+  recorded_fingerprint jsonb,
+  tombstoned_at timestamptz,
+  tombstone_reason text
+)
+language plpgsql
+stable
+security definer
+set search_path = ''
+as $$
+begin
+  if not agent_board._session_identity_read_allowed(p_identity_agent_id) then
+    raise exception 'identity_read_forbidden' using errcode = '42501';
+  end if;
+
+  return query
+  select si.agent_id,
+         si.parent_agent_id,
+         si.root_agent_id,
+         a.handle,
+         si.depth,
+         si.harness,
+         case
+           when si.identity_kind <> 'session' then 'not_applicable'
+           when si.holder_secret_hash is null then 'unclaimed'
+           when agent_board._session_identity_lease_live(si.agent_id) then 'live'
+           else 'lapsed'
+         end,
+         si.resolution_state,
+         coalesce(si.recorded_fingerprint ->> 'resolution', 'unresolved'),
+         si.current_risky_digest,
+         si.approved_risky_digest,
+         si.recorded_fingerprint,
+         si.tombstoned_at,
+         si.tombstone_reason
+    from agent_board.session_identities si
+    join agent_board.agents a on a.id = si.agent_id
+   where si.agent_id = p_identity_agent_id;
+end;
+$$;
+revoke all on function agent_board.get_session_identity_state(uuid) from public, anon;
+grant execute on function agent_board.get_session_identity_state(uuid) to authenticated, service_role;
+comment on function agent_board.get_session_identity_state(uuid) is 'SIDOWNER normalized safe identity-state read. The active human root owner, selected identity, or a strict lineage ancestor may inspect one identity, including tombstones. Missing and inaccessible identities both refuse identity_read_forbidden; no credential epochs, aliases, holder hashes, keys, or credentials are projected.';
+
+create function agent_board.list_session_children(p_parent_agent_id uuid)
+returns table(
+  agent_id uuid,
+  parent_agent_id uuid,
+  root_agent_id uuid,
+  handle text,
+  depth smallint,
+  harness text,
+  lease_state text,
+  resolution_state text,
+  fingerprint_resolution text,
+  current_risky_digest text,
+  approved_risky_digest text,
+  recorded_fingerprint jsonb,
+  tombstoned_at timestamptz,
+  tombstone_reason text
+)
+language plpgsql
+stable
+security definer
+set search_path = ''
+as $$
+begin
+  if not agent_board._session_identity_read_allowed(p_parent_agent_id) then
+    raise exception 'identity_read_forbidden' using errcode = '42501';
+  end if;
+
+  return query
+  with recursive descendants(agent_id) as (
+    select child.agent_id
+      from agent_board.session_identities child
+     where child.parent_agent_id = p_parent_agent_id
+    union all
+    select child.agent_id
+      from agent_board.session_identities child
+      join descendants parent on child.parent_agent_id = parent.agent_id
+  )
+  select state.agent_id,
+         state.parent_agent_id,
+         state.root_agent_id,
+         state.handle,
+         state.depth,
+         state.harness,
+         state.lease_state,
+         state.resolution_state,
+         state.fingerprint_resolution,
+         state.current_risky_digest,
+         state.approved_risky_digest,
+         state.recorded_fingerprint,
+         state.tombstoned_at,
+         state.tombstone_reason
+    from descendants d
+    cross join lateral agent_board.get_session_identity_state(d.agent_id) state
+   order by state.depth, state.agent_id;
+end;
+$$;
+revoke all on function agent_board.list_session_children(uuid) from public, anon;
+grant execute on function agent_board.list_session_children(uuid) to authenticated, service_role;
+comment on function agent_board.list_session_children(uuid) is 'SIDOWNER scoped strict-lineage descendant list. The parent is excluded; only parent_agent_id edges are traversed, never forked_from. Authorized callers receive the normalized safe projection for depth-one and depth-two descendants, including tombstones, ordered by depth then identity.';
+
+create function agent_board._session_identity_has_human_owner(p_root_agent_id uuid)
+returns boolean
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  select exists (
+    select 1 from agent_board.agents root
+      join agent_board.agents human on human.auth_user_id = root.owner_user_id
+     where root.id = p_root_agent_id
+       and human.agent_type = 'human'
+       and human.status = 'active'
+  );
+$$;
+revoke all on function agent_board._session_identity_has_human_owner(uuid) from public, anon, authenticated;
+grant execute on function agent_board._session_identity_has_human_owner(uuid) to service_role;
+comment on function agent_board._session_identity_has_human_owner(uuid) is 'Internal N1 root-owner existence predicate, not acting-human authorization: the root owner_user_id must bind an active human agent, matching the human-existence requirement of _session_identity_owner.';
+
+create or replace function agent_board.record_session_identity_state(p_identity_agent_id uuid, p_fingerprint jsonb)
+returns void language plpgsql security definer set search_path = '' as $$
+declare v_identity agent_board.session_identities%rowtype;
+  v_risky text := nullif(p_fingerprint ->> 'risky_digest', '');
+  v_recorded jsonb := coalesce(p_fingerprint -> 'recorded', '{}'::jsonb)
+    || jsonb_build_object('resolution', coalesce(p_fingerprint ->> 'resolution', 'unresolved'));
+begin
+  if not agent_board._is_service_role() then
+    raise exception 'identity reading is service_role-only' using errcode = '42501';
+  end if;
+  if coalesce(p_fingerprint ->> 'resolution', 'unresolved') not in ('resolved', 'unresolved') then
+    raise exception 'invalid identity fingerprint resolution' using errcode = '22023';
+  end if;
+  perform 1 from agent_board.agents where id = (
+    select root_agent_id from agent_board.session_identities where agent_id = p_identity_agent_id
+  ) for update;
+  select * into v_identity from agent_board.session_identities where agent_id = p_identity_agent_id for update;
+  if not found then raise exception 'identity not found' using errcode = 'P0002'; end if;
+  if v_identity.tombstoned_at is not null then raise exception 'identity_tombstoned' using errcode = '42501'; end if;
+  if not exists (select 1 from agent_board.agents a where a.id = p_identity_agent_id and a.auth_user_id = auth.uid() and a.status = 'active')
+     or (v_identity.identity_kind = 'session' and agent_board.current_agent_id() is distinct from p_identity_agent_id) then
+    raise exception 'identity_lease_not_held' using errcode = '42501';
+  end if;
+  if v_identity.depth = 0 and not agent_board._session_identity_has_human_owner(v_identity.root_agent_id) then
+    raise exception 'identity_human_owner_required' using errcode = '42501';
+  end if;
+  if jsonb_typeof(coalesce(p_fingerprint, '{}'::jsonb)) <> 'object' or jsonb_typeof(v_recorded) <> 'object' then
+    raise exception 'invalid identity fingerprint reading' using errcode = '22023';
+  end if;
+  -- Return normally: throwing here would roll back the freeze. SIDSERVER must
+  -- commit this measured reading before invoking a protected action separately.
+  update agent_board.session_identities
+     set current_risky_digest = v_risky, recorded_fingerprint = v_recorded,
+         resolution_state = case
+           when p_fingerprint ->> 'resolution' is distinct from 'resolved' or v_risky is null
+             or v_identity.approved_risky_digest is null then 'frozen'
+           when v_risky is distinct from v_identity.approved_risky_digest or v_identity.resolution_state = 'frozen' then 'frozen'
+           else 'active' end,
+         updated_at = now()
+   where agent_id = p_identity_agent_id;
+end;
+$$;
+revoke all on function agent_board.record_session_identity_state(uuid,jsonb) from public, anon, authenticated;
+grant execute on function agent_board.record_session_identity_state(uuid,jsonb) to service_role;
+comment on function agent_board.record_session_identity_state(uuid,jsonb) is 'Service-only fingerprint recording bound to verified subject and epoch, with root-before-identity locking. N1 refuses every depth-zero identity without a bound active human owner before any reading or freeze is stored. Other trusted session recording, durable freeze, explicit approval and lease-preservation semantics remain unchanged; no public body attestation is accepted.';

package/migrations/20261014000100_agent_board_grant_target_role.sql

@@ -0,0 +1,218 @@
+-- #674 (SECURITY): grant_board_role must check the TARGET's current role.
+--
+-- DEFECT. agent_board.grant_board_role authorized a grant by the NEW role only, through
+-- _grant_within_ceiling(grantor, board, new_role). It never read the target's CURRENT role, so
+-- any active member -- an observer included -- could demote every owner and admin of a board,
+-- and an admin could then remove them (update_board_membership refuses an admin removing an
+-- owner directly, but not an admin removing a member it had just demoted), leaving the board
+-- with no owner. Evidence: message-board-ui contracts/evidence/membership-semantics.md, C.2-C.5,
+-- C.7, E.1, E.3, E.4b, E.4c.
+--
+-- OWNER DECISIONS (2026-10-14, plans/plan-674-grant-target-role.md D0):
+--   1. deploy 1.63.0 and publish it to npm (with the 1.61.1/1.62.0 SID migrations);
+--   2. a rolled-back production probe is allowed;
+--   3. only owners and admins may change anyone ELSE's role.
+--
+-- THE RULE (D1-D9 in brief). Two checks, only when the grantor is a different AGENT ID from the
+-- target ("self" is the same agent id, not the same human):
+--   C-A (decision 3): grantor rank < admin  -> 42501 'grant on another member requires owner or admin role'
+--   C-B (#674):       grantor rank <= target's CURRENT rank
+--                                           -> 42501 'grant requires a higher board role than the target'
+-- Ranks are _role_rank's (owner 4, admin 3, member 2, observer 1, null/other 0), so a missing
+-- grantor row fails closed. Equal rank is refused for every rank: an owner cannot act on another
+-- owner (D3; symmetric with update_board_membership), an admin cannot act on another admin (D4),
+-- and a retry of a promotion to the grantor's own rank refuses. Any role may still lower ITSELF
+-- (D2); the unchanged ceiling bounds a self-grant to keep-or-lower. service_role keeps its
+-- existing supplied-grantor trust boundary (D8): the checks run relative to the grantor it
+-- names. The signed route inherits by construction. Delegates are unchanged (no EXECUTE; a
+-- delegate target is refused at step 2). boards.role_gate_enforced does not interact.
+-- #675 (ownerless boards through SELF-exit) stays separate and is not made worse (D9).
+--
+-- ORDER (D5). Steps 1-5 unchanged (role literal, delegate target, board advisory lock, resolved
+-- actor, fleet gate). Step 6 is now ONE statement: the target's active row locked
+-- FOR NO KEY UPDATE OF t -- the mode the UPDATE already takes, so the lock mode and set are
+-- unchanged and the lock is only taken earlier -- LEFT JOINed to the grantor's active row
+-- (unlocked). Step 7 the ceiling, unchanged. Step 8 C-A then C-B. Step 9 the UPDATE, unchanged.
+-- Every existing refusal keeps its code, message and precedence: P0002, then the ceiling, then
+-- the new checks. Lock order stays advisory -> agents(SHARE) -> board_memberships.
+--
+-- SOURCE RULE (R1, AGENTS.md rule 5). The body is pg_get_functiondef of
+-- agent_board.grant_board_role(uuid,uuid,text,uuid) on a fresh replay of this tree (160
+-- migrations; md5(prosrc) 038bad38eae94604312e38bc74a7782c), which is byte-identical to the
+-- live definition in 20261008000100_agent_board_hosted_delegates.sql:1893-1983, plus ONLY the
+-- #674-marked edits. It is NOT the body at 20260909000100:480, which predates the HOSTED
+-- delegate-target refusal; copying that one would silently revert it.
+--
+-- EC-1 (rule 1), run on that replay: pg_proc over every namespace except pg_catalog,
+-- information_schema, pg_toast, pg_temp* and the test helpers, subject
+-- agent_board_test.stripped_body(oid, true) (literals kept, so dynamic SQL counts), pattern
+-- agent_board_test.call_re('grant_board_role'), plus every view's stripped_viewdef: exactly
+-- {agent_board.signed_grant_board_role}; zero views. agent_board_grant_target_role.test.sql
+-- re-asserts it.
+--
+-- DEFINITION-ONLY: every top-level statement is `create or replace function`, `revoke`,
+-- `grant` or `comment`. No data is altered; past demotions made through the defect are not
+-- undone. Rollback posture: forward_corrective_migration -- repinning to 1.62.0 does NOT revert
+-- this, and restoring the old body would re-open the hole.
+--
+-- Same signature and return type, so CREATE OR REPLACE (not DROP). The ACL and the COMMENT are
+-- restated anyway, identical in ACL to 20260909000100:591-592.
+
+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::uuid)
+ RETURNS TABLE(board_id uuid, agent_id uuid, role text, updated_at timestamp with time zone)
+ LANGUAGE plpgsql
+ SECURITY DEFINER
+ SET search_path TO 'agent_board', 'public'
+AS $function$
+declare
+  v_grantor uuid;
+  v_updated agent_board.board_memberships%rowtype;
+  -- #674: the target's and the grantor's CURRENT active roles, read in one statement (step 6).
+  v_target_role text;
+  v_grantor_role text;
+begin
+  if p_grantee_role not in ('owner', 'admin', 'member', 'observer') then
+    raise exception 'invalid grantee role' using errcode = '22023';
+  end if;
+
+  -- #276, FORCED BY AN EXISTING CLASS ASSERTION, not chosen. Adding the ledger gate makes this
+  -- function row-lock `agents` (transitively, through _assert_actor_not_fleet_revoked) as well
+  -- as board_memberships, which puts it in the class agent_board_signer_lifecycle.test.sql
+  -- section 9 pins from the call-graph closure: every function locking BOTH relations must take
+  -- the board advisory lock that serialises them against onboard_federated_fleet_agent. That
+  -- assertion FAILED and named this function when the gate was added without this line.
+  --
+  -- The tempting reply is that this function's order is agents -> board_memberships, the SAME
+  -- direction as onboarding, so it cannot close the F4 cycle. That is true today and is exactly
+  -- the ordering argument #269 refused: mutual exclusion survives a lock being added downstream,
+  -- a re-derived ordering does not. So the lock is taken rather than the assertion relaxed.
+  --
+  -- It also closes a gap 20260901000110 left open and explicitly declined to determine: this
+  -- function reads the ceiling for authorization (via _grant_within_ceiling below) and was one
+  -- of the three readers that did NOT take the lock serialising the ceiling row's ABSENCE, so a
+  -- concurrent first-ceiling insert could be missed and the read pass as default-owner. It is
+  -- now serialised, and agent_board_atomic_fleet_onboarding.test.sql's ceiling-reader registry
+  -- records it as such.
+  --
+  -- FIRST, before any row lock, so both routes are advisory -> agents -> board_memberships.
+  -- Re-taking it inside signed_grant_board_role (which already holds it) is a no-op: advisory
+  -- transaction locks are re-entrant within a session.
+  -- HOSTED (role-writer class): a hosted delegate is a member, never higher.
+  perform agent_board._refuse_delegate_membership_target(p_agent_id, 'grant_board_role');
+
+  perform agent_board._lock_board_authority_ceiling(p_board_id);
+
+  -- 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');
+
+  -- #276. Fleet revocation removes board authority, not only send. Sited HERE — inside the
+  -- chokepoint, not in the signed wrapper — because signed_grant_board_role is the only other
+  -- referrer of this function in the whole database, so the signed route inherits this check
+  -- by construction and the unsigned `authenticated` route (the wider door) is closed by the
+  -- same line. Before the membership pre-check so the lock order is agents -> board_memberships,
+  -- matching onboard_federated_fleet_agent; below the write it would be the inversion #269
+  -- reproduced as `deadlock detected`, and this route has no advisory lock to be rescued by.
+  perform agent_board._assert_actor_not_fleet_revoked(v_grantor, 'grant_board_role');
+
+  -- #674 step 6. ONE statement replaces the bare EXISTS pre-check: the target's active row,
+  -- row-locked in NO KEY UPDATE mode, on t only (the mode the UPDATE below takes, only earlier),
+  -- LEFT JOINed to the grantor's active row, which is NOT locked. Its snapshot is taken after
+  -- the board advisory-lock wait above. After a row-lock wait, READ COMMITTED re-fetches only
+  -- the locked row t; the joined grantor row g keeps the statement snapshot's version. That is
+  -- benign (plan D5): every grant on this board and link_session_alias are excluded by the
+  -- advisory lock, and the one unserialized writer that can change an active grantor's role
+  -- (invite-link redeem's rank-max) only RAISES it, so a stale grantor rank is conservative.
+  -- A later change (#675's hook) must not rely on g being fresh after this statement.
+  -- Both reads are single-row by the partial unique index on active memberships.
+  select t.role, g.role
+    into v_target_role, v_grantor_role
+    from agent_board.board_memberships t
+    left join agent_board.board_memberships g
+      on g.board_id = t.board_id
+     and g.agent_id = v_grantor
+     and g.membership_state in ('joined', 'subscribed')
+   where t.board_id = p_board_id
+     and t.agent_id = p_agent_id
+     and t.membership_state in ('joined', 'subscribed')
+     for no key update of t;
+  if not found 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;
+
+  -- #674 step 8. Two checks for a grantor that is NOT the target (self = the same agent id,
+  -- not the same human). C-A (owner decision 3): only an owner or admin may change anyone
+  -- else's role. C-B (#674): the grantor must STRICTLY outrank the target's current role, so
+  -- equal rank is refused for every rank (owner -> owner, admin -> admin). Both read the roles
+  -- step 6 observed. A null role ranks 0, so a missing grantor row fails closed. C-A runs
+  -- before C-B; the ceiling above runs before both. Self-grants are exempt from both, and the
+  -- ceiling still bounds a self-grant to keep-or-lower.
+  if v_grantor is distinct from p_agent_id then
+    if agent_board._role_rank(v_grantor_role) < agent_board._role_rank('admin') then
+      raise exception 'grant on another member requires owner or admin role' using errcode = '42501';
+    end if;
+    if agent_board._role_rank(v_grantor_role) <= agent_board._role_rank(v_target_role) then
+      raise exception 'grant requires a higher board role than the target' using errcode = '42501';
+    end if;
+  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;
+$function$;
+
+revoke all on function agent_board.grant_board_role(uuid, uuid, text, uuid) from public, anon;
+grant execute on function agent_board.grant_board_role(uuid, uuid, text, uuid) to authenticated, service_role;
+
+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). #276: the resolved grantor is then checked against the fleet revocation ledger '
+  'by _assert_actor_not_fleet_revoked -- an agent carrying an agent-subject fleet_revocation_events '
+  'row cannot complete a grant (42501, ''fleet_revoked:''), which is the same answer '
+  'evaluate_fleet_sender_policy already gives that principal on the send path. The check sits in '
+  'THIS function rather than in signed_grant_board_role because signed_grant_board_role is the only '
+  'other referrer of it in the database, so the signed route inherits the gate and the wider '
+  'unsigned authenticated route is closed by the same line; it is placed before the membership '
+  'pre-check so the lock order is agents(FOR SHARE) -> board_memberships, matching '
+  'onboard_federated_fleet_agent. A principal with no fleet binding has no such row and is '
+  'unaffected. Then 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. '
+  '#674: the membership pre-check is ONE statement that locks the target''s active row FOR NO KEY '
+  'UPDATE OF t (the mode the UPDATE takes, only earlier; lock order unchanged: advisory -> '
+  'agents(SHARE) -> board_memberships) and LEFT JOINs the grantor''s active row, unlocked. After '
+  'the unchanged ceiling check, a grantor that is not the target (self = the same agent id, not '
+  'the same human) must be an owner or admin (C-A, 42501 ''grant on another member requires owner '
+  'or admin role'') and must strictly outrank the target''s CURRENT role (C-B, 42501 ''grant '
+  'requires a higher board role than the target''), so equal rank is refused for every rank. A '
+  'self-grant is exempt from both and stays bounded to keep-or-lower by the ceiling. For '
+  'service_role the checks run relative to the grantor the caller SUPPLIES -- the existing '
+  'operator-trust boundary, which #674 does not change (passing p_grantor_agent_id = p_agent_id '
+  'takes the self-exemption).';

package/migrations/20261014000200_agent_board_last_owner.sql

@@ -0,0 +1,239 @@
+-- Consiliency/message-board#675: row-level last-active-owner invariant, schema 1.64.0.
+-- Main's grant_board_role body, ACL and COMMENT remain unchanged (schema 1.63.0).
+-- The trigger is refusal-only: it never assigns NEW or clamps a role. The
+-- 20260802000100 / 20260803000100 prohibition concerns a role-changing clamp
+-- that would erase intentional owner/admin seeds; this UPDATE/DELETE guard
+-- leaves all allowed writes and INSERT seeders unchanged.
+
+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 $function$
+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;
+  -- HOSTED (D7): the caller is the target hosted delegate's principal asking for `left`.
+  v_principal_withdraw boolean;
+begin
+  if v_actor is null and not v_is_service then
+    raise exception 'current agent principal not resolved' using errcode = '42501';
+  end if;
+
+  -- Board authority lock first, before the target row and the sink's FK locks.
+  perform agent_board._lock_board_authority_ceiling(p_board_id);
+
+  v_principal_withdraw := not v_is_service
+    and v_actor <> p_agent_id
+    and p_membership_state = 'left'
+    and v_actor = agent_board._delegate_principal_agent_id(p_agent_id);
+
+  if not v_is_service and v_actor <> p_agent_id and not v_principal_withdraw 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;
+
+  -- HOSTED: LOCKED, so every transition rule below is decided on the state the sink will
+  -- overwrite. Unlocked, an admin's uncommitted `removed` committed after this read, and the D7
+  -- withdrawal (and an ordinary self-leave, the same branch shape) then wrote `left` over it in
+  -- the sink, erasing the eviction R-LINK-7 reads (hosted_delegate_withdraw_evict_race). The
+  -- sink's own first lock is this same row in the same order, so the lock set is unchanged;
+  -- it is only taken earlier, before reads that lock nothing.
+  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
+   for update;
+  if v_existing_state is null then
+    raise exception 'board membership not found' using errcode = 'P0002';
+  end if;
+
+  if v_principal_withdraw then
+    -- HOSTED (D7): the owner withdraws its own delegate whatever its board role, but ONLY from
+    -- the states a self-leave may leave. Never from `removed`: turning an eviction into `left`
+    -- would erase the standing R-LINK-7 reads and let the owner re-add the evicted delegate.
+    if v_existing_state not in ('joined', 'subscribed', 'invited', 'requested') then
+      raise exception 'a principal may withdraw its delegate only from an active or pending membership'
+        using errcode = '42501';
+    end if;
+  elsif not v_is_service then
+    if v_actor = p_agent_id then
+      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
+      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;
+
+      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;
+
+      -- INVITEPOLICY (#90): seating an inbound-disclosure membership ('invited'/'requested')
+      -- for a target that has blocked THIS actor is refused, mirroring invite_board_member.
+      -- Without this, an owner/admin re-seats the exact row the block refuses. Active-admission
+      -- states are already consent-gated above; service_role/self never reach this branch.
+      if p_membership_state in ('invited', 'requested')
+         and not agent_board._invite_permitted(p_board_id, p_agent_id, v_actor) then
+        raise exception 'target has blocked invitations from this inviter on this board'
+          using errcode = '42501';
+      end if;
+    end if;
+  end if;
+
+  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
+       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;
+$function$;
+
+-- Consiliency/message-board#675: enforce at the table so every RPC, raw writer,
+-- DELETE and FK cascade has the same invariant. Existing ownerless boards remain usable.
+create or replace function agent_board._board_memberships_last_owner_guard()
+returns trigger
+language plpgsql
+security definer
+set search_path = ''
+as $function$
+declare
+  v_key bigint := pg_catalog.hashtextextended(
+    'agent_board.board_authority_ceilings:' || old.board_id::text, 0);
+begin
+  if old.role <> 'owner' or old.membership_state not in ('joined', 'subscribed') then
+    if tg_op = 'DELETE' then return old; else return new; end if;
+  end if;
+  if tg_op = 'UPDATE' then
+    if new.board_id = old.board_id and new.agent_id = old.agent_id and new.role = 'owner'
+       and new.membership_state in ('joined', 'subscribed') then
+      return new;
+    end if;
+  end if;
+  -- Deleting the board itself is not leaving an existing board ownerless.
+  if not exists (select 1 from agent_board.boards where id = old.board_id) then
+    if tg_op = 'DELETE' then return old; else return new; end if;
+  end if;
+  -- A transaction snapshot does not advance after an advisory-lock wait.
+  if current_setting('transaction_isolation') <> 'read committed' then
+    raise exception 'last_active_board_owner: owner transitions require read committed'
+      using errcode = '25001';
+  end if;
+  -- Require the board mutex to have been acquired BEFORE the row lock. This
+  -- covers raw DML and cascades without taking a waiting lock in reverse order.
+  if not exists (
+    select 1 from pg_catalog.pg_locks l
+     where l.locktype = 'advisory' and l.pid = pg_catalog.pg_backend_pid()
+       and l.database = (select oid from pg_catalog.pg_database where datname = current_database())
+       and l.classid = ((v_key >> 32) & 4294967295)::oid
+       and l.objid = (v_key & 4294967295)::oid and l.objsubid = 1
+       and l.mode = 'ExclusiveLock' and l.granted
+  ) then
+    raise exception 'last_active_board_owner: acquire board authority lock before owner transition'
+      using errcode = '55000';
+  end if;
+  -- Re-entrant: it CANNOT wait, since this backend already holds the exclusive
+  -- key. Promote a session-level lock to transaction lifetime so releasing the
+  -- session lock early cannot let a second departure miss our uncommitted exit.
+  perform pg_catalog.pg_advisory_xact_lock(v_key);
+  -- A separate volatile statement has a fresh read-committed snapshot.
+  if not exists (
+    select 1 from agent_board.board_memberships bm
+     where bm.board_id = old.board_id and bm.id <> old.id
+       and bm.role = 'owner' and bm.membership_state in ('joined', 'subscribed')
+  ) then
+    raise exception 'last_active_board_owner: cannot remove the last active owner'
+      using errcode = '23514';
+  end if;
+  if tg_op = 'DELETE' then return old; else return new; end if;
+end;
+$function$;
+
+revoke all on function agent_board._board_memberships_last_owner_guard()
+  from public, anon, authenticated, service_role, agent_board_delegate;
+comment on function agent_board._board_memberships_last_owner_guard() is
+  'Consiliency/message-board#675: table-level UPDATE/DELETE guard against removing the last joined/subscribed owner of an existing board, including raw DML and cascades. No service-role bypass. Owner transitions require read committed and serialize to commit on the board authority advisory key; a pre-held exclusive board advisory lock is required (55000 otherwise) and reacquired re-entrantly for transaction lifetime. All waiting locks precede row locks. Existing ownerless boards and unrelated writes are unaffected; recovery by restoring ownership remains service_role-only.';
+
+create trigger trg_board_memberships_last_owner_guard
+  before update or delete on agent_board.board_memberships
+  for each row execute function agent_board._board_memberships_last_owner_guard();
+comment on trigger trg_board_memberships_last_owner_guard on agent_board.board_memberships is
+  'Refuse only a transition that removes an existing active owner and leaves no other active owner; every membership writer is covered by construction. Refusal-only: NEW is never rewritten. A future hard agent delete must acquire every owned board advisory lock before agent or membership row locks.';
+
+revoke all on function agent_board.update_board_membership(uuid,uuid,text,jsonb)
+  from public, anon, agent_board_delegate;
+grant execute on function agent_board.update_board_membership(uuid,uuid,text,jsonb)
+  to authenticated, service_role;
+
+comment on function agent_board.update_board_membership(uuid,uuid,text,jsonb) is
+  'Authorized membership state transitions with existing self, principal-withdrawal, rank, consent and idempotency rules. Consiliency/message-board#675: board advisory lock before target membership/FK locks; the table refuses any transition removing the last active owner.';
+
+comment on function agent_board._lock_board_authority_ceiling(uuid) is
+  'Board-keyed transaction advisory lock serializing the ABSENCE of a board_authority_ceilings row, held to commit. WRITERS[serialized: set_board_authority_ceiling][UNSERIALIZED: (none)] READERS[serialized: add_delegate_to_board, grant_board_role, link_session_alias, mint_delegated_child, onboard_federated_fleet_agent, readmit_session_identity][UNSERIALIZED: _redeem_unbounded_invite_for_agent, create_invite_link] The SIDSCHEMA readers take the mutexes for every requested or existing descendant room before root, identity and membership locks. The two UNSERIALIZED readers still evaluate a missing ceiling as default-owner without serializing its absence; that known race (message-board#277) is not changed here. Both lists are machine-compared against the catalog; a new reader/writer or changed serialization state fails by name. Internal invoker helper, not an authorization gate; caller privileges determine table access. Consiliency/message-board#675: also the per-board departure mutex, acquired by update_board_membership before row locks and held through commit; all destructive owner transitions require this key, including direct writes and hard agent-deletion cascades.';