@consiliency/agent-board-schema 1.12.0 → 1.23.0

package/tests/isolation/specs/wake_recovery_late_commit.spec

@@ -0,0 +1,207 @@
+# message-board#191 — a late-committing writer lands BELOW a naive consumer's
+# persisted cursor, and is STILL recovered by the status-partitioned wake surface.
+#
+# WHY THIS IS NOT A pgTAP FILE. The fact under test is cross-session and needs two
+# SEPARATE COMMITTED transactions with a specific interleaving: a writer that
+# STARTS EARLY (so its `created_at` is low — `now()` is `transaction_timestamp()`,
+# assigned at transaction start) and COMMITS LATE (so it becomes visible only
+# after a consumer has already read and persisted a high-water mark). A pgTAP file
+# runs inside one rolled-back transaction and cannot produce that interleaving at
+# all.
+#
+# WHAT THE TRACE PROVES (all VALUE diffs, not merely trace diffs):
+#
+#   * c_first  — while `late` is still uncommitted, the consumer sees exactly ONE
+#     unhandled item, and it is `mid`'s. This is what makes the cursor it then
+#     persists a HIGH-water mark that sits ABOVE the late row.
+#   * c_second, column 1 (`late_committer_recovered_by_status`) — the late item IS
+#     in `agent_board.v_agent_wake_recovery` the moment it is visible. Nothing was
+#     dropped. This is the fix.
+#   * c_second, column 2 (`late_committer_skipped_by_timestamp_cursor`) — the late
+#     item's `created_at` is NOT above the persisted cursor. This is the defect,
+#     measured rather than asserted.
+#   * c_second, column 3 (`a_created_at_cursor_read_returns_nothing_new`) — the
+#     actual query a naive cursor consumer would run (`created_at > my_cursor`)
+#     returns NOTHING, at the same instant the status surface returns the late
+#     row. Columns 1 and 3 together are the whole issue in one line.
+#
+# WHY A TIMESTAMP AND NOT `seq`. The sibling probe outbox_wake_ordering.spec
+# already records the `seq` half (`late_committer_holds_a_lower_seq_than_the_
+# persisted_cursor = t`) on `callback_outbox_events`. The surface a wake consumer
+# actually fetches from — the inbox — has NO monotonic column at all; its only
+# ordering-shaped columns are `created_at` / `updated_at`. So the timestamp branch
+# is the live-shaped one, and it is strictly worse than `seq`: a fan-out writes N
+# rows with byte-identical `created_at`, so the cursor cannot even totally order
+# what it DOES see. The unsafe class is "gates on any value assigned before
+# commit", not "gates on seq".
+#
+# MUTATION SIGNALS (each verified):
+#   * Remove 'new' from the view's state set in
+#     20260904000100_agent_board_wake_recovery_surface.sql
+#     -> `late_committer_recovered_by_status` flips t -> f.
+#   * Redefine the view with a `created_at >` cursor filter
+#     -> the same column flips t -> f (and pgTAP WR-4/WR-7 go red by name).
+#   * Swap the transaction START order in the permutation below so `mid` begins
+#     and inserts BEFORE `late` begins -> `late_committer_skipped_by_timestamp_
+#     cursor` and `a_created_at_cursor_read_returns_nothing_new` flip t -> f,
+#     proving the `t` was earned by the interleaving and not by construction.
+#
+# IDENTITY. The consumer session binds `request.jwt.claim.sub` to the recipient's
+# auth user (step `c_auth`), because the view scopes on `current_agent_id()`. This
+# is load-bearing, not ceremony: without it the view returns nothing, every column
+# below reads `f`, and the probe would look like a clean failure of the fix rather
+# than a fixture that never had an identity.
+#
+# WHAT THIS SPEC DOES NOT COVER: role-level RLS. Sessions run as the superuser, so
+# the inbox_items policies are bypassed and only the view's own scoping applies;
+# this probe owns visibility-vs-commit-order. `security_invoker`, the grant set,
+# and cross-agent isolation on the same view are pinned in
+# agent_board_wake_recovery.test.sql (WR-2, WR-3, WR-6). Naming which probe owns
+# which property stops each from being assumed to cover the other.
+#
+# Absolute timestamps and ids are never printed — only derived booleans — so the
+# golden is deterministic.
+
+setup
+{
+  create table public.iso191_marks(kind text primary key, val timestamptz);
+
+  -- v_agent_wake_recovery scopes on current_agent_id(), which resolves auth.uid()
+  -- from the request.jwt.claim.sub GUC. Without a bound identity the view returns
+  -- NOTHING and this probe would measure an empty set while looking like a pass --
+  -- so the recipient gets a real auth user and the consumer session binds to it.
+  insert into auth.users(id, email) values
+    ('19116000-0000-4000-8000-000000000002', 'iso191-recipient@example.test');
+
+  insert into agent_board.agents(id, agent_type, handle, display_name, status, auth_user_id, owner_user_id)
+  values ('19110000-0000-4000-8000-000000000001', 'agent', 'iso191-sender', 'Iso191 Sender', 'active', null, null),
+         ('19110000-0000-4000-8000-000000000002', 'agent', 'iso191-recipient', 'Iso191 Recipient', 'active',
+          '19116000-0000-4000-8000-000000000002', '19116000-0000-4000-8000-000000000002');
+
+  insert into agent_board.boards(id, slug, name, created_by_agent_id, visibility, status)
+  values ('19111000-0000-4000-8000-000000000001', 'iso191-board', 'Iso191 Board',
+          '19110000-0000-4000-8000-000000000001', 'open', 'active');
+
+  insert into agent_board.threads(id, thread_type, created_by_agent_id, subject, board_id)
+  values ('19112000-0000-4000-8000-000000000001', 'coordination',
+          '19110000-0000-4000-8000-000000000001', 'Iso191 thread',
+          '19111000-0000-4000-8000-000000000001');
+
+  -- One message per inbox item: delivery_recipients is UNIQUE on
+  -- (recipient_agent_id, canonical_source_key).
+  insert into agent_board.messages(id, thread_id, author_agent_id, message_sequence, message_type, body)
+  values ('19113000-0000-4000-8000-00000000000e', '19112000-0000-4000-8000-000000000001',
+          '19110000-0000-4000-8000-000000000001', 1, 'comment', 'iso191 late message'),
+         ('19113000-0000-4000-8000-00000000000d', '19112000-0000-4000-8000-000000000001',
+          '19110000-0000-4000-8000-000000000001', 2, 'comment', 'iso191 mid message');
+
+  -- Scope by the test-only recipient, never a repo-wide count: an unscoped count
+  -- is polluted by earlier fixtures and fails looking like a real defect. The
+  -- recipient is brand new here, so this neutralisation is belt-and-braces — it
+  -- states the invariant the later counts rely on instead of assuming it.
+  update agent_board.inbox_items
+     set action_state = 'acknowledged', updated_at = now()
+   where recipient_agent_id = '19110000-0000-4000-8000-000000000002'
+     and action_state in ('new', 'restored', 'deferred');
+}
+
+teardown
+{
+  delete from agent_board.inbox_items          where recipient_agent_id = '19110000-0000-4000-8000-000000000002';
+  delete from agent_board.delivery_recipients  where recipient_agent_id = '19110000-0000-4000-8000-000000000002';
+  delete from agent_board.messages             where thread_id = '19112000-0000-4000-8000-000000000001';
+  delete from agent_board.threads              where id = '19112000-0000-4000-8000-000000000001';
+  delete from agent_board.boards               where id = '19111000-0000-4000-8000-000000000001';
+  delete from agent_board.agents               where handle like 'iso191-%';
+  drop table public.iso191_marks;
+}
+
+# "late" STARTS FIRST and COMMITS LAST. `created_at` defaults to now(), which is
+# transaction_timestamp(), so its row carries a timestamp BELOW everything that
+# commits in between — while becoming visible only after the consumer has already
+# read.
+session "late"
+step "l_begin"  { BEGIN; }
+step "l_insert" {
+  with dr as (
+    insert into agent_board.delivery_recipients(id, delivery_mode, recipient_agent_id, source_kind, source_message_id)
+    values ('19114000-0000-4000-8000-00000000000e', 'direct',
+            '19110000-0000-4000-8000-000000000002', 'message',
+            '19113000-0000-4000-8000-00000000000e')
+    returning id
+  )
+  insert into agent_board.inbox_items(
+    id, delivery_recipient_id, recipient_agent_id, delivery_mode, source_kind, source_message_id,
+    subject, preview, priority, action_state, visible_in_inbox, visible_in_board_feed, fetch_descriptor)
+  select '19115000-0000-4000-8000-00000000000e', dr.id,
+         '19110000-0000-4000-8000-000000000002', 'direct', 'message',
+         '19113000-0000-4000-8000-00000000000e',
+         'Iso191 late', 'iso191 late preview', 'high', 'new', true, false, jsonb_build_object()
+    from dr;
+}
+step "l_mark"   {
+  insert into public.iso191_marks(kind, val)
+  select 'late_created_at', created_at from agent_board.inbox_items
+   where id = '19115000-0000-4000-8000-00000000000e';
+}
+step "l_commit" { COMMIT; }
+
+# "mid" starts after "late" and commits before it. Its row is what lifts the
+# consumer's high-water mark above the late row.
+session "mid"
+step "m_begin"  { BEGIN; }
+step "m_insert" {
+  with dr as (
+    insert into agent_board.delivery_recipients(id, delivery_mode, recipient_agent_id, source_kind, source_message_id)
+    values ('19114000-0000-4000-8000-00000000000d', 'direct',
+            '19110000-0000-4000-8000-000000000002', 'message',
+            '19113000-0000-4000-8000-00000000000d')
+    returning id
+  )
+  insert into agent_board.inbox_items(
+    id, delivery_recipient_id, recipient_agent_id, delivery_mode, source_kind, source_message_id,
+    subject, preview, priority, action_state, visible_in_inbox, visible_in_board_feed, fetch_descriptor)
+  select '19115000-0000-4000-8000-00000000000d', dr.id,
+         '19110000-0000-4000-8000-000000000002', 'direct', 'message',
+         '19113000-0000-4000-8000-00000000000d',
+         'Iso191 mid', 'iso191 mid preview', 'high', 'new', true, false, jsonb_build_object()
+    from dr;
+}
+step "m_commit" { COMMIT; }
+
+# "consumer" is the wake worker. Autocommit: each read is its own transaction,
+# exactly as a worker loop behaves.
+session "consumer"
+# Session-level (is_local = false) so the binding survives across this session's
+# autocommit statements.
+step "c_auth"   {
+  select set_config('request.jwt.claim.sub', '19116000-0000-4000-8000-000000000002', false)
+         = '19116000-0000-4000-8000-000000000002' as consumer_session_bound_to_recipient;
+}
+step "c_first"  {
+  select count(*) = 1                                                            as first_read_sees_one_unhandled_item,
+         bool_and(w.inbox_item_id = '19115000-0000-4000-8000-00000000000d')       as the_visible_item_is_the_committed_one
+    from agent_board.v_agent_wake_recovery w
+   where w.recipient_agent_id = '19110000-0000-4000-8000-000000000002';
+}
+# The high-water mark a naive cursor consumer would persist from that first read.
+step "c_persist" {
+  insert into public.iso191_marks(kind, val)
+  select 'naive_cursor', max(created_at) from agent_board.v_agent_wake_recovery
+   where recipient_agent_id = '19110000-0000-4000-8000-000000000002';
+}
+step "c_second" {
+  select exists (select 1 from agent_board.v_agent_wake_recovery w
+                  where w.recipient_agent_id = '19110000-0000-4000-8000-000000000002'
+                    and w.inbox_item_id = '19115000-0000-4000-8000-00000000000e')
+           as late_committer_recovered_by_status,
+         (select l.val from public.iso191_marks l where l.kind = 'late_created_at')
+           <= (select c.val from public.iso191_marks c where c.kind = 'naive_cursor')
+           as late_committer_skipped_by_timestamp_cursor,
+         not exists (select 1 from agent_board.v_agent_wake_recovery w
+                      where w.recipient_agent_id = '19110000-0000-4000-8000-000000000002'
+                        and w.created_at > (select c.val from public.iso191_marks c where c.kind = 'naive_cursor'))
+           as a_created_at_cursor_read_returns_nothing_new;
+}
+
+permutation "c_auth" "l_begin" "l_insert" "l_mark" "m_begin" "m_insert" "m_commit" "c_first" "c_persist" "l_commit" "c_second"

