@consiliency/agent-board-schema 1.68.0 → 1.74.0

package/migrations/20261104065658_agent_board_reply_delivery.sql

@@ -0,0 +1,659 @@
+-- #661: separate authorized insertion from public reply delivery.
+-- Current-tree definitions replayed in an owned disposable database; no live catalog source.
+CREATE OR REPLACE FUNCTION agent_board._insert_thread_message(p_thread_id uuid, p_author_agent_id uuid, p_body text, p_message_type text DEFAULT 'comment'::text, p_task_id uuid DEFAULT NULL::uuid, p_metadata jsonb DEFAULT '{}'::jsonb)
+ RETURNS TABLE(message_id uuid, thread_id uuid, task_id uuid, message_sequence bigint, created_at timestamp with time zone)
+ LANGUAGE plpgsql
+ SECURITY DEFINER
+ SET search_path TO 'agent_board', 'public'
+AS $function$
+declare
+  v_sequence bigint;
+  v_actor_agent_id uuid;
+  v_metadata jsonb;
+  v_instance agent_board.delegate_instances%rowtype;
+begin
+  v_actor_agent_id := agent_board._resolved_actor_agent_id(p_author_agent_id, 'p_author_agent_id');
+
+  if nullif(trim(p_body), '') is null then
+    raise exception 'message body is required' using errcode = '22023';
+  end if;
+  if not exists (select 1 from agent_board.threads where id = p_thread_id) then
+    raise exception 'thread not found' using errcode = 'P0002';
+  end if;
+  if not agent_board._current_agent_can_access_thread(p_thread_id) then
+    raise exception 'thread not accessible to current agent' using errcode = '42501';
+  end if;
+  -- OBSGATE (#78): a board-linked thread under 'inherit' requires a non-observer board role.
+  -- All message entrypoints use this authorized insertion primitive; the gate cannot be bypassed
+  -- by any send path. Board-less threads and service_role fall through (access check above).
+  if not agent_board._current_agent_can_post_to_thread(p_thread_id) then
+    raise exception 'thread posting requires a non-observer board role' using errcode = '42501';
+  end if;
+  if p_task_id is not null and not exists (select 1 from agent_board.tasks where id = p_task_id and tasks.thread_id = p_thread_id) then
+    raise exception 'task not found in thread' using errcode = '22023';
+  end if;
+
+  -- HOSTED attribution: the `delegate` key is written by the server, never by a caller. A
+  -- hosted delegate's post carries it (overwriting anything supplied); every other author's
+  -- caller-supplied `delegate` key is removed, so no keyed agent can forge the mark.
+  -- client_verified is always false: under dynamic client registration anyone can name a client.
+  v_metadata := coalesce(p_metadata, '{}'::jsonb);
+  if jsonb_typeof(v_metadata) = 'object' then
+    v_metadata := v_metadata - 'delegate';
+  end if;
+  select di.* into v_instance
+    from agent_board.agents a
+    join agent_board.delegate_instances di on di.agent_id = a.id
+   where a.id = v_actor_agent_id
+     and a.is_delegate;
+  if found then
+    if jsonb_typeof(v_metadata) <> 'object' then
+      raise exception 'a hosted delegate''s message metadata must be a JSON object' using errcode = '22023';
+    end if;
+    v_metadata := v_metadata || jsonb_build_object('delegate', jsonb_build_object(
+      'delegate', true,
+      'instance_id', v_instance.instance_id,
+      'owner_agent_id', agent_board._delegate_principal_agent_id(v_actor_agent_id),
+      'client_id', v_instance.client_id,
+      'client_verified', false));
+  end if;
+
+  v_sequence := agent_board._next_thread_message_sequence(p_thread_id);
+  -- The sequence update may have waited for an association; re-read after that wait.
+  if not agent_board._current_agent_can_access_thread(p_thread_id) then
+    raise exception 'thread not accessible to current agent' using errcode = '42501';
+  end if;
+  if not agent_board._current_agent_can_post_to_thread(p_thread_id) then
+    raise exception 'thread posting requires a non-observer board role' using errcode = '42501';
+  end if;
+
+  return query
+  insert into agent_board.messages(thread_id, author_agent_id, task_id, message_sequence, message_type, body, metadata)
+  values (p_thread_id, v_actor_agent_id, p_task_id, v_sequence, coalesce(p_message_type, 'comment'), p_body, v_metadata)
+  returning id, messages.thread_id, messages.task_id, messages.message_sequence, messages.created_at;
+end;
+$function$;
+revoke all on function agent_board._insert_thread_message(uuid,uuid,text,text,uuid,jsonb) from public,anon,authenticated,service_role,agent_board_delegate;
+comment on function agent_board._insert_thread_message(uuid,uuid,text,text,uuid,jsonb) is 'Internal authorized message insertion; preserves sequence locking, session author and hosted attribution. Delivery is the caller responsibility.';
+
+create or replace function agent_board._deliver_board_message(p_message_id uuid, p_subject text, p_body text, p_priority text)
+returns table(delivered_recipient_count integer, callback_outbox_count integer)
+language plpgsql security definer set search_path=agent_board,public as $function$
+declare
+  v_message agent_board.messages%rowtype;
+  v_membership record;
+  v_recipient agent_board.delivery_recipients%rowtype;
+  v_inbox agent_board.inbox_items%rowtype;
+  v_delivered_count integer := 0;
+  v_callback_count integer := 0;
+  v_preview text;
+  v_fetch_descriptor jsonb;
+  v_actor_agent_id uuid;
+  v_is_author boolean;
+  p_board_id uuid;
+  p_thread_id uuid;
+begin
+  select * into strict v_message from agent_board.messages where id=p_message_id;
+  p_thread_id := v_message.thread_id;
+  v_actor_agent_id := v_message.author_agent_id;
+  select board_id into p_board_id from agent_board.threads where id=p_thread_id;
+  if p_board_id is null then
+    raise exception 'board delivery requires a board thread' using errcode='22023';
+  end if;
+  -- Keep the canonical early board/thread boundary before any recipient sink,
+  -- including boards whose current membership set is empty.
+  perform agent_board._associate_empty_thread(p_thread_id, p_board_id);
+  v_preview := agent_board._trim_inbox_text(p_body, 280);
+  v_fetch_descriptor := agent_board._build_fetch_descriptor(
+    'board',
+    p_board_id,
+    'agent_board.v_board_feed',
+    'board delivery',
+    jsonb_build_object('messageId', v_message.id::text)
+  );
+
+  for v_membership in
+    select bm.id, bm.agent_id
+      from agent_board.board_memberships bm
+     where bm.board_id = p_board_id
+       and bm.membership_state in ('joined', 'subscribed')
+     order by bm.created_at
+  loop
+    -- #608: the author is not a recipient of its own post. Its row stays, FEED-ONLY
+    -- (visible_in_inbox = false), because v_board_feed is built from these rows and a post on a
+    -- board whose only member is its author would otherwise vanish from the feed. A feed-only
+    -- row is outside v_agent_inbox, v_agent_wake_recovery and v_agent_inbox_counts by their own
+    -- `visible_in_inbox` filter, and _queue_inbox_callbacks queues nothing for it.
+    v_is_author := v_membership.agent_id is not distinct from v_actor_agent_id;
+    v_recipient := agent_board._upsert_delivery_recipient(
+      'board',
+      v_membership.agent_id,
+      'message',
+      v_message.id,
+      null,
+      null,
+      p_board_id,
+      v_membership.id,
+      jsonb_build_object('priority', p_priority)
+    );
+
+    v_inbox := agent_board._upsert_inbox_item(
+      v_recipient.id,
+      v_membership.agent_id,
+      p_board_id,
+      v_recipient.delivery_mode,
+      'message',
+      v_message.id,
+      null,
+      null,
+      trim(p_subject),
+      v_preview,
+      p_priority,
+      not v_is_author,
+      true,
+      v_fetch_descriptor,
+      jsonb_build_object('threadId', p_thread_id::text, 'boardId', p_board_id::text)
+    );
+
+    -- delivered_recipient_count counts RECIPIENTS; the author's feed-only row is not one.
+    if not v_is_author then
+      v_delivered_count := v_delivered_count + 1;
+    end if;
+    v_callback_count := v_callback_count + agent_board._queue_inbox_callbacks(v_inbox.id, 'inbox.item.delivered');
+  end loop;
+
+  v_callback_count := v_callback_count + agent_board._queue_board_post_callbacks(
+    p_board_id,
+    v_message.id,
+    trim(p_subject),
+    v_preview,
+    p_priority,
+    v_fetch_descriptor
+  );
+
+  return query select v_delivered_count,v_callback_count;
+end;
+$function$;
+revoke all on function agent_board._deliver_board_message(uuid,text,text,text) from public,anon,authenticated,service_role,agent_board_delegate;
+comment on function agent_board._deliver_board_message(uuid,text,text,text) is 'Internal canonical board fan-out for an authorized persisted message; board and author derive from the source, with feed-only self delivery and existing callbacks.';
+
+CREATE OR REPLACE FUNCTION agent_board.post_board_message(p_thread_id uuid, p_author_agent_id uuid, p_board_id uuid, p_subject text, p_body text, p_message_type text DEFAULT 'comment'::text, p_priority text DEFAULT 'medium'::text, p_idempotency_key text DEFAULT NULL::text, p_metadata jsonb DEFAULT '{}'::jsonb)
+ RETURNS TABLE(message_id uuid, board_id uuid, delivered_recipient_count integer, callback_outbox_count integer, created_at timestamp with time zone)
+ LANGUAGE plpgsql
+ SECURITY DEFINER
+ SET search_path TO 'agent_board', 'public'
+AS $function$
+declare
+  v_message agent_board.messages%rowtype;
+  v_created_message record;
+  v_membership record;
+  v_recipient agent_board.delivery_recipients%rowtype;
+  v_inbox agent_board.inbox_items%rowtype;
+  v_delivered_count integer := 0;
+  v_callback_count integer := 0;
+  v_metadata jsonb;
+  v_preview text;
+  v_fetch_descriptor jsonb;
+  v_idempotency_key text := nullif(trim(p_idempotency_key), '');
+  v_actor_agent_id uuid;
+  v_is_author boolean;
+begin
+  v_actor_agent_id := agent_board._resolved_actor_agent_id(p_author_agent_id, 'p_author_agent_id');
+
+  if nullif(trim(p_subject), '') is null or nullif(trim(p_body), '') is null then
+    raise exception 'subject and body are required' using errcode = '22023';
+  end if;
+  if p_priority not in ('low', 'medium', 'high', 'urgent') then
+    raise exception 'invalid priority' using errcode = '22023';
+  end if;
+  if not exists (select 1 from agent_board.threads where id = p_thread_id) then
+    raise exception 'thread not found' using errcode = 'P0002';
+  end if;
+  if not exists (select 1 from agent_board.boards where id = p_board_id) then
+    raise exception 'board not found' using errcode = 'P0002';
+  end if;
+  if not agent_board._current_agent_can_access_thread(p_thread_id) then
+    raise exception 'thread not accessible to current agent' using errcode = '42501';
+  end if;
+  if not agent_board._current_agent_has_board_access(p_board_id) then
+    raise exception 'board not accessible to current agent' using errcode = '42501';
+  end if;
+  if not agent_board._current_agent_can_send_to_board(p_board_id) then
+    raise exception 'board send requires a non-observer board role' using errcode = '42501';
+  end if;
+
+  if agent_board._is_service_role() then
+    perform agent_board._record_send_authz_telemetry(
+      'service_role_bypass',
+      coalesce(nullif(p_metadata -> 'signed_write' ->> 'origin', ''), 'unknown'),
+      v_actor_agent_id,
+      p_board_id,
+      'post_board_message',
+      agent_board._resolve_send_fleet_scope(v_actor_agent_id),
+      null,
+      jsonb_build_object('redacted', true)
+    );
+  end if;
+
+  perform agent_board._lock_idempotency_key(
+    'post_board_message:' || p_thread_id::text || ':' || v_actor_agent_id::text || ':' || p_board_id::text,
+    v_idempotency_key
+  );
+
+  if p_board_id is not null then
+    perform agent_board._associate_empty_thread(p_thread_id, p_board_id);
+    -- Both checks are new statements after the thread-lock wait.
+    if not agent_board._current_agent_can_access_thread(p_thread_id) then
+      raise exception 'thread not accessible to current agent' using errcode = '42501';
+    end if;
+    if not agent_board._current_agent_has_board_access(p_board_id) then
+      raise exception 'board not accessible to current agent' using errcode = '42501';
+    end if;
+    if not agent_board._current_agent_can_send_to_board(p_board_id) then
+      raise exception 'board send requires a non-observer board role' using errcode = '42501';
+    end if;
+  end if;
+
+  if v_idempotency_key is not null then
+    select *
+      into v_message
+      from agent_board.messages
+     where thread_id = p_thread_id
+       and author_agent_id = v_actor_agent_id
+       and metadata ->> 'rpcName' = 'post_board_message'
+       and metadata ->> 'idempotencyKey' = v_idempotency_key
+     order by created_at desc, id desc
+     limit 1;
+  end if;
+
+  if v_message.id is null then
+    v_metadata := coalesce(p_metadata, '{}'::jsonb)
+      || jsonb_build_object(
+        'rpcName', 'post_board_message',
+        'subject', trim(p_subject),
+        'priority', p_priority,
+        'boardId', p_board_id::text
+      );
+    if v_idempotency_key is not null then
+      v_metadata := v_metadata || jsonb_build_object('idempotencyKey', v_idempotency_key);
+    end if;
+
+    select *
+      into v_created_message
+      from agent_board._insert_thread_message(
+        p_thread_id,
+        v_actor_agent_id,
+        p_body,
+        p_message_type,
+        null,
+        v_metadata
+      );
+
+    select *
+      into v_message
+      from agent_board.messages
+     where id = v_created_message.message_id;
+  end if;
+
+  select d.delivered_recipient_count, d.callback_outbox_count
+    into v_delivered_count, v_callback_count
+    from agent_board._deliver_board_message(v_message.id, trim(p_subject), p_body, p_priority) d;
+
+  return query
+  select v_message.id, p_board_id, v_delivered_count, v_callback_count, v_message.created_at;
+end;
+$function$;
+
+CREATE OR REPLACE FUNCTION agent_board.post_message(p_thread_id uuid, p_author_agent_id uuid, p_body text, p_message_type text DEFAULT 'comment'::text, p_task_id uuid DEFAULT NULL::uuid, p_metadata jsonb DEFAULT '{}'::jsonb)
+ RETURNS TABLE(message_id uuid, thread_id uuid, task_id uuid, message_sequence bigint, created_at timestamp with time zone)
+ LANGUAGE plpgsql
+ SECURITY DEFINER
+ SET search_path TO 'agent_board', 'public'
+AS $function$
+declare
+  v_message record;
+  v_board_id uuid;
+  v_subject text;
+  v_access_mode text;
+begin
+  select * into v_message from agent_board._insert_thread_message(
+    p_thread_id,p_author_agent_id,p_body,p_message_type,p_task_id,p_metadata);
+  -- Insertion holds the sequence/thread lock. Read the association after that
+  -- lock, so an initially unstamped thread cannot race past board delivery.
+  select t.board_id,coalesce(nullif(trim(t.subject),''),'Thread reply'),t.access_mode
+    into v_board_id,v_subject,v_access_mode from agent_board.threads t where t.id=p_thread_id;
+  -- Restricted threads keep their explicit audience; board association alone
+  -- does not authorize broadcasting an ordinary reply to all board members.
+  if v_board_id is not null and v_access_mode = 'inherit' then
+    if not agent_board._current_agent_has_board_access(v_board_id) then
+      raise exception 'board not accessible to current agent' using errcode='42501';
+    end if;
+    if not agent_board._current_agent_can_send_to_board(v_board_id) then
+      raise exception 'board send requires a non-observer board role' using errcode='42501';
+    end if;
+    perform * from agent_board._deliver_board_message(v_message.message_id,v_subject,p_body,'medium');
+  end if;
+  return query select v_message.message_id,v_message.thread_id,v_message.task_id,
+    v_message.message_sequence,v_message.created_at;
+end;
+$function$;
+
+CREATE OR REPLACE FUNCTION agent_board.send_direct_message(p_thread_id uuid, p_author_agent_id uuid, p_recipient_agent_id uuid, p_subject text, p_body text, p_message_type text DEFAULT 'comment'::text, p_priority text DEFAULT 'medium'::text, p_idempotency_key text DEFAULT NULL::text, p_metadata jsonb DEFAULT '{}'::jsonb)
+ RETURNS TABLE(message_id uuid, delivery_recipient_id uuid, inbox_item_id uuid, callback_outbox_count integer, created_at timestamp with time zone)
+ LANGUAGE plpgsql
+ SECURITY DEFINER
+ SET search_path TO 'agent_board', 'public'
+AS $function$
+declare
+  v_message agent_board.messages%rowtype;
+  v_created_message record;
+  v_recipient agent_board.delivery_recipients%rowtype;
+  v_inbox agent_board.inbox_items%rowtype;
+  v_callback_count integer := 0;
+  v_metadata jsonb;
+  v_preview text;
+  v_fetch_descriptor jsonb;
+  v_idempotency_key text := nullif(trim(p_idempotency_key), '');
+  v_actor_agent_id uuid;
+begin
+  v_actor_agent_id := agent_board._resolved_actor_agent_id(p_author_agent_id, 'p_author_agent_id');
+
+  if nullif(trim(p_subject), '') is null or nullif(trim(p_body), '') is null then
+    raise exception 'subject and body are required' using errcode = '22023';
+  end if;
+  if p_priority not in ('low', 'medium', 'high', 'urgent') then
+    raise exception 'invalid priority' using errcode = '22023';
+  end if;
+  if not exists (select 1 from agent_board.threads where id = p_thread_id) then
+    raise exception 'thread not found' using errcode = 'P0002';
+  end if;
+  if not agent_board._current_agent_can_access_thread(p_thread_id) then
+    raise exception 'thread not accessible to current agent' using errcode = '42501';
+  end if;
+  if not exists (select 1 from agent_board.agents where id = p_recipient_agent_id) then
+    raise exception 'recipient agent not found' using errcode = 'P0002';
+  end if;
+
+  if agent_board._is_service_role() then
+    perform agent_board._record_send_authz_telemetry(
+      'service_role_bypass',
+      coalesce(nullif(p_metadata -> 'signed_write' ->> 'origin', ''), 'unknown'),
+      v_actor_agent_id,
+      null,
+      'send_direct_message',
+      agent_board._resolve_send_fleet_scope(v_actor_agent_id),
+      null,
+      jsonb_build_object('redacted', true)
+    );
+  end if;
+
+  perform agent_board._lock_idempotency_key(
+    'send_direct_message:' || p_thread_id::text || ':' || v_actor_agent_id::text,
+    v_idempotency_key
+  );
+
+  if v_idempotency_key is not null then
+    select *
+      into v_message
+      from agent_board.messages
+     where thread_id = p_thread_id
+       and author_agent_id = v_actor_agent_id
+       and metadata ->> 'rpcName' = 'send_direct_message'
+       and metadata ->> 'idempotencyKey' = v_idempotency_key
+     order by created_at desc
+     limit 1;
+  end if;
+
+  if v_message.id is null then
+    v_metadata := coalesce(p_metadata, '{}'::jsonb)
+      || jsonb_build_object(
+        'rpcName', 'send_direct_message',
+        'subject', trim(p_subject),
+        'priority', p_priority
+      );
+    if v_idempotency_key is not null then
+      v_metadata := v_metadata || jsonb_build_object('idempotencyKey', v_idempotency_key);
+    end if;
+
+    select *
+      into v_created_message
+      from agent_board._insert_thread_message(
+        p_thread_id,
+        v_actor_agent_id,
+        p_body,
+        p_message_type,
+        null,
+        v_metadata
+      );
+
+    select *
+      into v_message
+      from agent_board.messages
+     where id = v_created_message.message_id;
+  end if;
+
+  v_preview := agent_board._trim_inbox_text(p_body, 280);
+  v_fetch_descriptor := agent_board._build_fetch_descriptor(
+    'thread',
+    p_thread_id,
+    'agent_board.v_thread_feed',
+    'direct delivery',
+    jsonb_build_object('messageId', v_message.id::text, 'recipientAgentId', p_recipient_agent_id::text)
+  );
+
+  v_recipient := agent_board._upsert_delivery_recipient(
+    'direct',
+    p_recipient_agent_id,
+    'message',
+    v_message.id,
+    null,
+    null,
+    null,
+    null,
+    jsonb_build_object('priority', p_priority)
+  );
+
+  v_inbox := agent_board._upsert_inbox_item(
+    v_recipient.id,
+    p_recipient_agent_id,
+    null,
+    v_recipient.delivery_mode,
+    'message',
+    v_message.id,
+    null,
+    null,
+    trim(p_subject),
+    v_preview,
+    p_priority,
+    true,
+    false,
+    v_fetch_descriptor,
+    jsonb_build_object('threadId', p_thread_id::text)
+  );
+
+  v_callback_count := agent_board._queue_inbox_callbacks(v_inbox.id, 'inbox.item.delivered');
+
+  return query
+  select v_message.id, v_recipient.id, v_inbox.id, v_callback_count, v_message.created_at;
+end;
+$function$;
+
+CREATE OR REPLACE FUNCTION agent_board.send_multicast_message(p_thread_id uuid, p_author_agent_id uuid, p_recipient_agent_ids uuid[], p_subject text, p_body text, p_message_type text DEFAULT 'comment'::text, p_priority text DEFAULT 'medium'::text, p_idempotency_key text DEFAULT NULL::text, p_metadata jsonb DEFAULT '{}'::jsonb)
+ RETURNS TABLE(message_id uuid, delivered_recipient_count integer, inbox_item_count integer, callback_outbox_count integer, created_at timestamp with time zone)
+ LANGUAGE plpgsql
+ SECURITY DEFINER
+ SET search_path TO 'agent_board', 'public'
+AS $function$
+declare
+  v_message agent_board.messages%rowtype;
+  v_created_message record;
+  v_recipient_ids uuid[];
+  v_recipient_id uuid;
+  v_recipient agent_board.delivery_recipients%rowtype;
+  v_inbox agent_board.inbox_items%rowtype;
+  v_delivered_count integer := 0;
+  v_inbox_count integer := 0;
+  v_callback_count integer := 0;
+  v_metadata jsonb;
+  v_preview text;
+  v_fetch_descriptor jsonb;
+  v_idempotency_key text := nullif(trim(p_idempotency_key), '');
+  v_actor_agent_id uuid;
+begin
+  v_actor_agent_id := agent_board._resolved_actor_agent_id(p_author_agent_id, 'p_author_agent_id');
+
+  if nullif(trim(p_subject), '') is null or nullif(trim(p_body), '') is null then
+    raise exception 'subject and body are required' using errcode = '22023';
+  end if;
+  if p_priority not in ('low', 'medium', 'high', 'urgent') then
+    raise exception 'invalid priority' using errcode = '22023';
+  end if;
+  if p_recipient_agent_ids is null or cardinality(p_recipient_agent_ids) = 0 then
+    raise exception 'recipient_agent_ids must not be empty' using errcode = '22023';
+  end if;
+  if array_position(p_recipient_agent_ids, null) is not null then
+    raise exception 'recipient_agent_ids must not contain nulls' using errcode = '22023';
+  end if;
+  if not exists (select 1 from agent_board.threads where id = p_thread_id) then
+    raise exception 'thread not found' using errcode = 'P0002';
+  end if;
+  if not agent_board._current_agent_can_access_thread(p_thread_id) then
+    raise exception 'thread not accessible to current agent' using errcode = '42501';
+  end if;
+
+  select array_agg(distinct recipient_id)
+    into v_recipient_ids
+    from unnest(p_recipient_agent_ids) as recipient_id;
+
+  if (
+    select count(*)
+      from agent_board.agents
+     where id = any(v_recipient_ids)
+  ) <> cardinality(v_recipient_ids) then
+    raise exception 'recipient agent not found' using errcode = 'P0002';
+  end if;
+
+  if agent_board._is_service_role() then
+    perform agent_board._record_send_authz_telemetry(
+      'service_role_bypass',
+      coalesce(nullif(p_metadata -> 'signed_write' ->> 'origin', ''), 'unknown'),
+      v_actor_agent_id,
+      null,
+      'send_multicast_message',
+      agent_board._resolve_send_fleet_scope(v_actor_agent_id),
+      null,
+      jsonb_build_object('redacted', true)
+    );
+  end if;
+
+  perform agent_board._lock_idempotency_key(
+    'send_multicast_message:' || p_thread_id::text || ':' || v_actor_agent_id::text,
+    v_idempotency_key
+  );
+
+  if v_idempotency_key is not null then
+    select *
+      into v_message
+      from agent_board.messages
+     where thread_id = p_thread_id
+       and author_agent_id = v_actor_agent_id
+       and metadata ->> 'rpcName' = 'send_multicast_message'
+       and metadata ->> 'idempotencyKey' = v_idempotency_key
+     order by created_at desc
+     limit 1;
+  end if;
+
+  if v_message.id is null then
+    v_metadata := coalesce(p_metadata, '{}'::jsonb)
+      || jsonb_build_object(
+        'rpcName', 'send_multicast_message',
+        'subject', trim(p_subject),
+        'priority', p_priority
+      );
+    if v_idempotency_key is not null then
+      v_metadata := v_metadata || jsonb_build_object('idempotencyKey', v_idempotency_key);
+    end if;
+
+    select *
+      into v_created_message
+      from agent_board._insert_thread_message(
+        p_thread_id,
+        v_actor_agent_id,
+        p_body,
+        p_message_type,
+        null,
+        v_metadata
+      );
+
+    select *
+      into v_message
+      from agent_board.messages
+     where id = v_created_message.message_id;
+  end if;
+
+  v_preview := agent_board._trim_inbox_text(p_body, 280);
+
+  foreach v_recipient_id in array v_recipient_ids loop
+    v_fetch_descriptor := agent_board._build_fetch_descriptor(
+      'thread',
+      p_thread_id,
+      'agent_board.v_thread_feed',
+      'multicast delivery',
+      jsonb_build_object('messageId', v_message.id::text, 'recipientAgentId', v_recipient_id::text)
+    );
+
+    v_recipient := agent_board._upsert_delivery_recipient(
+      'multicast',
+      v_recipient_id,
+      'message',
+      v_message.id,
+      null,
+      null,
+      null,
+      null,
+      jsonb_build_object('priority', p_priority)
+    );
+
+    v_inbox := agent_board._upsert_inbox_item(
+      v_recipient.id,
+      v_recipient_id,
+      null,
+      v_recipient.delivery_mode,
+      'message',
+      v_message.id,
+      null,
+      null,
+      trim(p_subject),
+      v_preview,
+      p_priority,
+      true,
+      false,
+      v_fetch_descriptor,
+      jsonb_build_object('threadId', p_thread_id::text)
+    );
+
+    v_delivered_count := v_delivered_count + 1;
+    v_inbox_count := v_inbox_count + 1;
+    v_callback_count := v_callback_count + agent_board._queue_inbox_callbacks(v_inbox.id, 'inbox.item.delivered');
+  end loop;
+
+  return query
+  select v_message.id, v_delivered_count, v_inbox_count, v_callback_count, v_message.created_at;
+end;
+$function$;
+
+revoke all on function agent_board.post_message(uuid,uuid,text,text,uuid,jsonb) from public,anon,authenticated,service_role,agent_board_delegate;
+grant execute on function agent_board.post_message(uuid,uuid,text,text,uuid,jsonb) to authenticated,service_role,agent_board_delegate;
+comment on function agent_board.post_message(uuid,uuid,text,text,uuid,jsonb) is 'Posts a thread reply; inherited board threads use canonical board delivery; non-board and restricted threads retain insertion-only behavior. Session-derived author and return shape are unchanged.';
+
+revoke all on function agent_board.post_board_message(uuid,uuid,uuid,text,text,text,text,text,jsonb) from public,anon,authenticated,service_role,agent_board_delegate;
+grant execute on function agent_board.post_board_message(uuid,uuid,uuid,text,text,text,text,text,jsonb) to authenticated,service_role,agent_board_delegate;
+comment on function agent_board.post_board_message(uuid,uuid,uuid,text,text,text,text,text,jsonb) is 'Creates or reuses a canonical board post after validating the session actor, board authority and locked thread association; delivery fan-out and downstream effects are transactional.';
+
+revoke all on function agent_board.send_direct_message(uuid,uuid,uuid,text,text,text,text,text,jsonb) from public,anon,authenticated,service_role,agent_board_delegate;
+grant execute on function agent_board.send_direct_message(uuid,uuid,uuid,text,text,text,text,text,jsonb) to authenticated,service_role;
+comment on function agent_board.send_direct_message(uuid,uuid,uuid,text,text,text,text,text,jsonb) is 'Sends privately to the explicit recipient, including on board threads; uses the common authorized insertion primitive.';
+
+revoke all on function agent_board.send_multicast_message(uuid,uuid,uuid[],text,text,text,text,text,jsonb) from public,anon,authenticated,service_role,agent_board_delegate;
+grant execute on function agent_board.send_multicast_message(uuid,uuid,uuid[],text,text,text,text,text,jsonb) to authenticated,service_role;
+comment on function agent_board.send_multicast_message(uuid,uuid,uuid[],text,text,text,text,text,jsonb) is 'Sends privately to explicit recipients, including on board threads; uses the common authorized insertion primitive.';