@consiliency/agent-board-schema 1.22.0 → 1.24.0

package/tests/isolation/specs/onboarding_ceiling_lock_order.spec

@@ -0,0 +1,183 @@
+# Consiliency/message-board#196 — onboard_federated_fleet_agent must take the
+# board-keyed ceiling ADVISORY lock BEFORE it locks the boards row.
+#
+# WHAT THIS PINS AND WHY IT IS NOT COVERED ELSEWHERE. This is the #189 ABBA edge:
+# set_board_authority_ceiling goes advisory -> boards (its upsert reaches the
+# boards row as FOR KEY SHARE through board_authority_ceilings' FK), so onboarding
+# must agree. The first cut of 20260901000110 had them inverted and deadlocked
+# deterministically. atomic_fleet_authority_races.spec CANNOT see this -- its own
+# header says so: every permutation there runs each RPC to completion in ONE step,
+# so neither transaction can be paused between its two acquisitions and no cycle
+# can form. That spec passed while the deadlock was live.
+#
+# Until #196 the only guard was a positional pgTAP assertion over RAW function
+# text, which one `--` comment naming the marker defeats. Measured against all 20
+# committed specs, an inverted onboarding (advisory taken after the boards lock)
+# moved NOTHING.
+#
+# HOW THE ORDER IS OBSERVED. A guard session holds the ceiling advisory lock, so
+# onboarding blocks -- `<waiting ...>`. A third session then probes the BOARDS row
+# with `for update nowait`:
+#   * CORRECT ORDER: onboarding is parked on the advisory lock and has not reached
+#     `select * into v_board ... for update`, so the probe returns the board;
+#   * INVERTED ORDER: onboarding already holds the boards row, so the probe fails
+#     with `ERROR: could not obtain lock on row in relation "boards"`.
+# The probe never joins the wait graph, so this terminates in BOTH orders instead
+# of reproducing the deadlock it is guarding against.
+#
+# SCOPE. This pins the advisory-before-boards edge ONLY. The boards-lock-before-
+# ceiling-read edge (the FOR KEY SHARE mechanism 20260901000110's header calls the
+# load-bearing one) is pinned elsewhere, and not by this spec -- a mutant that moves
+# only that lock leaves this golden byte-identical. What does catch it, measured:
+#   * agent_board_federated_lock_order_class.test.sql EC-3 fails BY NAME, and it
+#     already reads a stripped body, so a comment or literal mask does not hide it;
+#   * atomic_fleet_authority_races.spec pins the OUTCOME only for the state where
+#     BOTH serializers are gone -- its own header records that removing the boards
+#     FOR UPDATE alone still passes, because the advisory lock takes over;
+#   * atomic_fleet_board_archive.spec BLOCKS on that mutant rather than failing by
+#     name, which under the isolation runner (no timeout around isolationtester) is
+#     a stuck job, not a diagnosis.
+#
+# MUTATION-VERIFIED: `perform agent_board._lock_board_authority_ceiling(v_inv.board_id)`
+# moved below the boards lock -> this golden changes. Clean schema -> byte-identical
+# across 10 runs.
+
+setup
+{
+  insert into auth.users (id) values ('19610000-0000-0000-0000-0000000000a1');
+  insert into agent_board.agents(id, agent_type, kind, handle, display_name, status, auth_user_id)
+  values ('19610000-0000-0000-0000-000000000001', 'agent', 'agent',
+          'onboard-ceiling-owner', 'Onboard Ceiling Owner', 'active',
+          '19610000-0000-0000-0000-0000000000a1');
+
+  select count(*) from agent_board.create_board(
+    '19610000-0000-0000-0000-000000000001',
+    'onboard-ceiling-board', 'Onboard Ceiling Board',
+    'Consiliency/message-board#196 onboarding ceiling lock-order probe',
+    jsonb_build_object(), 'private'
+  );
+  insert into agent_board.fleet_trust_domains(
+    id, slug, display_name, domain_kind, owner_agent_id, lifecycle_state, approved_at
+  ) values (
+    '19610000-0000-0000-0000-000000000002', 'onboard-ceiling-domain',
+    'Onboard Ceiling Domain', 'tailnet', '19610000-0000-0000-0000-000000000001',
+    'active', now()
+  );
+  insert into agent_board.fleet_machines(
+    id, trust_domain_id, owner_agent_id, machine_label, machine_fingerprint,
+    lifecycle_state, enrollment_source, enrolled_at
+  ) values (
+    '19610000-0000-0000-0000-000000000003',
+    '19610000-0000-0000-0000-000000000002',
+    '19610000-0000-0000-0000-000000000001',
+    'claw', 'sha256:onboard-ceiling-machine', 'active', 'portal', now()
+  );
+  insert into agent_board.identity_providers(
+    issuer, audience, supported, policy_approved,
+    allowed_scopes, allowed_board_scopes, allowed_agent_kinds
+  ) values (
+    'https://onboard-ceiling.test', 'message-board', true, true,
+    ARRAY['board:send'], ARRAY[]::text[], ARRAY['agent']
+  );
+  select count(*) from agent_board.create_fleet_onboarding_invite(
+    (select id from agent_board.boards where slug='onboard-ceiling-board'),
+    '19610000-0000-0000-0000-000000000003', 'codex', 'phase-loop',
+    'message-board', 'sha256:onboard-ceiling-repo', 'worker', 'phase_worker',
+    'onboard-ceiling-agent', 1, now() + interval '1 hour',
+    '19610000-0000-0000-0000-000000000001', jsonb_build_object()
+  );
+}
+
+teardown
+{
+  delete from agent_board.fleet_machine_agents where machine_id='19610000-0000-0000-0000-000000000003';
+  delete from agent_board.fleet_repo_scopes where harness_registration_id in (
+    select id from agent_board.fleet_harness_registrations where machine_id='19610000-0000-0000-0000-000000000003'
+  );
+  delete from agent_board.fleet_harness_registrations where machine_id='19610000-0000-0000-0000-000000000003';
+  delete from agent_board.board_invite_redemptions where invite_id in (
+    select id from agent_board.board_invite_tokens where created_by_agent_id='19610000-0000-0000-0000-000000000001'
+  );
+  truncate agent_board.fleet_onboarding_invite_bounds;
+  delete from agent_board.board_invite_tokens where created_by_agent_id='19610000-0000-0000-0000-000000000001';
+  delete from agent_board.board_authority_ceilings where board_id in (
+    select id from agent_board.boards where slug='onboard-ceiling-board'
+  );
+  delete from agent_board.board_memberships where board_id in (
+    select id from agent_board.boards where slug='onboard-ceiling-board'
+  );
+  delete from agent_board.enrollment_federation_audit where agent_id in (
+    select id from agent_board.agents where handle='onboard-ceiling-agent'
+  );
+  delete from agent_board.agent_signing_keys where agent_id in (
+    select id from agent_board.agents where handle='onboard-ceiling-agent'
+  );
+  delete from agent_board.agents where handle='onboard-ceiling-agent';
+  delete from agent_board.boards where slug='onboard-ceiling-board';
+  delete from agent_board.fleet_machines where id='19610000-0000-0000-0000-000000000003';
+  delete from agent_board.fleet_trust_domains where id='19610000-0000-0000-0000-000000000002';
+  delete from agent_board.agents where id='19610000-0000-0000-0000-000000000001';
+  delete from auth.users where id='19610000-0000-0000-0000-0000000000a1';
+  delete from agent_board.identity_providers where issuer='https://onboard-ceiling.test';
+}
+
+# Holds the SAME board-keyed advisory lock onboarding must take first. It calls the
+# helper rather than re-deriving the key, so a key-derivation change cannot silently
+# make this guard lock a different object.
+session "holder"
+step "holder_begin" { BEGIN; }
+step "hold_ceiling_lock" {
+  select agent_board._lock_board_authority_ceiling(
+    (select id from agent_board.boards where slug='onboard-ceiling-board')) as locked;
+}
+step "holder_commit" { COMMIT; }
+
+session "onboard"
+step "onboard_begin" { BEGIN; SET LOCAL "request.jwt.claim.role" = 'service_role'; }
+step "onboard_call" {
+  select identity_disposition, membership_disposition, binding_disposition
+  from agent_board.onboard_federated_fleet_agent(
+    'https://onboard-ceiling.test', 'message-board', 'human-onboard-ceiling',
+    jsonb_build_object('iss','https://onboard-ceiling.test','aud','message-board','sub','human-onboard-ceiling'),
+    'onboard-ceiling-agent',
+    'yd_DIFGWGusVg3SbktDJQ1bE5UWvtR33xln4b05JIhk',
+    'raw_ed25519_base64url',
+    'sha256:NeVC2vx1MbTY56jUwJcLLr6YwB4IKCERsXWbUwhf5pA',
+    true, null, 'agent', ARRAY['board:send'], ARRAY[]::text[],
+    (select code from agent_board.board_invite_tokens where created_by_agent_id='19610000-0000-0000-0000-000000000001'),
+    (select id from agent_board.boards where slug='onboard-ceiling-board'),
+    '19610000-0000-0000-0000-000000000003', 'codex', 'phase-loop',
+    'message-board', 'sha256:onboard-ceiling-repo', 'worker', 'phase_worker',
+    'onboard-ceiling-agent'
+  );
+}
+step "onboard_commit" { COMMIT; }
+
+# NOWAIT probe: witnesses whether the blocked onboarding already holds the boards
+# row. Never blocks, so the permutation terminates in both orders.
+session "probe"
+step "probe_begin" { BEGIN; }
+step "probe_boards_row" {
+  select status from agent_board.boards
+   where id = (select id from agent_board.boards where slug='onboard-ceiling-board')
+   for update nowait;
+}
+step "probe_commit" { COMMIT; }
+
+session "check"
+step "check" {
+  select
+    (select count(*) from agent_board.agents where handle='onboard-ceiling-agent') as onboarded_agents,
+    (select count(*) from agent_board.board_memberships bm
+      where bm.board_id=(select id from agent_board.boards where slug='onboard-ceiling-board')
+        and bm.agent_id in (select id from agent_board.agents where handle='onboard-ceiling-agent')) as memberships;
+}
+
+# THE ORDERING PROBE. Onboarding is parked on the advisory lock; the boards row
+# must still be free.
+permutation "holder_begin" "hold_ceiling_lock" "onboard_begin" "onboard_call" "probe_begin" "probe_boards_row" "probe_commit" "holder_commit" "onboard_commit" "check"
+
+# Uncontended control: with nobody holding the advisory lock onboarding completes
+# in one step, so a `<waiting ...>` above is attributable to the advisory lock and
+# not to some unrelated serialization.
+permutation "onboard_begin" "onboard_call" "onboard_commit" "probe_begin" "probe_boards_row" "probe_commit" "check"

