@consiliency/agent-board-schema 1.12.0 → 1.23.0

package/fixtures/already-applied.json

@@ -328,6 +328,166 @@
     {
       "id": "20260730000200_agent_board_membstate_authz",
       "sha256": "a4d935614f970a946f27a5925c0166e1d41510a82078e559fb769f4ea39afc2e"
+    },
+    {
+      "id": "20260731000100_agent_board_agentsdir_column_scope",
+      "sha256": "e05ddbbcf778828dbc4ba2631a5a288567d361371a60373c7e9090b718aa7433"
+    },
+    {
+      "id": "20260801000100_agent_board_leaveidem_terminal_noop",
+      "sha256": "72b20a3a365d0c84969cd1129cbc04578ee487a70e28a4245171c2abc68ec779"
+    },
+    {
+      "id": "20260802000100_agent_board_rolereset_reentry_clamp",
+      "sha256": "d04f596cdc97dc2ddc83348ee49c48888b334d12c31394586e7058409fa48cce"
+    },
+    {
+      "id": "20260803000100_agent_board_rowid_total_order",
+      "sha256": "a3c58ff1f55d3134c6096d10bf56df09db573938e7b4b92c13b7389451dd4c3c"
+    },
+    {
+      "id": "20260804000100_agent_board_hygiene_actor_binding_rls",
+      "sha256": "3feac0b5002bbff56c89adc3b9f071e21e1bb5ab2c4eea1571cfb61f254caa88"
+    },
+    {
+      "id": "20260806000100_agent_board_consent_substrate",
+      "sha256": "91ba2ec5885dfcaaa138ab3da3665a6779b6149147045773dfcbb707cfd9db07"
+    },
+    {
+      "id": "20260807000100_agent_board_consent_emission",
+      "sha256": "b6fb6f8254169d4fc3ab8016ab2f9ec2a2800c800178aebb602ff1db4aa0e7ee"
+    },
+    {
+      "id": "20260808000100_agent_board_rejectsem",
+      "sha256": "945a719e127573816cb9d18e318cf0778a99f3b0f8239b8e6ae0f8e62b04d919"
+    },
+    {
+      "id": "20260809000100_agent_board_consent_gating",
+      "sha256": "666e413ae1474e5e00de4d2bf2e7f7733f6ad149c91c3ef9a938e049115e387c"
+    },
+    {
+      "id": "20260810000100_agent_board_consent_locking",
+      "sha256": "d027468d3adb8563563f4fac4b13140013b68f28f39abe37c1de487c7fd36978"
+    },
+    {
+      "id": "20260811000100_agent_board_retention_metadata_revoke",
+      "sha256": "8d08dc986d532862d6593fe49b2e38e7447e57006360cae3406127c820ec19d6"
+    },
+    {
+      "id": "20260812000100_agent_board_pubexec_class_revoke",
+      "sha256": "34dabae96c11ab7fce68d71f1aa782eccef1bce5de4ad0567013d73949815606"
+    },
+    {
+      "id": "20260813000100_agent_board_invitepolicy_block",
+      "sha256": "8ee82c196483bf7d80091a46f6189328934fda2345947aea905505e37090719d"
+    },
+    {
+      "id": "20260814000100_agent_board_obsgate_thread_post_policy",
+      "sha256": "b36433d8aa78413b3d1e5119c45f8a24d37de053d03f4c4fd47b449814c4becb"
+    },
+    {
+      "id": "20260815000100_agent_board_obsgate2_authoring_gates",
+      "sha256": "7e76aa13aef8450aba50eb08d9da66b75a55457f41e3c92662137a1f6d7e2850"
+    },
+    {
+      "id": "20260816000100_agent_board_obsgate3_task_lifecycle",
+      "sha256": "921cc40511e4070c61f7b164a7528362a9662da2b902252a3e92091f01ebf0fd"
+    },
+    {
+      "id": "20260817000100_agent_board_obsgate4_claims_lifecycle",
+      "sha256": "6dd2d7928df2dff87c61b52e7edb75c5ec781fec5a85dd7c4273dadfd162f8ef"
+    },
+    {
+      "id": "20260818000100_agent_board_fleet_machines_rls_correlation",
+      "sha256": "f8bca2d75755589a1fa72d0c30ca799bd20db776d73a3a5e27832e112b57ea5d"
+    },
+    {
+      "id": "20260819000100_agent_board_resolve_noop_retire",
+      "sha256": "68bcb6d1b7e8ee8424e6d1d13a5a7d2c7d4554f348cc2cbf946ec95999517ac5"
+    },
+    {
+      "id": "20260820000100_agent_board_roomdeleg_lane_b",
+      "sha256": "2b10b8507b9bc704e9419b93d6d5d0af6d24f0ceef28c3eaa520516158f6c3e2"
+    },
+    {
+      "id": "20260821000100_agent_board_claimgate_claimkey",
+      "sha256": "caf8a83d4f39fc0a3d76d5b97077f0c3cf281305e47c50d370e940497a211022"
+    },
+    {
+      "id": "20260822000100_agent_board_mint_harden",
+      "sha256": "67585b17791598391515e63fa680c35cedaf27edc7ba3296f98242b925b9f490"
+    },
+    {
+      "id": "20260822000200_agent_board_mint_harden_fingerprint_backfill",
+      "sha256": "8bfd8e1bde5dbe85f21f5e0eb6c8f34462d16b92a763977ad9930539ac259698"
+    },
+    {
+      "id": "20260823000100_agent_board_fleet_machine_hijack",
+      "sha256": "73dcb65af8f8c754e2c6cc1c29f8649619a7653519a36a6b3acddf1a344a2bee"
+    },
+    {
+      "id": "20260824000100_agent_board_claimgate_shadow",
+      "sha256": "da42126b6cf40b0b044513313b0921394cd25de13426b16bcebd09bbcf5310a1"
+    },
+    {
+      "id": "20260825000100_agent_board_claimgate_enforce",
+      "sha256": "7264c8ff93f366238788f1a68c72a7ca0651da6e1b0cd9e27516e9acc01e6d3f"
+    },
+    {
+      "id": "20260826000100_agent_board_fleet_machine_reactivation",
+      "sha256": "fe437413046fba73b5306f1e21de81116369989a5d6e934a57c83c91bd5abb4b"
+    },
+    {
+      "id": "20260828000100_agent_board_delegation_cap_ceiling",
+      "sha256": "b9556374b6e512cc4f2ffc6a6d80d2abceca9ae1963e0f0ecdcd0485f6580e9e"
+    },
+    {
+      "id": "20260829000100_agent_board_fleet_machine_reclaim",
+      "sha256": "6ba17d49d5ef9ced3824f4f7ef7dbb40dd9ac3564576dad8b479545b2bab3b19"
+    },
+    {
+      "id": "20260830000100_agent_board_delegation_sole_writer",
+      "sha256": "26f5febc3c63f665eeb6eca2909d72187f16bae2c2643065e8ddb7c919086a86"
+    },
+    {
+      "id": "20260831000100_agent_board_fleet_domain_reclaim",
+      "sha256": "8d24ec4d682969a5d9339aec0573fad65ee95993dce2f8dca214906549b5ebe8"
+    },
+    {
+      "id": "20260901000100_agent_board_atomic_fleet_onboarding",
+      "sha256": "4cf07673b7c7da4ee13550e71d2bfe606b4b9c56971169e1ef61ac0d545ac6ef"
+    },
+    {
+      "id": "20260901000110_agent_board_fleet_onboarding_ceiling_lock",
+      "sha256": "310a32931562be6b4ad323b5e2926ebe459d6cd31bd6f601c7b862f354b5ce58"
+    },
+    {
+      "id": "20260901000120_agent_board_human_revocation_evidence_completeness",
+      "sha256": "e8ccb3605fb6dfa4e8dfbefbbb4328179a61aec00616c1abef27d6a09c2a913e"
+    },
+    {
+      "id": "20260901000130_agent_board_fedsession_human_revocation_gate",
+      "sha256": "f76d78973b87cc66c54ca0af4754358221ede19c8e0644df81a08e65dab0e89b"
+    },
+    {
+      "id": "20260901000140_agent_board_fedsession_board_owner_lock_order",
+      "sha256": "2388528532e974ab27c35337f9b00263056c1b16d973b7b3a0cf8cebb7724cc4"
+    },
+    {
+      "id": "20260902000100_agent_board_outbox_wake_ordering",
+      "sha256": "d3557acc29bf146862920fe903c3ac2e9e0e0317f3ca2134c5bb0835620fd2da"
+    },
+    {
+      "id": "20260903000100_agent_board_enroll_identity_board_owner_lock_order",
+      "sha256": "f8dc4ae6c5c6ea56183258402ab283cd424929b8e637984a59cf6ecd0685f681"
+    },
+    {
+      "id": "20260903000200_agent_board_fedsession_provider_absence_gate",
+      "sha256": "79c581011be386d0efd97db723d3aa07947ad7b996667878ed1387cdd106b000"
+    },
+    {
+      "id": "20260904000100_agent_board_wake_recovery_surface",
+      "sha256": "6349f705751104c5d60ec6602ea534e7c8b7de5c4c6ad2d84dbda680a5267848"
     }
   ]
 }

