@consiliency/agent-board-schema 1.48.0 → 1.51.0

package/tests/agent_board_fk_lock_edges.test.sql

@@ -259,12 +259,32 @@ select is(
 -- pinned as a class in agent_board_task_thread_lock_order.test.sql (TT-1), which
 -- is what makes a REGRESSION fail there and name the function, rather than only
 -- failing here as an opaque re-appearance of the pair.
+--
+-- ONE PAIR HAS BEEN ADDED, and it is added with its own positive pin rather than as a
+-- widened exemption. F1's supersede-at-the-cap makes issue_signing_key_challenge write
+-- an agent_signing_key_challenges row while holding the agent_signing_keys row, which
+-- mint_fleet_agent_session takes in the opposite order -- so this detector named
+-- `agent_signing_key_challenges <-> agent_signing_keys` the first time that migration
+-- was written. The cycle is closed at RUNTIME, by `for update skip locked` on the
+-- eviction's row selection: a transaction that never waits on a challenge row cannot
+-- close a cycle. This detector is a static regex scan and cannot see a SKIP LOCKED, so
+-- it reports the pair and always will.
+--
+-- The clause is therefore pinned TWICE, POSITIVELY, so that deleting it fails a NAMED
+-- assertion rather than merely re-adding a member to a list that already contains it
+-- (which would be silent):
+--   * agent_board_signing_challenge_pending_cap.test.sql asserts the DEPLOYED body
+--     carries it, over stripped_body() so a comment cannot satisfy the match;
+--   * tests/isolation/specs/challenge_supersede_lock_order.spec proves the absence of
+--     the wait across two real sessions -- removing the clause turns its golden from a
+--     clean completion into `<waiting ...>` and then a deadlock.
 -- ===========================================================================
 select is(
   (select array_agg(p order by p) from (
      select distinct least(rel_a, rel_b) || ' <-> ' || greatest(rel_a, rel_b) as p
        from _abba where not both_advisory) z),
   array[
+    'agent_board.agent_signing_key_challenges <-> agent_board.agent_signing_keys',
     'agent_board.agent_signing_keys <-> agent_board.agents',
     'agent_board.agent_signing_keys <-> agent_board.board_memberships',
     'agent_board.agent_signing_keys <-> agent_board.fleet_machine_agents',

package/tests/agent_board_ownerless_quota_census.test.sql

@@ -386,6 +386,12 @@ select is(
 -- membership to exercise it would be testing who may set the policy (BCP's subject) rather than
 -- what the reader does with it. updated_at is set as the RPC sets it, so the row is not a shape
 -- the RPC could never produce.
+--
+-- SINCE #400 THE TWO PATHS DIVERGE IN ONE RESPECT, recorded here rather than left as a silent
+-- premise: the RPC ALSO re-applies the ownerless TTL cap to this board's active ownerless claims on
+-- an advisory -> inherit revert, and a direct UPDATE does not. It changes nothing this assertion
+-- reads — a clamped 30-day lease is still active and still counted — but "the row is not a shape
+-- the RPC could never produce" is now a statement about the BOARD row only.
 update agent_board.boards
    set claim_policy = 'inherit', updated_at = now()
  where id = (select adv_board from _oq);

package/tests/agent_board_ownerless_renew_quota.test.sql

@@ -7,8 +7,16 @@
 -- SCOPED, AND THE SCOPE IS ASSERTED HERE RATHER THAN PROMISED IN PROSE. That convergence holds
 -- against an agent whose boards do not opt out. It does NOT hold against one whose board is flipped
 -- to `claim_policy = 'advisory'` and back, which an owner may do at will and which an agent that
--- created its own board may do to itself. ORQ-11/12 perform that flip-flop and pin both halves: the
--- horizon survives the revert, and the census cannot see that it was taken.
+-- created its own board may do to itself. ORQ-11/12 perform that flip-flop and pin what survives it.
+--
+-- #400 CHANGED WHAT SURVIVES, AND ORQ-11'S CONTRACT WITH IT. When this file shipped, the escape was
+-- UNBOUNDED: the horizon taken during the advisory window survived the revert intact, so one flip
+-- bought as much time as the agent asked for. Reverting to 'inherit' now re-applies the ownerless
+-- TTL cap to that board's active ownerless claims, so a cycle banks at most
+-- `_claimgate_ownerless_ttl_cap()` — what any claim on any inherit board may hold. ORQ-11 asserts
+-- the CLAMP where it used to assert the survival. The escape is BOUNDED, not closed: an owner
+-- flipping before each expiry still keeps an over-quota agent over quota, and ORQ-12 is unchanged
+-- because the census still cannot see that any of it happened.
 --
 -- ORQ-1 IS THE ASSERTION THIS FILE EXISTS FOR, and it is written as the attack #388 describes: an
 -- agent that is already over the ceiling asks for +400 days, which before this migration it got,
@@ -431,6 +439,21 @@ select is(
 -- monotone clamp guarantees convergence against an agent whose boards do not opt out; it guarantees
 -- NOTHING against one whose board owner cooperates, and the flip-flop can be repeated forever.
 --
+-- WHAT #400 TOOK AWAY IS THE HORIZON, NOT THE FLIP. The revert now re-applies the ownerless TTL cap
+-- (BCP-11 owns the mechanics), so ORQ-11b's +400 days does not survive ORQ-11c. ORQ-11 asserts that
+-- clamp. Its contract genuinely CHANGED — it used to assert `now() + 400 days` and now asserts
+-- `now() + _claimgate_ownerless_ttl_cap()` — and the change is legitimate because the BEHAVIOUR
+-- changed underneath it, not because a red test needed to go green: the migration is what makes the
+-- old value impossible, and this assertion is the one #399 deliberately left in place so that
+-- closing the escape could not be done in prose.
+--
+-- IT IS STILL AN ESCAPE, AND THIS ASSERTION STILL DOCUMENTS ONE. Each cycle banks up to the cap, so
+-- an owner flipping every 29 days keeps an over-quota agent over quota indefinitely; convergence is
+-- still defeatable by a board owner, just no longer by a single flip. To hold MORE than the cap the
+-- board must STAY advisory — and while it does, those claims are counted by the census's
+-- claims_on_advisory_boards, which is the column an operator reads. Above the cap the escape is
+-- ineffective or visible; below it, ORQ-12 still applies.
+--
 -- AND THE AGENT CAN BE ITS OWN OWNER, which is why the fixture builds this board through
 -- create_board rather than inserting it. create_board seeds the creator's owner membership and
 -- set_board_claim_policy is gated on exactly that, so no accomplice is required — an agent that
@@ -459,11 +482,12 @@ select lives_ok(
 
 select is(
   (select lease_expires_at from agent_board.claims where lease_token = (select tok from _tok where name = 'over-escape')),
-  now() + interval '400 days',
-  'ORQ-11 THE ESCAPE HATCH: reverting to inherit does NOT take the horizon back — the +400 day lease survives the revert, so an owner who flips advisory/inherit before each expiry keeps an over-quota agent over quota forever. Convergence is guaranteed only against an agent whose boards do not opt out');
+  now() + agent_board._claimgate_ownerless_ttl_cap(),
+  'ORQ-11 THE ESCAPE HATCH, BOUNDED (#400): reverting to inherit TAKES THE HORIZON BACK to the ownerless TTL cap — the +400 day lease does not survive the revert, so a flip-flop banks at most what any claim on any inherit board may hold. Still an escape (the owner may flip again before that expiry), no longer an unbounded one');
 
--- The second half, kept HERE rather than in the census file. The escape and its invisibility are
--- one defect: the census resolves board policy at QUERY time (OQ-29's subject), so once the board
+-- The second half, kept HERE rather than in the census file, and UNCHANGED by #400 — which is the
+-- point of keeping it. Bounding the horizon did nothing about the visibility: the escape and its
+-- invisibility are one defect: the census resolves board policy at QUERY time (OQ-29's subject), so once the board
 -- is back to 'inherit' this claim contributes ZERO to claims_on_advisory_boards while the overage
 -- it produced is still counted. An operator reading the census sees an agent over quota with no
 -- advisory share — the exact shape that says "this one is a squatter, act on it" — and the column
@@ -499,14 +523,19 @@ select is(
 -- text asserts "acquire_claim/renew_claim are the only SQL writers" — a recorded fact, which rule 5
 -- says is a claim about the moment it was written. Derived here instead, so a third writer that
 -- needs this guard fails a test and NAMES ITSELF rather than relying on someone remembering.
+--
+-- IT DID, one release later. #400's cap reset is exactly the third writer this assertion was built
+-- to catch, and it turned this test red before anyone wrote it down. The expected set is widened
+-- deliberately: the reset writes leases, only ever SHORTENING them to the ownerless TTL cap, and the
+-- mechanics are pinned in agent_board_board_claim_policy.test.sql (BCP-11..20).
 -- ---------------------------------------------------------------------------
 select is(
   (select 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 agent_board_test.stripped_body(p.oid, true) ~ '(lease_expires_at\s*=[^=]|insert into agent_board\.claims\s*\([^)]*lease_expires_at)'),
-  'acquire_claim, renew_claim',
-  'ORQ-14 CLASS: acquire_claim and renew_claim are the ONLY functions that write a claim lease — a new one names itself here instead of quietly inheriting an unconverged renewal path');
+  'acquire_claim, renew_claim, set_board_claim_policy',
+  'ORQ-14 CLASS: acquire_claim, renew_claim and (since #400) set_board_claim_policy''s advisory-revert cap reset are the ONLY functions that write a claim lease — a new one names itself here instead of quietly inheriting an unconverged renewal path');
 
 -- ---------------------------------------------------------------------------
 -- ORQ-15/14: CLASS, one definition of the count. Three hand-copies of a predicate across two

package/tests/agent_board_signing_challenge_pending_cap.test.sql

@@ -1,23 +1,71 @@
--- MBHARDEN SL-1 pgTAP: issue_signing_key_challenge enforces a per-key cap of
--- N=16 concurrently-pending challenges; <=16 issue as before, the 17th is
--- rejected, and expired/consumed challenges do not count toward the cap.
+-- issue_signing_key_challenge bounds a key to N=16 concurrently-pending challenges,
+-- and AT the bound it supersedes the oldest pending challenge instead of refusing.
+--
+-- WHY THIS FILE CHANGED SHAPE (F1, code-review-2026-09-01). It used to assert that the
+-- 17th pending challenge was REJECTED. That rejection was the defect: /session step
+-- "challenge" is verify_jwt=false and needs only a directory-visible handle and key id,
+-- so sixteen requests denied a key every further challenge, and the client stopped its
+-- refresh loop on the resulting 403. The bound is unchanged and still asserted; what is
+-- asserted now is that arrival is never refused.
+--
+-- It also stopped standing on `select pass(...)`. Three of this file's four assertions
+-- were unconditional passes placed after a DO block that raised on failure — an ok line
+-- that says nothing about what it ran beside, and the exact construct review finding F51
+-- names. Every assertion below reads state back out of the table.
+--
+-- WHY EVERY `DO` BLOCK HERE TRAPS INSTEAD OF RAISING, which is the part that is easy to
+-- undo. Rewriting the passes into real assertions is only half the job, and the half that
+-- is visible. The other half was found by MUTATING: reverting the supersede so the RPC
+-- raises `challenge_pending_cap` again made this file report NOTHING. A bare call to a
+-- raising RPC inside a `DO` block aborts the whole transaction, so pgTAP printed `1..18`,
+-- then `ok 1`, `ok 2`, `ok 3`, then twenty lines of `current transaction is aborted` — and
+-- ZERO `not ok`. Three of eighteen assertions ran and nothing said so. That is AGENTS.md
+-- rule 3 exactly, and it is worse than it sounds: the shipped code path never raises, so
+-- this only appears when someone mutates, and a `grep not ok` over the failing run comes
+-- back clean.
+--
+-- So every block that calls the RPC wraps it in `begin … exception when others then …`
+-- and records the OUTCOME (an id, or `sqlerrm`) into the `pcap_state` temp table, which a
+-- named assertion then checks. A raise becomes a value, not an abort. With the trap in
+-- place the same mutation emits 20 of 20 with a named `not ok`, the first being #4.
+--
+-- "Every block" is now literally true, and was not when first written: the SEED loop below
+-- called the RPC sixteen times bare. It happens not to raise under either mutation this
+-- file is cited for (sixteen issues are UNDER the cap), so nothing caught it — which is
+-- the point. A block that cannot raise TODAY is one cap constant away from being the block
+-- that silently stops the file, and "every" in a comment is a claim, not a description.
+--
+-- Two smaller traps in the same family, both of which abort identically and both of which
+-- cost a debugging round here:
+--   * `v_c := null` on a plpgsql `record` raises `record "v_c" is not assigned yet` — the
+--     exception HANDLER was aborting the transaction. Use a scalar (`v_id uuid`).
+--   * Writing `pcap_state` while still under `set local role service_role` raises
+--     `permission denied for table pcap_state`: the temp table belongs to the session
+--     user. Every temp-table write below therefore happens after `reset role`.
+--
+-- If you add a probe here that can raise, trap it. An untrapped one does not fail loudly;
+-- it silently stops the file.
 create extension if not exists pgtap with schema extensions;
 set search_path = extensions, public, agent_board;
 
 begin;
 
-select plan(4);
+select plan(20);
 
 select has_function(
   'agent_board', 'issue_signing_key_challenge', array['uuid', 'text', 'interval'],
   'issue_signing_key_challenge exists');
+select has_function(
+  'agent_board', 'mint_fleet_agent_session', array['uuid', 'text', 'uuid', 'uuid', 'integer'],
+  'mint_fleet_agent_session exists');
 
--- Block 1: 16 pending challenges are allowed; the 17th is rejected by the cap.
+-- Seed one agent + key, then fill the key's sixteen pending slots.
 do $$
 declare
   v_agent uuid := '00000000-0000-0000-0000-0000000000c1';
   v_i int;
   v_c record;
+  v_ids uuid[] := '{}';
 begin
   insert into agent_board.agents(id, agent_type, handle, display_name)
   values (v_agent, 'agent', 'pcap-agent', 'PCAP Agent');
@@ -27,60 +75,367 @@ begin
     v_agent, 'primary', 1, public.test_pubkey('pcap-primary'), 'raw_ed25519_base64url',
     public.test_key_fingerprint('pcap-primary'));
 
+  -- Issue as service_role, then RESET before back-dating: service_role holds SELECT
+  -- only on agent_signing_key_challenges, so the UPDATE must run as the owner.
+  -- created_at is set explicitly rather than relying on clock order, because every
+  -- row in one statement-less loop can share a now().
   set local role service_role;
-
   for v_i in 1..16 loop
-    select * into v_c
-      from agent_board.issue_signing_key_challenge(v_agent, 'primary', interval '5 minutes');
-    if v_c.challenge_id is null then
-      raise exception 'pending challenge % was not issued below the cap', v_i;
-    end if;
+    -- Trapped like every other call site here. These sixteen are below the cap and do not
+    -- raise today; if a change makes one raise, this leaves v_ids short and assertion 3
+    -- fails BY NAME instead of the raise aborting the transaction and emitting nothing.
+    begin
+      select * into v_c
+        from agent_board.issue_signing_key_challenge(v_agent, 'primary', interval '5 minutes');
+      v_ids := array_append(v_ids, v_c.challenge_id);
+    exception when others then
+      exit;
+    end;
   end loop;
+  reset role;
+
+  for v_i in 1..coalesce(array_length(v_ids, 1), 0) loop
+    update agent_board.agent_signing_key_challenges
+       set created_at = now() - make_interval(secs => (17 - v_i))
+     where id = v_ids[v_i];
+  end loop;
+end
+$$;
+reset role;
+
+-- 1. The bound is reached, and every one of the sixteen is genuinely pending.
+select is(
+  (select count(*)::int from agent_board.agent_signing_key_challenges
+    where agent_id = '00000000-0000-0000-0000-0000000000c1'
+      and proof_state = 'pending' and consumed_at is null and expires_at > now()),
+  16,
+  'sixteen challenges issue below the cap and are all pending');
+
+-- Remember which row is the oldest before the 17th arrives.
+create temporary table pcap_state as
+select (select id from agent_board.agent_signing_key_challenges
+         where agent_id = '00000000-0000-0000-0000-0000000000c1'
+           and proof_state = 'pending' and consumed_at is null
+         order by created_at, id limit 1) as oldest_id,
+       null::uuid as seventeenth_id,
+       null::uuid as next_oldest_id,
+       null::uuid as victim_id,
+       null::text as lapse_note;
+
+-- 2. The 17th request is SERVED, not refused. This is the assertion that inverts.
+do $$
+declare
+  v_agent uuid := '00000000-0000-0000-0000-0000000000c1';
+  v_id uuid;
+begin
+  set local role service_role;
+  begin
+    select c.challenge_id into v_id
+      from agent_board.issue_signing_key_challenge(v_agent, 'primary', interval '5 minutes') c;
+  exception when others then
+    -- Trapped, never re-raised: a bare call to a raising RPC aborts the whole
+    -- transaction, and pgTAP then emits NO `not ok` -- only a short assertion count
+    -- (AGENTS.md rule 3). Leaving the id null makes the assertion below fail BY NAME.
+    v_id := null;
+  end;
+  reset role;
+  update pcap_state set seventeenth_id = v_id;
+end
+$$;
+reset role;
+
+select isnt(
+  (select seventeenth_id from pcap_state), null,
+  'the 17th request at the cap is served, not refused (challenge_pending_cap is not raised)');
+
+-- 3. The resource bound the cap exists for is still held.
+select is(
+  (select count(*)::int from agent_board.agent_signing_key_challenges
+    where agent_id = '00000000-0000-0000-0000-0000000000c1'
+      and proof_state = 'pending' and consumed_at is null and expires_at > now()),
+  16,
+  'the per-key pending bound is still 16 after the 17th issues');
+
+-- 4-7. The evicted row is the OLDEST one, closed out in the shape the
+-- consumed-shape CHECK requires, and it names what superseded it.
+select is(
+  (select proof_state from agent_board.agent_signing_key_challenges
+    where id = (select oldest_id from pcap_state)),
+  'expired',
+  'the oldest pending challenge is closed out as expired');
+select ok(
+  (select consumed_at is not null from agent_board.agent_signing_key_challenges
+    where id = (select oldest_id from pcap_state)),
+  'the superseded row carries consumed_at (agent_signing_key_challenges_consumed_shape)');
+-- `ok(a = b)`, NOT `is(a, b)`. pgTAP's `is` is IS NOT DISTINCT FROM, so under the
+-- revert-supersede mutation — where nothing is evicted and nothing is issued, leaving
+-- BOTH sides null — `is(null, null)` PASSES. This assertion was cited in the PR as one of
+-- the nine that mutation fails, and it was in fact vacuous there: a probe that scores
+-- 0-vs-0 and reads as agreement. `=` yields NULL when either side is null, and pgTAP
+-- fails a NULL result, so the null case now reads `not ok`.
+select ok(
+  (select (metadata->>'superseded_by')::uuid from agent_board.agent_signing_key_challenges
+    where id = (select oldest_id from pcap_state))
+    = (select seventeenth_id from pcap_state),
+  'the superseded row names the challenge that superseded it');
+select is(
+  (select count(*)::int from agent_board.agent_signing_key_challenges
+    where agent_id = '00000000-0000-0000-0000-0000000000c1'
+      and metadata ? 'superseded_by'),
+  1,
+  'exactly one row was evicted -- the oldest, and only the oldest');
 
+-- 8. A second request at the cap takes the NEXT-oldest, not the same row twice and
+-- not an arbitrary one.
+do $$
+declare
+  v_next uuid;
+  v_agent uuid := '00000000-0000-0000-0000-0000000000c1';
+begin
+  select id into v_next from agent_board.agent_signing_key_challenges
+   where agent_id = v_agent and proof_state = 'pending' and consumed_at is null
+   order by created_at, id limit 1;
+  update pcap_state set next_oldest_id = v_next;
+  set local role service_role;
   begin
-    perform *
-      from agent_board.issue_signing_key_challenge(v_agent, 'primary', interval '5 minutes');
-    raise exception 'the 17th pending challenge was NOT rejected by the cap';
-  exception
-    when others then
-      if sqlerrm !~ 'challenge_pending_cap' then
-        raise;
-      end if;
+    perform * from agent_board.issue_signing_key_challenge(v_agent, 'primary', interval '5 minutes');
+  exception when others then
+    null;
   end;
+  reset role;
 end
 $$;
 reset role;
 
-select pass('16 pending challenges issue below the cap');
-select pass('the 17th concurrently-pending challenge is rejected (challenge_pending_cap)');
+select is(
+  (select proof_state from agent_board.agent_signing_key_challenges
+    where id = (select next_oldest_id from pcap_state)),
+  'expired',
+  'a second request at the cap evicts the NEXT-oldest row, not the same one twice');
+select is(
+  (select count(*)::int from agent_board.agent_signing_key_challenges
+    where agent_id = '00000000-0000-0000-0000-0000000000c1'
+      and metadata ? 'superseded_by'),
+  2,
+  'a second request at the cap evicts one row, not several');
+
+-- 9-10. An eviction is reported as an eviction, NOT as a replay. A client may retry
+-- challenge_superseded; it must never learn to retry nonce_replay, so the two must not
+-- share a message.
+select throws_matching(
+  $q$ select agent_board.mint_fleet_agent_session(
+        (select oldest_id from pcap_state),
+        (select challenge_nonce from agent_board.agent_signing_key_challenges
+          where id = (select oldest_id from pcap_state)),
+        (select id from agent_board.agent_signing_keys
+          where agent_id = '00000000-0000-0000-0000-0000000000c1'),
+        '00000000-0000-0000-0000-0000000000c1'::uuid,
+        900) $q$,
+  'challenge_superseded',
+  'minting a superseded challenge raises challenge_superseded');
+
+-- A genuinely CONSUMED challenge still raises nonce_replay: the new branch narrowed
+-- nothing. Consume one of the still-pending rows by hand and mint it.
+update agent_board.agent_signing_key_challenges
+   set proof_state = 'consumed', consumed_at = now()
+ where id = (select id from agent_board.agent_signing_key_challenges
+              where agent_id = '00000000-0000-0000-0000-0000000000c1'
+                and proof_state = 'pending' and consumed_at is null
+              order by created_at desc, id limit 1);
+
+select throws_matching(
+  $q$ select agent_board.mint_fleet_agent_session(
+        (select id from agent_board.agent_signing_key_challenges
+          where agent_id = '00000000-0000-0000-0000-0000000000c1'
+            and proof_state = 'consumed' and not (metadata ? 'superseded_by')
+          order by consumed_at desc limit 1),
+        (select challenge_nonce from agent_board.agent_signing_key_challenges
+          where agent_id = '00000000-0000-0000-0000-0000000000c1'
+            and proof_state = 'consumed' and not (metadata ? 'superseded_by')
+          order by consumed_at desc limit 1),
+        (select id from agent_board.agent_signing_keys
+          where agent_id = '00000000-0000-0000-0000-0000000000c1'),
+        '00000000-0000-0000-0000-0000000000c1'::uuid,
+        900) $q$,
+  'nonce_replay',
+  'a genuinely consumed challenge still raises nonce_replay, not challenge_superseded');
 
--- Expire one pending challenge (as owner), then a new challenge succeeds: expired
--- rows do not count toward the cap.
+-- 11-12. An EXPIRED-by-lapse pending row frees a slot without being evicted: expiry
+-- and eviction remain different things, and expiry still costs no one their challenge.
 update agent_board.agent_signing_key_challenges
    set expires_at = now() - interval '1 minute'
- where id = (
-   select id from agent_board.agent_signing_key_challenges
-    where agent_id = '00000000-0000-0000-0000-0000000000c1'
-      and proof_state = 'pending'
-    order by created_at
-    limit 1);
+ where id = (select id from agent_board.agent_signing_key_challenges
+              where agent_id = '00000000-0000-0000-0000-0000000000c1'
+                and proof_state = 'pending' and consumed_at is null
+              order by created_at desc, id limit 1);
 
 do $$
 declare
   v_agent uuid := '00000000-0000-0000-0000-0000000000c1';
-  v_c record;
+  v_note text;
+begin
+  set local role service_role;
+  begin
+    perform * from agent_board.issue_signing_key_challenge(v_agent, 'primary', interval '5 minutes');
+    v_note := 'issued';
+  exception when others then
+    v_note := sqlerrm;
+  end;
+  -- The pcap_state write happens as the OWNER: service_role has no privilege on a
+  -- temp table created by the session user, and a permission error here would abort
+  -- the transaction exactly as an untrapped raise would.
+  reset role;
+  update pcap_state set lapse_note = v_note;
+end
+$$;
+reset role;
+
+select is(
+  (select lapse_note from pcap_state), 'issued',
+  'a lapsed pending row frees a slot, so the next request issues rather than raising');
+
+select is(
+  (select count(*)::int from agent_board.agent_signing_key_challenges
+    where agent_id = '00000000-0000-0000-0000-0000000000c1'
+      and metadata ? 'superseded_by'),
+  2,
+  'a lapsed pending row frees a slot with NO eviction (still 2 superseded)');
+select is(
+  (select count(*)::int from agent_board.agent_signing_key_challenges
+    where agent_id = '00000000-0000-0000-0000-0000000000c1'
+      and proof_state = 'pending' and consumed_at is null and expires_at > now()),
+  15,
+  'the pending set never exceeds the bound across evictions and lapses');
+
+-- 13. The grant surface is unchanged by the create-or-replace.
+select is(
+  (select array_agg(g order by g)
+     from unnest(array['anon', 'authenticated', 'service_role']) g
+    where has_function_privilege(
+      g, 'agent_board.issue_signing_key_challenge(uuid,text,interval)', 'execute')),
+  array['authenticated', 'service_role'],
+  'issue_signing_key_challenge stays authenticated + service_role, never anon');
+
+-- 14. THE DEADLOCK-FREEDOM CLAUSE, pinned positively.
+--
+-- The eviction writes agent_signing_key_challenges while this function holds the
+-- agent_signing_keys row; mint_fleet_agent_session takes that pair in the opposite
+-- order (challenge row FOR UPDATE at 20260718000600:73-76, key row FOR UPDATE at
+-- :95-100). `for update skip locked` is what keeps that from being a live ABBA:
+-- an issuer that never waits on a challenge row cannot close the cycle.
+--
+-- agent_board_fk_lock_edges.test.sql FKL-10 reports the PAIR (its detector is a
+-- static scan and cannot see a SKIP LOCKED, so the pair is listed there as known),
+-- which means removing this clause would fail NOTHING there. This is the named
+-- assertion that removing it fails. Read over stripped_body(), which removes
+-- comments and literals in one pass, so the prose above cannot satisfy the match --
+-- a comment satisfying a body scan is how a prior class assertion in this repo went
+-- green over an inverted lock.
+--
+-- A source scan has a floor, and this one is bounded rather than trusted: the
+-- BEHAVIOUR (an issuer skipping a mint-held row instead of waiting) is proved across
+-- two real sessions by tests/isolation/specs/challenge_supersede_lock_order.spec.
+-- Neither check covers the other -- a scan cannot observe a wait, and the golden
+-- cannot tell you which function the clause is missing from.
+select matches(
+  (select agent_board_test.stripped_body(
+            'agent_board.issue_signing_key_challenge(uuid,text,interval)'::regprocedure)),
+  'for\s+update\s+skip\s+locked',
+  'the eviction selects its victim FOR UPDATE SKIP LOCKED (no wait => no ABBA with mint_fleet_agent_session)');
+
+-- 19-20. THE RESIDUAL, PINNED RATHER THAN LEFT IN PROSE.
+--
+-- What this change closes is the HOLDABLE lockout: filling a key's sixteen slots and
+-- walking away no longer denies anything, because arrival is never refused. What it does
+-- NOT close is eviction under a SUSTAINED flood. A challenge issued now is the NEWEST, so
+-- it survives fifteen further issues and is evicted by the sixteenth -- and there is no
+-- per-key aggregate bound on how fast those sixteen arrive, because a per-key aggregate
+-- bound is exactly the holdable lever this change removed. Per source it is bounded by the
+-- `session:` rate cap; across N sources the sixteen land in 1/N of that time.
+--
+-- So a minter whose issue->mint gap exceeds the flood's rotation period loses its
+-- challenge, for as long as the flood runs. That is DoS-class -- it costs the attacker
+-- continuous traffic and stores nothing -- and it is a real residual, recorded here as an
+-- assertion instead of a sentence because a sentence is not re-checked (rule 5).
+--
+-- NOT A DUPLICATE OF #12. That one mints a row which was ALREADY the oldest of sixteen and
+-- was evicted by ONE further issue. This one starts from a challenge that is the NEWEST of
+-- its key and shows the whole queue rotating past it -- the property under discussion is
+-- that a LIVE minter can be rotated out, which #12's setup cannot exhibit.
+--
+-- The count is load-bearing and was measured, not assumed: with fifteen further issues
+-- both assertions below FAIL (the victim survives). Sixteen is the number.
+do $$
+declare
+  v_agent uuid := '00000000-0000-0000-0000-0000000000c2';
+  v_victim uuid;
+  v_i int;
 begin
+  insert into agent_board.agents(id, agent_type, handle, display_name)
+  values (v_agent, 'agent', 'pcap-victim', 'PCAP Victim');
+  -- active + proven deliberately: mint checks the key AFTER the superseded branch, so an
+  -- inactive key would let assertion 20 pass on `key_revoked` instead of on the property.
+  insert into agent_board.agent_signing_keys(
+    agent_id, key_id, key_version, public_key, public_key_format, fingerprint, status, proof_state)
+  values (
+    v_agent, 'primary', 1, public.test_pubkey('pcap-victim'), 'raw_ed25519_base64url',
+    public.test_key_fingerprint('pcap-victim'), 'active', 'proven');
+
   set local role service_role;
-  select * into v_c
-    from agent_board.issue_signing_key_challenge(v_agent, 'primary', interval '5 minutes');
-  if v_c.challenge_id is null then
-    raise exception 'a new challenge was rejected even though an expired row freed a slot';
-  end if;
+  -- The victim obtains a challenge, exactly as a legitimate agent would.
+  begin
+    select c.challenge_id into v_victim
+      from agent_board.issue_signing_key_challenge(v_agent, 'primary', interval '5 minutes') c;
+  exception when others then
+    v_victim := null;   -- trapped: an untrapped raise kills the file (see the header)
+  end;
+  reset role;
+
+  -- Back-date the victim so "oldest" is unambiguous. `now()` is TRANSACTION start time, so
+  -- every row this pgTAP transaction inserts shares one created_at and the eviction's
+  -- `order by created_at, id` degenerates to uuid order -- which made the first version of
+  -- this block evict a random row and fail for a reason that had nothing to do with the
+  -- property. In production each issue is its own transaction and now() advances, so this
+  -- back-date restores the real ordering rather than inventing one. Owner-only UPDATE,
+  -- hence the reset above.
+  update agent_board.agent_signing_key_challenges
+     set created_at = now() - interval '1 hour'
+   where id = v_victim;
+
+  set local role service_role;
+  -- Sixteen further issues for the SAME key. The 16th finds the set full and evicts the
+  -- oldest, which by then is the victim's.
+  for v_i in 1..16 loop
+    begin
+      perform * from agent_board.issue_signing_key_challenge(v_agent, 'primary', interval '5 minutes');
+    exception when others then
+      null;
+    end;
+  end loop;
+  reset role;
+
+  update pcap_state set victim_id = v_victim;
 end
 $$;
 reset role;
 
-select pass('an expired pending challenge frees a slot under the cap');
+select is(
+  (select proof_state from agent_board.agent_signing_key_challenges
+    where id = (select victim_id from pcap_state)),
+  'expired',
+  'RESIDUAL: a live challenge is rotated out by sixteen later issues for the same key');
+
+select throws_matching(
+  $q$ select agent_board.mint_fleet_agent_session(
+        (select victim_id from pcap_state),
+        (select challenge_nonce from agent_board.agent_signing_key_challenges
+          where id = (select victim_id from pcap_state)),
+        (select id from agent_board.agent_signing_keys
+          where agent_id = '00000000-0000-0000-0000-0000000000c2'),
+        '00000000-0000-0000-0000-0000000000c2'::uuid,
+        900) $q$,
+  'challenge_superseded',
+  'RESIDUAL: that victim''s mint then fails -- a sustained flood evicts a slow minter (DoS-class, retryable, not a stored lockout)');
 
 select finish();
 

package/tests/catalog/p_metadata_parameters.json

@@ -73,10 +73,22 @@
       "signature": "_claimgate_board_claim_policy(p_thread_id uuid)",
       "declares_p_metadata": false
     },
+    {
+      "signature": "_claimgate_board_claim_policy_of(p_board_id uuid)",
+      "declares_p_metadata": false
+    },
+    {
+      "signature": "_claimgate_board_of_thread(p_thread_id uuid)",
+      "declares_p_metadata": false
+    },
     {
       "signature": "_claimgate_kind_enforced(p_resource_kind text)",
       "declares_p_metadata": false
     },
+    {
+      "signature": "_claimgate_lock_board_policy(p_board_id uuid)",
+      "declares_p_metadata": false
+    },
     {
       "signature": "_claimgate_max_lease_horizon()",
       "declares_p_metadata": false
@@ -85,6 +97,10 @@
       "signature": "_claimgate_ownerless_guards_enabled()",
       "declares_p_metadata": false
     },
+    {
+      "signature": "_claimgate_ownerless_kinds()",
+      "declares_p_metadata": false
+    },
     {
       "signature": "_claimgate_ownerless_quota()",
       "declares_p_metadata": false