package/tests/isolation/specs/outbox_wake_ordering.spec

@@ -0,0 +1,202 @@
+# message-board#187 — the notification outbox has a monotonic write order (`seq`),
+# and the claim RPC uses it instead of a random uuid.
+#
+# WHY THIS IS NOT A pgTAP FILE. Two facts here need SEPARATE COMMITTED SESSIONS and
+# cannot be produced inside one rolled-back transaction:
+#
+#   1. `seq` comes from a NON-TRANSACTIONAL sequence, so a transaction that commits
+#      LATER can hold a LOWER seq than one that already committed. That is only
+#      observable when two sessions overlap.
+#   2. What a bounded claim TAKES, when several rows share `created_at`, is a
+#      cross-session fact about a committed queue — the defect this issue fixes.
+#
+# WHAT THE TRACE PROVES (all four are VALUE diffs, not just trace diffs):
+#
+#   * f_report — a fan-out to 8 subscribers, one statement, one transaction, writes 8
+#     rows with ONE distinct `created_at` and 8 distinct, CONTIGUOUS `seq`. `now()` is
+#     `transaction_timestamp()`, so time cannot order this set; `seq` can.
+#   * c_first — a claim of 4 takes exactly `fan_base .. fan_base+3`, IN THAT ORDER.
+#     Under the old `available_at, created_at, id` ordering the tiebreak was a random
+#     v4 uuid, so both the set (1 in 70) and the order (1 in 24) were chance.
+#   * c_second — after the late session commits, the next claim returns its row FIRST,
+#     because its `seq` was allocated BEFORE the fan-out's even though it committed
+#     after.
+#   * The same c_second line records the CONSEQUENCE for a consumer design: a
+#     late-committing writer lands BELOW the high-water mark a naive `seq`-cursor
+#     consumer would already have persisted. The claim RPC is unaffected — it is
+#     status-driven, not cursor-driven — but the wake contract this issue unblocks
+#     must not assume "seq greater than my cursor" is sufficient on its own.
+#
+# MUTATION SIGNAL: restore `order by coe.available_at asc, coe.created_at asc,
+# coe.id asc` in claim_callback_outbox_events and both c_first and c_second flip from
+# `t` to `f` (verified). Note what this spec does NOT pin: deleting `order by u.seq asc`
+# from the RETURNED batch changes nothing here, because the plan feeds the ordered
+# candidate CTE straight through and the observed order stays ascending anyway. That
+# property is pinned as a source assertion in agent_board_outbox_wake_ordering.test.sql
+# (WO-4 "RETURNED ordered by seq"), which is where the mutation actually lands.
+
+setup
+{
+  create table public.iso187_marks(kind text primary key, val bigint);
+
+  insert into agent_board.agents(id, agent_type, handle, display_name, status)
+  values ('18700000-0000-4000-8000-000000000000', 'agent', 'iso187-sender', 'Iso187 Sender', 'active');
+  insert into agent_board.agents(id, agent_type, handle, display_name, status)
+  select ('18700000-0000-4000-8000-' || lpad(n::text, 12, '0'))::uuid,
+         'agent', 'iso187-sub-' || n, 'Iso187 Subscriber ' || n, 'active'
+    from generate_series(1, 8) n;
+
+  insert into agent_board.boards(id, slug, name, created_by_agent_id, visibility, status)
+  values ('18701000-0000-4000-8000-00000000000a', 'iso187-board-a', 'Iso187 Board A',
+          '18700000-0000-4000-8000-000000000000', 'open', 'active'),
+         ('18701000-0000-4000-8000-00000000000b', 'iso187-board-b', 'Iso187 Board B',
+          '18700000-0000-4000-8000-000000000000', 'open', 'active');
+
+  insert into agent_board.threads(id, thread_type, created_by_agent_id, subject, board_id)
+  values ('18702000-0000-4000-8000-00000000000a', 'coordination',
+          '18700000-0000-4000-8000-000000000000', 'Iso187 thread A',
+          '18701000-0000-4000-8000-00000000000a'),
+         ('18702000-0000-4000-8000-00000000000b', 'coordination',
+          '18700000-0000-4000-8000-000000000000', 'Iso187 thread B',
+          '18701000-0000-4000-8000-00000000000b');
+
+  insert into agent_board.messages(id, thread_id, author_agent_id, message_sequence, message_type, body)
+  values ('18703000-0000-4000-8000-00000000000a', '18702000-0000-4000-8000-00000000000a',
+          '18700000-0000-4000-8000-000000000000', 1, 'comment', 'iso187 board A post'),
+         ('18703000-0000-4000-8000-00000000000b', '18702000-0000-4000-8000-00000000000b',
+          '18700000-0000-4000-8000-000000000000', 1, 'comment', 'iso187 board B post');
+
+  insert into agent_board.board_memberships(id, board_id, agent_id, role, membership_state, created_by_agent_id)
+  select ('18704000-0000-4000-8000-' || lpad(n::text, 12, '0'))::uuid,
+         '18701000-0000-4000-8000-00000000000a',
+         ('18700000-0000-4000-8000-' || lpad(n::text, 12, '0'))::uuid,
+         'member', 'joined', '18700000-0000-4000-8000-000000000000'
+    from generate_series(1, 8) n;
+  insert into agent_board.board_memberships(id, board_id, agent_id, role, membership_state, created_by_agent_id)
+  values ('18704000-0000-4000-8000-0000000000b1', '18701000-0000-4000-8000-00000000000b',
+          '18700000-0000-4000-8000-000000000001', 'member', 'joined',
+          '18700000-0000-4000-8000-000000000000');
+
+  insert into agent_board.callback_endpoints(id, owner_agent_id, endpoint_url, endpoint_status, verification_requested_at, verified_at)
+  select ('18705000-0000-4000-8000-' || lpad(n::text, 12, '0'))::uuid,
+         ('18700000-0000-4000-8000-' || lpad(n::text, 12, '0'))::uuid,
+         'https://example.test/iso187/' || n, 'verified', now(), now()
+    from generate_series(1, 8) n;
+
+  insert into agent_board.callback_subscriptions(
+    id, endpoint_id, agent_id, subscription_scope, event_category,
+    board_id, board_membership_id, subscription_status)
+  select ('18706000-0000-4000-8000-' || lpad(n::text, 12, '0'))::uuid,
+         ('18705000-0000-4000-8000-' || lpad(n::text, 12, '0'))::uuid,
+         ('18700000-0000-4000-8000-' || lpad(n::text, 12, '0'))::uuid,
+         'board', 'board.post.delivered',
+         '18701000-0000-4000-8000-00000000000a',
+         ('18704000-0000-4000-8000-' || lpad(n::text, 12, '0'))::uuid,
+         'active'
+    from generate_series(1, 8) n;
+  insert into agent_board.callback_subscriptions(
+    id, endpoint_id, agent_id, subscription_scope, event_category,
+    board_id, board_membership_id, subscription_status)
+  values ('18706000-0000-4000-8000-0000000000b1', '18705000-0000-4000-8000-000000000001',
+          '18700000-0000-4000-8000-000000000001', 'board', 'board.post.delivered',
+          '18701000-0000-4000-8000-00000000000b',
+          '18704000-0000-4000-8000-0000000000b1', 'active');
+
+  -- claim_callback_outbox_events polls the GLOBAL ready queue. Neutralize anything the
+  -- template left ready so this spec controls what a bounded claim can take.
+  update agent_board.callback_outbox_events
+     set outbox_status = 'delivered', delivered_at = now(), updated_at = now()
+   where outbox_status in ('pending', 'retryable');
+}
+
+teardown
+{
+  delete from agent_board.callback_outbox_events where board_id in ('18701000-0000-4000-8000-00000000000a', '18701000-0000-4000-8000-00000000000b');
+  delete from agent_board.callback_subscriptions  where board_id in ('18701000-0000-4000-8000-00000000000a', '18701000-0000-4000-8000-00000000000b');
+  delete from agent_board.callback_endpoints      where endpoint_url like 'https://example.test/iso187/%';
+  delete from agent_board.board_memberships       where board_id in ('18701000-0000-4000-8000-00000000000a', '18701000-0000-4000-8000-00000000000b');
+  delete from agent_board.messages                where thread_id in ('18702000-0000-4000-8000-00000000000a', '18702000-0000-4000-8000-00000000000b');
+  delete from agent_board.threads                 where id in ('18702000-0000-4000-8000-00000000000a', '18702000-0000-4000-8000-00000000000b');
+  delete from agent_board.boards                  where id in ('18701000-0000-4000-8000-00000000000a', '18701000-0000-4000-8000-00000000000b');
+  delete from agent_board.agents                  where handle like 'iso187-%';
+  drop table public.iso187_marks;
+}
+
+# "late" writes FIRST and commits LAST. Its row therefore holds a seq BELOW every row
+# the fan-out writes, while becoming visible only after the fan-out is already claimed.
+session "late"
+step "l_begin"  { BEGIN; }
+step "l_insert" {
+  select agent_board._queue_board_post_callbacks(
+    '18701000-0000-4000-8000-00000000000b'::uuid,
+    '18703000-0000-4000-8000-00000000000b'::uuid,
+    'Iso187 late', 'Iso187 late preview', 'high', jsonb_build_object()) as late_rows_written;
+}
+step "l_mark"   {
+  insert into public.iso187_marks(kind, val)
+  select 'late_seq', min(seq) from agent_board.callback_outbox_events
+   where board_id = '18701000-0000-4000-8000-00000000000b';
+}
+step "l_commit" { COMMIT; }
+
+# "fan" is the multicast fan-out: ONE statement, ONE transaction, eight recipients.
+session "fan"
+step "f_begin"  { BEGIN; }
+step "f_fanout" {
+  select agent_board._queue_board_post_callbacks(
+    '18701000-0000-4000-8000-00000000000a'::uuid,
+    '18703000-0000-4000-8000-00000000000a'::uuid,
+    'Iso187 fanout', 'Iso187 fanout preview', 'high', jsonb_build_object()) as fanout_rows_written;
+}
+step "f_mark"   {
+  insert into public.iso187_marks(kind, val)
+  select 'fan_base', min(seq) from agent_board.callback_outbox_events
+   where board_id = '18701000-0000-4000-8000-00000000000a';
+}
+# The heart of the issue: identical created_at across the whole fan-out, distinct and
+# contiguous seq. Absolute seq values are never printed — they depend on how many rows
+# the template ever wrote — so the golden stays deterministic.
+step "f_report" {
+  select count(*)                        as rows_written,
+         count(distinct created_at)      as distinct_created_at,
+         count(distinct seq)             as distinct_seq,
+         (max(seq) - min(seq) + 1)       as seq_span
+    from agent_board.callback_outbox_events
+   where board_id = '18701000-0000-4000-8000-00000000000a';
+}
+step "f_commit" { COMMIT; }
+
+# "claimer" is the notification worker. Autocommit: each claim is its own transaction,
+# exactly as a worker loop behaves.
+session "claimer"
+# The late row is still uncommitted here, so the visible queue is the fan-out alone.
+# The claim must take fan_base..fan_base+3 IN ASCENDING ORDER — set AND order.
+step "c_first"  {
+  select (select array_agg(outbox_seq) from agent_board.claim_callback_outbox_events(4))
+         = (select array_agg(g order by g)
+              from generate_series((select val from public.iso187_marks where kind = 'fan_base'),
+                                   (select val from public.iso187_marks where kind = 'fan_base') + 3) g)
+         as claimed_lowest_four_in_seq_order;
+}
+# The late row is committed now. It sorts FIRST despite committing last, and it sits
+# BELOW the high-water mark a naive seq-cursor consumer would have persisted from the
+# first claim — the boundary the wake contract must respect.
+step "c_second" {
+  with claimed as (
+    select array_agg(outbox_seq) as got from agent_board.claim_callback_outbox_events(4)
+  ),
+  marks as (
+    select (select val from public.iso187_marks where kind = 'late_seq') as late_seq,
+           (select val from public.iso187_marks where kind = 'fan_base') as fan_base
+  )
+  select (select got from claimed)
+           = array[(select late_seq from marks)]
+             || (select array_agg(g order by g)
+                   from generate_series((select fan_base from marks) + 4,
+                                        (select fan_base from marks) + 6) g)
+             as late_row_claimed_first_then_next_fan_rows,
+         (select late_seq from marks) < (select fan_base from marks)
+             as late_committer_holds_a_lower_seq_than_the_persisted_cursor;
+}
+
+permutation "l_begin" "l_insert" "l_mark" "f_begin" "f_fanout" "f_mark" "f_report" "f_commit" "c_first" "l_commit" "c_second"

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"