@consiliency/agent-board-schema 1.12.0 → 1.23.0

package/migrations/20260807000100_agent_board_consent_emission.sql

@@ -0,0 +1,619 @@
+-- =============================================================================
+-- MBCONSENT-B(a) — START RECORDING (emission only, no gating)
+-- =============================================================================
+-- message-board#82/#89/#90.
+--
+-- Every membership transition now writes exactly one event to the consent ledger that
+-- MBCONSENT-A froze. NOTHING READS IT YET: no route consults the predicate, so no call that
+-- succeeds today can begin failing. That is the point of landing emission alone -- the ledger
+-- fills, and the gating change that follows reads a populated ledger instead of an empty one.
+-- Gating first would deny everyone.
+--
+-- schema_version stays 8: additive.
+--
+-- The one load-bearing rule: provenance is derived HERE, from the session, and never from
+-- p_created_by_agent_id. A caller-supplied id is an ASSERTION about who acted; the session is
+-- EVIDENCE. And service_role is ALWAYS operator-designated -- even when a subject happens to
+-- resolve from its token -- because an operator acting is an operator placement, not the
+-- subject consenting.
+-- =============================================================================
+
+
+-- =============================================================================
+-- The emitter. ONE implementation, called from the shared sink AND from every raw writer.
+-- =============================================================================
+-- Five functions write board_memberships. Instrumenting only the shared sink leaves the other
+-- four emitting NOTHING, so a membership created through them would carry a SILENT ledger and
+-- later read as non-consenting once gating lands. Duplicating the derivation five times would
+-- let the copies drift, so there is exactly one.
+create or replace function agent_board._emit_membership_event(
+  p_board_id uuid,
+  p_agent_id uuid,
+  p_membership_state text,
+  p_event_kind text default null
+)
+returns void
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_actor_id uuid := agent_board.current_agent_id();
+  v_prov text;
+  v_event_actor uuid;
+  v_event_kind text;
+begin
+  -- Provenance is DERIVED HERE from the session and NEVER from a caller-supplied argument.
+  -- A caller-supplied id is an ASSERTION about who acted; the session is EVIDENCE. Keying off
+  -- the argument would let any caller mint a `target-authored` event -- the one provenance
+  -- that means "the subject consented".
+  --
+  -- service_role is ALWAYS operator-designated, even when a subject resolves from its token.
+  -- An operator acting while some agent id happens to be resolvable is still an operator
+  -- placement, and recording it as the subject's own act launders exactly what this ledger
+  -- exists to distinguish.
+  if agent_board._is_service_role() then
+    v_prov := 'operator-designated';
+    v_event_actor := null;
+  elsif v_actor_id is not null and v_actor_id = p_agent_id then
+    v_prov := 'target-authored';
+    v_event_actor := p_agent_id;
+  elsif v_actor_id is not null then
+    v_prov := 'board-authored';
+    v_event_actor := v_actor_id;
+  else
+    -- Unresolved, non-service actor. GATENULL should have refused upstream; if it did not,
+    -- fail CLOSED rather than invent a provenance for an unattributable write.
+    raise exception 'membership change has no attributable actor'
+      using errcode = '42501';
+  end if;
+
+  -- The KIND may be supplied by the caller; the PROVENANCE never can. The frozen mapping
+  -- names specific kinds for the raw writers -- owner_seed, consent_link_redeem,
+  -- operator_repair -- which a generic (provenance, state) derivation cannot produce. Letting
+  -- the caller name the kind while the security-critical field stays derived keeps the
+  -- vocabulary honest without reopening the forge: a wrong kind mislabels an event, a wrong
+  -- provenance would fabricate consent.
+  v_event_kind := coalesce(p_event_kind, case
+    when v_prov = 'target-authored' and p_membership_state in ('joined', 'subscribed') then 'consent_self_join'
+    when v_prov = 'target-authored' and p_membership_state = 'requested'               then 'consent_join_request'
+    when v_prov = 'target-authored' and p_membership_state = 'invited'                 then 'consent_self_invite'
+    when v_prov = 'target-authored' and p_membership_state in ('left', 'removed')      then 'self_withdraw'
+    when v_prov = 'board-authored'  and p_membership_state = 'invited'                 then 'invite_offer'
+    when v_prov = 'board-authored'  and p_membership_state = 'requested'               then 'request_manufactured'
+    when v_prov = 'board-authored'  and p_membership_state in ('joined', 'subscribed') then 'resolution'
+    when v_prov = 'board-authored'  and p_membership_state in ('left', 'removed')      then 'eviction'
+    when v_prov = 'operator-designated' and p_membership_state in ('joined', 'subscribed') then 'operator_designation'
+    when v_prov = 'operator-designated' and p_membership_state in ('left', 'removed')      then 'operator_removal'
+    -- Operator writes to a PENDING state are NEUTRAL, and must not borrow a grant kind.
+    -- `operator_repair` denotes bootstrap's grant; letting it be the catch-all made an ordinary
+    -- service-role write to `invited`/`requested` read as a repair-grant. Bootstrap still gets
+    -- operator_repair -- it passes the kind explicitly.
+    when v_prov = 'operator-designated' and p_membership_state = 'invited'                 then 'invite_offer'
+    when v_prov = 'operator-designated' and p_membership_state = 'requested'               then 'request_manufactured'
+    -- No catch-all. The (provenance, state) space is fully enumerated above, so reaching here
+    -- means a state was added without deciding what it MEANS. Fail loudly rather than silently
+    -- labelling it -- a wrong kind in an append-only ledger cannot be corrected later.
+    else null
+  end);
+
+  if v_event_kind is null then
+    raise exception 'no event kind for provenance % with resulting state %', v_prov, p_membership_state
+      using errcode = '22023';
+  end if;
+
+  insert into agent_board.board_membership_events(
+    board_id, agent_id, event_kind, result_state, provenance, actor_agent_id)
+  values (p_board_id, p_agent_id, v_event_kind, p_membership_state, v_prov, v_event_actor);
+end;
+$$;
+
+revoke all on function agent_board._emit_membership_event(uuid, uuid, text, text) from public;
+grant execute on function agent_board._emit_membership_event(uuid, uuid, text, text) to service_role;
+
+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::uuid, 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;
+  -- EC-MBROWID-3: currently-removed standing (R-LINK-7 set form), not a single row.
+  v_currently_removed boolean;
+  v_prior_state text;
+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\_%';
+
+  -- EC-MBROWID-3 / R-LINK-7: currently-removed standing is the SET predicate
+  -- (exists removed AND no active), not a single total-ordered row. A higher-id
+  -- removed row can coexist with an active row; inferring "removed" from the
+  -- total-order winner alone would then try to activate the removed row and
+  -- collide with idx_agent_board_board_memberships_active_unique (23505).
+  -- Capture standing before the row lock so the predicate is independent of
+  -- which physical row the active-preferring SELECT below returns.
+  v_currently_removed :=
+    exists (
+      select 1 from agent_board.board_memberships bm
+       where bm.board_id = p_board_id
+         and bm.agent_id = p_agent_id
+         and bm.membership_state = 'removed'
+    ) and not exists (
+      select 1 from agent_board.board_memberships bm
+       where bm.board_id = p_board_id
+         and bm.agent_id = p_agent_id
+         and bm.membership_state in ('joined', 'subscribed')
+    );
+
+  -- Duplicate-aware ACTIVE-row selection (3a): prefer an active row when one
+  -- exists, then total-order by created_at desc, id desc. A pure total-order
+  -- can select a higher-id REMOVED row while an ACTIVE row still exists.
+  -- When v_currently_removed, no active row exists and the total-order pick is
+  -- non-active (re-entry clamp applies below).
+  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
+     case when bm.membership_state in ('joined', 'subscribed') then 0 else 1 end,
+     bm.created_at desc,
+     bm.id desc
+   limit 1
+   for update;
+
+  -- The PRIOR state, captured before the update below overwrites v_membership. The emitter
+  -- cannot see it, and without it a joined<->subscribed self-toggle is indistinguishable from
+  -- a fresh join.
+  v_prior_state := v_membership.membership_state;
+
+  if v_membership.id is null then
+    -- INSERT branch intentionally omits `role` so a no-prior-row entry takes the table default
+    -- (20260717000100:13-15). Do not write role here — an explicit write is wrong.
+    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,
+           -- ROLERESET (#79): clamp role to the table default on non-active -> active re-entry.
+           -- Hardcoded 'member' (column default at 20260717000100:13-15); do not read
+           -- information_schema at runtime. Active -> active preserves bm.role (including owner).
+           -- Unconditional — no service_role exemption.
+           -- MBROWID: origin is non-active when the selected row is non-active OR when
+           -- currently-removed standing holds (R-LINK-7 set form). With active-preferring
+           -- selection those agree; the set form is load-bearing against equal-created_at
+           -- removed+left duplicates where a single-row read would flip with id order.
+           role = case
+                    when p_membership_state in ('joined', 'subscribed')
+                     and (
+                       v_membership.membership_state not in ('joined', 'subscribed')
+                       or v_currently_removed
+                     )
+                    then 'member'
+                    else bm.role
+                  end,
+           metadata = coalesce(bm.metadata, '{}'::jsonb) || v_metadata,
+           updated_at = now()
+     where bm.id = v_membership.id
+     returning * into v_membership;
+  end if;
+
+  -- Emission is delegated so the sink and the four raw writers cannot drift apart.
+  -- The frozen mapping distinguishes a self-TOGGLE between two active states from a fresh
+  -- self-JOIN. Only the sink knows the prior state, so it names the kind; the emitter derives
+  -- everything security-critical regardless.
+  perform agent_board._emit_membership_event(
+    p_board_id, p_agent_id, p_membership_state,
+    case
+      when v_prior_state in ('joined', 'subscribed')
+       and p_membership_state in ('joined', 'subscribed')
+       -- The states must actually DIFFER. join_board and update_board_membership both permit
+       -- joined->joined and subscribed->subscribed, and a write that changes nothing is not a
+       -- toggle of anything -- recording it as one permanently mislabels an append-only event.
+       and v_prior_state <> p_membership_state
+       and not agent_board._is_service_role()
+       and agent_board.current_agent_id() = p_agent_id
+      then 'consent_self_toggle'
+      else null
+    end);
+
+  return v_membership;
+end;
+$$;
+
+create or replace function agent_board.create_board(p_created_by_agent_id uuid, p_slug text, p_name text, p_description text DEFAULT NULL::text, p_metadata jsonb DEFAULT '{}'::jsonb, p_visibility text DEFAULT 'private'::text)
+ RETURNS TABLE(board_id uuid, slug text, name text, status text, visibility text, created_at timestamp with time zone, updated_at timestamp with time zone)
+ LANGUAGE plpgsql
+ SECURITY DEFINER
+ SET search_path TO 'agent_board', 'public'
+as $$
+#variable_conflict use_column
+declare
+  v_seed_state text;
+  v_actor uuid;
+  v_existing agent_board.boards%rowtype;
+  v_board agent_board.boards%rowtype;
+begin
+  if nullif(trim(p_slug), '') is null or nullif(trim(p_name), '') is null then
+    raise exception 'board slug and name are required' using errcode = '22023';
+  end if;
+  if coalesce(p_visibility, 'private') not in ('private', 'invite_only', 'open', 'directory_hidden') then
+    raise exception 'invalid board visibility' using errcode = '22023';
+  end if;
+
+  -- Effective actor: service_role -> supplied arg (create-on-behalf-of);
+  -- authenticated -> current_agent_id() and rejects arg <> current (42501).
+  v_actor := agent_board._resolved_actor_agent_id(p_created_by_agent_id, 'p_created_by_agent_id');
+
+  if not exists (select 1 from agent_board.agents where id = v_actor) then
+    raise exception 'agent not found' using errcode = 'P0002';
+  end if;
+
+  select * into v_existing
+    from agent_board.boards b
+   where b.slug = trim(p_slug);
+
+  if found then
+    -- Slug-collision path is OWNER-ONLY, keyed on CURRENT authority: the actor must
+    -- hold an ACTIVE owner-role membership on the existing board — NOT merely be its
+    -- original `created_by_agent_id`. A demoted or departed original creator no longer
+    -- owns the board and must NOT be able to re-open/rename/flip-visibility it.
+    if not exists (
+      select 1 from agent_board.board_memberships m
+       where m.board_id = v_existing.id
+         and m.agent_id = v_actor
+         and m.role = 'owner'
+         and m.membership_state in ('joined', 'subscribed')
+    ) then
+      raise exception 'board slug already in use' using errcode = '42501';
+    end if;
+
+    update agent_board.boards as b
+       set name = trim(p_name),
+           description = nullif(trim(p_description), ''),
+           status = 'active',
+           visibility = coalesce(p_visibility, 'private'),
+           metadata = coalesce(b.metadata, '{}'::jsonb) || coalesce(p_metadata, '{}'::jsonb),
+           updated_at = now()
+     where b.id = v_existing.id
+    returning * into v_board;
+    -- No owner re-seed: the owner was seeded at this board's original creation, and
+    -- re-promoting on every create_board would resurrect a deliberately demoted owner.
+  else
+    insert into agent_board.boards as b(slug, name, description, created_by_agent_id, visibility, metadata)
+    values (
+      trim(p_slug),
+      trim(p_name),
+      nullif(trim(p_description), ''),
+      v_actor,
+      coalesce(p_visibility, 'private'),
+      coalesce(p_metadata, '{}'::jsonb)
+    )
+    returning * into v_board;
+
+    -- Seed the creator's owner membership, bound to the board's ACTUAL
+    -- created_by_agent_id (never the raw param). Idempotent against the active
+    -- partial-unique index so at most one active owner row exists.
+    insert into agent_board.board_memberships as bm(board_id, agent_id, membership_state, role, created_by_agent_id)
+    values (v_board.id, v_board.created_by_agent_id, 'joined', 'owner', v_board.created_by_agent_id)
+    on conflict (board_id, agent_id) where (membership_state in ('joined', 'subscribed'))
+      do update set role = 'owner', updated_at = now()
+    returning bm.membership_state into v_seed_state;
+    -- The creator seeds their OWN owner seat, so the session is the subject and this emits
+    -- target-authored. Under service_role it emits operator-designated instead -- correct
+    -- either way, because the helper reads the session rather than being told.
+    --
+    -- v_seed_state, NOT a literal 'joined'. The ON CONFLICT above lifts only the ROLE, so a
+    -- board whose creator already holds a `subscribed` row stays subscribed while a literal
+    -- would record `joined` -- a ledger contradicting the table. Same defect the redemption
+    -- path had; fixing one instance without sweeping the class is how it survived here.
+    perform agent_board._emit_membership_event(v_board.id, v_board.created_by_agent_id, v_seed_state, 'owner_seed');
+  end if;
+
+  return query
+  select v_board.id, v_board.slug, v_board.name, v_board.status, v_board.visibility, v_board.created_at, v_board.updated_at;
+end;
+$$;
+
+create or replace function agent_board.bootstrap_board_owner_memberships()
+ RETURNS TABLE(board_id uuid, owner_agent_id uuid, membership_id uuid)
+ LANGUAGE plpgsql
+ SECURITY DEFINER
+ SET search_path TO 'agent_board', 'public'
+as $$
+#variable_conflict use_column
+declare
+  v_seed_state text;
+  v_row record;
+  v_membership_id uuid;
+begin
+  -- service_role-only: current_agent_id() is null for service_role, non-null for any
+  -- authenticated principal (guarded here in addition to the EXECUTE revoke below).
+  if not agent_board._is_service_role() then
+    raise exception 'bootstrap_board_owner_memberships is service_role-only' using errcode = '42501';
+  end if;
+
+  -- R-LINK-7 guard shape (structural proof requires no-active AND no-removed
+  -- contiguously): re-seed only when the creator has no active membership AND is
+  -- not currently removed. NEVER suppress on 'left' alone — that is the
+  -- sole-owner-lockout recovery trigger (agent_board_rolereset.test.sql assertion
+  -- 23). requested/invited-only creators still re-seed; a removed+left pair is
+  -- suppressed.
+  for v_row in
+    select b.id as board_id, b.created_by_agent_id as owner_agent_id
+      from agent_board.boards b
+     where not exists (
+       select 1
+         from agent_board.board_memberships bm
+        where bm.board_id = b.id
+          and bm.agent_id = b.created_by_agent_id
+          and bm.membership_state in ('joined', 'subscribed')
+     )
+       and not exists (
+       select 1
+         from agent_board.board_memberships bm
+        where bm.board_id = b.id
+          and bm.agent_id = b.created_by_agent_id
+          and bm.membership_state = 'removed'
+     )
+  loop
+    insert into agent_board.board_memberships as bm(board_id, agent_id, membership_state, role, created_by_agent_id)
+    values (v_row.board_id, v_row.owner_agent_id, 'joined', 'owner', v_row.owner_agent_id)
+    on conflict (board_id, agent_id) where (membership_state in ('joined', 'subscribed'))
+      do update set role = 'owner', updated_at = now()
+    returning bm.id, bm.membership_state into v_membership_id, v_seed_state;
+
+    -- Operator repair path: always operator-designated, never the owner's own act.
+    -- v_seed_state, NOT a literal: the ON CONFLICT lifts only the ROLE, so a concurrently
+    -- created `subscribed` membership stays subscribed while a literal would record `joined`.
+    perform agent_board._emit_membership_event(v_row.board_id, v_row.owner_agent_id, v_seed_state, 'operator_repair');
+
+    board_id := v_row.board_id;
+    owner_agent_id := v_row.owner_agent_id;
+    membership_id := v_membership_id;
+    return next;
+  end loop;
+end;
+$$;
+
+create or replace function agent_board._redeem_invite_for_agent(p_code text, p_agent_id uuid)
+ RETURNS TABLE(board_id uuid, agent_id uuid, role text, membership_state text, updated_at timestamp with time zone)
+ LANGUAGE plpgsql
+ SECURITY DEFINER
+ SET search_path TO 'agent_board', 'public'
+as $$
+-- OUT params board_id/agent_id/role/membership_state/updated_at share names with the
+-- membership columns referenced in the on-conflict target + update set below; prefer
+-- the column in any collision (mirrors ROOMOWN create_board).
+#variable_conflict use_column
+declare
+  v_inv agent_board.board_invite_tokens%rowtype;
+  v_led agent_board.board_invite_redemptions%rowtype;
+  v_m agent_board.board_memberships%rowtype;
+begin
+  -- Lock the token row FIRST (concurrency invariant: the exhaustion check and the
+  -- same-txn uses_count increment happen under this lock, and concurrent redeemers
+  -- of the same token serialize here).
+  select * into v_inv
+    from agent_board.board_invite_tokens t
+   where t.code = p_code
+   for update;
+  if not found then
+    raise exception 'invite is not usable' using errcode = '42501';
+  end if;
+
+  -- M1 idempotency ordering: an existing (invite, agent) ledger row means this is a
+  -- replay -> return the existing membership and SKIP every exhaustion/ceiling check
+  -- (a maxed link re-redeemed by the same agent is a no-op, NOT 42501).
+  select * into v_led
+    from agent_board.board_invite_redemptions r
+   where r.invite_id = v_inv.id
+     and r.agent_id = p_agent_id;
+  if found then
+    select * into v_m
+      from agent_board.board_memberships bm
+     where bm.id = v_led.membership_id;
+    return query
+    select v_m.board_id, v_m.agent_id, v_m.role, v_m.membership_state, v_m.updated_at;
+    return;
+  end if;
+
+  -- Genuinely new redemption: uniform 42501 for revoked / expired / exhausted
+  -- (no P0002-vs-42501 existence oracle).
+  if v_inv.revoked_at is not null then
+    raise exception 'invite is not usable' using errcode = '42501';
+  end if;
+  if v_inv.expires_at <= now() then
+    raise exception 'invite is not usable' using errcode = '42501';
+  end if;
+  if v_inv.max_uses is not null and v_inv.uses_count >= v_inv.max_uses then
+    raise exception 'invite is not usable' using errcode = '42501';
+  end if;
+
+  -- R-LINK-2 suspension containment: the creator must still be an ACTIVE agent
+  -- (revoke_agent suspends but does not drop memberships, so an outstanding link
+  -- from a compromised-then-suspended owner must stop minting).
+  if not exists (
+    select 1 from agent_board.agents a
+     where a.id = v_inv.created_by_agent_id and a.status = 'active'
+  ) then
+    -- Uniform message (see other 42501s) so a code-bearer cannot distinguish
+    -- "creator suspended" from a dead/expired/exhausted link (no lifecycle oracle).
+    raise exception 'invite is not usable' using errcode = '42501';
+  end if;
+
+  -- Re-bind: the creator's CURRENT authority must still cover the preset role
+  -- (stale admin-link auto-degrades if the creator was demoted).
+  if not agent_board._grant_within_ceiling(v_inv.created_by_agent_id, v_inv.board_id, v_inv.preset_role) then
+    raise exception 'invite is not usable' using errcode = '42501';
+  end if;
+
+  -- R-LINK-7 kicked-agent re-entry: refuse when the agent's CURRENT standing on the
+  -- board is 'removed' — i.e. a 'removed' row exists AND there is no active
+  -- (joined/subscribed) membership. The active partial-unique index does NOT cover
+  -- 'removed' rows, so a fresh 'joined' insert would otherwise bypass revocation +
+  -- join-approval. Scoping to "removed and not currently active" avoids a false
+  -- negative for an agent who was removed and then legitimately re-added (an active
+  -- row present ⇒ the rank-max upsert handles them correctly). Voluntary 'left' is
+  -- intentionally NOT blocked (self-departure).
+  if exists (
+    select 1 from agent_board.board_memberships bm
+     where bm.board_id = v_inv.board_id
+       and bm.agent_id = p_agent_id
+       and bm.membership_state = 'removed'
+  ) and not exists (
+    select 1 from agent_board.board_memberships bm
+     where bm.board_id = v_inv.board_id
+       and bm.agent_id = p_agent_id
+       and bm.membership_state in ('joined', 'subscribed')
+  ) then
+    raise exception 'invite is not usable' using errcode = '42501';
+  end if;
+
+  -- Record the ledger row (idempotent under concurrent same-agent redemption).
+  insert into agent_board.board_invite_redemptions as r(invite_id, agent_id)
+  values (v_inv.id, p_agent_id)
+  on conflict (invite_id, agent_id) do nothing;
+
+  -- B1 atomic rank-max membership upsert: never downgrade a higher existing role,
+  -- race-safe across concurrent tokens. On conflict targets the active partial-unique
+  -- index; the CASE lifts ONLY when the preset outranks the current role.
+  insert into agent_board.board_memberships (
+    board_id, agent_id, membership_state, role, created_by_agent_id
+  )
+  values (
+    v_inv.board_id, p_agent_id, v_inv.preset_membership_state, v_inv.preset_role,
+    v_inv.created_by_agent_id
+  )
+  on conflict (board_id, agent_id) where (membership_state in ('joined', 'subscribed'))
+    do update set
+      role = case
+        when agent_board._role_rank(excluded.role) > agent_board._role_rank(agent_board.board_memberships.role)
+          then excluded.role
+        else agent_board.board_memberships.role
+      end,
+      updated_at = now()
+  returning * into v_m;
+
+  -- The redeemer places THEMSELVES -- the public wrapper passes current_agent_id() and takes no
+  -- target parameter -- so this emits target-authored: redeeming a link IS the consenting act.
+  --
+  -- v_m.membership_state, NOT v_inv.preset_membership_state. The ON CONFLICT above lifts only
+  -- the ROLE and leaves an existing membership_state untouched, so an already-`subscribed`
+  -- member redeeming a `joined` link stays subscribed. Emitting the token's preset would
+  -- record a resulting state the row does not have -- a ledger that contradicts the table it
+  -- describes. Recording the redemption as a fresh consent act is right; recording the wrong
+  -- outcome is not.
+  perform agent_board._emit_membership_event(
+    v_inv.board_id, p_agent_id, v_m.membership_state, 'consent_link_redeem');
+
+  -- Consume one use and bind the ledger row to the resulting membership.
+  update agent_board.board_invite_tokens t
+     set uses_count = t.uses_count + 1
+   where t.id = v_inv.id;
+
+  update agent_board.board_invite_redemptions r
+     set membership_id = v_m.id
+   where r.invite_id = v_inv.id
+     and r.agent_id = p_agent_id;
+
+  return query
+  select v_m.board_id, v_m.agent_id, v_m.role, v_m.membership_state, v_m.updated_at;
+end;
+$$;
+
+create or replace function agent_board._fedsession_autojoin_default_board(p_provider agent_board.identity_providers, p_agent_id uuid)
+ RETURNS void
+ LANGUAGE plpgsql
+ SECURITY DEFINER
+ SET search_path TO 'agent_board', 'public'
+as $$
+begin
+  if p_provider.default_board_id is null then
+    return;
+  end if;
+  -- The NOT EXISTS below is FIRST-TIME-ONLY (any existing membership row, incl. 'left'/
+  -- 'removed', suppresses the auto-join so a human who deliberately left is not re-joined).
+  -- Under concurrency it is NOT sufficient on its own: two concurrent re-provisions of the
+  -- same already-provisioned human can both pass NOT EXISTS, and the second insert then trips
+  -- the partial unique index idx_agent_board_board_memberships_active_unique. Catch that
+  -- unique_violation to a no-op (mirrors enroll_federated_human's step-8 agent-insert race
+  -- handling) so auto-join is NEVER fatal to the session mint and never duplicates.
+  begin
+    insert into agent_board.board_memberships(
+      board_id, agent_id, role, membership_state, created_by_agent_id, metadata)
+    select p_provider.default_board_id, p_agent_id, 'member', 'joined', p_agent_id,
+           jsonb_build_object('source', 'fedsession-autojoin', 'providerId', p_provider.id)
+    where exists (
+        select 1 from agent_board.boards b
+         where b.id = p_provider.default_board_id
+           and b.status = 'active')
+      and not exists (
+        select 1 from agent_board.board_memberships m
+         where m.board_id = p_provider.default_board_id
+           and m.agent_id = p_agent_id);
+
+    -- FOUND is true only if the conditional insert actually placed a row. The NOT EXISTS can
+    -- suppress it entirely, and the race branch below is a no-op -- neither must emit an event
+    -- for a placement that did not happen.
+    if found then
+      -- A LITERAL is correct here, and only here. The other writers use ON CONFLICT DO UPDATE,
+      -- which can preserve a DIFFERENT existing state -- so a literal there records an outcome
+      -- the row does not have. This insert has NO conflict-update path: it either inserts
+      -- exactly this state or inserts nothing, and `found` gates the emit. Do not copy the
+      -- literal to a writer that upserts.
+      perform agent_board._emit_membership_event(p_provider.default_board_id, p_agent_id, 'joined', 'operator_designation');
+    end if;
+  exception when unique_violation then
+    null;  -- concurrent auto-join won the race; its membership stands. Non-fatal.
+  end;
+end;
+$$;