@consiliency/agent-board-schema 1.28.0 → 1.35.0

package/tests/agent_board_signer_lifecycle.test.sql

@@ -646,13 +646,30 @@ select ok(
   'and it takes them agents-BEFORE-keys, matching _revoke_agent_principal [SOLE PIN: no isolation permutation discriminates this ordering]');
 
 -- ===========================================================================
--- 9. CLASS (catalog-derived, CLAUDE.md rule 1): the agents/board_memberships cycle class.
+-- 9. CLASS: the agents/board_memberships cycle class AS FAR AS A TEXT SCAN CAN SEE IT.
 --
 --    F4 was an ABBA between signed_grant_board_role and onboard_federated_fleet_agent on
---    (board_memberships, agents). The fix is only as good as the claim that those are the ONLY
---    two functions that lock both — and that claim must come from pg_catalog, not from this
---    file. Any function that row-locks both relations can close the same cycle, so every member
---    must take the board advisory lock that serialises them.
+--    (board_memberships, agents). The fix is only as good as the claim about which functions
+--    lock both relations. Any function that row-locks both can close the same cycle, so every
+--    member here must take the board advisory lock that serialises them.
+--
+--    WHAT THIS ASSERTION ACTUALLY DELIVERS, corrected under message-board#281. It finds locks by
+--    matching `for (update|share)` and `update agent_board.board_memberships` in the body text.
+--    That is a claim about EXPLICIT locks only. A lock PostgreSQL takes on our behalf through a
+--    FOREIGN KEY appears nowhere in a body, so this scan is structurally blind to it, and the
+--    header it carried until #281 — "every function that row-locks BOTH" — claimed a closure it
+--    cannot compute. Measured: this scan finds THREE members; the FK-aware derivation in
+--    agent_board_fk_lock_edges.test.sql finds 28. One of the 25 it cannot see,
+--    `_upsert_board_membership_state` (board_memberships FOR UPDATE, then agents FOR KEY SHARE
+--    via board_membership_events_agent_id_fkey inside `_emit_membership_event`), is one half of a
+--    live ABBA against onboard_federated_fleet_agent.
+--
+--    So this assertion is kept for what it IS — the explicit-lock members must stay
+--    advisory-serialised, and a new explicit both-locker still names itself here — and the
+--    class-completeness claim now lives in agent_board_fk_lock_edges.test.sql (FKL-9), which
+--    derives FK-implied edges from pg_constraint. It is NOT upgraded in place: the FK-aware class
+--    is 25 members short of serialised, and greening THAT is the ordering fix #281 deliberately
+--    separates from the tooling.
 --
 --    THE CALL GRAPH IS CLOSED OVER FIRST, because a body-text scan cannot see a lock taken in a
 --    CALLEE and EVERY lock the wrapper takes is in one: board_memberships in grant_board_role's
@@ -708,7 +725,7 @@ select is(
     'onboard_federated_fleet_agent => serialised by the board advisory lock',
     'signed_grant_board_role => serialised by the board advisory lock'
   ]::text[],
-  'every function that row-locks BOTH agents and board_memberships takes the board advisory lock (transitive; a new one names itself)');
+  'every function that EXPLICITLY row-locks both agents and board_memberships takes the board advisory lock (transitive; a new one names itself). FK-implied locks are invisible here and are covered by agent_board_fk_lock_edges.test.sql');
 
 select finish();
 

package/tests/agent_board_source_strip_helper.test.sql

@@ -29,7 +29,7 @@ set search_path = extensions, public, agent_board;
 
 begin;
 
-select plan(31);
+select plan(47);
 
 -- ---------------------------------------------------------------------------
 -- The four demonstrated masking constructs.
@@ -205,6 +205,162 @@ select ok(
     > length(pg_get_functiondef('agent_board.mark_retention_metadata(text,timestamp with time zone,uuid,text)'::regprocedure)) / 4,
   'stripped_def on a body containing a dollar-quoted block keeps the surrounding code rather than collapsing the definition');
 
