@consiliency/agent-board-schema 1.12.0 → 1.22.0

package/tests/agent_board_claimgate_predicate.test.sql

@@ -0,0 +1,360 @@
+-- CLAIMGATE Phase 2 — SHADOW (#133): _can_claim_resource authority predicate + shadow stamping.
+--
+-- Fleet-graph authority ONLY (NEGATIVE RULE: no board-admin fallback). Fixtures are built as
+-- the postgres superuser (RLS bypassed), then each authority probe runs `set local role
+-- authenticated` with request.jwt.claim.sub selecting the actor — the same harness as
+-- agent_board_fleet_machines_rls.test.sql. `_can_claim_resource` returns a boolean and never
+-- raises, so authority probes use is((select …), true/false) directly; the acquire-side
+-- (shadow-stamp / TTL / quota) uses lives_ok/throws_ok + a separate state read (#113).
+--
+-- Each destructive mutation (revoke binding / scope / harness / machine / domain) is paired with
+-- a BEFORE assertion (authorized) and an AFTER assertion (denied) so the deny is a verified FLIP,
+-- not an incidental false. The harness-revoked pin is the design panel's key amendment: a harness
+-- revoke does NOT cascade to child repo-scopes, so the scope stays 'active' yet the actor must be
+-- denied — that only holds because the chain walk re-checks fhr.lifecycle_state='active'.
+create extension if not exists pgtap with schema extensions;
+set search_path = extensions, public;
+
+begin;
+
+select plan(36);
+
+do $$
+declare
+  u_owner uuid; u_bound uuid; u_nonbound uuid; u_worker uuid; u_obs uuid; u_h2 uuid;
+  u_d2owner uuid; u_d2worker uuid; u_ttl uuid; u_quota uuid; u_bindrev uuid;
+begin
+  u_owner    := public.ensure_github_user('cg-owner',    'cg-owner@example.test',    'cg-owner',    'CG Owner');
+  u_bound    := public.ensure_github_user('cg-bound',    'cg-bound@example.test',    'cg-bound',    'CG Bound');
+  u_nonbound := public.ensure_github_user('cg-nonbound', 'cg-nonbound@example.test', 'cg-nonbound', 'CG NonBound');
+  u_worker   := public.ensure_github_user('cg-worker',   'cg-worker@example.test',   'cg-worker',   'CG Worker');
+  u_obs      := public.ensure_github_user('cg-obs',      'cg-obs@example.test',      'cg-obs',      'CG Observer');
+  u_h2       := public.ensure_github_user('cg-h2',       'cg-h2@example.test',       'cg-h2',       'CG H2');
+  u_d2owner  := public.ensure_github_user('cg-d2owner',  'cg-d2owner@example.test',  'cg-d2owner',  'CG D2 Owner');
+  u_d2worker := public.ensure_github_user('cg-d2worker', 'cg-d2worker@example.test', 'cg-d2worker', 'CG D2 Worker');
+  u_ttl      := public.ensure_github_user('cg-ttl',      'cg-ttl@example.test',      'cg-ttl',      'CG TTL');
+  u_quota    := public.ensure_github_user('cg-quota',    'cg-quota@example.test',    'cg-quota',    'CG Quota');
+  u_bindrev  := public.ensure_github_user('cg-bindrev',  'cg-bindrev@example.test',  'cg-bindrev',  'CG BindRev');
+
+  insert into agent_board.agents(id, agent_type, kind, handle, display_name, status, auth_user_id, owner_user_id)
+  values
+    ('c9a70000-0000-4000-8000-0000000000a1', 'agent', 'agent', 'cg-owner',    'CG Owner',    'active', u_owner,    u_owner),
+    ('c9a70000-0000-4000-8000-0000000000a2', 'agent', 'agent', 'cg-bound',    'CG Bound',    'active', u_bound,    u_bound),
+    ('c9a70000-0000-4000-8000-0000000000a3', 'agent', 'agent', 'cg-nonbound', 'CG NonBound', 'active', u_nonbound, u_nonbound),
+    ('c9a70000-0000-4000-8000-0000000000a4', 'agent', 'agent', 'cg-worker',   'CG Worker',   'active', u_worker,   u_worker),
+    ('c9a70000-0000-4000-8000-0000000000a5', 'agent', 'agent', 'cg-obs',      'CG Observer', 'active', u_obs,      u_obs),
+    ('c9a70000-0000-4000-8000-0000000000a6', 'agent', 'agent', 'cg-h2',       'CG H2',       'active', u_h2,       u_h2),
+    ('c9a70000-0000-4000-8000-0000000000b1', 'agent', 'agent', 'cg-d2owner',  'CG D2 Owner', 'active', u_d2owner,  u_d2owner),
+    ('c9a70000-0000-4000-8000-0000000000b2', 'agent', 'agent', 'cg-d2worker', 'CG D2 Worker','active', u_d2worker, u_d2worker),
+    ('c9a70000-0000-4000-8000-0000000000c9', 'agent', 'agent', 'cg-ttl',      'CG TTL',      'active', u_ttl,      u_ttl),
+    ('c9a70000-0000-4000-8000-0000000000ca', 'agent', 'agent', 'cg-quota',    'CG Quota',    'active', u_quota,    u_quota),
+    ('c9a70000-0000-4000-8000-0000000000a7', 'agent', 'agent', 'cg-bindrev',  'CG BindRev',  'active', u_bindrev,  u_bindrev);
+
+  -- ---- DOMAIN D1 (active) --------------------------------------------------------------
+  insert into agent_board.fleet_trust_domains(id, slug, display_name, domain_kind, owner_agent_id, lifecycle_state)
+  values ('c9a70000-0000-4000-8000-0000000000d1', 'cg-d1', 'CG Domain 1', 'tailnet', 'c9a70000-0000-4000-8000-0000000000a1', 'active');
+
+  -- M1 fpM1 (owner = A_owner); Mrev fpMrev (owner = A_owner, revoked mid-test).
+  insert into agent_board.fleet_machines(id, trust_domain_id, owner_agent_id, machine_label, machine_fingerprint, lifecycle_state)
+  values
+    ('c9a70000-0000-4000-8000-0000000000f1', 'c9a70000-0000-4000-8000-0000000000d1', 'c9a70000-0000-4000-8000-0000000000a1', 'M1',   'fpM1',   'active'),
+    ('c9a70000-0000-4000-8000-0000000000f2', 'c9a70000-0000-4000-8000-0000000000d1', 'c9a70000-0000-4000-8000-0000000000a1', 'Mrev', 'fpMrev', 'active');
+
+  -- Harness H1 (active) on M1: worker + observer scopes on the SAME repo (fpR1).
+  insert into agent_board.fleet_harness_registrations(id, machine_id, harness_kind, harness_label, lifecycle_state)
+  values ('c9a70000-0000-4000-8000-0000000000e1', 'c9a70000-0000-4000-8000-0000000000f1', 'claude', 'H1', 'active');
+  insert into agent_board.fleet_repo_scopes(id, harness_registration_id, repo_slug, repo_fingerprint, scope_role, lifecycle_state)
+  values
+    ('c9a70000-0000-4000-8000-00000000ab01', 'c9a70000-0000-4000-8000-0000000000e1', 'repo1',  'fpR1',  'worker',   'active'),
+    ('c9a70000-0000-4000-8000-00000000ab02', 'c9a70000-0000-4000-8000-0000000000e1', 'repo1',  'fpR1',  'observer', 'active'),
+    -- RSbr: a distinct active worker scope (fpR1b) for the repo-arm BINDING-revoke pin. Distinct
+    -- fingerprint so it does not collide with RSW on (harness, repo_fingerprint, scope_role).
+    ('c9a70000-0000-4000-8000-00000000ab05', 'c9a70000-0000-4000-8000-0000000000e1', 'repo1b', 'fpR1b', 'worker',   'active');
+
+  -- Harness H2 (active, REVOKED mid-test) on M1: worker scope on fpR2 (the harness-revoke pin).
+  insert into agent_board.fleet_harness_registrations(id, machine_id, harness_kind, harness_label, lifecycle_state)
+  values ('c9a70000-0000-4000-8000-0000000000e2', 'c9a70000-0000-4000-8000-0000000000f1', 'codex', 'H2', 'active');
+  insert into agent_board.fleet_repo_scopes(id, harness_registration_id, repo_slug, repo_fingerprint, scope_role, lifecycle_state)
+  values ('c9a70000-0000-4000-8000-00000000ab03', 'c9a70000-0000-4000-8000-0000000000e2', 'repo2', 'fpR2', 'worker', 'active');
+
+  -- Bindings on M1.
+  insert into agent_board.fleet_machine_agents(id, machine_id, agent_id, repo_scope_id, lifecycle_state)
+  values
+    ('c9a70000-0000-4000-8000-00000000ac02', 'c9a70000-0000-4000-8000-0000000000f1', 'c9a70000-0000-4000-8000-0000000000a2', null,                                     'active'),
+    ('c9a70000-0000-4000-8000-00000000ac04', 'c9a70000-0000-4000-8000-0000000000f1', 'c9a70000-0000-4000-8000-0000000000a4', 'c9a70000-0000-4000-8000-00000000ab01',   'active'),
+    ('c9a70000-0000-4000-8000-00000000ac05', 'c9a70000-0000-4000-8000-0000000000f1', 'c9a70000-0000-4000-8000-0000000000a5', 'c9a70000-0000-4000-8000-00000000ab02',   'active'),
+    ('c9a70000-0000-4000-8000-00000000ac06', 'c9a70000-0000-4000-8000-0000000000f1', 'c9a70000-0000-4000-8000-0000000000a6', 'c9a70000-0000-4000-8000-00000000ab03',   'active'),
+    ('c9a70000-0000-4000-8000-00000000ac07', 'c9a70000-0000-4000-8000-0000000000f1', 'c9a70000-0000-4000-8000-0000000000a7', 'c9a70000-0000-4000-8000-00000000ab05',   'active');
+
+  -- ---- DOMAIN D2 (active, REVOKED mid-test) --------------------------------------------
+  insert into agent_board.fleet_trust_domains(id, slug, display_name, domain_kind, owner_agent_id, lifecycle_state)
+  values ('c9a70000-0000-4000-8000-0000000000d2', 'cg-d2', 'CG Domain 2', 'tailnet', 'c9a70000-0000-4000-8000-0000000000b1', 'active');
+  insert into agent_board.fleet_machines(id, trust_domain_id, owner_agent_id, machine_label, machine_fingerprint, lifecycle_state)
+  values ('c9a70000-0000-4000-8000-0000000000f3', 'c9a70000-0000-4000-8000-0000000000d2', 'c9a70000-0000-4000-8000-0000000000b1', 'M2', 'fpM2', 'active');
+  insert into agent_board.fleet_harness_registrations(id, machine_id, harness_kind, harness_label, lifecycle_state)
+  values ('c9a70000-0000-4000-8000-0000000000e3', 'c9a70000-0000-4000-8000-0000000000f3', 'claude', 'H3', 'active');
+  insert into agent_board.fleet_repo_scopes(id, harness_registration_id, repo_slug, repo_fingerprint, scope_role, lifecycle_state)
+  values ('c9a70000-0000-4000-8000-00000000ab04', 'c9a70000-0000-4000-8000-0000000000e3', 'repo3', 'fpR3', 'worker', 'active');
+  insert into agent_board.fleet_machine_agents(id, machine_id, agent_id, repo_scope_id, lifecycle_state)
+  values ('c9a70000-0000-4000-8000-00000000ac23', 'c9a70000-0000-4000-8000-0000000000f3', 'c9a70000-0000-4000-8000-0000000000b2', 'c9a70000-0000-4000-8000-00000000ab04', 'active');
+
+  -- NEGATIVE RULE fixture: A_nonbound is a board OWNER but has NO fleet binding — must be denied.
+  insert into agent_board.boards(id, slug, name, created_by_agent_id)
+  values ('c9a70000-0000-4000-8000-00000000ad01', 'cg-neg-board', 'CG Neg Board', 'c9a70000-0000-4000-8000-0000000000a3');
+
+  perform set_config('_cg.owner',    u_owner::text,    true);
+  perform set_config('_cg.bound',     u_bound::text,     true);
+  perform set_config('_cg.nonbound',  u_nonbound::text,  true);
+  perform set_config('_cg.worker',    u_worker::text,    true);
+  perform set_config('_cg.obs',       u_obs::text,       true);
+  perform set_config('_cg.h2',        u_h2::text,        true);
+  perform set_config('_cg.d2owner',   u_d2owner::text,   true);
+  perform set_config('_cg.d2worker',  u_d2worker::text,  true);
+  perform set_config('_cg.ttl',       u_ttl::text,       true);
+  perform set_config('_cg.quota',     u_quota::text,     true);
+  perform set_config('_cg.bindrev',   u_bindrev::text,   true);
+end
+$$;
+
+-- Seed 49 = (quota - 1) active file claims for the quota agent (postgres insert, RLS bypassed).
+-- The 50th acquire reaches the cap and lives; the 51st is denied.
+insert into agent_board.claims(agent_id, resource_kind, resource_key, lease_expires_at)
+select 'c9a70000-0000-4000-8000-0000000000ca', 'file', 'cg-quota-seed-' || g, now() + interval '1 hour'
+  from generate_series(1, agent_board._claimgate_ownerless_quota() - 1) g;
+
+set local role authenticated;
+select set_config('request.jwt.claim.role', 'authenticated', true);
+
+-- ============================ MACHINE ARM ============================================
+select set_config('request.jwt.claim.sub', current_setting('_cg.owner'), true);
+select is((select agent_board._can_claim_resource('machine', 'fpM1')), true,
+  'machine: the machine OWNER is authorized');
+
+select set_config('request.jwt.claim.sub', current_setting('_cg.bound'), true);
+select is((select agent_board._can_claim_resource('machine', 'fpM1')), true,
+  'machine: an actively BOUND agent is authorized');
+
+select set_config('request.jwt.claim.sub', current_setting('_cg.nonbound'), true);
+select is((select agent_board._can_claim_resource('machine', 'fpM1')), false,
+  'machine: a non-bound agent is DENIED');
+
+-- machine-revoked flip (owner of Mrev, fpMrev): authorized BEFORE, denied AFTER revoke.
+select set_config('request.jwt.claim.sub', current_setting('_cg.owner'), true);
+select is((select agent_board._can_claim_resource('machine', 'fpMrev')), true,
+  'machine: owner authorized on an active machine (pre-revoke)');
+reset role;
+update agent_board.fleet_machines set lifecycle_state = 'revoked', revoked_at = now()
+ where id = 'c9a70000-0000-4000-8000-0000000000f2';
+set local role authenticated;
+select set_config('request.jwt.claim.role', 'authenticated', true);
+select set_config('request.jwt.claim.sub', current_setting('_cg.owner'), true);
+select is((select agent_board._can_claim_resource('machine', 'fpMrev')), false,
+  'machine: a REVOKED machine denies even its owner (flip)');
+
+-- revoked-binding flip (A_bound on M1): authorized above, denied after its binding is revoked.
+reset role;
+update agent_board.fleet_machine_agents set lifecycle_state = 'revoked', revoked_at = now()
+ where id = 'c9a70000-0000-4000-8000-00000000ac02';
+set local role authenticated;
+select set_config('request.jwt.claim.role', 'authenticated', true);
+select set_config('request.jwt.claim.sub', current_setting('_cg.bound'), true);
+select is((select agent_board._can_claim_resource('machine', 'fpM1')), false,
+  'machine: a REVOKED binding denies (flip)');
+
+-- ============================ REPO ARM ==============================================
+select set_config('request.jwt.claim.sub', current_setting('_cg.worker'), true);
+select is((select agent_board._can_claim_resource('repository', 'fpR1')), true,
+  'repo: an active non-observer (worker) scope is authorized');
+select is((select agent_board._can_claim_resource('repo_file', 'fpR1:src/db.sql')), true,
+  'repo_file: fp extracted before the first colon is authorized (worker scope)');
+
+select set_config('request.jwt.claim.sub', current_setting('_cg.obs'), true);
+select is((select agent_board._can_claim_resource('repository', 'fpR1')), false,
+  'repo: an OBSERVER scope is DENIED');
+
+-- repo-arm BINDING-revoke flip (A_bindrev on fpR1b): authorized BEFORE, denied AFTER only its
+-- own fleet_machine_agents binding is revoked (scope + harness + machine + domain stay active).
+-- This is the sole pin on the repo arm's `fma.lifecycle_state='active'` edge — the entire effect
+-- of revoke_fleet_subject('agent',…), which revokes ONLY bindings, flows through that one line.
+select set_config('request.jwt.claim.sub', current_setting('_cg.bindrev'), true);
+select is((select agent_board._can_claim_resource('repository', 'fpR1b')), true,
+  'repo: an active binding to an active non-observer scope is authorized (pre binding-revoke)');
+reset role;
+update agent_board.fleet_machine_agents set lifecycle_state = 'revoked', revoked_at = now()
+ where id = 'c9a70000-0000-4000-8000-00000000ac07';
+set local role authenticated;
+select set_config('request.jwt.claim.role', 'authenticated', true);
+select set_config('request.jwt.claim.sub', current_setting('_cg.bindrev'), true);
+select is((select agent_board._can_claim_resource('repository', 'fpR1b')), false,
+  'repo: a REVOKED binding denies the repo arm though scope/harness/machine stay active (flip)');
+
+-- harness-revoked pin (A_h2 on fpR2): authorized BEFORE, denied AFTER the HARNESS is revoked,
+-- while its repo-scope stays active (revoke does not cascade — the load-bearing fhr edge check).
+select set_config('request.jwt.claim.sub', current_setting('_cg.h2'), true);
+select is((select agent_board._can_claim_resource('repository', 'fpR2')), true,
+  'repo: worker scope under an active harness is authorized (pre harness-revoke)');
+reset role;
+update agent_board.fleet_harness_registrations set lifecycle_state = 'revoked', revoked_at = now()
+ where id = 'c9a70000-0000-4000-8000-0000000000e2';
+select is(
+  (select count(*)::int from agent_board.fleet_repo_scopes
+    where id = 'c9a70000-0000-4000-8000-00000000ab03' and lifecycle_state = 'active'),
+  1, 'repo: the child repo-scope is STILL active after the harness revoke (no cascade)');
+set local role authenticated;
+select set_config('request.jwt.claim.role', 'authenticated', true);
+select set_config('request.jwt.claim.sub', current_setting('_cg.h2'), true);
+select is((select agent_board._can_claim_resource('repository', 'fpR2')), false,
+  'repo: a REVOKED HARNESS denies though the scope is active (PANEL amendment pin, flip)');
+
+-- revoked-scope flip (A_worker on fpR1): revoke the worker scope -> denied.
+reset role;
+update agent_board.fleet_repo_scopes set lifecycle_state = 'revoked', revoked_at = now()
+ where id = 'c9a70000-0000-4000-8000-00000000ab01';
+set local role authenticated;
+select set_config('request.jwt.claim.role', 'authenticated', true);
+select set_config('request.jwt.claim.sub', current_setting('_cg.worker'), true);
+select is((select agent_board._can_claim_resource('repository', 'fpR1')), false,
+  'repo: a REVOKED repo-scope denies (flip)');
+
+-- domain-revoked flip (D2): A_d2owner (machine) and A_d2worker (repo) authorized BEFORE, denied AFTER.
+select set_config('request.jwt.claim.sub', current_setting('_cg.d2owner'), true);
+select is((select agent_board._can_claim_resource('machine', 'fpM2')), true,
+  'domain: D2 machine owner authorized (pre domain-revoke)');
+select set_config('request.jwt.claim.sub', current_setting('_cg.d2worker'), true);
+select is((select agent_board._can_claim_resource('repository', 'fpR3')), true,
+  'domain: D2 repo worker authorized (pre domain-revoke)');
+reset role;
+update agent_board.fleet_trust_domains set lifecycle_state = 'revoked', revoked_at = now()
+ where id = 'c9a70000-0000-4000-8000-0000000000d2';
+set local role authenticated;
+select set_config('request.jwt.claim.role', 'authenticated', true);
+select set_config('request.jwt.claim.sub', current_setting('_cg.d2owner'), true);
+select is((select agent_board._can_claim_resource('machine', 'fpM2')), false,
+  'domain: a REVOKED trust domain denies the machine arm (flip)');
+select set_config('request.jwt.claim.sub', current_setting('_cg.d2worker'), true);
+select is((select agent_board._can_claim_resource('repository', 'fpR3')), false,
+  'domain: a REVOKED trust domain denies the repo arm (flip)');
+
+-- ============================ NEGATIVE RULE ==========================================
+-- A board OWNER with no fleet binding is denied on BOTH arms (fleet graph only, no fallback).
+select set_config('request.jwt.claim.sub', current_setting('_cg.nonbound'), true);
+select is((select agent_board._can_claim_resource('machine', 'fpM1')), false,
+  'NEGATIVE: a board owner NOT in the fleet graph is denied (machine)');
+select is((select agent_board._can_claim_resource('repository', 'fpR1')), false,
+  'NEGATIVE: a board owner NOT in the fleet graph is denied (repository)');
+
+-- ============================ OWNERLESS TAIL (predicate returns true; guards live in acquire) ===
+select set_config('request.jwt.claim.sub', current_setting('_cg.nonbound'), true);
+select is((select agent_board._can_claim_resource('file', 'anything')), true,
+  'ownerless: file is not fleet-gated (predicate true)');
+select is((select agent_board._can_claim_resource('task', gen_random_uuid()::text)), true,
+  'task: not this predicate''s concern (predicate true)');
+
+-- ============================ CATALOG-DERIVED COMPLETENESS ============================
+-- Every resource_kind the CHECK constraint admits resolves to a non-null verdict — a new kind
+-- (added to the constraint without a predicate arm) makes this fail and names itself.
+select is(
+  (select count(*)::int
+     from (
+       select unnest(array['task','file','repo_file','repository','machine','tool','custom']) as k
+     ) kinds
+    where agent_board._can_claim_resource(
+            kinds.k,
+            case kinds.k when 'repo_file' then 'fp:path' when 'task' then gen_random_uuid()::text else 'x' end
+          ) is null),
+  0, 'completeness: every catalog resource_kind resolves to a non-null verdict');
+select is(
+  (select array_agg(distinct m[1] order by m[1])
+     from pg_constraint c
+    cross join lateral regexp_matches(pg_get_constraintdef(c.oid), '''([a-z_]+)''', 'g') as m
+    where c.conname = 'claims_resource_kind_check'
+      and c.conrelid = 'agent_board.claims'::regclass),
+  array['custom','file','machine','repo_file','repository','task','tool']::text[],
+  'completeness: the catalog kind set is exactly the 7 the predicate enumerates (guards a silent new kind)');
+
+-- ============================ SHADOW STAMP — BLOCKS NOTHING (denied actor STILL acquires) ===
+-- The discriminating case: acquire as a fleet-DENIED actor. The claim MUST be created and the
+-- stamp MUST record authorized=false. (With an authorized actor this would prove nothing.)
+select set_config('request.jwt.claim.sub', current_setting('_cg.nonbound'), true);
+select lives_ok($$
+  select agent_board.acquire_claim(
+    null, 'machine', 'fpM1', now() + interval '1 hour', null, null, '{}'::jsonb)
+$$, 'shadow: a fleet-DENIED actor can still acquire (blocks nothing)');
+
+select is(
+  (select (metadata #>> '{claimgate_shadow,authorized}')::boolean
+     from agent_board.claims
+    where resource_kind = 'machine' and resource_key = 'fpM1'
+      and agent_id = 'c9a70000-0000-4000-8000-0000000000a3'),
+  false, 'shadow: the stamp on the denied actor''s claim records authorized=false');
+
+select is(
+  (select metadata #>> '{claimgate_shadow,kind}'
+     from agent_board.claims
+    where resource_kind = 'machine' and resource_key = 'fpM1'
+      and agent_id = 'c9a70000-0000-4000-8000-0000000000a3'),
+  'machine', 'shadow: the stamp records the resource kind');
+
+-- Authorized-verdict stamp: an ownerless (file) acquire as A_owner records authorized=true.
+select set_config('request.jwt.claim.sub', current_setting('_cg.owner'), true);
+select lives_ok($$
+  select agent_board.acquire_claim(
+    null, 'file', 'cg-owner-file-1', now() + interval '1 hour', null, null, '{}'::jsonb)
+$$, 'shadow: an authorized (ownerless) acquire succeeds');
+select is(
+  (select (metadata #>> '{claimgate_shadow,authorized}')::boolean
+     from agent_board.claims
+    where resource_kind = 'file' and resource_key = 'cg-owner-file-1'),
+  true, 'shadow: an authorized verdict stamps authorized=true');
+
+-- ============================ OWNERLESS GUARDS — OFF BY DEFAULT (blocks nothing) ======
+-- The TTL cap + quota are gated behind _claimgate_ownerless_guards_enabled(), which DEFAULTS
+-- FALSE (no flag row). Per the census amendment SHADOW ships with guards OFF, so an over-cap
+-- AND an over-quota ownerless acquire both SUCCEED — SHADOW literally blocks nothing.
+select set_config('request.jwt.claim.sub', current_setting('_cg.ttl'), true);
+select lives_ok($$
+  select agent_board.acquire_claim(
+    null, 'file', 'cg-ttl-offcap', now() + interval '40 days', null, null, '{}'::jsonb)
+$$, 'guards OFF (default): an over-cap ownerless lease SUCCEEDS (blocks nothing)');
+
+-- u_quota holds (quota-1)=49 seeded; with guards off, pushing to and past the quota still succeeds.
+select set_config('request.jwt.claim.sub', current_setting('_cg.quota'), true);
+select lives_ok($$
+  select agent_board.acquire_claim(
+    null, 'file', 'cg-quota-off-a', now() + interval '1 hour', null, null, '{}'::jsonb)
+$$, 'guards OFF: the quota-th ownerless acquire succeeds');
+select lives_ok($$
+  select agent_board.acquire_claim(
+    null, 'file', 'cg-quota-off-b', now() + interval '1 hour', null, null, '{}'::jsonb)
+$$, 'guards OFF (default): an over-quota ownerless acquire SUCCEEDS (blocks nothing)');
+
+-- ============================ OWNERLESS GUARDS — FLIP ON (operator post-census) =======
+-- The operator enables the guards after the census ratifies the cap; now the cap + quota enforce.
+reset role;
+insert into agent_board.claimgate_enforcement_flags(scope_key, enabled) values ('ownerless_guards', true)
+  on conflict (scope_key) do update set enabled = true;
+set local role authenticated;
+select set_config('request.jwt.claim.role', 'authenticated', true);
+
+-- u_quota now holds 49 + 2 = 51 active >= quota(50): any further ownerless acquire is denied.
+select set_config('request.jwt.claim.sub', current_setting('_cg.quota'), true);
+select throws_ok($$
+  select agent_board.acquire_claim(
+    null, 'file', 'cg-quota-on', now() + interval '1 hour', null, null, '{}'::jsonb)
+$$, '54000', null, 'guards ON: an over-quota ownerless acquire is denied');
+
+-- TTL cap enforces once ON: over-horizon rejected (checked before quota), within-horizon allowed.
+select set_config('request.jwt.claim.sub', current_setting('_cg.ttl'), true);
+select throws_ok($$
+  select agent_board.acquire_claim(
+    null, 'file', 'cg-ttl-on-over', now() + interval '40 days', null, null, '{}'::jsonb)
+$$, '22023', null, 'guards ON: an over-cap ownerless lease is rejected');
+select lives_ok($$
+  select agent_board.acquire_claim(
+    null, 'file', 'cg-ttl-on-ok', now() + interval '1 hour', null, null, '{}'::jsonb)
+$$, 'guards ON: a within-horizon ownerless lease is allowed');
+
+reset role;
+select * from finish();
+
+rollback;

package/tests/agent_board_claimkey.test.sql

@@ -0,0 +1,229 @@
+-- CLAIMGATE Phase 1 — CLAIMKEY (#133) pgTAP.
+--
+-- Pins IF-0-CLAIMKEY-1 (the canonical claim-key grammar) and the NORMALIZE-ONLY wiring into
+-- acquire_claim / renew_claim / release_claim. Every property below is mutation-pinned: the
+-- deliberate break that flips each assertion is noted inline.
+--
+-- Runs as the postgres db role; request.jwt.claim.role='service_role' takes the operator
+-- carve-out so acquire honours the supplied agent id and renew/release skip the ownership
+-- check (we exercise the KEY NORMALIZATION, not the authz gates, which are unchanged here).
+--
+-- Allow-side is lives_ok(...) + a separate state read (never is((select … from rpc()))) —
+-- repo rule #113. The normalizer itself is a PURE function (no side effect, cannot abort the
+-- txn), so its shape checks use is() directly.
+create extension if not exists pgtap with schema extensions;
+set search_path = extensions, public, agent_board;
+
+begin;
+
+select plan(25);
+
+select set_config('request.jwt.claim.role', 'service_role', true);
+select set_config('request.jwt.claim.sub', '', true);
+
+create temp table _ck_fixture (
+  agent uuid,
+  tok_dup_legacy uuid,   -- 'machine:fpDup' — active, aliased with a canonical twin
+  tok_heal uuid,         -- 'machine:fpHeal' — active, lone (canonical is free)
+  tok_release uuid       -- 'machine:fpRel' — active, lone
+) on commit drop;
+
+do $$
+declare
+  v_agent uuid := gen_random_uuid();
+  v_tok_dup_legacy uuid;
+  v_tok_heal uuid;
+  v_tok_release uuid;
+begin
+  insert into agent_board.agents(id, agent_type, handle, display_name, status)
+  values (v_agent, 'agent', 'ck-agent-' || substr(v_agent::text, 1, 8), 'CK Agent', 'active');
+
+  -- Aliased pair for the renew never-raise pin: a legacy-shaped key and its canonical twin,
+  -- both ACTIVE (distinct resource_key values, so the partial unique index permits both).
+  insert into agent_board.claims(agent_id, resource_kind, resource_key, lease_expires_at)
+  values (v_agent, 'machine', 'machine:fpDup', now() + interval '1 hour')
+  returning lease_token into v_tok_dup_legacy;
+  insert into agent_board.claims(agent_id, resource_kind, resource_key, lease_expires_at)
+  values (v_agent, 'machine', 'fpDup', now() + interval '1 hour');
+
+  -- Lone legacy claim whose canonical form is FREE — renew must self-heal it.
+  insert into agent_board.claims(agent_id, resource_kind, resource_key, lease_expires_at)
+  values (v_agent, 'machine', 'machine:fpHeal', now() + interval '1 hour')
+  returning lease_token into v_tok_heal;
+
+  -- Lone legacy claim for the release canonicalization pin.
+  insert into agent_board.claims(agent_id, resource_kind, resource_key, lease_expires_at)
+  values (v_agent, 'machine', 'machine:fpRel', now() + interval '1 hour')
+  returning lease_token into v_tok_release;
+
+  -- MUST-FIX 3: still-active LEGACY-keyed claims; a fresh acquire whose canonical form aliases
+  -- one must be rejected (no second live hold on the same machine during the legacy window).
+  -- Two independent legacy rows so the prefixed-input and bare-input pins don't contaminate each
+  -- other (a first wrongful insert must not satisfy the second's conflict check).
+  insert into agent_board.claims(agent_id, resource_kind, resource_key, lease_expires_at)
+  values (v_agent, 'machine', 'machine:fpDH',  now() + interval '1 hour'),
+         (v_agent, 'machine', 'machine:fpDH2', now() + interval '1 hour');
+
+  insert into _ck_fixture values (v_agent, v_tok_dup_legacy, v_tok_heal, v_tok_release);
+end
+$$;
+
+-- ============================================================================
+-- A. _canonical_claim_key grammar (IF-0-CLAIMKEY-1) — pure function shape pins
+--    Mutation: revert the normalizer to identity (return btrim(p_resource_key))
+--    -> assertions 1,3-8 flip (bare/trim cases hold; transforms fail).
+-- ============================================================================
+select is(agent_board._canonical_claim_key('machine', 'machine:fp1'), 'fp1',
+  'machine: strips a legacy machine: prefix to the bare fingerprint');
+select is(agent_board._canonical_claim_key('machine', 'fp1'), 'fp1',
+  'machine: a bare fingerprint is already canonical');
+select is(agent_board._canonical_claim_key('machine', '  fp2  '), 'fp2',
+  'machine: surrounding whitespace is trimmed');
+select is(agent_board._canonical_claim_key('repository', 'repository:r1'), 'r1',
+  'repository: strips a legacy repository: prefix');
+select is(agent_board._canonical_claim_key('repository', 'repo:r1'), 'r1',
+  'repository: strips a legacy repo: prefix');
+select is(agent_board._canonical_claim_key('repo_file', 'repo_file:fpR:src/db.sql'), 'fpR:src/db.sql',
+  'repo_file: strips the kind prefix and keeps <fp>:<path>');
+select is(agent_board._canonical_claim_key('repo_file', 'fpR:src/db.sql'), 'fpR:src/db.sql',
+  'repo_file: a bare <fp>:<path> is already canonical');
+select is(agent_board._canonical_claim_key('repo_file', 'fpR:a:b'), 'fpR:a:b',
+  'repo_file: only the FIRST colon splits fp|path (path may contain colons)');
+select is(agent_board._canonical_claim_key('custom', '  ck  '), '  ck  ',
+  'custom: free-form key passes through VERBATIM — not even trimmed (SHOULD-FIX 4; " x " != "x")');
+select is(
+  agent_board._canonical_claim_key('task', '11111111-2222-3333-4444-555555555555'),
+  '11111111-2222-3333-4444-555555555555',
+  'task: uuid key passes through unchanged');
+-- Unmappable keys are shadow-logged and returned UNCHANGED — never rejected (normalize-only).
+select is(agent_board._canonical_claim_key('machine', 'machine:'), 'machine:',
+  'machine: an empty-after-strip key is unmappable — returned unchanged, not raised');
+select is(agent_board._canonical_claim_key('repo_file', 'repo_file:justfp'), 'repo_file:justfp',
+  'repo_file: a single-component key has no <fp>:<path> split — unmappable, returned unchanged (not rejected)');
+
+-- ============================================================================
+-- B. acquire_claim normalizes the SUPPLIED key before insert/uniqueness
+--    Mutation: delete the `p_resource_key := _canonical_claim_key(...)` line in
+--    acquire_claim -> assertion 14 (stored key) and 15 (canonical dedup) flip.
+-- ============================================================================
+select lives_ok(
+  (select format($q$select agent_board.acquire_claim(%L::uuid, 'machine', 'machine:fpAcq', now() + interval '1 hour')$q$, agent)
+     from _ck_fixture),
+  'acquire_claim accepts a legacy-prefixed machine key (normalize-only, no rejection)');
+select is(
+  (select resource_key from agent_board.claims
+    where resource_kind = 'machine' and status = 'active'
+      and agent_id = (select agent from _ck_fixture)
+      and resource_key = 'fpAcq'),
+  'fpAcq',
+  'acquire_claim STORES the canonical bare fingerprint, not the prefixed input');
+-- The bare canonical form now contends on the SAME uniqueness slot -> conflict.
+select throws_ok(
+  (select format($q$select agent_board.acquire_claim(%L::uuid, 'machine', 'fpAcq', now() + interval '1 hour')$q$, agent)
+     from _ck_fixture),
+  '23505', 'conflicting active claim',
+  'a bare key canonically aliasing an active prefixed acquire conflicts (normalization feeds the index)');
+
+-- ============================================================================
+-- C. renew_claim is NON-RAISING on a canonical alias via retry-once (MUST-FIX 1)
+--    The canonical twin 'fpDup' is committed-visible, so renew's first UPDATE toward 'fpDup'
+--    deterministically collides (23505) and the unique_violation handler retries keeping the
+--    legacy key — exercising the SAME handler that covers the concurrent race.
+--    Mutation: drop the exception handler (bare unconditional-canonical UPDATE) ->
+--    assertion 16 (lives_ok) flips red with 23505. (Concurrent race pinned by the
+--    isolation spec claimkey_renew_race.spec.)
+-- ============================================================================
+select lives_ok(
+  (select format($q$select agent_board.renew_claim(%L::uuid, now() + interval '2 hours')$q$, tok_dup_legacy)
+     from _ck_fixture),
+  'renew_claim does NOT raise when the canonical key is already held by an active twin');
+select is(
+  (select resource_key from agent_board.claims
+    where lease_token = (select tok_dup_legacy from _ck_fixture)),
+  'machine:fpDup',
+  'renew_claim KEEPS the legacy key when its canonical form is occupied (deferred alias for ENFORCE)');
+
+-- ============================================================================
+-- D. renew_claim self-heals a lone legacy key to canonical
+--    Mutation: drop the resource_key CASE from renew's UPDATE set-list ->
+--    assertion 19 flips (key stays 'machine:fpHeal').
+-- ============================================================================
+select lives_ok(
+  (select format($q$select agent_board.renew_claim(%L::uuid, now() + interval '2 hours')$q$, tok_heal)
+     from _ck_fixture),
+  'renew_claim renews a lone legacy-keyed lease');
+select is(
+  (select resource_key from agent_board.claims
+    where lease_token = (select tok_heal from _ck_fixture)),
+  'fpHeal',
+  'renew_claim canonicalizes a lone legacy key when the canonical form is free (self-heal)');
+
+-- ============================================================================
+-- E. release_claim canonicalizes the stored key (always safe — row leaves index)
+--    Mutation: drop the resource_key assignment from release's UPDATE ->
+--    assertion 21 flips (key stays 'machine:fpRel').
+-- ============================================================================
+select lives_ok(
+  (select format($q$select agent_board.release_claim(%L::uuid)$q$, tok_release)
+     from _ck_fixture),
+  'release_claim releases a legacy-keyed lease');
+select is(
+  (select resource_key || '|' || status from agent_board.claims
+    where lease_token = (select tok_release from _ck_fixture)),
+  'fpRel|released',
+  'release_claim canonicalizes the stored key as it releases');
+
+-- ============================================================================
+-- E2. acquire is ALIAS-AWARE against an un-healed legacy row (MUST-FIX 3)
+--     'machine:fpDH' is active (legacy); an acquire whose canonical form is 'fpDH' must
+--     conflict — otherwise two agents hold the same machine during the legacy window.
+--     Mutation: revert acquire's sweep/conflict to exact `resource_key = p_resource_key`
+--     -> both acquires below succeed and assertions 22,23 flip to lives (throws_ok fails).
+-- ============================================================================
+select throws_ok(
+  (select format($q$select agent_board.acquire_claim(%L::uuid, 'machine', 'machine:fpDH', now() + interval '1 hour')$q$, agent)
+     from _ck_fixture),
+  '23505', 'conflicting active claim',
+  'acquire of a legacy-prefixed key aliasing an active legacy row conflicts (no dual live hold)');
+select throws_ok(
+  (select format($q$select agent_board.acquire_claim(%L::uuid, 'machine', 'fpDH2', now() + interval '1 hour')$q$, agent)
+     from _ck_fixture),
+  '23505', 'conflicting active claim',
+  'acquire of the bare canonical key aliasing an active legacy row also conflicts (independent row)');
+
+-- ============================================================================
+-- F. Catalog-derived completeness (repo rule #1): the resource_key writer class,
+--    enumerated from pg_proc — NOT from a hand list. A new claims writer changes
+--    the set (set_eq names it) and, if it skips the normalizer, fails assertion 25.
+--    Regexes are case-insensitive, whitespace-tolerant, and match an UNQUALIFIED
+--    `update claims` (schema on search_path) — a qualifier/spacing dodge no longer
+--    fails-open (MUST-FIX 2). Mutation: add any new agent_board function that writes
+--    claims without routing through _canonical_claim_key -> both 24 and 25 flip and name it.
+-- ============================================================================
+select set_eq(
+  $$ select 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 pg_get_functiondef(p.oid) ~* '(insert\s+into|update)\s+(agent_board\.)?claims\M' $$,
+  -- reclaim_fleet_machine (#150) is a fourth writer: on operator reclaim it RELEASES the squatter's
+  -- active machine claim(s) on the reclaimed fingerprint so the new owner can acquire. It routes the
+  -- key through _canonical_claim_key (assertion 25 stays 0); its positive state claim (status set to
+  -- 'released') is pinned in agent_board_fleet_machine_reclaim.test.sql.
+  array['acquire_claim', 'renew_claim', 'release_claim', 'reclaim_fleet_machine'],
+  'exactly acquire/renew/release/reclaim write agent_board.claims (catalog-enumerated writer class)');
+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 pg_get_functiondef(p.oid) ~* '(insert\s+into|update)\s+(agent_board\.)?claims\M'
+      and pg_get_functiondef(p.oid) !~ '_canonical_claim_key'),
+  0,
+  'every catalog-enumerated claims writer routes its resource_key through _canonical_claim_key');
+
+select * from finish();
+
+rollback;

package/tests/agent_board_consent_backfill.test.sql

@@ -0,0 +1,48 @@
+-- message-board#103 — BEHAVIOURAL test of the MBCONSENT-A (20260806000100) backfill.
+--
+-- The test runner seeds a legacy 'requested' board_membership BEFORE that migration
+-- (tests/seeds/20260806000100_agent_board_consent_substrate.sql.pre.sql), so the SHIPPED backfill
+-- runs against a real row. This asserts what the shipped migration actually wrote — it FAILS if
+-- the backfill is removed or miscorrelated, with the migration unmodified (message-board#103
+-- acceptance). Reads persisted replay state (no fixture of its own); the begin/rollback wrapper
+-- the runner adds does not undo the already-applied backfill.
+create extension if not exists pgtap with schema extensions;
+set search_path = extensions, public;
+
+begin;
+
+select plan(3);
+
+-- The seeded pending subject received exactly ONE backfill event, with the exact shape the
+-- shipped backfill promises: neutral kind, the pending state preserved, board-authored provenance,
+-- and the board creator as the actor. Remove the backfill -> 0 rows -> fails. Miscorrelate the
+-- not-exists / join (e.agent_id, bm.board_id, created_by) -> wrong shape or 0 -> fails.
+select is(
+  (select count(*)::int from agent_board.board_membership_events e
+    where e.board_id = 'bf103bbb-0000-0000-0000-0000000000b1'
+      and e.agent_id = 'bf103aaa-0000-0000-0000-000000000002'
+      and e.event_kind = 'backfill_neutral'
+      and e.result_state = 'requested'
+      and e.provenance = 'board-authored'
+      and e.actor_agent_id = 'bf103aaa-0000-0000-0000-000000000001'),
+  1,
+  'shipped MBCONSENT-A backfill emitted the neutral board-authored event for the seeded pending row');
+
+-- Exactly one event for the subject (the DISTINCT ON / not-exists de-duplication held).
+select is(
+  (select count(*)::int from agent_board.board_membership_events e
+    where e.board_id = 'bf103bbb-0000-0000-0000-0000000000b1'
+      and e.agent_id = 'bf103aaa-0000-0000-0000-000000000002'),
+  1,
+  'the seeded subject received exactly one backfill event (no duplicate emission)');
+
+-- The predicate derived consent presence from the backfilled ledger: a board-authored neutral
+-- event is NOT the subject's own consent act, so the subject is not consent-present.
+select is(
+  agent_board._membership_consent_present('bf103bbb-0000-0000-0000-0000000000b1', 'bf103aaa-0000-0000-0000-000000000002'),
+  false,
+  'a backfilled board-authored neutral event does not by itself establish subject consent');
+
+select * from finish();
+
+rollback;