@consiliency/agent-board-schema 1.22.0 → 1.24.0

package/migrations/20260903000200_agent_board_fedsession_provider_absence_gate.sql

@@ -0,0 +1,177 @@
+-- Consiliency/message-board#193 -- enroll_federated_human skipped its board and
+-- provider locking entirely when the provider row did not exist, then locked the
+-- human owner and delegated. The delegate re-reads the provider under a FRESH READ
+-- COMMITTED snapshot, so a provider inserted and committed in that gap was visible
+-- to it and its default board was auto-joined while this transaction already held
+-- auth.users:
+--
+--   portal fedsession (absent-provider path)   holds owner  -> wants board
+--   onboard_federated_fleet_agent              holds board  -> wants owner
+--
+-- reproduced as `ERROR: deadlock detected`. This is the third instance of one
+-- family (#153 machine<->domain, #189 ceiling-ABSENCE, this) plus #194: an
+-- ordering guarantee that holds on the common path and escapes on an edge no
+-- textual check can see. Here the escaping edge is ABSENCE -- there is no row to
+-- lock, so the ordering simply does not happen.
+--
+-- THE FIX is to fail before acquiring anything, which is the only ordering-safe
+-- answer when the thing to order on does not exist. The neighbouring case (a
+-- concurrent NULL -> board designation) was already handled by 20260901000140 via
+-- the snapshot/lock/compare; provider-absent-entirely was the case that escaped it.
+--
+-- BEHAVIOUR CHANGE IN THE RACE, written down rather than left to be discovered.
+-- Pre-fix, a caller that lost a provider-creation race could OCCASIONALLY SUCCEED:
+-- the delegate re-read the provider on a fresh READ COMMITTED snapshot and, if the
+-- creation had committed in the gap, proceeded -- which is precisely the
+-- interleaving that produced the deadlock. Post-fix that caller deterministically
+-- fails ONCE, with the same 42501 a permanently unallowlisted issuer gets, and
+-- succeeds on its next /portal-session call. That is the trade: an occasional
+-- silent success bought with a cross-route cycle, exchanged for one deterministic
+-- refusal.
+--
+-- WHY 42501 AND NOT A RETRYABLE 40001. No shipped caller distinguishes them.
+-- Nothing under packages/*/src references 40001 or 40P01, and
+-- AgentBoardClientError.retryable is set from HTTP status and only ever consumed by
+-- the session-mint loop -- no code path maps a SQLSTATE to a retry. So the two
+-- codes are operationally identical to every client that exists today, while 40001
+-- would additionally instruct any FUTURE retry loop to spin forever on a genuinely
+-- unallowlisted issuer. A serialization-based alternative (advisory-lock the
+-- absence, re-read under it, let the race loser proceed) was built and reverted for
+-- the same reason: it is machinery for a difference no caller can observe.
+
+-- Recreated with CREATE OR REPLACE (ACL and COMMENT survive); grants and comment
+-- restated below regardless, per the repo rule. Body is otherwise byte-identical to
+-- 20260901000140.
+--
+-- WHAT THIS DOES NOT CHANGE. A permanently unallowlisted (issuer, audience) already
+-- failed with 42501 -- from the delegate's step (4), after the owner had been
+-- provisioned and locked. The verdict and the SQLSTATE are unchanged; only the
+-- point at which they are reached moves, and with it the lock the transaction was
+-- holding when it happened. tests/isolation/specs/fedsession_provider_absent_owner_lock.spec
+-- pins exactly that: with a guard session holding the owner row, the pre-fix
+-- function BLOCKS and the fixed one raises without waiting.
+
+create or replace function agent_board.enroll_federated_human(
+  p_issuer text,
+  p_audience text,
+  p_subject text,
+  p_human_identity_claim jsonb,
+  p_display_name text default null
+)
+returns table(
+  agent_id uuid,
+  auth_user_id uuid,
+  handle text,
+  kind text,
+  status text,
+  provider_id text,
+  created_at timestamptz
+)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_provider_id agent_board.identity_providers.id%type;
+  v_default_board_id uuid;
+  v_locked_default_board_id uuid;
+  v_handle text;
+  v_uid uuid;
+begin
+  if not agent_board._is_service_role() then
+    raise exception 'service_role required for enroll_federated_human' using errcode = '42501';
+  end if;
+  if p_subject is null then
+    raise exception 'verified subject is required' using errcode = '22023';
+  end if;
+
+  -- Snapshot the provider's auto-join target without a row lock so a non-null
+  -- target can be locked in canonical board -> provider order. Then lock the
+  -- provider row and require that the target did not change across the gap. A
+  -- concurrent NULL -> board designation is rejected for retry rather than
+  -- falling back to provider -> board and recreating the cross-route cycle.
+  select ip.id, ip.default_board_id
+    into v_provider_id, v_default_board_id
+    from agent_board.identity_providers ip
+   where ip.issuer = p_issuer
+     and ip.audience = p_audience
+   limit 1;
+
+  -- #193 PROVIDER-ABSENCE GATE, and it must come BEFORE the owner is provisioned
+  -- or locked. PostgreSQL cannot row-lock a row that does not exist, so an absent
+  -- provider left NOTHING to serialize on: this function used to skip the whole
+  -- board/provider ordering, lock the owner, and delegate -- and under READ
+  -- COMMITTED the delegate takes a FRESH snapshot, so a provider committed in that
+  -- gap became visible and its default board was auto-joined while this
+  -- transaction held auth.users. That is owner -> board, inverted against fleet
+  -- onboarding's board -> owner, and it deadlocked.
+  --
+  -- Rejecting here is a VALID serialization -- it orders this call before the
+  -- provider's creation, which is exactly what its own snapshot saw -- and it is
+  -- the same verdict _enroll_federated_human_after_revocation_gate step (4) would
+  -- have reached anyway for an allowlist miss, only now reached before any lock.
+  -- The message differs from the delegate's so a test can tell which gate fired.
+  -- NOTE: this is a permanent 42501, not a retryable 40001. A genuinely
+  -- unallowlisted issuer is a configuration error, and telling a caller to retry it
+  -- forever is worse than telling it no; the rare loser of a real provider-creation
+  -- race succeeds on its next /portal-session call.
+  if v_provider_id is null then
+    raise exception 'issuer/audience not in the identity-provider allowlist (rejected before any owner or board lock)'
+      using errcode = '42501';
+  end if;
+
+  if v_default_board_id is not null then
+    perform 1 from agent_board.boards b
+     where b.id = v_default_board_id
+     for update;
+    if not found then
+      raise exception 'federated human default board changed during enrollment'
+        using errcode = '40001';
+    end if;
+  end if;
+
+  -- Freeze the designation this transaction will delegate against. The provider row
+  -- is held FOR UPDATE through commit, and (issuer, audience) is UNIQUE, so the
+  -- delegate's own lookup cannot resolve to a different row or a changed
+  -- default_board_id than the one locked above.
+  select ip.default_board_id
+    into v_locked_default_board_id
+    from agent_board.identity_providers ip
+   where ip.id = v_provider_id
+   for update;
+  if not found or v_locked_default_board_id is distinct from v_default_board_id then
+    raise exception 'federated human default board changed during enrollment'
+      using errcode = '40001';
+  end if;
+
+  v_handle := 'fed-human-' || substr(
+    encode(extensions.digest(convert_to(p_issuer || '|' || p_subject, 'UTF8'), 'sha256'), 'hex'),
+    1, 32);
+  v_uid := agent_board._ensure_agent_auth_user(v_handle);
+
+  perform 1 from auth.users u where u.id = v_uid for update;
+  if not found then
+    raise exception 'federated human owner not found after provisioning' using errcode = 'P0002';
+  end if;
+  if exists (
+    select 1
+      from agent_board.fleet_human_revocations r
+     where r.issuer = p_issuer
+       and r.subject = p_subject
+  ) then
+    raise exception 'human identity is durably revoked' using errcode = '42501';
+  end if;
+
+  return query
+  select * from agent_board._enroll_federated_human_after_revocation_gate(
+    p_issuer, p_audience, p_subject, p_human_identity_claim, p_display_name
+  );
+end;
+$$;
+
+comment on function agent_board.enroll_federated_human(text, text, text, jsonb, text) is
+  'Service-role federated-human enrollment used by /portal-session. Requires an allowlisted (issuer, audience) BEFORE provisioning or locking anything (#193: an absent provider cannot be row-locked, so proceeding left the board/provider ordering unenforced and inverted board -> owner against fleet onboarding), then locks a non-null default board before its provider row, freezes that designation, holds the deterministic auth.users owner lock, rejects durable issuer/subject revocation, and delegates to the internal provisioner.';
+revoke all on function agent_board.enroll_federated_human(text, text, text, jsonb, text)
+  from public, anon, authenticated;
+grant execute on function agent_board.enroll_federated_human(text, text, text, jsonb, text)
+  to service_role;

package/migrations/20260904000100_agent_board_wake_recovery_surface.sql

@@ -0,0 +1,155 @@
+-- WAKERECOVERY / message-board#191 — a gap-safe wake recovery surface.
+--
+-- THE DEFECT THIS CLOSES. A wake consumer that gates recovery on a monotonic
+-- cursor silently drops a late-committing writer. `callback_outbox_events.seq`
+-- (#187) is an identity column and identity sequences are NON-TRANSACTIONAL, so
+-- `seq` is monotonic in ASSIGNMENT order, not COMMIT order: a transaction that
+-- inserts early and commits late holds a seq BELOW a cursor the consumer has
+-- already persisted, and `seq > my_cursor` never returns it. The committed
+-- isolation probe `outbox_wake_ordering.spec` records exactly that
+-- (`late_committer_holds_a_lower_seq_than_the_persisted_cursor = t`).
+--
+-- THE CLASS IS WIDER THAN `seq`. `created_at` / `updated_at` default to `now()`,
+-- which is `transaction_timestamp()` — also assigned before commit, and worse:
+-- a fan-out writes N rows with byte-identical timestamps, so a timestamp cursor
+-- cannot even totally order what it DOES see. The unsafe class is therefore
+-- "gates recovery on ANY value assigned before commit", not "gates on seq".
+--
+-- THE FIX IS TO STOP ASKING AN ORDERING QUESTION. Restart recovery does not need
+-- "what is new since I last looked" (a cursor); it needs "what have I not dealt
+-- with" (a STATE). A late-committing insert lands with `action_state = 'new'`, so
+-- the moment it is visible it is in the set. There is no value to compare and
+-- therefore nothing to skip. This is the same property that makes
+-- `claim_callback_outbox_events` lossless (#187: "the claim path is lossless
+-- because it partitions on STATUS, never on seq"), applied to the surface a wake
+-- consumer actually fetches from.
+--
+-- WHY A VIEW AND NOT A FILTER IN THE CONSUMER. A predicate that lives only in a
+-- TypeScript descriptor cannot be pinned: an isolation spec could only assert a
+-- query the spec itself writes, and mutating the spec to make the spec fail
+-- proves nothing. A view puts the predicate in pg_catalog where a probe can read
+-- it and a mutation can break it. `pg_get_viewdef` is regenerated from the parse
+-- tree, so comments and formatting are gone by construction — a class assertion
+-- over a view definition cannot be defeated by prose the way a `prosrc` scanner
+-- in this repo was once defeated by a COMMENT placed beside an inverted lock.
+--
+-- WHAT THIS MIGRATION DOES NOT DO. No producer changes. `inbox_items` gains no
+-- column, no trigger, no policy. `callback_outbox_events` and its `seq` are
+-- untouched — `seq` keeps exactly the meaning #187 shipped it with (deterministic
+-- claim ordering and observability, never a recovery cursor).
+-- `agent_board.schema_version` stays at 8: this adds no enforcement switch.
+--
+-- RECIPIENT SCOPING IS IN THIS VIEW, NOT IN THE CONSUMER'S FILTER. RLS on
+-- `inbox_items` is NOT self-scoped: `agent_board_authenticated_select_inbox_items`
+-- (20260713000000) admits a second disjunct --
+--   board_id is not null AND visible_in_board_feed AND caller is a co-member
+-- -- and `post_board_message` upserts every board delivery with BOTH visibility
+-- flags true. So an unfiltered read of the unhandled set hands a caller its
+-- CO-MEMBERS' items, which a triage consumer would then act on. Measured, not
+-- reasoned: driving the real `post_board_message` path and reading this view as
+-- agent A returned 1 row belonging to agent B before this predicate was added.
+--
+-- The scoping deliberately lives HERE and not in the runtime's fetch descriptor.
+-- The FLEETNOTIFY contract states that a hint's filters are never authority; a
+-- security boundary placed in `filters` is one a caller can drop or mistype, and
+-- no catalog assertion could pin it. In the view it is server-side, applies to
+-- every caller regardless of the descriptor, and is pinnable from pg_catalog --
+-- the same argument that made this a view rather than a TypeScript predicate.
+--
+-- ACL NOTE. There is no DROP FUNCTION here, so the ACL/COMMENT-discard trap does
+-- not arise. A `create or replace view` preserves an existing ACL, so the revoke
+-- below is stated explicitly rather than implied by omitting a grant: re-running
+-- this migration over an earlier copy of the view must CONVERGE, not inherit.
+--
+-- `service_role` is deliberately DENIED, which is why the grants are NOT a mirror
+-- of `v_agent_inbox`'s. `service_role` holds BYPASSRLS and `current_agent_id()`
+-- returns NULL for it, so a scoped view would hand it a silently EMPTY recovery
+-- set -- an identity-less principal being told "nothing to recover" is precisely
+-- the silent-drop failure this migration exists to close. Denying SELECT converts
+-- that silence into a loud `permission denied`. This surface is defined relative
+-- to the session's own agent identity; a principal without one has no answer here,
+-- and must read `v_agent_inbox` with an explicit recipient filter instead.
+
+-- Built on `v_agent_inbox`, not on `inbox_items`, so `visible_in_inbox = true` is
+-- INHERITED rather than restated: one rule, one place.
+--
+-- WHAT `security_invoker = true` BUYS -- corrected AGAIN, from a full matrix.
+-- Cross-agent exclusion is enforced by the `current_agent_id()` predicate below,
+-- not by RLS. With that predicate deleted and the read taken as agent A, the four
+-- cells are (co-member rows / stranger rows returned):
+--
+--     this view    v_agent_inbox    co-member   stranger
+--     invoker      invoker          1           0
+--     reset        invoker          1           0
+--     invoker      reset            1           1
+--     reset        reset            1           1
+--
+-- THIS view's flag is inert in every cell. The bound is carried entirely by
+-- `v_agent_inbox`'s flag: an inner `security_invoker` view re-anchors base-table
+-- RLS to the real querying user through any outer definer view. An earlier
+-- version of this paragraph said the bound held "on this view OR on
+-- `v_agent_inbox`" -- attributing it to a flag that does not carry it. The flag
+-- is still declared here because it becomes load-bearing the moment this view is
+-- rebuilt directly on `inbox_items`, and `v_agent_inbox`'s flag is pinned as a
+-- catalog-derived class over every agent_board view in
+-- agent_board_inbox_reads.test.sql.
+--
+-- WHAT RECOVERY COMPLETENESS NOW DEPENDS ON, stated because this migration is what
+-- makes it depend on them. `current_agent_id()` resolves `auth.uid()` to one
+-- active agent. It carries no ORDER BY, but that is NOT a hazard: partial unique
+-- indexes `idx_agent_board_agents_auth_user_id_unique` (auth_user_id IS NOT NULL)
+-- and `..._active_unique` make two agents on one auth user impossible, so the
+-- resolution is single-valued. (Checked -- a review seat reported "no unique
+-- constraint on agents.auth_user_id", which is true of pg_constraint and false of
+-- the schema: the guarantee is enforced by unique INDEXES.)
+--
+-- The real exposure is the other one: if the caller has NO active agent -- revoked,
+-- or an operator session with no agent identity -- `current_agent_id()` returns
+-- NULL and this view returns an EMPTY set rather than raising. Empty is
+-- indistinguishable from "nothing to recover", which is the same silent-drop shape
+-- the `service_role` revoke below closes, one layer up. A consumer that can be
+-- identity-less must check its identity, not infer it from an empty recovery set.
+--
+-- There is deliberately NO `ORDER BY`. The unhandled set is a SET, not a cursor
+-- stream. Ordering is presentation and belongs to the caller; putting one here
+-- would invite keyset pagination over `created_at`, which is the exact defect
+-- this migration closes.
+--
+-- The state set is `('new', 'restored', 'deferred')` VERBATIM from the existing
+-- partial index `idx_agent_board_inbox_items_agent_pending`, so the index serves
+-- this view. The pgTAP asserts that equality from the catalog on BOTH sides, so
+-- editing either one alone fails.
+create or replace view agent_board.v_agent_wake_recovery
+with (security_invoker = true)
+as
+select
+  vi.inbox_item_id,
+  vi.delivery_recipient_id,
+  vi.recipient_agent_id,
+  vi.recipient_handle,
+  vi.recipient_display_name,
+  vi.board_id,
+  vi.board_slug,
+  vi.board_name,
+  vi.delivery_mode,
+  vi.source_kind,
+  vi.source_message_id,
+  vi.source_task_id,
+  vi.source_delegation_id,
+  vi.subject,
+  vi.preview,
+  vi.priority,
+  vi.action_state,
+  vi.visible_in_board_feed,
+  vi.fetch_descriptor,
+  vi.created_at,
+  vi.updated_at
+from agent_board.v_agent_inbox vi
+where vi.action_state in ('new', 'restored', 'deferred')
+  and vi.recipient_agent_id = agent_board.current_agent_id();
+
+grant select on agent_board.v_agent_wake_recovery to authenticated;
+revoke all on agent_board.v_agent_wake_recovery from service_role;
+
+comment on view agent_board.v_agent_wake_recovery is
+  'message-board#191 gap-safe wake recovery surface: the caller''s UNHANDLED inbox set (action_state in new/restored/deferred), partitioned on STATUS and carrying no cursor. Recovery must never gate on a pre-commit-assigned value (callback_outbox_events.seq, created_at, updated_at): those order ASSIGNMENT, not COMMIT, so a transaction that inserts early and commits late lands below an already-persisted cursor and is silently dropped. Scoped to the calling agent (current_agent_id()): RLS on inbox_items is NOT self-scoped -- it also admits co-members'' board-feed-visible items -- so the scoping is stated here rather than left to a caller''s filter. EXIT PATHS, verified against pg_catalog and not against the design doc: agent_board.update_inbox_item_state is the ONLY function that writes inbox_items.action_state. mark_read does NOT -- it writes read_receipts, so a read item is still unhandled. notification_ack is not a database function at all; it is a client-side alias that calls update_inbox_item_state with action_state = ''acknowledged''. DRAIN IN BOUNDED PASSES, NEVER "UNTIL EMPTY": ''deferred'' is itself an explicit ack write AND is a member of this set, so deferring an item acknowledges it and leaves it here -- a consumer that defers anything and loops until empty never terminates. Concurrent inserts can also outpace processing. A drain MUST bound its own passes and must not treat a non-empty set as a reason to keep looping. WHY THE ONE-WRITER CLAIM IS STRUCTURAL: inbox_items carries no user trigger, and authenticated/service_role hold SELECT only (no direct UPDATE), so nothing can move an item out of this set except the definer RPC. The second DML writer, _upsert_inbox_item, never touches action_state on conflict -- though it does overwrite visible_in_inbox, which would hide an item from this set with no ack if a caller ever passed false (no current caller does; the argument is positional and this is not pinned). security_invoker, so RLS on inbox_items still applies underneath the scoping.';

package/migrations/20260905000100_agent_board_consent_gating_reconcile.sql

@@ -0,0 +1,151 @@
+-- Reconcile join_board onto its consent-gated definition (message-board#217).
+--
+-- WHY THIS EXISTS. Supabase keys supabase_migrations.schema_migrations on the
+-- 14-digit VERSION PREFIX alone, not the name. An adopter that independently
+-- authored a migration at 20260809000100 therefore has that version recorded
+-- under its own name, and the bundle's 20260809000100_agent_board_consent_gating
+-- is SKIPPED SILENTLY -- no error, because that file is three
+-- `create or replace function` statements. The database reaches schema_version 8
+-- while retaining pre-consent authorization semantics, and the deploy reports
+-- success. Found by Consiliency/consiliency-portal while adopting 1.22.0.
+--
+-- WHY join_board AND NOTHING ELSE. The skipped file redefines three functions,
+-- but two of them are superseded by LATER migrations that carry the consent
+-- gating forward: resolve_board_request by 20260819000100 and
+-- update_board_membership by 20260813000100. join_board has no later definition
+-- -- its newest is the skipped one -- so on an affected database it is still the
+-- pre-consent 20260803000100 body. That single function is the entire live gap.
+--
+-- WHY NOT RENUMBER THE ORIGINAL. Renumbering looks safe because the migration is
+-- idempotent, but idempotent is not order-independent. On a HEALTHY database the
+-- renumbered file would be the only unapplied migration, so it would run LAST --
+-- after 20260813000100 and 20260819000100 -- and re-apply the older
+-- resolve_board_request and update_board_membership bodies over the newer ones.
+-- That is a silent authorization ROLLBACK on every correctly-adopted database,
+-- including production. A forward-only migration cannot do that, because it runs
+-- last by construction and carries the newest definition of the only function it
+-- touches.
+--
+-- EFFECT. Healthy database: byte-identical body, a true no-op. Affected database:
+-- receives the consent gating it never got, with no `supabase migration repair`
+-- and no operator intervention. `create or replace` preserves the existing ACL
+-- and this migration adds no new grants, so the privilege surface is unchanged
+-- either way.
+
+create or replace function agent_board.join_board(p_board_id uuid, p_agent_id uuid, p_membership_state text DEFAULT 'joined'::text, p_created_by_agent_id uuid DEFAULT NULL::uuid, p_metadata jsonb DEFAULT '{}'::jsonb)
+ RETURNS TABLE(membership_id uuid, board_id uuid, agent_id uuid, membership_state 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 $$
+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
+  -- GATENULL (#58): only service_role may proceed with an unresolved actor.
+  if v_actor is null and not agent_board._is_service_role() then
+    raise exception 'current agent principal not resolved' using errcode = '42501';
+  end if;
+
+  if p_membership_state not in ('joined', 'subscribed') then
+    raise exception 'join_board only accepts joined or subscribed' using errcode = '22023';
+  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 p_created_by_agent_id is not null and 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;
+
+  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;
+
+  -- MBROWID (3a): prefer ACTIVE standing for joinability / idempotent-join. A bare
+  -- total-order can surface a high-id REMOVED row while a low-id JOINED row exists,
+  -- locking an active member out of their own private / invite_only board (P0002).
+  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
+     case when bm.membership_state in ('joined', 'subscribed') then 0 else 1 end,
+     bm.created_at desc,
+     bm.id desc
+   limit 1;
+
+  -- #82: the CREATOR EXEMPTION IS REMOVED. Previously a board's creator could join ANY agent
+  -- to their board -- `v_actor <> v_board.created_by_agent_id` let them past this guard, and
+  -- the joinability check below only runs for self-joins, so nothing else stopped them. That
+  -- is the force-join hole. Creating a board does not entitle you to place other people in it.
+  --
+  -- Only the subject may join the subject. service_role (v_actor null) keeps the operator
+  -- carve-out, which is deliberate and maintainer-confirmed.
+  if v_actor is not null and v_actor <> p_agent_id then
+    raise exception 'board membership actor mismatch' using errcode = '42501';
+  end if;
+
+  -- NULLFIX (CR): v_existing_state is NULL when the caller has NO membership row, and the original
+  -- guard then evaluated to NULL — `not (false or false or NULL)` is NULL, not TRUE — so `if NULL
+  -- then` never fired and ANY resolvable actor self-joined ANY board, private ones included. That
+  -- (not the null-actor bypass) was the true root cause of the live "joined a private invite_only
+  -- board with no invite" finding, and it is reachable by an ACTIVE agent, which the GATENULL guard
+  -- above cannot touch. coalesce() makes the absent-row case FALSE so the raise fires.
+  --
+  -- MBROWID (3b): a 'removed' agent is excluded from self-joining even an OPEN board via the
+  -- R-LINK-7 SET predicate (exists removed AND no active), not a single latest-row state.
+  -- Total-ordering the latest-row read alone is insufficient: a removed+left pair with equal
+  -- created_at can surface 'left' as the total-order winner while standing is still removed
+  -- (mutator + grant_board_role already use set-based rules). The three defenses must agree.
+  if v_actor is not null
+     and v_actor = p_agent_id
+     and v_board.created_by_agent_id <> v_actor
+     and not (
+       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 = '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')
+         )
+       )
+       and (
+         v_board.visibility = 'open'
+         -- #108: HOLDING AN INVITATION ADMITS THE SUBJECT ON ANY VISIBILITY, not only
+         -- invite_only. Previously `private` and `directory_hidden` were excluded outright, so
+         -- an invited subject had NO act available -- verified: a first-time invitee with no
+         -- prior refusal was blocked identically to a refused one. Gating makes consent
+         -- REQUIRED, so a board type where consent cannot be GIVEN is correct-but-unusable.
+         --
+         -- This is the narrowest widening that makes consent exercisable. It admits nobody new:
+         -- this whole guard is reached only when v_actor = p_agent_id (the actor-mismatch raise
+         -- above returns otherwise), so it is self-accept only. The board still decides who is
+         -- invited; the subject decides whether to accept.
+         or coalesce(v_existing_state, '') = 'invited'
+         or coalesce(v_existing_state, '') in ('joined', 'subscribed')
+       )
+     ) then
+    raise exception 'board is not joinable by this agent' using errcode = 'P0002';
+  end if;
+
+  v_membership := agent_board._upsert_board_membership_state(
+    p_board_id,
+    p_agent_id,
+    p_membership_state,
+    coalesce(p_created_by_agent_id, p_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;
+$$;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@consiliency/agent-board-schema",
-  "version": "1.22.0",
+  "version": "1.24.0",
   "description": "Canonical, immutable, exact-pinnable agent_board schema bundle: ordered SQL migrations, digest + compatibility manifest, and deterministic materialize/plan/check tooling for adopters.",
   "repository": "https://github.com/Consiliency/message-board.git",
   "type": "module",

package/schema-manifest.json

@@ -2,7 +2,7 @@
   "schema": "agent_board_schema_manifest.v1",
   "interface": "IF-0-MBPLANE-BUNDLE-1",
   "package": "@consiliency/agent-board-schema",
-  "packageVersion": "1.22.0",
+  "packageVersion": "1.24.0",
   "schemaVersion": 8,
   "minClientVersion": "1.1.0",
   "source": {
@@ -46,8 +46,8 @@
       "usage": "upsert (retention/monitoring defaults; on conflict do nothing)"
     }
   ],
-  "migrationCount": 113,
-  "aggregateSha256": "fb690d702458562b331aed192580f1568018d9d007368c8b9edd45d35d18ad96",
+  "migrationCount": 123,
+  "aggregateSha256": "f268991d3da80351c547d94249c48a5069a66267c3c1eaf580193bb47a89ff74",
   "migrations": [
     {
       "order": 0,
@@ -1065,6 +1065,96 @@
       "sourceRef": "message-board",
       "bytes": 25051,
       "sha256": "8d24ec4d682969a5d9339aec0573fad65ee95993dce2f8dca214906549b5ebe8"
+    },
+    {
+      "order": 113,
+      "id": "20260901000100_agent_board_atomic_fleet_onboarding",
+      "filename": "20260901000100_agent_board_atomic_fleet_onboarding.sql",
+      "origin": "message-board-forward",
+      "sourceRef": "message-board",
+      "bytes": 64896,
+      "sha256": "4cf07673b7c7da4ee13550e71d2bfe606b4b9c56971169e1ef61ac0d545ac6ef"
+    },
+    {
+      "order": 114,
+      "id": "20260901000110_agent_board_fleet_onboarding_ceiling_lock",
+      "filename": "20260901000110_agent_board_fleet_onboarding_ceiling_lock.sql",
+      "origin": "message-board-forward",
+      "sourceRef": "message-board",
+      "bytes": 30096,
+      "sha256": "310a32931562be6b4ad323b5e2926ebe459d6cd31bd6f601c7b862f354b5ce58"
+    },
+    {
+      "order": 115,
+      "id": "20260901000120_agent_board_human_revocation_evidence_completeness",
+      "filename": "20260901000120_agent_board_human_revocation_evidence_completeness.sql",
+      "origin": "message-board-forward",
+      "sourceRef": "message-board",
+      "bytes": 3077,
+      "sha256": "e8ccb3605fb6dfa4e8dfbefbbb4328179a61aec00616c1abef27d6a09c2a913e"
+    },
+    {
+      "order": 116,
+      "id": "20260901000130_agent_board_fedsession_human_revocation_gate",
+      "filename": "20260901000130_agent_board_fedsession_human_revocation_gate.sql",
+      "origin": "message-board-forward",
+      "sourceRef": "message-board",
+      "bytes": 2919,
+      "sha256": "f76d78973b87cc66c54ca0af4754358221ede19c8e0644df81a08e65dab0e89b"
+    },
+    {
+      "order": 117,
+      "id": "20260901000140_agent_board_fedsession_board_owner_lock_order",
+      "filename": "20260901000140_agent_board_fedsession_board_owner_lock_order.sql",
+      "origin": "message-board-forward",
+      "sourceRef": "message-board",
+      "bytes": 3824,
+      "sha256": "2388528532e974ab27c35337f9b00263056c1b16d973b7b3a0cf8cebb7724cc4"
+    },
+    {
+      "order": 118,
+      "id": "20260902000100_agent_board_outbox_wake_ordering",
+      "filename": "20260902000100_agent_board_outbox_wake_ordering.sql",
+      "origin": "message-board-forward",
+      "sourceRef": "message-board",
+      "bytes": 8783,
+      "sha256": "d3557acc29bf146862920fe903c3ac2e9e0e0317f3ca2134c5bb0835620fd2da"
+    },
+    {
+      "order": 119,
+      "id": "20260903000100_agent_board_enroll_identity_board_owner_lock_order",
+      "filename": "20260903000100_agent_board_enroll_identity_board_owner_lock_order.sql",
+      "origin": "message-board-forward",
+      "sourceRef": "message-board",
+      "bytes": 29382,
+      "sha256": "f8dc4ae6c5c6ea56183258402ab283cd424929b8e637984a59cf6ecd0685f681"
+    },
+    {
+      "order": 120,
+      "id": "20260903000200_agent_board_fedsession_provider_absence_gate",
+      "filename": "20260903000200_agent_board_fedsession_provider_absence_gate.sql",
+      "origin": "message-board-forward",
+      "sourceRef": "message-board",
+      "bytes": 8967,
+      "sha256": "79c581011be386d0efd97db723d3aa07947ad7b996667878ed1387cdd106b000"
+    },
+    {
+      "order": 121,
+      "id": "20260904000100_agent_board_wake_recovery_surface",
+      "filename": "20260904000100_agent_board_wake_recovery_surface.sql",
+      "origin": "message-board-forward",
+      "sourceRef": "message-board",
+      "bytes": 10795,
+      "sha256": "6349f705751104c5d60ec6602ea534e7c8b7de5c4c6ad2d84dbda680a5267848"
+    },
+    {
+      "order": 122,
+      "id": "20260905000100_agent_board_consent_gating_reconcile",
+      "filename": "20260905000100_agent_board_consent_gating_reconcile.sql",
+      "origin": "message-board-forward",
+      "sourceRef": "message-board",
+      "bytes": 8152,
+      "sha256": "d5328a0006ecd1ec940c4fde5bbb43acf29b0997eefbea557009f792868e298b"
     }
   ],
   "excludedBridge": {

package/src/check.js

@@ -9,8 +9,29 @@ export const EXIT = {
   ahead: 11,
   divergent: 12,
   error: 13,
+  // 14, not a reuse of `behind`: a collision previously reported as behind, and
+  // "behind" invites the fix of applying again -- which is exactly the no-op
+  // that leaves the database wrong. See message-board#217.
+  collision: 14,
 };
 
+// Operator guidance per posture. It lives HERE, next to the posture definition,
+// because the live-drift tool selected its message with a ternary over two named
+// postures and an else -- so a `collision` printed "the deployment has migrations
+// the bundle does not know about", which is the exact misdiagnosis this posture
+// exists to prevent. A completeness test over EXIT keeps a new posture from ever
+// again arriving without an action.
+export const POSTURE_ACTIONS = Object.freeze({
+  exact: null, // nothing to do
+  behind:
+    'migrations in the bundle are NOT applied to this deployment (or were applied without being recorded). Reconcile before assuming the board is current.',
+  ahead: 'the deployment has migrations the bundle does not know about.',
+  divergent:
+    'an applied migration digest does NOT match the bundle — the deployment ran different bytes. Investigate before applying anything further.',
+  collision:
+    'a bundle migration was SKIPPED because its version is already recorded under a different name. The deployment is missing that DDL while reporting the bundle\'s schema version. Do NOT simply re-apply: the version is taken, so applying again is a no-op. See the collisions list for the expected and recorded ids, and message-board#217.',
+});
+
 export function check(history) {
   const p = plan(history);
   return {
@@ -19,5 +40,7 @@ export function check(history) {
     exitCode: EXIT[p.posture] ?? EXIT.error,
     counts: p.counts,
     ahead: p.ahead,
+    collisions: p.collisions,
+    collisionsRemediated: p.collisionsRemediated,
   };
 }