@consiliency/agent-board-schema 1.12.0 → 1.23.0

package/migrations/20260901000130_agent_board_fedsession_human_revocation_gate.sql

@@ -0,0 +1,74 @@
+-- Consiliency/message-board#162 follow-up: /portal-session provisions through
+-- enroll_federated_human, so that route must share the durable human-revocation
+-- owner lock and marker gate with fleet enrollment.
+
+alter function agent_board.enroll_federated_human(text, text, text, jsonb, text)
+  rename to _enroll_federated_human_after_revocation_gate;
+
+revoke all on function agent_board._enroll_federated_human_after_revocation_gate(text, text, text, jsonb, text)
+  from public, anon, authenticated, service_role;
+comment on function agent_board._enroll_federated_human_after_revocation_gate(text, text, text, jsonb, text) is
+  'Internal federated-human provisioner. Call only through enroll_federated_human, which holds the deterministic auth.users owner lock and rejects durable issuer/subject revocation markers.';
+
+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_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;
+
+  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. Derives the deterministic owner, holds its auth.users row lock through commit, rejects durable issuer/subject revocation, then 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/20260901000140_agent_board_fedsession_board_owner_lock_order.sql

@@ -0,0 +1,102 @@
+-- Consiliency/message-board#162 follow-up: a federated-human provisioner may
+-- auto-join its provider's default board. Fleet onboarding takes board -> owner,
+-- so /portal-session must take the same order rather than owner -> board.
+
+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;
+  if v_provider_id is not null then
+    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;
+
+    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;
+  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. Locks a non-null default board before its provider row, freezes that designation, then 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/20260902000100_agent_board_outbox_wake_ordering.sql

