@consiliency/agent-board-schema 1.28.0 → 1.38.0

package/migrations/20260912000100_agent_board_receipt_subject_gate.sql

@@ -0,0 +1,348 @@
+-- Consiliency/message-board#287 — a read receipt is a MEMO of access, never a SOURCE of it.
+--
+-- ============================================================================
+-- THE MEASURED DEFECT
+-- ============================================================================
+-- `agent_board.read_receipts` is an access KEY: `_current_agent_can_access_thread` treats
+-- "there is a receipt for (thread, me)" as one of the seven disjuncts that grant access to an
+-- `access_mode = 'inherit'` thread. `mark_read` is the ONLY route by which a `service_role`
+-- caller can create such a row — `information_schema.role_table_grants` gives `service_role`
+-- exactly SELECT on the table, no INSERT and no UPDATE, so the SECURITY DEFINER body is the
+-- only path.
+--
+-- The subject of the receipt is `p_agent_id` and nothing gated it. The gate `mark_read` did
+-- apply — `_current_agent_can_access_thread(p_thread_id)` — is evaluated for the SESSION, and
+-- `_is_service_role()` short-circuits it to true; `_resolved_actor_agent_id` then returns
+-- `p_agent_id` verbatim for a service_role caller. Measured on a live replay inside
+-- BEGIN … ROLLBACK: an agent B with no relationship to an inherit thread T went
+-- `can_access = false` -> service_role calls `mark_read(T, B, 0)` -> `can_access = true`,
+-- without B calling anything. The memo minted a grant.
+--
+-- Under `authenticated` there was never a gap: `_resolved_actor_agent_id` forces the subject to
+-- equal `current_agent_id()`, and the session must already pass the predicate. The asymmetry was
+-- service_role-only.
+--
+-- ============================================================================
+-- THE FIX — gate the SUBJECT, not the caller
+-- ============================================================================
+-- The NAMED agent must itself pass the thread-access predicate before a receipt is written for
+-- it. Then a receipt can only ever record access already held.
+--
+-- HOW THE PREDICATE IS EVALUATED FOR AN ARBITRARY SUBJECT. The shipped predicate is
+-- `current_agent_id()`-based, and under `service_role` there is no current agent, so it cannot
+-- simply be called for the subject. Impersonating the subject (rewriting `request.jwt.claims`
+-- so `current_agent_id()` resolves to it) was rejected: `current_agent_id()` additionally
+-- requires the JWT's `agent_credential_id` claim to reference a live credential, so a forged
+-- session would answer a DIFFERENT question than "does this agent have access", and
+-- `set_config` is volatile inside a `stable` predicate.
+--
+-- Instead the predicate is PARAMETERIZED over the agent, and the current-agent form is
+-- recomposed from it:
+--
+--     _agent_can_access_thread(p_thread_id, p_agent_id)   -- the disjunct set, subject-explicit
+--     _current_agent_can_access_thread(p_thread_id)
+--       = _is_service_role() or _agent_can_access_thread(p_thread_id, current_agent_id())
+--
+-- There is therefore exactly ONE definition of the disjunct set. A future disjunct added to the
+-- access model is added once and is seen by both the session check and the subject gate; the two
+-- cannot drift, which is the failure mode a hand-copied second predicate would have guaranteed.
+-- `_agent_has_board_access(p_board_id, p_agent_id)` is the same move for the board-delivery
+-- disjunct, whose helper is also `current_agent_id()`-based.
+--
+-- THE INVARIANT THAT MAKES THE GATE REAL: neither parameterized helper carries the
+-- `_is_service_role()` short-circuit. That short-circuit is what made the session check vacuous
+-- for the very caller this closes; reintroducing it into `_agent_can_access_thread` would make
+-- the gate a no-op while every test that exercises an agent WITH access stayed green. The
+-- short-circuit lives in exactly one place, `_current_agent_can_access_thread`, where it is a
+-- statement about the SESSION and remains correct.
+--
+-- Behaviour for `authenticated` is unchanged BY CONSTRUCTION, not by inspection: the session
+-- check for a non-service_role caller already evaluates
+-- `_agent_can_access_thread(p_thread_id, current_agent_id())`, and `_resolved_actor_agent_id`
+-- makes `v_actor_agent_id = current_agent_id()`, so the new gate re-evaluates an expression that
+-- was just proved true. It is applied unconditionally rather than only when the subject differs
+-- from the session agent — a conditional gate would be one `is distinct from` away from being
+-- skipped by a caller that presents both a service_role claim and a `sub`.
+--
+-- GATE PLACEMENT is deliberate: session check (42501) -> thread lookup (P0002) -> subject gate
+-- (42501). Putting the subject gate last preserves the existing error CODES exactly, including
+-- "a service_role caller naming a nonexistent thread still gets P0002 'thread not found'", which
+-- moving the gate earlier would have silently turned into 42501.
+--
+-- ============================================================================
+-- WHAT IS DELIBERATELY NOT CHANGED — the receipt grandfather
+-- ============================================================================
+-- The receipt disjunct itself STAYS. Nothing in this schema deletes a `read_receipts` row (there
+-- is no DELETE grant to any Supabase role and no function body deletes from it), so a receipt is
+-- PERMANENT: an agent that leaves a board, or is reassigned off a task, keeps access to the
+-- threads it had already opened. That is the ratified rule — YOU KEEP WHAT YOU SAW — and it is
+-- load-bearing for two measured flows: a late board joiner, and a reassigned task assignee, both
+-- of which lose thread access entirely if the disjunct is removed. It is recorded here and in
+-- the `comment on function` below because it arrived in a 2026-04 commit with an empty message
+-- and the only prior record of intent was a later decision to "preserve the existing OR
+-- verbatim" — nobody was on record CHOOSING it.
+--
+-- The gate and the grandfather are complementary, not in tension: the gate decides WHO MAY BE
+-- NAMED in a receipt, the grandfather decides WHAT A RECEIPT MEANS afterwards. Gating the
+-- subject is what makes the grandfather safe to keep, because a receipt can no longer be
+-- conjured for an agent that never had access.
+--
+-- OUT OF SCOPE, stated rather than implied: `acquire_claim` has the same third-party-naming
+-- shape on the sibling `claims` disjunct (and worse — a RELEASED claim row remains a permanent
+-- key). The owner chose to close the receipt route only; the claims/inbox sibling survey is
+-- filed separately. This migration does not touch `acquire_claim`.
+--
+-- Additive; no signature changes (so no DROP, so the ACLs and COMMENTs on the two redefined
+-- functions survive). `schema_version` stays 8.
+
+-- 1. The disjunct set, parameterized over the subject agent ------------------
+-- NOTE the absence of `_is_service_role()`: see THE INVARIANT above.
+create or replace function agent_board._agent_has_board_access(
+  p_board_id uuid,
+  p_agent_id uuid
+)
+returns boolean
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  select exists (
+    select 1
+      from agent_board.board_memberships bm
+     where bm.board_id = p_board_id
+       and bm.agent_id = p_agent_id
+       and bm.membership_state in ('joined', 'subscribed')
+  )
+$$;
+
+revoke all on function agent_board._agent_has_board_access(uuid, uuid) from public, anon, authenticated;
+grant execute on function agent_board._agent_has_board_access(uuid, uuid) to service_role;
+
+comment on function agent_board._agent_has_board_access(uuid, uuid) is
+  'Board access for an EXPLICIT agent: an active (joined|subscribed) board_memberships row. '
+  'Subject-explicit twin of _current_agent_has_board_access, which is this predicate applied to '
+  'current_agent_id() with an _is_service_role() short-circuit in front. This one has NO '
+  'short-circuit and must never gain one: it is evaluated on behalf of a service_role caller to '
+  'answer a question about a THIRD party (message-board#287), and a short-circuit would answer '
+  '"yes" for every agent. Internal; service_role only.';
+
+create or replace function agent_board._agent_can_access_thread(
+  p_thread_id uuid,
+  p_agent_id uuid
+)
+returns boolean
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  select exists (
+    select 1
+      from agent_board.threads t
+     where t.id = p_thread_id
+       and (
+         (
+           t.access_mode = 'inherit'
+           and (
+             t.created_by_agent_id = p_agent_id
+             or exists (
+               select 1
+                 from agent_board.messages m
+                where m.thread_id = t.id
+                  and m.author_agent_id = p_agent_id
+             )
+             or exists (
+               select 1
+                 from agent_board.tasks task
+                where task.thread_id = t.id
+                  and (
+                    task.created_by_agent_id = p_agent_id
+                    or task.assigned_agent_id = p_agent_id
+                  )
+             )
+             or exists (
+               select 1
+                 from agent_board.read_receipts rr
+                where rr.thread_id = t.id
+                  and rr.agent_id = p_agent_id
+             )
+             or exists (
+               select 1
+                 from agent_board.claims c
+                where c.thread_id = t.id
+                  and c.agent_id = p_agent_id
+             )
+             or exists (
+               select 1
+                 from agent_board.inbox_items ii
+                 left join agent_board.messages im on im.id = ii.source_message_id
+                 left join agent_board.tasks it on it.id = ii.source_task_id
+                 left join agent_board.delegations ide on ide.id = ii.source_delegation_id
+                 left join agent_board.tasks idt on idt.id = ide.child_task_id
+                where ii.recipient_agent_id = p_agent_id
+                  and (
+                    im.thread_id = t.id
+                    or it.thread_id = t.id
+                    or idt.thread_id = t.id
+                  )
+             )
+             or exists (
+               select 1
+                 from agent_board.delivery_recipients dr
+                 join agent_board.messages bm on bm.id = dr.source_message_id
+                where dr.board_id is not null
+                  and bm.thread_id = t.id
+                  and agent_board._agent_has_board_access(dr.board_id, p_agent_id)
+             )
+           )
+         )
+         or (
+           t.access_mode = 'restricted'
+           and exists (
+             select 1
+               from agent_board.thread_memberships tm
+              where tm.thread_id = t.id
+                and tm.agent_id = p_agent_id
+                and tm.revoked_at is null
+                and (tm.expires_at is null or tm.expires_at > now())
+           )
+         )
+       )
+  )
+$$;
+
+revoke all on function agent_board._agent_can_access_thread(uuid, uuid) from public, anon, authenticated;
+grant execute on function agent_board._agent_can_access_thread(uuid, uuid) to service_role;
+
+comment on function agent_board._agent_can_access_thread(uuid, uuid) is
+  'THE thread-access predicate, evaluated for an EXPLICIT agent. access_mode=inherit is the '
+  'historical seven-way OR (creator | message author | task creator-or-assignee | read receipt | '
+  'claim | inbox item | board-delivered message on a board the agent is in); '
+  'access_mode=restricted requires an unexpired, unrevoked thread_memberships row. '
+  '_current_agent_can_access_thread is DEFINED AS _is_service_role() OR this predicate applied '
+  'to current_agent_id(), so this is the single source of the disjunct set and the two cannot '
+  'drift. It carries NO _is_service_role() short-circuit and must never gain one: mark_read '
+  'evaluates it on behalf of a service_role caller to decide whether a THIRD party may be named '
+  'in a receipt (message-board#287), and a short-circuit would make that gate vacuous while '
+  'leaving every allow-side test green. A null p_agent_id yields false. Internal; '
+  'service_role only.';
+
+-- 2. Recompose the current-agent form from the parameterized one ------------
+-- create or replace (not drop): the signature is unchanged, so the existing ACL survives.
+create or replace function agent_board._current_agent_can_access_thread(
+  p_thread_id uuid
+)
+returns boolean
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  select
+    agent_board._is_service_role()
+    or agent_board._agent_can_access_thread(p_thread_id, agent_board.current_agent_id())
+$$;
+
+revoke all on function agent_board._current_agent_can_access_thread(uuid) from public, anon, authenticated;
+
+comment on function agent_board._current_agent_can_access_thread(uuid) is
+  'Thread access for the CURRENT session: service_role short-circuits true, otherwise '
+  '_agent_can_access_thread(p_thread_id, current_agent_id()). The disjunct set lives in that '
+  'helper and is not restated here. '
+  'THE READ RECEIPT IS A PERMANENT GRANDFATHER, AND THAT IS DELIBERATE (message-board#287). '
+  'An agent_board.read_receipts row is one of the inherit-mode disjuncts, and nothing in this '
+  'schema ever deletes one: no role holds DELETE on the table and no function body removes a '
+  'row. So access that was once exercised is never withdrawn -- LEAVING A BOARD, OR LOSING A '
+  'TASK ASSIGNMENT, DOES NOT REVOKE ACCESS TO A THREAD THE AGENT HAD ALREADY READ. The rule is '
+  '"you keep what you saw". This is not an oversight and it is not a leak to be closed later: '
+  'two shipped flows depend on it and lose thread access entirely without it -- an agent that '
+  'joins a board late and reads history, and an agent reassigned off a task whose thread it '
+  'worked. The same is true of the claims and inbox_items disjuncts, which are likewise never '
+  'deleted. What IS closed is the mint: mark_read gates the NAMED subject through '
+  '_agent_can_access_thread, so a receipt can only ever record access already held and can no '
+  'longer be conjured for an agent that never had any.';
+
+-- 3. mark_read: gate the named subject --------------------------------------
+-- create or replace (not drop): signature unchanged, ACL survives.
+create or replace function agent_board.mark_read(p_thread_id uuid, p_agent_id uuid, p_last_read_message_sequence bigint)
+returns table(thread_id uuid, agent_id uuid, last_read_message_sequence bigint, last_read_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_sequence bigint;
+  v_actor_agent_id uuid;
+begin
+  v_actor_agent_id := agent_board._resolved_actor_agent_id(p_agent_id, 'p_agent_id');
+
+  if p_last_read_message_sequence < 0 then
+    raise exception 'negative read sequence' using errcode = '22023';
+  end if;
+
+  if not agent_board._current_agent_can_access_thread(p_thread_id) then
+    raise exception 'thread not accessible to current agent' using errcode = '42501';
+  end if;
+
+  select least(p_last_read_message_sequence, t.last_message_sequence)
+    into v_sequence
+    from agent_board.threads t
+   where t.id = p_thread_id;
+
+  if v_sequence is null then
+    raise exception 'thread not found' using errcode = 'P0002';
+  end if;
+
+  -- message-board#287: the SUBJECT gate. The check above answers "may this SESSION touch the
+  -- thread" and is short-circuited true for service_role; this one answers "does the agent the
+  -- receipt is ABOUT already have access". Without it a service_role caller could name any
+  -- agent and the resulting receipt -- itself an access disjunct -- would MINT access rather
+  -- than record it. Unconditional: for an authenticated caller v_actor_agent_id is
+  -- current_agent_id() and the session check already established this same expression, so this
+  -- is provably a no-op on that path.
+  --
+  -- DO NOT "OPTIMIZE" THIS INTO `if _is_service_role() and not ...`. The redundancy on the
+  -- authenticated path is the PRICE of an unconditional invariant, and it is worth paying:
+  -- branching on _is_service_role() would make this gate's correctness depend on
+  -- _resolved_actor_agent_id continuing to raise 42501 whenever a non-service_role caller
+  -- supplies an id other than current_agent_id(). That is true today, but it converts a
+  -- property this function states for itself into one it borrows from another function.
+  --
+  -- The second evaluation does open a one-statement window at READ COMMITTED, since each
+  -- plpgsql statement takes a fresh snapshot: access revoked between the two checks turns a
+  -- would-be receipt into a 42501. That non-atomicity is PRE-EXISTING, not introduced here --
+  -- the old code already had a window between its single check and the INSERT -- and this
+  -- widens it by one statement. The outcome is a spurious refusal for an agent that has just
+  -- lost access, which retries to a consistent 42501: no security consequence, and no
+  -- grandfathered access lost by anyone who still holds it.
+  if not agent_board._agent_can_access_thread(p_thread_id, v_actor_agent_id) then
+    raise exception 'read receipt subject has no access to thread' using errcode = '42501';
+  end if;
+
+  return query
+  insert into agent_board.read_receipts(thread_id, agent_id, last_read_message_sequence, last_read_at)
+  values (p_thread_id, v_actor_agent_id, v_sequence, now())
+  on conflict on constraint read_receipts_pkey do update
+    set last_read_message_sequence = greatest(read_receipts.last_read_message_sequence, excluded.last_read_message_sequence),
+        last_read_at = now()
+  returning read_receipts.thread_id, read_receipts.agent_id, read_receipts.last_read_message_sequence, read_receipts.last_read_at;
+end;
+$$;
+
+revoke all on function agent_board.mark_read(uuid, uuid, bigint) from public, anon;
+grant execute on function agent_board.mark_read(uuid, uuid, bigint) to authenticated, service_role;
+
+comment on function agent_board.mark_read(uuid, uuid, bigint) is
+  'Advances the (thread, agent) read cursor in agent_board.read_receipts. The subject is '
+  '_resolved_actor_agent_id(p_agent_id): authenticated callers are forced to current_agent_id() '
+  'and fail closed on mismatch; service_role may mark on behalf of another agent. '
+  'A RECEIPT IS A MEMO OF ACCESS, NEVER A SOURCE OF IT (message-board#287): because a receipt '
+  'row is itself a disjunct of _agent_can_access_thread, the NAMED agent must already pass that '
+  'predicate or the call raises 42501 ''read receipt subject has no access to thread''. This '
+  'closes the only route by which service_role could create a read_receipts row for an '
+  'arbitrary agent (service_role holds SELECT only on the table, so this SECURITY DEFINER body '
+  'is the sole path) and thereby hand it durable access to an inherit thread. The gate is placed '
+  'after the thread lookup so a nonexistent thread still answers P0002, not 42501. All three '
+  'shipped callers (client, CLI, MCP) default p_agent_id to the session''s own acting agent and '
+  'name no third party, so nothing in the fleet changes shape.';

package/migrations/20260913000100_agent_board_task_thread_lock_order.sql

@@ -0,0 +1,292 @@
+-- Consiliency/message-board#281 (R1) — agree on ONE order for (threads, tasks):
+-- THREADS BEFORE TASKS, in every function that touches both.
+--
+-- WHAT WAS WRONG. #290's FK-aware detector (agent_board_test.lock_edges()) found 186
+-- unserialised ABBA rows over 27 relation pairs. Forty of them — the single largest block,
+-- and the only one whose operand coincidence is an ordinary workload rather than a
+-- lifecycle event — sat on `tasks <-> threads`:
+--
+--   append_task_event:  tasks (explicit FOR UPDATE)  ->  threads (KEY SHARE, via the
+--                       task_events.thread_id FK on the event insert)
+--   post_message:       threads (UPDATE, one frame down in
+--                       _next_thread_message_sequence)  ->  tasks (KEY SHARE, via the
+--                       messages.task_id FK on the message insert)
+--
+-- The colliding operand is `postMessage({ threadId: task.threadId, taskId: task.id })` —
+-- commenting on a task in its own thread — concurrent with any agent claiming, delegating
+-- or resolving that task. Both sides are foreground, user-attributable writes.
+--
+-- WHAT IS ACTUALLY REACHABLE TODAY, STATED HONESTLY. Those 40 rows are a lock-ORDER
+-- disagreement, not a live deadlock. `_next_thread_message_sequence` updates
+-- `threads.last_message_sequence` / `updated_at`; `threads` carries exactly one unique
+-- index (threads_pkey on id), so that UPDATE takes FOR NO KEY UPDATE — which by
+-- PostgreSQL's matrix (pinned verbatim as FKL-2) does NOT conflict with the FOR KEY SHARE
+-- that append_task_event takes on threads through the FK. So post_message blocks on
+-- append_task_event's `tasks FOR UPDATE`, but append_task_event never blocks on
+-- post_message's threads lock: one-way blocking, no cycle. The detector reports the rows
+-- because `_acq` aggregates any write-update to mode `update` — it over-reports by design,
+-- which is the correct direction for a safety instrument.
+--
+-- That is a reason to fix the ORDER, not a reason to leave it. The CYCLE this closes is
+-- LATENT, not live, and the permanent record should say so: nobody should later read this
+-- migration as evidence that a real deadlock was occurring, because none was.
+--
+-- BUT "LATENT" UNDERSTATES THE CHANGE, AND THE UNDERSTATEMENT IS THE DANGEROUS DIRECTION —
+-- "latent only" is exactly the framing that invites someone to deprioritise or revert this.
+-- The reorder also fixes a LOCK-CONVOY THAT HAPPENS TODAY, against the real shipped
+-- `create_or_find_thread` (which holds `threads … for update` on its reuse path).
+--   * BEFORE: append_task_event took `tasks … for update` FIRST and did not reach its
+--     threads lock until the task_events insert. So when it blocked behind
+--     create_or_find_thread's thread lock, IT BLOCKED WHILE HOLDING tasks FOR UPDATE —
+--     and every other writer of that task queued behind an unrelated thread lookup.
+--   * AFTER: it takes the threads KEY SHARE first, HOLDING NOTHING, and reaches `tasks`
+--     only once that is granted. Same wait for the appender; no convoy for anyone else.
+-- Measured with isolationtester, three sessions — real create_or_find_thread, real
+-- append_task_event, and a `tasks … for key share` observer standing in for any FK
+-- reference to that task (messages.task_id, delivery_recipients.source_task_id,
+-- delegations.child_task_id all take exactly that mode). PRE-FIX the observer WAITS; POST-FIX
+-- it completes immediately. In both runs the appender itself waits — that part is unchanged
+-- and is not what the fix improves.
+--
+-- IF YOU ARE THE AUTHOR WHO ACTIVATES IT, THIS PARAGRAPH IS FOR YOU. The cycle goes live
+-- the moment anything takes a lock on `threads` that CONFLICTS with FOR KEY SHARE. Four
+-- ways to do that without ever reading this file, and the first is NOT hypothetical:
+--   * GIVING `create_or_find_thread` A `tasks` ACQUISITION. It already takes
+--     `select … from agent_board.threads … for update`
+--     (20260517000000_agent_board_addressing.sql:265-273) — it is the only function in the
+--     bundle holding an explicit lock on threads — and it is harmless here for exactly one
+--     reason: it touches NO `tasks` row (its only other edges are FK KEY SHARE on `agents`
+--     and `boards`). So it already performs the first half of the adversary that the
+--     isolation spec's `probe` session has to synthesize. Add any tasks acquisition to it —
+--     a `tasks` lookup, an FK to tasks on a row it writes — and permutation 1 of
+--     tests/isolation/specs/task_thread_lock_order.spec stops being an instrument and
+--     becomes a shipped path. It is the shortest route from here to a live deadlock.
+--   * an explicit `for update` (or `for share` / `for no key update`) on threads in some
+--     OTHER function that also reaches tasks;
+--   * a `delete from agent_board.threads`, which row-locks the deleted row outright;
+--   * ADDING A UNIQUE INDEX THAT COVERS A COLUMN THE SEQUENCE UPDATE WRITES — with no
+--     function change at all. Be precise about which columns those are, or this reads as a
+--     warning against every index: `_next_thread_message_sequence` writes exactly
+--     `last_message_sequence` and `updated_at`. A unique index that covers one of THOSE
+--     promotes its UPDATE from FOR NO KEY UPDATE to FOR UPDATE; a unique index on any
+--     other threads column (`board_id`, a slug, anything the statement does not SET)
+--     leaves it at FOR NO KEY UPDATE and changes nothing here. Verified empirically with
+--     isolationtester on a two-column toy table rather than asserted from the manual: with
+--     the unique index on a column the UPDATE does not write, a concurrent FOR KEY SHARE
+--     did not wait; moved onto the column it does write, the same FOR KEY SHARE waited.
+--     `updated_at` is the live end of this: it is generic bookkeeping, it is the column
+--     most likely to be swept into a unique or covering index for optimistic concurrency
+--     (`unique (id, updated_at)`) or a dedup window, and nobody adding such an index would
+--     connect it to task-event ordering.
+-- None of those has any visible connection to append_task_event. What protects you is that
+-- both relations already agree on ONE order, so a stronger mode changes how long a caller
+-- waits and not whether it deadlocks. Keep the agreement: TT-1 in
+-- agent_board_task_thread_lock_order.test.sql enumerates the class from the catalog and
+-- will fail NAMING your function if it takes tasks before threads, and FKL-10 in
+-- agent_board_fk_lock_edges.test.sql will fail if the relation pair returns to the cycle
+-- set. An agreed order survives a mode change; an accidental mode mismatch does not.
+--
+-- THE TWO EDITS, AND WHY IT IS TWO AND NOT ONE. The #281 triage said reordering
+-- append_task_event alone "removes all 40 rows — no other explicit lock on either relation
+-- participates". Measured, that is wrong: it holds for EXPLICIT locks only.
+-- `_upsert_delivery_recipient` has no explicit lock at all — it inserts into
+-- delivery_recipients (KEY SHARE on tasks, via delivery_recipients_source_task_id_fkey)
+-- and only then updates `threads.board_id`. That order was harmless while
+-- append_task_event was also tasks-first; moving append_task_event to threads-first
+-- promotes `_upsert_delivery_recipient` into the cycle set. Reordering append_task_event
+-- alone measures 186 -> 150 with FOUR rows still on the pair and the pair still in FKL-10.
+-- Both edits together measure 186 -> 146, the pair empty, and a per-pair diff showing no
+-- other relation pair changed by a single row.
+--
+-- THE RESULTING TOTAL ORDER, now shared by every function that acquires both relations --
+-- 20 by name, 24 by (function, signature), the difference being the four addressing-mode
+-- overloads (post_board_message, send_direct_message, send_multicast_message,
+-- create_tasking_delivery). The by-name count is what TT-2 asserts:
+--
+--     agent_board.threads   BEFORE   agent_board.tasks
+--
+-- It is the direction the whole message/board write surface already took for free
+-- (post_message, post_board_message, send_direct_message, send_multicast_message,
+-- create_tasking_delivery and their signed wrappers), and the direction create_task,
+-- acquire_claim, add_artifact, delegate_task, raise_conflict and raise_escalation already
+-- took. append_task_event and _upsert_delivery_recipient were the only two outliers.
+--
+-- WHAT IS NOT CHANGED. append_task_event still takes `tasks ... FOR UPDATE`. That lock is
+-- not decoration: it is the mutual exclusion behind
+--   `select coalesce(max(te.event_sequence), 0) + 1`
+-- against task_events_task_id_event_sequence_key. Dropping it would trade a lock-order
+-- disagreement for a live duplicate-key race, so it is kept at exactly its current
+-- strength and asserted positively (TT-6) rather than left to a reader's confidence.
+--
+-- Additive and forward-only. No behaviour, gate, error code or grant changes.
+-- schema_version stays 8.
+
+-- 1. append_task_event: threads first ---------------------------------------
+-- `v_thread_id` comes OUT of tasks, so taking threads first needs the thread id before the
+-- task row is locked. The unlocked pre-read supplies it; the FOR UPDATE re-read then
+-- returns the authoritative value and the two are compared. tasks.thread_id is never
+-- re-pointed by any function in the bundle — asserted from the catalog as TT-4, not from a
+-- grep — so the recheck is fail-closed against a state that cannot currently arise, and it
+-- raises 40001 (serialization_failure, a retryable class) rather than silently writing a
+-- task_events row whose thread_id disagrees with its task's.
+--
+-- The threads lock is FOR KEY SHARE: exactly the mode the task_events insert takes through
+-- task_events_thread_id_fkey a few statements later, so hoisting it adds NO new blocking
+-- anywhere (KEY SHARE conflicts only with FOR UPDATE, which nothing in the bundle takes on
+-- threads). It makes the acquisition SCHEDULABLE, which an FK-implied lock is not.
+--
+-- Everything else — the actor resolution, the P0002 on a missing task, the
+-- _current_agent_can_access_task check, the OBSGATE-3 _current_agent_can_mutate_task gate,
+-- the sequence computation, both writes and the returned row — is byte-identical to
+-- 20260816000100. CREATE OR REPLACE, so the ACL survives; the grants are restated anyway.
+create or replace function agent_board.append_task_event(
+  p_task_id uuid,
+  p_actor_agent_id uuid,
+  p_event_type text,
+  p_payload jsonb default '{}'::jsonb,
+  p_status text default null,
+  p_assigned_agent_id uuid default null,
+  p_completed_at timestamp with time zone default null
+)
+returns table(task_id uuid, thread_id uuid, event_id uuid, event_sequence bigint, task_status text, assigned_agent_id uuid, updated_at timestamp with time zone, completed_at timestamp with time zone)
+language plpgsql
+security definer
+set search_path to 'agent_board', 'public'
+as $function$
+declare
+  v_thread_id uuid;
+  v_locked_thread_id uuid;
+  v_sequence bigint;
+  v_event_id uuid;
+  v_actor_agent_id uuid;
+begin
+  v_actor_agent_id := agent_board._resolved_actor_agent_id(p_actor_agent_id, 'p_actor_agent_id');
+
+  select tasks.thread_id into v_thread_id from agent_board.tasks where id = p_task_id;
+  if v_thread_id is null then
+    raise exception 'task not found' using errcode = 'P0002';
+  end if;
+
+  perform 1 from agent_board.threads th where th.id = v_thread_id for key share;
+
+  select tasks.thread_id into v_locked_thread_id from agent_board.tasks where id = p_task_id for update;
+  if v_locked_thread_id is null then
+    raise exception 'task not found' using errcode = 'P0002';
+  end if;
+  if v_locked_thread_id is distinct from v_thread_id then
+    raise exception 'task thread changed while acquiring locks' using errcode = '40001';
+  end if;
+
+  if not agent_board._current_agent_can_access_task(p_task_id) then
+    raise exception 'task not accessible to current agent' using errcode = '42501';
+  end if;
+  if not agent_board._current_agent_can_mutate_task(p_task_id) then
+    raise exception 'task mutation requires a non-observer board role, or task assignment/creation'
+      using errcode = '42501';
+  end if;
+
+  select coalesce(max(te.event_sequence), 0) + 1 into v_sequence from agent_board.task_events te where te.task_id = p_task_id;
+  insert into agent_board.task_events(task_id, thread_id, actor_agent_id, event_sequence, event_type, payload)
+  values (p_task_id, v_thread_id, v_actor_agent_id, v_sequence, p_event_type, coalesce(p_payload, '{}'::jsonb))
+  returning id into v_event_id;
+
+  update agent_board.tasks
+     set status = coalesce(p_status, tasks.status),
+         assigned_agent_id = coalesce(p_assigned_agent_id, tasks.assigned_agent_id),
+         completed_at = coalesce(p_completed_at, tasks.completed_at),
+         updated_at = now()
+   where id = p_task_id;
+
+  return query
+  select t.id, t.thread_id, v_event_id, v_sequence, t.status, t.assigned_agent_id, t.updated_at, t.completed_at
+    from agent_board.tasks t
+   where t.id = p_task_id;
+end;
+$function$;
+comment on function agent_board.append_task_event(uuid, uuid, text, jsonb, text, uuid, timestamp with time zone) is
+  '#281 R1 lock order: threads(KEY SHARE) BEFORE tasks(FOR UPDATE), matching every other function that touches both. The tasks FOR UPDATE is retained deliberately — it is the mutual exclusion behind the event_sequence computation against task_events_task_id_event_sequence_key. OBSGATE-3 (#125) gating and every error code are unchanged from 20260816000100.';
+revoke all on function agent_board.append_task_event(uuid, uuid, text, jsonb, text, uuid, timestamp with time zone) from public, anon;
+grant execute on function agent_board.append_task_event(uuid, uuid, text, jsonb, text, uuid, timestamp with time zone) to authenticated, service_role;
+
+-- 2. _upsert_delivery_recipient: threads first ------------------------------
+-- The OBSGATE (#78) board stamp is hoisted ABOVE the delivery_recipients insert. It is a
+-- pure statement reorder: the stamp resolves its thread from the three source PARAMETERS
+-- (p_source_message_id / p_source_task_id / p_source_delegation_id), never from `v_row`, so
+-- it has no data dependency on the insert. Both statements are in the same transaction and
+-- the function has no exception handler, so a failing insert still discards the stamp —
+-- there is no observable ordering difference, only a lock-acquisition one.
+--
+-- Semantics preserved exactly: first-board-wins (`where t.board_id is null`), board-less
+-- deliveries (p_board_id null) never stamp, and the coalesce order across message / task /
+-- delegation sources is untouched.
+create or replace function agent_board._upsert_delivery_recipient(
+  p_delivery_mode text,
+  p_recipient_agent_id uuid,
+  p_source_kind text,
+  p_source_message_id uuid default null,
+  p_source_task_id uuid default null,
+  p_source_delegation_id uuid default null,
+  p_board_id uuid default null,
+  p_board_membership_id uuid default null,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns agent_board.delivery_recipients
+language plpgsql
+security definer
+set search_path to 'agent_board', 'public'
+as $function$
+declare
+  v_row agent_board.delivery_recipients%rowtype;
+begin
+  -- OBSGATE (#78): stamp the thread's owning board on first board delivery so
+  -- post_message's posting gate can resolve it. Resolve the thread from WHICHEVER source the
+  -- delivery carries — message (post_board_message), task (create_tasking_delivery), or
+  -- delegation — so EVERY board-fanning path links the thread, not just the message-sourced one.
+  -- First-board-wins (never overwrites); board-less deliveries (p_board_id null) never stamp.
+  if p_board_id is not null then
+    update agent_board.threads t
+       set board_id = p_board_id
+     where t.board_id is null
+       and t.id = coalesce(
+         (select m.thread_id from agent_board.messages m where m.id = p_source_message_id),
+         (select tk.thread_id from agent_board.tasks tk where tk.id = p_source_task_id),
+         (select tk.thread_id
+            from agent_board.delegations d
+            join agent_board.tasks tk on tk.id = d.child_task_id
+           where d.id = p_source_delegation_id)
+       );
+  end if;
+
+  insert into agent_board.delivery_recipients(
+    delivery_mode,
+    recipient_agent_id,
+    source_kind,
+    source_message_id,
+    source_task_id,
+    source_delegation_id,
+    board_id,
+    board_membership_id,
+    metadata
+  )
+  values (
+    p_delivery_mode,
+    p_recipient_agent_id,
+    p_source_kind,
+    p_source_message_id,
+    p_source_task_id,
+    p_source_delegation_id,
+    p_board_id,
+    p_board_membership_id,
+    coalesce(p_metadata, '{}'::jsonb)
+  )
+  on conflict (recipient_agent_id, canonical_source_key) do update
+    set metadata = coalesce(agent_board.delivery_recipients.metadata, '{}'::jsonb) || coalesce(excluded.metadata, '{}'::jsonb)
+  returning * into v_row;
+
+  return v_row;
+end;
+$function$;
+comment on function agent_board._upsert_delivery_recipient(text, uuid, text, uuid, uuid, uuid, uuid, uuid, jsonb) is
+  '#281 R1 lock order: the OBSGATE (#78) threads board-stamp runs BEFORE the delivery_recipients insert, so this function is threads-before-tasks like every other function that touches both. Pure statement reorder — the stamp resolves its thread from the source parameters, not from the inserted row. Internal-only; PUBLIC EXECUTE revoked.';
+revoke all on function agent_board._upsert_delivery_recipient(text, uuid, text, uuid, uuid, uuid, uuid, uuid, jsonb) from public, anon, authenticated;
+grant execute on function agent_board._upsert_delivery_recipient(text, uuid, text, uuid, uuid, uuid, uuid, uuid, jsonb) to service_role;