@consiliency/agent-board-schema 1.48.0 → 1.50.0

package/migrations/20261001000100_agent_board_claimpolicy_lock_grant_revoke.sql

@@ -0,0 +1,158 @@
+-- Consiliency/message-board#405 — the board policy lock helper is granted to NOBODY.
+--
+-- WHAT THIS CLOSES, measured rather than argued. 20260930000100 revoked
+-- `_claimgate_lock_board_policy` from public/anon/authenticated and GRANTED it to `service_role`,
+-- on the reasoning (stated in its own comment) that the serialisation "cannot be reached from a
+-- session". `service_role` IS a session role. With that grant in place a single service_role
+-- transaction assembles the exact inversion claimpolicy_claimrow_lock_order.spec constructs by
+-- hand:
+--
+--   BEGIN;  select agent_board.renew_claim(<token>, …);      -- claims ROW LOCK, no board lock
+--           select agent_board._claimgate_lock_board_policy(<board>);   -- board lock, AFTER it
+--
+-- and a concurrent `set_board_claim_policy` on that board (board lock, then #400's cap-reset
+-- UPDATE onto the row session 1 holds) closes the cycle. Reproduced against this bundle as
+-- `ERROR: deadlock detected` before this migration existed.
+--
+-- WHY renew_claim STILL TAKES THE ROW LOCK FOR service_role, which is the part that makes the
+-- composition work: its `update agent_board.claims` sits OUTSIDE the ownerless block, so
+-- `_is_service_role()` short-circuits the BOARD lock while the ROW lock is taken regardless. The
+-- caller therefore holds a claims row lock and no board lock — precisely the state the inversion
+-- needs — and only needs one more granted call to want the board lock.
+--
+-- WHY REVOKING IS SAFE, derived from the catalog rather than assumed. The helper is NOT
+-- `SECURITY DEFINER`; its three callers (`acquire_claim`, `renew_claim`, `set_board_claim_policy`)
+-- ARE, and are owned by the same role that owns the helper. A SECURITY DEFINER function executes
+-- as its owner, and an owner needs no grant on its own function, so the definer path is unaffected
+-- by any grant at all. CPR-22 asserts the empty ACL; CPR-22a asserts the definer path still
+-- reaches the lock AND that the advisory lock is genuinely held afterwards, so the negative cannot
+-- pass by the enforcement having been taken offline.
+--
+-- NOTHING CALLS IT DIRECTLY. Derived from the tree on this branch, not from a live database: the
+-- only references to `_claimgate_lock_board_policy` outside its defining migration are in this
+-- package's pgTAP file, the isolation-spec COMMENTS, and the p_metadata catalog snapshot. No
+-- TypeScript package (client/cli/mcp/runtime) and no Edge Function names it, in any casing.
+--
+-- WHY A NEW MIGRATION RATHER THAN EDITING 20260930000100's GRANT LINE. That migration is this
+-- PR's own and still unmerged, so amending it would be tidier history — but this repository cannot
+-- prove that no database has already applied it (the canary project tracks this branch), and a
+-- bundle is replayed by digest rather than re-derived. A forward revoke is correct whether or not
+-- the grant was ever applied, and `revoke` on an absent grant is a no-op. Replay-safe either way.
+--
+-- NOT `DROP FUNCTION`: that would discard the ACL *and* the COMMENT and re-grant EXECUTE to PUBLIC
+-- by default (AGENTS.md, "Schema-change mechanics that bite"). The function body is unchanged here;
+-- only its ACL and its comment move.
+
+-- THE REVOKE IS DERIVED, ACROSS EVERY OVERLOAD, AND CASCADES. Three separate holes closed here,
+-- each of which would leave this migration's own comment asserting something false:
+--
+-- 1. NAMED ROLES ARE A HAND LIST. `revoke ... from public, anon, authenticated, service_role`
+--    leaves a grant to any fifth role standing. That is not hypothetical bookkeeping — this bundle
+--    is REPLAYED ONTO ADOPTER DATABASES we do not control, where an operator may have granted this
+--    helper to a role we have never heard of.
+--
+-- 2. ONE SIGNATURE IS A HAND LIST TOO. Keying the sweep to `(uuid)` lets a `(text)` overload carry
+--    a grant straight through it. The property wanted is about the NAME: nothing in agent_board
+--    called _claimgate_lock_board_policy should be executable by a non-owner, whatever its
+--    argument types. Every overload is swept.
+--
+-- 3. `REVOKE` DEFAULTS TO `RESTRICT`, AND RESTRICT FAILS ON A DEPENDENT GRANT. If a grantee holds
+--    EXECUTE **WITH GRANT OPTION** and has granted it onward, a plain REVOKE ERRORS ("dependent
+--    privileges exist") — and on an adopter database that is a FAILED MIGRATION, not a tidier ACL,
+--    with the empty ACL not achieved either. `CASCADE` is chosen deliberately over enumerating
+--    dependencies: the whole claim of this migration is that NOTHING non-owner holds EXECUTE, so a
+--    downstream grant is exactly as unwanted as the grant it hangs from, and handling dependencies
+--    individually would only reach the same end state by a longer route. Stated rather than
+--    slipped in, because CASCADE silently removes grants a third party made: an operator who
+--    deliberately delegated this helper onward will find that delegation gone after upgrading.
+--    That is the intended outcome — the helper is not meant to be reachable from any session — but
+--    it is a real effect on someone else's database and belongs in the record.
+--
+-- 4. `ON FUNCTION` IS THE WRONG VERB FOR A ROUTINE, AND RAISES. The scan above selects by NAME,
+--    which admits any pg_proc row — a legal same-name PROCEDURE or AGGREGATE included. `REVOKE …
+--    ON FUNCTION` against a procedure fails with `is not a function`, and it would fail at the
+--    MATERIALISATION statement, before the sweep runs at all: a second adopter-upgrade abort from
+--    the same source as the RESTRICT one, a query written for functions applied to routines.
+--    Measured on this bundle: `on function` against a procedure errors, `on routine` succeeds
+--    against a procedure AND an aggregate. So both statements say ROUTINE and there is no prokind
+--    filter — operating on routines consistently is the choice, rather than narrowing the scan to
+--    prokind='f' and leaving a same-name procedure's grant standing. Window functions ('w') cannot
+--    be created without C-level support and are untested here; ROUTINE is the widest verb available
+--    and no narrower verb would cover more.
+--
+-- The OWNER is excluded throughout: EXECUTE is implicit in ownership, cannot be revoked, and is
+-- exactly the path the three SECURITY DEFINER callers use.
+--
+-- A missing function RAISES rather than silently sweeping nothing: this migration exists to
+-- establish an ACL, and doing that to a function that is not there is a failure, not a success.
+-- Likewise an unresolvable grantee OID. Both differ from CPR-22, which RENDERS those cases instead
+-- — a raise inside a pgTAP assertion aborts the file and emits no `not ok`, whereas here failing
+-- closed is right, because skipping silently would leave a live grant standing.
+do $$
+declare
+  v_overloads int := 0;
+  v_who       text;
+  f           record;
+  r           record;
+begin
+  for f in
+    select p.oid, p.oid::regprocedure::text as sig
+      from pg_proc p join pg_namespace n on n.oid = p.pronamespace
+     where n.nspname = 'agent_board'
+       and p.proname = '_claimgate_lock_board_policy'
+  loop
+    v_overloads := v_overloads + 1;
+
+    -- MATERIALISE THE ACL FIRST. While `proacl` is NULL the function carries DEFAULT privileges,
+    -- and the default for a function is EXECUTE to PUBLIC — but aclexplode(NULL) yields no rows,
+    -- so the sweep below would find nothing to revoke on a database where no grant was ever
+    -- written explicitly. This statement both removes that implicit PUBLIC grant and populates
+    -- proacl so the sweep can see the rest.
+    execute format('revoke all on routine %s from public cascade', f.sig);
+
+    for r in
+      select distinct a.grantee
+        from pg_proc p, aclexplode(p.proacl) a
+       where p.oid = f.oid
+         and a.privilege_type = 'EXECUTE'
+         and a.grantee <> p.proowner
+    loop
+      if r.grantee = 0 then
+        v_who := 'public';
+      else
+        select quote_ident(rolname) into v_who from pg_roles where oid = r.grantee;
+      end if;
+      if v_who is null then
+        raise exception
+          'EXECUTE grantee % on % has no pg_roles row — cannot revoke it, and reporting an empty ACL would be false',
+          r.grantee, f.sig
+          using errcode = '42704';
+      end if;
+      execute format('revoke all on routine %s from %s cascade', f.sig, v_who);
+    end loop;
+  end loop;
+
+  if v_overloads = 0 then
+    raise exception
+      'no function named agent_board._claimgate_lock_board_policy — refusing to report an empty ACL for a function that does not exist'
+      using errcode = '42883';
+  end if;
+end $$;
+
+-- The comment 20260930000100 attached asserts the service_role grant this migration removes, and
+-- cites CPR-14 for the ACL — CPR-14 is the claims row-lock class assertion; CPR-22 is the ACL one.
+-- Both corrected here, in the same migration that makes the first sentence true.
+comment on function agent_board._claimgate_lock_board_policy(uuid) is
+  '#405: the board-scoped serialisation point for claim policy. Takes a pg_advisory_xact_lock on '
+  'hashtextextended(''agent_board.board_claim_policy:''||board_id) so set_board_claim_policy''s '
+  'flip and every ownerless enforcement decision on that board are totally ordered, and RAISES '
+  '0A000 unless transaction_isolation is ''read committed'' — under repeatable read or '
+  'serializable the wait does not advance the caller''s snapshot, so the lock would be silently '
+  'ineffective; under read uncommitted the lock still works (PostgreSQL runs it as read '
+  'committed) and the refusal is a deliberate one-accepted-spelling contract rather than a '
+  'correctness requirement. A null board is isolation-checked and takes no lock. '
+  'EXECUTE is granted to NO role (#405 follow-up): the helper is not SECURITY DEFINER, its three '
+  'callers are and share its owner, so they reach it by ownership. The grant that existed briefly '
+  'let a service_role session compose renew_claim''s claims row lock with a direct call to this '
+  'helper and deadlock against the policy writer. CPR-22 pins the empty ACL; CPR-22a pins that '
+  'the definer path still works.';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@consiliency/agent-board-schema",
-  "version": "1.48.0",
+  "version": "1.50.0",
   "description": "Canonical, immutable, exact-pinnable agent_board schema bundle: ordered SQL migrations, digest + compatibility manifest, and deterministic materialize/plan/check tooling for adopters.",
   "repository": "https://github.com/Consiliency/message-board.git",
   "type": "module",

package/schema-manifest.json

@@ -2,7 +2,7 @@
   "schema": "agent_board_schema_manifest.v1",
   "interface": "IF-0-MBPLANE-BUNDLE-1",
   "package": "@consiliency/agent-board-schema",
-  "packageVersion": "1.48.0",
+  "packageVersion": "1.50.0",
   "schemaVersion": 8,
   "minClientVersion": "1.1.0",
   "source": {
@@ -46,8 +46,8 @@
       "usage": "upsert (retention/monitoring defaults; on conflict do nothing)"
     }
   ],
