@consiliency/agent-board-schema 1.12.0 → 1.23.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@consiliency/agent-board-schema",
-  "version": "1.12.0",
+  "version": "1.23.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",