@consiliency/agent-board-schema 1.44.0 → 1.48.0

package/tests/agent_board_ownerless_quota_census.test.sql

@@ -0,0 +1,400 @@
+-- #388 — the ownerless quota census. A read-only instrument, so the failure modes it can have are
+-- (a) counting something acquire does not count, (b) reading healthy because it saw nothing, and
+-- (c) answering per-caller while looking fleet-wide. Every assertion here is aimed at one of those.
+--
+-- OQ-6 IS THE ASSERTION THIS FILE EXISTS FOR. The census reproduces acquire_claim's quota count
+-- predicate by hand, and a census whose arithmetic drifts from the enforcer's is silently about a
+-- different question. So the UNDER agent is given three COUNTED claims and four NEAR-MISS rows,
+-- each differing from a counted row in EXACTLY ONE dimension — a set released_at, a non-active
+-- status, a lapsed lease, and an owned resource kind. Dropping any single conjunct from the view
+-- makes exactly one of those rows count and OQ-6 reads 4 instead of 3. Asserting "the over agent
+-- is over" would have proved nothing about the predicate at all: 51 rows are over the quota under
+-- almost any predicate you could write.
+--
+-- OQ-25/26 ARE THE OTHER HALF, and they are the only assertions here that test the OPERATION
+-- rather than a property of the reader. They put the AT agent at exactly the quota, flip the
+-- guards on, and require that the census's `acquire_blocked` and acquire_claim's actual 54000
+-- agree — then release one claim and require that BOTH flip together. A reader can agree with a
+-- hand-copied predicate and still disagree with the function; only calling the function settles it.
+--
+-- OQ-14 IS THE ANTI-VACUOUS ASSERTION. The live answer is expected to be zero agents over quota,
+-- so "0 offenders" must be provably distinguishable from "examined nothing" — the #367 shape,
+-- where a reader returned zero rows about an entirely unmonitored fleet and read as perfect
+-- health. It requires the summary's denominator to be STRICTLY GREATER than its finding, which is
+-- true here because the fixture guarantees a holder that is not an offender, and which fails
+-- immediately if the denominator is ever derived from the offender set.
+--
+-- SCOPING. Every per-agent assertion is keyed to this file's agent ids, and every summary
+-- assertion is either an identity against the view (immune to pollution) or a recomputation
+-- scoped by handle suffix. The summary counts every agent in the database; an absolute literal
+-- against it would fail on other fixtures' leftovers and look like a real defect.
+create extension if not exists pgtap with schema extensions;
+set search_path = extensions, public, agent_board;
+
+begin;
+
+select plan(30);
+
+-- ---------------------------------------------------------------------------
+-- Fixture.
+--   over   — quota + 1 active ownerless claims: over by 1, and blocked
+--   at     — exactly quota: over by NOTHING, and still blocked (the asymmetry OQ-4/5 pin)
+--   under  — 3 counted claims (one per ownerless kind) + 4 near-miss rows + 1 advisory board
+--   none   — an active agent holding NO ownerless claims: a non-holder, absent from the view
+--   susp   — a SUSPENDED agent holding quota + 2: must still appear (OQ-12)
+-- ---------------------------------------------------------------------------
+create temp table _oq (
+  sfx text,
+  over_agent uuid, at_agent uuid, under_agent uuid, none_agent uuid, susp_agent uuid,
+  at_user uuid, adv_board uuid, adv_thread uuid
+) on commit drop;
+
+do $$
+declare
+  v_sfx text := replace(substr(gen_random_uuid()::text, 1, 8), '-', '');
+  v_over uuid := gen_random_uuid();
+  v_at uuid := gen_random_uuid();
+  v_under uuid := gen_random_uuid();
+  v_none uuid := gen_random_uuid();
+  v_susp uuid := gen_random_uuid();
+  v_at_user uuid;
+  v_board uuid := gen_random_uuid();
+  v_thread uuid := gen_random_uuid();
+begin
+  -- Only the AT agent needs an auth identity: it is the one OQ-25/26 call acquire_claim as.
+  v_at_user := public.ensure_github_user(
+    'oq-at-' || v_sfx, 'oq-at-' || v_sfx || '@example.test', 'oq-at-' || v_sfx, 'OQ At Quota');
+
+  insert into agent_board.agents(id, agent_type, handle, display_name, status, auth_user_id, owner_user_id)
+  values (v_over,  'agent', 'oq-over-'  || v_sfx, 'OQ Over',      'active',   null,      null),
+         (v_at,    'agent', 'oq-at-'    || v_sfx, 'OQ At Quota',  'active',   v_at_user, v_at_user),
+         (v_under, 'agent', 'oq-under-' || v_sfx, 'OQ Under',     'active',   null,      null),
+         (v_none,  'agent', 'oq-none-'  || v_sfx, 'OQ Non Holder','active',   null,      null),
+         -- Not active. A liveness reader excludes a decommissioned agent; a QUOTA reader must not
+         -- — a suspended agent still holding 52 live leases is the row an operator most needs.
+         (v_susp,  'agent', 'oq-susp-'  || v_sfx, 'OQ Suspended', 'suspended', null,     null);
+
+  -- An ADVISORY board, so one of the UNDER agent's counted claims is governed by the opt-out.
+  -- Inserted directly rather than through set_board_claim_policy: that RPC is owner-gated and
+  -- this file is about the reader, not about who may set the policy (that is BCP's subject).
+  insert into agent_board.boards(id, slug, name, created_by_agent_id, claim_policy)
+  values (v_board, 'oq-adv-' || v_sfx, 'OQ Advisory Board', v_under, 'advisory');
+
+  insert into agent_board.threads(id, thread_type, created_by_agent_id, subject, board_id)
+  values (v_thread, 'coordination', v_under, 'OQ advisory thread', v_board);
+
+  -- Mirrored into GUCs because OQ-25/27 run under `set local role authenticated`, and a temp
+  -- table belongs to the creating role — an authenticated read of _oq raises 42501 rather than
+  -- returning the id, which would abort the transaction and take the rest of the plan with it.
+  perform set_config('_oq.at_user',  v_at_user::text, true);
+  perform set_config('_oq.at_agent', v_at::text,      true);
+
+  insert into _oq values (v_sfx, v_over, v_at, v_under, v_none, v_susp, v_at_user, v_board, v_thread);
+end $$;
+
+-- OVER: quota + 1 active file claims.
+insert into agent_board.claims(agent_id, resource_kind, resource_key, lease_expires_at)
+select (select over_agent from _oq), 'file', 'oq-over-' || (select sfx from _oq) || '-' || g, now() + interval '1 hour'
+  from generate_series(1, agent_board._claimgate_ownerless_quota() + 1) g;
+
+-- AT: exactly quota.
+insert into agent_board.claims(agent_id, resource_kind, resource_key, lease_expires_at)
+select (select at_agent from _oq), 'file', 'oq-at-' || (select sfx from _oq) || '-' || g, now() + interval '1 hour'
+  from generate_series(1, agent_board._claimgate_ownerless_quota()) g;
+
+-- SUSP: quota + 2, held by an agent that is no longer active.
+insert into agent_board.claims(agent_id, resource_kind, resource_key, lease_expires_at)
+select (select susp_agent from _oq), 'tool', 'oq-susp-' || (select sfx from _oq) || '-' || g, now() + interval '1 hour'
+  from generate_series(1, agent_board._claimgate_ownerless_quota() + 2) g;
+
+-- UNDER: three COUNTED claims, one per ownerless kind. The 'custom' one sits on the ADVISORY
+-- board — counted all the same, because the opt-out gates whether the guard RUNS for an
+-- acquisition, not whether the row COUNTS afterwards.
+insert into agent_board.claims(agent_id, thread_id, resource_kind, resource_key, lease_expires_at)
+values
+  ((select under_agent from _oq), null, 'file',   'oq-under-file-'   || (select sfx from _oq), now() + interval '1 hour'),
+  ((select under_agent from _oq), null, 'tool',   'oq-under-tool-'   || (select sfx from _oq), now() + interval '1 hour'),
+  ((select under_agent from _oq), (select adv_thread from _oq), 'custom', 'oq-under-custom-' || (select sfx from _oq), now() + interval '1 hour');
+
+-- UNDER: four NEAR-MISS rows. Each differs from a counted row in EXACTLY ONE conjunct of the
+-- predicate, so dropping that conjunct from the view makes this row count and OQ-6 fails naming
+-- itself. A near-miss that differed in two dimensions would survive a mutation and prove nothing.
+insert into agent_board.claims(agent_id, resource_kind, resource_key, status, released_at, lease_expires_at)
+values
+  -- released_at is null
+  ((select under_agent from _oq), 'file', 'oq-nm-released-' || (select sfx from _oq), 'active',  now(), now() + interval '1 hour'),
+  -- status = 'active'
+  ((select under_agent from _oq), 'file', 'oq-nm-status-'   || (select sfx from _oq), 'expired', null,  now() + interval '1 hour'),
+  -- lease_expires_at > now()
+  ((select under_agent from _oq), 'file', 'oq-nm-lease-'    || (select sfx from _oq), 'active',  null,  now() - interval '1 hour'),
+  -- resource_kind in ('file','tool','custom') — an OWNED kind, governed by the fleet gate and not
+  -- by this quota at all.
+  ((select under_agent from _oq), 'machine', 'oq-nm-kind-'  || (select sfx from _oq), 'active',  null,  now() + interval '1 hour');
+
+-- NONE holds one owned-kind claim and nothing ownerless: it must be a non-holder, not a zero row.
+insert into agent_board.claims(agent_id, resource_kind, resource_key, lease_expires_at)
+values ((select none_agent from _oq), 'repository', 'oq-none-repo-' || (select sfx from _oq), now() + interval '1 hour');
+
+-- The guards start OFF for OQ-20a. Deleted rather than assumed absent: another fixture in the
+-- same database may have set it, and "no row" inferred from a fresh build is exactly the
+-- premise-that-was-already-false shape. Deleting makes the starting regime a fact.
+delete from agent_board.claimgate_enforcement_flags where scope_key = 'ownerless_guards';
+
+-- ---------------------------------------------------------------------------
+-- OQ-1..3: the over-quota agent. The headline case.
+-- ---------------------------------------------------------------------------
+select is(
+  (select active_ownerless_claims from agent_board.v_ownerless_claim_quota where agent_id = (select over_agent from _oq)),
+  agent_board._claimgate_ownerless_quota() + 1,
+  'OQ-1: an agent holding quota+1 active ownerless claims is counted at quota+1');
+
+select is(
+  (select overage from agent_board.v_ownerless_claim_quota where agent_id = (select over_agent from _oq)),
+  1,
+  'OQ-2: and its overage is 1 — the number of claims that exceed the ceiling, which is the convergence question');
+
+select is(
+  (select acquire_blocked from agent_board.v_ownerless_claim_quota where agent_id = (select over_agent from _oq)),
+  true,
+  'OQ-3: and it is acquire_blocked');
+
+-- ---------------------------------------------------------------------------
+-- OQ-4..5: THE ASYMMETRY. Acquire refuses at count >= quota, so an agent holding exactly the
+-- quota is frozen while being over by nothing. Collapsing overage and acquire_blocked into one
+-- boolean answers one of those two questions wrongly; these two assertions on the SAME agent are
+-- what make the distinction load-bearing rather than decorative.
+-- ---------------------------------------------------------------------------
+select is(
+  (select overage from agent_board.v_ownerless_claim_quota where agent_id = (select at_agent from _oq)),
+  0,
+  'OQ-4: an agent at EXACTLY the quota has overage 0 — it exceeds the ceiling by nothing');
+
+select is(
+  (select acquire_blocked from agent_board.v_ownerless_claim_quota where agent_id = (select at_agent from _oq)),
+  true,
+  'OQ-5 THE ASYMMETRY: the same agent is nevertheless acquire_blocked, because acquire refuses at count >= quota — an overage of 0 does NOT mean it can take another lock');
+
+-- ---------------------------------------------------------------------------
+-- OQ-6..9: THE PREDICATE. Three counted claims beside four near-miss rows.
+-- ---------------------------------------------------------------------------
+select is(
+  (select active_ownerless_claims from agent_board.v_ownerless_claim_quota where agent_id = (select under_agent from _oq)),
+  3,
+  'OQ-6 THE PREDICATE: exactly 3 — the released, expired, lease-lapsed and owned-kind rows sitting beside them are each excluded by exactly one conjunct, so dropping any conjunct reads 4 here');
+
+select is(
+  (select file_claims || '/' || tool_claims || '/' || custom_claims
+     from agent_board.v_ownerless_claim_quota where agent_id = (select under_agent from _oq)),
+  '1/1/1',
+  'OQ-7: and all three ownerless kinds are counted — dropping one from the kind list reads 3 counted as 2');
+
+select is(
+  (select claims_on_advisory_boards from agent_board.v_ownerless_claim_quota where agent_id = (select under_agent from _oq)),
+  1,
+  'OQ-8: the advisory-board share is reported SEPARATELY — one of the three sits on a claim_policy=advisory board and is still counted, because the opt-out gates whether the guard RUNS, not whether the row COUNTS');
+
+select is(
+  (select overage::text || '/' || acquire_blocked::text
+     from agent_board.v_ownerless_claim_quota where agent_id = (select under_agent from _oq)),
+  '0/false',
+  'OQ-9: a holder well under the quota is neither over nor blocked — it is still a holder, and OQ-14 depends on that');
+
+-- ---------------------------------------------------------------------------
+-- OQ-10..12: who appears at all.
+-- ---------------------------------------------------------------------------
+select is(
+  (select count(*)::int from agent_board.v_ownerless_claim_quota where agent_id = (select none_agent from _oq)),
+  0,
+  'OQ-10: an agent holding only OWNED-kind claims is not a holder and does not appear — a zero row would inflate the denominator with agents this quota does not govern');
+
+select is(
+  (select agents_active from agent_board.ownerless_quota_census()),
+  (select count(*)::integer from agent_board.agents where status = 'active'),
+  'OQ-11: agents_active is the FLEET, counted from agents — the widest denominator, non-zero even when nobody holds an ownerless claim at all');
+
+select is(
+  (select overage from agent_board.v_ownerless_claim_quota where agent_id = (select susp_agent from _oq)),
+  2,
+  'OQ-12 NO STATUS FILTER: a SUSPENDED agent holding quota+2 live leases appears with its overage — an agent-status filter here would hide precisely the row an operator most needs');
+
+-- ---------------------------------------------------------------------------
+-- OQ-13..16: THE DENOMINATOR. Identities against the view, so they are immune to other fixtures.
+-- ---------------------------------------------------------------------------
+select is(
+  (select agents_holding_ownerless_claims from agent_board.ownerless_quota_census()),
+  (select count(*)::integer from agent_board.v_ownerless_claim_quota),
+  'OQ-13: the summary''s population is counted from the VIEW, not derived from the offender set');
+
+select ok(
+  (select agents_holding_ownerless_claims > agents_over_quota from agent_board.ownerless_quota_census()),
+  'OQ-14 ANTI-VACUOUS: the denominator is STRICTLY greater than the finding — this fixture guarantees a holder that is not an offender, so a denominator derived from the offender set (which would make "0 over, of 0 examined" read as health) fails here');
+
+select is(
+  (select agents_over_quota::text || ' over quota, ' ||
+          agents_acquire_blocked::text || ' acquire-blocked, of ' ||
+          agents_holding_ownerless_claims::text || ' holders'
+     from (select
+             count(*) filter (where overage > 0) as agents_over_quota,
+             count(*) filter (where acquire_blocked) as agents_acquire_blocked,
+             count(*) as agents_holding_ownerless_claims
+           from agent_board.v_ownerless_claim_quota v
+           join agent_board.agents a on a.id = v.agent_id
+          where a.handle like 'oq-%' || (select sfx from _oq)) s),
+  '2 over quota, 3 acquire-blocked, of 4 holders',
+  'OQ-15: scoped to this fixture the reader states its finding WITH its population — over(2) < blocked(3) < holders(4), three numbers a single count could not carry');
+
+select is(
+  (select agents_acquire_blocked from agent_board.ownerless_quota_census()),
+  (select count(*) filter (where acquire_blocked)::integer from agent_board.v_ownerless_claim_quota),
+  'OQ-16: the summary''s acquire_blocked count is the view''s acquire_blocked count');
+
+select is(
+  (select total_overage from agent_board.ownerless_quota_census()),
+  (select coalesce(sum(overage), 0)::integer from agent_board.v_ownerless_claim_quota),
+  'OQ-17: total_overage is the sum of the per-agent overages — the size of the convergence problem, not the number of agents in it');
+
+select is(
+  (select total_active_ownerless_claims from agent_board.ownerless_quota_census()),
+  (select coalesce(sum(active_ownerless_claims), 0)::integer from agent_board.v_ownerless_claim_quota),
+  'OQ-18: total_active_ownerless_claims is the sum of the per-agent counts');
+
+-- ---------------------------------------------------------------------------
+-- OQ-19..20: THE REGIME. "0 over quota" means a different thing with the guards off, so the
+-- summary states the flag and the quota it measured under.
+-- ---------------------------------------------------------------------------
+select is(
+  (select quota from agent_board.ownerless_quota_census()),
+  agent_board._claimgate_ownerless_quota(),
+  'OQ-19: the summary reports the quota it measured against, from the single source acquire uses');
+
+select is(
+  (select guards_enabled from agent_board.ownerless_quota_census()),
+  false,
+  'OQ-20a: with the flag row deleted the summary says the guards are OFF — a count reported without its regime is a fact with no expiry (rule 5)');
+
+insert into agent_board.claimgate_enforcement_flags(scope_key, enabled) values ('ownerless_guards', true)
+  on conflict (scope_key) do update set enabled = true;
+
+select is(
+  (select guards_enabled from agent_board.ownerless_quota_census()),
+  true,
+  'OQ-20b: and it tracks the flag — a hardcoded true or false here would misreport every census run under the other regime');
+
+-- ---------------------------------------------------------------------------
+-- OQ-21..24: SERVICE_ROLE ONLY. Under RLS an authenticated caller sees essentially its OWN
+-- claims, so this view read by that caller returns one row — itself — and the census reports
+-- "1 holder, 0 over quota": a confident, plausible, fleet-shaped answer that is wrong in the
+-- reassuring direction, and the agent sitting at 60 claims is invisible to everyone but itself.
+-- ---------------------------------------------------------------------------
+select ok(
+  (select 'security_invoker=true' = any(c.reloptions)
+     from pg_class c join pg_namespace n on n.oid = c.relnamespace
+    where n.nspname = 'agent_board' and c.relname = 'v_ownerless_claim_quota'),
+  'OQ-21: the view is security_invoker — if the grant is ever widened, rows are still RLS-filtered rather than leaked wholesale');
+
+select ok(
+  (select not p.prosecdef
+     from pg_proc p join pg_namespace n on n.oid = p.pronamespace
+    where n.nspname = 'agent_board' and p.proname = 'ownerless_quota_census'),
+  'OQ-22: the summary is not SECURITY DEFINER either — OQ-21 inspects only the view, so a definer function over an invoker view would silently restore the fleet-wide read this design refuses');
+
+select is(
+  (select coalesce(string_agg(r, ', ' order by r), '')
+     from unnest(array['anon','authenticated','service_role']) r
+    where has_table_privilege(r, 'agent_board.v_ownerless_claim_quota', 'select')),
+  'service_role',
+  'OQ-23 SECURITY: only service_role may read the view — an authenticated reader sees only its own claims and would report a per-caller answer that reads fleet-wide');
+
+select is(
+  (select coalesce(string_agg(r, ', ' order by r), '')
+     from unnest(array['anon','authenticated','service_role']) r
+    where has_function_privilege(r, 'agent_board.ownerless_quota_census()', 'execute')),
+  'service_role',
+  'OQ-24: and the summary is service_role only — a new function is EXECUTE-to-PUBLIC by default, so granting service_role without the REVOKE would leave authenticated holding it through PUBLIC');
+
+-- ---------------------------------------------------------------------------
+-- OQ-25..28: THE OPERATION. Everything above tests the reader against a predicate copied by hand
+-- from acquire_claim. These test it against acquire_claim.
+-- ---------------------------------------------------------------------------
+select set_config('request.jwt.claim.role', 'authenticated', true);
+select set_config('request.jwt.claim.sub', current_setting('_oq.at_user'), true);
+set local role authenticated;
+
+select throws_ok($$
+  select agent_board.acquire_claim(
+    null, 'file', 'oq-at-probe-blocked', now() + interval '1 hour', null, null, '{}'::jsonb)
+$$, '54000', null,
+  'OQ-25 THE OPERATION: the agent OQ-5 called acquire_blocked really is refused by acquire_claim with 54000 — the census agreeing with a hand-copied predicate is not the same as agreeing with the function');
+
+reset role;
+-- Release exactly one, so the agent drops to quota-1 and BOTH answers must flip together.
+update agent_board.claims
+   set released_at = now(), status = 'released'
+ where id = (select id from agent_board.claims
+              where agent_id = (select at_agent from _oq)
+                and resource_kind = 'file'
+                and status = 'active'
+              order by resource_key
+              limit 1);
+
+select is(
+  (select active_ownerless_claims::text || '/' || acquire_blocked::text
+     from agent_board.v_ownerless_claim_quota where agent_id = (select at_agent from _oq)),
+  (agent_board._claimgate_ownerless_quota() - 1)::text || '/false',
+  'OQ-26: releasing one drops the census to quota-1 and clears acquire_blocked');
+
+select set_config('request.jwt.claim.role', 'authenticated', true);
+select set_config('request.jwt.claim.sub', current_setting('_oq.at_user'), true);
+set local role authenticated;
+
+-- lives_ok + a SEPARATE state read (#113): a bare select from a raising RPC aborts the
+-- transaction instead of failing one assertion, and pgTAP then emits no `not ok` at all.
+select lives_ok($$
+  select agent_board.acquire_claim(
+    null, 'file', 'oq-at-probe-allowed', now() + interval '1 hour', null, null, '{}'::jsonb)
+$$, 'OQ-27: and acquire_claim now ALLOWS the acquire the census said was no longer blocked — both answers flipped together');
+
+-- Back to the owning role BEFORE the state read: OQ-28 reads _oq, and it must not be the
+-- assertion that discovers the temp-table permission problem.
+reset role;
+
+select is(
+  (select active_ownerless_claims::text || '/' || acquire_blocked::text
+     from agent_board.v_ownerless_claim_quota where agent_id = (select at_agent from _oq)),
+  agent_board._claimgate_ownerless_quota()::text || '/true',
+  'OQ-28: the state read for OQ-27 — the granted claim is back in the census, at the quota and blocked again');
+
+-- ---------------------------------------------------------------------------
+-- OQ-29: WHEN THE POLICY IS RESOLVED. `claims_on_advisory_boards` calls
+-- _claimgate_board_claim_policy on the claim's thread at QUERY time, so it reports the board's
+-- CURRENT policy — not the policy in force when the claim was acquired, which nothing records.
+-- Reverting a board to 'inherit' therefore empties that column for claims already taken under it,
+-- while the claims themselves keep counting toward the quota.
+--
+-- That is a real operational hole, not a nicety: specs/operations.md listed "acquired on a board
+-- that was advisory and later set back to inherit" as one of three ways an agent ends up over
+-- quota, and pointed the operator at this column to size it — the one population it structurally
+-- cannot see. The column is right; the sentence was wrong, and this assertion is what stops it
+-- growing back. The view CANNOT be fixed to report acquire-time policy, so only the prose can be
+-- made true.
+--
+-- Deliberately the SAME claim OQ-8 read as 1. Nothing about the row changes here; only the board
+-- does. A fresh fixture would prove the number, this proves the RESOLUTION TIME.
+--
+-- Flipped with a direct UPDATE, for the reason the fixture gives at the top of this file:
+-- set_board_claim_policy is owner-gated, and giving UNDER an auth identity plus an owner
+-- 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.
+update agent_board.boards
+   set claim_policy = 'inherit', updated_at = now()
+ where id = (select adv_board from _oq);
+
+select is(
+  (select active_ownerless_claims::text || '/' || claims_on_advisory_boards::text
+     from agent_board.v_ownerless_claim_quota where agent_id = (select under_agent from _oq)),
+  '3/0',
+  'OQ-29 QUERY-TIME RESOLUTION: the claim OQ-8 counted as advisory drops OUT of claims_on_advisory_boards once its board reverts to inherit — the column reports the board''s policy NOW, so claims acquired under an advisory board that was later reverted are invisible to it. Both halves are load-bearing: the claim still counts in active_ownerless_claims, so the column emptying is a re-resolution and not the claim disappearing');
+
+select * from finish();
+rollback;