+-- ===========================================================================
+-- SQL-STANDARD BODIES (`BEGIN ATOMIC` / `RETURN <expr>`) -- message-board#293.
+--
+-- Such a function is PARSED at definition time and stored in pg_proc.prosqlbody;
+-- its prosrc is the EMPTY STRING. stripped_body read prosrc only, so it returned
+-- `''` for one -- and `''` satisfies every `!~` and defeats every `~`, so a writer
+-- spelled that way was invisible to the class assertions in 22 test files at once.
+-- The fixtures below are created INSIDE this rolled-back transaction and live in
+-- agent_board on purpose: the CORPUS assertions further down scan that schema, so
+-- they exercise the fix through a real class scan rather than only through a
+-- direct call.
+-- ===========================================================================
+create table agent_board._mb293_sentinel (id int, note text);
+
+-- (a) the BEGIN ATOMIC form.
+create function agent_board._mb293_atomic_writer(p int) returns void
+language sql
+begin atomic
+  insert into agent_board._mb293_sentinel (id, note) values (p, 'mb293-literal-marker');
+end;
+
+-- (b) the single-expression RETURN form -- the OTHER SQL-standard-body syntax,
+--     equally empty in prosrc. Named separately because a fix that special-cased
+--     the literal string `BEGIN ATOMIC` would pass (a) and fail (b).
+create function agent_board._mb293_atomic_reader() returns bigint
+language sql
+return (select count(*) from agent_board._mb293_sentinel);
+
+-- (c) the prosrc twin: the SAME write, written the ordinary way. Every assertion
+--     about (a) is asserted about (c) too, so a regression in the untouched
+--     prosrc path -- the one the other 21 consumers use -- cannot hide behind a
+--     green BEGIN ATOMIC assertion.
+create function agent_board._mb293_prosrc_writer(p int) returns void
+language sql as $mb$
+  -- mb293-comment-marker: prose naming a thing is not doing it
+  insert into agent_board._mb293_sentinel (id, note) values (p, 'mb293-literal-marker');
+$mb$;
+
+-- (d) a body that is genuinely UNREADABLE: prosrc empty AND prosqlbody null.
+--     Reachable with plain DDL (`as $$$$`), no catalog surgery -- the runner's
+--     role is not superuser. Lives in pg_temp, NOT agent_board, because
+--     stripped_body now RAISES on it and the CORPUS scans below would abort.
+create function pg_temp._mb293_unreadable() returns void language sql as $$$$;
+
+-- PREMISE. Everything below is worthless if the fixtures are not actually the
+-- shape they are named for, so the shape is measured, not assumed.
+select is(
+  (select length(p.prosrc) || '/' || (p.prosqlbody is not null)::text
+     from pg_proc p where p.oid = 'agent_board._mb293_atomic_writer(int)'::regprocedure),
+  '0/true',
+  'SQLBODY PREMISE: the BEGIN ATOMIC fixture really does have an EMPTY prosrc and a non-null prosqlbody -- the condition the old stripped_body read as "this function does nothing"');
+
+-- THE HEADLINE. Pre-fix this returned '' and the assertion was red.
+select ok(
+  agent_board_test.stripped_body('agent_board._mb293_atomic_writer(int)'::regprocedure)
+    ~* 'insert\s+into\s+agent_board\._mb293_sentinel\M',
+  'SQLBODY-1: stripped_body SEES the write in a BEGIN ATOMIC body');
+
+select ok(
+  agent_board_test.stripped_body('agent_board._mb293_atomic_reader()'::regprocedure)
+    ~* 'from\s+agent_board\._mb293_sentinel\M',
+  'SQLBODY-2: the `RETURN <expr>` form is read too -- it is the same prosqlbody shape under different syntax');
+
+-- QUALIFICATION, and why it is a SEPARATE risk rather than a detail of the above.
+-- pg_get_function_sqlbody DEPARSES the stored tree, and the deparser OMITS the
+-- schema for any relation visible on the CURRENT search_path. Every consumer regex
+-- in this suite spells `agent_board\.`, so a fallback deparsed under the session's
+-- search_path would have replaced one fail-open with another. What prevents it is
+-- `SET search_path = pg_catalog` on stripped_body itself. Measured both ways on
+-- PG 17.6: `INSERT INTO agent_board.x` under pg_catalog, `INSERT INTO x` when
+-- agent_board is visible.
+select ok(
+  current_setting('search_path') ~ '\magent_board\M',
+  'SQLBODY-3 (NON-VACUITY for SQLBODY-1/-2): the SESSION search_path really does make agent_board visible, so an unpinned deparse WOULD drop the schema -- the trap is live, not hypothetical');
+
+-- LITERAL SYMMETRY, mirroring MASK 4. A deparsed body carries no author comments
+-- (they are parsed away), but it DOES carry string literals, so the strip must
+-- still apply to it and `p_keep_literals` must still mean what it means.
+select ok(
+  agent_board_test.stripped_body('agent_board._mb293_atomic_writer(int)'::regprocedure)
+    !~ 'mb293-literal-marker',
+  'SQLBODY-4: the default strip removes a string literal from a DEPARSED body too -- strip_sql is applied to it, not bypassed');
+
+select ok(
+  agent_board_test.stripped_body('agent_board._mb293_atomic_writer(int)'::regprocedure, true)
+    ~ 'mb293-literal-marker',
+  'SQLBODY-5: ...and keep-literals mode keeps it, so the two modes are not silently the same function');
+
+-- NON-REGRESSION on the prosrc path, at the same call shape.
+select ok(
+  agent_board_test.stripped_body('agent_board._mb293_prosrc_writer(int)'::regprocedure)
+    ~* 'insert\s+into\s+agent_board\._mb293_sentinel\M',
+  'SQLBODY-6: the ordinary prosrc path still sees its write -- the path the other 21 consumers use is unchanged');
+
+select ok(
+  agent_board_test.stripped_body('agent_board._mb293_prosrc_writer(int)'::regprocedure)
+    !~ 'mb293-comment-marker',
+  'SQLBODY-7: ...and still strips its comments');
+
+-- LOUD, NOT SILENT. There is no value stripped_body can return for a body it
+-- cannot read that a class scan reads correctly: '' satisfies every negative
+-- assertion, and NULL is DROPPED by the `where … ~ …` shape most consumers use.
+-- So it raises. Both raising branches are pinned.
+select is(
+  (select (p.prosrc = '' and p.prosqlbody is null)::text
+     from pg_proc p where p.oid = 'pg_temp._mb293_unreadable()'::regprocedure),
+  'true',
+  'SQLBODY-8 (NON-VACUITY for SQLBODY-9): the unreadable fixture really has an empty prosrc AND a null prosqlbody');
+
+select throws_ok(
+  $$ select agent_board_test.stripped_body('pg_temp._mb293_unreadable()'::regprocedure) $$,
+  null, null,
+  'SQLBODY-9: LOUD -- an unreadable body RAISES instead of returning '''' (which every `!~` accepts) or NULL (which a `where … ~ …` scan drops silently)');
+
+select throws_ok(
+  $$ select agent_board_test.stripped_body(0::oid) $$,
+  null, null,
+  'SQLBODY-10: LOUD -- an oid with no pg_proc row RAISES rather than returning the NULL a zero-row SELECT used to produce');
+
+-- CLASS-SCAN INTEGRATION. The nine assertions above call stripped_body directly.
+-- This one is the shape the 22 consumer files actually use -- a catalog-derived
+-- exact-set scan over agent_board -- and it is the one that shows the BEGIN ATOMIC
+-- writer is now NAMED by such a scan rather than omitted from it.
+select is(
+  (select coalesce(string_agg(p.proname, ', ' order by p.proname), '')
+     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 agent_board_test.stripped_body(p.oid) ~* 'insert\s+into\s+agent_board\._mb293_sentinel\M'),
+  '_mb293_atomic_writer, _mb293_prosrc_writer',
+  'SQLBODY-11: a catalog-derived exact-set writer scan -- the shape every consumer file uses -- now names the BEGIN ATOMIC writer alongside the ordinary one');
+
+-- stripped_def is in the SAME class and is fixed with it: for a BEGIN ATOMIC
+-- function pg_get_functiondef renders the body INLINE, and the old code returned
+-- that definition RAW (literals intact) whenever prosrc was empty.
+select ok(
+  agent_board_test.stripped_def('agent_board._mb293_atomic_writer(int)'::regprocedure)
+    ~* 'insert\s+into\s+agent_board\._mb293_sentinel\M',
+  'SQLBODY-12: stripped_def still contains the BEGIN ATOMIC body -- the splice found it, it was not deleted');
+
+select ok(
+  agent_board_test.stripped_def('agent_board._mb293_atomic_writer(int)'::regprocedure)
+    !~ 'mb293-literal-marker',
+  'SQLBODY-13: stripped_def STRIPS the literals of a BEGIN ATOMIC body -- previously it returned the definition unstripped');
+
+select ok(
+  agent_board_test.stripped_def('agent_board._mb293_atomic_writer(int)'::regprocedure, true)
+    ~ 'mb293-literal-marker',
+  'SQLBODY-14: ...and keep-literals mode keeps them, so SQLBODY-13 is not passing because the body vanished');
+
+select throws_ok(
+  $$ select agent_board_test.stripped_def(0::oid) $$,
+  null, null,
+  'SQLBODY-15: stripped_def is LOUD on a missing oid too -- it used to return NULL');
+
 -- ---------------------------------------------------------------------------
 -- CORPUS (catalog-derived). The vectors above are written by hand and can only
 -- prove what their author thought of. These run the scanner over every live

package/tests/agent_board_task_thread_lock_order.test.sql

@@ -0,0 +1,337 @@
+-- Consiliency/message-board#281 (R1) pgTAP: ONE order for (threads, tasks) --
+-- THREADS BEFORE TASKS -- pinned as a CLASS, plus the guard the reorder could have
+-- broken, plus the behaviour the reorder could have silently changed.
+--
+-- WHY A CLASS AND NOT TWO FUNCTION CHECKS. The #281 triage said reordering
+-- append_task_event alone "removes all 40 rows -- no other explicit lock on either
+-- relation participates". That was true of EXPLICIT locks and false of the fix:
+-- `_upsert_delivery_recipient` takes no explicit lock at all (KEY SHARE on tasks through
+-- delivery_recipients_source_task_id_fkey, then an UPDATE on threads), and moving
+-- append_task_event to threads-first promoted it into the cycle set -- 186 -> 150 with four
+-- rows still on the pair. A hand-written list of "the functions that matter" produced
+-- exactly the wrong list. TT-1 therefore enumerates the class from
+-- agent_board_test.lock_edges() (catalog-derived: pg_constraint / pg_attribute / pg_class
+-- by OID, plus stripped_body regexes -- read that function's header before reading a green
+-- run here as a closure claim), so a NEW function that takes tasks before threads fails and
+-- NAMES ITSELF.
+--
+-- TIES ARE RENDERED, NOT ROUNDED. Six of these functions take both relations in ONE
+-- statement (`create_task`, `acquire_claim`, `add_artifact`, `delegate_task`,
+-- `raise_conflict`, `raise_escalation` -- an insert whose FKs reach both parents). FKL-9's
+-- two-branch `case` maps a tie to its else-branch, which would report those six as
+-- "threads-first" -- a claim the derivation does not support. They are rendered as
+-- `same statement` here, so the assertion says only what it knows.
+--
+-- WHAT IS ASSERTED, AND WHAT IS NOT.
+--   * TT-1/TT-2 are the ORDER. They do not claim, and this file does not claim, that a
+--     deadlock was reachable before the fix: `threads.last_message_sequence`/`updated_at`
+--     are not in any unique index on threads (threads_pkey(id) is the only one), so
+--     `_next_thread_message_sequence`'s UPDATE takes FOR NO KEY UPDATE, which does not
+--     conflict with the FOR KEY SHARE append_task_event takes on threads. The 40 rows were
+--     an over-report of the strongest-mode aggregation. The order is fixed because the
+--     cycle goes live the moment any caller strengthens a mode on either relation.
+--   * TT-6 pins the lock the reorder could have been "simplified" into dropping. A fix that
+--     traded a lock-order disagreement for a duplicate-key race would look greener, not
+--     redder, in every other assertion here.
+--   * TT-8..TT-12 are behaviour. A file that only reads the catalog would pass against a
+--     function that no longer works.
+create extension if not exists pgtap with schema extensions;
+set search_path = extensions, public, agent_board;
+
+begin;
+
+select plan(13);
+
+-- ---------------------------------------------------------------------------
+-- The derivation, materialized once. Same shape as agent_board_fk_lock_edges.test.sql:
+-- `first_path` is the position PATH of the first acquisition (caller offset prepended to
+-- the callee's, so ordering survives nesting); `strongest` is the strongest mode taken
+-- anywhere, which over-reports conflicts rather than under-reporting them.
+-- ---------------------------------------------------------------------------
+create temp table _tt_le on commit drop as select * from agent_board_test.lock_edges();
+
+create temp table _tt_acq on commit drop as
+select fn_oid, fn_name, fn_sig, rel_oid, rel_name,
+       min(path) as first_path,
+       (array_agg(lock_mode order by agent_board_test.row_lock_rank(lock_mode) desc))[1] as strongest
+  from _tt_le
+ group by fn_oid, fn_name, fn_sig, rel_oid, rel_name;
+
+create temp table _tt_ord on commit drop as
+select distinct h.fn_name || ': ' ||
+       case when h.first_path < t.first_path
+              then 'threads(' || h.strongest || ') then tasks(' || t.strongest || ')'
+            when t.first_path < h.first_path
+              then 'tasks(' || t.strongest || ') then threads(' || h.strongest || ')'
+            else 'same statement: threads(' || h.strongest || ') + tasks(' || t.strongest || ')' end as m,
+       (t.first_path < h.first_path) as tasks_first
+  from _tt_acq h
+  join _tt_acq t on t.fn_oid = h.fn_oid and t.fn_sig = h.fn_sig
+ where h.rel_name = 'agent_board.threads'
+   and t.rel_name = 'agent_board.tasks';
+
+-- ===========================================================================
+-- TT-1: THE CLASS. Every function whose lock graph contains BOTH threads and tasks, with
+-- the order it takes them. NOT ONE says `tasks(...) then threads(...)`, and that is the
+-- whole content of the #281 R1 fix. Asserted as an EXACT SET rather than as "none is
+-- tasks-first", because an exact set cannot pass vacuously if the derivation breaks, and a
+-- new member fails here carrying its own name and order.
+-- ===========================================================================
+select is(
+  (select array_agg(m order by m) from _tt_ord),
+  array[
+    '_upsert_delivery_recipient: threads(update) then tasks(key share)',
+    'acquire_claim: same statement: threads(key share) + tasks(update)',
+    'add_artifact: same statement: threads(key share) + tasks(update)',
+    'append_task_event: threads(key share) then tasks(update)',
+    'create_task: same statement: threads(key share) + tasks(key share)',
+    'create_tasking_delivery: same statement: threads(update) + tasks(key share)',
+    'delegate_task: same statement: threads(key share) + tasks(update)',
+    'post_board_message: threads(update) then tasks(key share)',
+    'post_message: threads(update) then tasks(key share)',
+    'raise_conflict: same statement: threads(key share) + tasks(update)',
+    'raise_escalation: same statement: threads(key share) + tasks(update)',
+    'resolve_conflict: threads(key share) then tasks(update)',
+    'resolve_escalation: threads(key share) then tasks(update)',
+    'send_direct_message: threads(update) then tasks(key share)',
+    'send_multicast_message: threads(update) then tasks(key share)',
+    'signed_append_task_event: threads(key share) then tasks(update)',
+    'signed_create_tasking_delivery: same statement: threads(update) + tasks(key share)',
+    'signed_post_board_message: threads(update) then tasks(key share)',
+    'signed_send_direct_message: threads(update) then tasks(key share)',
+    'signed_send_multicast_message: threads(update) then tasks(key share)'
+  ]::text[],
+  'TT-1: the threads+tasks lock class, FK edges included -- every member is threads-first or single-statement');
+
+-- ===========================================================================
+-- TT-2: the same claim as a scalar, with its DENOMINATOR attached. "0 tasks-first" alone
+-- is an absence and would read green against an empty derivation; the member count makes
+-- the assertion say how many functions it actually examined to get there.
+-- ===========================================================================
+select is(
+  (select count(*)::text || ' functions acquire both; '
+          || count(*) filter (where tasks_first)::text || ' take tasks before threads'
+     from _tt_ord),
+  '20 functions acquire both; 0 take tasks before threads',
+  'TT-2: 20 functions acquire both relations and NONE takes tasks before threads');
+
+-- ===========================================================================
+-- TT-3: append_task_event's acquisitions on the two relations, in path order, with mode
+-- and provenance. The FIRST is the hoisted `threads ... for key share` (via `textual`, i.e.
+-- schedulable), before the tasks FOR UPDATE. The two `fk-insert` edges are the task_events
+-- insert's own FKs -- they are what made the old order invisible to a text scan.
+-- ===========================================================================
+select is(
+  (select string_agg(e.rel_name || ' ' || e.lock_mode || ' via ' || e.via, ' -> '
+                     order by e.path, e.rel_name, e.lock_mode, e.via)
+     from _tt_le e
+    where e.fn_name = 'append_task_event'
+      and e.rel_name in ('agent_board.tasks', 'agent_board.threads')),
+  'agent_board.threads key share via textual'
+  || ' -> agent_board.tasks update via textual'
+  || ' -> agent_board.tasks key share via fk-insert:task_events_task_id_fkey'
+  || ' -> agent_board.threads key share via fk-insert:task_events_thread_id_fkey'
+  || ' -> agent_board.tasks update via write-update',
+  'TT-3: append_task_event takes threads(KEY SHARE, explicit) FIRST, then the tasks FOR UPDATE');
+
+-- ===========================================================================
+-- TT-4: THE PREMISE THE PRE-READ RESTS ON. append_task_event now reads tasks.thread_id
+-- WITHOUT a lock in order to know which threads row to take first. That is only sound
+-- because no function in the bundle ever re-points tasks.thread_id -- an FK re-point is
+-- reported by the detector as a `fk-update:` edge (FKL-14), so this is catalog-derived and
+-- names the offender rather than trusting a grep. The constraint's existence is asserted in
+-- the SAME string: if tasks_thread_id_fkey were dropped or renamed, "no fk-update edges"
+-- would go on passing while meaning nothing.
+-- ===========================================================================
+select is(
+  (select (select coalesce(string_agg(distinct e.fn_name, ', ' order by e.fn_name), '<none>')
+             from _tt_le e where e.via = 'fk-update:tasks_thread_id_fkey')
+          || ' / ' ||
+          (select coalesce(string_agg(c.conname, ', '), '<missing>')
+             from pg_constraint c
+            where c.conrelid = 'agent_board.tasks'::regclass
+              and c.contype = 'f'
+              and c.confrelid = 'agent_board.threads'::regclass)),
+  '<none> / tasks_thread_id_fkey',
+  'TT-4: no function re-points tasks.thread_id, and the FK that would report one exists');
+
+-- ===========================================================================
+-- TT-5: the constraint the tasks FOR UPDATE exists to serialise against. If this were
+-- dropped, append_task_event's sequence computation would stop being a race and start
+-- being a silent duplicate -- and TT-9 would go on passing, because it is sequential.
+-- ===========================================================================
+select is(
+  (select c.conname || ' ' || pg_get_constraintdef(c.oid)
+     from pg_constraint c
+    where c.conrelid = 'agent_board.task_events'::regclass
+      and c.contype = 'u'),
+  'task_events_task_id_event_sequence_key UNIQUE (task_id, event_sequence)',
+  'TT-5: task_events still carries the (task_id, event_sequence) uniqueness the lock guards');
+
+-- ===========================================================================
+-- TT-6: THE LOCK THAT WAS NOT DROPPED. The cheapest way to "fix" this cycle is to delete
+-- append_task_event's `for update` -- which trades an ordering disagreement for a live
+-- duplicate-key race and makes every other assertion in this file greener. Pinned
+-- positively: an EXPLICIT (`textual`) lock on tasks, in `update` mode, is still taken.
+-- `write-update` is excluded on purpose -- the function's own later UPDATE would satisfy a
+-- mode-only check and hide the deletion.
+-- ===========================================================================
+select is(
+  (select coalesce(string_agg(distinct e.lock_mode, ', ' order by e.lock_mode), '<none>')
+     from _tt_le e
+    where e.fn_name = 'append_task_event'
+      and e.rel_name = 'agent_board.tasks'
+      and e.via = 'textual'),
+  'update',
+  'TT-6: append_task_event still takes an EXPLICIT FOR UPDATE on tasks -- the sequence guard is intact');
+
+-- ===========================================================================
+-- TT-7: the second half of the fix, on its own. `_upsert_delivery_recipient` has no
+-- explicit lock at all, so it is invisible to every textual lock-order guard in this repo;
+-- its order is entirely a statement order. The OBSGATE (#78) threads stamp must precede the
+-- delivery_recipients insert whose FK reaches tasks.
+-- ===========================================================================
+select is(
+  (select string_agg(e.rel_name || ' ' || e.lock_mode || ' via ' || e.via, ' -> ' order by e.path)
+     from _tt_le e
+    where e.fn_name = '_upsert_delivery_recipient'
+      and e.rel_name in ('agent_board.tasks', 'agent_board.threads')),
+  'agent_board.threads update via write-update'
+  || ' -> agent_board.tasks key share via fk-insert:delivery_recipients_source_task_id_fkey',
+  'TT-7: _upsert_delivery_recipient stamps threads BEFORE the insert that FK-locks tasks');
+
+-- ===========================================================================
+-- BEHAVIOUR. Everything above reads the catalog and would pass against a function that no
+-- longer runs.
+--
+-- EVERY ALLOW-SIDE ASSERTION IS lives_ok() PLUS A SEPARATE STATE CHECK, never
+-- `is((select ... from rpc(...)), ...)`. The bare form ABORTS the transaction on a raise
+-- instead of failing the assertion, and pgTAP then emits NO `not ok` at all -- the file
+-- simply stops, and a summary-line reader calls that a pass (#113).
+--
+-- The fixture is: a board with a member and an observer; a board-linked thread carrying one
+-- task; and a SECOND board plus a board-LESS thread carrying its own task, which TT-12/13
+-- need in order to observe a stamp actually being written rather than a no-op.
+-- ===========================================================================
+create temp table _tt_fixture (
+  board uuid, board2 uuid, actor uuid, observer uuid,
+  thread uuid, task uuid, free_thread uuid, free_task uuid,
+  actor_user uuid, observer_user uuid, membership uuid, membership2 uuid
+) on commit drop;
+
+do $$
+declare
+  v_suffix text := replace(substr(gen_random_uuid()::text, 1, 8), '-', '');
+  v_actor_user uuid; v_observer_user uuid;
+  v_creator uuid := gen_random_uuid();
+  v_actor uuid := gen_random_uuid();
+  v_observer uuid := gen_random_uuid();
+  v_board uuid; v_board2 uuid; v_membership uuid; v_membership2 uuid;
+  v_thread uuid := gen_random_uuid(); v_task uuid;
+  v_free_thread uuid := gen_random_uuid(); v_free_task uuid;
+begin
+  v_actor_user := public.ensure_github_user('tt-actor-' || v_suffix, 'tt-actor-' || v_suffix || '@example.test', 'tt-actor-' || v_suffix, 'TT Actor');
+  v_observer_user := public.ensure_github_user('tt-obs-' || v_suffix, 'tt-obs-' || v_suffix || '@example.test', 'tt-obs-' || v_suffix, 'TT Observer');
+
+  insert into agent_board.agents(id, agent_type, handle, display_name, status, auth_user_id, owner_user_id)
+  values
+    (v_creator, 'agent', 'tt-creator-' || v_suffix, 'TT Creator', 'active', null, null),
+    (v_actor, 'agent', 'tt-actor-' || v_suffix, 'TT Actor', 'active', v_actor_user, v_actor_user),
+    (v_observer, 'agent', 'tt-obs-' || v_suffix, 'TT Observer', 'active', v_observer_user, v_observer_user);
+
+  select board_id into v_board
+    from agent_board.create_board(v_creator, 'tt-board-' || v_suffix, 'TT Board', 'task/thread lock order', '{}'::jsonb, 'private');
+  select board_id into v_board2
+    from agent_board.create_board(v_creator, 'tt-board2-' || v_suffix, 'TT Board 2', 'second board', '{}'::jsonb, 'private');
+
+  insert into agent_board.board_memberships(board_id, agent_id, membership_state, created_by_agent_id, role)
+  values (v_board, v_actor, 'joined', v_creator, 'member')
+  returning id into v_membership;
+  insert into agent_board.board_memberships(board_id, agent_id, membership_state, created_by_agent_id, role)
+  values (v_board, v_observer, 'joined', v_creator, 'observer');
+  -- delivery_recipients carries a COMPOSITE fk (board_membership_id, board_id,
+  -- recipient_agent_id), so the second-board delivery in TT-12 needs the actor to hold a
+  -- membership on THAT board too.
+  insert into agent_board.board_memberships(board_id, agent_id, membership_state, created_by_agent_id, role)
+  values (v_board2, v_actor, 'joined', v_creator, 'member')
+  returning id into v_membership2;
+
+  insert into agent_board.threads(id, thread_type, created_by_agent_id, subject)
+  values (v_thread, 'coordination', v_actor, 'TT board thread'),
+         (v_free_thread, 'coordination', v_actor, 'TT board-less thread');
+
+  perform set_config('request.jwt.claim.role', 'authenticated', true);
+  perform set_config('request.jwt.claim.sub', v_actor_user::text, true);
+  -- Links v_thread to v_board through the delivery fan-out, which is the only writer of
+  -- threads.board_id -- i.e. through the very statement this change hoisted.
+  perform agent_board.post_board_message(v_thread, v_actor, v_board, 'seed', 'seed body');
+  select task_id into v_task from agent_board.create_task(v_thread, v_actor, 'tt task', 'd');
+  select task_id into v_free_task from agent_board.create_task(v_free_thread, v_actor, 'tt free task', 'd');
+
+  insert into _tt_fixture values (v_board, v_board2, v_actor, v_observer, v_thread, v_task,
+                                  v_free_thread, v_free_task, v_actor_user, v_observer_user,
+                                  v_membership, v_membership2);
+end
+$$;
+
+-- TT-8: the reordered function still runs. lives_ok, not a value comparison -- a raise here
+-- must fail THIS assertion, not abort the file.
+select lives_ok(
+  $$ select * from agent_board.append_task_event(
+       (select task from _tt_fixture), (select actor from _tt_fixture), 'commented') $$,
+  'TT-8: append_task_event still runs after the reorder (lives_ok, so a raise fails here)');
+
+-- TT-9: the state TT-8 wrote. `create_task` inserts task_events seq 1 directly, so the
+-- append is seq 2, and its thread_id is the task's own thread -- the value the unlocked
+-- pre-read supplied and the FOR UPDATE re-read confirmed. Sequential, so this does NOT
+-- prove the concurrency guard; that is the isolation spec's permutation 3.
+select is(
+  (select string_agg(te.event_sequence::text || ':' || te.event_type
+                     || ':' || (te.thread_id = f.thread)::text, ' ' order by te.event_sequence)
+     from agent_board.task_events te, _tt_fixture f
+    where te.task_id = f.task),
+  '1:created:true 2:commented:true',
+  'TT-9: the append landed as seq 2 carrying the task''s own thread_id');
+
+-- TT-10: the P0002 the pre-read raises for an unknown task, BEFORE any lock is taken.
+select throws_ok(
+  $$ select * from agent_board.append_task_event(
+       '00000000-0000-4000-8000-0000000000ff'::uuid,
+       (select actor from _tt_fixture), 'commented') $$,
+  'P0002',
+  'task not found',
+  'TT-10: an unknown task still raises P0002 from the pre-read, before any row lock');
+
+-- TT-11: the OBSGATE-3 (#125) gate still denies a board observer that is not a party to the
+-- task. The reorder moved two statements ABOVE this gate; if it had moved the gate itself,
+-- this is where that shows.
+select throws_ok(
+  $$ select set_config('request.jwt.claim.sub', (select observer_user from _tt_fixture)::text, true);
+     select * from agent_board.append_task_event(
+       (select task from _tt_fixture), (select observer from _tt_fixture), 'commented') $$,
+  '42501',
+  'task mutation requires a non-observer board role, or task assignment/creation',
+  'TT-11: a board observer that is not a party to the task is still denied');
+
+-- TT-12: the hoisted OBSGATE (#78) stamp still runs. service_role -- the helper is
+-- service_role-only by grant. Two calls: one that must STAMP (board-less thread), one that
+-- must NOT overwrite (same thread, different board).
+select lives_ok(
+  $$ select set_config('request.jwt.claim.role', 'service_role', true);
+     select agent_board._upsert_delivery_recipient('tasking', f.actor, 'task', null,
+              f.free_task, null, f.board, f.membership) from _tt_fixture f;
+     select agent_board._upsert_delivery_recipient('tasking', f.actor, 'task', null,
+              f.free_task, null, f.board2, f.membership2) from _tt_fixture f $$,
+  'TT-12: the hoisted stamp runs for both a first and a second board delivery');
+
+-- TT-13: the state TT-12 wrote -- first-board-wins survived the hoist. `false` on the
+-- second element would mean the reorder turned the stamp into an overwrite.
+select is(
+  (select (t.board_id = f.board)::text || '/' || (t.board_id = f.board2)::text
+     from agent_board.threads t, _tt_fixture f where t.id = f.free_thread),
+  'true/false',
+  'TT-13: the board-less thread was stamped with the FIRST board and not overwritten by the second');
+
+select * from finish();
+
+rollback;

package/tests/catalog/p_metadata_parameters.json

@@ -17,6 +17,14 @@
       "signature": "_addressing_descriptors_array(p_descriptors jsonb)",
       "declares_p_metadata": false
     },
+    {
+      "signature": "_agent_can_access_thread(p_thread_id uuid, p_agent_id uuid)",
+      "declares_p_metadata": false
+    },
+    {
+      "signature": "_agent_has_board_access(p_board_id uuid, p_agent_id uuid)",
+      "declares_p_metadata": false
+    },
     {
       "signature": "_agent_principal_active(p_agent_id uuid)",
       "declares_p_metadata": false
@@ -133,6 +141,10 @@
       "signature": "_ensure_agent_auth_user(p_slug text)",
       "declares_p_metadata": false
     },
+    {
+      "signature": "_federated_identity_slug(p_issuer text, p_subject text)",
+      "declares_p_metadata": false
+    },
     {
       "signature": "_fedsession_autojoin_default_board(p_provider agent_board.identity_providers, p_agent_id uuid)",
       "declares_p_metadata": false