@consiliency/agent-board-schema 1.12.0 → 1.23.0

package/tests/agent_board_consent_substrate.test.sql

@@ -0,0 +1,720 @@
+-- MBCONSENT-A pgTAP: the consent SUBSTRATE only (interface freeze IF-0-MBCONSENT-1).
+--
+-- Scope is deliberately narrow. This suite asserts the ledger, the anti-forge rules, the
+-- privilege posture, the two predicates, and the backfill. It drives NO membership route,
+-- because this migration changes none -- emission and the force-join closure are MBCONSENT-B.
+--
+-- Methodology notes that are load-bearing:
+--   * The CHECK constraint is verified with the BEFORE INSERT trigger DISABLED. With the
+--     trigger enabled the constraint cannot be reached, so a null-permissive CHECK would pass
+--     a naive test -- which is exactly the state a review found in an earlier draft.
+--   * Privilege assertions use has_table_privilege / has_function_privilege, which resolve
+--     ROLE MEMBERSHIP. A query filtering information_schema on grantee = 'authenticated' sees
+--     only DIRECT grants and reads clean when a privilege is held through another role.
+--   * Event ordering is asserted through seq, never created_at: now() is
+--     transaction_timestamp() and is constant within a transaction.
+create extension if not exists pgtap with schema extensions;
+set search_path = extensions, public, agent_board;
+
+begin;
+
+select plan(91);
+
+-- ---------------------------------------------------------------------------
+-- Fixtures. Agents 1..6; board 1 owned by agent 1.
+-- ---------------------------------------------------------------------------
+insert into agent_board.agents(id, agent_type, kind, handle, display_name, status)
+select ('c0000000-0000-4000-8000-' || lpad(n::text, 12, '0'))::uuid,
+       'agent', 'agent', 'substrate-agent-' || n, 'Substrate Agent ' || n, 'active'
+from generate_series(1, 7) n;
+
+insert into agent_board.boards(id, slug, name, created_by_agent_id, visibility, status)
+values ('cb000000-0000-4000-8000-000000000001', 'substrate-b1', 'Substrate B1',
+        'c0000000-0000-4000-8000-000000000001', 'private', 'active');
+
+-- ===========================================================================
+-- 1. Table shape
+-- ===========================================================================
+select has_table('agent_board', 'board_membership_events', 'substrate: ledger table exists');
+select has_column('agent_board', 'board_membership_events', 'seq', 'substrate: seq exists');
+select col_is_pk('agent_board', 'board_membership_events', 'seq',
+  'substrate: seq is the PRIMARY KEY -- the total order, not created_at');
+
+select is(
+  (select a.attidentity from pg_attribute a
+    where a.attrelid = 'agent_board.board_membership_events'::regclass and a.attname = 'seq'),
+  'a'::"char",
+  'substrate: seq is GENERATED ALWAYS AS IDENTITY (callers cannot supply it)');
+
+select is(
+  (select count(*)::int from pg_constraint c
+    where c.conrelid = 'agent_board.board_membership_events'::regclass
+      and c.contype = 'f' and c.confdeltype = 'c'),
+  2,
+  'substrate: board_id and agent_id both cascade on delete');
+
+-- ===========================================================================
+-- 2. Anti-forge: CHECK constraint IN ISOLATION, then the trigger
+-- ===========================================================================
+-- The trigger masks the constraint, so it is disabled here on purpose. Without this the
+-- next four assertions would pass against a CHECK that accepts a NULL actor.
+alter table agent_board.board_membership_events
+  disable trigger trg_board_membership_events_provenance_guard;
+
+select throws_ok($$
+  insert into agent_board.board_membership_events(board_id, agent_id, event_kind, result_state, provenance, actor_agent_id)
+  values ('cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000002',
+          'consent_self_join', 'joined', 'target-authored', null)
+$$, '23514', null,
+  'CHECK alone: target-authored with a NULL actor is refused');
+
+select throws_ok($$
+  insert into agent_board.board_membership_events(board_id, agent_id, event_kind, result_state, provenance, actor_agent_id)
+  values ('cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000002',
+          'consent_self_join', 'joined', 'target-authored', 'c0000000-0000-4000-8000-000000000003')
+$$, '23514', null,
+  'CHECK alone: target-authored by a THIRD PARTY is refused');
+
+select throws_ok($$
+  insert into agent_board.board_membership_events(board_id, agent_id, event_kind, result_state, provenance, actor_agent_id)
+  values ('cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000002',
+          'operator_designation', 'joined', 'operator-designated', 'c0000000-0000-4000-8000-000000000003')
+$$, '23514', null,
+  'CHECK alone: operator-designated with a NON-NULL actor is refused');
+
+select throws_ok($$
+  insert into agent_board.board_membership_events(board_id, agent_id, event_kind, result_state, provenance, actor_agent_id)
+  values ('cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000002',
+          'invite_offer', 'invited', 'board-authored', 'c0000000-0000-4000-8000-000000000002')
+$$, '23514', null,
+  'CHECK alone: board-authored by the SUBJECT is refused');
+
+alter table agent_board.board_membership_events
+  enable trigger trg_board_membership_events_provenance_guard;
+
+-- Now the MIRROR IMAGE: isolate the TRIGGER by dropping the CHECK. Asserting a bare 23514
+-- with the constraint in place would be vacuous -- the CHECK rejects these same rows, so a
+-- trigger whose body was replaced with `return new` would still pass. Each assertion below
+-- pins the trigger's OWN message, which only the trigger can produce.
+-- Capture the SHIPPED definition before dropping it, so the restore below cannot drift from
+-- the migration. Hand-copying the constraint here would mean a later change to the migration
+-- leaves this suite asserting a stale definition -- the test would still pass, against the
+-- wrong constraint.
+create temporary table _saved_provenance_check on commit drop as
+select pg_get_constraintdef(oid) as def
+  from pg_constraint where conname = 'board_membership_events_provenance_actor';
+
+select is((select count(*)::int from _saved_provenance_check), 1,
+  'guard: the shipped provenance CHECK was captured before dropping it');
+
+alter table agent_board.board_membership_events
+  drop constraint board_membership_events_provenance_actor;
+
+select throws_ok($$
+  insert into agent_board.board_membership_events(board_id, agent_id, event_kind, result_state, provenance, actor_agent_id)
+  values ('cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000002',
+          'consent_self_join', 'joined', 'target-authored', null)
+$$, 'substrate CHECK refuses target-authored actor <> subject',
+  'TRIGGER alone (CHECK dropped) refuses target-authored with a NULL actor');
+
+select throws_ok($$
+  insert into agent_board.board_membership_events(board_id, agent_id, event_kind, result_state, provenance, actor_agent_id)
+  values ('cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000002',
+          'consent_self_join', 'joined', 'target-authored', 'c0000000-0000-4000-8000-000000000003')
+$$, 'substrate CHECK refuses target-authored actor <> subject',
+  'TRIGGER alone refuses a third-party target-authored forge');
+
+select throws_ok($$
+  insert into agent_board.board_membership_events(board_id, agent_id, event_kind, result_state, provenance, actor_agent_id)
+  values ('cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000002',
+          'operator_designation', 'joined', 'operator-designated', 'c0000000-0000-4000-8000-000000000003')
+$$, 'substrate CHECK refuses operator-designated non-null actor',
+  'TRIGGER alone refuses operator-designated with a non-null actor');
+
+select throws_ok($$
+  insert into agent_board.board_membership_events(board_id, agent_id, event_kind, result_state, provenance, actor_agent_id)
+  values ('cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000002',
+          'invite_offer', 'invited', 'board-authored', 'c0000000-0000-4000-8000-000000000002')
+$$, 'substrate CHECK refuses board-authored actor = subject',
+  'TRIGGER alone refuses board-authored by the subject');
+
+-- Restore the captured definition verbatim rather than a hand-written copy.
+do $restore$
+declare
+  v_def text;
+begin
+  select def into strict v_def from _saved_provenance_check;
+  execute format(
+    'alter table agent_board.board_membership_events add constraint %I %s',
+    'board_membership_events_provenance_actor', v_def);
+end
+$restore$;
+
+select is(
+  (select pg_get_constraintdef(oid) from pg_constraint
+    where conname = 'board_membership_events_provenance_actor'),
+  (select def from _saved_provenance_check),
+  'guard: the restored CHECK is identical to the shipped one');
+
+-- ...and with BOTH restored, the row is still refused (defense in depth intact).
+select throws_ok($$
+  insert into agent_board.board_membership_events(board_id, agent_id, event_kind, result_state, provenance, actor_agent_id)
+  values ('cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000002',
+          'consent_self_join', 'joined', 'target-authored', null)
+$$, 'substrate CHECK refuses target-authored actor <> subject',
+  'CHECK + trigger together still refuse the null-actor forge');
+
+-- The three LEGAL shapes must all be writable.
+select lives_ok($$
+  insert into agent_board.board_membership_events(board_id, agent_id, event_kind, result_state, provenance, actor_agent_id)
+  values ('cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000002',
+          'consent_self_join', 'joined', 'target-authored', 'c0000000-0000-4000-8000-000000000002')
+$$, 'legal: target-authored by the subject');
+
+select lives_ok($$
+  insert into agent_board.board_membership_events(board_id, agent_id, event_kind, result_state, provenance, actor_agent_id)
+  values ('cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000003',
+          'operator_designation', 'joined', 'operator-designated', null)
+$$, 'legal: operator-designated with a null actor');
+
+select lives_ok($$
+  insert into agent_board.board_membership_events(board_id, agent_id, event_kind, result_state, provenance, actor_agent_id)
+  values ('cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000004',
+          'invite_offer', 'invited', 'board-authored', 'c0000000-0000-4000-8000-000000000001')
+$$, 'legal: board-authored by a third party');
+
+-- ===========================================================================
+-- 3. Privilege posture
+-- ===========================================================================
+select ok(
+  (select relrowsecurity from pg_class
+    where oid = 'agent_board.board_membership_events'::regclass),
+  'substrate: RLS is enabled');
+
+select is(has_table_privilege('authenticated', 'agent_board.board_membership_events', 'SELECT'),
+  true, 'substrate: authenticated may SELECT (RLS narrows it to own rows)');
+
+select is(has_table_privilege('authenticated', 'agent_board.board_membership_events', 'INSERT'),
+  false, 'substrate: authenticated holds no INSERT by ANY route (incl. role membership)');
+select is(has_table_privilege('authenticated', 'agent_board.board_membership_events', 'UPDATE'),
+  false, 'substrate: authenticated holds no UPDATE by any route');
+select is(has_table_privilege('authenticated', 'agent_board.board_membership_events', 'DELETE'),
+  false, 'substrate: authenticated holds no DELETE by any route');
+
+-- The frozen contract forbids an authenticated write POLICY, not merely the privilege. With RLS
+-- on and no permissive policy, the default is DENY; a permissive policy backed by a raising
+-- function would satisfy every privilege assertion above while violating the substrate shape.
+select is(
+  (select count(*)::int from pg_policy
+    where polrelid = 'agent_board.board_membership_events'::regclass
+      and polcmd in ('a', 'w', 'd')
+      and 'authenticated' = any (select rolname from pg_roles where oid = any (polroles))),
+  0,
+  'substrate: NO authenticated INSERT/UPDATE/DELETE policy exists at all');
+select is(has_table_privilege('anon', 'agent_board.board_membership_events', 'SELECT'),
+  false, 'substrate: anon cannot read the ledger at all');
+
+select is(has_function_privilege('authenticated', 'agent_board._membership_consent_present(uuid,uuid)', 'EXECUTE'),
+  false, 'substrate: authenticated cannot read an arbitrary subject consent state');
+select is(has_function_privilege('authenticated', 'agent_board._membership_consent_kind(uuid,uuid)', 'EXECUTE'),
+  false, 'substrate: authenticated cannot read an arbitrary subject consent provenance');
+
+-- The SELECT policy must be subject-scoped, not permissive-true.
+-- The schema qualifier is OPTIONAL in the rendering: pg_get_expr omits it when the schema is
+-- on search_path, which this suite puts there. Pinning one spelling would fail against a
+-- CORRECT policy -- a rendering artifact, not a policy defect.
+select matches(
+  (select pg_get_expr(polqual, polrelid) from pg_policy
+    where polrelid = 'agent_board.board_membership_events'::regclass
+      and polname = 'agent_board_authenticated_select_board_membership_events'),
+  '^\(agent_id = (agent_board\.)?current_agent_id\(\)\)$',
+  'substrate: the authenticated SELECT policy is subject-scoped');
+
+-- Direct-table RLS probe -- the one case that requires SET LOCAL ROLE.
+set local role authenticated;
+select throws_ok($$
+  insert into agent_board.board_membership_events(board_id, agent_id, event_kind, result_state, provenance, actor_agent_id)
+  values ('cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000005',
+          'consent_self_join', 'joined', 'target-authored', 'c0000000-0000-4000-8000-000000000005')
+$$, '42501', 'permission denied for table board_membership_events',
+  'substrate: authenticated direct INSERT is refused by PRIVILEGE, before RLS');
+reset role;
+
+-- ===========================================================================
+-- 4. Predicate semantics -- _present and _kind must agree on every case
+-- ===========================================================================
+-- agent 2: target-authored joined (above)  -> consent
+select is(agent_board._membership_consent_present(
+  'cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000002'),
+  true, 'predicate: a target-authored placement is consent');
+select is(agent_board._membership_consent_kind(
+  'cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000002'),
+  'target', 'predicate: ...and _kind agrees');
+
+-- agent 3: operator-designated JOINED -> consent (Assumption 6 operator carve-out)
+select is(agent_board._membership_consent_present(
+  'cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000003'),
+  true, 'predicate: an operator PLACEMENT is consent');
+select is(agent_board._membership_consent_kind(
+  'cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000003'),
+  'operator', 'predicate: ...and _kind agrees');
+
+-- agent 4: board-authored invited -> NEUTRAL
+select is(agent_board._membership_consent_present(
+  'cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000004'),
+  false, 'predicate: a board-authored offer is not consent');
+select is(agent_board._membership_consent_kind(
+  'cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000004'),
+  null, 'predicate: ...and _kind agrees');
+
+-- agent 5: a PENDING operator OFFER is not consent. This is the case an earlier draft got
+-- wrong: any operator-designated non-removal event counted, so an invitation the subject had
+-- never seen read as consent.
+insert into agent_board.board_membership_events(board_id, agent_id, event_kind, result_state, provenance, actor_agent_id)
+values ('cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000005',
+        'invite_offer', 'invited', 'operator-designated', null);
+select is(agent_board._membership_consent_present(
+  'cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000005'),
+  false, 'predicate: a PENDING operator invitation is NOT consent');
+select is(agent_board._membership_consent_kind(
+  'cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000005'),
+  null, 'predicate: ...and _kind agrees on the pending offer');
+
+-- The operator boundary is joined|subscribed EXACTLY. Testing only `invited` would leave an
+-- implementation that wrongly accepts `requested`, or wrongly rejects `subscribed`, green.
+insert into agent_board.board_membership_events(board_id, agent_id, event_kind, result_state, provenance, actor_agent_id)
+values ('cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000005',
+        'join_request', 'requested', 'operator-designated', null);
+select is(agent_board._membership_consent_present(
+  'cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000005'),
+  false, 'boundary: operator-designated REQUESTED is not consent');
+select is(agent_board._membership_consent_kind(
+  'cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000005'),
+  null, 'boundary: ...and _kind agrees');
+
+insert into agent_board.board_membership_events(board_id, agent_id, event_kind, result_state, provenance, actor_agent_id)
+values ('cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000005',
+        'operator_designation', 'subscribed', 'operator-designated', null);
+select is(agent_board._membership_consent_present(
+  'cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000005'),
+  true, 'boundary: operator-designated SUBSCRIBED IS consent');
+select is(agent_board._membership_consent_kind(
+  'cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000005'),
+  'operator', 'boundary: ...and _kind agrees');
+
+-- target-authored REQUESTED is a grant. Without this, an implementation restricting target
+-- consent to joined|subscribed stays green -- and that would break the join-request approval
+-- path, where the subject's own request IS the consenting act.
+insert into agent_board.board_membership_events(board_id, agent_id, event_kind, result_state, provenance, actor_agent_id)
+values ('cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000004',
+        'consent_join_request', 'requested', 'target-authored', 'c0000000-0000-4000-8000-000000000004');
+select is(agent_board._membership_consent_present(
+  'cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000004'),
+  true, 'predicate: a target-authored REQUEST is consent (the approval path)');
+select is(agent_board._membership_consent_kind(
+  'cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000004'),
+  'target', 'predicate: ...and _kind agrees');
+
+-- A board-authored NEUTRAL event after a valid grant must PRESERVE the grant. An
+-- implementation treating neutral events as revocations stays green without this.
+insert into agent_board.board_membership_events(board_id, agent_id, event_kind, result_state, provenance, actor_agent_id)
+values ('cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000004',
+        'invite_offer', 'invited', 'board-authored', 'c0000000-0000-4000-8000-000000000001');
+select is(agent_board._membership_consent_present(
+  'cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000004'),
+  true, 'predicate: a board-authored neutral event PRESERVES an existing grant');
+-- _kind must be asserted HERE, immediately after the neutral event. Checking only _present
+-- leaves a _kind that includes board-authored rows in its candidate set returning null while
+-- _present says true -- the twins disagreeing, with the suite green.
+select is(agent_board._membership_consent_kind(
+  'cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000004'),
+  'target', 'predicate: _kind also preserves the grant across a neutral event');
+
+-- A pending OPERATOR event must likewise preserve an existing grant, not just read neutral on
+-- an empty history.
+insert into agent_board.board_membership_events(board_id, agent_id, event_kind, result_state, provenance, actor_agent_id)
+values ('cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000004',
+        'invite_offer', 'invited', 'operator-designated', null);
+select is(agent_board._membership_consent_present(
+  'cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000004'),
+  true, 'predicate: a pending OPERATOR offer preserves an existing grant');
+select is(agent_board._membership_consent_kind(
+  'cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000004'),
+  'target', 'predicate: ...and _kind agrees');
+
+-- removal-first must cover REMOVED, not only LEFT.
+insert into agent_board.board_membership_events(board_id, agent_id, event_kind, result_state, provenance, actor_agent_id)
+values ('cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000004',
+        'operator_removal', 'removed', 'operator-designated', null);
+select is(agent_board._membership_consent_present(
+  'cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000004'),
+  false, 'predicate: REMOVED is removal-first, not just LEFT');
+select is(agent_board._membership_consent_kind(
+  'cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000004'),
+  null, 'predicate: ...and _kind agrees on removed');
+
+-- LEDGER-ONLY, the contract's central claim: consent is read from board_membership_events and
+-- NEVER from board_memberships.membership_state. Agent 6 has NO membership row, so an
+-- implementation that fell back to membership_state on an empty ledger would still read false
+-- and pass. Agent 3 below has an ACTIVE row and a ledger that does not grant -- that is the
+-- case which discriminates.
+insert into agent_board.board_memberships(board_id, agent_id, role, membership_state, created_by_agent_id)
+values ('cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000005',
+        'member', 'joined', 'c0000000-0000-4000-8000-000000000001');
+insert into agent_board.board_membership_events(board_id, agent_id, event_kind, result_state, provenance, actor_agent_id)
+values ('cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000005',
+        'self_withdraw', 'left', 'target-authored', 'c0000000-0000-4000-8000-000000000005');
+select is(agent_board._membership_consent_present(
+  'cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000005'),
+  false,
+  'LEDGER-ONLY: an ACTIVE membership row does not grant consent when the ledger says left');
+select is(agent_board._membership_consent_kind(
+  'cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000005'),
+  null, 'LEDGER-ONLY: ...and _kind agrees');
+
+-- board-authored is neutral at EVERY non-removal state, not only `invited`.
+insert into agent_board.board_membership_events(board_id, agent_id, event_kind, result_state, provenance, actor_agent_id)
+values ('cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000003',
+        'join_request', 'requested', 'board-authored', 'c0000000-0000-4000-8000-000000000001');
+select is(agent_board._membership_consent_present(
+  'cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000003'),
+  true, 'board-authored REQUESTED is neutral: it neither grants nor revokes');
+
+insert into agent_board.board_membership_events(board_id, agent_id, event_kind, result_state, provenance, actor_agent_id)
+values ('cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000003',
+        'resolution', 'joined', 'board-authored', 'c0000000-0000-4000-8000-000000000001');
+select is(agent_board._membership_consent_present(
+  'cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000003'),
+  true, 'board-authored JOINED is neutral -- an owner resolution is not the subject consenting');
+
+-- ...but a board-authored REMOVAL does revoke: removal-first applies to every provenance.
+insert into agent_board.board_membership_events(board_id, agent_id, event_kind, result_state, provenance, actor_agent_id)
+values ('cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000003',
+        'eviction', 'removed', 'board-authored', 'c0000000-0000-4000-8000-000000000001');
+select is(agent_board._membership_consent_present(
+  'cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000003'),
+  false, 'board-authored REMOVAL revokes: removal-first applies to every provenance');
+select is(agent_board._membership_consent_kind(
+  'cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000003'),
+  null, 'board-authored removal: ...and _kind agrees');
+
+-- THE discriminating case for LEDGER-ONLY. The other fixture (active row + a `left` event)
+-- catches an implementation where membership_state replaces or overrides the ledger -- but NOT
+-- the one actually prohibited: consult the ledger when it has events, fall back to
+-- membership_state when it is EMPTY. That implementation passes every other assertion in this
+-- file. Agent 7 exists solely for this and is never given an event.
+insert into agent_board.board_memberships(board_id, agent_id, role, membership_state, created_by_agent_id)
+values ('cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000007',
+        'member', 'joined', 'c0000000-0000-4000-8000-000000000001');
+
+select is(
+  (select count(*)::int from agent_board.board_memberships
+    where agent_id = 'c0000000-0000-4000-8000-000000000007'
+      and membership_state in ('joined','subscribed')),
+  1,
+  'LEDGER-ONLY setup: agent 7 holds an ACTIVE membership row');
+select is(
+  (select count(*)::int from agent_board.board_membership_events
+    where agent_id = 'c0000000-0000-4000-8000-000000000007'),
+  0,
+  'LEDGER-ONLY setup: ...and its ledger is EMPTY');
+
+select is(agent_board._membership_consent_present(
+  'cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000007'),
+  false,
+  'LEDGER-ONLY: an ACTIVE membership with an EMPTY ledger is NOT consent (no fallback)');
+select is(agent_board._membership_consent_kind(
+  'cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000007'),
+  null, 'LEDGER-ONLY: ...and _kind agrees');
+
+-- a silent ledger reads false, never "unknown"
+select is(agent_board._membership_consent_present(
+  'cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000006'),
+  false, 'predicate: a silent ledger is not consent');
+select is(agent_board._membership_consent_kind(
+  'cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000006'),
+  null, 'predicate: ...and _kind agrees on the silent ledger');
+
+-- REMOVAL-FIRST and seq ordering: decline after consent -> false; re-accept -> true.
+insert into agent_board.board_membership_events(board_id, agent_id, event_kind, result_state, provenance, actor_agent_id)
+values ('cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000002',
+        'consent_decline', 'left', 'target-authored', 'c0000000-0000-4000-8000-000000000002');
+select is(agent_board._membership_consent_present(
+  'cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000002'),
+  false, 'predicate: a later decline revokes consent (removal-first)');
+select is(agent_board._membership_consent_kind(
+  'cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000002'),
+  null, 'sequence: ...and _kind agrees after the decline');
+
+-- A board-authored RE-INVITE after the decline must NOT launder it back to consent.
+insert into agent_board.board_membership_events(board_id, agent_id, event_kind, result_state, provenance, actor_agent_id)
+values ('cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000002',
+        'invite_offer', 'invited', 'board-authored', 'c0000000-0000-4000-8000-000000000001');
+select is(agent_board._membership_consent_present(
+  'cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000002'),
+  false, 'predicate: a re-invite cannot launder a prior refusal (REJECTSEM substrate)');
+select is(agent_board._membership_consent_kind(
+  'cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000002'),
+  null, 'sequence: ...and _kind agrees after the re-invite');
+
+-- ...but the subject's own later act does restore it.
+insert into agent_board.board_membership_events(board_id, agent_id, event_kind, result_state, provenance, actor_agent_id)
+values ('cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000002',
+        'consent_self_join', 'joined', 'target-authored', 'c0000000-0000-4000-8000-000000000002');
+select is(agent_board._membership_consent_present(
+  'cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000002'),
+  true, 'predicate: the subject can consent again after declining');
+select is(agent_board._membership_consent_kind(
+  'cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000002'),
+  'target', 'sequence: ...and _kind agrees after re-consent (pins _kind ordering too)');
+
+-- All four events for agent 2 landed in a strict seq order despite identical created_at.
+select is(
+  (select count(distinct seq)::int from agent_board.board_membership_events
+    where agent_id = 'c0000000-0000-4000-8000-000000000002'),
+  4,
+  'ordering: every event has a distinct seq');
+select is(
+  (select count(distinct created_at)::int from agent_board.board_membership_events
+    where agent_id = 'c0000000-0000-4000-8000-000000000002'),
+  1,
+  'ordering: ...while created_at is IDENTICAL for all of them (transaction_timestamp)');
+
+-- ===========================================================================
+-- 5. Function contracts
+-- ===========================================================================
+-- provolatile is "char", so it must be cast before concatenation ("char" || text is
+-- ambiguous). Asserting the two properties separately is clearer than a packed string.
+select is(
+  (select p.provolatile::text from pg_proc p
+    join pg_namespace n on n.oid = p.pronamespace
+   where n.nspname = 'agent_board' and p.proname = '_membership_consent_present'),
+  's',
+  'contract: _membership_consent_present is STABLE');
+
+select is(
+  (select p.prosecdef from pg_proc p
+    join pg_namespace n on n.oid = p.pronamespace
+   where n.nspname = 'agent_board' and p.proname = '_membership_consent_present'),
+  true,
+  'contract: _membership_consent_present is SECURITY DEFINER');
+
+select is(
+  (select pg_get_function_identity_arguments(p.oid) from pg_proc p
+    join pg_namespace n on n.oid = p.pronamespace
+   where n.nspname = 'agent_board' and p.proname = '_membership_consent_present'),
+  'p_board_id uuid, p_agent_id uuid',
+  'contract: the frozen signature takes NO actor -- consent is a property of the subject');
+
+-- ===========================================================================
+-- 6. Backfill
+-- ===========================================================================
+-- Duplicate non-active rows for one (board, agent) are permitted -- the partial unique index
+-- constrains ACTIVE rows only -- and `not exists` sees the table as it stood BEFORE the
+-- statement, so without DISTINCT ON each duplicate emits its own event.
+insert into agent_board.board_memberships(board_id, agent_id, role, membership_state, created_by_agent_id)
+values ('cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000006', 'member', 'requested', 'c0000000-0000-4000-8000-000000000001'),
+       ('cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000006', 'member', 'invited',   'c0000000-0000-4000-8000-000000000001');
+
+insert into agent_board.board_membership_events(board_id, agent_id, event_kind, result_state, provenance, actor_agent_id)
+select distinct on (bm.board_id, bm.agent_id)
+       bm.board_id, bm.agent_id, 'backfill_neutral', bm.membership_state, 'board-authored', b.created_by_agent_id
+  from agent_board.board_memberships bm
+  join agent_board.boards b on b.id = bm.board_id
+ where bm.membership_state in ('requested', 'invited')
+   and b.created_by_agent_id is not null
+   and b.created_by_agent_id <> bm.agent_id
+   and not exists (select 1 from agent_board.board_membership_events e
+                    where e.board_id = bm.board_id and e.agent_id = bm.agent_id)
+ order by bm.board_id, bm.agent_id, bm.id;
+
+select is(
+  (select count(*)::int from agent_board.board_membership_events
+    where agent_id = 'c0000000-0000-4000-8000-000000000006' and event_kind = 'backfill_neutral'),
+  1,
+  'backfill: duplicate pending rows yield exactly ONE event, not one per row');
+
+select is(
+  (select provenance from agent_board.board_membership_events
+    where agent_id = 'c0000000-0000-4000-8000-000000000006' and event_kind = 'backfill_neutral'),
+  'board-authored',
+  'backfill: annotates as board-authored');
+
+select is(
+  agent_board._membership_consent_present(
+    'cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000006'),
+  false,
+  'backfill: a backfilled row does NOT read as consent');
+
+-- The owner-subject exclusion (b.created_by_agent_id <> bm.agent_id) is load-bearing, not a
+-- tidy-up: a board-authored event REQUIRES actor <> subject, so backfilling the CREATOR's own
+-- pending row would violate the anti-forge CHECK and abort the migration on deploy. The
+-- creator's row must be skipped entirely.
+insert into agent_board.board_memberships(board_id, agent_id, role, membership_state, created_by_agent_id)
+values ('cb000000-0000-4000-8000-000000000001', 'c0000000-0000-4000-8000-000000000001',
+        'owner', 'requested', 'c0000000-0000-4000-8000-000000000001');
+
+select lives_ok($$
+  insert into agent_board.board_membership_events(board_id, agent_id, event_kind, result_state, provenance, actor_agent_id)
+  select distinct on (bm.board_id, bm.agent_id)
+         bm.board_id, bm.agent_id, 'backfill_neutral', bm.membership_state, 'board-authored', b.created_by_agent_id
+    from agent_board.board_memberships bm
+    join agent_board.boards b on b.id = bm.board_id
+   where bm.membership_state in ('requested', 'invited')
+     and b.created_by_agent_id is not null
+     and b.created_by_agent_id <> bm.agent_id
+     and not exists (select 1 from agent_board.board_membership_events e
+                      where e.board_id = bm.board_id and e.agent_id = bm.agent_id)
+   order by bm.board_id, bm.agent_id, bm.id
+$$, 'backfill: survives a board CREATOR holding a pending row on their own board');
+
+select is(
+  (select count(*)::int from agent_board.board_membership_events
+    where agent_id = 'c0000000-0000-4000-8000-000000000001' and event_kind = 'backfill_neutral'),
+  0,
+  'backfill: the creator''s own pending row is SKIPPED (board-authored needs actor <> subject)');
+
+-- IDEMPOTENCY asserted AFTER a second application, not before it. Checking the count before the
+-- rerun proves nothing; a miscorrelated guard keeps every lexical assertion green and still
+-- inserts a duplicate.
+insert into agent_board.board_membership_events(
+  board_id, agent_id, event_kind, result_state, provenance, actor_agent_id)
+select distinct on (bm.board_id, bm.agent_id)
+       bm.board_id, bm.agent_id, 'backfill_neutral', bm.membership_state,
+       'board-authored', b.created_by_agent_id
+  from agent_board.board_memberships bm
+  join agent_board.boards b on b.id = bm.board_id
+ where bm.membership_state in ('requested', 'invited')
+   and b.created_by_agent_id is not null
+   and b.created_by_agent_id <> bm.agent_id
+   and not exists (select 1 from agent_board.board_membership_events e
+                    where e.board_id = bm.board_id and e.agent_id = bm.agent_id)
+ order by bm.board_id, bm.agent_id, bm.id;
+
+select is(
+  (select count(*)::int from agent_board.board_membership_events
+    where agent_id = 'c0000000-0000-4000-8000-000000000006' and event_kind = 'backfill_neutral'),
+  1,
+  'backfill: IDEMPOTENT -- a second application adds nothing');
+
+-- ===========================================================================
+-- ===========================================================================
+-- 6b. Join-request EXPIRY
+-- ===========================================================================
+-- A join request IS the subject's consenting act, but it goes stale: an owner approving a
+-- six-month-old request re-adds someone who has moved on. Per-board TTL, 30 days by default.
+-- An expired request is NEUTRAL, never a refusal -- so a genuine grant BENEATH it survives.
+-- created_at is written explicitly here; it is the one column age depends on.
+
+select is(
+  (select join_request_ttl_days from agent_board.boards
+    where id = 'cb000000-0000-4000-8000-000000000001'),
+  30,
+  'expiry: the default request TTL is 30 days');
+
+-- agent 1 of a second board: a FRESH request still counts.
+insert into agent_board.boards(id, slug, name, created_by_agent_id, visibility, status)
+values ('cb000000-0000-4000-8000-000000000002', 'substrate-b2', 'Substrate B2',
+        'c0000000-0000-4000-8000-000000000001', 'private', 'active');
+
+insert into agent_board.board_membership_events(
+  board_id, agent_id, event_kind, result_state, provenance, actor_agent_id, created_at)
+values ('cb000000-0000-4000-8000-000000000002', 'c0000000-0000-4000-8000-000000000002',
+        'consent_join_request', 'requested', 'target-authored',
+        'c0000000-0000-4000-8000-000000000002', now() - interval '29 days');
+select is(agent_board._membership_consent_present(
+  'cb000000-0000-4000-8000-000000000002', 'c0000000-0000-4000-8000-000000000002'),
+  true, 'expiry: a request 29 days old still counts as consent');
+select is(agent_board._membership_consent_kind(
+  'cb000000-0000-4000-8000-000000000002', 'c0000000-0000-4000-8000-000000000002'),
+  'target', 'expiry: ...and _kind agrees');
+
+-- ...and one past the TTL does not.
+insert into agent_board.board_membership_events(
+  board_id, agent_id, event_kind, result_state, provenance, actor_agent_id, created_at)
+values ('cb000000-0000-4000-8000-000000000002', 'c0000000-0000-4000-8000-000000000003',
+        'consent_join_request', 'requested', 'target-authored',
+        'c0000000-0000-4000-8000-000000000003', now() - interval '31 days');
+select is(agent_board._membership_consent_present(
+  'cb000000-0000-4000-8000-000000000002', 'c0000000-0000-4000-8000-000000000003'),
+  false, 'expiry: a request 31 days old is NO LONGER consent');
+select is(agent_board._membership_consent_kind(
+  'cb000000-0000-4000-8000-000000000002', 'c0000000-0000-4000-8000-000000000003'),
+  null, 'expiry: ...and _kind agrees');
+
+-- NEUTRAL, not a refusal: a genuine self-join BENEATH an expired request survives.
+insert into agent_board.board_membership_events(
+  board_id, agent_id, event_kind, result_state, provenance, actor_agent_id, created_at)
+values ('cb000000-0000-4000-8000-000000000002', 'c0000000-0000-4000-8000-000000000004',
+        'consent_self_join', 'joined', 'target-authored',
+        'c0000000-0000-4000-8000-000000000004', now() - interval '90 days'),
+       ('cb000000-0000-4000-8000-000000000002', 'c0000000-0000-4000-8000-000000000004',
+        'consent_join_request', 'requested', 'target-authored',
+        'c0000000-0000-4000-8000-000000000004', now() - interval '60 days');
+select is(agent_board._membership_consent_present(
+  'cb000000-0000-4000-8000-000000000002', 'c0000000-0000-4000-8000-000000000004'),
+  true,
+  'expiry: an expired request is NEUTRAL -- an earlier genuine join beneath it survives');
+-- _kind MUST be asserted here too. `null` is what BOTH a neutral and a removal-like
+-- implementation return for a bare expired request, so the standalone case cannot tell them
+-- apart -- only the overlay can. A _kind that kept the expired request as the latest candidate
+-- would return null here while _present returns true: the twins disagreeing, suite green. That
+-- exact divergence already shipped once in an earlier draft.
+select is(agent_board._membership_consent_kind(
+  'cb000000-0000-4000-8000-000000000002', 'c0000000-0000-4000-8000-000000000004'),
+  'target',
+  'expiry: _kind agrees -- it reports the surviving grant, not the expired request');
+
+-- ...whereas a real REMOVAL beneath nothing still revokes, so expiry has not become a blanket skip.
+insert into agent_board.board_membership_events(
+  board_id, agent_id, event_kind, result_state, provenance, actor_agent_id, created_at)
+values ('cb000000-0000-4000-8000-000000000002', 'c0000000-0000-4000-8000-000000000005',
+        'consent_join_request', 'requested', 'target-authored',
+        'c0000000-0000-4000-8000-000000000005', now() - interval '90 days'),
+       ('cb000000-0000-4000-8000-000000000002', 'c0000000-0000-4000-8000-000000000005',
+        'self_withdraw', 'left', 'target-authored',
+        'c0000000-0000-4000-8000-000000000005', now() - interval '80 days');
+select is(agent_board._membership_consent_present(
+  'cb000000-0000-4000-8000-000000000002', 'c0000000-0000-4000-8000-000000000005'),
+  false, 'expiry: a removal is still a removal -- expiry is not a blanket skip');
+
+-- The TTL is PER BOARD: widening it revives the same 31-day-old request.
+update agent_board.boards set join_request_ttl_days = 365
+ where id = 'cb000000-0000-4000-8000-000000000002';
+select is(agent_board._membership_consent_present(
+  'cb000000-0000-4000-8000-000000000002', 'c0000000-0000-4000-8000-000000000003'),
+  true, 'expiry: the TTL is per-board -- widening it to 365 days revives that request');
+update agent_board.boards set join_request_ttl_days = 30
+ where id = 'cb000000-0000-4000-8000-000000000002';
+
+-- A non-positive TTL is refused.
+select throws_ok($$
+  update agent_board.boards set join_request_ttl_days = 0
+   where id = 'cb000000-0000-4000-8000-000000000002'
+$$, '23514', null, 'expiry: a non-positive TTL is refused by the constraint');
+
+-- 7. This migration changes no route
+-- ===========================================================================
+-- SCOPE BOUNDARY, updated when gating landed. This previously read "no membership 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, 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.proname in ('join_board','resolve_board_request','update_board_membership','_upsert_board_membership_state')
+      and pg_get_functiondef(p.oid) ~ '_membership_consent_present'),
+  'resolve_board_request, update_board_membership',
+  'scope: exactly TWO membership routes read the predicate');
+
+select is((select version from agent_board.schema_version), 8,
+  'schema_version stays 8 -- this migration is additive');
+
+select finish();
+rollback;