@consiliency/agent-board-schema 1.35.0 → 1.40.0

package/tests/agent_board_invite_no_downgrade.test.sql

@@ -0,0 +1,689 @@
+-- #317 — an invite must not weaken an active membership.
+--
+-- The defect: `_upsert_board_membership_state` set `membership_state = p_membership_state`
+-- unconditionally, so inviting an agent who was ALREADY joined moved them back to `invited`
+-- and silently revoked board delivery. Observed in production (`invite_offer -> invited` on a
+-- membership joined since 2026-08-05) and reproduced at this bundle before the fix.
+--
+-- Both directions are asserted. A guard that refuses everything would satisfy "no downgrade"
+-- while breaking every legitimate transition, so the untouched paths are pinned as positively
+-- as the blocked one.
+
+begin;
+select plan(53);
+
+select agent_board.register_agent('agent', 'nd-owner', 'ND Owner');
+select agent_board.register_agent('agent', 'nd-member', 'ND Member');
+
+create temp table _nd on commit drop as
+select (select id from agent_board.agents where handle = 'nd-owner')  as owner_id,
+       (select id from agent_board.agents where handle = 'nd-member') as member_id;
+
+select agent_board.create_board((select owner_id from _nd), 'nd-board', 'ND Board');
+
+create temp table _ndb on commit drop as
+select id as board_id from agent_board.boards where slug = 'nd-board';
+
+-- ORDER BY is not decoration. An unordered single-row read over (board, agent) is
+-- non-deterministic the moment two rows exist for the pair -- the DUPROW (#88) shape --
+-- and would make every assertion below flip with physical row order rather than fail.
+-- Same ordering the consent suite uses (agent_board_consent_gating.test.sql pg_temp.state).
+create or replace function pg_temp.nd_state() returns text language sql as $$
+  select membership_state from agent_board.board_memberships
+   where board_id = (select board_id from _ndb) and agent_id = (select member_id from _nd)
+   order by case when membership_state in ('joined', 'subscribed') then 0 else 1 end,
+            created_at desc, id desc
+   limit 1;
+$$;
+
+-- ---------------------------------------------------------------------------
+-- THE DEFECT: an offer applied to an existing membership must not weaken it.
+-- ---------------------------------------------------------------------------
+select lives_ok(
+  $$ select agent_board._upsert_board_membership_state(
+       (select board_id from _ndb), (select member_id from _nd), 'joined', (select owner_id from _nd)) $$,
+  'a member joins');
+select is(pg_temp.nd_state(), 'joined', 'the member is joined');
+
+select lives_ok(
+  $$ select agent_board.invite_board_member(
+       (select board_id from _ndb), (select member_id from _nd), (select owner_id from _nd)) $$,
+  'inviting an already-joined member does not raise — invite stays idempotent');
+select is(pg_temp.nd_state(), 'joined',
+  '#317: inviting a JOINED member leaves them joined — an offer never weakens active standing');
+
+-- Re-join FIRST, so this arm is evidenced against a JOINED row independently of the
+-- assertion above. Without it, a mutation that reverts only the `invited` arm leaves the
+-- row already `invited` here, and this pair then tests requested-against-INVITED while
+-- reading as though it tested requested-against-joined. Found by the review board: the
+-- earlier PR text claimed one mutation evidenced both arms, and it could not.
+select lives_ok(
+  $$ select agent_board._upsert_board_membership_state(
+       (select board_id from _ndb), (select member_id from _nd), 'joined', (select owner_id from _nd)) $$,
+  'the member is (re-)joined, so the `requested` arm below is evidenced against JOINED');
+
+-- `requested` is the other offer state and must behave identically.
+select lives_ok(
+  $$ select agent_board._upsert_board_membership_state(
+       (select board_id from _ndb), (select member_id from _nd), 'requested', (select member_id from _nd)) $$,
+  'a `requested` offer against a joined member does not raise');
+select is(pg_temp.nd_state(), 'joined',
+  '#317: `requested` against a JOINED member also leaves them joined');
+
+-- ---------------------------------------------------------------------------
+-- THE LEDGER, on the no-op path. The row keeping `joined` is only half the claim:
+-- `board_membership_events` is what the #317 investigation actually read to establish
+-- what happened, it is APPEND-ONLY, and before this was asserted the sink emitted the
+-- ARGUMENT rather than the resulting row -- appending `invite_offer -> invited` beside a
+-- row that says `joined`. A ledger contradicting the table it describes is worse than the
+-- demotion this migration removes, because it cannot be corrected afterwards.
+--
+-- Asserted on RESULT_STATE and not on event_kind, deliberately. The kind is derived from
+-- the session: these calls run with no JWT, so the emitter records `operator_designation`,
+-- while the production event that exposed #317 was an authenticated owner's `invite_offer`.
+-- Pinning the kind here would pin the test harness's own principal, not the property.
+-- ---------------------------------------------------------------------------
+select is(
+  (select result_state from agent_board.board_membership_events
+    where board_id = (select board_id from _ndb) and agent_id = (select member_id from _nd)
+    order by seq desc limit 1),
+  pg_temp.nd_state(),
+  '#317: the latest ledger event records the state the ROW actually has — the ledger cannot contradict the table');
+
+select is(
+  (select count(*)::text from agent_board.board_membership_events
+    where board_id = (select board_id from _ndb) and agent_id = (select member_id from _nd)
+      and result_state in ('invited', 'requested')),
+  '0',
+  '#317: NO event so far records an offer state — before the fix the no-op invite appended `-> invited` beside a joined row, append-only and uncorrectable');
+
+-- ---------------------------------------------------------------------------
+-- WHAT "NO-OP" ACTUALLY MEANS, both halves. The migration claims a suppressed offer leaves the
+-- membership "exactly as strong as it was"; the row is nonetheless still written. Asserting only
+-- the preserved half would leave the prose broader than the evidence, which is the failure this
+-- file has been corrected for twice. So both are pinned: the authority-bearing columns do NOT
+-- move, and the bookkeeping columns DO.
+-- ---------------------------------------------------------------------------
+create temp table _ndbefore on commit drop as
+select membership_state, left_at, role, metadata, updated_at, created_by_agent_id
+  from agent_board.board_memberships
+ where board_id = (select board_id from _ndb) and agent_id = (select member_id from _nd);
+
+select lives_ok(
+  $$ select agent_board._upsert_board_membership_state(
+       (select board_id from _ndb), (select member_id from _nd), 'invited', (select owner_id from _nd),
+       '{"nd_probe": true}'::jsonb) $$,
+  'a suppressed offer carrying metadata is applied to the active member');
+
+select is(
+  (select (b.membership_state is not distinct from a.membership_state)
+       and (b.left_at          is not distinct from a.left_at)
+       and (b.role             is not distinct from a.role)
+     from _ndbefore b
+     cross join lateral (
+       select membership_state, left_at, role from agent_board.board_memberships
+        where board_id = (select board_id from _ndb) and agent_id = (select member_id from _nd)
+        order by case when membership_state in ('joined','subscribed') then 0 else 1 end,
+                 created_at desc, id desc
+        limit 1) a)::text,
+  'true',
+  '#317: a suppressed offer moves NONE of the authority-bearing columns — membership_state, left_at, role');
+
+select is(
+  (select (a.metadata ? 'nd_probe')::text
+     from agent_board.board_memberships a
+    where a.board_id = (select board_id from _ndb) and a.agent_id = (select member_id from _nd)
+    order by case when a.membership_state in ('joined','subscribed') then 0 else 1 end,
+             a.created_at desc, a.id desc
+    limit 1),
+  'true',
+  '#317 scope: the row IS still written — caller metadata merges on the suppressed path, which the migration states rather than implies');
+
+-- ---------------------------------------------------------------------------
+-- AN OFFER AGAINST THE OWNER'S OWN MEMBERSHIP. membership_state is written from the RESOLVED
+-- next state while `role` and `left_at` key off the caller's REQUEST; this pins that an offer
+-- costs the owner neither their standing nor their role.
+--
+-- Honest about what this does NOT cover, because the first version of this comment claimed more
+-- and a mutation refuted it: re-keying the #79 clamp to the resolved state leaves these
+-- assertions GREEN, since the clamp also requires a non-active prior state (or currently-removed
+-- standing) and a suppressed offer always has an active prior. The two spellings diverge only in
+-- the `v_currently_removed` corner, which this fixture does not build. Recorded rather than
+-- papered over -- an assertion that cannot fail for the reason its comment gives is exactly the
+-- shape this repo keeps finding.
+-- ---------------------------------------------------------------------------
+select is(
+  (select role from agent_board.board_memberships
+    where board_id = (select board_id from _ndb) and agent_id = (select owner_id from _nd)
+    order by case when membership_state in ('joined','subscribed') then 0 else 1 end, created_at desc, id desc
+    limit 1),
+  'owner',
+  'fixture: the board creator holds the owner role');
+
+select lives_ok(
+  $$ select agent_board._upsert_board_membership_state(
+       (select board_id from _ndb), (select owner_id from _nd), 'invited', (select owner_id from _nd)) $$,
+  'an offer is applied to the OWNER''s own active membership');
+
+select is(
+  (select role || '/' || membership_state from agent_board.board_memberships
+    where board_id = (select board_id from _ndb) and agent_id = (select owner_id from _nd)
+    order by case when membership_state in ('joined','subscribed') then 0 else 1 end, created_at desc, id desc
+    limit 1),
+  'owner/joined',
+  '#317: a suppressed offer leaves the owner at owner/joined — role and standing both survive an offer');
+
+-- ---------------------------------------------------------------------------
+-- THE MINTED-CONSENT TRAP, which is why the no-op emits NOTHING rather than the row's
+-- own state. The second draft of this migration "fixed" the false ledger by emitting
+-- v_membership.membership_state -- and that MINTS CONSENT: with no JWT the provenance is
+-- `operator-designated`, and `_membership_consent_present` treats operator-designated +
+-- joined/subscribed as an actual PLACEMENT. An operator merely OFFERING would have become
+-- an admission grant, reopening the exact narrowing MBCONSENT shipped to make.
+--
+-- It needs its OWN fixture: the member in the main scenario joined through the sink, so
+-- their ledger already carries a grant and consent reads true no matter what happens here.
+-- The trap is only visible on a membership whose ledger is SILENT -- which is reachable,
+-- because five shipped writers seat a row without routing through the sink.
+-- ---------------------------------------------------------------------------
+select agent_board.register_agent('agent', 'nd-silent', 'ND Silent');
+
+create temp table _ndsil on commit drop as
+select (select id from agent_board.agents where handle = 'nd-silent') as agent_id;
+
+-- seated directly, so the consent ledger says nothing about this agent
+insert into agent_board.board_memberships(board_id, agent_id, membership_state, role, created_by_agent_id)
+select (select board_id from _ndb), (select agent_id from _ndsil), 'joined', 'member', (select owner_id from _nd);
+
+select is(
+  agent_board._membership_consent_present((select board_id from _ndb), (select agent_id from _ndsil))::text,
+  'false',
+  '#317 fixture: the silently-seated member has NO consent on record — the precondition the trap needs');
+
+select lives_ok(
+  $$ select agent_board.invite_board_member(
+       (select board_id from _ndb), (select agent_id from _ndsil), (select owner_id from _nd)) $$,
+  'an operator invites the silently-seated JOINED member');
+
+select is(
+  (select count(*)::text from agent_board.board_membership_events
+    where board_id = (select board_id from _ndb) and agent_id = (select agent_id from _ndsil)),
+  '0',
+  '#317: a suppressed offer appends NO event at all — the ledger records state CHANGES, and nothing changed');
+
+select is(
+  agent_board._membership_consent_present((select board_id from _ndb), (select agent_id from _ndsil))::text,
+  'false',
+  '#317: the offer did NOT mint consent — emitting the row state here would have turned an operator OFFER into an admission grant');
+
+-- THE SECOND CONJUNCT of the suppression test, which nothing else reaches. `joined -> joined`
+-- also does not move the state, but it IS the caller getting exactly what they asked for, and it
+-- must still emit -- join_board and update_board_membership both permit it. Defining suppression
+-- as "the state did not move" alone silently stops emitting for that call, and left the whole
+-- suite green until this assertion existed.
+select lives_ok(
+  $$ select agent_board._upsert_board_membership_state(
+       (select board_id from _ndb), (select agent_id from _ndsil), 'joined', (select owner_id from _nd)) $$,
+  'the silently-seated member is re-asserted as joined');
+
+select is(
+  (select count(*)::text from agent_board.board_membership_events
+    where board_id = (select board_id from _ndb) and agent_id = (select agent_id from _ndsil)),
+  '1',
+  '#317: joined -> joined DOES emit — it moves no state but is not a suppressed offer, so the ledger records it');
+
+-- ---------------------------------------------------------------------------
+-- THE SUBSCRIBED ARM. The guard names two active states, and until this existed only
+-- `joined` was exercised: narrowing the guard to `in ('joined')` -- restoring the whole
+-- defect for every subscribed member -- left all 19 assertions green. Found by the review
+-- board, and it is the sharpest kind of miss: the rule was stated correctly in the
+-- migration and half of it was unverified.
+-- ---------------------------------------------------------------------------
+select lives_ok(
+  $$ select agent_board._upsert_board_membership_state(
+       (select board_id from _ndb), (select member_id from _nd), 'subscribed', (select member_id from _nd)) $$,
+  'the member self-toggles to subscribed');
+select is(pg_temp.nd_state(), 'subscribed', 'the member is subscribed');
+
+select lives_ok(
+  $$ select agent_board.invite_board_member(
+       (select board_id from _ndb), (select member_id from _nd), (select owner_id from _nd)) $$,
+  'inviting a SUBSCRIBED member does not raise');
+select is(pg_temp.nd_state(), 'subscribed',
+  '#317: inviting a SUBSCRIBED member leaves them subscribed — the guard covers BOTH active states, not just joined');
+
+-- Restore to subscribed FIRST, for the same reason the joined pair re-joins above: a mutation
+-- that drops only the `invited` arm would have demoted this member on the assertion before
+-- this one, and the pair below would then be testing requested-against-INVITED while reading
+-- as though it tested requested-against-SUBSCRIBED. Round 1 fixed this on the joined pair and
+-- left the subscribed pair contaminated; a review seat caught the other half.
+select lives_ok(
+  $$ select agent_board._upsert_board_membership_state(
+       (select board_id from _ndb), (select member_id from _nd), 'subscribed', (select member_id from _nd)) $$,
+  'restored to subscribed, so the `requested` arm below is evidenced against SUBSCRIBED');
+
+select lives_ok(
+  $$ select agent_board._upsert_board_membership_state(
+       (select board_id from _ndb), (select member_id from _nd), 'requested', (select member_id from _nd)) $$,
+  'a `requested` offer against a subscribed member does not raise');
+select is(pg_temp.nd_state(), 'subscribed',
+  '#317: `requested` against a SUBSCRIBED member also leaves them subscribed');
+
+-- Finding 1A: the ledger was pinned only at the JOINED stage, so the SUBSCRIBED arm of the
+-- suppression could emit a contradicting event with nothing reading it. It can now be checked
+-- here because nothing else writes this membership between the toggle and this point.
+select is(
+  (select result_state from agent_board.board_membership_events
+    where board_id = (select board_id from _ndb) and agent_id = (select member_id from _nd)
+    order by seq desc limit 1),
+  pg_temp.nd_state(),
+  '#317: the latest event still matches the row at the SUBSCRIBED stage too — the suppression arms are pinned symmetrically');
+
+-- restore to joined so the transitions below start from the state they describe
+select lives_ok(
+  $$ select agent_board._upsert_board_membership_state(
+       (select board_id from _ndb), (select member_id from _nd), 'joined', (select member_id from _nd)) $$,
+  'back to joined for the transition checks');
+
+-- ---------------------------------------------------------------------------
+-- THE OTHER DIRECTION: everything legitimate still works. Without these, a guard
+-- that simply refused all offers would pass the assertions above.
+-- ---------------------------------------------------------------------------
+select lives_ok(
+  $$ select agent_board._upsert_board_membership_state(
+       (select board_id from _ndb), (select member_id from _nd), 'subscribed', (select member_id from _nd)) $$,
+  'joined -> subscribed does not raise');
+select is(pg_temp.nd_state(), 'subscribed', 'joined -> subscribed self-toggle still works');
+
+select lives_ok(
+  $$ select agent_board._upsert_board_membership_state(
+       (select board_id from _ndb), (select member_id from _nd), 'removed', (select owner_id from _nd)) $$,
+  'active -> removed does not raise');
+select is(pg_temp.nd_state(), 'removed', 'active -> removed still works');
+
+-- Finding 1B: widening the suppression predicate to swallow a REAL transition left the suite
+-- green, because nothing asserted that a genuine state change still reaches the ledger. An
+-- append-only record that silently omits a removal is the same class of defect as one that
+-- records a state the row does not have.
+select is(
+  (select event_kind || ' -> ' || result_state from agent_board.board_membership_events
+    where board_id = (select board_id from _ndb) and agent_id = (select member_id from _nd)
+    order by seq desc limit 1),
+  'operator_removal -> removed',
+  '#317: a REAL transition still emits — suppression must not swallow an actual state change');
+
+select lives_ok(
+  $$ select agent_board._upsert_board_membership_state(
+       (select board_id from _ndb), (select member_id from _nd), 'invited', (select owner_id from _nd)) $$,
+  're-inviting a REMOVED member does not raise — an OVER-BROAD guard trips board_memberships_state_left_at here, and a bare call would abort the file with NO `not ok` (verified)');
+select is(pg_temp.nd_state(), 'invited',
+  're-inviting a REMOVED member still works — the guard is about weakening, not about offers');
+
+-- ---------------------------------------------------------------------------
+-- THE SECOND DOOR: invite-link redemption reaches an active membership by a
+-- different statement shape (INSERT … ON CONFLICT DO UPDATE), so the guard in the
+-- UPDATE path says nothing about it. Asserted behaviourally rather than by reading
+-- the source: `_redeem_unbounded_invite_for_agent` lifts only `role`, and this is
+-- what makes that claim evidence instead of a comment.
+-- ---------------------------------------------------------------------------
+select lives_ok(
+  $$ select agent_board._upsert_board_membership_state(
+       (select board_id from _ndb), (select member_id from _nd), 'joined', (select owner_id from _nd)) $$,
+  'the member is restored to joined for the invite-link probe');
+
+-- The preset is `subscribed` while the member is `joined`, DELIBERATELY: a link presetting
+-- the state the member already has cannot show whether redemption writes the column, so the
+-- probe would pass no matter what the function did. (`invited` would be the sharper contrast
+-- but create_invite_link rejects it -- "invalid preset membership state" -- so `subscribed`
+-- is the strongest observable difference available.)
+--
+-- `select * from`, not a bare call: create_invite_link RETURNS TABLE, so a scalar
+-- projection is a pseudo-type record and `create table as` errors -- which ABORTS the
+-- transaction. The run then stops early and pgTAP emits NO `not ok` line at all, so the
+-- failure is INVISIBLE rather than loud (message-board#113, and observed here).
+--
+-- Deliberately no assertion count in that sentence. It used to name one, and the number was
+-- stale within a day of being written -- a hand-maintained count of a machine-derivable fact
+-- is rule 1's own anti-pattern applied to prose. The invariant is that the failure prints
+-- nothing; the exact stopping point moves every time an assertion is added.
+-- lives_ok, not a bare statement. create_invite_link checks the creator's role against the
+-- board authority ceiling, so ANY mutation that weakens the owner's own membership earlier in
+-- this file makes it RAISE here -- and as a bare call that aborted the transaction at assertion
+-- 38, hiding every catalog and structural assertion after it. Measured: three separate
+-- behavioural mutations truncated the run to 38 of 52 that way, so a regression in the guard
+-- could conceal a simultaneous regression in the class assertions. This is the file's own
+-- subject matter applied to its own fixture.
+create temp table _ndlink(invite_id uuid, board_id uuid, code text, preset_role text,
+                          preset_membership_state text, max_uses int, uses_count int,
+                          expires_at timestamptz, created_at timestamptz) on commit drop;
+
+select lives_ok(
+  $$ insert into _ndlink select * from agent_board.create_invite_link(
+       (select board_id from _ndb), 'member', 'subscribed', null, null, (select owner_id from _nd)) $$,
+  'the owner can still create an invite link — a weakened owner membership fails HERE by name rather than aborting the file');
+
+-- lives_ok, not a bare `is((select … from rpc(…)))`: redemption is a state-mutating
+-- admission RPC, and a raise inside an assertion's value expression aborts the whole
+-- file with no `not ok` (message-board#113).
+select lives_ok(
+  $$ create temp table _ndcap as select * from agent_board._redeem_unbounded_invite_for_agent(
+       (select code from _ndlink), (select member_id from _nd)) $$,
+  'a JOINED member redeems a board invite link — redemption stays idempotent');
+select is(pg_temp.nd_state(), 'joined',
+  '#317 second door: redeeming a `subscribed`-preset link leaves a JOINED member joined — the ON CONFLICT lifts role only');
+
+-- ---------------------------------------------------------------------------
+-- THE CLASS, derived from pg_proc rather than from a list written here.
+--
+-- The guard lives in the shared sink so every caller inherits it. A future function that
+-- writes board_memberships.MEMBERSHIP_STATE directly would bypass it, and a hand-written list
+-- of "the writers that matter" is what this repo's rule 1 forbids -- so the set is enumerated
+-- from the catalog and these assertions NAME any new member.
+--
+-- WHY THE PREDICATE IS SHAPED THIS WAY -- each clause was forced by a mutation that
+-- ESCAPED an earlier draft, not chosen for tidiness:
+--
+--   * `stripped_body`, not `pg_get_functiondef`. The generated header carries
+--     `SET search_path = …` with no semicolon before the body, so `set[^;]*membership_state`
+--     over the full definition matched functions that only READ the column (join_board,
+--     onboard_federated_fleet_agent). The earlier draft hid that false positive behind an
+--     `update agent_board.board_memberships` conjunct -- and that conjunct was itself the
+--     hole below. stripped_body also strips comments and literals, so prose near a write
+--     cannot satisfy a claim (message-board#196/#199), and it RAISES rather than returning
+--     NULL for a body it cannot read, which a `where … ~ …` scan would drop silently.
+--
+--   * The statement alternation and the optional-qualifier spelling are TAKEN VERBATIM from
+--     agent_board_receipt_subject_gate.test.sql rather than written fresh. That file already
+--     paid for this: it records `merge into`, `update only`, `delete from only`,
+--     `agent_board."board_memberships"` and `"agent_board" . "board_memberships"` as
+--     VERIFIED-LEGAL spellings that were each invisible to a narrower pattern. A second pattern
+--     written here would be a second list to drift -- rule 1 applied to the predicate itself.
+--     The first draft of THIS file required `update agent_board.board_memberships` alone, and
+--     FOUR separate decoys each left it 19/19 green: `insert ... on conflict ... do update set`,
+--     `merge into`, an UNQUALIFIED `update board_memberships` under a search_path, and dynamic
+--     SQL inside a string literal. The review board found three of the four; the fourth came
+--     from testing its findings rather than accepting them.
+--
+--   * `stripped_body(p.oid, TRUE)` -- literals KEPT, deliberately, and this is the one place the
+--     usual advice inverts. A writer assembled as dynamic SQL lives ENTIRELY inside a string
+--     literal, so the default literal-stripping mode cannot see it. Comments are still stripped,
+--     so prose naming the pattern still cannot satisfy the claim. Keeping literals can only
+--     produce a LOUD false positive on an exact-set assertion, never a silent miss.
+--
+--   * `lower(...)` with `~` rather than `~*`: same effect, and it matches the neighbouring file
+--     so the two cannot drift on case handling.
+--
+-- WHAT THIS SCAN CANNOT SEE, stated exactly rather than generously, because a scan that reports
+-- clean on its own boundary forms is worth less than one that says which forms it declines to
+-- judge. All of these were DEMONSTRATED against this file, not imagined:
+--
+--   * a body that ASSEMBLES the statement rather than containing it. Two demonstrated forms:
+--     fragment concatenation (`'update agent_board.board_mem' || 'berships set ...'`) and
+--     `EXECUTE format('update %I.%I set %I = %L', 'agent_board', 'board_memberships',
+--     'membership_state', 'invited')`, where the identifiers live in format ARGUMENTS so neither
+--     the table nor the column is ever adjacent to the keyword. Keeping literals is what makes a
+--     single COMPLETE literal statement visible; it does nothing for an assembled one, because no
+--     regex can concatenate or interpolate. Neither can be closed by a better pattern -- only by
+--     a parser -- so both are disclosed and then BOUNDED structurally by the privilege assertion
+--     further down, which holds however the SQL is spelt.
+--   * a writer in a schema other than `agent_board` (the `nspname` filter). Same bound applies.
+--
+-- Both are recorded rather than closed. The privilege assertion is the reason that is an
+-- acceptable answer instead of a shrug: it does not identify such a writer, but it proves one
+-- could only exist as a SECURITY DEFINER function, which is the population this scan reads.
+--
+--   * `prokind in ('f','p')`. A PROCEDURE writer is exempt under `prokind = 'f'`.
+--
+--   * `\m` word boundaries. Without them the role canary below silently matched nothing.
+--
+-- A `BEGIN ATOMIC` writer is covered too: stripped_body falls back to
+-- pg_get_function_sqlbody, verified with a BEGIN ATOMIC decoy that this assertion named.
+select is(
+  (select coalesce(array_agg(p.proname::text order by p.proname::text), array[]::text[])
+     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')
+      and lower(agent_board_test.stripped_body(p.oid, true))
+          ~ '(insert\s+into|merge\s+into|update|delete\s+from|copy|truncate(\s+table)?)(\s+only)?\s+(("?agent_board"?\s*\.\s*)?board_memberships\M|("?agent_board"?\s*\.\s*)?"board_memberships")'),
+  array['_fedsession_autojoin_default_board', '_redeem_unbounded_invite_for_agent',
+        '_upsert_board_membership_state', 'bootstrap_board_owner_memberships',
+        'create_board', 'grant_board_role']::text[],
+  '#317: the set of functions that WRITE board_memberships is exactly these six — a new writer fails here NAMING itself');
+
+-- The direction claim itself: of those writers, only the shared sink assigns
+-- membership_state in a SET clause, so only the sink can move an EXISTING row between
+-- states -- and it is the one carrying the guard. The other five are exempt because of
+-- what they write, and that is asserted here as a set rather than by leaving names out;
+-- an exemption claimed by absence is this repo's named soft spot.
+select is(
+  (select coalesce(array_agg(p.proname::text order by p.proname::text), array[]::text[])
+     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')
+      and lower(agent_board_test.stripped_body(p.oid, true))
+          ~ '(insert\s+into|merge\s+into|update|delete\s+from|copy|truncate(\s+table)?)(\s+only)?\s+(("?agent_board"?\s*\.\s*)?board_memberships\M|("?agent_board"?\s*\.\s*)?"board_memberships")'
+      and lower(agent_board_test.stripped_body(p.oid, true))
+          ~ '(set\s[^;]*\mmembership_state"?\s*=|set\s*\([^;()]*\mmembership_state"?[^;()]*\)\s*=)'),
+  array['_upsert_board_membership_state']::text[],
+  '#317: the shared sink is the ONLY writer that assigns membership_state IN A SET CLAUSE — i.e. the only one that can MOVE an existing row between states');
+
+-- POSITIVE CANARY for the SET-clause predicate the assertion above depends on. Without
+-- this, a regex that stopped matching SET clauses at all would make that assertion green
+-- and empty -- the exact fail-open this file exists to prevent. These five DO assign
+-- `role` in a SET clause, so the predicate is proven to still see real SET clauses.
+select is(
+  (select coalesce(array_agg(p.proname::text order by p.proname::text), array[]::text[])
+     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')
+      and lower(agent_board_test.stripped_body(p.oid, true))
+          ~ '(insert\s+into|merge\s+into|update|delete\s+from|copy|truncate(\s+table)?)(\s+only)?\s+(("?agent_board"?\s*\.\s*)?board_memberships\M|("?agent_board"?\s*\.\s*)?"board_memberships")'
+      and lower(agent_board_test.stripped_body(p.oid, true)) ~ 'set\s[^;]*\mrole\s*='),
+  array['_redeem_unbounded_invite_for_agent', '_upsert_board_membership_state',
+        'bootstrap_board_owner_memberships', 'create_board', 'grant_board_role']::text[],
+  '#317 canary: the SET-clause predicate still matches real SET clauses (these five assign `role`) — so an empty membership_state result means empty, not blind');
+
+-- THE DOORS THAT ARE NOT FUNCTION BODIES. Every predicate above reads function source, so
+-- anything that writes membership_state WITHOUT a function body naming the table is invisible
+-- to all of them. Three such doors exist and all three are asserted, because two of them were
+-- found only by a review seat asking what was not a function:
+--
+--   * a TRIGGER assigning NEW.membership_state;
+--   * a non-SELECT RULE rewriting a statement onto the table;
+--   * an auto-updatable VIEW -- `update agent_board.<view> set membership_state = ...` is
+--     rewritten by PostgreSQL onto the base table with NO trigger and NO mention of
+--     `board_memberships` anywhere in the writer's body. Verified: a decoy view plus a writer
+--     through it left the whole suite green before this assertion existed.
+--
+-- The view set is pinned by NAME rather than by "no views exist", because two legitimately do.
+-- A new view over this table is then a loud event that forces its author to decide whether it
+-- is writable, which is the decision that would otherwise be made silently.
+select is(
+  (select coalesce(array_agg(t.tgname::text order by t.tgname::text), array[]::text[])
+     from pg_trigger t
+     join pg_class c on c.oid = t.tgrelid
+     join pg_namespace n on n.oid = c.relnamespace
+    where n.nspname = 'agent_board' and c.relname = 'board_memberships'
+      and not t.tgisinternal),
+  array[]::text[],
+  '#317: no user trigger on board_memberships — a trigger assigning NEW.membership_state would bypass every source predicate above');
+
+select is(
+  (select coalesce(array_agg(r.rulename::text order by r.rulename::text), array[]::text[])
+     from pg_rewrite r
+     join pg_class c on c.oid = r.ev_class
+     join pg_namespace n on n.oid = c.relnamespace
+    where n.nspname = 'agent_board' and c.relname = 'board_memberships'
+      and r.ev_type <> '1'),
+  array[]::text[],
+  '#317: no INSERT/UPDATE/DELETE rule on board_memberships — a rule rewrites a statement onto the table with no function body naming it');
+
+-- ---------------------------------------------------------------------------
+-- THE STRUCTURAL BOUND, which is the one claim here that a regex cannot be talked out of.
+--
+-- Everything above enumerates writers by READING SOURCE, and a source scan has a floor: a
+-- body that assembles `update agent_board.board_' || 'memberships set ...` from separate
+-- string fragments and EXECUTEs the result is invisible to any pattern, because no regex can
+-- concatenate. That escape was demonstrated against this very file (it stayed 35/35 green),
+-- and it cannot be closed by a better regex -- only by a parser.
+--
+-- What CAN be stated without reading source: nobody but the table owner may write this table
+-- at all. `authenticated`, `anon` and `service_role` hold no INSERT/UPDATE/DELETE, so every
+-- write -- fragment-assembled or not -- must go through a SECURITY DEFINER function owned by
+-- the owner. That does not identify the writer, but it bounds WHERE one can exist to the set
+-- the scan above enumerates, and it holds regardless of how the statement is spelled.
+--
+-- has_table_privilege, not a pg_class.relacl or information_schema read: it resolves privileges
+-- inherited through role membership and PUBLIC defaults, which a direct-grant read misses --
+-- the fail-open shape #302 corrected and #118's drop/recreate class. Verified on a built
+-- database that all three routes read false here, including the PUBLIC default, and that none
+-- of these roles reaches the owner via pg_has_role.
+--
+-- SCOPE, because "no role may write it" would otherwise overstate: this asserts the three
+-- APPLICATION principals. A SUPERUSER (supabase_admin) and the owner itself are outside any
+-- in-database privilege check by construction -- no assertion written in SQL can bound them,
+-- and saying so is more useful than a claim that quietly excludes them. `service_role` carries
+-- BYPASSRLS, which is deliberately NOT the same thing: it defeats row-level policies and does
+-- nothing about table privileges, so it still holds no UPDATE here.
+-- ---------------------------------------------------------------------------
+select is(
+  (select coalesce(array_agg(g.grant_found order by g.grant_found), array[]::text[])
+     from (
+       select r.rolname || ':' || t.tbl || ':' || t.priv as grant_found
+         from (values ('authenticated'), ('anon'), ('service_role')) as r(rolname)
+        cross join (values
+                     -- direct writes to the table
+                     ('agent_board.board_memberships', 'INSERT'),
+                     ('agent_board.board_memberships', 'UPDATE'),
+                     ('agent_board.board_memberships', 'DELETE'),
+                     -- TRUNCATE is a WRITE by this file's own definition: the statement scan
+                     -- above counts `truncate` as a writer. Checking only INSERT/UPDATE/DELETE
+                     -- made the privilege bound NARROWER than the scan it is supposed to
+                     -- backstop -- a role holding only TRUNCATE could empty the table and fail
+                     -- neither. Found by a review seat comparing the two lists against each other.
+                     ('agent_board.board_memberships', 'TRUNCATE'),
+                     -- THE CASCADE PARENTS, and they are load-bearing rather than thorough.
+                     -- board_id and agent_id are ON DELETE CASCADE, so deleting a board or an
+                     -- agent DESTROYS membership rows through internal FK triggers -- with no
+                     -- privilege on board_memberships and no SECURITY DEFINER function anywhere.
+                     -- Measured: 2 membership rows -> 0 on one `delete from agent_board.boards`.
+                     -- That is exactly the write class this assertion claimed could not exist,
+                     -- reached through a table the assertion never mentioned. It is closed in
+                     -- the shipped grant set, and now it is closed BY ASSERTION rather than by
+                     -- the accident of nobody having granted it. (It also reproduces #317's
+                     -- original symptom -- a member with no visible membership -- by a different
+                     -- mechanism, which is worth knowing next time that symptom is reported.)
+                     ('agent_board.boards', 'DELETE'),
+                     ('agent_board.agents', 'DELETE')
+                   ) as t(tbl, priv)
+        where has_table_privilege(r.rolname, t.tbl, t.priv)
+     ) g),
+  array[]::text[],
+  '#317 structural bound: no application role can write board_memberships directly, empty it, or destroy its rows through an ON DELETE CASCADE parent');
+
+select is(
+  (select coalesce(array_agg(p.proname::text order by p.proname::text), array[]::text[])
+     from pg_proc p
+     join pg_namespace n on n.oid = p.pronamespace
+    where n.nspname = 'agent_board'
+      and p.proname in ('_fedsession_autojoin_default_board', '_redeem_unbounded_invite_for_agent',
+                        '_upsert_board_membership_state', 'bootstrap_board_owner_memberships',
+                        'create_board', 'grant_board_role')
+      and not p.prosecdef),
+  array[]::text[],
+  '#317: every one of the six FUNCTION writers is SECURITY DEFINER — a function writer that is not would need a direct table grant, which the assertion above forbids (FK cascade is covered there, not here)');
+
+select is(
+  (select coalesce(array_agg(distinct c.relname::text order by c.relname::text), array[]::text[])
+     from pg_depend d
+     join pg_rewrite r on r.oid = d.objid
+     join pg_class c on c.oid = r.ev_class
+     join pg_class t on t.oid = d.refobjid
+     join pg_namespace tn on tn.oid = t.relnamespace
+     join pg_namespace cn on cn.oid = c.relnamespace
+    where tn.nspname = 'agent_board' and t.relname = 'board_memberships'
+      and cn.nspname = 'agent_board' and c.relkind in ('v', 'm')),
+  array['v_board_directory', 'v_board_memberships']::text[],
+  '#317: exactly these two views read board_memberships — a NEW view is auto-updatable by default, and an update through it reaches the table with nothing naming it');
+
+-- ---------------------------------------------------------------------------
+-- THE WHOLE INPUT SPACE, not a chosen path through it. Every assertion above walks ONE
+-- scenario, and a scenario can only show that the cases someone thought of behave. This
+-- drives all 6x6 (prior state, requested state) pairs through the sink and asserts two
+-- things about the result set as a whole:
+--
+--   * the suppressed set is EXACTLY the four offer-against-active pairs, named. A guard
+--     that is too narrow drops a pair; one that is too broad adds one; either way the
+--     assertion prints the actual set, so it says what went wrong rather than just that
+--     something did.
+--   * no pair RAISES. The over-broad-guard mutation trips
+--     `board_memberships_state_left_at` on a transition no scenario above visits, and a
+--     raise inside a scenario is what truncates a pgTAP file silently.
+--
+-- The ledger is cleared between seating the prior state and the call under test, so the
+-- count measures only that call.
+-- ---------------------------------------------------------------------------
+create temp table _ndmx(prior text, req text, after_state text, events int, err text) on commit drop;
+
+select lives_ok($$
+do $mx$
+declare
+  st text[] := array['requested','invited','joined','subscribed','left','removed'];
+  p text; r text; v_b uuid; v_a uuid; v_o uuid; n int; after_s text; i int := 0;
+begin
+  foreach p in array st loop
+    foreach r in array st loop
+      i := i + 1;
+      begin
+        perform agent_board.register_agent('agent','ndmx-o-'||i,'O');
+        perform agent_board.register_agent('agent','ndmx-m-'||i,'M');
+        select a.id into v_o from agent_board.agents a where a.handle='ndmx-o-'||i;
+        select a.id into v_a from agent_board.agents a where a.handle='ndmx-m-'||i;
+        perform agent_board.create_board(v_o,'ndmx-b-'||i,'B');
+        select b.id into v_b from agent_board.boards b where b.slug='ndmx-b-'||i;
+        perform agent_board._upsert_board_membership_state(v_b, v_a, p, v_o);
+        delete from agent_board.board_membership_events where board_id=v_b and agent_id=v_a;
+        perform agent_board._upsert_board_membership_state(v_b, v_a, r, v_o);
+        select membership_state into after_s from agent_board.board_memberships
+          where board_id=v_b and agent_id=v_a
+          order by case when membership_state in ('joined','subscribed') then 0 else 1 end,
+                   created_at desc, id desc limit 1;
+        select count(*) into n from agent_board.board_membership_events
+          where board_id=v_b and agent_id=v_a;
+        insert into _ndmx values (p, r, after_s, n, null);
+      exception when others then
+        insert into _ndmx values (p, r, null, null, substr(sqlerrm,1,60));
+      end;
+    end loop;
+  end loop;
+end $mx$;
+$$, 'the 6x6 transition matrix runs to completion');
+
+select is(
+  (select coalesce(array_agg(prior || '+' || req order by prior, req), array[]::text[])
+     from _ndmx where err is not null),
+  array[]::text[],
+  '#317 matrix: no (prior, requested) pair RAISES — a raise here is the silent-truncation failure mode, and no scenario above visits every pair');
+
+select is(
+  (select coalesce(array_agg(prior || '+' || req order by prior, req), array[]::text[])
+     from _ndmx where err is null and events = 0),
+  array['joined+invited', 'joined+requested', 'subscribed+invited', 'subscribed+requested']::text[],
+  '#317 matrix: EXACTLY the four offer-against-active pairs are suppressed — too narrow drops one, too broad adds one, and this names which');
+
+select is(
+  (select coalesce(array_agg(prior || '+' || req || '->' || coalesce(after_state,'?') order by prior, req), array[]::text[])
+     from _ndmx
+    where err is null
+      and events <> (case when after_state is not distinct from prior and req is distinct from after_state then 0 else 1 end)),
+  array[]::text[],
+  '#317 matrix: across all 36 pairs the ledger is written exactly when the state moved or the caller got what they asked for');
+
+select * from finish();
+rollback;