-  "migrationCount": 146,
-  "aggregateSha256": "cbb24bed446f3334f4c0593716b51ee00e5b6faf57bfd7b48a8767f019551551",
+  "migrationCount": 149,
+  "aggregateSha256": "c15239411cdaff38ce6a52294d6586ae6fe711cdea40938785c55e7e38e13c0b",
   "migrations": [
     {
       "order": 0,
@@ -1362,6 +1362,33 @@
       "sourceRef": "message-board",
       "bytes": 36921,
       "sha256": "9982efff25378703a744187b15081b5cd53ab38fa6ac7d2950092a471780169e"
+    },
+    {
+      "order": 146,
+      "id": "20260929000100_agent_board_advisory_revert_cap_reset",
+      "filename": "20260929000100_agent_board_advisory_revert_cap_reset.sql",
+      "origin": "message-board-forward",
+      "sourceRef": "message-board",
+      "bytes": 24052,
+      "sha256": "f2bd4e9e06f5c348aba379a004a010d8dba29a84f66b1b4569313fad4a0046ba"
+    },
+    {
+      "order": 147,
+      "id": "20260930000100_agent_board_claim_policy_race",
+      "filename": "20260930000100_agent_board_claim_policy_race.sql",
+      "origin": "message-board-forward",
+      "sourceRef": "message-board",
+      "bytes": 58999,
+      "sha256": "1893b57ccb643a8293c0dc801d2d66d20fe1d71a2b7dc95cd93f64ced39b472d"
+    },
+    {
+      "order": 148,
+      "id": "20261001000100_agent_board_claimpolicy_lock_grant_revoke",
+      "filename": "20261001000100_agent_board_claimpolicy_lock_grant_revoke.sql",
+      "origin": "message-board-forward",
+      "sourceRef": "message-board",
+      "bytes": 10193,
+      "sha256": "db73a9941d4601dd6db0c767fdc718534fe2856598a305f4747496cadc722afd"
     }
   ],
   "excludedBridge": {

package/src/tooling.test.mjs

@@ -38,9 +38,9 @@ describe('manifest integrity', () => {
     expect(manifest.schemaVersion).toBe(8);
     expect(manifest.minClientVersion).toMatch(/^\d+\.\d+\.\d+$/);
   });
-  it('registers the four MBAUTHZ + four MBSENDAUTHZ + four MBSESSION + four MBDELEG + three MBFED + three MBHARDEN + two MBPORTALGATE + two MBPORTAL-PR32 + two ROOMOWN + two ROOMLINK + one ROOMDELEG + one LOCALAUTH + one ROOMUIAPI + one FEDSESSION + one FEDSESSION-AUTOJOIN + one GATENULL + one MEMBSTATE + one AGENTSDIR + one LEAVEIDEM + one ROLERESET + one MBROWID + one MBHYGIENE + one MBCONSENT-A + one MBCONSENT-B(a) + one MBCONSENT-B(i) + one MBCONSENT-B(ii) + one MBCONSENT-B(iii) + one MBHARDEN-#97 + one MBHARDEN-#118 + one INVITEPOLICY + one OBSGATE + one OBSGATE-2 + one OBSGATE-3 + one OBSGATE-4 + one FLEETMACHINERLS + one RESOLVENOOP + one ROOMDELEG-LANEB + one CLAIMKEY + two MINTHARDEN + one FLEETMACHINEHIJACK + one CLAIMGATE-SHADOW + one CLAIMGATE-ENFORCE + one FLEETMACHINEREACTIVATION + one DELEGCAPCEILING + one FLEETMACHINERECLAIM + one DELEGSOLEWRITER + one FLEETDOMAINRECLAIM + five ATOMICFLEETONBOARDING (onboarding + ceiling-lock + revocation-evidence + fedsession-gate + fedsession-lock-order) + one OUTBOXWAKE + one ENROLLLOCKORDER + one FEDPROVIDERABSENCE + one WAKERECOVERY + one CONSENTRECONCILE + one ENROLLRESUMPTION + one SIGNEDAUTHORITY + one SIGNERLIFECYCLE + one LEDGERAUTHORITY + one CEILINGLOCKCOMMENT + one LEDGERBOARDCREATE + one RECEIPTSUBJECTGATE + one TASKTHREADLOCKORDER + one CLAIMSUBJECTGATE + one FEDSESSIONIDENTITYGATE + one FEDIDENTITYSLUG + one INVITENODOWNGRADE + one SIGNEDWRITEFLAG + one SIGNEDWRITEMODEL + one RTCREDCLAIM + one ORIGINPOSTURE + one BOARDCLAIMPOLICY + one HEARTBEATPRESERVE + one LIVENESSDENOM + one OWNERLESSRENEWTTL + one OWNERLESSQUOTACENSUS + one FLEETDOMAINNODOWNGRADE + one OWNERLESSQUOTACONVERGE forward migrations (migrationCount = prior 113 + 5 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 = 146)', () => {
+  it('registers the four MBAUTHZ + four MBSENDAUTHZ + four MBSESSION + four MBDELEG + three MBFED + three MBHARDEN + two MBPORTALGATE + two MBPORTAL-PR32 + two ROOMOWN + two ROOMLINK + one ROOMDELEG + one LOCALAUTH + one ROOMUIAPI + one FEDSESSION + one FEDSESSION-AUTOJOIN + one GATENULL + one MEMBSTATE + one AGENTSDIR + one LEAVEIDEM + one ROLERESET + one MBROWID + one MBHYGIENE + one MBCONSENT-A + one MBCONSENT-B(a) + one MBCONSENT-B(i) + one MBCONSENT-B(ii) + one MBCONSENT-B(iii) + one MBHARDEN-#97 + one MBHARDEN-#118 + one INVITEPOLICY + one OBSGATE + one OBSGATE-2 + one OBSGATE-3 + one OBSGATE-4 + one FLEETMACHINERLS + one RESOLVENOOP + one ROOMDELEG-LANEB + one CLAIMKEY + two MINTHARDEN + one FLEETMACHINEHIJACK + one CLAIMGATE-SHADOW + one CLAIMGATE-ENFORCE + one FLEETMACHINEREACTIVATION + one DELEGCAPCEILING + one FLEETMACHINERECLAIM + one DELEGSOLEWRITER + one FLEETDOMAINRECLAIM + five ATOMICFLEETONBOARDING (onboarding + ceiling-lock + revocation-evidence + fedsession-gate + fedsession-lock-order) + one OUTBOXWAKE + one ENROLLLOCKORDER + one FEDPROVIDERABSENCE + one WAKERECOVERY + one CONSENTRECONCILE + one ENROLLRESUMPTION + one SIGNEDAUTHORITY + one SIGNERLIFECYCLE + one LEDGERAUTHORITY + one CEILINGLOCKCOMMENT + one LEDGERBOARDCREATE + one RECEIPTSUBJECTGATE + one TASKTHREADLOCKORDER + one CLAIMSUBJECTGATE + one FEDSESSIONIDENTITYGATE + one FEDIDENTITYSLUG + one INVITENODOWNGRADE + one SIGNEDWRITEFLAG + one SIGNEDWRITEMODEL + one RTCREDCLAIM + one ORIGINPOSTURE + one BOARDCLAIMPOLICY + one HEARTBEATPRESERVE + one LIVENESSDENOM + one OWNERLESSRENEWTTL + one OWNERLESSQUOTACENSUS + one FLEETDOMAINNODOWNGRADE + one OWNERLESSQUOTACONVERGE + one ADVISORYREVERTRESET + one CLAIMPOLICYRACE + one CLAIMPOLICYLOCKGRANT forward migrations (migrationCount = prior 113 + 5 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 = 149)', () => {
     expect(manifest.migrationCount).toBe(manifest.migrations.length);
-    expect(manifest.migrationCount).toBe(146);
+    expect(manifest.migrationCount).toBe(149);
     // MBSESSION switched enforcement on (scoped-send re-grant): the client-visible
     // schema version bumped to 8. MBDELEG tightens delegation and MBFED adds only
     // enrollment-only additive surface (identity_providers registry, enrollment audit,
@@ -304,6 +304,29 @@ describe('manifest integrity', () => {
       // ceiling is untouched. acquire's inline count is extracted into
       // _claimgate_active_ownerless_claims() so the two enforcement paths cannot drift.
       '20260928000100_agent_board_ownerless_quota_renew_convergence.sql',
+      // #400 ADVISORYREVERTRESET. claim_policy='advisory' skips both the ownerless TTL cap and
+      // #388's convergence clamp, and set_board_claim_policy is gated on the owner membership
+      // create_board seeds for the creator -- so an agent that creates a board can flip to
+      // advisory, renew its ownerless claims to an arbitrary horizon, flip back to inherit, and
+      // repeat, staying over quota forever while the census (which resolves policy at query time)
+      // reports no advisory share at all. The revert now RE-APPLIES the ownerless TTL cap to that
+      // board's active ownerless claims -- least(lease_expires_at, now()+cap), clamp only, never an
+      // extension -- so a horizon banked under the opt-out cannot be kept by handing the opt-out
+      // back. advisory->inherit only, governed by ownerless_guards. Bounded, not closed: a cycle
+      // still banks up to the cap.
+      '20260929000100_agent_board_advisory_revert_cap_reset.sql',
+      // #405 CLAIMPOLICYRACE. _claimgate_board_claim_policy took no lock on boards, so any
+      // operation whose snapshot predated a committed policy change acted on policy that was
+      // already gone -- renew_claim (read stale), acquire_claim (stale AND no row for #406's
+      // reset to clamp), and set_board_claim_policy itself (readers serialised on nothing).
+      // All three now take a board-scoped advisory xact lock BEFORE the policy decision --
+      // including acquire's 'advisory' path, which skips the block the agent-scoped lock lives
+      // in -- and re-read the policy as a separate statement; renew re-reads the whole CLAIM,
+      // because #400's reset clamps the very row whose pre-wait expiry is the convergence
+      // baseline. The lock helper REFUSES any isolation level but read committed, where the
+      // wait would not advance the snapshot and the lock would be silently inert.
+      '20260930000100_agent_board_claim_policy_race.sql',
+      '20261001000100_agent_board_claimpolicy_lock_grant_revoke.sql',
     ]) {
       expect(names.has(f)).toBe(true);
     }

package/tests/agent_board_board_claim_policy.test.sql

@@ -17,6 +17,13 @@
 -- the kind of reasoning that stops being true when someone moves a line, and this file would
 -- otherwise be a set of tests that only ever prove the permissive direction.
 --
+-- BCP-11..21 ARE #400: THE ADVISORY-REVERT CAP RESET. The opt-out is a TOGGLE, and that made it an
+-- escape from every ownerless bound: flip to advisory, take an arbitrary horizon, flip back, repeat
+-- — self-service, because create_board seeds the creator's owner membership and this RPC is gated
+-- on exactly that. Reverting to inherit now re-applies the ownerless TTL cap to the board's active
+-- ownerless claims, clamp only. The section pins all four transitions, both bounds (kind and board),
+-- the operator flag, and the catalog class check that this RPC is the only writer of the column.
+--
 -- BCP-5 IS THE SECOND ONE THAT MATTERS. A claim reaches its board through its thread. So the
 -- obvious hole is a claim that simply omits the thread — if that inherited "no board, therefore no
 -- enforcement", any agent could opt itself out by passing null. It resolves to 'inherit' instead,
@@ -26,7 +33,7 @@ set search_path = extensions, public, agent_board;
 
 begin;
 
-select plan(13);
+select plan(30);
 
 -- ---------------------------------------------------------------------------
 -- Fixture: one board with an owner and a non-owner member, a board-linked thread, and a
@@ -193,6 +200,259 @@ select throws_ok(
   null,
   'BCP-9: an unknown policy is refused as a bad argument, naming the vocabulary — not as a raw CHECK violation');
 
+-- ===========================================================================
+-- BCP-11..21 (#400): THE ADVISORY-REVERT CAP RESET.
+--
+-- THE DEFECT. The advisory carve-out is resolved at ENFORCEMENT time against the board's CURRENT
+-- policy, so an owner could flip to 'advisory', let an ownerless claim take an arbitrary horizon
+-- (the carve-out skips both the #373 TTL cap and #388's convergence clamp), flip back to 'inherit',
+-- and repeat before expiry. `create_board` seeds the creator's owner membership and this RPC is
+-- gated on exactly that, so an agent that created a board holds the switch that exempts its own
+-- claims: no accomplice. And #393's census resolves policy at QUERY time (OQ-29), so after the
+-- revert the escaped claim contributes zero to `claims_on_advisory_boards` while its overage still
+-- counts.
+--
+-- THE FIX. Reverting to 'inherit' means accepting inherit's rules: the ownerless TTL cap is
+-- re-applied to this board's active ownerless claims, clamp only. The opt-out may be given back —
+-- but not after banking a lease longer than inherit allows.
+--
+-- BOUNDED, NOT CLOSED, and this file does not pretend otherwise: each advisory window still banks
+-- up to the cap, so an owner flipping every 29 days still defeats convergence. What is gone is the
+-- UNBOUNDED horizon. ORQ-11 pins that bound end-to-end through the real RPCs.
+--
+-- NUMBERED 11+ AND PLACED HERE, BEFORE BCP-10, because BCP-10 fleet-revokes the owner and every
+-- assertion below needs that owner to be able to call this RPC. Renumbering BCP-10 would break its
+-- citations for no gain.
+-- ===========================================================================
+do $$
+declare
+  v_b uuid := gen_random_uuid();
+  v_t uuid := gen_random_uuid();
+begin
+  -- Session: the owner. BCP-7/8/9 set their GUCs INSIDE throws_ok, whose exception block rolls
+  -- them back with the raise, so the state here is the fixture's — but inferring that is exactly
+  -- the reading rule 4 exists for, so it is set explicitly instead.
+  perform set_config('request.jwt.claim.role', 'authenticated', true);
+  perform set_config('request.jwt.claim.sub', (select owner_user from _bcp)::text, true);
+
+  -- A SECOND BOARD, and it stays 'advisory' for the whole section. It is the scope witness for
+  -- BCP-14: reverting board A must not reach a board that never reverted. Advisory is also the
+  -- realistic shape — a board still coordinating through its own mutex, legitimately holding a
+  -- lease longer than our cap.
+  insert into agent_board.boards(id, slug, name, created_by_agent_id, claim_policy)
+  values (v_b, 'bcp400-' || substr(v_b::text, 1, 8), 'BCP 400 Other Board', (select owner_agent from _bcp), 'advisory');
+  insert into agent_board.threads(id, thread_type, created_by_agent_id, subject, board_id)
+  values (v_t, 'coordination', (select owner_agent from _bcp), 'BCP 400 other-board thread', v_b);
+
+  create temp table _bcp400 (other_board uuid, other_thread uuid) on commit drop;
+  insert into _bcp400 values (v_b, v_t);
+end $$;
+
+select lives_ok(
+  $$ select agent_board.set_board_claim_policy((select board from _bcp), 'advisory') $$,
+  'BCP-11a: the owner opts the board out again — this is the flip an over-quota holder makes to buy an unbounded horizon');
+
+-- The claims the advisory window buys. Inserted directly rather than acquired, because three of
+-- them are shapes acquire cannot produce in one call (a 'machine' kind needs a fleet fixture, one
+-- belongs to another board, one has no thread) — but they are all shapes the DATABASE can hold:
+-- an over-cap ownerless lease exists exactly where an advisory board, a grandfathered pre-flag
+-- claim, or a service_role extension put it. BCP-11 scores a fourth claim that WAS acquired
+-- through the real RPC under advisory, so the property is not proven only on synthetic rows.
+insert into agent_board.claims(agent_id, thread_id, resource_kind, resource_key, lease_expires_at)
+values
+  ((select owner_agent from _bcp), (select thread from _bcp), 'file',    'bcp400-a-file',    now() + interval '400 days'),
+  ((select owner_agent from _bcp), (select thread from _bcp), 'tool',    'bcp400-a-tool',    now() + interval '400 days'),
+  ((select owner_agent from _bcp), (select thread from _bcp), 'custom',  'bcp400-a-custom',  now() + interval '400 days'),
+  -- an OWNED kind on the same board: governed by the fleet-authority gate, never by this cap
+  ((select owner_agent from _bcp), (select thread from _bcp), 'machine', 'bcp400-a-machine', now() + interval '400 days'),
+  -- already WITHIN the cap: the twin. A reset that assigned now()+cap would LENGTHEN this one
+  ((select owner_agent from _bcp), (select thread from _bcp), 'file',    'bcp400-a-under',   now() + interval '5 days'),
+  -- another board, still advisory
+  ((select owner_agent from _bcp), (select other_thread from _bcp400), 'file', 'bcp400-b-file', now() + interval '400 days'),
+  -- no thread at all, so no board to revert
+  ((select owner_agent from _bcp), null,                      'file',    'bcp400-free-file', now() + interval '400 days');
+
+-- Two DEAD rows on the reverting board, for BCP-21. They are inserted separately because they need
+-- columns the list above does not set.
+insert into agent_board.claims(agent_id, thread_id, resource_kind, resource_key, status, released_at, lease_expires_at, updated_at)
+values
+  -- released: least() would still shorten it, so this conjunct IS observable through the lease
+  ((select owner_agent from _bcp), (select thread from _bcp), 'file', 'bcp400-a-released', 'released', now(), now() + interval '400 days', now() - interval '3 days'),
+  -- active but LAPSED: least(now()-1h, now()+cap) is the lease it already has, so this conjunct is
+  -- observable ONLY through updated_at — which is why the row carries a distinctive one
+  ((select owner_agent from _bcp), (select thread from _bcp), 'file', 'bcp400-a-lapsed',   'active',   null,  now() - interval '1 hour',   now() - interval '3 days');
+
+select lives_ok(
+  $$ select agent_board.set_board_claim_policy((select board from _bcp), 'inherit') $$,
+  'BCP-11b: and hands the opt-out back — the step that used to cost the escaping agent nothing');
+
+-- ---------------------------------------------------------------------------
+-- BCP-11: THE POINT. Every active ownerless claim on the reverting board is clamped to the TTL cap.
+-- All three ownerless kinds are scored: every other assertion here drives `file`, and dropping
+-- 'tool' or 'custom' from the kind list is the mutation that passed ORT's entire battery (ORT-9).
+-- `rpc-acquired` is 'bcp-over-cap-advisory' from BCP-3b — taken through acquire_claim under
+-- advisory and clamped by this file's own earlier revert, so the property is pinned on a row a
+-- deployment can actually produce and not only on inserted fixtures.
+-- ---------------------------------------------------------------------------
+select is(
+  (select string_agg(l.label || '=' ||
+            (c.lease_expires_at = now() + agent_board._claimgate_ownerless_ttl_cap())::text, ', ' order by l.label)
+     from agent_board.claims c
+     join (values ('bcp400-a-file', 'file'),
+                  ('bcp400-a-tool', 'tool'),
+                  ('bcp400-a-custom', 'custom'),
+                  ('bcp-over-cap-advisory', 'rpc-acquired')) as l(key, label) on l.key = c.resource_key),
+  'custom=true, file=true, rpc-acquired=true, tool=true',
+  'BCP-11 THE POINT: reverting advisory -> inherit re-applies the ownerless TTL cap to this board''s active claims, all three kinds — so a horizon banked under the opt-out cannot be kept by handing the opt-out back');
+
+-- ---------------------------------------------------------------------------
+-- BCP-12: THE TWIN, and the reason the clamp is least(). A claim already within the cap must come
+-- back untouched: an assignment to now()+cap would satisfy BCP-11 and silently LENGTHEN this lease
+-- from five days to thirty. Asserts the lease only — the row's updated_at IS bumped, which is the
+-- documented cost of least() being the single mutation-visible clamp (see the migration header).
+-- ---------------------------------------------------------------------------
+select is(
+  (select lease_expires_at from agent_board.claims where resource_key = 'bcp400-a-under'),
+  now() + interval '5 days',
+  'BCP-12 THE TWIN: a lease already within the cap is preserved to the microsecond — the reset is least(held, now()+cap), not a rewrite to now()+cap, which would hand back time the claim never had');
+
+-- ---------------------------------------------------------------------------
+-- BCP-13: the kind bound. 'machine' is an OWNED kind, governed by the fleet-authority gate and by
+-- no ownerless cap at all, so the reset must not touch it — a reset that clamped every claim on the
+-- board would satisfy BCP-11 and quietly shorten fleet leases.
+-- ---------------------------------------------------------------------------
+select is(
+  (select lease_expires_at from agent_board.claims where resource_key = 'bcp400-a-machine'),
+  now() + interval '400 days',
+  'BCP-13: a machine claim on the reverting board is untouched — the reset is scoped to the ownerless kinds, which are the only ones the TTL cap ever governed');
+
+-- ---------------------------------------------------------------------------
+-- BCP-14: the board bound. This board's revert is a statement about THIS board. A claim on another
+-- board — still advisory, legitimately holding a long lease — and a claim with no thread at all
+-- must both survive it. Dropping the board join would clamp every ownerless claim in the fleet on
+-- any revert anywhere, and every assertion above would still pass.
+-- ---------------------------------------------------------------------------
+select is(
+  (select string_agg(l.label || '=' || (c.lease_expires_at = now() + interval '400 days')::text, ', ' order by l.label)
+     from agent_board.claims c
+     join (values ('bcp400-b-file', 'other-board'),
+                  ('bcp400-free-file', 'no-thread')) as l(key, label) on l.key = c.resource_key),
+  'no-thread=true, other-board=true',
+  'BCP-14 SCOPE: a claim on a DIFFERENT board and a claim with no thread are both untouched by this board''s revert — the reset resolves through the claim''s thread to this board, the same path the policy resolver uses');
+
+-- ---------------------------------------------------------------------------
+-- BCP-21: THE DEAD ROWS. The reset is scoped to ACTIVE, unreleased, unexpired claims — the same
+-- three conjuncts the shared count predicate uses — so a revert does not rewrite history.
+--
+-- The two halves are scored differently on purpose. A RELEASED row still holds a future timestamp,
+-- so dropping `status = 'active' and released_at is null` shortens it and the LEASE moves. A LAPSED
+-- row's lease is already in the past, and least(past, now()+cap) is that same past value — so
+-- dropping `lease_expires_at > now()` is invisible in the lease and visible ONLY as a touched row.
+-- Both rows therefore carry a distinctive updated_at, and this assertion reads it.
+-- ---------------------------------------------------------------------------
+select is(
+  (select string_agg(l.label || '=' ||
+            (c.lease_expires_at = l.expected and c.updated_at = now() - interval '3 days')::text, ', ' order by l.label)
+     from agent_board.claims c
+     join (values ('bcp400-a-released', 'released', now() + interval '400 days'),
+                  ('bcp400-a-lapsed',   'lapsed',   now() - interval '1 hour')) as l(key, label, expected) on l.key = c.resource_key),
+  'lapsed=true, released=true',
+  'BCP-21: a RELEASED claim and a LAPSED one on the reverting board are not touched at all — same lease, same updated_at. The reset governs live leases, not the ledger of dead ones');
+
+-- ---------------------------------------------------------------------------
+-- BCP-15..17: THE TRANSITION CONDITION, all three non-triggering transitions. The rows below are
+-- inserted once, while the board is 'inherit', and each is read after its own transition.
+--
+-- BCP-17 (advisory -> advisory) is the one the other two cannot see: dropping the `= 'inherit'`
+-- conjunct leaves "was previously advisory", which still clamps nothing on either inherit-first
+-- case. Without it that mutation survives BCP-15 and BCP-16 untouched.
+-- ---------------------------------------------------------------------------
+insert into agent_board.claims(agent_id, thread_id, resource_kind, resource_key, lease_expires_at)
+values
+  ((select owner_agent from _bcp), (select thread from _bcp), 'file', 'bcp400-noop-ii',  now() + interval '400 days'),
+  ((select owner_agent from _bcp), (select thread from _bcp), 'file', 'bcp400-noop-ia',  now() + interval '400 days'),
+  ((select owner_agent from _bcp), (select thread from _bcp), 'file', 'bcp400-noop-aa',  now() + interval '400 days'),
+  ((select owner_agent from _bcp), (select thread from _bcp), 'file', 'bcp400-flag-off', now() + interval '400 days');
+
+select lives_ok(
+  $$ select agent_board.set_board_claim_policy((select board from _bcp), 'inherit') $$,
+  'BCP-15a: the owner re-sets inherit on a board that is already inherit');
+
+select is(
+  (select lease_expires_at from agent_board.claims where resource_key = 'bcp400-noop-ii'),
+  now() + interval '400 days',
+  'BCP-15: inherit -> inherit clamps NOTHING — a no-op re-set is not a policy change, and treating it as one would let any owner shorten their own board''s leases by calling the RPC twice');
+
+select lives_ok(
+  $$ select agent_board.set_board_claim_policy((select board from _bcp), 'advisory') $$,
+  'BCP-16a: the owner opts out');
+
+select is(
+  (select lease_expires_at from agent_board.claims where resource_key = 'bcp400-noop-ia'),
+  now() + interval '400 days',
+  'BCP-16: inherit -> advisory clamps nothing — the reset belongs to the REVERT, and clamping while opting OUT would be the opposite of what the opt-out promises');
+
+select lives_ok(
+  $$ select agent_board.set_board_claim_policy((select board from _bcp), 'advisory') $$,
+  'BCP-17a: and re-sets advisory on a board that is already advisory');
+
+select is(
+  (select lease_expires_at from agent_board.claims where resource_key = 'bcp400-noop-aa'),
+  now() + interval '400 days',
+  'BCP-17: advisory -> advisory clamps nothing — the discriminating case, because a guard that asked only "was it advisory?" passes BCP-15 and BCP-16 and would clamp a board that never came back');
+
+-- ---------------------------------------------------------------------------
+-- BCP-18: ONE OPERATOR FLAG. With ownerless_guards off, nothing enforces the TTL cap at acquire or
+-- at renew, so a revert must not enforce it either — the flag means the same thing on all three
+-- write paths or it means nothing.
+-- ---------------------------------------------------------------------------
+do $$
+begin
+  update agent_board.claimgate_enforcement_flags set enabled = false where scope_key = 'ownerless_guards';
+end $$;
+
+select lives_ok(
+  $$ select agent_board.set_board_claim_policy((select board from _bcp), 'inherit') $$,
+  'BCP-18a: with the guards off the owner reverts to inherit');
+
+select is(
+  (select lease_expires_at from agent_board.claims where resource_key = 'bcp400-flag-off'),
+  now() + interval '400 days',
+  'BCP-18: with ownerless_guards OFF an advisory -> inherit revert clamps nothing — one flag governs the cap at acquire, at renew and at the revert alike');
+
+do $$
+begin
+  update agent_board.claimgate_enforcement_flags set enabled = true where scope_key = 'ownerless_guards';
+end $$;
+
+-- ---------------------------------------------------------------------------
+-- BCP-19/20: CLASS (rule 1). The hook can only close the escape if this RPC is the ONLY way
+-- boards.claim_policy changes. Derived from the catalog, not from a list: a second writer names
+-- itself here rather than silently inheriting a policy change that resets nothing.
+--
+-- Two independent bounds, because neither is sufficient alone. BCP-19 is a source scan and a source
+-- scan has a floor — it sees `set claim_policy` and not, say, a dynamic EXECUTE. BCP-20 is the
+-- privilege bound underneath it: NO role holds UPDATE on agent_board.boards, so the column cannot
+-- be written from a session at all, only from a SECURITY DEFINER function (which BCP-19 enumerates)
+-- or by the table owner. `boards` also carries no user triggers, so there is no third path.
+-- ---------------------------------------------------------------------------
+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 agent_board_test.stripped_body(p.oid, true) ~ 'set\s+claim_policy'),
+  'set_board_claim_policy',
+  'BCP-19 CLASS: set_board_claim_policy is the ONLY function that writes boards.claim_policy — a second writer would need the same advisory-revert reset and fails here instead of being remembered');
+
+select is(
+  format('anon=%s, authenticated=%s, service_role=%s, user_triggers=%s',
+         has_table_privilege('anon',          'agent_board.boards', 'update')::text,
+         has_table_privilege('authenticated', 'agent_board.boards', 'update')::text,
+         has_table_privilege('service_role',  'agent_board.boards', 'update')::text,
+         (select count(*) from pg_trigger where tgrelid = 'agent_board.boards'::regclass and not tgisinternal)::text),
+  'anon=false, authenticated=false, service_role=false, user_triggers=0',
+  'BCP-20 CLASS: no role holds UPDATE on agent_board.boards and the table carries no user triggers — so the column is unreachable except through the definer function BCP-19 enumerates, which is the bound a source scan cannot give');
+
 -- ---------------------------------------------------------------------------
 -- BCP-10: A FLEET-REVOKED OWNER IS STILL AN OWNER BY MEMBERSHIP. This function shipped its first
 -- version WITHOUT this check while its own commit message claimed to mirror set_board_role_gate

package/tests/agent_board_claim_subject_gate.test.sql

@@ -850,14 +850,23 @@ select is(
 -- sides: the catalog function scan, and the effective-privilege assertions after it (no role
 -- holds a write privilege by ANY route, so a direct write is impossible and the SECURITY
 -- DEFINER bodies are the whole surface).
+--
+-- set_board_claim_policy (#400) is the FIFTH member, and it named itself here rather than being
+-- remembered -- which is what this assertion is for. It creates no claims row and re-keys nothing:
+-- its only claims write is the advisory -> inherit cap reset, `set lease_expires_at =
+-- least(lease_expires_at, now() + cap), updated_at = now()`, on the reverting board's active
+-- ownerless claims. That EXEMPTION IS ASSERTED POSITIVELY, not by absence: BCP-11/13/14 look those
+-- claims up BY resource_key and score the resulting timestamps, so a reset that re-keyed or
+-- inserted a row fails them by name, and assertion 51 below (every function that CREATES a claims
+-- row refuses without thread access) still holds because this one creates none.
 select is(
   (select coalesce(string_agg(p.proname, ',' order by p.proname), '(none)')
      from pg_proc p
     where p.pronamespace = 'agent_board'::regnamespace
       and lower(agent_board_test.stripped_body(p.oid, true))
           ~ '(insert\s+into|merge\s+into|update|delete\s+from|truncate)(\s+table)?(\s+only)?\s+(("?agent_board"?\s*\.\s*)?claims\M|("?agent_board"?\s*\.\s*)?"claims")'),
-  'acquire_claim,reclaim_fleet_machine,release_claim,renew_claim',
-  'catalog: these four are the ONLY agent_board functions that write claims (insert/merge/update/delete/TRUNCATE) -- a new writer names itself here');
+  'acquire_claim,reclaim_fleet_machine,release_claim,renew_claim,set_board_claim_policy',
+  'catalog: these five are the ONLY agent_board functions that write claims (insert/merge/update/delete/TRUNCATE) -- a new writer names itself here');
 
 select is(
   (select coalesce(string_agg(p.proname, ',' order by p.proname), '(none)')

package/tests/agent_board_claimkey.test.sql

@@ -211,8 +211,14 @@ select set_eq(
   -- 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)');
+  -- set_board_claim_policy (#400) is a fifth writer: an advisory -> inherit revert re-applies the
+  -- ownerless TTL cap to that board's active ownerless claims. It is EXEMPT FROM ASSERTION 25 by a
+  -- DERIVED property and not by name -- its claims UPDATE sets only lease_expires_at/updated_at and
+  -- its body never mentions resource_key at all, so there is no key for the normalizer to canonicalize.
+  -- The exemption's positive claim (the reset moves lease timestamps and nothing else) is scored in
+  -- agent_board_board_claim_policy.test.sql BCP-11/13/14, which look the claims up BY resource_key.
+  array['acquire_claim', 'renew_claim', 'release_claim', 'reclaim_fleet_machine', 'set_board_claim_policy'],
+  'exactly acquire/renew/release/reclaim/set_board_claim_policy write agent_board.claims (catalog-enumerated writer class)');
 select is(
   (select count(*)::int
      from pg_proc p
@@ -220,6 +226,15 @@ select is(
     where n.nspname = 'agent_board'
       and p.prokind = 'f'
       and agent_board_test.stripped_body(p.oid) ~* '(insert\s+into|update)\s+(agent_board\.)?claims\M'
+      -- #400: SCOPED TO WRITERS THAT HAVE A KEY TO NORMALIZE. A claims writer whose body never
+      -- mentions resource_key cannot set one -- an UPDATE must name the column in its SET list and
+      -- an INSERT must name it in its column list (resource_key is NOT NULL) -- so requiring it to
+      -- call the normalizer would be dead code added to satisfy a check, which is the anti-pattern
+      -- rule 2 names. DERIVED, not a name exemption: a new writer that touches resource_key at all
+      -- is still in the population and still fails closed. STATED HOLE: `insert into claims select *
+      -- from ...` names no column and would slip past, which is the same shape assertion 24's regex
+      -- already cannot see.
+      and agent_board_test.stripped_body(p.oid) ~* '\mresource_key\M'
       -- message-board#196 Bucket B: read RAW, one comment naming _canonical_claim_key
       -- dropped a bypass writer out of this set and the count went to 0 green.
       -- anchored to the CALL shape: a bare-substring `!~` is satisfied by any