@consiliency/agent-board-schema 1.12.0 → 1.23.0

package/tests/agent_board_consent_emission.test.sql

@@ -0,0 +1,601 @@
+-- MBCONSENT-B(a) pgTAP: EMISSION only. No gating.
+--
+-- The claim under test: every membership transition writes exactly one ledger event whose
+-- provenance is DERIVED FROM THE SESSION and cannot be influenced by any caller argument.
+--
+-- Methodology:
+--   * RPC probes are driven by the JWT claim triplet only. SET LOCAL ROLE is never used here:
+--     it would revoke _is_service_role() and mask the operator branch behind a permission
+--     error on the function itself.
+--   * p_created_by_agent_id is passed DELIBERATELY WRONG in the anti-forge cases. If provenance
+--     were keyed off it rather than the session, those assertions flip.
+create extension if not exists pgtap with schema extensions;
+set search_path = extensions, public, agent_board;
+
+begin;
+
+select plan(68);
+
+create function pg_temp.claims(p_sub text) returns void language plpgsql as $$
+begin
+  perform set_config('request.jwt.claims', json_build_object('role','authenticated','sub',p_sub)::text, true);
+end $$;
+create function pg_temp.service() returns void language plpgsql as $$
+begin
+  perform set_config('request.jwt.claims', '', true);
+end $$;
+create function pg_temp.latest(p_agent uuid)
+returns table(kind text, prov text, actor uuid, state text) language sql as $$
+  select event_kind, provenance, actor_agent_id, result_state
+    from agent_board.board_membership_events
+   where agent_id = p_agent order by seq desc limit 1;
+$$;
+
+insert into auth.users(id, instance_id, aud, role, email)
+select ('f0000000-0000-0000-0000-' || lpad(n::text,12,'0'))::uuid,
+       '00000000-0000-0000-0000-000000000000', 'authenticated', 'authenticated',
+       'emit'||n||'@t.test'
+from generate_series(1,6) n;
+
+insert into agent_board.agents(id, agent_type, kind, handle, display_name, status, auth_user_id)
+select ('f1000000-0000-4000-8000-' || lpad(n::text,12,'0'))::uuid,
+       'agent','agent','emit-agent-'||n,'Emit Agent '||n,'active',
+       ('f0000000-0000-0000-0000-' || lpad(n::text,12,'0'))::uuid
+from generate_series(1,6) n;
+
+insert into agent_board.boards(id, slug, name, created_by_agent_id, visibility, status)
+values ('f2000000-0000-4000-8000-000000000001','emit-b1','Emit B1',
+        'f1000000-0000-4000-8000-000000000001','private','active');
+
+-- ===========================================================================
+-- 1. Every transition emits exactly ONE event
+-- ===========================================================================
+select pg_temp.claims('f0000000-0000-0000-0000-000000000002');
+select lives_ok($$
+  select agent_board._upsert_board_membership_state(
+    'f2000000-0000-4000-8000-000000000001','f1000000-0000-4000-8000-000000000002','joined')
+$$, 'emission: a self-join succeeds');
+
+select is(
+  (select count(*)::int from agent_board.board_membership_events
+    where agent_id = 'f1000000-0000-4000-8000-000000000002'),
+  1,
+  'emission: exactly ONE event per transition, not zero and not two');
+
+
+-- ===========================================================================
+-- 2. Provenance is derived from the SESSION, not from any argument
+-- ===========================================================================
+select is((select prov from pg_temp.latest('f1000000-0000-4000-8000-000000000002')),
+  'target-authored', 'derivation: the subject acting on itself is target-authored');
+select is((select actor from pg_temp.latest('f1000000-0000-4000-8000-000000000002')),
+  'f1000000-0000-4000-8000-000000000002'::uuid, 'derivation: ...with the subject as actor');
+select is((select kind from pg_temp.latest('f1000000-0000-4000-8000-000000000002')),
+  'consent_self_join', 'derivation: ...and the self-join kind');
+
+-- ANTI-FORGE. p_created_by_agent_id is a caller ASSERTION; the session is EVIDENCE. Here the
+-- argument NAMES THE SUBJECT while the session is a third party. If provenance were keyed off
+-- the argument this would read target-authored -- a forged consent event.
+select pg_temp.claims('f0000000-0000-0000-0000-000000000001');
+select lives_ok($$
+  select agent_board._upsert_board_membership_state(
+    'f2000000-0000-4000-8000-000000000001','f1000000-0000-4000-8000-000000000003','invited',
+    'f1000000-0000-4000-8000-000000000003')
+$$, 'anti-forge setup: a third party acts, naming the SUBJECT in p_created_by_agent_id');
+
+select is((select prov from pg_temp.latest('f1000000-0000-4000-8000-000000000003')),
+  'board-authored',
+  'ANTI-FORGE: provenance follows the SESSION, not p_created_by_agent_id');
+select is((select actor from pg_temp.latest('f1000000-0000-4000-8000-000000000003')),
+  'f1000000-0000-4000-8000-000000000001'::uuid,
+  'ANTI-FORGE: ...and the actor is the real session, not the named argument');
+select isnt((select actor from pg_temp.latest('f1000000-0000-4000-8000-000000000003')),
+  'f1000000-0000-4000-8000-000000000003'::uuid,
+  'ANTI-FORGE: the subject is NOT recorded as having acted');
+
+-- ===========================================================================
+-- 3. service_role is ALWAYS operator-designated -- even with a resolvable subject
+-- ===========================================================================
+-- This is the laundering path a review caught on the abandoned larger change: an operator
+-- acting while some agent id happens to resolve from its token was recorded as the subject's
+-- own act. An operator placement is an operator placement.
+select pg_temp.service();
+select lives_ok($$
+  select agent_board._upsert_board_membership_state(
+    'f2000000-0000-4000-8000-000000000001','f1000000-0000-4000-8000-000000000004','joined',
+    'f1000000-0000-4000-8000-000000000004')
+$$, 'operator setup: service_role places a subject');
+
+select is((select prov from pg_temp.latest('f1000000-0000-4000-8000-000000000004')),
+  'operator-designated', 'OPERATOR: service_role records operator-designated');
+select is((select actor from pg_temp.latest('f1000000-0000-4000-8000-000000000004')),
+  null::uuid, 'OPERATOR: ...with a NULL actor');
+select is((select kind from pg_temp.latest('f1000000-0000-4000-8000-000000000004')),
+  'operator_designation', 'OPERATOR: ...and the designation kind');
+
+-- ...and with a subject RESOLVABLE from the service session, it is STILL operator-designated.
+select set_config('request.jwt.claims',
+  '{"role":"service_role","sub":"f0000000-0000-0000-0000-000000000004"}', true);
+select lives_ok($$
+  select agent_board._upsert_board_membership_state(
+    'f2000000-0000-4000-8000-000000000001','f1000000-0000-4000-8000-000000000004','subscribed')
+$$, 'operator setup: service_role acts with a RESOLVABLE subject in its token');
+select is((select prov from pg_temp.latest('f1000000-0000-4000-8000-000000000004')),
+  'operator-designated',
+  'OPERATOR: a resolvable subject does NOT make an operator action target-authored');
+select is((select actor from pg_temp.latest('f1000000-0000-4000-8000-000000000004')),
+  null::uuid, 'OPERATOR: ...actor stays NULL');
+
+-- ===========================================================================
+-- 4. An unattributable write FAILS CLOSED
+-- ===========================================================================
+-- Neither service_role nor a resolvable actor. An earlier draft of this logic labelled that
+-- case operator-designated, which manufactures evidence of an operator placement that never
+-- happened. It must raise instead.
+select pg_temp.claims('00000000-0000-0000-0000-0000000000ff');
+select throws_ok($$
+  select agent_board._upsert_board_membership_state(
+    'f2000000-0000-4000-8000-000000000001','f1000000-0000-4000-8000-000000000002','left')
+$$, '42501', 'membership change has no attributable actor',
+   'FAIL CLOSED: an unattributable write raises rather than inventing a provenance');
+
+-- STATEMENT-LEVEL ATOMICITY. The refused write above did not just skip the LEDGER (section 6
+-- pins the empty ledger); the membership WRITE that preceded the failing emit rolled back with
+-- it. _upsert writes the row and PERFORMs _emit in ONE function body, so an emit exception
+-- unwinds the row too -- no partial `left` can commit. Agent 2 was `joined` before the refused
+-- `left`; had the write leaked it would read `left` here.
+-- This is NOT redundant with the ledger-empty check: an autonomous/independent membership write
+-- would still raise, still leave the ledger empty, and still commit the `left` -- only reading
+-- the membership row catches that leak.
+select is(
+  (select membership_state from agent_board.board_memberships
+    where board_id = 'f2000000-0000-4000-8000-000000000001'
+      and agent_id = 'f1000000-0000-4000-8000-000000000002'),
+  'joined',
+  'ATOMICITY: the refused write rolled its membership row back too -- state is still joined, no partial left committed');
+
+-- ===========================================================================
+-- 5. Event-kind mapping across the state space
+-- ===========================================================================
+select pg_temp.claims('f0000000-0000-0000-0000-000000000002');
+select lives_ok($$ select agent_board._upsert_board_membership_state(
+  'f2000000-0000-4000-8000-000000000001','f1000000-0000-4000-8000-000000000002','left') $$,
+  'kinds setup: the subject leaves');
+select is((select kind from pg_temp.latest('f1000000-0000-4000-8000-000000000002')),
+  'self_withdraw', 'kinds: target-authored + left is a self-withdraw, not an eviction');
+
+select pg_temp.claims('f0000000-0000-0000-0000-000000000001');
+select lives_ok($$ select agent_board._upsert_board_membership_state(
+  'f2000000-0000-4000-8000-000000000001','f1000000-0000-4000-8000-000000000002','removed') $$,
+  'kinds setup: a third party removes');
+select is((select kind from pg_temp.latest('f1000000-0000-4000-8000-000000000002')),
+  'eviction', 'kinds: board-authored + removed is an eviction, not a self-withdraw');
+
+select pg_temp.claims('f0000000-0000-0000-0000-000000000002');
+select lives_ok($$ select agent_board._upsert_board_membership_state(
+  'f2000000-0000-4000-8000-000000000001','f1000000-0000-4000-8000-000000000002','requested') $$,
+  'kinds setup: the subject requests');
+select is((select kind from pg_temp.latest('f1000000-0000-4000-8000-000000000002')),
+  'consent_join_request', 'kinds: target-authored + requested is a join request');
+
+-- Exactly-once ACROSS THE CALL GRAPH, driven through a FACADE rather than the sink. Counting
+-- call sites per function cannot see double-emission: adding a second emit to a wrapper that
+-- already calls the emitting sink leaves BOTH functions with one textual call while a single
+-- transition writes two events. Placed here, after the derivation assertions, because it moves
+-- agent 2's state and would otherwise change what a later assertion reads.
+-- Counted RELATIVE to this call, via the seq high-water mark. An absolute count over the
+-- subject's history is polluted by earlier sections -- it read 2 because a previous test had
+-- already written a `left` for this agent, and that failure looks exactly like a real
+-- double-emission defect.
+create temporary table _seq_mark on commit drop as
+select coalesce(max(seq), 0) as seq from agent_board.board_membership_events;
+
+select pg_temp.claims('f0000000-0000-0000-0000-000000000002');
+select lives_ok($$
+  select agent_board.update_board_membership(
+    'f2000000-0000-4000-8000-000000000001','f1000000-0000-4000-8000-000000000002','left')
+$$, 'call-graph setup: a transition driven through the update_board_membership facade');
+
+select is(
+  (select count(*)::int from agent_board.board_membership_events e
+    where e.seq > (select seq from _seq_mark)),
+  1,
+  'emission: a FACADE transition emits once across the whole call graph, not twice');
+
+-- ===========================================================================
+-- 5b. COMPLETENESS -- every writer emits, not just the shared sink
+-- ===========================================================================
+-- The first version of this migration instrumented ONLY _upsert_board_membership_state. Four
+-- functions write board_memberships DIRECTLY and emitted nothing, so a membership created
+-- through them carried a SILENT ledger and would read as non-consenting once gating lands.
+-- This assertion pins the completeness claim itself, derived from the catalog rather than from
+-- a hand-maintained list -- a new writer added later will fail it.
+-- Covers INSERT **and** UPDATE writers, and fails CLOSED: a function that writes
+-- board_memberships must either emit, or appear on the exemption list below with a stated
+-- reason. Keying only on INSERT would miss a future path that flips membership_state via
+-- UPDATE -- and catching FUTURE writers is the entire purpose of this assertion.
+--
+-- The single exemption is grant_board_role: it sets `role` only, with membership_state
+-- appearing exclusively in its WHERE clauses, so it cannot change membership state and a role
+-- change is not a consent event. If that ever stops being true, this assertion fails.
+-- COMMENTS ARE STRIPPED and CALL SITES ARE COUNTED. Checking that the emitter name appears
+-- anywhere in the body is fail-open twice over: the name in a comment or a dead branch would
+-- satisfy it, and calling the emitter TWICE would too -- while this suite claims exactly one
+-- event per transition.
+-- Strips BOTH comment forms. The first version stripped only `--`, so a /* */ commented-out
+-- call still satisfied the completeness assertion.
+create function pg_temp.code(p_oid oid) returns text language sql stable as $$
+  select regexp_replace(
+           regexp_replace(pg_get_functiondef(p_oid), '/\*.*?\*/', '', 'gs'),
+           '--[^\n]*', '', 'g');
+$$;
+
+select is(
+  (select coalesce(string_agg(p.proname, ', ' order by p.proname), '')
+     from pg_proc p join pg_namespace n on n.oid = p.pronamespace
+    where n.nspname = 'agent_board' and p.prokind = 'f'
+      and p.prolang <> (select oid from pg_language where lanname = 'internal')
+      and pg_temp.code(p.oid) ~* '(insert into|update)[[:space:]]+agent_board\.board_memberships'
+      and pg_temp.code(p.oid) !~ 'perform agent_board\._emit_membership_event'
+      and p.proname <> 'grant_board_role'),
+  '',
+  'COMPLETENESS: every function writing board_memberships emits, or is a stated exemption');
+
+-- ...and none of them emits MORE than once, which would break one-event-per-transition.
+select is(
+  (select coalesce(string_agg(p.proname || '=' ||
+            (length(pg_temp.code(p.oid)) - length(replace(pg_temp.code(p.oid),
+              'perform agent_board._emit_membership_event', '')))
+            / length('perform agent_board._emit_membership_event'), ', ' order by p.proname), '')
+     from pg_proc p join pg_namespace n on n.oid = p.pronamespace
+    where n.nspname = 'agent_board' and p.prokind = 'f'
+      and p.prolang <> (select oid from pg_language where lanname = 'internal')
+      and pg_temp.code(p.oid) ~ 'perform agent_board\._emit_membership_event'
+      and (length(pg_temp.code(p.oid)) - length(replace(pg_temp.code(p.oid),
+            'perform agent_board._emit_membership_event', '')))
+          / length('perform agent_board._emit_membership_event') <> 1),
+  '',
+  'COMPLETENESS: no writer emits more than once (exactly one event per transition)');
+
+-- ...and the one exemption is genuinely state-blind: membership_state never appears in a SET.
+select ok(
+  (select pg_get_functiondef(p.oid) !~* 'set[^;]*membership_state[[:space:]]*='
+     from pg_proc p join pg_namespace n on n.oid = p.pronamespace
+    where n.nspname = 'agent_board' and p.proname = 'grant_board_role'),
+  'COMPLETENESS: the exemption holds -- grant_board_role never SETs membership_state');
+
+-- ...and the emitter itself is the single implementation, not five copies.
+select is(
+  (select count(*)::int
+     from pg_proc p join pg_namespace n on n.oid = p.pronamespace
+    where n.nspname = 'agent_board' and p.prokind = 'f'
+      and p.proname <> '_emit_membership_event'
+      and pg_get_functiondef(p.oid) ~* 'insert into[[:space:]]+agent_board\.board_membership_events'),
+  0,
+  'COMPLETENESS: only _emit_membership_event writes the ledger -- the derivation cannot drift');
+
+-- ===========================================================================
+-- 5c. The RAW WRITERS, exercised behaviourally with their FROZEN event kinds
+-- ===========================================================================
+-- Instrumenting them is not enough: the frozen mapping names SPECIFIC kinds that a generic
+-- (provenance, state) derivation cannot produce -- owner_seed, consent_link_redeem,
+-- operator_repair. A structural check that "the emitter is called" would miss a wrong kind.
+
+select pg_temp.claims('f0000000-0000-0000-0000-000000000003');
+select lives_ok($$
+  select agent_board.create_board('f1000000-0000-4000-8000-000000000003',
+    'emit-owned', 'Emit Owned', null, '{}'::jsonb, 'private')
+$$, 'raw writer setup: an agent creates a board');
+
+select is((select kind from pg_temp.latest('f1000000-0000-4000-8000-000000000003')),
+  'owner_seed',
+  'RAW WRITER: create_board emits owner_seed, not the generic consent_self_join');
+select is((select prov from pg_temp.latest('f1000000-0000-4000-8000-000000000003')),
+  'target-authored',
+  'RAW WRITER: ...target-authored, because the creator seeds their OWN seat');
+
+-- A board whose owner has NO membership row -- exactly what bootstrap exists to repair.
+insert into agent_board.boards(id, slug, name, created_by_agent_id, visibility, status)
+values ('f2000000-0000-4000-8000-000000000009','emit-orphan','Emit Orphan',
+        'f1000000-0000-4000-8000-000000000004','private','active');
+
+select pg_temp.service();
+select lives_ok($$ select agent_board.bootstrap_board_owner_memberships() $$,
+  'raw writer setup: operator bootstrap runs');
+
+-- Asserting the EVENT, not merely that the call lives. A structural check cannot prove the
+-- emit is REACHABLE -- moving it into `if false then` would satisfy one. Only this can.
+select is(
+  (select event_kind from agent_board.board_membership_events
+    where board_id = 'f2000000-0000-4000-8000-000000000009'
+      and agent_id = 'f1000000-0000-4000-8000-000000000004'
+    order by seq desc limit 1),
+  'operator_repair',
+  'RAW WRITER: bootstrap emits operator_repair, not the generic operator_designation');
+
+select is(
+  (select provenance from agent_board.board_membership_events
+    where board_id = 'f2000000-0000-4000-8000-000000000009'
+      and agent_id = 'f1000000-0000-4000-8000-000000000004'
+    order by seq desc limit 1),
+  'operator-designated',
+  'RAW WRITER: ...operator-designated, never the owner''s own act');
+
+select is(
+  (select result_state from agent_board.board_membership_events
+    where board_id = 'f2000000-0000-4000-8000-000000000009'
+      and agent_id = 'f1000000-0000-4000-8000-000000000004'
+    order by seq desc limit 1),
+  (select membership_state from agent_board.board_memberships
+    where board_id = 'f2000000-0000-4000-8000-000000000009'
+      and agent_id = 'f1000000-0000-4000-8000-000000000004'),
+  'RAW WRITER: bootstrap records the ACTUAL row state, not a literal');
+
+-- REDEEM MUST RECORD THE ACTUAL OUTCOME, NOT THE TOKEN'S PRESET.
+-- The redeem upsert's ON CONFLICT lifts only the ROLE and leaves an existing membership_state
+-- untouched. So an already-SUBSCRIBED member redeeming a JOINED-preset link stays subscribed --
+-- and emitting the preset would write a ledger row that contradicts the table it describes.
+insert into agent_board.board_memberships(board_id, agent_id, role, membership_state, created_by_agent_id)
+values ('f2000000-0000-4000-8000-000000000001','f1000000-0000-4000-8000-000000000005',
+        'member','subscribed','f1000000-0000-4000-8000-000000000001');
+
+insert into agent_board.board_invite_tokens(code, board_id, preset_role, preset_membership_state,
+                                            max_uses, expires_at, created_by_agent_id)
+values ('emit-token-1','f2000000-0000-4000-8000-000000000001','member','joined',
+        5, now() + interval '7 days','f1000000-0000-4000-8000-000000000001');
+
+select pg_temp.claims('f0000000-0000-0000-0000-000000000005');
+select lives_ok($$
+  select agent_board._redeem_invite_for_agent('emit-token-1','f1000000-0000-4000-8000-000000000005')
+$$, 'redeem setup: an already-SUBSCRIBED member redeems a JOINED-preset link');
+
+select is(
+  (select membership_state from agent_board.board_memberships
+    where board_id = 'f2000000-0000-4000-8000-000000000001'
+      and agent_id = 'f1000000-0000-4000-8000-000000000005'),
+  'subscribed',
+  'redeem: the membership row STAYS subscribed -- ON CONFLICT lifts role only');
+
+select is((select state from pg_temp.latest('f1000000-0000-4000-8000-000000000005')),
+  'subscribed',
+  'REDEEM: the event records the ACTUAL resulting state, not the token preset');
+select is((select kind from pg_temp.latest('f1000000-0000-4000-8000-000000000005')),
+  'consent_link_redeem',
+  'REDEEM: ...with the frozen consent_link_redeem kind');
+
+-- ===========================================================================
+-- 5d. Self-TOGGLE vs self-JOIN, and the two gaps a structural check cannot close
+-- ===========================================================================
+-- The frozen mapping distinguishes a toggle between two ACTIVE states from a fresh join.
+-- Deriving from (provenance, state) alone cannot tell them apart -- both are target-authored
+-- and both land active -- so the sink names the kind from the PRIOR state.
+select pg_temp.claims('f0000000-0000-0000-0000-000000000002');
+select lives_ok($$ select agent_board._upsert_board_membership_state(
+  'f2000000-0000-4000-8000-000000000001','f1000000-0000-4000-8000-000000000002','joined') $$,
+  'toggle setup: the subject joins');
+select is((select kind from pg_temp.latest('f1000000-0000-4000-8000-000000000002')),
+  'consent_self_join', 'TOGGLE: a fresh join is consent_self_join');
+
+select lives_ok($$ select agent_board._upsert_board_membership_state(
+  'f2000000-0000-4000-8000-000000000001','f1000000-0000-4000-8000-000000000002','subscribed') $$,
+  'toggle setup: the subject switches to subscribed');
+select is((select kind from pg_temp.latest('f1000000-0000-4000-8000-000000000002')),
+  'consent_self_toggle',
+  'TOGGLE: joined -> subscribed is a TOGGLE, not a second join');
+
+-- The two boundaries of the toggle rule, both verified live before being pinned:
+--   * NO prior row -> v_prior_state is NULL, `null in (...)` is NULL, so the CASE falls through
+--     to the generic derivation. A first-ever join straight to `subscribed` is a JOIN.
+--   * a prior row that is NOT active (left/removed) -> re-entry is a fresh act of consent, not
+--     a toggle. Someone returning after leaving is consenting again, and the ledger must say so.
+select pg_temp.claims('f0000000-0000-0000-0000-000000000006');
+select lives_ok($$ select agent_board._upsert_board_membership_state(
+  'f2000000-0000-4000-8000-000000000001','f1000000-0000-4000-8000-000000000006','subscribed') $$,
+  'toggle boundary setup: a first-ever membership, straight to subscribed');
+select is((select kind from pg_temp.latest('f1000000-0000-4000-8000-000000000006')),
+  'consent_self_join',
+  'TOGGLE boundary: with NO prior row it is a JOIN, not a toggle');
+
+select lives_ok($$ select agent_board._upsert_board_membership_state(
+  'f2000000-0000-4000-8000-000000000001','f1000000-0000-4000-8000-000000000006','left') $$,
+  'toggle boundary setup: they leave');
+select lives_ok($$ select agent_board._upsert_board_membership_state(
+  'f2000000-0000-4000-8000-000000000001','f1000000-0000-4000-8000-000000000006','joined') $$,
+  'toggle boundary setup: they come back');
+select is((select kind from pg_temp.latest('f1000000-0000-4000-8000-000000000006')),
+  'consent_self_join',
+  'TOGGLE boundary: re-entry from LEFT is a fresh JOIN -- returning is consenting again');
+
+-- A third party moving an ACTIVE member between active states is NOT a self-toggle.
+select pg_temp.claims('f0000000-0000-0000-0000-000000000001');
+select lives_ok($$ select agent_board._upsert_board_membership_state(
+  'f2000000-0000-4000-8000-000000000001','f1000000-0000-4000-8000-000000000002','joined') $$,
+  'toggle setup: a third party moves them back');
+select is((select kind from pg_temp.latest('f1000000-0000-4000-8000-000000000002')),
+  'resolution',
+  'TOGGLE: a third party is board-authored resolution, never a self-toggle');
+
+-- FEDSESSION, behaviourally. A textual call-site count cannot tell whether the emit sits
+-- inside `if found` -- moving it out would emit on idempotent no-insert calls, and hiding it
+-- behind `if false` would emit none. Both keep exactly one textual call.
+-- A DEDICATED board so the counts below are isolated. Agent 4 already carries operator events
+-- on board 1 from the operator section, and counting across both made the baseline wrong --
+-- the assertion failed on my own fixture, not on the code.
+insert into agent_board.boards(id, slug, name, created_by_agent_id, visibility, status)
+values ('f2000000-0000-4000-8000-00000000000f','emit-fed','Emit Fed',
+        'f1000000-0000-4000-8000-000000000001','private','active');
+
+insert into agent_board.identity_providers(id, issuer, audience, default_board_id)
+values ('emit-prov','https://p.test','aud','f2000000-0000-4000-8000-00000000000f');
+
+select pg_temp.service();
+select lives_ok($$
+  select agent_board._fedsession_autojoin_default_board(
+    (select p from agent_board.identity_providers p where p.id = 'emit-prov'),
+    'f1000000-0000-4000-8000-000000000004')
+$$, 'fedsession setup: first auto-join');
+
+select is(
+  (select count(*)::int from agent_board.board_membership_events
+    where agent_id = 'f1000000-0000-4000-8000-000000000004'
+      and board_id = 'f2000000-0000-4000-8000-00000000000f'),
+  1,
+  'FEDSESSION: the first auto-join emits exactly one event');
+
+-- ...and that one event records the ACTUAL inserted state and its frozen kind, not merely SOME
+-- event. Counting alone is mutation-blind: changing the emitted `joined` literal, or the
+-- explicit `operator_designation` kind the writer passes, keeps the count at one. The fedsession
+-- insert has NO on-conflict-do-update path -- it inserts exactly this state or nothing -- so the
+-- emitted literal must equal the row, and a state literal here (unlike the upserting writers) is
+-- correct precisely because there is no divergent existing state to preserve.
+select is(
+  (select result_state from agent_board.board_membership_events
+    where agent_id = 'f1000000-0000-4000-8000-000000000004'
+      and board_id = 'f2000000-0000-4000-8000-00000000000f'
+    order by seq desc limit 1),
+  'joined',
+  'FEDSESSION: the auto-join event records the frozen joined literal, not merely some state');
+
+select is(
+  (select result_state from agent_board.board_membership_events
+    where agent_id = 'f1000000-0000-4000-8000-000000000004'
+      and board_id = 'f2000000-0000-4000-8000-00000000000f'
+    order by seq desc limit 1),
+  (select membership_state from agent_board.board_memberships
+    where agent_id = 'f1000000-0000-4000-8000-000000000004'
+      and board_id = 'f2000000-0000-4000-8000-00000000000f'),
+  'FEDSESSION: literal == actual -- the emitted state matches the row the no-conflict insert placed');
+
+select is(
+  (select event_kind from agent_board.board_membership_events
+    where agent_id = 'f1000000-0000-4000-8000-000000000004'
+      and board_id = 'f2000000-0000-4000-8000-00000000000f'
+    order by seq desc limit 1),
+  'operator_designation',
+  'FEDSESSION: ...with the frozen operator_designation kind the writer passes explicitly');
+
+-- ...and a SECOND call is a no-op (the NOT EXISTS suppresses the insert) so it must emit NOTHING.
+select lives_ok($$
+  select agent_board._fedsession_autojoin_default_board(
+    (select p from agent_board.identity_providers p where p.id = 'emit-prov'),
+    'f1000000-0000-4000-8000-000000000004')
+$$, 'fedsession setup: idempotent second call');
+
+select is(
+  (select count(*)::int from agent_board.board_membership_events
+    where agent_id = 'f1000000-0000-4000-8000-000000000004'
+      and board_id = 'f2000000-0000-4000-8000-00000000000f'),
+  1,
+  'FEDSESSION: a no-op second call emits NOTHING -- still exactly one event');
+
+-- ===========================================================================
+-- 5e. The FULL reachable (provenance, state) -> kind matrix
+-- ===========================================================================
+-- Sampling three combinations left the mapping mutation-blind: changing any UNASSERTED cell
+-- passed the suite. Asserted here as a single set comparison, so an added or altered cell
+-- fails and NAMES itself rather than silently diverging from the frozen record.
+--
+-- Driven through the emitter directly. Reaching every cell through the RPCs would need a
+-- fixture per cell and still miss the operator+pending rows, which no route produces.
+select pg_temp.service();
+
+create function pg_temp.kind_of(p_state text) returns text language plpgsql as $$
+declare v text;
+begin
+  perform agent_board._emit_membership_event(
+    'f2000000-0000-4000-8000-000000000001'::uuid,
+    'f1000000-0000-4000-8000-000000000006'::uuid, p_state);
+  select event_kind into v from agent_board.board_membership_events
+   where agent_id = 'f1000000-0000-4000-8000-000000000006' order by seq desc limit 1;
+  return v;
+end $$;
+
+select is(
+  (select string_agg(s || '=' || pg_temp.kind_of(s), ' ' order by s)
+     from unnest(array['joined','subscribed','invited','requested','left','removed']) s),
+  'invited=invite_offer joined=operator_designation left=operator_removal '
+  || 'removed=operator_removal requested=request_manufactured subscribed=operator_designation',
+  'MATRIX: the operator row maps exactly -- pending states are NEUTRAL, not operator_repair');
+
+-- The TARGET-AUTHORED row. Asserting only the operator row left every self-authored cell
+-- mutation-blind -- and those are the cells that decide whether someone consented.
+select pg_temp.claims('f0000000-0000-0000-0000-000000000006');
+select is(
+  (select string_agg(s || '=' || pg_temp.kind_of(s), ' ' order by s)
+     from unnest(array['joined','subscribed','invited','requested','left','removed']) s),
+  'invited=consent_self_invite joined=consent_self_join left=self_withdraw '
+  || 'removed=self_withdraw requested=consent_join_request subscribed=consent_self_join',
+  'MATRIX: the target-authored row maps exactly');
+
+-- The BOARD-AUTHORED row. Reachable through update_board_membership's other-agent path, and
+-- previously unasserted -- changing board-authored `requested` to invite_offer would have passed.
+select pg_temp.claims('f0000000-0000-0000-0000-000000000001');
+select is(
+  (select string_agg(s || '=' || pg_temp.kind_of(s), ' ' order by s)
+     from unnest(array['joined','subscribed','invited','requested','left','removed']) s),
+  'invited=invite_offer joined=resolution left=eviction '
+  || 'removed=eviction requested=request_manufactured subscribed=resolution',
+  'MATRIX: the board-authored row maps exactly');
+select pg_temp.service();
+
+-- An unmapped combination must RAISE rather than land unlabelled in an append-only ledger.
+select throws_ok($$
+  select agent_board._emit_membership_event(
+    'f2000000-0000-4000-8000-000000000001'::uuid,
+    'f1000000-0000-4000-8000-000000000006'::uuid, 'not-a-state')
+$$, '22023', null,
+   'MATRIX: an unmapped (provenance, state) raises rather than silently mislabelling');
+
+-- A no-change active write is NOT a toggle. join_board and update_board_membership both
+-- permit joined->joined, so this is reachable, and it was recorded as a toggle.
+select pg_temp.claims('f0000000-0000-0000-0000-000000000006');
+select lives_ok($$ select agent_board._upsert_board_membership_state(
+  'f2000000-0000-4000-8000-000000000001','f1000000-0000-4000-8000-000000000006','joined') $$,
+  'no-change setup: the subject writes joined while already joined');
+select is((select kind from pg_temp.latest('f1000000-0000-4000-8000-000000000006')),
+  'consent_self_join',
+  'MATRIX: a no-change active write is a JOIN, not a toggle of nothing');
+
+-- ===========================================================================
+-- 6. SCOPE: this migration emits but does not GATE
+-- ===========================================================================
+-- SCOPE BOUNDARY, updated when gating landed. This assertion previously read "no route
+-- consults the predicate yet" and FAILED the moment MBCONSENT-B(ii) shipped -- which is what a
+-- scope guard is for. It now names the expected consumer SET, so a route that starts consulting
+-- the predicate without being added here fails and names itself.
+--
+-- resolve_board_request is the sole predicate READER. join_board and update_board_membership
+-- gate STRUCTURALLY (the actor must be the subject; no other-agent promotion), which needs no
+-- ledger read -- a structural refusal is stronger than a predicate check, because it cannot be
+-- satisfied by manufacturing evidence.
+select is(
+  (select coalesce(string_agg(p.proname, ', ' order by p.proname), '')
+     from pg_proc p join pg_namespace n on n.oid = p.pronamespace
+    where n.nspname = 'agent_board' and p.prokind = 'f'
+      and p.prolang <> (select oid from pg_language where lanname = 'internal')
+      and has_function_privilege('authenticated', p.oid, 'EXECUTE')
+      and pg_get_functiondef(p.oid) ~ '_membership_consent_present'),
+  'resolve_board_request, update_board_membership',
+  'scope: exactly TWO authenticated routes read the predicate');
+
+-- ...and the ledger it fills is the one MBCONSENT-A froze.
+-- The refused write must leave NO trace. Asserted against the SUBJECT of the refused attempt
+-- rather than a global row count: a hardcoded total breaks every time a test is added, which
+-- makes it noise rather than a signal, and it was already wrong once here.
+select is(
+  (select count(*)::int from agent_board.board_membership_events
+    where agent_id = 'f1000000-0000-4000-8000-000000000002'
+      and result_state = 'left'
+      and provenance = 'operator-designated'),
+  0,
+  'scope: the refused unattributable write left NO ledger row, invented or otherwise');
+
+-- ...and every event that DID land carries a real kind and provenance.
+select is(
+  (select count(*)::int from agent_board.board_membership_events
+    where event_kind is null or provenance is null),
+  0,
+  'scope: no event landed with a null kind or provenance');
+
+select finish();
+rollback;