@consiliency/agent-board-schema 1.3.0 → 1.4.0

package/fixtures/already-applied.json

@@ -180,6 +180,110 @@
     {
       "id": "20260714000200_agent_board_workload_providers_rls",
       "sha256": "37a6f94d47b0948b1d5f384e52101eb48d9a15ba96a351669c87b907cc8a03e1"
+    },
+    {
+      "id": "20260717000100_agent_board_board_role",
+      "sha256": "969980a7b52c6fee9329d2367006e5ce6d36b6471b53fee2247e493ac8ae512f"
+    },
+    {
+      "id": "20260717000200_agent_board_thread_acl",
+      "sha256": "afb323d6f9189f1f37a7fee3ffceaaa17474059d46a1fdd84adb73c28bfb27ba"
+    },
+    {
+      "id": "20260717000300_agent_board_agent_lineage",
+      "sha256": "48aff20015f74e5f201a2985f71b33cd3e718aeb9dfb25fbd5720cb824fe85b3"
+    },
+    {
+      "id": "20260717000400_agent_board_delegation_policies",
+      "sha256": "ef7827af400e8a6206c17c8cc35623c280a92d25f4b678314847ff308d9d9dc7"
+    },
+    {
+      "id": "20260718000100_agent_board_send_authz_config",
+      "sha256": "d56909d4fbb7054e74818903d3eea84451d561c60908026dbbdb1956f500565d"
+    },
+    {
+      "id": "20260718000200_agent_board_send_role_gate",
+      "sha256": "805afdef2c11e52966bec1cd47a55dfd5e687af9181316d9ef71975b516de288"
+    },
+    {
+      "id": "20260718000300_agent_board_fleet_policy_default_deny",
+      "sha256": "47ad42dd50fb31ede0cb6044a22cce04a31168af2dead73ed8e01dabf84fddea"
+    },
+    {
+      "id": "20260718000400_agent_board_grant_ceiling_wiring",
+      "sha256": "0461f6d403fb1dd07e9423db898cd41a15a3ecfbf75402cd0085791d57a646b7"
+    },
+    {
+      "id": "20260718000500_agent_board_fleet_agent_session_class",
+      "sha256": "028f931aaba673fba29dd92ef3c17efcc08cb50b0dab01789986652a54fb003a"
+    },
+    {
+      "id": "20260718000600_agent_board_mint_fleet_agent_session",
+      "sha256": "25972553fd1ec4f350e751495d79695a8b0ccc66c0b8b272fdf517115ba37307"
+    },
+    {
+      "id": "20260718000700_agent_board_nonfleet_session_reaper",
+      "sha256": "9b6ff596ac386c49530c9405535b5255dcb09c271288957711a0d553446ef161"
+    },
+    {
+      "id": "20260718000800_agent_board_regrant_scoped_send",
+      "sha256": "1332cf2ee23d875cf0b3d646890a0fffe0efc6d2312da4e315d5dc0abadaf74f"
+    },
+    {
+      "id": "20260718000900_agent_board_agents_status_revoked",
+      "sha256": "f0e9b95c286bb4b6873cdc882e30262788636886360c0100b745569d6553a51b"
+    },
+    {
+      "id": "20260718001000_agent_board_delegation_enforcement",
+      "sha256": "7e93bd1ff924b06922bb9312684f57ce81c3d3e921dbf52357ae5059a01dbc8b"
+    },
+    {
+      "id": "20260718001100_agent_board_revoke_agent_subtree",
+      "sha256": "bcf14370a3da288ebe43e337d050f5fb6fb736fad69c9f6b7a0b6e0992371b7e"
+    },
+    {
+      "id": "20260718001200_agent_board_resigning_refresh",
+      "sha256": "47248250ab9bc11abdea8533d62611efba9812b913dc2dc5405612eb2fbafd12"
+    },
+    {
+      "id": "20260718001300_agent_board_identity_providers",
+      "sha256": "ab8169709faf7f74b27a593a7c980022ee073f0371b39c0dda18f2202c0f4eae"
+    },
+    {
+      "id": "20260718001400_agent_board_enrollment_federation_audit",
+      "sha256": "c42e5122625639155d9ff1d2511ebdec3ac379ca0660e67c159e37efb8ea24f5"
+    },
+    {
+      "id": "20260718001500_agent_board_enroll_federated_identity",
+      "sha256": "497d1f657d78c56744017409f5bd2ca361cd691ee1d0bab5b9a55ab3dd4b8ae7"
+    },
+    {
+      "id": "20260719000100_agent_board_signing_challenge_pending_cap",
+      "sha256": "1e48b413d31f11b9c120480c8453c8502fdde1c3a7997dcd9e22e957a2459b0b"
+    },
+    {
+      "id": "20260719000200_agent_board_signing_challenge_reaper",
+      "sha256": "488bbf16bf526b7df7c9b3fa5b068964703aa04ba657d6e6ceaff856a9523634"
+    },
+    {
+      "id": "20260719000300_agent_board_enroll_rate_cap",
+      "sha256": "402c6d8bc5d4662b10d6fe0228a2bdd30026be96a5b5a237e26e1d44a639ae1d"
+    },
+    {
+      "id": "20260719001000_agent_board_identity_providers_portal_contract",
+      "sha256": "e0406afebf9b36f3793e04ca757a252f038b4100697598e0a2e76050193674a0"
+    },
+    {
+      "id": "20260719001100_agent_board_enroll_federated_identity_pop",
+      "sha256": "3d4517243a7d228fb04ea41e9dc7236c870cb5830fb2f815bfa12426eee47bd7"
+    },
+    {
+      "id": "20260719001200_agent_board_enroll_federated_identity_raw_fingerprint",
+      "sha256": "70943047b522ec23ee3d451f704c961d130a053bc210dad8759cbc9a22444454"
+    },
+    {
+      "id": "20260719001300_agent_board_enroll_rate_events_reaper_rls",
+      "sha256": "b2f58eadc13cb227991c4d978c5460878dc3cbada43c58285b55154b89a28459"
     }
   ]
 }

