@consiliency/agent-board-schema 1.45.0 → 1.50.0

package/migrations/20260929000100_agent_board_advisory_revert_cap_reset.sql

@@ -0,0 +1,371 @@
+-- #400 — a board owner can defeat ownerless-quota convergence indefinitely, and leave no trace.
+--
+-- THE DEFECT, AND IT NEEDS NO ACCOMPLICE. `create_board` seeds the creator's owner membership, and
+-- that membership is exactly what `set_board_claim_policy`'s gate tests. So an agent that creates a
+-- board holds the switch that exempts its own claims:
+--
+--   1. flip the board to claim_policy = 'advisory';
+--   2. renew every ownerless claim to the full horizon — the advisory carve-out skips BOTH the
+--      #373 TTL cap and the #388 convergence clamp;
+--   3. flip back to 'inherit';
+--   4. repeat before expiry.
+--
+-- And it is invisible. #393's census resolves board policy at QUERY time (OQ-29), so after step 3
+-- `claims_on_advisory_boards` reports ZERO for those claims while the overage they bought is still
+-- counted. An operator sees an agent over quota with no advisory share — the shape that reads as
+-- plain squatting — and the column built to explain the exemption reports none of it. #399 shipped
+-- with this pinned as a test (ORQ-11/12) rather than described in prose, precisely so that closing
+-- it would have to change an assertion instead of a paragraph.
+--
+-- ===========================================================================
+-- THE FIX: A CAP RESET ON REVERT. On an 'advisory' -> 'inherit' transition, re-apply the ownerless
+-- TTL cap to that board's active ownerless claims. Clamp only — least(lease_expires_at, now() +
+-- _claimgate_ownerless_ttl_cap()) — never extend.
+-- ===========================================================================
+--
+-- THE FAIRNESS ARGUMENT, which is the whole justification: reverting to 'inherit' means accepting
+-- inherit's rules, and the clamp only ever SHORTENS. A board that wants the long horizon its own
+-- mutex granted may keep it — by staying advisory. What it may not do is bank a long lease under
+-- the opt-out and then hand the opt-out back. The claim keeps exactly what an ordinary claim on an
+-- ordinary inherit board is allowed to keep, which is what "inherit" means.
+--
+-- WHY NOT THE AUDIT LEDGER #400 ORIGINALLY PROPOSED. A ledger makes the escape VISIBLE; this
+-- removes its BENEFIT, and the two are not equal. To hold a lease longer than the cap the board
+-- must STAY advisory — and while it is advisory those claims are counted by the census's
+-- `claims_on_advisory_boards`, which is exactly the column an operator reads. So above the cap the
+-- escape becomes either ineffective or visible, with no new mechanism and no policy history to
+-- maintain. The owner chose this over the ledger.
+--
+-- ===========================================================================
+-- WHAT THIS DOES NOT CLOSE. BOUNDED, NOT CLOSED — and the difference is stated here rather than
+-- discovered later, because a header that overclaims is the #399 failure being repeated.
+-- ===========================================================================
+--
+--   1. THE FLIP-FLOP STILL WORKS, up to the cap. Each advisory window still buys a lease of up to
+--      `_claimgate_ownerless_ttl_cap()` (30 days) that survives the revert, so an owner who flips
+--      every 29 days keeps an over-quota agent over quota forever. What is gone is the UNBOUNDED
+--      horizon: the ceiling on what a cycle can bank drops from "whatever was asked for" to the
+--      same cap every non-advisory ownerless lease already lives under. #388's convergence clamp
+--      is therefore still defeatable by a board owner; it is no longer defeatable by ONE flip.
+--      ORQ-11 asserts the bound (the +400 day lease does not survive the revert) and says so.
+--
+--   2. IT IS STILL INVISIBLE BETWEEN FLIPS. Nothing here records that the exemption was used, and
+--      the census still resolves policy at query time. ORQ-12 is unchanged and still pins that.
+--      Recording acquire-time policy remains #393's own documented gap and is not invented here.
+--
+--   3. AN IN-FLIGHT RENEW CAN STILL WIN THE RACE, AND THIS IS UNPINNED. `_claimgate_board_claim_
+--      policy` takes no lock on `boards`, so a `renew_claim` whose snapshot predates the revert's
+--      commit resolves 'advisory' and, under READ COMMITTED, re-evaluates and applies its full
+--      horizon AFTER this function's row lock is released at commit. The attacker owns both
+--      sessions, so a deliberate interleave banks a full-horizon lease past the revert. Closing it
+--      means taking a `boards` lock on the renew path, which is a LOCK-ORDER decision (renew
+--      already touches claims and, through the resolver, threads/boards) and belongs with the
+--      two-session isolationtester harness, not with this change. Recorded as open rather than
+--      quietly excluded from the claim.
+--
+--   4. AN OPERATOR EXTENSION IS CLAMPED TOO. `service_role` is exempt from the guards at acquire
+--      and at renew, so an operator may deliberately hand an agent a 400-day ownerless lease. If
+--      that claim's board is later reverted from advisory to inherit, this reset shortens it —
+--      nothing records who last extended a lease, and inventing provenance to protect it would be
+--      a second unreviewed mechanism. The operator can re-extend; service_role's renew is exempt.
+--
+-- ===========================================================================
+-- THE DECISIONS, EACH PINNED
+-- ===========================================================================
+--
+-- TRIGGER CONDITION: 'advisory' -> 'inherit' ONLY. Not 'inherit' -> 'inherit' (a no-op re-set must
+-- clamp nothing; BCP-15), not 'inherit' -> 'advisory' (BCP-16), not 'advisory' -> 'advisory'
+-- (BCP-17 — the one the other three cannot see: dropping the `= 'inherit'` conjunct leaves
+-- "previously advisory", which still passes the two inherit-first cases). The OUTGOING policy is
+-- read under `for no key update` on the board row, so two concurrent flips serialize and only the
+-- one that actually observed 'advisory' resets. `for no key update` is deliberate over `for
+-- update`: it does not conflict with the FOR KEY SHARE that an FK reference to `boards` takes, so
+-- inserting a thread on this board does not queue behind a policy flip.
+--
+-- CARVE-OUTS, and where they DIFFER from the guards this mirrors — stated because "consistency" is
+-- the default expectation and one of the two is deliberately absent:
+--
+--   * `_claimgate_ownerless_guards_enabled()` GOVERNS THIS, exactly as it governs every other
+--     ownerless guard on both write paths. With the flag off nothing enforces the TTL cap at
+--     acquire or at renew, so re-applying it on a revert would enforce a cap that no other path
+--     enforces — one flag, one meaning. BCP-18 pins it.
+--
+--   * THERE IS NO service_role CARVE-OUT, because there is nothing for it to carve out.
+--     `set_board_claim_policy` REFUSES service_role outright (current_agent_id() is null, so the
+--     owner gate raises 42501 — BCP-8) and the reset sits below that gate. An `and not
+--     _is_service_role()` conjunct here would be dead code that reads like a policy. The carve-out
+--     that DOES bite is the one recorded above as limitation 4: the reset governs the BOARD's
+--     claims regardless of who last extended them.
+--
+-- SCOPE: active, unreleased, unexpired claims of the ownerless kinds whose thread resolves to this
+-- board. The kind list is NOT hand-written a fourth time — `_claimgate_ownerless_kinds()` is
+-- introduced below and `_claimgate_active_ownerless_claims()` (the helper both enforcement paths
+-- count through) is re-created to consume it, so the reset and the guards share one definition. A
+-- claim on ANOTHER board, or with no thread at all, is out of scope and untouched (BCP-14): this
+-- board's revert is a statement about this board. So are the DEAD rows on this board — a released
+-- claim and a lapsed one (BCP-21), scored on the lease for the released row and on `updated_at` for
+-- the lapsed one, whose lease `least()` already protects on its own.
+--
+-- `least()`, AND IT IS THE ONLY CLAMP MECHANISM — deliberately not paired with a
+-- `lease_expires_at > now() + cap` conjunct in the WHERE. The two would be the same guard written
+-- twice, and only one of them can be mutation-visible: with the WHERE conjunct present, deleting
+-- `least()` changes nothing observable. So `least()` stands alone and BCP-12 fails when it is
+-- replaced by an assignment. The cost is that a claim already WITHIN the cap has its `updated_at`
+-- bumped by a revert while its lease is preserved to the microsecond; that is a documented
+-- consequence of keeping one mechanism rather than two, and BCP-12 asserts the lease only.
+--
+-- CLASS (rule 1): `set claim_policy` appears in exactly one function in `agent_board`, and no role
+-- holds UPDATE on `agent_board.boards` — so this RPC is the only writer of the column and the only
+-- place the hook can live. Both halves are asserted from the catalog in BCP-19/20, the second as a
+-- privilege bound rather than as a longer regex.
+
+-- ---------------------------------------------------------------------------
+-- The ownerless kind list, once. Every other site still spells it inline; those are the two
+-- enforcement paths (acquire_claim, renew_claim) and they are pinned BEHAVIOURALLY (ORT-9, ORQ-2)
+-- because a kind that stops being clamped is only visible as a clamp that did not happen. They are
+-- not re-emitted here: transcribing two 150-line function bodies for a cosmetic dedup is a
+-- transcription risk taken for no behaviour change.
+-- ---------------------------------------------------------------------------
+create or replace function agent_board._claimgate_ownerless_kinds()
+returns text[]
+language sql
+immutable
+parallel safe
+set search_path = ''
+as $$
+  select array['file', 'tool', 'custom']::text[];
+$$;
+
+revoke all on function agent_board._claimgate_ownerless_kinds() from public, anon;
+grant execute on function agent_board._claimgate_ownerless_kinds() to authenticated, service_role;
+
+comment on function agent_board._claimgate_ownerless_kinds() is
+  'The OWNERLESS claim kinds — the ones governed by the per-agent quota and the TTL cap rather '
+  'than by the fleet-authority gate. Single definition shared by '
+  '_claimgate_active_ownerless_claims() (which both enforcement paths count through) and by '
+  'set_board_claim_policy''s advisory-revert cap reset (#400). Granted to authenticated like its '
+  'sibling _claimgate_ownerless_quota(): it returns a constant and tells a caller nothing about '
+  'any row.';
+
+-- ---------------------------------------------------------------------------
+-- The count, re-created to consume the kind helper. Body otherwise unchanged from 20260928000100.
+-- ---------------------------------------------------------------------------
+create or replace function agent_board._claimgate_active_ownerless_claims(p_agent_id uuid)
+returns integer
+language sql
+stable
+set search_path = ''
+as $$
+  select count(*)::integer
+    from agent_board.claims c
+   where c.agent_id = p_agent_id
+     and c.resource_kind = any(agent_board._claimgate_ownerless_kinds())
+     and c.status = 'active'
+     and c.released_at is null
+     and c.lease_expires_at > now();
+$$;
+
+revoke all on function agent_board._claimgate_active_ownerless_claims(uuid) from public, anon;
+grant execute on function agent_board._claimgate_active_ownerless_claims(uuid) to service_role;
+
+-- Rule 5: the previous wording said a board owner may flip "indefinitely", which #400 falsifies in
+-- its unbounded form. Corrected in the migration that changes the behaviour, not left for the next
+-- reader to disbelieve.
+comment on function agent_board._claimgate_active_ownerless_claims(uuid) is
+  '#388: THE single definition of an agent''s active ownerless claim count — acquire_claim''s quota '
+  'predicate (kind in _claimgate_ownerless_kinds(), status active, released_at null, lease '
+  'unexpired). Called by acquire_claim (which refuses at >= _claimgate_ownerless_quota()) and by '
+  'renew_claim (which stops EXTENDING at > quota, so an over-quota agent converges to the ceiling '
+  'UNLESS its board opts out). The opt-out escape is now BOUNDED rather than unbounded (#400): a '
+  'board owner may still flip claim_policy to advisory and back, but reverting to inherit '
+  're-applies the ownerless TTL cap, so a cycle banks at most _claimgate_ownerless_ttl_cap() '
+  'instead of an arbitrary horizon. NO board-policy filter here: the advisory opt-out gates whether '
+  'a guard RUNS, not whether the resulting rows COUNT. service_role only, and deliberately narrower '
+  'than _claimgate_ownerless_quota(): this reads claims under security invoker, so an authenticated '
+  'caller would receive its own RLS-filtered count under a fleet-wide name.';
+
+-- ---------------------------------------------------------------------------
+-- set_board_claim_policy. The 20260922000100 body with the outgoing-policy read and the cap reset
+-- added; the validation, the owner gate, the boards UPDATE, the P0002 check and the fleet-revocation
+-- assertion are unchanged and in the same order.
+--
+-- ORDER: boards -> claims -> the agents-side revocation assertion. The canonical boards-before-
+-- agents order (#194) is preserved and the reset sits between them; the assertion still raises in
+-- the same transaction, so a fleet-revoked owner's reset is rolled back with their policy change.
+-- ---------------------------------------------------------------------------
+create or replace function agent_board.set_board_claim_policy(
+  p_board_id uuid,
+  p_claim_policy text
+)
+returns table(
+  board_id uuid,
+  claim_policy text,
+  updated_at timestamptz
+)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_actor uuid := agent_board.current_agent_id();
+  v_row agent_board.boards%rowtype;
+  v_prev_policy text;
+begin
+  if p_claim_policy is null then
+    raise exception 'p_claim_policy must not be null' using errcode = '22023';
+  end if;
+  -- Validated HERE as well as by the column CHECK. The CHECK would reject an unknown value
+  -- anyway, but with a constraint-violation error naming an internal constraint; a caller asking
+  -- for 'off' deserves to be told the vocabulary, not handed 23514.
+  if p_claim_policy not in ('inherit', 'advisory') then
+    raise exception 'claim policy must be one of inherit, advisory (received %)', p_claim_policy
+      using errcode = '22023';
+  end if;
+
+  -- Owner gate: only an active owner-role member may set this. service_role
+  -- (current_agent_id() = null) is not an owner and is rejected here.
+  if v_actor is null
+     or not exists (
+       select 1
+         from agent_board.board_memberships bm
+        where bm.board_id = p_board_id
+          and bm.agent_id = v_actor
+          and bm.role = 'owner'
+          and bm.membership_state in ('joined', 'subscribed')
+     ) then
+    raise exception 'only a board owner may set the claim policy' using errcode = '42501';
+  end if;
+
+  -- #400: the OUTGOING policy, read under the row lock the UPDATE below will take anyway. Placed
+  -- AFTER the owner gate so an unauthorized caller never locks the row. `for no key update` rather
+  -- than `for update`: it does not conflict with the FOR KEY SHARE an FK reference to boards takes,
+  -- so a concurrent thread insert on this board is not queued behind a policy flip. Two concurrent
+  -- flips serialize here, so only the one that genuinely observed 'advisory' resets.
+  --
+  -- A missing board leaves this null and the UPDATE below matches nothing, so the P0002 answer and
+  -- its ordering are unchanged.
+  select b.claim_policy into v_prev_policy
+    from agent_board.boards b
+   where b.id = p_board_id
+     for no key update;
+
+  update agent_board.boards b
+     set claim_policy = p_claim_policy,
+         updated_at = now()
+   where b.id = p_board_id
+  returning * into v_row;
+
+  if v_row.id is null then
+    raise exception 'board not found' using errcode = 'P0002';
+  end if;
+
+  -- #400 THE CAP RESET ON REVERT. Reverting to 'inherit' means accepting inherit's rules, so this
+  -- board's active ownerless claims get the ownerless TTL cap re-applied. The escape it closes:
+  -- flip to advisory, renew every claim to an arbitrary horizon (the advisory carve-out skips both
+  -- the cap and #388's convergence clamp), flip back, repeat. An agent that created the board is
+  -- its owner, so no accomplice is needed. Nothing took the granted horizon back — the convergence
+  -- clamp only refuses to EXTEND — so the horizon simply survived the revert.
+  --
+  -- CLAMP ONLY, and least() is the ONLY thing doing it. There is deliberately no `lease_expires_at
+  -- > now() + cap` conjunct in the WHERE: it would be the same guard written twice and would make
+  -- least() unmutatable. So a claim already within the cap keeps its lease to the microsecond
+  -- (BCP-12) while its updated_at is bumped — the documented cost of one mechanism over two.
+  --
+  -- 'advisory' -> 'inherit' ONLY. A no-op re-set (inherit -> inherit) must clamp nothing, and
+  -- neither may inherit -> advisory or advisory -> advisory (BCP-15/16/17).
+  --
+  -- Governed by the same operator flag as every other ownerless guard: with ownerless_guards off
+  -- nothing enforces this cap at acquire or renew, so re-applying it here would enforce a bound no
+  -- other path enforces (BCP-18). There is no service_role conjunct because service_role cannot
+  -- reach this line — the owner gate above refuses it (BCP-8).
+  --
+  -- Scoped to THIS board through the claim's thread, the same path _claimgate_board_claim_policy
+  -- resolves. A claim on another board, or with no thread, is untouched (BCP-14).
+  if v_prev_policy = 'advisory'
+     and p_claim_policy = 'inherit'
+     and agent_board._claimgate_ownerless_guards_enabled() then
+    update agent_board.claims c
+       set lease_expires_at = least(c.lease_expires_at,
+                                    now() + agent_board._claimgate_ownerless_ttl_cap()),
+           updated_at = now()
+     where c.resource_kind = any(agent_board._claimgate_ownerless_kinds())
+       and c.status = 'active'
+       and c.released_at is null
+       and c.lease_expires_at > now()
+       and c.thread_id in (select t.id
+                             from agent_board.threads t
+                            where t.board_id = p_board_id);
+  end if;
+
+  -- #276, AFTER the boards UPDATE so this function's order is boards -> agents, the canonical one
+  -- (#194). Fleet revocation deliberately LEAVES agents.status = 'active' -- the ledger row is the
+  -- only authority signal -- so the owner-membership check above passes for a revoked owner and
+  -- cannot stand alone. Disabling this board's claim enforcement is an authority write in the same
+  -- class as flipping the role gate, which is why the mirror has to include this call and not just
+  -- the membership test. Same transaction: the raise rolls the UPDATE back -- and, since #400, the
+  -- cap reset with it.
+  --
+  -- This was MISSING in the first version of this function, which claimed in its own commit
+  -- message to mirror set_board_role_gate "exactly". A review seat found it by reading both
+  -- functions side by side rather than taking that claim.
+  perform agent_board._assert_actor_not_fleet_revoked(v_actor, 'set_board_claim_policy');
+
+  return query select v_row.id, v_row.claim_policy, v_row.updated_at;
+end;
+$$;
+
+revoke all on function agent_board.set_board_claim_policy(uuid, text) from public, anon;
+grant execute on function agent_board.set_board_claim_policy(uuid, text) to authenticated, service_role;
+
+comment on function agent_board.set_board_claim_policy(uuid, text) is
+  'Board-owner-only. Sets boards.claim_policy to ''inherit'' (follow the fleet-wide claimgate flags) '
+  'or ''advisory'' (this board coordinates through another locking mechanism, so our ownerless '
+  'file/tool/custom TTL cap and quota are recorded but not enforced). Never weakens the '
+  'fleet-authority gate on machine/repository/repo_file, the subject gate, or claim uniqueness. '
+  'Owner gate and service_role refusal mirror set_board_role_gate. #400: an advisory -> inherit '
+  'transition RE-APPLIES the ownerless TTL cap to this board''s active ownerless claims — '
+  'least(lease_expires_at, now() + _claimgate_ownerless_ttl_cap()), clamp only, never an extension '
+  '— so a long lease banked under the opt-out cannot be kept by handing the opt-out back. Governed '
+  'by ownerless_guards; no other transition resets anything.';
+
+-- ---------------------------------------------------------------------------
+-- Rule 5: three recorded facts that were true when written and are not now. #399 stated the escape
+-- as UNBOUNDED ("indefinitely", "forever"); it is now bounded by the TTL cap per cycle. Corrected
+-- in the migration that falsifies them. The 20260928000100 file itself cannot be edited — its
+-- bytes are hashed in the manifest and in fixtures/already-applied.json — so the comments it set
+-- are restated here, which is the pattern that migration used for the same reason.
+-- ---------------------------------------------------------------------------
+comment on column agent_board.boards.claim_policy is
+  'Board-settable claim enforcement. ''inherit'' follows the fleet-wide claimgate flags. ''advisory'' '
+  'means this board coordinates through some OTHER locking mechanism, so our ownerless '
+  '(file/tool/custom) TTL cap and per-agent quota are recorded but not enforced for its claims. It '
+  'does NOT weaken the fleet-authority gate on machine/repository/repo_file, the subject gate, or '
+  'claim uniqueness — a board may decline our lock, never grant itself another owner''s resource. '
+  'Set via agent_board.set_board_claim_policy (board owner only), which since #400 re-applies the '
+  'ownerless TTL cap to this board''s active ownerless claims when the policy reverts from '
+  '''advisory'' to ''inherit'': the opt-out may be given back, but not after banking a lease longer '
+  'than inherit allows.';
+
+comment on function agent_board._claimgate_ownerless_quota() is
+  'CLAIMGATE/SHADOW (#133): max concurrent ACTIVE ownerless (file/tool/custom) claims per agent. '
+  'Single source for the migration logic and its tests. GENEROUS placeholder (50) pending prod '
+  'census. Enforced on BOTH write paths: acquire_claim REFUSES at count >= quota (54000), and '
+  'renew_claim stops EXTENDING at count > quota (#388) so an agent already over the ceiling '
+  'converges back to it instead of renewing its overage forever — SCOPED to agents whose boards do '
+  'not opt out. A board owner may flip claim_policy to advisory, let the agent renew, and flip '
+  'back; since #400 the revert re-applies the ownerless TTL cap, so each such cycle banks at most '
+  '_claimgate_ownerless_ttl_cap() rather than an arbitrary horizon. The escape is bounded, not '
+  'closed (ORQ-11/12). The two predicates differ deliberately — >= is what makes the quota the '
+  'largest reachable population, > is what makes the ceiling the convergence fixed point — and both '
+  'count through _claimgate_active_ownerless_claims(). Governed by '
+  '_claimgate_ownerless_guards_enabled() on both paths, service_role exempt, and skipped for a board '
+  'whose claim_policy is advisory.';
+
+comment on table agent_board.claimgate_enforcement_flags is
+  'CLAIMGATE per-scope enforcement flags. Absent row => disabled (SHADOW default: blocks nothing). '
+  'scope_key ''ownerless_guards'' gates EVERY ownerless (file/tool/custom) guard on ALL THREE write '
+  'paths: the TTL cap + per-agent quota in acquire_claim, in renew_claim both the TTL clamp (#373) '
+  'and the quota-convergence clamp (#388), and in set_board_claim_policy the advisory -> inherit cap '
+  'reset (#400). The advisory opt-out is owner-toggleable and re-toggleable, so it remains an escape '
+  'from convergence — bounded since #400 by the TTL cap per cycle rather than unbounded. '
+  'Operator-managed (service_role); enabled only after the prod lease-length census.';