package/migrations/20260731000100_agent_board_agentsdir_column_scope.sql

@@ -0,0 +1,88 @@
+-- AGENTSDIR — stop exposing identity-linkage columns of agent_board.agents to `authenticated`.
+-- Tracks message-board#80.
+--
+-- THE DEFECT. The SELECT policy on agent_board.agents is
+--   agent_board_authenticated_select_agents USING (agent_board.current_agent_id() is not null)
+-- (20260512000003_agent_board_auth_rls.sql:48-54) — effectively TRUE for any principal that
+-- resolves to an active agent. Combined with a TABLE-LEVEL `grant select` to `authenticated` and
+-- PostgREST exposing the agent_board schema, ANY authenticated JWT reads EVERY agent row and
+-- EVERY column. Measured live as role `authenticated` with RLS enforced: 6 of 6 agents visible,
+-- 5 exposing auth_user_id.
+--
+-- Post-FEDSESSION every Portal-federated human has an agents row, so this is cross-tenant: one
+-- signed-in human enumerates every other human and agent on the deployment.
+--
+-- WHY COLUMN SCOPE, NOT ROW SCOPE. The 4-seat plan panel unanimously rejected row-scoping, and
+-- each objection was reproduced live before this migration was written:
+--   * `agents` IS the product's participant directory by contract — specs/schema.md:179 ("the
+--     canonical participant directory for both humans and automation"), and specs/read-models.md
+--     designates v_agent_dashboard the sanctioned substitute precisely so clients need not read
+--     this table. Handle/display_name are the feature, not the leak.
+--   * A co-member row predicate is DEAD CODE: board_memberships' own SELECT policy is self-scoped
+--     (20260515000000:465-472) and RLS applies inside a policy's USING expression, so a join to
+--     another agent's membership row can never match. Verified: a board owner was invisible to
+--     their own co-member.
+--   * ~18 views INNER JOIN agents, so an invisible row DELETES the row rather than hiding a name.
+--     Verified: after an author left a board, v_board_feed went 1 -> 0 — historical messages
+--     vanished for everyone still on the board. Same class would drop stranger-created `open`
+--     boards from discovery (v_board_directory) and escalations from the supervision feed
+--     (v_open_escalations).
+--   * Row scope kills invite-by-handle: resolve_agent_handle is SECURITY INVOKER and bounded by
+--     this very policy (20260727000100:119), so you could only invite people you ALREADY share a
+--     board with — which is what an invite creates.
+--   * Board co-membership is not a trust boundary anyway: a creator can force-join any agent
+--     without consent (message-board#82, verified live), so it is manufacturable in two calls.
+-- What actually leaks is IDENTITY LINKAGE, which is a column property:
+--   auth_user_id / owner_user_id  — raw auth.users UUIDs, cross-linkable to Portal identity
+--   parent_agent_id / root_agent_id — the delegation lineage graph
+--   metadata — the field LOCALAUTH deliberately keeps plaintext email OUT of precisely because
+--              this table is broadly readable (20260726000100:15-22)
+-- No view granted to `authenticated` projects ANY of those columns, and no client/CLI/MCP package
+-- reads this table directly (they go through views and RPCs) — so scoping columns removes the
+-- exposure at ~zero product risk.
+--
+-- MECHANISM NOTE (this is why the migration is shaped this way). A column-level
+-- `revoke select (col, ...)` is a NO-OP while a table-level `grant select` exists — the
+-- table-level grant covers every column, including ones added later. Verified live: the
+-- "revoke columns" form left auth_user_id readable. The table-level grant must be revoked FIRST
+-- and only the permitted columns re-granted.
+--
+-- MAINTENANCE OBLIGATION: because the grant is now an explicit column list, a future
+-- `alter table agent_board.agents add column ...` is NOT readable by `authenticated` until it is
+-- added here. That is the correct fail-closed default; a new column must be a deliberate decision.
+--
+-- NOT CHANGED: the row policy itself (unchanged — see above), the service_role ALL policy
+-- (`using (true)`), and every SECURITY DEFINER RPC (they run as the table owner, RLS- and
+-- grant-exempt, so list_board_pending_memberships et al. keep returning handles/display names).
+-- `anon` holds no grants on this table and none are added.
+--
+-- BREAKING (fail-loud, intended): `select *` on agent_board.agents as `authenticated` now raises
+-- 42501 rather than returning narrowed rows. No in-repo consumer does this; a non-SDK consumer
+-- (e.g. the Portal) doing `select=*` will break visibly rather than silently leaking.
+--
+-- Additive, forward-only. Grants/RLS only — no function, table or column changes. Writes no
+-- agent_board.schema_version (stays 8). No PostgREST reload required (no signature change), but a
+-- reload is harmless.
+
+revoke select on agent_board.agents from authenticated;
+
+grant select (
+  id,
+  handle,
+  display_name,
+  kind,
+  agent_type,
+  status,
+  created_at,
+  updated_at
+) on agent_board.agents to authenticated;
+
+comment on table agent_board.agents is
+  'Canonical participant directory for humans and automation. READ POSTURE (AGENTSDIR, #80): '
+  '`authenticated` may select ONLY the directory columns (id, handle, display_name, kind, '
+  'agent_type, status, created_at, updated_at). The identity-linkage columns — auth_user_id, '
+  'owner_user_id, parent_agent_id, root_agent_id — and metadata are NOT granted to '
+  '`authenticated`, because raw auth.users UUIDs and the delegation lineage are cross-tenant '
+  'identity linkage and metadata is an acknowledged PII-hazard field. service_role and '
+  'SECURITY DEFINER RPCs are unaffected. A NEWLY ADDED COLUMN IS NOT READABLE by `authenticated` '
+  'until explicitly granted here — fail closed by design.';

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;