package/migrations/20260717000100_agent_board_board_role.sql

@@ -0,0 +1,180 @@
+-- MBAUTHZ SL-1 (Lane A): board authority role + per-board role-gate flag.
+--
+-- Additive, no send-path behavior change. Adds:
+--   * agent_board.board_memberships.role (backfilled: owner for the board
+--     creator's membership, member otherwise; new rows default member),
+--   * agent_board.boards.role_gate_enforced (per-board flag, default false),
+--   * a role gate inside invite_board_member / resolve_board_request that only
+--     applies when the board's role_gate_enforced flag is true. When false
+--     (default) the existing any-active-member behavior is preserved verbatim,
+--     and a null actor (service_role / current_agent_id() = null) still bypasses.
+
+-- 1. board_memberships.role -------------------------------------------------
+alter table agent_board.board_memberships
+  add column if not exists role text not null default 'member'
+    check (role in ('owner', 'admin', 'member', 'observer'));
+
+comment on column agent_board.board_memberships.role is
+  'Board authority role (partial order owner>admin>member>observer). Backfilled owner for the board creator, member otherwise; new rows default member.';
+
+-- One-time, idempotent backfill: the creator's membership becomes owner.
+update agent_board.board_memberships bm
+   set role = 'owner'
+  from agent_board.boards b
+ where bm.board_id = b.id
+   and bm.agent_id = b.created_by_agent_id
+   and bm.role <> 'owner';
+
+-- 2. boards.role_gate_enforced (board-native flag; deliberately NOT the
+--    portal-owned public.app_settings) ------------------------------------
+alter table agent_board.boards
+  add column if not exists role_gate_enforced boolean not null default false;
+
+comment on column agent_board.boards.role_gate_enforced is
+  'When true, invite_board_member/resolve_board_request require the actor to hold board role owner or admin. Default false preserves the any-active-member behavior.';
+
+-- 3. Role-gated invite_board_member -----------------------------------------
+create or replace function agent_board.invite_board_member(
+  p_board_id uuid,
+  p_agent_id uuid,
+  p_created_by_agent_id uuid,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(membership_id uuid, board_id uuid, agent_id uuid, membership_state text, created_at timestamptz, updated_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_board agent_board.boards%rowtype;
+  v_membership agent_board.board_memberships%rowtype;
+  v_actor uuid := agent_board.current_agent_id();
+begin
+  select * into v_board from agent_board.boards where id = p_board_id and status = 'active';
+  if v_board.id is null then
+    raise exception 'board not found' using errcode = 'P0002';
+  end if;
+  if v_actor is not null and v_actor <> v_board.created_by_agent_id then
+    if v_board.role_gate_enforced then
+      if not exists (
+        select 1
+          from agent_board.board_memberships bm
+         where bm.board_id = p_board_id
+           and bm.agent_id = v_actor
+           and bm.membership_state in ('joined', 'subscribed')
+           and bm.role in ('owner', 'admin')
+      ) then
+        raise exception 'board invite requires owner or admin role' using errcode = '42501';
+      end if;
+    else
+      if not exists (
+        select 1
+          from agent_board.board_memberships bm
+         where bm.board_id = p_board_id
+           and bm.agent_id = v_actor
+           and bm.membership_state in ('joined', 'subscribed')
+      ) then
+        raise exception 'board invite requires active membership' using errcode = '42501';
+      end if;
+    end if;
+  end if;
+  if not exists (select 1 from agent_board.agents where id = p_agent_id) then
+    raise exception 'agent not found' using errcode = 'P0002';
+  end if;
+  if not exists (select 1 from agent_board.agents where id = p_created_by_agent_id) then
+    raise exception 'creator agent not found' using errcode = 'P0002';
+  end if;
+
+  v_membership := agent_board._upsert_board_membership_state(
+    p_board_id,
+    p_agent_id,
+    'invited',
+    p_created_by_agent_id,
+    p_metadata
+  );
+
+  return query
+  select v_membership.id, v_membership.board_id, v_membership.agent_id, v_membership.membership_state, v_membership.created_at, v_membership.updated_at;
+end;
+$$;
+
+-- 4. Role-gated resolve_board_request ---------------------------------------
+create or replace function agent_board.resolve_board_request(
+  p_board_id uuid,
+  p_agent_id uuid,
+  p_membership_state text,
+  p_created_by_agent_id uuid,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(membership_id uuid, board_id uuid, agent_id uuid, membership_state text, left_at timestamptz, updated_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_board agent_board.boards%rowtype;
+  v_existing_state text;
+  v_membership agent_board.board_memberships%rowtype;
+  v_actor uuid := agent_board.current_agent_id();
+begin
+  if p_membership_state not in ('joined', 'subscribed', 'removed') then
+    raise exception 'resolve_board_request only accepts joined, subscribed, or removed' using errcode = '22023';
+  end if;
+  select * into v_board from agent_board.boards where id = p_board_id and status = 'active';
+  if v_board.id is null then
+    raise exception 'board not found' using errcode = 'P0002';
+  end if;
+  if v_actor is not null and v_actor <> v_board.created_by_agent_id then
+    if v_board.role_gate_enforced then
+      if not exists (
+        select 1
+          from agent_board.board_memberships bm
+         where bm.board_id = p_board_id
+           and bm.agent_id = v_actor
+           and bm.membership_state in ('joined', 'subscribed')
+           and bm.role in ('owner', 'admin')
+      ) then
+        raise exception 'board request resolution requires owner or admin role' using errcode = '42501';
+      end if;
+    else
+      if not exists (
+        select 1
+          from agent_board.board_memberships bm
+         where bm.board_id = p_board_id
+           and bm.agent_id = v_actor
+           and bm.membership_state in ('joined', 'subscribed')
+      ) then
+        raise exception 'board request resolution requires active membership' using errcode = '42501';
+      end if;
+    end if;
+  end if;
+
+  select bm.membership_state
+    into v_existing_state
+    from agent_board.board_memberships bm
+   where bm.board_id = p_board_id
+     and bm.agent_id = p_agent_id
+   order by bm.created_at desc
+   limit 1;
+
+  if v_existing_state not in ('requested', 'invited') then
+    raise exception 'pending board membership not found' using errcode = 'P0002';
+  end if;
+
+  v_membership := agent_board._upsert_board_membership_state(
+    p_board_id,
+    p_agent_id,
+    p_membership_state,
+    p_created_by_agent_id,
+    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;
+$$;
+
+-- Re-assert grants (create or replace preserves them, but be explicit so a
+-- fresh replay is order-independent).
+grant execute on function agent_board.invite_board_member(uuid, uuid, uuid, jsonb) to authenticated, service_role;
+grant execute on function agent_board.resolve_board_request(uuid, uuid, text, uuid, jsonb) to authenticated, service_role;

package/migrations/20260717000200_agent_board_thread_acl.sql

@@ -0,0 +1,149 @@
+-- MBAUTHZ SL-2 (Lane B): per-thread ACL.
+--
+-- Additive, no send-path behavior change. Adds:
+--   * agent_board.threads.access_mode ('inherit' default | 'restricted'),
+--   * agent_board.thread_memberships (+ RLS),
+--   * a redefinition of _current_agent_can_access_thread so that
+--     access_mode='inherit' reproduces the current OR verbatim (unchanged
+--     behavior for every existing thread) while access_mode='restricted'
+--     consults thread_memberships (unexpired, unrevoked). The _is_service_role()
+--     short-circuit is retained, so live service_role traffic is unaffected.
+
+-- 1. threads.access_mode ----------------------------------------------------
+alter table agent_board.threads
+  add column if not exists access_mode text not null default 'inherit'
+    check (access_mode in ('inherit', 'restricted'));
+
+comment on column agent_board.threads.access_mode is
+  'inherit (default): thread access is the historical creator/author/task/receipt/claim/inbox/board OR. restricted: access requires an active agent_board.thread_memberships row.';
+
+-- 2. thread_memberships -----------------------------------------------------
+create table if not exists agent_board.thread_memberships (
+  id uuid primary key default gen_random_uuid(),
+  thread_id uuid not null references agent_board.threads(id) on delete cascade,
+  agent_id uuid not null references agent_board.agents(id) on delete cascade,
+  role text not null default 'member' check (role in ('owner', 'admin', 'member')),
+  granted_by_agent_id uuid references agent_board.agents(id) on delete set null,
+  expires_at timestamptz,
+  revoked_at timestamptz,
+  created_at timestamptz not null default now()
+);
+
+comment on table agent_board.thread_memberships is
+  'Per-thread access-control list consulted when threads.access_mode = restricted. A membership is active when revoked_at is null and (expires_at is null or expires_at > now()).';
+
+-- One active membership per (thread, agent).
+create unique index if not exists idx_agent_board_thread_memberships_active_unique
+  on agent_board.thread_memberships(thread_id, agent_id)
+  where revoked_at is null;
+
+create index if not exists idx_agent_board_thread_memberships_agent
+  on agent_board.thread_memberships(agent_id, thread_id);
+
+alter table agent_board.thread_memberships enable row level security;
+
+drop policy if exists agent_board_authenticated_select_thread_memberships on agent_board.thread_memberships;
+create policy agent_board_authenticated_select_thread_memberships
+on agent_board.thread_memberships
+as permissive
+for select
+to authenticated
+using (
+  agent_id = agent_board.current_agent_id()
+  or granted_by_agent_id = agent_board.current_agent_id()
+  or agent_board._current_agent_can_access_thread(thread_id)
+);
+
+grant select on agent_board.thread_memberships to authenticated;
+grant select, insert, update on agent_board.thread_memberships to service_role;
+
+-- 3. Redefine _current_agent_can_access_thread ------------------------------
+-- inherit mode reproduces the historical OR verbatim; restricted mode consults
+-- the ACL. _is_service_role() short-circuit preserved.
+create or replace function agent_board._current_agent_can_access_thread(
+  p_thread_id uuid
+)
+returns boolean
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  select
+    agent_board._is_service_role()
+    or exists (
+      select 1
+        from agent_board.threads t
+       where t.id = p_thread_id
+         and (
+           (
+             t.access_mode = 'inherit'
+             and (
+               t.created_by_agent_id = agent_board.current_agent_id()
+               or exists (
+                 select 1
+                   from agent_board.messages m
+                  where m.thread_id = t.id
+                    and m.author_agent_id = agent_board.current_agent_id()
+               )
+               or exists (
+                 select 1
+                   from agent_board.tasks task
+                  where task.thread_id = t.id
+                    and (
+                      task.created_by_agent_id = agent_board.current_agent_id()
+                      or task.assigned_agent_id = agent_board.current_agent_id()
+                    )
+               )
+               or exists (
+                 select 1
+                   from agent_board.read_receipts rr
+                  where rr.thread_id = t.id
+                    and rr.agent_id = agent_board.current_agent_id()
+               )
+               or exists (
+                 select 1
+                   from agent_board.claims c
+                  where c.thread_id = t.id
+                    and c.agent_id = agent_board.current_agent_id()
+               )
+               or exists (
+                 select 1
+                   from agent_board.inbox_items ii
+                   left join agent_board.messages im on im.id = ii.source_message_id
+                   left join agent_board.tasks it on it.id = ii.source_task_id
+                   left join agent_board.delegations ide on ide.id = ii.source_delegation_id
+                   left join agent_board.tasks idt on idt.id = ide.child_task_id
+                  where ii.recipient_agent_id = agent_board.current_agent_id()
+                    and (
+                      im.thread_id = t.id
+                      or it.thread_id = t.id
+                      or idt.thread_id = t.id
+                    )
+               )
+               or exists (
+                 select 1
+                   from agent_board.delivery_recipients dr
+                   join agent_board.messages bm on bm.id = dr.source_message_id
+                  where dr.board_id is not null
+                    and bm.thread_id = t.id
+                    and agent_board._current_agent_has_board_access(dr.board_id)
+               )
+             )
+           )
+           or (
+             t.access_mode = 'restricted'
+             and exists (
+               select 1
+                 from agent_board.thread_memberships tm
+                where tm.thread_id = t.id
+                  and tm.agent_id = agent_board.current_agent_id()
+                  and tm.revoked_at is null
+                  and (tm.expires_at is null or tm.expires_at > now())
+             )
+           )
+         )
+    )
+$$;
+
+revoke all on function agent_board._current_agent_can_access_thread(uuid) from public, anon, authenticated;

package/migrations/20260717000300_agent_board_agent_lineage.sql

@@ -0,0 +1,54 @@
+-- MBAUTHZ SL-3 (Lane C): agent lineage.
+--
+-- Additive, no send-path behavior change. Adds self-referential
+-- agents.parent_agent_id / agents.root_agent_id (nullable) plus an
+-- owner-consistency guard: a parented agent (root_agent_id set) must share the
+-- owner_user_id of its lineage root. Unparented rows (NULL lineage) are
+-- unaffected.
+
+alter table agent_board.agents
+  add column if not exists parent_agent_id uuid references agent_board.agents(id) on delete set null,
+  add column if not exists root_agent_id uuid references agent_board.agents(id) on delete set null;
+
+comment on column agent_board.agents.parent_agent_id is
+  'Direct delegating parent agent (self-referential, nullable). NULL for top-level agents.';
+comment on column agent_board.agents.root_agent_id is
+  'Lineage root agent (self-referential, nullable). When set, this agent must share the root agent''s owner_user_id.';
+
+create index if not exists idx_agent_board_agents_parent on agent_board.agents(parent_agent_id) where parent_agent_id is not null;
+create index if not exists idx_agent_board_agents_root on agent_board.agents(root_agent_id) where root_agent_id is not null;
+
+-- Owner-consistency guard.
+create or replace function agent_board._enforce_agent_lineage_owner()
+returns trigger
+language plpgsql
+security definer
+set search_path = ''
+as $$
+declare
+  v_root_owner uuid;
+begin
+  if new.root_agent_id is null then
+    return new;
+  end if;
+
+  select a.owner_user_id
+    into v_root_owner
+    from agent_board.agents a
+   where a.id = new.root_agent_id;
+
+  if new.owner_user_id is distinct from v_root_owner then
+    raise exception 'agent lineage owner mismatch: agent owner_user_id must equal its root agent owner_user_id'
+      using errcode = '23514';
+  end if;
+
+  return new;
+end;
+$$;
+
+drop trigger if exists trg_agent_board_agents_lineage_owner on agent_board.agents;
+create trigger trg_agent_board_agents_lineage_owner
+  before insert or update of parent_agent_id, root_agent_id, owner_user_id
+  on agent_board.agents
+  for each row
+  execute function agent_board._enforce_agent_lineage_owner();

package/migrations/20260717000400_agent_board_delegation_policies.sql

@@ -0,0 +1,175 @@
+-- MBAUTHZ SL-4 (Lane D): delegation policies, board authority ceilings, and the
+-- _grant_within_ceiling helper.
+--
+-- Additive, no send-path behavior change. MBAUTHZ OWNS this schema + helper;
+-- MBSENDAUTHZ (later phase) only consumes it. The board ceiling is a SEPARATE
+-- table keyed on board_id (maintainer decision), NOT a boards column; a board
+-- with no ceiling row defaults to 'owner' (unchanged behavior).
+
+-- 1. delegation_policies -----------------------------------------------------
+create table if not exists agent_board.delegation_policies (
+  id uuid primary key default gen_random_uuid(),
+  root_agent_id uuid not null references agent_board.agents(id) on delete cascade,
+  mode text not null default 'independent_auth' check (mode in ('independent_auth', 'root_minted')),
+  max_depth int not null default 1,
+  max_active_children int,
+  allowed_scopes jsonb,
+  -- The grant/working clock (hours-scale), NOT the <=15-min session-token clock.
+  child_ttl_ceiling interval not null default interval '8 hours',
+  require_child_signing_key boolean not null default true,
+  revoked_at timestamptz,
+  created_at timestamptz not null default now()
+);
+
+comment on table agent_board.delegation_policies is
+  'Per-root-agent delegation policy. child_ttl_ceiling is the hours-scale grant/working clock, not the session-token clock.';
+
+create index if not exists idx_agent_board_delegation_policies_root
+  on agent_board.delegation_policies(root_agent_id)
+  where revoked_at is null;
+
+alter table agent_board.delegation_policies enable row level security;
+
+drop policy if exists agent_board_authenticated_select_delegation_policies on agent_board.delegation_policies;
+create policy agent_board_authenticated_select_delegation_policies
+on agent_board.delegation_policies
+as permissive
+for select
+to authenticated
+using (root_agent_id = agent_board.current_agent_id());
+
+grant select on agent_board.delegation_policies to authenticated;
+grant select, insert, update on agent_board.delegation_policies to service_role;
+
+-- 2. board_authority_ceilings (separate table; not a boards column) ---------
+create table if not exists agent_board.board_authority_ceilings (
+  board_id uuid primary key references agent_board.boards(id) on delete cascade,
+  max_grantable_role text not null default 'owner' check (max_grantable_role in ('owner', 'admin', 'member', 'observer')),
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now()
+);
+
+comment on table agent_board.board_authority_ceilings is
+  'Optional per-board cap on the highest role a grantor may grant. No row means no explicit ceiling, resolved as owner (unchanged behavior).';
+
+alter table agent_board.board_authority_ceilings enable row level security;
+
+drop policy if exists agent_board_authenticated_select_board_authority_ceilings on agent_board.board_authority_ceilings;
+create policy agent_board_authenticated_select_board_authority_ceilings
+on agent_board.board_authority_ceilings
+as permissive
+for select
+to authenticated
+using (agent_board._current_agent_has_board_access(board_id));
+
+grant select on agent_board.board_authority_ceilings to authenticated;
+grant select, insert, update on agent_board.board_authority_ceilings to service_role;
+
+-- 3. _grant_within_ceiling ---------------------------------------------------
+-- Role partial order owner>admin>member>observer. A grant is permitted iff the
+-- grantee role does not outrank the grantor's own board role AND does not
+-- outrank the board's ceiling (default owner when no ceiling row exists).
+create or replace function agent_board._grant_within_ceiling(
+  p_grantor_agent_id uuid,
+  p_board_id uuid,
+  p_grantee_role text
+)
+returns boolean
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  with ranks(role, rank) as (
+    values ('owner', 4), ('admin', 3), ('member', 2), ('observer', 1)
+  ),
+  grantor as (
+    select r.rank
+      from agent_board.board_memberships bm
+      join ranks r on r.role = bm.role
+     where bm.board_id = p_board_id
+       and bm.agent_id = p_grantor_agent_id
+       and bm.membership_state in ('joined', 'subscribed')
+     order by r.rank desc
+     limit 1
+  ),
+  ceiling as (
+    select coalesce(
+      (select r.rank
+         from agent_board.board_authority_ceilings c
+         join ranks r on r.role = c.max_grantable_role
+        where c.board_id = p_board_id),
+      4  -- no row -> owner
+    ) as rank
+  ),
+  grantee as (
+    select rank from ranks where role = p_grantee_role
+  )
+  select
+    (select rank from grantee) is not null
+    and exists (select 1 from grantor)
+    and (select rank from grantee) <= (select rank from grantor)
+    and (select rank from grantee) <= (select rank from ceiling)
+$$;
+
+comment on function agent_board._grant_within_ceiling(uuid, uuid, text) is
+  'True iff p_grantee_role does not outrank the grantor''s active board role nor the board ceiling (default owner). MBAUTHZ owns this; MBSENDAUTHZ consumes it.';
+
+revoke all on function agent_board._grant_within_ceiling(uuid, uuid, text) from public, anon;
+grant execute on function agent_board._grant_within_ceiling(uuid, uuid, text) to authenticated, service_role;
+
+-- 4. set_board_authority_ceiling (owner-settable cap) ------------------------
+-- #13: the board owner (the human root's delegated authority) can set the per-board
+-- ceiling. Permitted ONLY when the caller (current_agent_id()) holds an owner
+-- board_memberships row for that board; every other caller raises 42501. The
+-- grantee-bounded _grant_within_ceiling semantics above are unchanged — this only
+-- lets the owner set the stored ceiling row that _grant_within_ceiling reads.
+-- service_role (current_agent_id() = null) is intentionally NOT an owner here; it
+-- retains its direct table-write grant for operator provisioning.
+create or replace function agent_board.set_board_authority_ceiling(
+  p_board_id uuid,
+  p_max_grantable_role text
+)
+returns table(
+  ceiling_board_id uuid,
+  ceiling_max_grantable_role text
+)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_actor uuid := agent_board.current_agent_id();
+begin
+  if p_max_grantable_role not in ('owner', 'admin', 'member', 'observer') then
+    raise exception 'max_grantable_role must be one of owner/admin/member/observer' using errcode = '22023';
+  end if;
+
+  if v_actor is null
+     or not exists (
+       select 1
+         from agent_board.board_memberships bm
+        where bm.board_id = p_board_id
+          and bm.agent_id = v_actor
+          and bm.role = 'owner'
+          and bm.membership_state in ('joined', 'subscribed')
+     ) then
+    raise exception 'only a board owner may set the board authority ceiling' using errcode = '42501';
+  end if;
+
+  insert into agent_board.board_authority_ceilings(board_id, max_grantable_role)
+  values (p_board_id, p_max_grantable_role)
+  on conflict (board_id) do update
+    set max_grantable_role = excluded.max_grantable_role,
+        updated_at = now();
+
+  return query
+  select p_board_id, p_max_grantable_role;
+end;
+$$;
+
+comment on function agent_board.set_board_authority_ceiling(uuid, text) is
+  'Owner-gated setter for a board''s authority ceiling: upserts board_authority_ceilings only when current_agent_id() is an owner of the board (else raises 42501). Leaves _grant_within_ceiling semantics unchanged.';
+
+revoke all on function agent_board.set_board_authority_ceiling(uuid, text) from public, anon;
+grant execute on function agent_board.set_board_authority_ceiling(uuid, text) to authenticated, service_role;