@consiliency/agent-board-schema 1.22.0 → 1.23.0

package/tests/agent_board_wake_recovery.test.sql

@@ -0,0 +1,756 @@
+-- WAKERECOVERY / message-board#191 — the gap-safe wake recovery surface.
+--
+-- WHAT THIS FILE PINS, and why each assertion is shaped the way it is:
+--
+--   * WR-1 EXISTENCE — the view exists and the exact string the runtime's fetch
+--     descriptor names (`agent_board.v_agent_wake_recovery`) resolves to a VIEW.
+--     Renaming the view in the migration without renaming it in the descriptor
+--     fails here.
+--   * WR-2 INVOKER + SHAPE -- `security_invoker = true` read from `reloptions`,
+--     not inferred from the DDL text. WR-2 pins the DECLARATION and NOTHING MORE,
+--     and the earlier claim here that it also bounded the blast radius was WRONG.
+--     The full four-cell matrix, measured with the scoping predicate deleted and
+--     read as agent A (co-member / stranger rows returned):
+--
+--         wake flag   v_agent_inbox flag   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, because an inner `security_invoker` view re-anchors
+--     base-table RLS to the real querying user through any outer definer view.
+--     My earlier note said "on this view OR on v_agent_inbox" and attributed the
+--     bound to a flag that does not carry it -- corrected from the measurement,
+--     which is the third time this paragraph has been rewritten by a probe.
+--     The flag is still declared and still asserted, because it becomes
+--     load-bearing the moment this view is rebuilt directly on `inbox_items`.
+--     The flag that DOES carry the bound is pinned in
+--     agent_board_inbox_reads.test.sql, now as a catalog-derived class over every
+--     agent_board view rather than a nine-name list.
+--     The column list is compared to `v_agent_inbox`'s FROM THE CATALOG on both
+--     sides, so the recovery surface cannot silently diverge from its source.
+--   * WR-3 GRANTS — asserted as a per-role privilege EQUALITY against
+--     `v_agent_inbox` (has_table_privilege for each of anon/authenticated/
+--     service_role, on each of SELECT/INSERT/UPDATE/DELETE), never a hand-copied
+--     grant list. `v_agent_inbox`'s own grants are split across TWO migrations
+--     (authenticated in 20260507000000, service_role in 20260508000001); an
+--     equality against the catalog absorbs that automatically. PUBLIC is checked
+--     separately through the ACL, because there is no role named `public` to ask.
+--   * WR-4 NO CURSOR — the view definition contains no comparison between a
+--     pre-commit-assigned column (`seq`, `created_at`, `updated_at`) and anything,
+--     and no ORDER BY. `pg_get_viewdef` is regenerated from the parse tree, so
+--     comments and formatting are gone by construction: unlike a `prosrc` scan,
+--     this cannot be defeated by prose.
+--   * WR-5 INDEX AGREEMENT — the view's `action_state` set equals the predicate
+--     set of the existing partial index `idx_agent_board_inbox_items_agent_pending`,
+--     both extracted from the catalog. Editing either alone fails. Both sides are
+--     coalesced to DISTINCT sentinels so a regex that stops matching cannot pass
+--     as NULL = NULL.
+--   * WR-6 BEHAVIOUR + SCOPING — the view returns exactly the unhandled items and
+--     nothing else (including inheriting `visible_in_inbox`), and under a real
+--     authenticated session a CO-MEMBER's board-delivered item is absent while a
+--     companion assertion proves that same row IS visible through `v_agent_inbox`.
+--     The pair is what makes the exclusion a measurement rather than an empty
+--     fixture. Deleting the scoping predicate turns them red.
+--   * WR-7 CLASS — catalog-derived, per repo rule #1. The member set comes from
+--     the transitive view closure over `inbox_items` / `callback_outbox_events`
+--     (pg_depend/pg_rewrite) plus every non-internal `agent_board` function whose
+--     definition reaches those tables — NOT from a list written here. A new object
+--     that gates a returned batch on a pre-commit-assigned value fails this and
+--     NAMES ITSELF. The enumeration is separately asserted to REACH the members it
+--     must, so the class cannot pass by enumerating nothing.
+--   * WR-8 / WR-9 POSITIVE — the one member the class scan names
+--     (`mark_retention_metadata`) is asserted POSITIVELY to be what it claims:
+--     a retention age sweep that returns a count and no batch, unreachable by
+--     authenticated. And the two recovery-shaped members are positively shown to
+--     partition on STATUS. Exemptions asserted by absence are where the hole hides.
+--
+-- WHAT THIS FILE DELIBERATELY DOES NOT ASSERT: that a late-committing writer is
+-- recovered. That is a CROSS-SESSION fact — a single rolled-back transaction
+-- cannot produce the interleaving at all — and it is pinned in
+-- tests/isolation/specs/wake_recovery_late_commit.spec. Saying which probe owns
+-- which property stops each from being assumed to cover the other.
+--
+-- The one-pass literal/comment strip used by WR-7 is a SINGLE alternation
+-- (`'…'` | `--…` | `/*…*/`) applied in one regexp_replace. Stripping literals and
+-- then comments in two passes desynchronises on a dollar quote or an odd
+-- apostrophe count; leftmost matching over one alternation cannot.
+--
+-- Allow-side calls are wrapped in lives_ok(...) with a SEPARATE state check
+-- (message-board#113): a bare `is((select ... from rpc(...)), ...)` aborts the
+-- transaction on a raise, pgTAP emits NO `not ok`, and every later assertion in
+-- the file silently does not run.
+
+create extension if not exists pgtap with schema extensions;
+set search_path = extensions, public, agent_board;
+
+begin;
+
+select plan(35);
+
+-- ---------------------------------------------------------------------------
+-- Shared helpers. Both are temp objects and vanish with the rollback.
+-- ---------------------------------------------------------------------------
+
+-- ONE-PASS strip of string literals, line comments, and block comments.
+create or replace function pg_temp._wr_strip(p_text text) returns text
+language sql immutable as $fn$
+  select regexp_replace(
+           coalesce($1, ''),
+           $re$'(?:[^']|'')*'|--[^\n]*|/\*(?:[^*]|\*+[^*/])*\*+/$re$,
+           ' ', 'g')
+$fn$;
+
+-- A "cursor gate" is a range test against a PRE-COMMIT-ASSIGNED column.
+--
+-- BOTH INPUTS ARE NOW DERIVED FROM THE CATALOG, not written here. The previous
+-- version hard-coded the column names AND the relation names; a name filter is a
+-- hand list wearing SQL, in the file whose whole job is to assert a class. Its
+-- concrete cost, named by the round-2 board: a function reading `v_board_feed` and
+-- gating on `first_delivered_at` -- which is `min(ii.created_at) OVER (...)`, i.e.
+-- the same pre-commit value under another name -- was outside the class entirely,
+-- on BOTH axes at once.
+--
+--   * the RELATION set is the dependency closure over the two base tables
+--     (pg_depend/pg_rewrite), so a new view over inbox_items joins the class the
+--     day it is created;
+--   * the COLUMN set is every `%_at` timestamptz column of every relation in that
+--     closure, plus `seq` -- so a derived alias like `first_delivered_at` or
+--     `latest_inbox_updated_at` is covered without being listed.
+--
+-- MATCHING IS CASE-INSENSITIVE, and that is load-bearing rather than tidiness.
+-- `pg_get_viewdef` is regenerated and lowercases everything, but
+-- `pg_get_functiondef` returns `prosrc` VERBATIM, so a PL/pgSQL body written
+-- `WHERE created_at BETWEEN p_cursor AND 'infinity'` kept its capitals and evaded
+-- a case-sensitive scan entirely. Measured: `'... BETWEEN ...' ~ '\mbetween\M'`
+-- was false. This is the actual mechanism behind the round-2 finding.
+--
+-- Shapes verified by EXECUTING the probe matrix, not by reading the regex:
+-- `created_at::timestamp > x`, `extract(epoch from created_at) > 5`,
+-- `date_trunc('day', created_at) >= x`, `coalesce(created_at, now()) > x`,
+-- `(co.seq) > p_after`, `co.seq::bigint > p_after`, reversed-with-alias
+-- `x > vi.created_at`, `created_at::timestamp > now() - interval '30 days'`,
+-- `BETWEEN` / `NOT BETWEEN` in either case, and `first_delivered_at > p_after`
+-- through `v_board_feed`. False-positive controls that must NOT match:
+-- `message_sequence >`, `event_sequence >=` (the \m boundary stops `seq` matching
+-- inside them). A detector that catches everything would make the class vacuous.
+--
+-- THE CEILING. WHAT THIS DETECTOR DOES *NOT* SEE -- measured, not guessed, and
+-- deliberately NOT widened a fourth time:
+--   * ALIAS LAUNDERING. A view projecting `created_at AS ts` and a gate on `s.ts`
+--     is inside the membership closure and returns EMPTY from this scan, because
+--     `ts` is not a `%_at` column. Renaming defeats a name-based column set by
+--     construction.
+--   * A WIDE WINDOW. The column and the operator are matched across a bounded
+--     window; two literal-free padding terms (~44 chars) between them evades.
+--     Raising the bound moves the threshold, it does not remove it.
+--   * `message_sequence` is excluded ON PURPOSE by the \m boundary (so `seq`
+--     cannot match inside it) -- but it is itself pre-commit-assigned, so a
+--     recovery gate on it would be this same defect class and invisible BY DESIGN
+--     CHOICE, not by oversight.
+-- So the narrower true claim, which is what the assertion name should be read as:
+-- this recognises LEXICAL gate shapes on KNOWN column names within a bounded
+-- window. The real guarantees in this file are the MEMBERSHIP closure (which is
+-- exhaustive and parse-tree-derived for views) and the BEHAVIOURAL WR-6
+-- assertions. WR-7 is a tripwire over the common shapes, not a proof of absence.
+--
+-- THE OTHER CEILING, ON THE FUNCTION HALF SPECIFICALLY. The function half is a TEXT scan
+-- over `prosrc`, and it cannot be anything better: PostgreSQL records no
+-- dependency from a string-bodied function to the relations it reads
+-- (`pg_depend` = 0 rows for `_upsert_inbox_item` -> `inbox_items`, measured) and
+-- exposes no parse tree for it (`prosqlbody IS NULL`). So the VIEW half is
+-- parse-tree-derived and exhaustive; the FUNCTION half is best-effort and can be
+-- evaded by dynamic SQL or by indirection through a helper. WR-13 is a tripwire on
+-- exactly that boundary: it goes red the day a function moves to a SQL-standard
+-- body, because at that point the parse tree this file could not use becomes
+-- available and the function half can be made exhaustive too.
+create or replace function pg_temp._wr_strip(p_text text) returns text
+language sql immutable as $fn$
+  select regexp_replace(
+           coalesce($1, ''),
+           $re$'(?:[^']|'')*'|--[^\n]*|/\*(?:[^*]|\*+[^*/])*\*+/$re$,
+           ' ', 'g')
+$fn$;
+
+-- The closure, and the two derived patterns, materialised once.
+create temp table _wr_class(kind text, pattern text) on commit drop;
+
+with recursive closure as (
+  select 'agent_board.inbox_items'::regclass as oid
+  union all
+  select 'agent_board.callback_outbox_events'::regclass
+  union
+  select r.ev_class
+    from pg_depend d
+    join pg_rewrite r on r.oid = d.objid
+    join closure c on c.oid = d.refobjid
+   where d.classid = 'pg_rewrite'::regclass
+     and d.refclassid = 'pg_class'::regclass
+     and r.ev_class <> d.refobjid
+),
+rels as (
+  select c.oid, c.relname, c.relkind
+    from closure cl
+    join pg_class c on c.oid = cl.oid
+    join pg_namespace n on n.oid = c.relnamespace
+   where n.nspname = 'agent_board'
+),
+cols as (
+  select distinct a.attname
+    from rels r
+    join pg_attribute a on a.attrelid = r.oid
+   where a.attnum > 0 and not a.attisdropped
+     and a.atttypid = 'timestamptz'::regtype
+     and a.attname ~ '_at$'
+  union
+  select 'seq'
+)
+insert into _wr_class(kind, pattern)
+select 'relations', string_agg(relname, '|' order by relname) from rels
+union all
+select 'columns', string_agg(attname, '|' order by length(attname) desc, attname) from cols;
+
+create or replace function pg_temp._wr_cursor_gates(p_text text) returns text
+language sql stable as $fn$
+  select coalesce(
+    (select string_agg(distinct regexp_replace(m[1], '[[:space:]]+', ' ', 'g'), ' | ')
+       from _wr_class c,
+            regexp_matches(
+              pg_temp._wr_strip($1),
+              '(\m(' || c.pattern || ')\M[^<>=]{0,40}(?:<=|>=|<|>)'
+              || '|(?:<=|>=|<|>)[^<>=]{0,40}\m(' || c.pattern || ')\M'
+              || '|\m(' || c.pattern || ')\M[^<>=]{0,20}\mbetween\M'
+              || '|\mbetween\M[^<>=]{0,40}\m(' || c.pattern || ')\M)',
+              'gi') m
+      where c.kind = 'columns'),
+    '')
+$fn$;
+
+create temp table _wr_members(name text, kind text, src text) on commit drop;
+
+with recursive closure as (
+  select 'agent_board.inbox_items'::regclass as oid
+  union all
+  select 'agent_board.callback_outbox_events'::regclass
+  union
+  select r.ev_class
+    from pg_depend d
+    join pg_rewrite r on r.oid = d.objid
+    join closure c on c.oid = d.refobjid
+   where d.classid = 'pg_rewrite'::regclass
+     and d.refclassid = 'pg_class'::regclass
+     and r.ev_class <> d.refobjid
+)
+insert into _wr_members(name, kind, src)
+select c.relname, 'view', pg_get_viewdef(c.oid)
+  from closure cl
+  join pg_class c on c.oid = cl.oid
+  join pg_namespace n on n.oid = c.relnamespace
+ where c.relkind in ('v', 'm')
+   and n.nspname = 'agent_board';
+
+insert into _wr_members(name, kind, src)
+select p.proname, 'function', pg_get_functiondef(p.oid)
+  from pg_proc p
+  join pg_namespace n on n.oid = p.pronamespace
+ where n.nspname = 'agent_board'
+   and p.prolang <> (select oid from pg_language where lanname = 'internal')
+   and pg_get_functiondef(p.oid) ~* ('(' || (select pattern from _wr_class where kind = 'relations') || ')');
+
+-- ---------------------------------------------------------------------------
+-- WR-1 EXISTENCE
+-- ---------------------------------------------------------------------------
+select has_view('agent_board', 'v_agent_wake_recovery',
+  'WR-1 v_agent_wake_recovery exists');
+
+-- The literal string the runtime fetch descriptor names. If the migration renames
+-- the view and the descriptor is not renamed with it, this is where it surfaces.
+select is(
+  (select c.relkind::text
+     from pg_class c
+    where c.oid = to_regclass('agent_board.v_agent_wake_recovery')),
+  'v',
+  'WR-1 the descriptor string agent_board.v_agent_wake_recovery resolves to a VIEW');
+
+-- ---------------------------------------------------------------------------
+-- WR-2 INVOKER + SHAPE
+-- ---------------------------------------------------------------------------
+select ok(
+  (select 'security_invoker=true' = any(coalesce(c.reloptions, '{}'::text[]))
+     from pg_class c
+    where c.oid = to_regclass('agent_board.v_agent_wake_recovery')),
+  'WR-2 v_agent_wake_recovery is security_invoker (reloptions, from the catalog) -- the DECLARATION only: measured inert in all four cells of the invoker matrix, load-bearing only if this view is ever rebuilt directly on inbox_items');
+
+select is(
+  (select string_agg(a.attname, ',' order by a.attnum)
+     from pg_attribute a
+    where a.attrelid = to_regclass('agent_board.v_agent_wake_recovery')
+      and a.attnum > 0 and not a.attisdropped),
+  (select string_agg(a.attname, ',' order by a.attnum)
+     from pg_attribute a
+    where a.attrelid = to_regclass('agent_board.v_agent_inbox')
+      and a.attnum > 0 and not a.attisdropped),
+  'WR-2 the recovery view projects EXACTLY v_agent_inbox''s column list, in order -- both sides read from pg_attribute');
+
+-- ---------------------------------------------------------------------------
+-- WR-3 GRANTS
+-- ---------------------------------------------------------------------------
+-- The grants are deliberately NOT a mirror of v_agent_inbox's: service_role is
+-- DENIED. It holds BYPASSRLS and current_agent_id() returns NULL for it, so a
+-- scoped view would hand it a silently EMPTY recovery set -- the very silent-drop
+-- shape this file exists to close. A denied SELECT is loud; an empty result is not.
+select is(
+  (select string_agg(r.rolname || ':' ||
+            (select string_agg(case when has_table_privilege(r.rolname, to_regclass('agent_board.v_agent_wake_recovery'), pr) then pr else '-' end, ',')
+               from unnest(array['SELECT', 'INSERT', 'UPDATE', 'DELETE']) pr),
+            ' ' order by r.rolname)
+     from pg_roles r
+    where r.rolname in ('anon', 'authenticated', 'service_role')),
+  'anon:-,-,-,- authenticated:SELECT,-,-,- service_role:-,-,-,-',
+  'WR-3 exactly authenticated holds SELECT; anon and service_role hold nothing -- service_role is denied ON PURPOSE so an identity-less read fails loudly instead of returning an empty recovery set');
+
+-- The half of the old mirror that still holds: whatever authenticated may do on
+-- v_agent_inbox, it may do here and no more. Catalog-derived on both sides.
+select is(
+  (select string_agg(case when has_table_privilege('authenticated', to_regclass('agent_board.v_agent_wake_recovery'), pr) then pr else '-' end, ','
+            order by pr)
+     from unnest(array['SELECT', 'INSERT', 'UPDATE', 'DELETE']) pr),
+  (select string_agg(case when has_table_privilege('authenticated', to_regclass('agent_board.v_agent_inbox'), pr) then pr else '-' end, ','
+            order by pr)
+     from unnest(array['SELECT', 'INSERT', 'UPDATE', 'DELETE']) pr),
+  'WR-3 authenticated''s privilege set matches v_agent_inbox''s exactly -- the recovery surface grants no more than the surface it derives from');
+
+select is(
+  (select count(*)::integer
+     from pg_class c
+    where c.oid = to_regclass('agent_board.v_agent_wake_recovery')
+      and array_to_string(coalesce(c.relacl, '{}'::aclitem[]), ',') ~ '(^|,)=[a-zA-Z*]+/'),
+  0,
+  'WR-3 PUBLIC holds no privilege entry in the wake recovery ACL');
+
+-- ---------------------------------------------------------------------------
+-- WR-4 NO CURSOR ON THE RECOVERY SURFACE ITSELF
+-- ---------------------------------------------------------------------------
+select is(
+  (select pg_temp._wr_cursor_gates(pg_get_viewdef(to_regclass('agent_board.v_agent_wake_recovery')))),
+  '',
+  'WR-4 the wake recovery view definition references no pre-commit ordering column in a comparison -- a cursor filter in view clothing is NAMED here');
+
+select ok(
+  (select pg_get_viewdef(to_regclass('agent_board.v_agent_wake_recovery')) !~* '\morder[[:space:]]+by\M'),
+  'WR-4 the wake recovery view carries no ORDER BY -- the unhandled set is a SET, not a cursor stream');
+
+-- ---------------------------------------------------------------------------
+-- WR-5 THE VIEW AND THE PARTIAL INDEX AGREE
+-- ---------------------------------------------------------------------------
+-- Both blobs are anchored on `action_state = ANY (ARRAY[...])`, which is how
+-- Postgres normalises an IN-list of constants, so this reads the WHERE clause and
+-- never the projection. Distinct sentinels on each side mean a regex that stops
+-- matching cannot pass as NULL = NULL.
+select is(
+  coalesce(
+    (select array_agg(btrim(btrim(split_part(e, '::', 1)), '''') order by btrim(btrim(split_part(e, '::', 1)), ''''))
+       from unnest(string_to_array(
+              substring(pg_get_viewdef(to_regclass('agent_board.v_agent_wake_recovery'))
+                        from 'action_state = ANY \(ARRAY\[([^]]*)\]'), ',')) e),
+    array['VIEW-STATE-SET-NOT-FOUND']),
+  coalesce(
+    (select array_agg(btrim(btrim(split_part(e, '::', 1)), '''') order by btrim(btrim(split_part(e, '::', 1)), ''''))
+       from unnest(string_to_array(
+              substring((select pg_get_expr(i.indpred, i.indrelid)
+                           from pg_index i
+                          where i.indexrelid = to_regclass('agent_board.idx_agent_board_inbox_items_agent_pending'))
+                        from 'action_state = ANY \(ARRAY\[([^]]*)\]'), ',')) e),
+    array['INDEX-STATE-SET-NOT-FOUND']),
+  'WR-5 the view''s action_state set equals idx_agent_board_inbox_items_agent_pending''s predicate set -- editing either one alone fails here');
+
+select isnt(
+  (select obj_description(to_regclass('agent_board.v_agent_wake_recovery'), 'pg_class')),
+  null,
+  'WR-5 the view carries a COMMENT stating that it is status-partitioned and carries no cursor');
+
+-- ---------------------------------------------------------------------------
+-- Fixture: two authenticated agents, one board, seven inbox items.
+-- Everything is scoped to these two agent ids; a repo-wide count would be
+-- polluted by earlier fixtures and would fail looking like a real defect.
+-- ---------------------------------------------------------------------------
+create temp table _wr_fixture(user_a uuid, user_b uuid, agent_a uuid, agent_b uuid) on commit drop;
+grant select on table _wr_fixture to authenticated;
+
+create temp table _wr_shape(label text, val text) on commit drop;
+grant insert, select on table _wr_shape to authenticated;
+
+do $$
+declare
+  v_suffix text := replace(substr(gen_random_uuid()::text, 1, 8), '-', '');
+  v_user_a uuid;
+  v_user_b uuid;
+  v_agent_a uuid := '19100000-0000-4000-8000-00000000000a';
+  v_agent_b uuid := '19100000-0000-4000-8000-00000000000b';
+  v_board  uuid := '19101000-0000-4000-8000-000000000001';
+  v_member uuid := '19102000-0000-4000-8000-000000000001';
+  v_member_b uuid := '19102000-0000-4000-8000-000000000002';
+  v_thread uuid := '19103000-0000-4000-8000-000000000001';
+  v_states text[] := array['new', 'restored', 'deferred', 'read', 'acknowledged', 'dismissed'];
+  v_state text;
+  v_n integer;
+begin
+  v_user_a := public.ensure_github_user(
+    'agent-board-wr191-a-' || v_suffix,
+    'agent-board-wr191-a-' || v_suffix || '@example.test',
+    'agent-board-wr191-a-' || v_suffix,
+    'Wake Recovery A ' || v_suffix);
+  v_user_b := public.ensure_github_user(
+    'agent-board-wr191-b-' || v_suffix,
+    'agent-board-wr191-b-' || v_suffix || '@example.test',
+    'agent-board-wr191-b-' || v_suffix,
+    'Wake Recovery B ' || v_suffix);
+
+  insert into agent_board.agents(id, agent_type, kind, handle, display_name, status, auth_user_id, owner_user_id)
+  values (v_agent_a, 'agent', 'agent', 'wr191-a-' || v_suffix, 'Wake Recovery Agent A', 'active', v_user_a, v_user_a),
+         (v_agent_b, 'agent', 'agent', 'wr191-b-' || v_suffix, 'Wake Recovery Agent B', 'active', v_user_b, v_user_b);
+
+  insert into agent_board.boards(id, slug, name, created_by_agent_id, visibility, status)
+  values (v_board, 'wr191-board-' || v_suffix, 'Wake Recovery Board', v_agent_a, 'open', 'active');
+
+  insert into agent_board.board_memberships(id, board_id, agent_id, role, membership_state, created_by_agent_id)
+  values (v_member, v_board, v_agent_a, 'member', 'joined', v_agent_a);
+
+  insert into agent_board.threads(id, thread_type, created_by_agent_id, subject, board_id)
+  values (v_thread, 'coordination', v_agent_a, 'Wake Recovery thread', v_board);
+
+  -- One message per inbox item: delivery_recipients is UNIQUE on
+  -- (recipient_agent_id, canonical_source_key), so one recipient cannot hold two
+  -- rows for the same message.
+  insert into agent_board.messages(id, thread_id, author_agent_id, message_sequence, message_type, body)
+  select ('19104000-0000-4000-8000-' || lpad(n::text, 12, '0'))::uuid, v_thread, v_agent_a, n, 'comment', 'wr191 message ' || n
+    from generate_series(1, 8) n;
+
+  -- Agent A: one item in each of the six action_states, all visible in inbox.
+  v_n := 0;
+  foreach v_state in array v_states loop
+    v_n := v_n + 1;
+    insert into agent_board.delivery_recipients(id, delivery_mode, recipient_agent_id, source_kind, source_message_id)
+    values (('19105000-0000-4000-8000-' || lpad(v_n::text, 12, '0'))::uuid, 'direct', v_agent_a, 'message',
+            ('19104000-0000-4000-8000-' || lpad(v_n::text, 12, '0'))::uuid);
+    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)
+    values (('19106000-0000-4000-8000-' || lpad(v_n::text, 12, '0'))::uuid,
+            ('19105000-0000-4000-8000-' || lpad(v_n::text, 12, '0'))::uuid,
+            v_agent_a, 'direct', 'message', ('19104000-0000-4000-8000-' || lpad(v_n::text, 12, '0'))::uuid,
+            'WR191 ' || v_state, 'wr191 preview', 'high', v_state, true, false, '{}'::jsonb);
+  end loop;
+
+  -- Agent A, seventh item: action_state 'new' but NOT visible in the inbox (board
+  -- feed only). v_agent_inbox filters it out; the recovery view must INHERIT that
+  -- rather than restate it.
+  insert into agent_board.delivery_recipients(id, delivery_mode, recipient_agent_id, source_kind, source_message_id, board_id, board_membership_id)
+  values ('19105000-0000-4000-8000-000000000007', 'board', v_agent_a, 'message',
+          '19104000-0000-4000-8000-000000000007', v_board, v_member);
+  insert into agent_board.inbox_items(
+    id, delivery_recipient_id, recipient_agent_id, board_id, delivery_mode, source_kind, source_message_id,
+    subject, preview, priority, action_state, visible_in_inbox, visible_in_board_feed, fetch_descriptor)
+  values ('19106000-0000-4000-8000-000000000007', '19105000-0000-4000-8000-000000000007',
+          v_agent_a, v_board, 'board', 'message', '19104000-0000-4000-8000-000000000007',
+          'WR191 board-feed only', 'wr191 preview', 'high', 'new', false, true, '{}'::jsonb);
+
+  -- Agent B is a CO-MEMBER of the same board, and its unhandled item is a BOARD
+  -- delivery with BOTH visibility flags true -- byte-for-byte the shape
+  -- post_board_message writes (it passes true, true to _upsert_inbox_item). This
+  -- is the shape the inbox_items RLS policy admits to co-members via its second
+  -- disjunct, and therefore the ONLY shape that can expose the defect. The
+  -- previous fixture used a direct, non-board row -- the one shape that IS
+  -- self-scoped -- which is why WR-6 was green while the surface leaked.
+  insert into agent_board.board_memberships(id, board_id, agent_id, role, membership_state, created_by_agent_id)
+  values (v_member_b, v_board, v_agent_b, 'member', 'joined', v_agent_a);
+
+  insert into agent_board.delivery_recipients(id, delivery_mode, recipient_agent_id, source_kind, source_message_id, board_id, board_membership_id)
+  values ('19105000-0000-4000-8000-000000000008', 'board', v_agent_b, 'message',
+          '19104000-0000-4000-8000-000000000008', v_board, v_member_b);
+  insert into agent_board.inbox_items(
+    id, delivery_recipient_id, recipient_agent_id, board_id, delivery_mode, source_kind, source_message_id,
+    subject, preview, priority, action_state, visible_in_inbox, visible_in_board_feed, fetch_descriptor)
+  values ('19106000-0000-4000-8000-000000000008', '19105000-0000-4000-8000-000000000008',
+          v_agent_b, v_board, 'board', 'message', '19104000-0000-4000-8000-000000000008',
+          'WR191 agent B board item', 'wr191 preview', 'high', 'new', true, true, '{}'::jsonb);
+
+  insert into _wr_fixture(user_a, user_b, agent_a, agent_b) values (v_user_a, v_user_b, v_agent_a, v_agent_b);
+end
+$$;
+
+-- ---------------------------------------------------------------------------
+-- WR-6 BEHAVIOUR + RLS, all under a REAL authenticated session.
+-- ---------------------------------------------------------------------------
+-- Every read below runs as agent A through an authenticated JWT, because the view
+-- is now scoped on current_agent_id() and a superuser read would legitimately see
+-- nothing. Captured under lives_ok FIRST, then asserted: read directly, a renamed
+-- or dropped view raises, aborts the transaction, and pgTAP emits NO `not ok` for
+-- this or any later assertion (#113) -- verified, the rename mutation did exactly
+-- that before this block was captured.
+select lives_ok($$
+  do $inner$
+  declare
+    v_fixture record;
+  begin
+    select * into v_fixture from _wr_fixture;
+    perform set_config('request.jwt.claim.role', 'authenticated', true);
+    perform set_config('request.jwt.claim.sub', v_fixture.user_a::text, true);
+    set local role authenticated;
+
+    insert into _wr_shape(label, val)
+    select 'states', (select string_agg(w.action_state, ',' order by w.action_state)
+                        from agent_board.v_agent_wake_recovery w)
+    union all
+    select 'handled', (select count(*)::text from agent_board.v_agent_wake_recovery w
+                        where w.action_state in ('read', 'acknowledged', 'dismissed'))
+    union all
+    select 'board_feed_only', (select count(*)::text from agent_board.v_agent_wake_recovery w
+                        where w.inbox_item_id = '19106000-0000-4000-8000-000000000007')
+    union all
+    select 'foreign_rows', (select count(*)::text from agent_board.v_agent_wake_recovery w
+                        where w.recipient_agent_id = v_fixture.agent_b)
+    union all
+    select 'own_rows', (select count(*)::text from agent_board.v_agent_wake_recovery w
+                        where w.recipient_agent_id = v_fixture.agent_a)
+    union all
+    -- The co-member's row IS readable through the unscoped surface this view is
+    -- derived from. Asserting that positively is what proves the next assertion
+    -- measures the scoping and not merely an empty board.
+    select 'foreign_rows_via_v_agent_inbox',
+           (select count(*)::text from agent_board.v_agent_inbox i
+             where i.recipient_agent_id = v_fixture.agent_b
+               and i.action_state in ('new', 'restored', 'deferred'));
+    reset role;
+  end
+  $inner$;
+$$, 'WR-6 an authenticated session can read the recovery view [call succeeds]');
+
+select is(
+  (select val from _wr_shape where label = 'states'),
+  'deferred,new,restored',
+  'WR-6 the view returns EXACTLY the caller''s unhandled states');
+
+select is(
+  (select val from _wr_shape where label = 'handled'),
+  '0',
+  'WR-6 handled items (read / acknowledged / dismissed) are NOT in the recovery set');
+
+select is(
+  (select val from _wr_shape where label = 'board_feed_only'),
+  '0',
+  'WR-6 a board-feed-only item (visible_in_inbox = false) is excluded -- the rule is INHERITED from v_agent_inbox, not restated');
+
+select is(
+  (select val from _wr_shape where label = 'own_rows'),
+  '3',
+  'WR-6 the authenticated agent sees its own three unhandled items');
+
+-- The defect this pins (message-board#191 board review): RLS on inbox_items is NOT
+-- self-scoped, so without the current_agent_id() predicate this returns the
+-- co-member's board item. Measured at 1 before the fix.
+select is(
+  (select val from _wr_shape where label = 'foreign_rows'),
+  '0',
+  'WR-6 a CO-MEMBER''s board-delivered unhandled item is NOT in the caller''s recovery set -- inbox_items RLS admits it, the view''s current_agent_id() scoping excludes it');
+
+select is(
+  (select val from _wr_shape where label = 'foreign_rows_via_v_agent_inbox'),
+  '1',
+  'WR-6 that same co-member row IS visible through v_agent_inbox -- so the assertion above measures the scoping, not an empty fixture');
+
+-- The scoping is a catalog fact, not only a behavioural one: a future edit that
+-- drops the predicate but leaves the fixture passing for another reason fails here.
+select ok(
+  (select pg_get_viewdef(to_regclass('agent_board.v_agent_wake_recovery')) ~ 'current_agent_id\(\)'),
+  'WR-6 the view definition itself scopes on current_agent_id() -- recipient scoping is server-side, never a caller''s filter');
+
+-- ---------------------------------------------------------------------------
+-- WR-7 CLASS (catalog-derived, and asserted to be non-vacuous first)
+-- ---------------------------------------------------------------------------
+-- Stated BEFORE the class assertion: if the enumeration silently stopped reaching
+-- these members, the class below would pass by finding nothing.
+select is(
+  (select string_agg(name, ', ' order by name)
+     from _wr_members
+    where name in ('claim_callback_outbox_events', 'mark_retention_metadata',
+                   'v_agent_inbox', 'v_agent_wake_recovery')),
+  'claim_callback_outbox_events, mark_retention_metadata, v_agent_inbox, v_agent_wake_recovery',
+  'WR-7 the class enumeration REACHES the members it must -- including v_agent_wake_recovery, which names inbox_items only transitively');
+
+select is(
+  (select coalesce(string_agg(distinct name, ', ' order by name), '')
+     from _wr_members
+    where pg_temp._wr_cursor_gates(src) <> ''),
+  'claim_callback_outbox_events, mark_retention_metadata',
+  'WR-7 no member of the derived class gates on a derived pre-commit column, except the two asserted positively below -- an offender NAMES ITSELF here');
+
+-- ---------------------------------------------------------------------------
+-- WR-8 POSITIVE: the one named member is what it claims to be.
+-- ---------------------------------------------------------------------------
+select is(
+  (select p.prorettype::regtype::text || '/' || p.proretset::text
+     from pg_proc p
+    where p.pronamespace = 'agent_board'::regnamespace
+      and p.proname = 'mark_retention_metadata'),
+  'bigint/false',
+  'WR-8 mark_retention_metadata returns a COUNT and is not set-returning -- it hands no batch to a consumer, so its comparison cannot be a recovery cursor');
+
+select is(
+  (select pg_temp._wr_cursor_gates(src) from _wr_members where name = 'mark_retention_metadata'),
+  'created_at <',
+  'WR-8 mark_retention_metadata''s ONLY pre-commit comparison is `created_at <` (an age cutoff) -- it never compares seq, and never gates on a lower bound');
+
+-- Read from the RAW definition on purpose: `ops_retention_reason` is a jsonb KEY,
+-- i.e. a string literal, and the one-pass strip removes it. The companion half of
+-- this assertion is read from the STRIPPED definition, where the UPDATE survives
+-- because it lives inside a dollar-quoted body rather than a single-quoted one.
+select ok(
+  (select src ~ 'ops_retention_reason'
+      and pg_temp._wr_strip(src) ~ 'update agent_board'
+     from _wr_members where name = 'mark_retention_metadata'),
+  'WR-8 mark_retention_metadata stamps retention metadata through an UPDATE sweep -- the age cutoff drives retention, not a fetch');
+
+select ok(
+  (select not has_function_privilege('authenticated', p.oid, 'EXECUTE')
+      and not has_function_privilege('anon', p.oid, 'EXECUTE')
+      and not has_function_privilege('public', p.oid, 'EXECUTE')
+     from pg_proc p
+    where p.pronamespace = 'agent_board'::regnamespace
+      and p.proname = 'mark_retention_metadata'),
+  'WR-8 mark_retention_metadata is not executable by authenticated / anon / PUBLIC -- it is not reachable as an agent read path');
+
+-- The second exemption, asserted positively rather than granted. `available_at`
+-- became a member of the DERIVED column set (it is a `%_at` timestamptz on a
+-- closure relation), and the claim RPC does gate on it -- legitimately: it is a
+-- SCHEDULING predicate against now(), not a caller-supplied cursor, and the batch
+-- it hands back is bounded by STATUS (WR-9 below). Both halves are stated.
+select is(
+  (select pg_temp._wr_cursor_gates(src) from _wr_members where name = 'claim_callback_outbox_events'),
+  'available_at <=',
+  'WR-8 claim_callback_outbox_events'' ONLY pre-commit gate is `available_at <=` -- a scheduling predicate, never a lower bound against a caller cursor');
+
+select ok(
+  (select pg_temp._wr_strip(src) !~* '\mavailable_at\M[^<>=]{0,40}(?:>=|>)'
+     from _wr_members where name = 'claim_callback_outbox_events'),
+  'WR-8 that gate is an UPPER bound (<=) and never a lower bound -- a `available_at >` would be a cursor, and is what this distinguishes');
+
+-- ---------------------------------------------------------------------------
+-- WR-13 TRIPWIRE ON THE CEILING
+-- ---------------------------------------------------------------------------
+-- The function half of WR-7 is a TEXT scan because PostgreSQL gives it nothing
+-- better: a string-bodied function records no pg_depend edge to the relations it
+-- reads and exposes no parse tree. This asserts that boundary still holds. It goes
+-- RED the day any function in the class moves to a SQL-standard body (BEGIN
+-- ATOMIC) -- which is good news, not a regression: at that point pg_depend and
+-- prosqlbody become available and the function half can be made exhaustive like
+-- the view half already is. A boundary a future change trips over, rather than a
+-- paragraph it can ignore.
+select is(
+  (select coalesce(string_agg(p.proname, ', ' order by p.proname), '')
+     from pg_proc p
+    where p.pronamespace = 'agent_board'::regnamespace
+      and p.prolang <> (select oid from pg_language where lanname = 'internal')
+      and p.prosqlbody is not null),
+  '',
+  'WR-13 CEILING: every agent_board function still has a STRING body (no prosqlbody), so no parse tree exists for the function half of WR-7 -- when this goes red, that half can stop being a text scan');
+
+-- ---------------------------------------------------------------------------
+-- WR-9 POSITIVE: the recovery-shaped members partition on STATUS.
+-- ---------------------------------------------------------------------------
+select ok(
+  (select pg_temp._wr_strip(src) ~ 'outbox_status[[:space:]]*(=|in|<>)'
+     from _wr_members where name = 'claim_callback_outbox_events'),
+  'WR-9 claim_callback_outbox_events partitions the queue on outbox_status -- the lossless property #187 relies on, restated positively here');
+
+select ok(
+  (select src ~ 'action_state = ANY'
+     from _wr_members where name = 'v_agent_wake_recovery'),
+  'WR-9 v_agent_wake_recovery partitions the inbox on action_state -- status, never an ordinal');
+
+-- ---------------------------------------------------------------------------
+-- WR-10 THE EXIT PATHS THE COMMENT CLAIMS ARE THE ONES THAT EXIST
+-- ---------------------------------------------------------------------------
+-- The migration's COMMENT carries the whole losslessness argument ("an item leaves
+-- the set only through an ack write"). Its first draft named three exit paths;
+-- pg_catalog says there is ONE. That is this repo's named trap -- a safety comment
+-- arguing from a premise the schema contradicts -- so the claim is pinned here,
+-- derived from the catalog, and a new or removed writer NAMES ITSELF.
+select is(
+  (select coalesce(string_agg(p.proname, ', ' order by p.proname), '')
+     from pg_proc p
+    where p.pronamespace = 'agent_board'::regnamespace
+      and p.prolang <> (select oid from pg_language where lanname = 'internal')
+      and pg_temp._wr_strip(pg_get_functiondef(p.oid)) ~ 'action_state[[:space:]]*=[[:space:]]*[^=]'
+      -- The schema qualification is OPTIONAL on purpose (board review F3): a writer
+      -- using `set search_path` plus a bare `update inbox_items` was invisible to
+      -- the qualified form, and WR-10 stayed green naming only one writer. Same
+      -- class as the WR-7 name filter -- two name-based enumerators in one file.
+      and pg_temp._wr_strip(pg_get_functiondef(p.oid)) ~* 'update[[:space:]]+(agent_board\.)?inbox_items\M'),
+  'update_inbox_item_state',
+  'WR-10 exactly ONE function writes inbox_items.action_state -- the only way out of the unhandled set');
+
+-- Stated positively rather than by absence, because "mark_read acks the item" is
+-- the intuition the comment encoded and it is false: mark_read writes read
+-- receipts, so a READ item is still unhandled and still woken for.
+select ok(
+  (select pg_temp._wr_strip(pg_get_functiondef(p.oid)) !~ 'action_state'
+      and pg_temp._wr_strip(pg_get_functiondef(p.oid)) ~ 'read_receipts'
+     from pg_proc p
+    where p.pronamespace = 'agent_board'::regnamespace and p.proname = 'mark_read'),
+  'WR-10 mark_read writes read_receipts and NEVER action_state -- marking an item read does not remove it from the recovery set');
+
+-- ---------------------------------------------------------------------------
+-- WR-11 WHY THE EXIT PATH IS STRUCTURAL, NOT JUST CONVENTIONAL
+-- ---------------------------------------------------------------------------
+-- WR-10 says one FUNCTION writes action_state. That is only half an invariant:
+-- a trigger, or a direct UPDATE grant, would be a second way out of the set that
+-- names no function at all. Both are closed, and asserted here so they stay that
+-- way. (Found by the Fable review seat; verified against this catalog before use.)
+select is(
+  (select count(*)::integer from pg_trigger t
+    where t.tgrelid = 'agent_board.inbox_items'::regclass and not t.tgisinternal),
+  0,
+  'WR-11 inbox_items carries NO user trigger -- nothing can move an item out of the unhandled set behind the writer''s back');
+
+select is(
+  (select coalesce(string_agg(g.grantee || '=' || g.privilege_type, ', ' order by g.grantee, g.privilege_type), '')
+     from information_schema.role_table_grants g
+    where g.table_schema = 'agent_board' and g.table_name = 'inbox_items'
+      and g.grantee in ('anon', 'authenticated', 'service_role')),
+  'authenticated=SELECT, service_role=SELECT',
+  'WR-11 authenticated and service_role hold SELECT and nothing else on inbox_items -- no direct UPDATE, so the RLS write policies cannot be reached without a grant and the ONLY way out of the set is the definer RPC');
+
+-- ---------------------------------------------------------------------------
+-- WR-12 THE ONE UNPINNED WAY OUT, NAMED RATHER THAN HIDDEN
+-- ---------------------------------------------------------------------------
+-- `_upsert_inbox_item` is the second DML writer. Its ON CONFLICT overwrites
+-- `visible_in_inbox` from the excluded row while leaving `action_state` alone, so
+-- a caller passing false on a conflicting upsert would drop an item out of
+-- `v_agent_inbox` -- and therefore out of the recovery set -- with NO ack write.
+--
+-- What is asserted: that its conflict path does not touch `action_state`, which is
+-- what keeps WR-10's "one writer" claim true.
+--
+-- What is NOT asserted, stated plainly rather than papered over: that no caller
+-- ever passes `visible_in_inbox => false`. All four current callers pass literal
+-- true (checked), but the arguments are POSITIONAL and three of them legitimately
+-- pass `false` for `visible_in_board_feed`, so a "no false in the call" scan would
+-- assert a falsehood. Pinning this properly needs named arguments at the call
+-- sites; until then this is a known, unpinned second exit.
+select ok(
+  (select regexp_replace(pg_get_functiondef(p.oid), '--[^\n]*', '', 'g')
+            ~ 'on conflict[^;]*do update'
+      and (select m[1] !~ 'action_state'
+             from regexp_matches(regexp_replace(pg_get_functiondef(p.oid), '--[^\n]*', '', 'g'),
+                                 'on conflict[^;]*do update([^;]*)', 'g') m
+            limit 1)
+     from pg_proc p
+    where p.pronamespace = 'agent_board'::regnamespace and p.proname = '_upsert_inbox_item'),
+  'WR-12 _upsert_inbox_item''s ON CONFLICT never writes action_state -- so the upsert path cannot silently ack an item (it CAN still hide one via visible_in_inbox; see the note above)');
+
+select * from finish();
+
+rollback;