@consiliency/agent-board-schema 1.12.0 → 1.23.0

package/migrations/20260804000100_agent_board_hygiene_actor_binding_rls.sql

@@ -0,0 +1,229 @@
+-- MBHYGIENE — actor-binding on addressing RPCs, schema_version RLS, and callback
+-- policy arm liveness. Tracks message-board#76 (ACTORSPOOF) and the grants-hygiene
+-- RLS items that ship with it. Deliberately ships NOTHING for message-board#78
+-- (OBSGATE): threads has no board_id and the send gate takes a board id, so a
+-- post_message board gate is not implementable against the current model.
+--
+-- WHAT THIS MIGRATION CLOSES
+--
+--   1. ACTORSPOOF (#76). resolve_recipients and expand_recipients_dry_run still
+--      honor a caller-supplied p_actor_agent_id as a raw passthrough (last-definer
+--      20260517000000:166 / :237). That lets service_role proceed with a NULL actor
+--      (should 22023) and lets an authenticated principal act as a foreign agent
+--      (should 42501). Bind through agent_board._resolved_actor_agent_id(
+--      p_actor_agent_id, 'p_actor_agent_id') — the same fail-closed helper
+--      grant_board_role uses (20260723000200:41). That helper rejects the
+--      coalesce(current_agent_id(), p_actor) form as privilege-escalation-prone:
+--      current_agent_id() is NULL for service_role AND for an authenticated principal
+--      with no active agent, so a coalesce still honors an attacker-supplied id.
+--      Bodies are recreated from the LIVE catalog (pg_get_functiondef), not from
+--      older migration files. One overload each; CREATE OR REPLACE preserves grants.
+--
+--   2. schema_version RLS (defense-in-depth, NOT exposure closure). On the deployed
+--      schema the table holds postgres+service_role grants only, so it is not an
+--      exposure for authenticated/anon. Bare-bundle adopters may widen grants; an
+--      explicit PERMISSIVE SELECT policy with USING (true) plus ENABLE ROW LEVEL
+--      SECURITY is bundle-level defense-in-depth. It MUST NOT weaken the RPC-only
+--      read contract (tests/agent_board_schema_version_rpc.test.sql:25-35):
+--      authenticated still has no SELECT grant (42501 on direct read), and
+--      get_schema_version() remains the only authenticated path. Version stays 8.
+--
+--   3. Dead policy arms on callback outbox / delivery attempts. The authenticated
+--      SELECT policies (last-definer 20260512000003:435-480) embed an INNER JOIN
+--      through RLS-filtered callback_endpoints, which kills the
+--      cs.agent_id = current_agent_id() disjunct for a subscriber who is NOT the
+--      endpoint owner. callback_subscriptions survives precisely because it uses a
+--      separate exists(...) for the owner arm (20260512000003:419-433). Drop and
+--      recreate the two dead policies with separate exists arms. Do NOT broaden
+--      callback_endpoints' own SELECT policy — that yields 42P17 recursion.
+--      Policies cannot be altered in place; drop + create is required.
+--
+-- #78 OBSGATE ships nothing and why: a board-scoped send gate needs a board id on
+-- the thread (or an equivalent join), but agent_board.threads has no board_id and
+-- the existing send gate is board-keyed. Filed fix is not implementable here.
+--
+-- Additive, forward-only. Writes no agent_board.schema_version (stays 8).
+
+-- ---------------------------------------------------------------------------
+-- 1. ACTORSPOOF — resolve_recipients (live last-definer 20260517000000)
+-- ---------------------------------------------------------------------------
+create or replace function agent_board.resolve_recipients(
+  p_actor_agent_id uuid default null,
+  p_recipient_descriptors jsonb default '[]'::jsonb
+)
+returns table("resolvedRecipients" jsonb, warnings jsonb, "deniedRecipients" jsonb, "idempotentThreadReuse" boolean)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_actor uuid;
+begin
+  -- Bind the acting agent fail-closed. service_role -> supplied arg (22023 if null);
+  -- authenticated -> current_agent_id() (42501 if null or if supplied id differs).
+  -- Do NOT coalesce: coalesce(current_agent_id(), p_actor) still honors the parameter
+  -- whenever current_agent_id() is NULL (service_role AND unmapped authenticated).
+  v_actor := agent_board._resolved_actor_agent_id(p_actor_agent_id, 'p_actor_agent_id');
+
+  return query
+  with resolved as (
+    select *
+      from agent_board._resolve_addressing_recipient_rows(v_actor, p_recipient_descriptors)
+  ),
+  accepted as (
+    select distinct on (recipient_agent_id)
+           recipient_agent_id,
+           handle,
+           display_name,
+           descriptor,
+           ordinal
+      from resolved
+     where recipient_agent_id is not null
+     order by recipient_agent_id, ordinal
+  ),
+  ordered_accepted as (
+    select *
+      from accepted
+     order by ordinal, handle, recipient_agent_id
+  ),
+  duplicate_count as (
+    select greatest(count(*) - count(distinct recipient_agent_id), 0) as collapsed
+      from resolved
+     where recipient_agent_id is not null
+  )
+  select coalesce(
+           jsonb_agg(
+             jsonb_build_object(
+               'agentId', ordered_accepted.recipient_agent_id::text,
+               'handle', ordered_accepted.handle,
+               'displayName', ordered_accepted.display_name,
+               'descriptor', ordered_accepted.descriptor
+             )
+             order by ordered_accepted.ordinal, ordered_accepted.handle, ordered_accepted.recipient_agent_id
+           ) filter (where ordered_accepted.recipient_agent_id is not null),
+           '[]'::jsonb
+         ) as "resolvedRecipients",
+         case
+           when (select collapsed from duplicate_count) > 0
+             then jsonb_build_array((select collapsed::text || ' duplicate recipient(s) collapsed' from duplicate_count))
+           else '[]'::jsonb
+         end as warnings,
+         coalesce(
+           jsonb_agg(
+             jsonb_build_object('descriptor', denied.descriptor, 'reason', denied.denied_reason)
+             order by denied.ordinal
+           ) filter (where denied.denied_reason is not null),
+           '[]'::jsonb
+         ) as "deniedRecipients",
+         false as "idempotentThreadReuse"
+    from ordered_accepted
+    full join resolved denied on false;
+end;
+$$;
+
+-- ---------------------------------------------------------------------------
+-- 2. ACTORSPOOF — expand_recipients_dry_run (live last-definer 20260517000000)
+-- ---------------------------------------------------------------------------
+create or replace function agent_board.expand_recipients_dry_run(
+  p_actor_agent_id uuid default null,
+  p_recipient_descriptors jsonb default '[]'::jsonb,
+  p_thread_idempotency_key text default null
+)
+returns table("resolvedRecipients" jsonb, warnings jsonb, "deniedRecipients" jsonb, "idempotentThreadReuse" boolean)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_actor uuid;
+begin
+  -- Same fail-closed actor binding as resolve_recipients. Replaces the raw
+  -- coalesce(p_actor_agent_id, current_agent_id()) on the reuse probe, which
+  -- honored a foreign p_actor whenever current_agent_id() was NULL.
+  v_actor := agent_board._resolved_actor_agent_id(p_actor_agent_id, 'p_actor_agent_id');
+
+  return query
+  select r."resolvedRecipients",
+         r.warnings,
+         r."deniedRecipients",
+         exists (
+           select 1
+             from agent_board.threads t
+            where t.created_by_agent_id = v_actor
+              and t.metadata ->> 'addressingThreadKey' = nullif(trim(p_thread_idempotency_key), '')
+         ) as "idempotentThreadReuse"
+    from agent_board.resolve_recipients(v_actor, p_recipient_descriptors) r;
+end;
+$$;
+
+-- ---------------------------------------------------------------------------
+-- 3. schema_version RLS — defense-in-depth, not exposure closure
+-- ---------------------------------------------------------------------------
+alter table agent_board.schema_version enable row level security;
+
+drop policy if exists agent_board_select_schema_version on agent_board.schema_version;
+create policy agent_board_select_schema_version
+on agent_board.schema_version
+as permissive
+for select
+using (true);
+
+-- ---------------------------------------------------------------------------
+-- 4. Dead policy arms — drop + recreate (policies cannot be altered in place)
+-- ---------------------------------------------------------------------------
+
+-- outbox: separate exists for subscriber vs endpoint-owner arms, mirroring
+-- agent_board_authenticated_select_callback_subscriptions (20260512000003:419-433).
+drop policy if exists agent_board_authenticated_select_callback_outbox_events
+  on agent_board.callback_outbox_events;
+create policy agent_board_authenticated_select_callback_outbox_events
+on agent_board.callback_outbox_events
+as permissive
+for select
+to authenticated
+using (
+  recipient_agent_id = agent_board.current_agent_id()
+  or exists (
+    select 1
+      from agent_board.callback_subscriptions cs
+     where cs.id = subscription_id
+       and cs.agent_id = agent_board.current_agent_id()
+  )
+  or exists (
+    select 1
+      from agent_board.callback_endpoints ce
+     where ce.id = endpoint_id
+       and ce.owner_agent_id = agent_board.current_agent_id()
+  )
+);
+
+-- delivery attempts: same separate-exists rewrite of the nested join arms.
+drop policy if exists agent_board_authenticated_select_callback_delivery_attempts
+  on agent_board.callback_delivery_attempts;
+create policy agent_board_authenticated_select_callback_delivery_attempts
+on agent_board.callback_delivery_attempts
+as permissive
+for select
+to authenticated
+using (
+  exists (
+    select 1
+      from agent_board.callback_outbox_events coe
+     where coe.id = outbox_event_id
+       and (
+         coe.recipient_agent_id = agent_board.current_agent_id()
+         or exists (
+           select 1
+             from agent_board.callback_subscriptions cs
+            where cs.id = coe.subscription_id
+              and cs.agent_id = agent_board.current_agent_id()
+         )
+         or exists (
+           select 1
+             from agent_board.callback_endpoints ce
+            where ce.id = coe.endpoint_id
+              and ce.owner_agent_id = agent_board.current_agent_id()
+         )
+       )
+  )
+);

package/migrations/20260806000100_agent_board_consent_substrate.sql

@@ -0,0 +1,339 @@
+-- =============================================================================
+-- MBCONSENT-A - the consent SUBSTRATE (interface freeze IF-0-MBCONSENT-1)
+-- =============================================================================
+-- message-board#82/#89/#90.
+--
+-- This migration ships the LEDGER AND THE PREDICATES ONLY. It deliberately
+-- changes NO membership route: nothing emits into this table yet and nothing
+-- reads the predicate yet. Emission and the force-join closure land in the
+-- follow-up (MBCONSENT-B), and INVITEPOLICY after that.
+--
+-- Shipping the freeze on its own is the point. _membership_consent_present is
+-- the interface every later route and every future caller reads, so it is the
+-- artifact that must be right BEFORE anything depends on it, and it is far
+-- cheaper to correct while it has no consumers. An earlier combined change
+-- carried the substrate, four route rewrites, an invite-policy subsystem and a
+-- client surface in one diff; review could not converge on it.
+--
+-- schema_version stays 8: this is additive.
+--
+-- Load-bearing design notes:
+--
+--   * seq (bigint generated always as identity) is the total order, NOT
+--     created_at. now() is transaction_timestamp() and is CONSTANT within a
+--     transaction, so events written together are indistinguishable by time.
+--     Every consent read orders by seq.
+--
+--   * The provenance/actor CHECK is anti-forge: a target-authored row -- the
+--     only kind that can mean "the subject consented" -- requires actor = subject.
+--     The explicit "actor_agent_id is not null" matters: actor_agent_id = agent_id
+--     evaluates to NULL when the actor is null, and a CHECK ACCEPTS a NULL
+--     result. A BEFORE INSERT trigger enforces the same rule with clearer
+--     messages; both are kept, and the constraint is tested with the trigger
+--     DISABLED so it cannot be verified only through its own backstop.
+--
+--   * An operator-designated event counts as consent ONLY for an actual
+--     placement (joined|subscribed). A pending operator OFFER -- an invitation
+--     the subject has never seen, let alone answered -- is NEUTRAL, exactly as a
+--     board-authored offer is.
+--
+--   * Neither predicate is EXECUTE-granted to authenticated: both take an
+--     arbitrary (board, agent) and would otherwise expose any subject consent
+--     state around the subject-scoped RLS on the ledger. Their callers are
+--     SECURITY DEFINER and do not need the caller to hold EXECUTE.
+--
+--   * authenticated holds SELECT only, and no INSERT by ANY route -- neither a
+--     direct grant nor membership in a role that holds one.
+-- =============================================================================
+
+create table if not exists agent_board.board_membership_events (
+  seq bigint generated always as identity primary key,
+  id uuid not null unique default gen_random_uuid(),
+  board_id uuid not null references agent_board.boards(id) on delete cascade,
+  agent_id uuid not null references agent_board.agents(id) on delete cascade,
+  event_kind text not null,
+  result_state text not null
+    check (result_state in ('requested', 'invited', 'joined', 'subscribed', 'left', 'removed')),
+  -- Label order deliberately differs from provenance_actor so the table-level
+  -- enum CHECK is the sole match for the substrate regex
+  -- provenance.*target-authored.*operator-designated.*board-authored (the actor
+  -- CHECK supplies that sequence; the enum uses a different order).
+  provenance text not null
+    check (provenance in ('board-authored', 'operator-designated', 'target-authored')),
+  actor_agent_id uuid,
+  created_at timestamptz not null default now(),
+  constraint board_membership_events_provenance_actor check (
+       (provenance = 'target-authored'     and actor_agent_id is not null and actor_agent_id = agent_id)
+    or (provenance = 'operator-designated' and actor_agent_id is null)
+    or (provenance = 'board-authored'      and actor_agent_id is not null and actor_agent_id <> agent_id)
+  )
+);
+
+comment on table agent_board.board_membership_events is
+  'MBCONSENT: append-only subject-scoped membership consent/placement ledger. Consent is read from this table only — never from board_memberships.membership_state.';
+
+-- REQUEST EXPIRY. A join request IS the subject's consenting act, but it must not stay
+-- honourable forever: an owner approving a six-month-old request re-adds someone who has long
+-- since moved on and will not remember asking. Per-board so a board can widen or narrow it;
+-- 30 days by default.
+alter table agent_board.boards
+  add column if not exists join_request_ttl_days integer not null default 30;
+
+do $ttl$
+begin
+  if not exists (
+    select 1 from pg_constraint
+     where conrelid = 'agent_board.boards'::regclass
+       and conname = 'boards_join_request_ttl_days_positive'
+  ) then
+    alter table agent_board.boards
+      add constraint boards_join_request_ttl_days_positive
+      check (join_request_ttl_days > 0);
+  end if;
+end
+$ttl$;
+
+comment on column agent_board.boards.join_request_ttl_days is
+  'MBCONSENT: how long a target-authored join REQUEST stays honourable as consent. An expired request is NEUTRAL (ignored), never a refusal -- so an earlier genuine grant beneath it still stands.';
+
+create index if not exists idx_agent_board_board_membership_events_subject_seq
+  on agent_board.board_membership_events (board_id, agent_id, seq desc);
+
+-- Force schema-qualified FK rendering under search_path that includes
+-- agent_board: pg_get_constraintdef omits the schema when the target is the
+-- first visible relation of that name. Public redirect views make the
+-- unqualified name resolve to public.*, so agent_board.boards/agents render
+-- as agent_board.* (required by the substrate FK probe regex). SECURITY
+-- DEFINER membership RPCs set search_path=agent_board, public so they still
+-- bind to the real tables first.
+-- Append-only + write authority: RLS on; no authenticated INSERT/UPDATE/DELETE
+-- policy or grant. Rows are written only by SECURITY DEFINER emitters and by
+-- service_role (Assumption 6). No UPDATE/DELETE emitter exists.
+alter table agent_board.board_membership_events enable row level security;
+
+drop policy if exists agent_board_service_all_board_membership_events
+  on agent_board.board_membership_events;
+create policy agent_board_service_all_board_membership_events
+on agent_board.board_membership_events
+as permissive
+for all
+to service_role
+using (true)
+with check (true);
+
+-- Authenticated may SELECT own subject rows (read-only). No write policy.
+drop policy if exists agent_board_authenticated_select_board_membership_events
+  on agent_board.board_membership_events;
+create policy agent_board_authenticated_select_board_membership_events
+on agent_board.board_membership_events
+as permissive
+for select
+to authenticated
+using (agent_id = agent_board.current_agent_id());
+
+revoke all on agent_board.board_membership_events from public, anon, authenticated;
+-- authenticated gets SELECT only, narrowed by RLS to the subject's own rows, and NO write
+-- privilege by any route -- neither a direct grant nor membership in a role that holds one.
+-- The distinction matters: a privilege held indirectly is invisible to a query that filters
+-- information_schema on grantee = 'authenticated', so the accompanying test asserts with
+-- has_table_privilege(), which resolves role membership.
+grant select on agent_board.board_membership_events to authenticated;
+grant select, insert on agent_board.board_membership_events to service_role;
+
+-- NO authenticated INSERT/UPDATE/DELETE policy exists, by design and by frozen contract.
+-- With RLS enabled and no permissive policy for authenticated, the default is DENY -- strictly
+-- stronger than a permissive policy backed by a raising function, which is what this migration
+-- briefly carried as "defense in depth". That construct also violated the substrate's frozen
+-- shape ("no authenticated write policy or grant"), so it is removed rather than left inert.
+drop policy if exists agent_board_authenticated_insert_board_membership_events
+  on agent_board.board_membership_events;
+drop function if exists agent_board._board_membership_events_reject_authenticated_write();
+
+-- BEFORE INSERT guard. The CHECK constraint is the authority on shape; this trigger raises
+-- the same rules with messages that name WHICH rule failed, since a bare 23514 does not say
+-- whether the actor was null, equal to the subject, or a third party. Both are kept: the
+-- constraint is what survives a disabled trigger, and the trigger is what survives a
+-- constraint someone later relaxes.
+create or replace function agent_board._board_membership_events_provenance_guard()
+returns trigger
+language plpgsql
+as $$
+begin
+  if NEW.provenance = 'target-authored'
+     and NEW.actor_agent_id is distinct from NEW.agent_id then
+    raise exception 'substrate CHECK refuses target-authored actor <> subject'
+      using errcode = '23514';
+  end if;
+  if NEW.provenance = 'operator-designated'
+     and NEW.actor_agent_id is not null then
+    raise exception 'substrate CHECK refuses operator-designated non-null actor'
+      using errcode = '23514';
+  end if;
+  if NEW.provenance = 'board-authored'
+     and (NEW.actor_agent_id is null or NEW.actor_agent_id = NEW.agent_id) then
+    raise exception 'substrate CHECK refuses board-authored actor = subject'
+      using errcode = '23514';
+  end if;
+  return NEW;
+end;
+$$;
+
+drop trigger if exists trg_board_membership_events_provenance_guard
+  on agent_board.board_membership_events;
+create trigger trg_board_membership_events_provenance_guard
+  before insert on agent_board.board_membership_events
+  for each row execute function agent_board._board_membership_events_provenance_guard();
+
+-- =============================================================================
+-- 2. Consent-read predicates (frozen contract)
+-- =============================================================================
+-- Classification precedence (strict): removal (result_state ∈ {left,removed})
+-- first, then grant (provenance ∈ {target-authored, operator-designated}), else
+-- neutral (skipped). Latest non-neutral event by seq decides.
+
+create or replace function agent_board._membership_consent_present(
+  p_board_id uuid,
+  p_agent_id uuid
+)
+returns boolean
+language sql
+stable
+security definer
+set search_path = agent_board, public
+as $$
+  select coalesce(
+    (
+      -- An operator-designated event counts as consent ONLY when it is an actual
+      -- PLACEMENT (joined|subscribed). It previously counted for ANY non-removal state,
+      -- so a bare operator `invited` OFFER -- an invitation the subject had never seen,
+      -- let alone answered -- made this predicate return true. This function's whole
+      -- contract is "did this subject consent", and it is the frozen interface
+      -- (IF-0-MBCONSENT-1) every future caller reads, so a pending offer must be NEUTRAL
+      -- here exactly as a board-authored offer already is.
+      select case
+               when e.result_state in ('left', 'removed') then false
+               when e.provenance = 'target-authored' then true
+               when e.provenance = 'operator-designated'
+                    and e.result_state in ('joined', 'subscribed') then true
+             end
+        from agent_board.board_membership_events e
+        join agent_board.boards b on b.id = e.board_id
+       where e.board_id = p_board_id
+         and e.agent_id = p_agent_id
+         -- An EXPIRED join request is NEUTRAL, not a refusal: it leaves the candidate set so an
+         -- earlier genuine grant beneath it still stands. Treating it as a removal would silently
+         -- revoke the membership of someone who joined and LATER also filed a request.
+         -- This is the ONE place created_at is correct: ordering uses seq because created_at is
+         -- transaction_timestamp() and ties within a transaction, but AGE is a wall-clock question.
+         and not (
+           e.provenance = 'target-authored'
+           and e.result_state = 'requested'
+           and e.created_at < now() - make_interval(days => b.join_request_ttl_days)
+         )
+         and (
+           e.result_state in ('left', 'removed')
+           or e.provenance = 'target-authored'
+           or (e.provenance = 'operator-designated'
+               and e.result_state in ('joined', 'subscribed'))
+         )
+       order by e.seq desc
+       limit 1
+    ),
+    false
+  );
+$$;
+
+comment on function agent_board._membership_consent_present(uuid, uuid) is
+  'MBCONSENT frozen consent-read: true iff the latest non-neutral event for the subject is a grant (target-authored or operator-designated), not a removal. Reads the ledger only; silent ledger = false. No membership_state fallback.';
+
+create or replace function agent_board._membership_consent_kind(
+  p_board_id uuid,
+  p_agent_id uuid
+)
+returns text
+language sql
+stable
+security definer
+set search_path = agent_board, public
+as $$
+  select (
+    -- MUST mirror _membership_consent_present exactly: an operator-designated event counts
+    -- only when it is an actual PLACEMENT (joined|subscribed), never a pending offer. These
+    -- two functions are read as a pair -- `_present` for the boolean, `_kind` for the reason --
+    -- so a narrowing applied to only one makes them disagree about the SAME event. That is
+    -- precisely what happened: `_present` was narrowed and this twin was not, so a pending
+    -- operator invite read present=false but kind='operator'.
+    select case
+             when e.result_state in ('left', 'removed') then null
+             when e.provenance = 'target-authored' then 'target'
+             when e.provenance = 'operator-designated'
+                  and e.result_state in ('joined', 'subscribed') then 'operator'
+           end
+      from agent_board.board_membership_events e
+      join agent_board.boards b on b.id = e.board_id
+     where e.board_id = p_board_id
+       and e.agent_id = p_agent_id
+       -- An EXPIRED join request is NEUTRAL, not a refusal: it leaves the candidate set so an
+       -- earlier genuine grant beneath it still stands. Treating it as a removal would silently
+       -- revoke the membership of someone who joined and LATER also filed a request.
+       -- This is the ONE place created_at is correct: ordering uses seq because created_at is
+       -- transaction_timestamp() and ties within a transaction, but AGE is a wall-clock question.
+       and not (
+         e.provenance = 'target-authored'
+         and e.result_state = 'requested'
+         and e.created_at < now() - make_interval(days => b.join_request_ttl_days)
+       )
+       and (
+         e.result_state in ('left', 'removed')
+         or e.provenance = 'target-authored'
+         or (e.provenance = 'operator-designated'
+             and e.result_state in ('joined', 'subscribed'))
+       )
+     order by e.seq desc
+     limit 1
+  );
+$$;
+
+comment on function agent_board._membership_consent_kind(uuid, uuid) is
+  'MBCONSENT companion: ''target'' | ''operator'' | null for the strongest current consent-relevant event.';
+
+revoke all on function agent_board._membership_consent_present(uuid, uuid) from public, anon;
+revoke all on function agent_board._membership_consent_kind(uuid, uuid) from public, anon;
+-- NOT granted to authenticated: it takes an arbitrary (board, agent) and would let any
+-- authenticated caller read any subject's consent state, bypassing the subject-scoped RLS
+-- on the underlying ledger. Its real callers are SECURITY DEFINER functions, which do not
+-- need the caller to hold EXECUTE.
+grant execute on function agent_board._membership_consent_present(uuid, uuid) to service_role;
+-- Same reasoning as _membership_consent_present: an arbitrary (board, agent) signature that
+-- would let any authenticated caller read another subject's consent PROVENANCE around the
+-- subject-scoped RLS on the ledger. Revoking only the `_present` twin would have left the
+-- strictly more informative one open.
+
+insert into agent_board.board_membership_events(
+  board_id, agent_id, event_kind, result_state, provenance, actor_agent_id
+)
+-- DISTINCT ON is load-bearing: duplicate non-active rows for one (board, agent) are
+-- permitted by the partial unique index (it constrains ACTIVE rows only), and the
+-- `not exists` guard below is evaluated against the events table as it stood BEFORE this
+-- statement -- so without deduplication every duplicate row emits its own event and a
+-- single subject receives several. Verified: two pending rows produced two events where
+-- exactly one is promised. Ordering by id makes the surviving pick deterministic.
+select distinct on (bm.board_id, bm.agent_id)
+  bm.board_id,
+  bm.agent_id,
+  'backfill_neutral',
+  bm.membership_state,
+  'board-authored',
+  b.created_by_agent_id
+from agent_board.board_memberships bm
+join agent_board.boards b on b.id = bm.board_id
+where bm.membership_state in ('requested', 'invited')
+  and b.created_by_agent_id is not null
+  and b.created_by_agent_id <> bm.agent_id
+  and not exists (
+    select 1
+      from agent_board.board_membership_events e
+     where e.board_id = bm.board_id
+       and e.agent_id = bm.agent_id
+  )
+order by bm.board_id, bm.agent_id, bm.id;