@consiliency/agent-board-schema 1.28.0 → 1.38.0

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

package/tests/fixtures/isolation-substrate.sql

@@ -1,7 +1,7 @@
 -- Minimal Supabase substrate for the two-session ISOLATION harness only.
 --
 -- The pgTAP runner applies the agent_board bundle onto the DB that `supabase
--- start` provisions (54322/postgres), which already carries GoTrue's `auth`
+-- start` provisions (24322/postgres), which already carries GoTrue's `auth`
 -- schema, the `extensions` schema, pgcrypto, and the base roles. The isolation
 -- harness instead builds a THROWAWAY template database (specs COMMIT across
 -- sessions and cannot share the live DB), so it must self-provision the same

package/tests/fixtures/test-prereqs.sql

@@ -359,18 +359,74 @@ COMMENT ON FUNCTION agent_board_test.strip_sql(text, boolean) IS
 
 -- The stripped BODY of a function. This is what a positional or negative
 -- assertion should read.
+--
+-- TWO BODY COLUMNS, NOT ONE (message-board#293). A function written with an
+-- SQL-standard body -- `LANGUAGE sql BEGIN ATOMIC … END`, or the single-expression
+-- `LANGUAGE sql RETURN …` form -- is PARSED at definition time and stored in
+-- pg_proc.prosqlbody; its prosrc is the EMPTY STRING (measured on PG 17.6, not
+-- inferred: `select length(prosrc), prosqlbody is null` over such a function
+-- returns `0, false`). Reading prosrc alone therefore handed back `''` for it, and
+-- `''` satisfies every `!~` in this suite and defeats every `~` -- so a writer
+-- spelled that way was invisible to ~22 test files' class assertions at once,
+-- INCLUDING the catalog-derived ones whose whole job is to name a new member of a
+-- class. That is the fail-OPEN direction, and it is the exact shape CLAUDE.md
+-- rule 1 bans.
+--
+-- WHY IT RAISES INSTEAD OF FALLING BACK TO ''. message-board#293 suggested
+-- `coalesce(nullif(prosrc,''), pg_get_function_sqlbody(oid), '')`. The third arm
+-- REBUILDS the defect one level down: an unreadable body would again come back as
+-- `''` and again satisfy every negative assertion. NULL is no better -- an `is()`
+-- would surface it, but the dominant consumer shape in this suite is
+-- `where … stripped_body(p.oid) ~ '<pattern>'`, and a NULL there silently DROPS
+-- the row from the scan, which is the same fail-open wearing a different hat.
+-- There is no value this function can return for a body it cannot read that a
+-- class scan reads correctly, so it raises. The population is empty today by
+-- construction (`select count(*) from pg_proc where prosrc = '' and prosqlbody is
+-- null` is 0 across the WHOLE catalog on this cluster, internal/C functions
+-- included -- their prosrc is the symbol name), so the raise is a tripwire, not a
+-- hazard. A missing pg_proc row raises for the same reason: the old form returned
+-- NULL from a zero-row SELECT.
+--
+-- WHY `SET search_path = pg_catalog` IS LOAD-BEARING HERE, not decoration.
+-- pg_get_function_sqlbody DEPARSES the stored parse tree, and the deparser omits
+-- the schema for any relation that is visible on the CURRENT search_path. Measured:
+-- the same function deparses as `INSERT INTO agent_board.x` under
+-- `search_path = pg_catalog` and as `INSERT INTO x` under a search_path containing
+-- agent_board -- and every consumer regex in this suite spells `agent_board\.`.
+-- Without this SET the fix would have been a NEW fail-open. Pinned positively by
+-- the QUAL assertion in agent_board_source_strip_helper.test.sql, whose fixture
+-- runs with agent_board ON the session search_path so the trap is live.
 CREATE OR REPLACE FUNCTION agent_board_test.stripped_body(
   p_fn            oid,
   p_keep_literals boolean DEFAULT false
 ) RETURNS text
-LANGUAGE sql
+LANGUAGE plpgsql
 STABLE
 SET search_path = pg_catalog
-AS $$
-  SELECT agent_board_test.strip_sql(p.prosrc, p_keep_literals)
-    FROM pg_proc p
-   WHERE p.oid = p_fn;
-$$;
+AS $strippedbody$
+declare
+  v_src text;
+begin
+  -- prosrc for a SQL-standard body is '' (not NULL), so nullif() -- not
+  -- coalesce() alone -- is what selects the prosqlbody arm.
+  select coalesce(nullif(p.prosrc, ''), pg_catalog.pg_get_function_sqlbody(p.oid))
+    into v_src
+    from pg_proc p
+   where p.oid = p_fn;
+
+  if not found then
+    raise exception
+      'agent_board_test.stripped_body: no pg_proc row for oid % -- refusing to return NULL, which a `where … ~ …` class scan drops SILENTLY', p_fn;
+  end if;
+
+  if v_src is null or v_src = '' then
+    raise exception
+      'agent_board_test.stripped_body: oid % has neither a prosrc body nor a prosqlbody body -- refusing to return an unreadable body that would satisfy every negative assertion', p_fn;
+  end if;
+
+  return agent_board_test.strip_sql(v_src, p_keep_literals);
+end;
+$strippedbody$;
 
 -- The stripped FULL DEFINITION. The header (`SECURITY DEFINER`, `SET
 -- search_path = …`, the argument list) is regenerated by Postgres from catalog
@@ -381,6 +437,27 @@ $$;
 -- the body is wrapped in a dollar quote (`AS $function$ … $function$`), so a
 -- dollar-quote-aware strip would delete THE ENTIRE BODY and every `!~` over the
 -- result would pass. Splicing avoids that trap by construction.
+--
+-- IN THE SAME CLASS AS stripped_body (message-board#293), and fixed here for that
+-- reason rather than left as "the other one". For a `BEGIN ATOMIC` function prosrc
+-- is '', so the old `if v_src is null or v_src = '' then return v_def` arm handed
+-- back the RAW generated definition with its string literals INTACT -- and
+-- pg_get_functiondef renders such a body INLINE (`… LANGUAGE sql BEGIN ATOMIC …
+-- END`, measured), so the literals really are in the returned text. A positive
+-- claim in default mode could then be satisfied by a literal instead of by code.
+-- Narrower than the stripped_body hole, same direction, so it splices the
+-- DEPARSED body instead; the substring is verbatim inside the definition because
+-- both come from the same deparse under the same pinned search_path (measured:
+-- `position(pg_get_function_sqlbody(o) in pg_get_functiondef(o))` is non-zero for
+-- both the BEGIN ATOMIC and the `RETURN <expr>` form, and the pre-existing
+-- `v_at = 0` arm still refuses to guess if that ever stops holding).
+--
+-- The `return null` arm for a missing oid is gone for the same reason
+-- stripped_body raises: a NULL is dropped silently by a `where … !~ …` scan.
+-- This is a deliberate contract change, stated rather than slipped in; the only
+-- live callers are in agent_board_source_strip_helper.test.sql (the #196 lint
+-- forbids stripped_def in any other test file's assertions without an explicit
+-- `-- header-claim`, and that set is empty).
 CREATE OR REPLACE FUNCTION agent_board_test.stripped_def(
   p_fn            oid,
   p_keep_literals boolean DEFAULT false
@@ -393,19 +470,45 @@ declare
   v_def  text;
   v_src  text;
   v_at   int;
+  v_hits int;
 begin
-  select pg_get_functiondef(p.oid), p.prosrc into v_def, v_src
+  select pg_get_functiondef(p.oid),
+         coalesce(nullif(p.prosrc, ''), pg_catalog.pg_get_function_sqlbody(p.oid))
+    into v_def, v_src
     from pg_proc p where p.oid = p_fn;
-  if v_def is null then
-    return null;
+  if not found or v_def is null then
+    raise exception
+      'agent_board_test.stripped_def: no readable definition for oid % -- refusing to return NULL, which a `where … !~ …` class scan drops SILENTLY', p_fn;
   end if;
   if v_src is null or v_src = '' then
-    return v_def;
+    raise exception
+      'agent_board_test.stripped_def: oid % has neither a prosrc body nor a prosqlbody body -- refusing to return an unstripped definition', p_fn;
   end if;
   v_at := position(v_src in v_def);
   if v_at = 0 then
     raise exception
-      'agent_board_test.stripped_def: prosrc not found verbatim inside pg_get_functiondef for oid % -- refusing to guess', p_fn;
+      'agent_board_test.stripped_def: body not found verbatim inside pg_get_functiondef for oid % -- refusing to guess', p_fn;
+  end if;
+  -- AMBIGUITY (message-board#304). `position()` returns the FIRST match, and
+  -- pg_get_functiondef emits AUTHOR-CONTROLLED text -- the function name, every
+  -- argument name, the SET clauses -- BEFORE the body. When a short body also
+  -- occurs in that header, the splice lands on the HEADER occurrence: the header
+  -- is corrupted and the real body is returned UNSTRIPPED, so a positive or
+  -- negative assertion over the result reads text that was never stripped. Not
+  -- hypothetical: a `mint_harden` assertion was already defeated once by an
+  -- argument named `p_raw_key_fingerprint` (the #196 lint's rule 3), so header
+  -- text is a live surface. The BEGIN ATOMIC arm above makes this MORE likely,
+  -- not less: a deparsed body is short and normalized (`RETURN (p + 1)`).
+  --
+  -- Anchoring on the last occurrence instead would still be a GUESS about which
+  -- match is the body. The `v_at = 0` arm already refuses to guess when the body
+  -- is not found; ambiguity gets the same answer, matching strip_sql's
+  -- fail-closed behaviour on an unterminated construct. `replace` counts
+  -- non-overlapping occurrences, which is the count that matters for a splice.
+  v_hits := (length(v_def) - length(replace(v_def, v_src, ''))) / length(v_src);
+  if v_hits > 1 then
+    raise exception
+      'agent_board_test.stripped_def: body occurs % times inside pg_get_functiondef for oid % — ambiguous splice, refusing to guess which occurrence is the body (a match in the author-controlled header would corrupt it and return the body unstripped)', v_hits, p_fn;
   end if;
   return substr(v_def, 1, v_at - 1)
       || agent_board_test.strip_sql(v_src, p_keep_literals)
@@ -427,4 +530,332 @@ AS $$
   SELECT agent_board_test.strip_sql(pg_get_viewdef(p_rel), p_keep_literals);
 $$;
 
+-- ===========================================================================
+-- FK-AWARE LOCK-EDGE DETECTOR (message-board#281)
+--
+-- WHY THIS EXISTS. Every lock-order guard in this repo up to now found locks by
+-- scanning a function body for the literal text `for update` / `for share`. A
+-- lock that PostgreSQL takes on our behalf through a FOREIGN KEY never appears
+-- in that text, so those guards are structurally blind to it -- and the blind
+-- spot already contains an ABBA. `_upsert_board_membership_state` takes
+-- `board_memberships FOR UPDATE` and then, via `_emit_membership_event`'s INSERT
+-- into `board_membership_events`, `agents FOR KEY SHARE` through
+-- `board_membership_events_agent_id_fkey`. It never NAMES `agents`.
+-- `onboard_federated_fleet_agent` takes those two relations in the opposite
+-- order with `FOR UPDATE`, which KEY SHARE conflicts with.
+--
+-- WHAT IS CATALOG-DERIVED, AND WHAT IS NOT. Being exact about this is the point;
+-- a detector that silently under-reports is worse than none, because it will be
+-- trusted.
+--   CATALOG (pg_constraint / pg_attribute / pg_class, resolved by OID, never by
+--   a rendered name -- `regclass::text` drops the schema for anything on
+--   search_path): which tables have foreign keys, to what, on which columns,
+--   with what ON DELETE action. So a NEW foreign key is covered the day it is
+--   added, with nothing here to update.
+--   REGEX over agent_board_test.stripped_body(): which tables a function WRITES,
+--   which explicit row locks it takes, and which functions it calls. plpgsql
+--   bodies carry no catalog-level table dependencies, so nothing stronger exists
+--   without a parser. Reading the STRIPPED body (not prosrc) is what stops a
+--   comment or a string literal from manufacturing an edge.
+--
+-- THE SIX ACQUISITION SHAPES. Each has a named mutation pin in
+-- agent_board_fk_lock_edges.test.sql; a shape with no pin is not in this list.
+--   (i)   `textual`      -- an explicit `for update|no key update|share|key share`
+--                           in any statement shape, mode captured (NOT anchored on
+--                           `where`: `from boards b join ... for update of b` is a
+--                           real acquisition);
+--   (ii)  `write-update` -- `update T ... set` row-locks T itself. Recorded as
+--                           `update`; PostgreSQL takes the weaker FOR NO KEY UPDATE
+--                           when no key column changes, so this is fail-CLOSED;
+--   (iii) `write-delete` -- `delete from T` row-locks the T rows it removes;
+--   (iv)  `fk-insert`    -- an INSERT into T takes FOR KEY SHARE on the referenced
+--                           row of EVERY foreign key of T. This is the shape that
+--                           no body scan can see, and the reason for this file;
+--   (v)   `fk-update`    -- an `update T ... set <col> = ...` where <col> is in some
+--                           FK's conkey re-checks that key and locks the NEW parent.
+--                           Gated on the SET naming a conkey column derived from
+--                           pg_attribute, NOT on "T has FKs" -- crediting every
+--                           UPDATE with every parent lock fabricates cycle members;
+--   (vi)  `fk-delete`    -- deleting a REFERENCED row locks the referencing child
+--                           rows; the mode follows confdeltype (cascade => the child
+--                           row is deleted, set null/default => it is updated,
+--                           no action/restrict => FOR KEY SHARE).
+--
+-- CALL GRAPH. Closed over transitively, because every lock a wrapper takes is
+-- usually in a callee. Each edge carries a POSITION PATH (`path int[]`): the
+-- caller's call-site offset prepended to the callee's own offset, so ordering
+-- survives nesting. Comparing bare offsets across frames is wrong -- two
+-- acquisitions reached through the SAME call site would tie, and the ordering that
+-- decides the cycle lives one frame down. Recursion in the (name-resolved,
+-- over-approximated) call graph is cut by the SQL:2023 CYCLE clause.
+--
+-- WHAT IT DOES NOT COVER, stated so a green run is read for what it is:
+--   * DYNAMIC SQL. An EXECUTE of a computed string is unreadable here. Pinned
+--     fail-closed: FKL-11 fails the suite the day any function with a lock edge
+--     acquires one.
+--   * LOCKS TAKEN BY TRIGGERS on a written table. Not folded in. Pinned instead
+--     by FKL-12, which asserts that no trigger function on an agent_board table
+--     has ANY lock edge -- true today, and loud the day it stops being.
+--   * INSERT/INSERT contention on a UNIQUE index. A second inserter of the same
+--     key blocks on the first and can be a deadlock participant, but it is not a
+--     row lock and has no mode.
+--   * an UPDATE of a PARENT's referenced key columns, which fires the same child
+--     RI checks as (vi). Our referenced keys are immutable uuid surrogates.
+--   * NULL FK columns. A null takes no parent lock; every fk-* edge is credited
+--     unconditionally, which over-reports rather than under-reports.
+--   * RUNTIME vs POSITIONAL order. Positions are read over statements AS WRITTEN;
+--     two acquisitions in mutually exclusive IF branches are treated as sequential.
+--   * OVERLOAD RESOLUTION. Call edges are name-resolved, so every overload sharing
+--     a proname is one callee -- over-connecting, which is safe for membership and
+--     fail-open for a positional claim.
+--   * `BEGIN ATOMIC` bodies. These are now READ (message-board#293:
+--     stripped_body falls back to the deparsed prosqlbody), but what is read is a
+--     DEPARSED tree, and the positional/`path` semantics this detector builds on
+--     are only exercised against author-written text. So the FKL-6 tripwire --
+--     `no agent_board function has a prosqlbody` -- is deliberately KEPT: it is no
+--     longer "unreadable", it is "readable but unexercised". (An earlier version of
+--     this line cited FKL-10, which is the ABBA-pair assertion; the tripwire is
+--     FKL-6.)
+-- ===========================================================================
+
+-- PostgreSQL row-level lock conflict matrix (Concurrency Control -> Row-Level
+-- Locks). The cycle enumeration is USELESS without it: over a schema this
+-- FK-dense, a mode-blind ABBA search reports every pair of functions that insert
+-- into two tables in opposite order, and two FOR KEY SHARE locks never conflict.
+CREATE OR REPLACE FUNCTION agent_board_test.row_locks_conflict(p_a text, p_b text)
+RETURNS boolean
+LANGUAGE sql IMMUTABLE
+SET search_path = pg_catalog
+AS $$
+  --          KEY SHARE  SHARE  NO KEY UPDATE  UPDATE
+  -- KEY SHARE     .       .          .          X
+  -- SHARE         .       .          X          X
+  -- NO KEY UPD    .       X          X          X
+  -- UPDATE        X       X          X          X
+  SELECT CASE
+    WHEN p_a IS NULL OR p_b IS NULL THEN true          -- unknown: fail closed
+    WHEN p_a = 'update' OR p_b = 'update' THEN true
+    WHEN p_a = 'no key update' THEN p_b IN ('no key update', 'share')
+    WHEN p_a = 'share' THEN p_b = 'no key update'
+    WHEN p_a = 'key share' THEN false
+    ELSE true                                          -- unrecognised: fail closed
+  END;
+$$;
+
+-- Strength order, used to pick the strongest mode a function takes on a relation.
+-- An unrecognised mode ranks HIGHEST so it cannot be discarded silently.
+CREATE OR REPLACE FUNCTION agent_board_test.row_lock_rank(p_mode text)
+RETURNS int
+LANGUAGE sql IMMUTABLE
+SET search_path = pg_catalog
+AS $$
+  SELECT CASE p_mode
+           WHEN 'key share' THEN 1
+           WHEN 'share' THEN 2
+           WHEN 'no key update' THEN 3
+           WHEN 'update' THEN 4
+           ELSE 5
+         END;
+$$;
+
+-- One row per (function, relation, acquisition). `own` distinguishes an
+-- acquisition written in the function's own body from one reached through a
+-- callee; `origin_name` names the function the acquisition actually lives in.
+CREATE OR REPLACE FUNCTION agent_board_test.lock_edges()
+RETURNS TABLE (
+  fn_oid      oid,
+  fn_name     text,
+  fn_sig      text,
+  rel_oid     oid,
+  rel_name    text,
+  lock_mode   text,
+  via         text,
+  path        int[],
+  own         boolean,
+  origin_oid  oid,
+  origin_name text
+)
+LANGUAGE sql STABLE
+SET search_path = pg_catalog
+AS $lockedges$
+WITH RECURSIVE
+fns AS (
+  SELECT p.oid,
+         p.proname,
+         p.proname || '(' || pg_get_function_identity_arguments(p.oid) || ')' AS sig,
+         agent_board_test.stripped_body(p.oid) AS body,
+         p.proconfig
+    FROM pg_proc p
+    JOIN pg_namespace n ON n.oid = p.pronamespace
+   WHERE n.nspname = 'agent_board'
+     AND p.prokind IN ('f', 'p')
+     AND p.prolang <> (SELECT oid FROM pg_language WHERE lanname = 'internal')
+),
+-- Resolve BARE names the way PostgreSQL would. A function pinning search_path
+-- WITHOUT agent_board cannot reach these tables unqualified, so bare matches are
+-- not attributed to it. No search_path setting at all is treated as bare-resolving,
+-- which over-approximates membership rather than under-approximating it.
+q AS (
+  SELECT f.oid, f.proname, f.sig, f.body,
+         CASE WHEN NOT EXISTS (SELECT 1 FROM unnest(coalesce(f.proconfig, '{}')) c
+                                WHERE c LIKE 'search\_path=%')
+              OR EXISTS (SELECT 1 FROM unnest(f.proconfig) c
+                          WHERE c LIKE 'search\_path=%'
+                            AND ',' || replace(replace(split_part(c, '=', 2), ' ', ''), '"', '') || ','
+                                LIKE '%,agent\_board,%')
+              THEN '(?:agent_board\.)?' ELSE 'agent_board\.' END AS q
+    FROM fns f
+),
+rels AS (
+  SELECT c.oid AS rel_oid, c.relname, n.nspname
+    FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+   WHERE c.relkind IN ('r', 'p')
+     AND (n.nspname = 'agent_board' OR (n.nspname = 'auth' AND c.relname = 'users'))
+),
+-- Prefilter: a function can only touch a relation whose name its body contains.
+cand AS (
+  SELECT f.oid AS fn_oid, f.body, f.q, r.rel_oid, r.relname,
+         CASE WHEN r.nspname = 'agent_board' THEN f.q ELSE r.nspname || '\.' END AS rq
+    FROM q f CROSS JOIN rels r
+   WHERE f.body ~ ('\m' || r.relname || '\M')
+),
+lit AS (
+  SELECT c.fn_oid, c.body, c.q, c.rel_oid, c.relname, c.rq,
+         substring(c.body FROM
+           '(?:insert\s+into\s+(?:only\s+)?' || c.rq || '\m' || c.relname || '\M)') AS ins_hit,
+         substring(c.body FROM
+           '(?:update\s+(?:only\s+)?' || c.rq || '\m' || c.relname || '\M[^;]{0,250}?\mset\M)') AS upd_hit,
+         substring(c.body FROM
+           '(?:delete\s+from\s+(?:only\s+)?' || c.rq || '\m' || c.relname || '\M)') AS del_hit,
+         substring(c.body FROM
+           '(?:' || c.rq || '\m' || c.relname
+           || '\M[^;]{0,250}?for\s+(?:update|no\s+key\s+update|share|key\s+share))') AS lock_hit
+    FROM cand c
+),
+-- FK columns by NAME, from pg_attribute over conkey. Shape (v) is gated on the
+-- SET naming one of these; hand-listing them, or skipping the gate, is what
+-- turns this detector into a cycle-fabricator.
+fkcols AS (
+  SELECT k.conname, k.conrelid, k.confrelid, a.attname
+    FROM pg_constraint k
+    CROSS JOIN LATERAL unnest(k.conkey) AS ck(attnum)
+    JOIN pg_attribute a ON a.attrelid = k.conrelid AND a.attnum = ck.attnum
+   WHERE k.contype = 'f'
+),
+upd AS (
+  SELECT l.fn_oid, fc.conname, fc.confrelid,
+         min(strpos(l.body, substring(l.body FROM
+           '(?:update\s+(?:only\s+)?' || l.rq || '\m' || l.relname
+           || '\M[^;]{0,250}?\mset\M[^;]{0,250}?\m' || fc.attname || '\M\s*=)'))) AS pos
+    FROM lit l
+    JOIN fkcols fc ON fc.conrelid = l.rel_oid
+   WHERE l.body ~ ('(?:update\s+(?:only\s+)?' || l.rq || '\m' || l.relname
+                   || '\M[^;]{0,250}?\mset\M[^;]{0,250}?\m' || fc.attname || '\M\s*=)')
+   GROUP BY l.fn_oid, fc.conname, fc.confrelid
+),
+direct AS (
+  -- (i) an explicit row lock written in the body
+  SELECT l.fn_oid, l.rel_oid,
+         regexp_replace(substring(l.lock_hit FROM
+           'for\s+(update|no\s+key\s+update|share|key\s+share)'), '\s+', ' ', 'g') AS lock_mode,
+         'textual' AS via,
+         strpos(l.body, l.lock_hit) AS pos
+    FROM lit l WHERE l.lock_hit IS NOT NULL
+  UNION ALL
+  -- (ii) UPDATE row-locks the updated rows
+  SELECT l.fn_oid, l.rel_oid, 'update', 'write-update', strpos(l.body, l.upd_hit)
+    FROM lit l WHERE l.upd_hit IS NOT NULL
+  UNION ALL
+  -- (iii) DELETE row-locks the deleted rows
+  SELECT l.fn_oid, l.rel_oid, 'update', 'write-delete', strpos(l.body, l.del_hit)
+    FROM lit l WHERE l.del_hit IS NOT NULL
+  UNION ALL
+  -- (iv) INSERT takes FOR KEY SHARE on every referenced parent row
+  SELECT l.fn_oid, k.confrelid, 'key share', 'fk-insert:' || k.conname, strpos(l.body, l.ins_hit)
+    FROM lit l
+    JOIN pg_constraint k ON k.conrelid = l.rel_oid AND k.contype = 'f'
+   WHERE l.ins_hit IS NOT NULL
+  UNION ALL
+  -- (v) an UPDATE that re-points an FK column locks the NEW parent row
+  SELECT u.fn_oid, u.confrelid, 'key share', 'fk-update:' || u.conname, u.pos
+    FROM upd u
+  UNION ALL
+  -- (vi) DELETE of a referenced row locks the referencing child rows
+  SELECT l.fn_oid, k.conrelid,
+         CASE k.confdeltype WHEN 'c' THEN 'update'
+                            WHEN 'n' THEN 'no key update'
+                            WHEN 'd' THEN 'no key update'
+                            ELSE 'key share' END,
+         'fk-delete:' || k.conname, strpos(l.body, l.del_hit)
+    FROM lit l
+    JOIN pg_constraint k ON k.confrelid = l.rel_oid AND k.contype = 'f'
+   WHERE l.del_hit IS NOT NULL
+),
+calls AS (
+  SELECT c.oid AS caller, e.oid AS callee, e.proname AS callee_name,
+         strpos(c.body, substring(c.body FROM c.q || '\m' || e.proname || '\M\s*\(')) AS pos
+    FROM q c JOIN q e ON e.oid <> c.oid
+   WHERE c.body ~ (c.q || '\m' || e.proname || '\M\s*\(')
+),
+reach AS (
+  SELECT d.fn_oid, d.rel_oid, d.lock_mode, d.via, array[d.pos] AS path,
+         true AS own, d.fn_oid AS origin_oid
+    FROM direct d
+  UNION ALL
+  SELECT c.caller, r.rel_oid, r.lock_mode, 'callee:' || c.callee_name,
+         c.pos || r.path, false, r.origin_oid
+    FROM reach r JOIN calls c ON c.callee = r.fn_oid
+) CYCLE fn_oid SET is_cycle USING cycle_path
+SELECT r.fn_oid, f.proname, f.sig, r.rel_oid,
+       (SELECT n.nspname || '.' || cl.relname FROM pg_class cl
+          JOIN pg_namespace n ON n.oid = cl.relnamespace WHERE cl.oid = r.rel_oid),
+       r.lock_mode, r.via, r.path, r.own, r.origin_oid,
+       (SELECT proname FROM q WHERE oid = r.origin_oid)
+  FROM reach r JOIN q f ON f.oid = r.fn_oid
+ WHERE NOT r.is_cycle;
+$lockedges$;
+
+-- The name-resolved call closure (reflexive), so a test can ask "does this route
+-- reach <serialising helper>" without re-deriving the graph.
+CREATE OR REPLACE FUNCTION agent_board_test.fn_call_closure()
+RETURNS TABLE (root_oid oid, root_name text, reached_oid oid, reached_name text)
+LANGUAGE sql STABLE
+SET search_path = pg_catalog
+AS $closure$
+WITH RECURSIVE
+fns AS (
+  SELECT p.oid, p.proname, agent_board_test.stripped_body(p.oid) AS body, p.proconfig
+    FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace
+   WHERE n.nspname = 'agent_board' AND p.prokind IN ('f','p')
+     AND p.prolang <> (SELECT oid FROM pg_language WHERE lanname = 'internal')
+),
+q AS (
+  SELECT f.oid, f.proname, f.body,
+         CASE WHEN NOT EXISTS (SELECT 1 FROM unnest(coalesce(f.proconfig,'{}')) c
+                                WHERE c LIKE 'search\_path=%')
+              OR EXISTS (SELECT 1 FROM unnest(f.proconfig) c
+                          WHERE c LIKE 'search\_path=%'
+                            AND ','||replace(replace(split_part(c,'=',2),' ',''),'"','')||','
+                                LIKE '%,agent\_board,%')
+              THEN '(?:agent_board\.)?' ELSE 'agent_board\.' END AS q
+    FROM fns f
+),
+calls AS (
+  SELECT c.oid AS caller, e.oid AS callee
+    FROM q c JOIN q e ON e.oid <> c.oid
+   WHERE c.body ~ (c.q || '\m' || e.proname || '\M\s*\(')
+),
+closure AS (
+  SELECT oid AS root, oid AS reached FROM q
+  UNION
+  SELECT c.root, e.callee FROM closure c JOIN calls e ON e.caller = c.reached
+)
+SELECT c.root, (SELECT proname FROM q WHERE oid = c.root),
+       c.reached, (SELECT proname FROM q WHERE oid = c.reached)
+  FROM closure c;
+$closure$;
+
+COMMENT ON FUNCTION agent_board_test.lock_edges() IS
+  'FK-aware per-function row-lock edge set: explicit locks, write locks, and the FOR KEY SHARE / child locks PostgreSQL takes through foreign keys. Test-only; see message-board#281.';
+
 GRANT USAGE ON SCHEMA agent_board_test TO PUBLIC;