@consiliency/agent-board-schema 1.28.0 → 1.38.0

package/tests/agent_board_receipt_subject_gate.test.sql

@@ -0,0 +1,624 @@
+-- Consiliency/message-board#287 — a read receipt is a MEMO of access, never a SOURCE of it.
+--
+-- Two properties are pinned here and they pull in opposite directions, which is why they share
+-- a file:
+--
+--   THE GATE      a service_role caller may no longer name a THIRD PARTY in mark_read unless
+--                 that agent already passes the thread-access predicate. Before
+--                 20260912000100, `mark_read(T, B, 0)` under service_role wrote a receipt for
+--                 an agent B with no relationship to T -- and because a receipt row is itself
+--                 an inherit-mode disjunct, B then PASSED the predicate. The memo minted a
+--                 grant.
+--
+--   THE GRANDFATHER  the receipt disjunct STAYS, and it is permanent. Nothing deletes a
+--                 read_receipts row, so leaving a board or losing a task assignment does NOT
+--                 revoke access to a thread already read. "You keep what you saw." Two shipped
+--                 flows depend on it and are asserted POSITIVELY below, because they are what a
+--                 well-meaning cleanup of the disjunct would break.
+--
+-- The file runs as the postgres db role and simulates callers the way
+-- agent_board_thread_acl.test.sql does: request.jwt.claim.role / .sub. Note that with NO role
+-- claim, _is_service_role() is ALREADY true for session_user postgres, so the service_role
+-- claim is set explicitly wherever it matters rather than relied on implicitly.
+--
+-- MUTATION EVIDENCE — measured, not predicted, and re-measured after each plan change.
+-- All 36 assertions RAN in every row below (`ran=36`); a truncated plan is the failure mode
+-- this table exists to rule out, and it is checked per row rather than inferred.
+--
+--   a  delete the subject-gate `if` from mark_read
+--        -> not ok 2, 3, 4 (the mint reopens), 24, 26 (the class assertion names it)
+--   b  re-add `_is_service_role() or` to _agent_can_access_thread
+--        -> not ok 1, 2, 3, 4, 8, 24  -- the gate goes vacuous; assertion 1 exists for this
+--   c  revert the tasks disjunct to current_agent_id()
+--        -> not ok 16, 17, 19  -- grandfather flow B collapses
+--   d  revert the board-delivery disjunct to _current_agent_has_board_access
+--        -> not ok 8  -- the disjunct starts answering about the SESSION, not the subject
+--   e  remove the read_receipts disjunct entirely
+--        -> not ok 13, 14, 15, 19  -- BOTH grandfather flows collapse
+--   f1 a writer spelled `merge into agent_board.read_receipts`
+--        -> not ok 25 (names it), 26, 27
+--   f2 a writer spelled `update only agent_board.read_receipts`
+--        -> not ok 25, 26
+--   f3 a writer spelled `delete from only "agent_board" . "read_receipts"`
+--        -> not ok 25, 26, 27
+--   f4 the EXISTING member mark_read's own write respelled
+--      `merge into only "agent_board"."read_receipts"` -- rule 2: mutate a member, do not only
+--      add a new one
+--        -> not ok 2, 3, 4, 24, 26, 27
+--   g  `grant insert on agent_board.read_receipts to public`
+--        -> not ok 28, 30, 32, 33  -- both privilege arms
+--   h  add a receipt reaper (`delete from read_receipts`)
+--        -> not ok 25, 26, 27
+--   i  `grant insert` to a BRAND-NEW role
+--        -> not ok 33 only.  has_table_privilege(service_role,INSERT) stayed FALSE, so the
+--           effective arm alone would have shipped this green -- this is why the set form exists
+--   j  `grant insert` to `anon` (a live Supabase role the effective arm never names)
+--        -> not ok 33 only
+--   k  `grant insert` to a role, then that role granted TO service_role (role MEMBERSHIP)
+--        -> not ok 28, 33.  The ACL names only the member role, so the set form reports the
+--           wrong subject; has_table_privilege(service_role) = true is the one that answers
+--           the real question -- this is why the effective arm exists
+--   l  a TRUNCATE-based receipt reaper (`truncate agent_board.read_receipts`)
+--        -> not ok 27.  Before `truncate` joined that alternation this was GREEN while the
+--           assertion claimed permanence
+--   l2 a TRUNCATE-based receipt reaper spelled `truncate table only agent_board.read_receipts`
+--      -- ADDED under message-board#291, which found this hole in its own transplanted copy of
+--      this pattern and fixed BOTH rather than leaving the known one on main
+--        -> not ok 27.  It was GREEN before that fix: the alternation was written
+--           `truncate(\s+only)?\s+(table\s+)?`, i.e. ONLY before TABLE, but PostgreSQL's
+--           syntax is `TRUNCATE [ TABLE ] [ ONLY ] name` -- TABLE FIRST. Measured on PG17:
+--           `truncate agent_board.read_receipts` / `truncate only …` / `truncate table …` all
+--           matched, and `truncate table only …` -- equally legal -- did NOT. A SECURITY
+--           DEFINER reaper spelled that way shipped green past the assertion that claims the
+--           receipt grandfather is permanent. The alternation is now
+--           `(\s+table)?(\s+only)?`, which accepts both keywords in the legal order, either
+--           alone, or neither.
+--   m  a writer that CALLS _agent_can_access_thread and IGNORES the result
+--        -> not ok 25, 26.  The previous assertion 26 predicate (a bare qualified call) MATCHED
+--           this function, i.e. it would have read as gated and shipped GREEN
+--   n  `revoke select on read_receipts from service_role` (over-revoke guard)
+--        -> not ok 29
+--   o  a writer on a DIFFERENT table named `read_receipts_archive`
+--        -> ran=36, notok=0.  A NEGATIVE pin: the guard must stay GREEN. Under the previous
+--           unbounded pattern this function MATCHED, i.e. assertion 25 went red and named a
+--           function that never touches read_receipts -- a false accusation.
+--   o-control  a REAL writer added in the same transaction as o
+--        -> not ok 25, 26.  Without this, o's green is indistinguishable from a pattern that
+--           matches nothing at all; a negative pin needs a positive control beside it.  -- permanence, hence the grandfather, would stop being true
+--
+-- TWO CONTRASTS THAT ARE THE POINT OF THE LAST REVISION, both measured directly:
+--   * f1-f3 were each INVISIBLE to the previous regex. Evaluating the old and new patterns
+--     over the same five spellings: the old matched only the plain
+--     `insert into agent_board.read_receipts` control and missed all four others; the new
+--     matched all five.
+--   * under g, the direct-grantee query these assertions replaced still reported
+--     service_role = 'SELECT' while has_table_privilege reported INSERT = true. The old
+--     assertion 28 would have stayed GREEN while its own message was false.
+--
+-- Assertions 29 and 31 are the positive SELECT guards (mutation n), and 34 is the positive
+-- owner-exemption guard: they red if the write-revoke is over-applied to the read path or if
+-- the postgres exclusion above stops being an owner exemption.
+--
+-- i/j/k are the three-way proof that NEITHER privilege arm subsumes the other: i and j red
+-- only the set form, k reds the effective form on the subject that matters. Dropping either
+-- arm leaves a real route uncovered.
+
+create extension if not exists pgtap with schema extensions;
+set search_path = extensions, public, agent_board;
+
+begin;
+
+select plan(36);
+
+create temp table _rsg (
+  thread_plain  uuid,
+  thread_board  uuid,
+  thread_task   uuid,
+  board_id      uuid,
+  agent_owner   uuid,
+  agent_strange uuid,
+  agent_joiner  uuid,
+  agent_reasgn  uuid,
+  user_owner    uuid,
+  user_strange  uuid,
+  task_id       uuid
+) on commit drop;
+
+-- Receipt captures land in a table that EXISTS BEFORE any RPC runs. `create temp table _x as
+-- select * from <rpc>(...)` inside lives_ok looks equivalent, but when the call raises, the
+-- table is never created and the NEXT assertion -- a plain select from it -- errors and aborts
+-- the whole file, so the remaining assertions never run (14 of 31, observed under mutation e).
+-- lives_ok's subtransaction contains the raise; a missing row then reads as null and FAILS a
+-- named assertion instead of killing the plan.
+create temp table _rsg_receipt (
+  label                      text primary key,
+  thread_id                  uuid,
+  agent_id                   uuid,
+  last_read_message_sequence bigint,
+  last_read_at               timestamptz
+) on commit drop;
+
+do $$
+declare
+  v_sfx      text := replace(substr(gen_random_uuid()::text, 1, 8), '-', '');
+  v_u_owner  uuid;
+  v_u_stran  uuid;
+  v_u_join   uuid;
+  v_u_reasg  uuid;
+  v_owner    uuid := gen_random_uuid();
+  v_stranger uuid := gen_random_uuid();
+  v_joiner   uuid := gen_random_uuid();
+  v_reasgn   uuid := gen_random_uuid();
+  v_t_plain  uuid := gen_random_uuid();
+  v_t_board  uuid := gen_random_uuid();
+  v_t_task   uuid := gen_random_uuid();
+  v_board    uuid := gen_random_uuid();
+  v_memb     uuid := gen_random_uuid();
+  v_msg      uuid := gen_random_uuid();
+  v_task     uuid := gen_random_uuid();
+begin
+  v_u_owner := public.ensure_github_user('rsg-owner-' || v_sfx, 'rsg-owner-' || v_sfx || '@example.test', 'rsg-owner-' || v_sfx, 'RSG Owner');
+  v_u_stran := public.ensure_github_user('rsg-stran-' || v_sfx, 'rsg-stran-' || v_sfx || '@example.test', 'rsg-stran-' || v_sfx, 'RSG Stranger');
+  v_u_join  := public.ensure_github_user('rsg-join-'  || v_sfx, 'rsg-join-'  || v_sfx || '@example.test', 'rsg-join-'  || v_sfx, 'RSG Joiner');
+  v_u_reasg := public.ensure_github_user('rsg-reasg-' || v_sfx, 'rsg-reasg-' || v_sfx || '@example.test', 'rsg-reasg-' || v_sfx, 'RSG Reassigned');
+
+  insert into agent_board.agents(id, agent_type, handle, display_name, status, auth_user_id, owner_user_id)
+  values
+    (v_owner,    'agent', 'rsg-owner-' || v_sfx, 'RSG Owner',      'active', v_u_owner, v_u_owner),
+    (v_stranger, 'agent', 'rsg-stran-' || v_sfx, 'RSG Stranger',   'active', v_u_stran, v_u_stran),
+    (v_joiner,   'agent', 'rsg-join-'  || v_sfx, 'RSG Joiner',     'active', v_u_join,  v_u_join),
+    (v_reasgn,   'agent', 'rsg-reasg-' || v_sfx, 'RSG Reassigned', 'active', v_u_reasg, v_u_reasg);
+
+  -- Three inherit threads. last_message_sequence is set high so mark_read's
+  -- least(p_seq, last_message_sequence) never silently clamps a cursor assertion.
+  insert into agent_board.threads(id, thread_type, created_by_agent_id, subject, last_message_sequence)
+  values
+    (v_t_plain, 'coordination', v_owner, 'RSG plain thread', 9),
+    (v_t_board, 'coordination', v_owner, 'RSG board thread', 9),
+    (v_t_task,  'task',         v_owner, 'RSG task thread',  9);
+
+  -- The board thread: a board-delivered message. The board-delivery disjunct keys on
+  -- delivery_recipients.board_id + the message's thread, NOT on recipient_agent_id, so the
+  -- late joiner reaches it through board membership alone -- which is the flow being pinned.
+  insert into agent_board.boards(id, slug, name, created_by_agent_id, visibility)
+  values (v_board, 'rsg-board-' || v_sfx, 'RSG Board', v_owner, 'open');
+
+  insert into agent_board.board_memberships(id, board_id, agent_id, membership_state, role)
+  values (v_memb, v_board, v_owner, 'joined', 'owner');
+
+  insert into agent_board.messages(id, thread_id, author_agent_id, message_sequence, message_type, body)
+  values (v_msg, v_t_board, v_owner, 1, 'comment', 'board post');
+
+  insert into agent_board.delivery_recipients(delivery_mode, recipient_agent_id, source_kind, source_message_id, board_id, board_membership_id)
+  values ('board', v_owner, 'message', v_msg, v_board, v_memb);
+
+  -- The task thread: v_reasgn is the assignee (the task disjunct), and will be reassigned away.
+  insert into agent_board.tasks(id, thread_id, created_by_agent_id, assigned_agent_id, title, status, priority, orchestration_mode)
+  values (v_task, v_t_task, v_owner, v_reasgn, 'RSG task', 'pending', 'medium', 'distributed');
+
+  insert into _rsg values
+    (v_t_plain, v_t_board, v_t_task, v_board, v_owner, v_stranger, v_joiner, v_reasgn, v_u_owner, v_u_stran, v_task);
+end
+$$;
+
+select set_config('request.jwt.claim.role', 'service_role', true);
+
+-- ============================================================================
+-- 1-4. THE GATE: service_role cannot mint a receipt for an agent with no access
+-- ============================================================================
+-- Assertion 1 is the SHORT-CIRCUIT INVARIANT and it is deliberately evaluated under a
+-- service_role claim: _agent_can_access_thread must carry NO _is_service_role() bypass, or the
+-- gate below is vacuous while every allow-side assertion in this file stays green.
+select is(
+  agent_board._agent_can_access_thread(
+    (select thread_plain from _rsg), (select agent_strange from _rsg)),
+  false,
+  'invariant: _agent_can_access_thread answers about the SUBJECT under a service_role claim (no short-circuit)');
+
+select throws_ok(
+  $$ select * from agent_board.mark_read(
+       (select thread_plain from _rsg), (select agent_strange from _rsg), 0) $$,
+  '42501',
+  'read receipt subject has no access to thread',
+  'service_role CANNOT mint a receipt for an agent with no access to the thread');
+
+select is(
+  (select count(*)::int from agent_board.read_receipts rr
+    where rr.thread_id = (select thread_plain from _rsg)
+      and rr.agent_id = (select agent_strange from _rsg)),
+  0,
+  'the refused call wrote NO read_receipts row for the named stranger');
+
+select is(
+  agent_board._agent_can_access_thread(
+    (select thread_plain from _rsg), (select agent_strange from _rsg)),
+  false,
+  'the stranger still has no thread access after the refused call (the false->true transition is closed)');
+
+-- ============================================================================
+-- 5-7. The allow side: an agent that DOES have access still gets its receipt
+-- ============================================================================
+-- #113: the call goes through lives_ok and the assertions read the captured row. A bare
+-- is((select ... from mark_read(...))) would ABORT the whole file on a raise, emitting no
+-- `not ok` -- an over-refusing gate would then look like a pass.
+select lives_ok(
+  $$ insert into _rsg_receipt
+       select 'owner', * from agent_board.mark_read(
+         (select thread_plain from _rsg), (select agent_owner from _rsg), 1) $$,
+  'service_role marks read for the thread creator [call succeeds]');
+
+select is(
+  (select agent_id from _rsg_receipt where label = 'owner'),
+  (select agent_owner from _rsg),
+  'the receipt subject is the named agent');
+
+select is(
+  (select count(*)::int from agent_board.read_receipts rr
+    where rr.thread_id = (select thread_plain from _rsg)
+      and rr.agent_id = (select agent_owner from _rsg)),
+  1,
+  'a receipt row IS written for an agent that already has access');
+
+-- ============================================================================
+-- 8-15. GRANDFATHER FLOW A — the late board joiner
+-- ============================================================================
+-- Joins a board after the history was posted, reads a thread, then leaves. The board-delivery
+-- disjunct evaporates on leaving; the receipt is what keeps the thread readable.
+select is(
+  agent_board._agent_can_access_thread(
+    (select thread_board from _rsg), (select agent_joiner from _rsg)),
+  false,
+  'flow A precondition: before joining the board, the joiner has no access to the board thread');
+
+insert into agent_board.board_memberships(board_id, agent_id, membership_state, role)
+select board_id, agent_joiner, 'joined', 'member' from _rsg;
+
+select is(
+  agent_board._agent_can_access_thread(
+    (select thread_board from _rsg), (select agent_joiner from _rsg)),
+  true,
+  'flow A: a late joiner reaches the board thread through the board-delivery disjunct');
+
+select lives_ok(
+  $$ insert into _rsg_receipt
+       select 'joiner', * from agent_board.mark_read(
+         (select thread_board from _rsg), (select agent_joiner from _rsg), 2) $$,
+  'flow A: service_role marks read on behalf of the late joiner [call succeeds]');
+
+select is(
+  (select last_read_message_sequence from _rsg_receipt where label = 'joiner'),
+  2::bigint,
+  'flow A: the joiner receipt records the cursor it was given');
+
+update agent_board.board_memberships
+   set membership_state = 'left', left_at = now()
+ where board_id = (select board_id from _rsg)
+   and agent_id = (select agent_joiner from _rsg);
+
+select is(
+  agent_board._agent_has_board_access(
+    (select board_id from _rsg), (select agent_joiner from _rsg)),
+  false,
+  'flow A: after leaving, the board disjunct no longer holds for the joiner');
+
+select is(
+  agent_board._agent_can_access_thread(
+    (select thread_board from _rsg), (select agent_joiner from _rsg)),
+  true,
+  'GRANDFATHER A: leaving the board does NOT revoke access to a thread already read');
+
+select lives_ok(
+  $$ insert into _rsg_receipt
+       select 'joiner-after-leaving', * from agent_board.mark_read(
+         (select thread_board from _rsg), (select agent_joiner from _rsg), 5) $$,
+  'GRANDFATHER A: the cursor still advances on grandfathered access [call succeeds]');
+
+select is(
+  (select last_read_message_sequence from _rsg_receipt where label = 'joiner-after-leaving'),
+  5::bigint,
+  'GRANDFATHER A: the subject gate accepts the receipt disjunct as the subject''s access');
+
+-- ============================================================================
+-- 16-19. GRANDFATHER FLOW B — the reassigned task assignee
+-- ============================================================================
+select is(
+  agent_board._agent_can_access_thread(
+    (select thread_task from _rsg), (select agent_reasgn from _rsg)),
+  true,
+  'flow B precondition: the assignee reaches the task thread through the task disjunct');
+
+select lives_ok(
+  $$ insert into _rsg_receipt
+       select 'assignee', * from agent_board.mark_read(
+         (select thread_task from _rsg), (select agent_reasgn from _rsg), 3) $$,
+  'flow B: service_role marks read on behalf of the assignee [call succeeds]');
+
+update agent_board.tasks
+   set assigned_agent_id = (select agent_owner from _rsg)
+ where id = (select task_id from _rsg);
+
+select is(
+  (select exists (
+     select 1 from agent_board.tasks t
+      where t.thread_id = (select thread_task from _rsg)
+        and (t.created_by_agent_id = (select agent_reasgn from _rsg)
+             or t.assigned_agent_id = (select agent_reasgn from _rsg)))),
+  false,
+  'flow B: after reassignment the task disjunct no longer holds for the former assignee');
+
+select is(
+  agent_board._agent_can_access_thread(
+    (select thread_task from _rsg), (select agent_reasgn from _rsg)),
+  true,
+  'GRANDFATHER B: losing the task assignment does NOT revoke access to a thread already read');
+
+-- ============================================================================
+-- 20-23. The authenticated path is unchanged
+-- ============================================================================
+select set_config('request.jwt.claim.role', 'authenticated', true);
+select set_config('request.jwt.claim.sub', (select user_owner from _rsg)::text, true);
+
+select throws_ok(
+  $$ select * from agent_board.mark_read(
+       (select thread_plain from _rsg), (select agent_strange from _rsg), 1) $$,
+  '42501',
+  'p_agent_id must match current_agent_id()',
+  'authenticated still cannot name a third party at all -- refused before the subject gate');
+
+select lives_ok(
+  $$ insert into _rsg_receipt
+       select 'authenticated-self', * from agent_board.mark_read(
+         (select thread_plain from _rsg), (select agent_owner from _rsg), 4) $$,
+  'authenticated marks its OWN read unchanged [call succeeds]');
+
+select is(
+  (select last_read_message_sequence from _rsg_receipt where label = 'authenticated-self'),
+  4::bigint,
+  'authenticated cursor advances exactly as before');
+
+select is(
+  agent_board._current_agent_can_access_thread((select thread_plain from _rsg)),
+  true,
+  'the recomposed _current_agent_can_access_thread still admits the creator under authenticated');
+
+select set_config('request.jwt.claim.sub', (select user_strange from _rsg)::text, true);
+
+select is(
+  agent_board._current_agent_can_access_thread((select thread_plain from _rsg)),
+  false,
+  'the recomposed _current_agent_can_access_thread still denies an unrelated agent under authenticated');
+
+-- ============================================================================
+-- 25-36. Catalog-derived class + the invariants that keep the gate real
+-- ============================================================================
+select set_config('request.jwt.claim.role', 'service_role', true);
+select set_config('request.jwt.claim.sub', '', true);
+
+-- The completeness claim is "mark_read is the ONLY route to a read_receipts row", and it is
+-- backed from BOTH sides: the catalog function scan below, and the effective-privilege
+-- assertions after it (no role holds a write privilege, by ANY route, so a direct write is
+-- impossible and the SECURITY DEFINER bodies are the whole surface).
+--
+-- WHAT THE SCAN COVERS, stated exactly rather than generously. It is a REGEX over stripped
+-- function source, so its completeness is the completeness of the pattern, and a spelling the
+-- pattern does not know is a SILENT miss -- not a loud one. An earlier version of this comment
+-- claimed "a wider scan can only produce a LOUD false positive, never a silent miss"; that
+-- argument is about WIDENING and says nothing about the NARROWING gaps the pattern had. It
+-- did, and these are VERIFIED-LEGAL spellings on PG17, not hypotheticals: `update only
+-- read_receipts`, `delete from only read_receipts`, `merge into read_receipts` and `merge into
+-- only read_receipts` (MERGE was absent from the alternation entirely), `insert into
+-- agent_board."read_receipts"`, `"agent_board" . "read_receipts"`. Each was invisible and left
+-- the assertion green. (`insert into only` is NOT one of them -- ONLY is not accepted after
+-- INSERT INTO. The pattern tolerates it anyway because refusing it would buy nothing; the
+-- claim here is confined to spellings Postgres actually parses.) The pattern below now covers
+-- ONLY, MERGE, double-quoted identifier parts and whitespace around the schema dot, and the
+-- mutations exercise them against a REAL member as well as a new one.
+--
+-- ONE MORE WAS MISSING AND IS NOW COVERED (message-board#291). The permanence scan below spelled
+-- its TRUNCATE arm `truncate(\s+only)?\s+(table\s+)?`, which has PostgreSQL's keyword order
+-- BACKWARDS: the syntax is `TRUNCATE [ TABLE ] [ ONLY ] name`, TABLE first. So
+-- `truncate table only agent_board.read_receipts` -- legal, verified on PG17 -- was invisible,
+-- and a reaper spelled that way would have shipped green past the assertion claiming the
+-- grandfather is permanent. Fixed here rather than on the branch that found it, because the
+-- defect is identical in both files and leaving the known one on main is worse than the scope
+-- mix. Mutation l2 pins it.
+--
+-- It still is not a parser, and it HAD one known blind spot, now closed by message-board#293.
+-- A function declared with an SQL-standard `BEGIN ATOMIC` body keeps its body in
+-- pg_proc.prosqlbody and leaves prosrc EMPTY -- verified directly on this cluster: a BEGIN
+-- ATOMIC function reading read_receipts showed prosrc empty, prosqlbody non-null, and
+-- stripped_body ''. A writer written that way was invisible to assertions 25, 26 and 27 alike.
+--
+-- It was fixed in the SHARED helper (tests/fixtures/test-prereqs.sql), not here: stripped_body
+-- had a LIVE use in 22 test files including this one (counted from the catalog of files, not
+-- estimated; #293's own text said 19 and an earlier draft of this comment guessed "roughly
+-- ten"), so a local patch would have fixed one caller and left 21 open -- the partial-fix shape
+-- CLAUDE.md rule 1 bans. stripped_body now falls back to the DEPARSED prosqlbody and RAISES on
+-- a body it can read by neither route, so an unreadable body is loud instead of silently
+-- matching nothing. Pinned by SQLBODY-1..-11 in agent_board_source_strip_helper.test.sql,
+-- SQLBODY-11 being an exact-set writer scan of this file's own shape.
+--
+-- What that does NOT buy: for such a function these regexes read Postgres' DEPARSE of the
+-- parse tree rather than the author's text, and no agent_board function is written that way
+-- today, so the shape remains UNEXERCISED against real schema code -- a fact about today's
+-- catalog, not a property of the scan.
+--
+-- What keeps the completeness claim honest despite all of the above is the SECOND LEG: no
+-- grantee holds a write privilege on the table by ANY route (assertions 29, 31, 32, 33), so an
+-- unmatched writer would have to be a SECURITY DEFINER function -- exactly the population this
+-- scans -- and the exact-set shape means a widened pattern fails LOUDLY and names what it
+-- caught rather than passing.
+--
+-- THE RIGHT-HAND BOUNDARY, and why it is an ALTERNATION rather than a trailing \M. Without a
+-- boundary the pattern also matched `read_receipts_archive` -- a DIFFERENT table whose name
+-- merely starts with this one. That direction is fail-CLOSED (a spurious member reds the
+-- exact-set assertion and names a function, rather than hiding one), so it never threatened
+-- the completeness claim. It is fixed anyway for a second-order reason: a future author who
+-- adds a read_receipts_archive table would get a FALSE accusation from this guard, and the
+-- natural response to a guard that cries wolf is to loosen it. That is how a real guard dies.
+--
+-- `_` is a word character in Postgres regex, so \M (end-of-word) correctly refuses
+-- `read_receipts_archive`. The trap is the QUOTED form: with a MANDATORY closing quote,
+-- `"read_receipts"\M` FAILS, because after `"` no word ends there -- verified directly.
+-- Writing `"?read_receipts"?\M` happens to work, but only because the optional `"?`
+-- BACKTRACKS to empty so \M lands between `s` and `"` -- i.e. on the quoted form the pattern
+-- silently stops requiring the closing quote at all. Correct today, and far too subtle to
+-- leave for the next editor. The alternation states the two cases separately: unquoted ends
+-- at \M, quoted ends at its own mandatory closing quote, which IS the boundary.
+--
+-- Verified over 14 spellings, 8 that MUST match and 6 that MUST NOT (`read_receipts_archive`
+-- bare / schema-qualified / quoted, `read_receipts2`, `old_read_receipts`, and a plain SELECT,
+-- which is a read and not a write).
+--
+-- The scan keeps STRING LITERALS (stripped_body's second argument) on purpose: a writer
+-- assembled as dynamic SQL lives in a literal. Comments are still stripped, so prose naming
+-- the pattern cannot satisfy it.
+select is(
+  (select coalesce(string_agg(p.proname, ',' order by p.proname), '(none)')
+     from pg_proc p
+    where p.pronamespace = 'agent_board'::regnamespace
+      and lower(agent_board_test.stripped_body(p.oid, true))
+          ~ '(insert\s+into|merge\s+into|update|delete\s+from)(\s+only)?\s+(("?agent_board"?\s*\.\s*)?read_receipts\M|("?agent_board"?\s*\.\s*)?"read_receipts")'),
+  'mark_read',
+  'catalog: mark_read is the ONLY agent_board function that writes read_receipts -- a new writer names itself here');
+
+select is(
+  (select coalesce(string_agg(p.proname, ',' order by p.proname), '(none)')
+     from pg_proc p
+    where p.pronamespace = 'agent_board'::regnamespace
+      and lower(agent_board_test.stripped_body(p.oid, true))
+          ~ '(insert\s+into|merge\s+into|update|delete\s+from)(\s+only)?\s+(("?agent_board"?\s*\.\s*)?read_receipts\M|("?agent_board"?\s*\.\s*)?"read_receipts")'
+      and lower(agent_board_test.stripped_body(p.oid))
+          !~ 'not\s+agent_board\._agent_can_access_thread\s*\('),
+  '(none)',
+  'catalog: every read_receipts writer contains a REFUSING reference to _agent_can_access_thread (source shape only -- assertion 2 is what proves it refuses)');
+
+-- WHAT ASSERTION 26 DOES AND DOES NOT ESTABLISH. It matches `not
+-- agent_board._agent_can_access_thread(` in the writer's body -- a source SHAPE, so it sees
+-- the refusing form rather than a bare mention, but it still cannot see whether the branch
+-- raises, or whether the result is discarded. Its message used to say every writer "gates its
+-- named subject", which is more than a regex can know: that is the "comment claims what no
+-- assertion does" tell. The message now says what it checks. The BEHAVIOUR -- that the gate
+-- actually refuses -- is assertion 2, which calls mark_read for a subject with no access and
+-- requires the 42501; mutation a (deleting the gate) reds 2 and 26 together, so the pair is
+-- not redundant: 26 is the CLASS half (a NEW writer that skips the gate) and 2 is the
+-- BEHAVIOURAL half (this writer really refuses).
+
+-- The permanence half of the grandfather, asserted rather than asserted-about: if a future
+-- migration adds a receipt reaper, "you keep what you saw" stops being true and this names it.
+-- TRUNCATE is in the alternation because it removes every row without a DELETE: the assertion
+-- claims permanence, so scanning only `delete from` would have claimed more than it checked.
+select is(
+  (select coalesce(string_agg(p.proname, ',' order by p.proname), '(none)')
+     from pg_proc p
+    where p.pronamespace = 'agent_board'::regnamespace
+      and lower(agent_board_test.stripped_body(p.oid, true))
+          ~ '(delete\s+from|merge\s+into|truncate)(\s+table)?(\s+only)?\s+(("?agent_board"?\s*\.\s*)?read_receipts\M|("?agent_board"?\s*\.\s*)?"read_receipts")'),
+  '(none)',
+  'catalog: no agent_board function deletes or truncates a read receipt -- the grandfather is permanent by construction');
+
+-- EFFECTIVE privilege, not the direct grant. information_schema.role_table_grants filtered on
+-- `grantee = '<role>'` shows only grants made TO THAT NAME, so `grant insert on
+-- agent_board.read_receipts to public` hands service_role a working INSERT while a
+-- direct-grantee query stays green -- and the assertion's own message ("SELECT and only
+-- SELECT") would then be false. That is the same PUBLIC-privilege fail-open class as #118, and
+-- the first version of these two assertions had it. has_table_privilege resolves PUBLIC and
+-- role membership, so it answers the question the message actually asks. Mutation g
+-- (`grant insert ... to public`) reds assertions 29 and 31 and would NOT have reded the
+-- direct-grantee form -- that contrast is the whole reason for the change.
+select is(
+  (select string_agg(priv, ',' order by priv)
+     from unnest(array['INSERT', 'UPDATE', 'DELETE', 'TRUNCATE', 'REFERENCES']) as priv
+    where has_table_privilege('service_role', 'agent_board.read_receipts', priv)),
+  null,
+  'service_role holds NO effective write privilege on read_receipts, by any route incl. PUBLIC');
+
+select ok(
+  has_table_privilege('service_role', 'agent_board.read_receipts', 'SELECT'),
+  'service_role does hold SELECT on read_receipts (the read path is not over-revoked)');
+
+select is(
+  (select string_agg(priv, ',' order by priv)
+     from unnest(array['INSERT', 'UPDATE', 'DELETE', 'TRUNCATE', 'REFERENCES']) as priv
+    where has_table_privilege('authenticated', 'agent_board.read_receipts', priv)),
+  null,
+  'authenticated holds NO effective write privilege on read_receipts, by any route incl. PUBLIC');
+
+select ok(
+  has_table_privilege('authenticated', 'agent_board.read_receipts', 'SELECT'),
+  'authenticated does hold SELECT on read_receipts (the read path is not over-revoked)');
+
+-- The PUBLIC pseudo-role directly: `=arwd` on the table would give EVERY role a write, present
+-- and future, including roles this file does not name.
+select is(
+  (select string_agg(priv, ',' order by priv)
+     from unnest(array['INSERT', 'UPDATE', 'DELETE', 'TRUNCATE', 'REFERENCES', 'SELECT']) as priv
+    where has_table_privilege('public', 'agent_board.read_receipts', priv)),
+  null,
+  'PUBLIC holds NO privilege at all on read_receipts -- no role gains a write through it');
+
+-- THE SET FORM -- and why BOTH arms are needed, measured rather than assumed.
+--
+-- The has_table_privilege assertions above are a HAND LIST of two grantees (CLAUDE.md rule 1):
+-- an INSERT granted to `anon`, or to a brand-new role, self-names NOWHERE in them. This arm is
+-- the rule-1-correct shape -- the set of grantees holding any non-SELECT privilege on the
+-- table, derived from the ACL, so a new grantee FAILS THIS AND NAMES ITSELF.
+--
+-- Neither arm subsumes the other. Measured on this cluster, granting INSERT to a new role
+-- `rsg_newrole`:
+--     set form                                 -> rsg_newrole:INSERT      (RED)
+--     has_table_privilege(service_role,INSERT)  -> false                   (still green)
+-- and granting INSERT to PUBLIC:
+--     set form                                 -> PUBLIC:INSERT           (RED)
+--     has_table_privilege(service_role,INSERT)  -> true                    (RED)
+-- PUBLIC happens to appear in the ACL as its own grantee, so the set form catches that case
+-- too; what it CANNOT catch is privilege reaching a role through ROLE MEMBERSHIP, where the
+-- ACL names only the member role and never service_role:
+--     grant insert to rsg_newrole; grant rsg_newrole to service_role;
+--     set form                                 -> rsg_newrole:INSERT   (names the wrong thing)
+--     has_table_privilege(service_role,INSERT)  -> true                 (names the real answer)
+-- So: the set form answers "has anyone been granted a write", the effective form answers "can
+-- THESE two roles write". Both, or a route is uncovered.
+--
+-- The ACL is read through aclexplode(pg_class.relacl) rather than
+-- information_schema.role_table_grants, because that view is filtered to roles the CURRENT
+-- user can see -- a privilege-dependent visibility filter has no place inside a completeness
+-- claim. `postgres` (the table owner, whose full ownership ACL is expected) is the one
+-- exemption, and it is stated POSITIVELY below rather than by absence of a match.
+select is(
+  (select coalesce(string_agg(distinct coalesce(g.rolname, 'PUBLIC') || ':' || a.privilege_type,
+                              ', ' order by coalesce(g.rolname, 'PUBLIC') || ':' || a.privilege_type),
+                   '(none)')
+     from pg_class c
+     cross join aclexplode(c.relacl) a
+     left join pg_roles g on g.oid = a.grantee
+    where c.oid = 'agent_board.read_receipts'::regclass
+      and a.privilege_type <> 'SELECT'
+      and coalesce(g.rolname, 'PUBLIC') <> 'postgres'),
+  '(none)',
+  'catalog: NO grantee holds a non-SELECT privilege on read_receipts -- a new one names itself here');
+
+-- The owner exemption, asserted positively: `postgres` is expected to hold the full ownership
+-- ACL, and saying so is what keeps the exclusion above from being a place to hide a grantee.
+select ok(
+  has_table_privilege('postgres', 'agent_board.read_receipts', 'INSERT')
+    and has_table_privilege('postgres', 'agent_board.read_receipts', 'DELETE'),
+  'the one excluded grantee, postgres, is the table OWNER and does hold the full ACL as expected');
+
+-- The board helper carries the same no-short-circuit invariant, for the same reason.
+select is(
+  agent_board._agent_has_board_access(
+    (select board_id from _rsg), (select agent_strange from _rsg)),
+  false,
+  'invariant: _agent_has_board_access answers about the SUBJECT under a service_role claim (no short-circuit)');
+
+-- Over-revoke guard: the short-circuit belongs in the SESSION predicate and must stay there.
+-- "Fixing" the invariant by deleting it everywhere would break every live service_role caller.
+select is(
+  agent_board._current_agent_can_access_thread((select thread_plain from _rsg)),
+  true,
+  'the _is_service_role() short-circuit is PRESERVED in the session predicate where it belongs');
+
+select * from finish();
+
+rollback;