@@ -0,0 +1,184 @@
+-- OUTBOXWAKE / #187 — monotonic wake ordering for the notification outbox.
+--
+-- THE DEFECT IS ALREADY LIVE, not hypothetical. `agent_board.callback_outbox_events`
+-- has no monotonic anchor: its only ordering columns are `id uuid default
+-- gen_random_uuid()` and `created_at`/`available_at timestamptz default now()`.
+-- `claim_callback_outbox_events` orders its candidate set by
+--   order by coe.available_at asc, coe.created_at asc, coe.id asc
+-- whose FINAL tiebreak is a random v4 uuid. And `now()` is `transaction_timestamp()`,
+-- constant within a transaction, so a multicast fan-out writes N rows with
+-- byte-identical `created_at`. Timestamp collision is the NORMAL path here, not the
+-- edge case, so which rows a bounded batch claims — and in what order a worker sees
+-- them — is decided by uuid randomness today.
+--
+-- This repo already met and solved this hazard once, on the consent substrate
+-- (`20260806000100_agent_board_consent_substrate.sql`), with `board_membership_events.seq`.
+-- That was, until now, the only identity column in the whole schema. The notification
+-- path never got the same treatment. This migration gives it one.
+--
+-- WHY `generated always` AND NOT `by default`:
+-- `seq` is EVIDENCE of write order, in the same sense that provenance is derived from
+-- the session and never from a caller argument. `generated always` makes the value
+-- un-suppliable: an INSERT that names `seq` is rejected by the server (SQLSTATE 428C9),
+-- so no writer — present or future — can assert an ordering it did not earn. Only an
+-- explicit `overriding system value` can bypass that, and the class assertion in
+-- `agent_board_outbox_wake_ordering.test.sql` fails, by name, on any function that uses it.
+--
+-- BACKFILL: none required. `callback_outbox_events` holds 0 rows in production
+-- (verified before writing this migration), so adding the identity column needs no
+-- decision about what order pre-existing rows "should" have had.
+--
+-- VISIBILITY IS NOT WIDENED. `seq` is exposed only on surfaces a consumer can already
+-- read: the table itself (RLS unchanged) and the service_role-only claim RPC, which
+-- already returns the row's contents. No view is created or altered.
+--
+-- WHAT THIS MIGRATION DOES NOT GIVE YOU — read this before building a consumer on `seq`:
+-- `seq` is monotonic in ASSIGNMENT order, NOT in COMMIT order. The sequence is
+-- non-transactional, so a transaction that inserts early and commits late holds a LOWER
+-- seq than rows a consumer has already seen and acknowledged. `seq > my persisted cursor`
+-- is therefore NOT a safe recovery predicate: it silently skips the late committer.
+-- Recovery must gate on transaction visibility or on row STATUS — never on `seq` alone.
+-- `claim_callback_outbox_events` is safe because it selects on `outbox_status`, not on a
+-- cursor. `agent-board-runtime/src/notifications.ts` (`shouldReplayMissedEvent`) does gate
+-- on `seq` today and is exposed to this; fixing it needs the wake contract and is tracked
+-- separately, NOT in this migration.
+--
+-- What this migration delivers, stated exactly: DETERMINISTIC CLAIM ORDERING over rows
+-- that share a timestamp, and a total order to build a gap-safe protocol on later.
+
+alter table agent_board.callback_outbox_events
+  add column if not exists seq bigint generated always as identity;
+
+comment on column agent_board.callback_outbox_events.seq is
+  'Monotonic write-order evidence for wake ordering (#187). GENERATED ALWAYS: not caller-suppliable. Gives same-timestamp rows a total order, which `created_at` cannot because now() is transaction_timestamp() and a fan-out shares it. CAUTION: monotonic in ASSIGNMENT order, NOT commit order -- a late-committing transaction holds a lower seq than rows already consumed, so `seq > cursor` is NOT a safe recovery predicate. Gate recovery on transaction visibility or on outbox_status, never on seq alone.';
+
+create unique index if not exists uq_agent_board_callback_outbox_events_seq
+  on agent_board.callback_outbox_events(seq);
+
+-- The consumer's access path is "rows for me newer than the cursor I persisted".
+create index if not exists idx_agent_board_callback_outbox_events_recipient_seq
+  on agent_board.callback_outbox_events(recipient_agent_id, seq);
+
+-- Claim ordering: `available_at` stays FIRST because it is scheduling (a row is not
+-- eligible before its time), and `seq` replaces the (created_at, id) pair because it is
+-- ordering. The uuid tiebreak is dropped entirely.
+--
+-- The returns table gains `outbox_seq` so a worker can observe and record the order it was
+-- handed rows in. It is NOT a lossless recovery cursor — see the caution above. That is a
+-- RETURN TYPE change, so the function must be dropped and recreated rather than replaced.
+--
+-- DROP FUNCTION DISCARDS THE ACL AND THE COMMENT. Recreating a SECURITY DEFINER function
+-- grants EXECUTE to PUBLIC by default. This repo shipped a real gate bypass by omitting
+-- exactly this restatement, so the revoke, the grant, and the comment are restated below
+-- in this SAME migration, and asserted by the test file.
+drop function if exists agent_board.claim_callback_outbox_events(integer);
+
+create function agent_board.claim_callback_outbox_events(
+  p_batch_size integer default 25
+)
+returns table(
+  outbox_event_id uuid,
+  endpoint_id uuid,
+  subscription_id uuid,
+  recipient_agent_id uuid,
+  inbox_item_id uuid,
+  board_id uuid,
+  endpoint_url text,
+  signing_key_version integer,
+  event_category text,
+  delivery_mode text,
+  source_kind text,
+  source_message_id uuid,
+  source_task_id uuid,
+  source_delegation_id uuid,
+  idempotency_key text,
+  subject text,
+  preview text,
+  priority text,
+  fetch_descriptor jsonb,
+  outbox_created_at timestamptz,
+  queued_at timestamptz,
+  claimed_at timestamptz,
+  attempt_number integer,
+  endpoint_status text,
+  subscription_status text,
+  metadata jsonb,
+  outbox_seq bigint
+)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+begin
+  if p_batch_size is null or p_batch_size < 1 or p_batch_size > 100 then
+    raise exception 'callback batch size must be between 1 and 100' using errcode = '22023';
+  end if;
+
+  return query
+  with candidates as (
+    select coe.id
+      from agent_board.callback_outbox_events coe
+      join agent_board.callback_endpoints ce on ce.id = coe.endpoint_id
+      join agent_board.callback_subscriptions cs on cs.id = coe.subscription_id
+     where coe.outbox_status in ('pending', 'retryable')
+       and coe.available_at <= now()
+       and ce.endpoint_status = 'verified'
+       and cs.subscription_status = 'active'
+     order by coe.available_at asc, coe.seq asc
+     for update of coe skip locked
+     limit p_batch_size
+  ),
+  updated as (
+    update agent_board.callback_outbox_events coe
+       set outbox_status = 'delivering',
+           locked_at = now(),
+           updated_at = now()
+      from candidates
+     where coe.id = candidates.id
+     returning coe.*
+  )
+  select
+    u.id,
+    u.endpoint_id,
+    u.subscription_id,
+    u.recipient_agent_id,
+    u.inbox_item_id,
+    u.board_id,
+    ce.endpoint_url,
+    ce.signing_key_version,
+    u.event_category,
+    u.delivery_mode,
+    u.source_kind,
+    u.source_message_id,
+    u.source_task_id,
+    u.source_delegation_id,
+    u.idempotency_key,
+    u.subject,
+    u.preview,
+    u.priority,
+    u.fetch_descriptor,
+    u.created_at,
+    u.available_at,
+    u.locked_at,
+    agent_board._next_callback_attempt_number(u.id),
+    ce.endpoint_status,
+    cs.subscription_status,
+    coalesce(u.metadata, '{}'::jsonb),
+    u.seq
+  from updated u
+  join agent_board.callback_endpoints ce on ce.id = u.endpoint_id
+  join agent_board.callback_subscriptions cs on cs.id = u.subscription_id
+  -- The batch is also RETURNED in wake order. Without this the claimed SET would be
+  -- deterministic while the order the worker observes it in stayed arbitrary, which is
+  -- the same defect one join away.
+  order by u.seq asc;
+end;
+$$;
+
+revoke all on function agent_board.claim_callback_outbox_events(integer)
+  from public, anon, authenticated;
+grant execute on function agent_board.claim_callback_outbox_events(integer)
+  to service_role;
+
+comment on function agent_board.claim_callback_outbox_events(integer) is
+  'Service-role notification worker claim: locks the ready outbox batch with SKIP LOCKED and marks it delivering. Ordered by (available_at, seq) — scheduling first, then monotonic write order (#187), so rows sharing a timestamp are claimed deterministically. Losslessness comes from selecting on outbox_status, NOT from seq: seq is monotonic in assignment order, not commit order, so `seq > cursor` is not a safe recovery predicate. Returns outbox_seq for observability and ordering, not as a recovery cursor.';