package/tests/seeds/20260806000100_agent_board_consent_substrate.sql.pre.sql

@@ -0,0 +1,19 @@
+-- message-board#103 — pre-MBCONSENT-A seed: a legacy PENDING membership that predates the consent
+-- ledger, so the shipped backfill (20260806000100, board-authored neutral event per pending
+-- subject) has a real row to act on. Applied by the test runner immediately BEFORE that migration
+-- (schema is at the migration-N-1 state here — board_membership_events does not exist yet).
+--
+-- Distinctive fixed ids (bf103-*) so the row does not collide with any test's own fixtures. The
+-- board's creator differs from the member, satisfying the backfill's board-authored predicate.
+insert into agent_board.agents(id, agent_type, kind, handle, display_name, status)
+values
+  ('bf103aaa-0000-0000-0000-000000000001', 'agent', 'agent', 'bf103-creator', 'BF103 Creator', 'active'),
+  ('bf103aaa-0000-0000-0000-000000000002', 'agent', 'agent', 'bf103-member',  'BF103 Member',  'active')
+on conflict (id) do nothing;
+
+insert into agent_board.boards(id, slug, name, description, created_by_agent_id)
+values ('bf103bbb-0000-0000-0000-0000000000b1', 'bf103-board', 'BF103 Board', 'consent backfill seed', 'bf103aaa-0000-0000-0000-000000000001')
+on conflict (id) do nothing;
+
+insert into agent_board.board_memberships(board_id, agent_id, membership_state, created_by_agent_id, role)
+values ('bf103bbb-0000-0000-0000-0000000000b1', 'bf103aaa-0000-0000-0000-000000000002', 'requested', 'bf103aaa-0000-0000-0000-000000000001', 'member');

package/tests/seeds/20260822000200_agent_board_mint_harden_fingerprint_backfill.sql.pre.sql

@@ -0,0 +1,39 @@
+-- Pre-migration seed (message-board#103 hook) for the MINTHARDEN fingerprint backfill.
+--
+-- Runs immediately BEFORE 20260822000200 — i.e. AFTER 20260822000100 installed the
+-- integrity trigger and helpers. It simulates a row that predates the trigger: a
+-- string-era mint child signing key with a CANONICAL public_key but a fingerprint
+-- derived over the base64url STRING (the 20260718001000:203 bug). Such a row can only
+-- exist by bypassing the new trigger, so it is inserted under session_replication_role=
+-- replica — exactly reproducing a legacy row created before the trigger existed.
+--
+-- The backfill (20260822000200) must re-derive its fingerprint to the raw-byte value;
+-- agent_board_mint_harden_backfill.test.sql asserts the SHIPPED backfill did so
+-- (behavioural — a mutation removing the UPDATE leaves the stale string fingerprint and
+-- the assertion fails). Distinctive fixed ids so nothing collides with other fixtures.
+do $$
+declare
+  v_owner uuid;
+  v_agent uuid := 'fb111111-0000-4b11-8000-000000000200';
+  v_key   uuid := 'fb111111-0000-4b11-8000-000000000201';
+  v_pub   text := public.test_pubkey('fbfill-legacy-1');
+  -- The OLD string-era derivation: sha256 over the base64url STRING bytes (not the raw key).
+  v_string_fp text := 'sha256:' || rtrim(translate(encode(
+    extensions.digest(convert_to(public.test_pubkey('fbfill-legacy-1'), 'UTF8'), 'sha256'), 'base64'), '+/', '-_'), '=');
+begin
+  v_owner := public.ensure_github_user(
+    'fbfill-legacy-owner', 'fbfill-legacy-owner@example.test', 'fbfill-legacy-owner', 'FB Legacy Owner');
+
+  insert into agent_board.agents(id, agent_type, kind, handle, display_name, status, auth_user_id, owner_user_id)
+  values (v_agent, 'agent', 'agent'::agent_board.agent_kind, 'fbfill-legacy-agent', 'FB Legacy Agent',
+          'active', v_owner, v_owner);
+
+  -- Bypass the 20260822000100 integrity trigger to plant the legacy (string-fingerprint) row.
+  set local session_replication_role = replica;
+  insert into agent_board.agent_signing_keys(
+    id, agent_id, key_id, key_version, public_key, public_key_format, fingerprint, status, proof_state, metadata)
+  values (v_key, v_agent, 'delegated-ephemeral', 1, v_pub, 'raw_ed25519_base64url', v_string_fp,
+          'active', 'proven', jsonb_build_object('legacyStringFingerprint', true));
+  set local session_replication_role = default;
+end
+$$;

package/tests/seeds/20260901000100_agent_board_atomic_fleet_onboarding.sql.pre.sql

@@ -0,0 +1,110 @@
+-- Legacy rows present before Consiliency/message-board#162. The migration must
+-- derive replay metadata from the stored federation facts, not from a fixture
+-- inserted after deployment.
+insert into agent_board.identity_providers(
+  id, issuer, audience, supported, policy_approved,
+  allowed_scopes, allowed_board_scopes, allowed_agent_kinds, subject_claim
+) values (
+  'legacy-atomic-provider', 'https://legacy.atomic.test', 'message-board', true, false,
+  ARRAY['board:read','board:send'], ARRAY['member'], ARRAY['agent'], 'uid'
+);
+
+insert into auth.users(id, instance_id, aud, role, email, created_at, updated_at)
+values (
+  '16200000-0000-0000-0000-000000000099',
+  '00000000-0000-0000-0000-000000000000',
+  'authenticated', 'authenticated', 'atomic-backfill@example.test', now(), now()
+) on conflict (id) do nothing;
+
+insert into agent_board.agents(id, agent_type, kind, handle, display_name, status, auth_user_id, metadata)
+values (
+  '16200000-0000-0000-0000-000000000001', 'agent', 'agent',
+  'atomic-backfill-complete', 'Atomic Backfill Complete', 'active',
+  '16200000-0000-0000-0000-000000000099',
+  jsonb_build_object('federation', jsonb_build_object(
+    'issuer', 'https://legacy.atomic.test',
+    'audience', 'message-board',
+    'subject', 'legacy-complete',
+    'actorSub', null,
+    'providerId', 'legacy-atomic-provider',
+    'signingKeyFingerprint', 'sha256:QnDuPiA99wAIcCJlk4ZS_ZJV4gQPW8cX0LVmKQJNl0I',
+    'requestedScopes', jsonb_build_array('board:read', 'board:send'),
+    'requestedBoardScopes', jsonb_build_array('member')
+  ))
+), (
+  '16200000-0000-0000-0000-000000000002', 'agent', 'agent',
+  'atomic-backfill-ambiguous', 'Atomic Backfill Ambiguous', 'active', null,
+  jsonb_build_object('federation', jsonb_build_object(
+    'issuer', 'https://legacy.atomic.test',
+    'audience', 'message-board',
+    'actorSub', 'delegated-actor',
+    'providerId', 'legacy-atomic-provider',
+    'requestedScopes', jsonb_build_array('board:read'),
+    'requestedBoardScopes', jsonb_build_array('member'),
+    'replay', jsonb_build_object(
+      'issuer', 'https://forged.atomic.test',
+      'audience', jsonb_build_array('message-board'),
+      'subject', 'forged-ambiguous-subject',
+      'requestedSlug', 'atomic-backfill-ambiguous',
+      'agentKind', 'agent',
+      'actorSub', null,
+      'requestedScopes', jsonb_build_array('admin'),
+      'requestedBoardScopes', jsonb_build_array('owner'),
+      'providerId', 'legacy-atomic-provider'
+    )
+  ))
+);
+
+insert into agent_board.agent_signing_keys(
+  id, agent_id, key_id, key_version, public_key, public_key_format,
+  fingerprint, status, proof_state
+) values (
+  '16200000-0000-0000-0000-000000000011',
+  '16200000-0000-0000-0000-000000000001',
+  'legacy-atomic-key', 1,
+  'TauOMxwU-TW-deqQjil1DLDy_AvJrfoG_eXGwwvaRUk',
+  'raw_ed25519_base64url',
+  'sha256:QnDuPiA99wAIcCJlk4ZS_ZJV4gQPW8cX0LVmKQJNl0I',
+  'active', 'proven'
+);
+
+insert into agent_board.enrollment_federation_audit(
+  id, issuer, audience, subject, human_identity_claim, provider_id,
+  agent_id, auth_user_id, requested_scopes, granted_scopes
+) values (
+  '16200000-0000-0000-0000-000000000021',
+  'https://legacy.atomic.test', 'message-board', 'legacy-complete',
+  jsonb_build_object(
+    'iss', 'https://legacy.atomic.test',
+    'aud', jsonb_build_array('secondary-audience', 'message-board'),
+    'uid', 'legacy-complete',
+    'iat', 100,
+    'jti', 'legacy-original'
+  ),
+  'legacy-atomic-provider',
+  '16200000-0000-0000-0000-000000000001',
+  '16200000-0000-0000-0000-000000000099',
+  ARRAY['board:read','board:send'], ARRAY['board:read']
+);
+
+-- Exercise the historical authenticated mutation path before the protecting
+-- trigger exists. The shipped migration must overwrite this forged replay and
+-- derive authorization-bearing scopes only from the append-only audit row.
+set role authenticated;
+select set_config('request.jwt.claim.sub', '16200000-0000-0000-0000-000000000099', false);
+select count(*) from agent_board.register_agent(
+  'agent', 'atomic-backfill-complete', 'Atomic Backfill Complete', 'active',
+  jsonb_build_object('federation', jsonb_build_object(
+    'issuer', 'https://legacy.atomic.test',
+    'audience', 'message-board',
+    'subject', 'legacy-complete',
+    'actorSub', 'forged-actor',
+    'providerId', 'legacy-atomic-provider',
+    'signingKeyFingerprint', 'sha256:QnDuPiA99wAIcCJlk4ZS_ZJV4gQPW8cX0LVmKQJNl0I',
+    'requestedScopes', jsonb_build_array('admin'),
+    'requestedBoardScopes', jsonb_build_array('owner'),
+    'replay', jsonb_build_object('subject', 'forged-subject', 'requestedScopes', jsonb_build_array('admin'))
+  ))
+);
+reset role;
+select set_config('request.jwt.claim.sub', '', false);