@consiliency/agent-board-schema 1.48.0 → 1.51.0

package/tests/isolation/specs/claimpolicy_claimrow_lock_order.spec

@@ -0,0 +1,200 @@
+# Consiliency/message-board#405 — the CLAIM-ROW side of the lock order, measured.
+# #405's acceptance names two adjacent paths by name: the thread-insert
+# `FOR KEY SHARE` on `boards` (measured in claimpolicy_writer_keyshare.spec) and
+# `reclaim_fleet_machine`. This is the second one, plus the general question it
+# is an instance of.
+#
+# THE QUESTION. Every path this issue touches now takes the board policy advisory
+# lock and THEN a `claims` row lock: acquire's sweep, renew's UPDATE, and #400's
+# cap reset are all after it. A cycle needs someone going the other way — holding
+# a claims row lock and then wanting the board lock. `reclaim_fleet_machine` is
+# the obvious candidate, because #150 MUST-FIX 2 made it RELEASE the squatter's
+# active machine claim, so it genuinely holds claims row locks while also holding
+# `fleet_machines ... for update`.
+#
+# PERMUTATION 1 — reclaim vs the policy writer. Measured result: NO contention in
+# either direction. Reclaim's rows are `resource_kind = 'machine'` and #400's cap
+# reset touches only the ownerless kinds, so the two hold disjoint rows; and
+# reclaim never enters a policy path, so it never wants the advisory lock. The
+# trace has no `<waiting ...>` at all, which is the observation this permutation
+# exists to record.
+#
+# PERMUTATION 2 — THE PROBE THAT MAKES PERMUTATION 1 EVIDENCE. A permutation that
+# never waits proves nothing on its own: it looks identical to a probe pointed at
+# the wrong subject. So this one CONSTRUCTS the inversion, in the shape #405 asks
+# for (PR #397 injected the reverted lock and observed 40P01). A session takes a
+# plain `select ... for update` on the claim row and THEN calls `renew_claim`,
+# which wants the board lock; the writer holds the board lock and wants that same
+# row through the cap reset. PostgreSQL reports `deadlock detected` — so the cycle
+# is REAL, and permutation 1's silence is a fact about which locks these paths
+# actually take rather than a fact about the probe.
+#
+# AND WHAT IS ACTUALLY TRUE ABOUT REACHING IT, corrected. An earlier version of
+# this paragraph said "no session can assemble permutation 2". That is FALSE, and
+# it was false in two independent ways; both were measured against this bundle
+# rather than argued, and both produced a real `deadlock detected`.
+#
+# It rested on two premises. The first was "no function in agent_board takes a
+# claims row lock (CPR-14)" — but CPR-14 only ever asked about an EXPLICIT
+# locking clause. `update agent_board.claims` takes row locks too, and FIVE
+# functions do it. The ordered premise that does hold is CPR-14a's: of those
+# five, the three that also want the board lock take the BOARD LOCK FIRST, and
+# the other two (reclaim_fleet_machine, release_claim) never want it at all. So
+# no single function inverts. The second premise was privilege: `select … for
+# update` on claims really is refused 42501 to `authenticated` and to
+# `service_role` alike, and `anon` cannot even SELECT (CPR-15/16 run the
+# statement rather than asserting a proxy for it). But that closes only the
+# DIRECT SPELLING.
+#
+# WHAT A SESSION CAN STILL DO IS COMPOSE. A definer function's `update` takes row
+# locks scoped to the CALLING transaction, and they outlive the call. So a
+# multi-statement transaction on a DIRECT database connection assembles the cycle
+# out of granted RPCs, with no table privilege and no hand-written `for update`:
+#
+#   as authenticated:  release_claim(<token>)  then  renew_claim(<other>, …)
+#                      against a concurrent set_board_claim_policy  -> 40P01
+#   as service_role:   renew_claim(<token>, …) then a DIRECT call to
+#                      _claimgate_lock_board_policy               -> 40P01
+#
+# The service_role path is CLOSED as of 20261001000100, which revokes that direct
+# grant (CPR-22 pins the now-empty ACL, CPR-22a pins that the definer callers
+# still work). The authenticated composition remains assemblable.
+#
+# AND IT IS A RESIDUAL ONLY UNDER A STATED ACCESS BOUNDARY. The boundary this
+# repository actually ships, checked rather than assumed: every shipped client
+# reaches the schema through PostgREST via @supabase/supabase-js — there is no
+# direct Postgres driver (`pg`, Pool, a postgresql:// connection) anywhere in
+# packages/*/src or supabase/functions. PostgREST runs one RPC per transaction,
+# and the control below measures that shape as safe. A deployment that adds
+# DIRECT authenticated-role sessions re-opens this; under that deployment it is
+# unclosed rather than residual, and what it yields is 40P01 — a detected
+# deadlock that aborts one side — not an authority bypass or a stale-policy read.
+#
+# SO THE ACCURATE CLAIM IS NARROWER, and it is a claim about the TRANSACTION
+# rather than about privilege. No single RPC can assemble the inversion, and one
+# RPC per transaction — PostgREST's model, which is how every shipped client
+# reaches this schema — is safe. Measured as a control: the identical call
+# sequence with a COMMIT between each RPC produces no deadlock and both calls
+# succeed. Only a caller holding a direct connection across a multi-statement
+# transaction can assemble it, and what it gets is 40P01 — a DETECTED DEADLOCK
+# that aborts one side, not an authority bypass or a stale-policy read. The two
+# shipped paths still agree on board-then-row.
+#
+# The deadlock victim is `w_flip` on every run: it enters the wait first, so its
+# deadlock_timeout fires first and PostgreSQL aborts the detecting backend. That
+# is what makes this golden stable; the ITER=10 gate is what checks the claim.
+
+setup
+{
+  insert into agent_board.claimgate_enforcement_flags(scope_key, enabled) values ('ownerless_guards', true)
+    on conflict (scope_key) do update set enabled = true;
+  insert into auth.users (id) values ('40500000-0000-4000-8000-0000000000f9');
+  insert into agent_board.agents(id, agent_type, kind, handle, display_name, status, auth_user_id, owner_user_id)
+  values ('40500000-0000-4000-8000-000000000009', 'agent', 'agent',
+          'cpr-inv-owner', 'CPR Inversion Owner', 'active',
+          '40500000-0000-4000-8000-0000000000f9', '40500000-0000-4000-8000-0000000000f9');
+  -- The operator and the arbitrated new owner for the reclaim leg.
+  insert into agent_board.agents(id, agent_type, handle, display_name, status, auth_user_id) values
+    ('40500000-0000-4000-8000-00000000000a', 'agent', 'cpr-inv-operator', 'CPR Inversion Operator', 'active', null),
+    ('40500000-0000-4000-8000-00000000000b', 'agent', 'cpr-inv-newowner', 'CPR Inversion New Owner', 'active', null);
+  insert into agent_board.fleet_trust_domains(id, slug, display_name, domain_kind, owner_agent_id, lifecycle_state, approved_at)
+  values ('40500000-0000-4000-8000-0000000000d0', 'cpr-inv-domain', 'CPR Inversion Domain', 'tailnet',
+          '40500000-0000-4000-8000-000000000009', 'active', now());
+  insert into agent_board.fleet_machines(id, trust_domain_id, owner_agent_id, machine_label, machine_fingerprint,
+                                         lifecycle_state, enrollment_source, enrolled_at, revoked_at, metadata)
+  values ('40500000-0000-4000-8000-0000000000c0', '40500000-0000-4000-8000-0000000000d0',
+          '40500000-0000-4000-8000-000000000009', 'cpr-inv-m', 'sha256:cpr-inv-m',
+          'active', 'portal', now(), null, jsonb_build_object('redacted', true, 'metadata-safe', true));
+
+  select count(*) from agent_board.create_board(
+    '40500000-0000-4000-8000-000000000009', 'cpr-inv-board', 'CPR Inversion Board',
+    'message-board#405 claim-row lock-order probe', jsonb_build_object(), 'private');
+  insert into agent_board.threads(id, thread_type, created_by_agent_id, subject, board_id)
+  values ('40500000-0000-4000-8000-000000000090', 'coordination',
+          '40500000-0000-4000-8000-000000000009', 'CPR inversion thread',
+          (select id from agent_board.boards where slug = 'cpr-inv-board'));
+  update agent_board.boards set claim_policy = 'advisory' where slug = 'cpr-inv-board';
+  -- The OWNERLESS claim #400's reset will clamp on the revert.
+  insert into agent_board.claims(id, agent_id, thread_id, resource_kind, resource_key, lease_token, lease_expires_at)
+  values ('40500000-0000-4000-8000-000000000091', '40500000-0000-4000-8000-000000000009',
+          '40500000-0000-4000-8000-000000000090', 'file', 'cpr-inv-key',
+          '40500000-0000-4000-8000-0000000000f8', now() + interval '400 days');
+  -- The MACHINE claim reclaim_fleet_machine releases (#150 MUST-FIX 2). Different kind, so the
+  -- reset never sees it -- which is exactly the disjointness permutation 1 measures.
+  insert into agent_board.claims(id, agent_id, resource_kind, resource_key, lease_token, lease_expires_at)
+  values ('40500000-0000-4000-8000-000000000092', '40500000-0000-4000-8000-000000000009',
+          'machine', 'sha256:cpr-inv-m', '40500000-0000-4000-8000-0000000000f7', now() + interval '1 hour');
+}
+
+teardown
+{
+  delete from agent_board.claims where agent_id in ('40500000-0000-4000-8000-000000000009',
+                                                    '40500000-0000-4000-8000-00000000000b');
+  delete from agent_board.threads where id = '40500000-0000-4000-8000-000000000090';
+  delete from agent_board.board_membership_events where board_id in (
+    select id from agent_board.boards where slug = 'cpr-inv-board');
+  delete from agent_board.board_memberships where board_id in (
+    select id from agent_board.boards where slug = 'cpr-inv-board');
+  delete from agent_board.boards where slug = 'cpr-inv-board';
+  delete from agent_board.fleet_revocation_events where subject_id = '40500000-0000-4000-8000-0000000000c0';
+  delete from agent_board.fleet_machine_agents where machine_id = '40500000-0000-4000-8000-0000000000c0';
+  delete from agent_board.fleet_machines where id = '40500000-0000-4000-8000-0000000000c0';
+  delete from agent_board.fleet_trust_domains where id = '40500000-0000-4000-8000-0000000000d0';
+  delete from agent_board.agents where id in ('40500000-0000-4000-8000-000000000009',
+                                              '40500000-0000-4000-8000-00000000000a',
+                                              '40500000-0000-4000-8000-00000000000b');
+  delete from auth.users where id = '40500000-0000-4000-8000-0000000000f9';
+  delete from agent_board.claimgate_enforcement_flags where scope_key = 'ownerless_guards';
+}
+
+# rc: the operator reclaim. Holds fleet_machines FOR UPDATE and the machine claim's row lock.
+session "rc"
+step "rc_begin"   { BEGIN; SET LOCAL "request.jwt.claim.role" = 'service_role'; }
+step "rc_reclaim" {
+  select owner_agent_id
+    from agent_board.reclaim_fleet_machine(
+      '40500000-0000-4000-8000-0000000000c0', '40500000-0000-4000-8000-00000000000b',
+      '40500000-0000-4000-8000-00000000000a', 'message-board#405 lock-order probe');
+}
+step "rc_commit"  { COMMIT; }
+
+# x: the constructed inversion — a claims row lock taken BEFORE entering renew_claim. Only the
+# connecting role can do this; CPR-14/15/16 pin that no function and no grantable role can.
+session "x"
+step "x_begin"   { BEGIN; }
+step "x_rowlock" { select resource_key from agent_board.claims where id = '40500000-0000-4000-8000-000000000091' for update; }
+step "x_renew"   {
+  SET LOCAL ROLE authenticated;
+  SET LOCAL "request.jwt.claim.role" = 'authenticated';
+  SET LOCAL "request.jwt.claim.sub" = '40500000-0000-4000-8000-0000000000f9';
+  select resource_key
+    from agent_board.renew_claim('40500000-0000-4000-8000-0000000000f8', now() + interval '400 days');
+}
+step "x_commit"  { COMMIT; }
+
+# w: the policy writer. Board advisory lock, then boards FOR NO KEY UPDATE, then the cap reset's
+# UPDATE on this board's ownerless claims.
+session "w"
+step "w_begin"  { BEGIN; SET LOCAL ROLE authenticated; SET LOCAL "request.jwt.claim.role" = 'authenticated'; SET LOCAL "request.jwt.claim.sub" = '40500000-0000-4000-8000-0000000000f9'; }
+step "w_flip"   {
+  select claim_policy
+    from agent_board.set_board_claim_policy(
+           (select id from agent_board.boards where slug = 'cpr-inv-board'), 'inherit');
+}
+step "w_commit" { COMMIT; }
+
+session "chk"
+step "chk" {
+  select (select claim_policy from agent_board.boards where slug = 'cpr-inv-board') as policy,
+         (select owner_agent_id from agent_board.fleet_machines
+           where id = '40500000-0000-4000-8000-0000000000c0') as machine_owner;
+}
+
+# 1. reclaim_fleet_machine holding its claims row locks, and the policy writer running anyway.
+# Disjoint kinds, and reclaim never wants the board lock: no wait in either direction.
+permutation "rc_begin" "rc_reclaim" "w_begin" "w_flip" "rc_commit" "w_commit" "chk"
+
+# 2. The inversion, constructed: claims row lock -> board lock versus board lock -> claims row lock.
+# `deadlock detected` is the point. It is unreachable through any grantable role, which is what
+# makes permutation 1's silence a property of the code rather than of the probe.
+permutation "x_begin" "x_rowlock" "w_begin" "w_flip" "x_renew" "w_commit" "x_commit" "chk"

package/tests/isolation/specs/claimpolicy_isolation_refusal.spec

@@ -0,0 +1,162 @@
+# Consiliency/message-board#405 — the board policy lock REFUSES a transaction
+# that is not READ COMMITTED, rather than being silently inert in one.
+#
+# THE DEPENDENCY THIS PINS. The whole mechanism is "take the lock, then re-read
+# the policy in a NEW statement". That works because under READ COMMITTED each
+# statement takes a fresh snapshot, so the re-read sees what the writer
+# committed while we were waiting. Under REPEATABLE READ and SERIALIZABLE the
+# snapshot is fixed at first use: the wait does not advance it, the re-read
+# returns the SAME stale policy, and the lock is not a guard at all — it is a
+# delay. That failure mode is invisible; nothing errors, nothing waits
+# incorrectly, the caller simply gets the answer the race was supposed to
+# prevent.
+#
+# SO THE DECISION IS REFUSE, NOT DOCUMENT. `_claimgate_lock_board_policy` reads
+# `current_setting('transaction_isolation')` and raises 0A000 naming the level.
+# Nothing in this repository sets another level (a repo-wide search finds only
+# two prose mentions and no code), so this refuses no caller that exists — and
+# if one appears it fails loudly at its first guarded claim instead of quietly
+# banking a horizon.
+#
+# THIS CANNOT BE A pgTAP ASSERTION. `SET TRANSACTION ISOLATION LEVEL` must be a
+# transaction's first statement, and the pgTAP suite is already inside one. An
+# isolation spec is the only place the level can be chosen.
+#
+# THREE PERMUTATIONS, because a refusal that fires everywhere is a different bug
+# from one that fires nowhere:
+#
+#   1. REPEATABLE READ, ownerless claim -> REFUSED, by name.
+#   2. READ COMMITTED, same call        -> SUCCEEDS (the allow side).
+#   3. REPEATABLE READ, 'machine' kind  -> NOT refused. The guard is scoped to
+#      the ownerless region it protects; a fleet-kind acquire never resolves
+#      board policy and must not be collateral damage.
+#
+# MUTATION SIGNAL (verified in the PR): invert the comparison in
+# `_claimgate_lock_board_policy` (`= 'read committed'`) -> permutation 1 succeeds
+# and permutation 2 raises; both halves of the golden move.
+
+setup
+{
+  insert into agent_board.claimgate_enforcement_flags(scope_key, enabled) values ('ownerless_guards', true)
+    on conflict (scope_key) do update set enabled = true;
+  insert into auth.users (id) values ('40500000-0000-4000-8000-0000000000d1');
+  insert into agent_board.agents(id, agent_type, kind, handle, display_name, status, auth_user_id, owner_user_id)
+  values ('40500000-0000-4000-8000-000000000004', 'agent', 'agent',
+          'cpr-iso-owner', 'CPR Isolation Owner', 'active',
+          '40500000-0000-4000-8000-0000000000d1', '40500000-0000-4000-8000-0000000000d1');
+  select count(*) from agent_board.create_board(
+    '40500000-0000-4000-8000-000000000004', 'cpr-iso-board', 'CPR Isolation Board',
+    'message-board#405 isolation-level refusal probe', jsonb_build_object(), 'private');
+  insert into agent_board.threads(id, thread_type, created_by_agent_id, subject, board_id)
+  values ('40500000-0000-4000-8000-000000000050', 'coordination',
+          '40500000-0000-4000-8000-000000000004', 'CPR isolation thread',
+          (select id from agent_board.boards where slug = 'cpr-iso-board'));
+}
+
+teardown
+{
+  delete from agent_board.claims where agent_id = '40500000-0000-4000-8000-000000000004';
+  delete from agent_board.threads where id = '40500000-0000-4000-8000-000000000050';
+  delete from agent_board.board_membership_events where board_id in (
+    select id from agent_board.boards where slug = 'cpr-iso-board');
+  delete from agent_board.board_memberships where board_id in (
+    select id from agent_board.boards where slug = 'cpr-iso-board');
+  delete from agent_board.boards where slug = 'cpr-iso-board';
+  delete from agent_board.agents where id = '40500000-0000-4000-8000-000000000004';
+  delete from auth.users where id = '40500000-0000-4000-8000-0000000000d1';
+  delete from agent_board.claimgate_enforcement_flags where scope_key = 'ownerless_guards';
+}
+
+# rr: a REPEATABLE READ caller. The lease it asks for is WITHIN the cap, so nothing else in the
+# ownerless block would reject it -- the only reason this can fail is the isolation guard.
+session "rr"
+step "rr_begin" { BEGIN ISOLATION LEVEL REPEATABLE READ; SET LOCAL ROLE authenticated; SET LOCAL "request.jwt.claim.role" = 'authenticated'; SET LOCAL "request.jwt.claim.sub" = '40500000-0000-4000-8000-0000000000d1'; }
+step "rr_acq"   {
+  select resource_key
+    from agent_board.acquire_claim(null, 'file', 'cpr-iso-key', now() + interval '1 hour',
+                                  null, '40500000-0000-4000-8000-000000000050');
+}
+# The fleet-kind path never resolves board policy, so it never reaches the guard. A claim with no
+# thread and no board: kind 'machine' is not ownerless, so the guarded region is skipped entirely.
+step "rr_machine" {
+  select resource_key
+    from agent_board.acquire_claim(null, 'machine', 'cpr-iso-machine', now() + interval '1 hour',
+                                  null, null);
+}
+step "rr_rollback" { ROLLBACK; }
+
+# rc: the same call under the level the guard demands.
+session "rc"
+step "rc_begin" { BEGIN; SET LOCAL ROLE authenticated; SET LOCAL "request.jwt.claim.role" = 'authenticated'; SET LOCAL "request.jwt.claim.sub" = '40500000-0000-4000-8000-0000000000d1'; }
+step "rc_acq"   {
+  select resource_key
+    from agent_board.acquire_claim(null, 'file', 'cpr-iso-key', now() + interval '1 hour',
+                                  null, '40500000-0000-4000-8000-000000000050');
+}
+step "rc_commit" { COMMIT; }
+
+# sz: SERIALIZABLE. THE LEVEL THE OLD SPEC LEFT UNPINNED, and the one that matters most. Like
+# REPEATABLE READ, a serializable transaction fixes its snapshot at first use and waiting on the
+# writer's lock does NOT advance it -- so the re-read after the lock returns the SAME stale policy
+# and the advisory lock is silently ineffective rather than failing closed. Admitting this level
+# REOPENS THE RACE this whole issue exists to close.
+#
+# WHY IT NEEDED ITS OWN PERMUTATION. The guard is `<> 'read committed'`, so one permutation under
+# REPEATABLE READ appears to cover its siblings -- but only the levels a permutation NAMES are
+# pinned. Measured: narrowing the guard to `= 'repeatable read'` kept permutation 1 passing and the
+# entire pgTAP suite green while serializable sailed through. That mutation now fails HERE by name,
+# and structurally at CPR-25a.
+session "sz"
+step "sz_begin" { BEGIN ISOLATION LEVEL SERIALIZABLE; SET LOCAL ROLE authenticated; SET LOCAL "request.jwt.claim.role" = 'authenticated'; SET LOCAL "request.jwt.claim.sub" = '40500000-0000-4000-8000-0000000000d1'; }
+step "sz_acq"   {
+  select resource_key
+    from agent_board.acquire_claim(null, 'file', 'cpr-iso-key', now() + interval '1 hour',
+                                  null, '40500000-0000-4000-8000-000000000050');
+}
+step "sz_rollback" { ROLLBACK; }
+
+# ru: READ UNCOMMITTED. A DIFFERENT KIND OF CLAIM, and the difference is deliberate rather than an
+# oversight -- do not collapse this permutation into the one above. PostgreSQL EXECUTES read
+# uncommitted AS read committed (fresh snapshot per statement), so the lock would in fact work at
+# this level: admitting it would NOT reopen the race. What the refusal defends is the guard's
+# one-accepted-spelling CONTRACT, which the migration argues for on the grounds that a guard
+# carrying an equivalence argument has to be re-argued by every reader.
+#
+# So this permutation pins a CONTRACT regression, not a correctness one. It is here because
+# `current_setting('transaction_isolation')` really does report `read uncommitted` distinctly --
+# the GUC preserves the requested spelling even though the engine does not distinguish the
+# behaviour -- which is the only reason a `<> 'read committed'` guard can see it at all.
+session "ru"
+step "ru_begin" { BEGIN ISOLATION LEVEL READ UNCOMMITTED; SET LOCAL ROLE authenticated; SET LOCAL "request.jwt.claim.role" = 'authenticated'; SET LOCAL "request.jwt.claim.sub" = '40500000-0000-4000-8000-0000000000d1'; }
+step "ru_acq"   {
+  select resource_key
+    from agent_board.acquire_claim(null, 'file', 'cpr-iso-key', now() + interval '1 hour',
+                                  null, '40500000-0000-4000-8000-000000000050');
+}
+step "ru_rollback" { ROLLBACK; }
+
+session "chk"
+step "chk" {
+  select coalesce(string_agg(resource_key, ',' order by resource_key), '<none>') as claims
+    from agent_board.claims
+   where agent_id = '40500000-0000-4000-8000-000000000004'
+     and status = 'active' and released_at is null;
+}
+
+# 1. REPEATABLE READ is refused by name, and nothing is written.
+permutation "rr_begin" "rr_acq" "rr_rollback" "chk"
+
+# 2. THE ALLOW SIDE: the identical call under READ COMMITTED succeeds.
+permutation "rc_begin" "rc_acq" "rc_commit" "chk"
+
+# 3. SCOPE: a fleet-kind acquire under REPEATABLE READ never resolves board policy, so it is not
+# refused. A guard that raised on entry to acquire_claim would fail here.
+permutation "rr_begin" "rr_machine" "rr_rollback" "chk"
+
+# 4. SERIALIZABLE is refused by name, and nothing is written. The race-reopening level.
+permutation "sz_begin" "sz_acq" "sz_rollback" "chk"
+
+# 5. READ UNCOMMITTED is refused by name too -- the contract half. PostgreSQL runs this level AS
+# read committed, so this permutation pins the guard's single-accepted-spelling rule rather than a
+# correctness property; see session "ru" for why the two are not the same claim.
+permutation "ru_begin" "ru_acq" "ru_rollback" "chk"

package/tests/isolation/specs/claimpolicy_renew_revert_race.spec

@@ -0,0 +1,150 @@
+# Consiliency/message-board#405 — a renew whose snapshot predates a committed
+# advisory -> inherit revert must neither resolve the stale policy NOR hand back
+# the horizon the revert just clamped.
+#
+# THIS IS #406's OWN RECORDED LIMITATION 3, closed. That header says: "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 ... Recorded as open rather
+# than quietly excluded from the claim."
+#
+# TWO INDEPENDENT PROPERTIES, AND THE SECOND IS THE ONE THAT IS EASY TO GET
+# WRONG.
+#
+#   (1) THE POLICY RE-READ. Without the board lock, r resolves 'advisory', skips
+#       the #373 TTL cap and the #388 convergence clamp, and writes the full
+#       400-day horizon after the revert has committed. `over_cap_lease` reads
+#       that out directly.
+#
+#   (2) THE CLAIM-STATE REVALIDATION. Re-reading only the POLICY moves the race
+#       instead of closing it, because the writer this waits on is
+#       set_board_claim_policy and since #400 that same call CLAMPS this board's
+#       ownerless leases on the revert. The row r read BEFORE the wait is
+#       exactly the row w changed DURING it, and `v_current_expires` — the
+#       baseline the convergence clamp least()s against — would still hold the
+#       pre-clamp horizon. w records the clamped lease in `cpr_renew_mark` while
+#       still uncommitted, and the checker asserts the renew left it EXACTLY
+#       there.
+#
+# WHY THE SECOND SIGNAL IS AN EQUALITY AND NOT A MAGNITUDE. `now()` is
+# transaction time. The reset writes w's `now() + 30 days`; the TTL cap computes
+# r's `now() + 30 days`, and r's transaction starts later, so a stale baseline
+# lets `least()` pick r's clock instead of w's and the lease creeps forward by
+# the gap between the two BEGINs. That gap is real but small, so the checker
+# scores `lease_expires_at = the recorded value` rather than a duration — a
+# boolean is deterministic where a difference of milliseconds is not. The
+# honest reading of that: this property's blast radius is one inter-transaction
+# gap per revert, not a full horizon. Property (1) is the large one; (2) is
+# pinned because "re-read the policy" and "revalidate the claim" are different
+# fixes and only one of them is complete.
+#
+# THE AGENT IS DELIBERATELY OVER QUOTA (quota + 1 active ownerless claims), because
+# the convergence clamp is the only consumer of `v_current_expires`. With the agent
+# at or under the ceiling that clamp never runs and signal (2) cannot exist.
+# The 50 filler claims carry NO thread, so #400's board-scoped reset does not touch
+# them (BCP-14) and the only claim whose lease moves is the one under test.
+#
+# MUTATION SIGNALS, MEASURED — and the first one is not what it was predicted to be:
+#   * delete `perform agent_board._claimgate_lock_board_policy(v_board_id)` from
+#     renew_claim -> over_cap_lease = t, lease_kept_by_revert = f. THE `<waiting ...>`
+#     LINE DOES NOT MOVE. Without the board lock the renew still blocks — later, on the
+#     claims ROW lock #400's cap reset is holding — but it has already resolved the stale
+#     'advisory' by then. A probe that scored the wait rather than the outcome would have
+#     passed this mutation clean, which is why the checker reports state and not timing.
+#   * delete the REVALIDATION select (keeping the lock and the policy re-read)
+#     -> over_cap_lease stays f, lease_kept_by_revert = f. Caught 10 times out of 10, so
+#     the inter-transaction gap this reads out is small but reliably nonzero.
+#
+# THE TWIN: the same renew with no revert at all. The board is advisory, so the
+# opt-out must still work and the 400-day renew must be GRANTED. A guard that
+# over-serialises, or one that resolved every board to 'inherit', passes the race
+# permutation and fails here.
+
+setup
+{
+  insert into agent_board.claimgate_enforcement_flags(scope_key, enabled) values ('ownerless_guards', true)
+    on conflict (scope_key) do update set enabled = true;
+  create table if not exists public.cpr_renew_mark(lease timestamptz);
+  grant select, insert on public.cpr_renew_mark to authenticated;
+  delete from public.cpr_renew_mark;
+  insert into auth.users (id) values ('40500000-0000-4000-8000-0000000000b1');
+  insert into agent_board.agents(id, agent_type, kind, handle, display_name, status, auth_user_id, owner_user_id)
+  values ('40500000-0000-4000-8000-000000000002', 'agent', 'agent',
+          'cpr-ren-owner', 'CPR Renew Owner', 'active',
+          '40500000-0000-4000-8000-0000000000b1', '40500000-0000-4000-8000-0000000000b1');
+  select count(*) from agent_board.create_board(
+    '40500000-0000-4000-8000-000000000002',
+    'cpr-ren-board', 'CPR Renew Board',
+    'message-board#405 renew stale-policy probe', jsonb_build_object(), 'private');
+  insert into agent_board.threads(id, thread_type, created_by_agent_id, subject, board_id)
+  values ('40500000-0000-4000-8000-000000000020', 'coordination',
+          '40500000-0000-4000-8000-000000000002', 'CPR renew thread',
+          (select id from agent_board.boards where slug = 'cpr-ren-board'));
+  update agent_board.boards set claim_policy = 'advisory' where slug = 'cpr-ren-board';
+  -- The claim under test: on the board, holding a horizon only the opt-out could have granted.
+  insert into agent_board.claims(id, agent_id, thread_id, resource_kind, resource_key, lease_token, lease_expires_at)
+  values ('40500000-0000-4000-8000-000000000030', '40500000-0000-4000-8000-000000000002',
+          '40500000-0000-4000-8000-000000000020', 'file', 'cpr-ren-key',
+          '40500000-0000-4000-8000-0000000000f1', now() + interval '400 days');
+  -- Filler that puts the holder OVER quota so the convergence clamp runs. No thread, so the
+  -- board-scoped reset leaves them alone and the only moving lease is the one under test.
+  insert into agent_board.claims(agent_id, resource_kind, resource_key, lease_expires_at)
+  select '40500000-0000-4000-8000-000000000002', 'file', 'cpr-ren-filler-' || g, now() + interval '1 hour'
+    from generate_series(1, agent_board._claimgate_ownerless_quota()) g;
+}
+
+teardown
+{
+  delete from agent_board.claims where agent_id = '40500000-0000-4000-8000-000000000002';
+  delete from agent_board.threads where id = '40500000-0000-4000-8000-000000000020';
+  delete from agent_board.board_membership_events where board_id in (
+    select id from agent_board.boards where slug = 'cpr-ren-board');
+  delete from agent_board.board_memberships where board_id in (
+    select id from agent_board.boards where slug = 'cpr-ren-board');
+  delete from agent_board.boards where slug = 'cpr-ren-board';
+  delete from agent_board.agents where id = '40500000-0000-4000-8000-000000000002';
+  delete from auth.users where id = '40500000-0000-4000-8000-0000000000b1';
+  delete from agent_board.claimgate_enforcement_flags where scope_key = 'ownerless_guards';
+  drop table if exists public.cpr_renew_mark;
+}
+
+# w: the owner reverting the opt-out. w_mark records what #400's reset actually wrote, from inside
+# the still-uncommitted transaction — the value the renew must not move.
+session "w"
+step "w_begin"  { BEGIN; SET LOCAL ROLE authenticated; SET LOCAL "request.jwt.claim.role" = 'authenticated'; SET LOCAL "request.jwt.claim.sub" = '40500000-0000-4000-8000-0000000000b1'; }
+step "w_flip"   {
+  select claim_policy
+    from agent_board.set_board_claim_policy(
+           (select id from agent_board.boards where slug = 'cpr-ren-board'), 'inherit');
+}
+step "w_mark"   {
+  insert into public.cpr_renew_mark(lease)
+  select lease_expires_at from agent_board.claims where id = '40500000-0000-4000-8000-000000000030';
+}
+step "w_commit" { COMMIT; }
+
+# r: the in-flight renew, asking for the full horizon again.
+session "r"
+step "r_begin"  { BEGIN; SET LOCAL ROLE authenticated; SET LOCAL "request.jwt.claim.role" = 'authenticated'; SET LOCAL "request.jwt.claim.sub" = '40500000-0000-4000-8000-0000000000b1'; }
+step "r_renew"  {
+  select resource_key
+    from agent_board.renew_claim('40500000-0000-4000-8000-0000000000f1', now() + interval '400 days');
+}
+step "r_commit" { COMMIT; }
+
+# checker: booleans only. `lease_kept_by_revert` is null in the twin (nothing was marked), which is
+# itself part of the golden.
+session "chk"
+step "chk" {
+  select (c.lease_expires_at > now() + interval '31 days') as over_cap_lease,
+         (c.lease_expires_at = (select m.lease from public.cpr_renew_mark m)) as lease_kept_by_revert
+    from agent_board.claims c
+   where c.id = '40500000-0000-4000-8000-000000000030';
+}
+
+# THE RACE: the renew is issued while the revert is uncommitted.
+permutation "w_begin" "w_flip" "w_mark" "r_begin" "r_renew" "w_commit" "r_commit" "chk"
+
+# THE TWIN: no revert. The board is advisory, the opt-out still works, the 400-day renew is granted
+# and nothing waits.
+permutation "r_begin" "r_renew" "r_commit" "chk"

package/tests/isolation/specs/claimpolicy_writer_keyshare.spec

@@ -0,0 +1,107 @@
+# Consiliency/message-board#405 — the WRITER-SIDE lock-order question, MEASURED
+# rather than argued (PR #397's standard).
+#
+# THE SHAPE OF THE CYCLE THAT WOULD EXIST. `set_board_claim_policy` now takes the
+# board policy advisory lock and THEN wants a row lock on `agent_board.boards`.
+# Any transaction that references that board row -- inserting a thread, a
+# membership, an invite, an inbox item: twelve tables carry an FK to `boards` --
+# holds `FOR KEY SHARE` on it, and if that same transaction then enters an
+# ownerless claim path it wants the advisory lock. advisory -> row versus row ->
+# advisory is a cycle, and #159 is open on lock ordering in this schema, so this
+# is exactly the class that has already produced a revert here (ab38805, a 40P01
+# on a comparable path).
+#
+# WHY IT IS NOT A CYCLE, AND WHY THAT IS AN OBSERVATION AND NOT A CLAIM. #400
+# reads the outgoing policy `for no key update`, which does NOT conflict with
+# `FOR KEY SHARE` -- so the writer never waits on the FK holder, and the wait
+# graph has one edge, not two. This spec drives the arrangement and records that
+# the writer COMPLETES: `t` holds KEY SHARE on the board row, `w` flips the
+# policy anyway, `t`'s acquire then queues on `w`'s advisory lock and proceeds
+# once `w` commits.
+#
+# THE PROBE IS DISCRIMINATING, which is the part that makes it evidence.
+# MUTATION SIGNAL (verified in the PR): change `for no key update` to
+# `for update` in set_board_claim_policy -> `w_flip` prints `<waiting ...>` on
+# t's KEY SHARE, `t_acq` then queues on w's advisory lock, and PostgreSQL
+# reports `ERROR: deadlock detected` (40P01). The same permutation, the same
+# fixture, one lock mode apart. CPR-10 pins the source spelling so the two fail
+# together.
+#
+# THE LEASE IS DELIBERATELY WITHIN THE CAP. This spec is about the wait graph,
+# not about which policy won: the acquire must succeed under either answer, so
+# any diff in the golden is a lock-order diff.
+
+setup
+{
+  insert into agent_board.claimgate_enforcement_flags(scope_key, enabled) values ('ownerless_guards', true)
+    on conflict (scope_key) do update set enabled = true;
+  insert into auth.users (id) values ('40500000-0000-4000-8000-0000000000e1');
+  insert into agent_board.agents(id, agent_type, kind, handle, display_name, status, auth_user_id, owner_user_id)
+  values ('40500000-0000-4000-8000-000000000005', 'agent', 'agent',
+          'cpr-ks-owner', 'CPR KeyShare Owner', 'active',
+          '40500000-0000-4000-8000-0000000000e1', '40500000-0000-4000-8000-0000000000e1');
+  select count(*) from agent_board.create_board(
+    '40500000-0000-4000-8000-000000000005', 'cpr-ks-board', 'CPR KeyShare Board',
+    'message-board#405 writer-side KEY SHARE lock-order probe', jsonb_build_object(), 'private');
+  insert into agent_board.threads(id, thread_type, created_by_agent_id, subject, board_id)
+  values ('40500000-0000-4000-8000-000000000060', 'coordination',
+          '40500000-0000-4000-8000-000000000005', 'CPR keyshare thread',
+          (select id from agent_board.boards where slug = 'cpr-ks-board'));
+  update agent_board.boards set claim_policy = 'advisory' where slug = 'cpr-ks-board';
+}
+
+teardown
+{
+  delete from agent_board.claims where agent_id = '40500000-0000-4000-8000-000000000005';
+  delete from agent_board.threads where id = '40500000-0000-4000-8000-000000000060';
+  delete from agent_board.board_membership_events where board_id in (
+    select id from agent_board.boards where slug = 'cpr-ks-board');
+  delete from agent_board.board_memberships where board_id in (
+    select id from agent_board.boards where slug = 'cpr-ks-board');
+  delete from agent_board.boards where slug = 'cpr-ks-board';
+  delete from agent_board.agents where id = '40500000-0000-4000-8000-000000000005';
+  delete from auth.users where id = '40500000-0000-4000-8000-0000000000e1';
+  delete from agent_board.claimgate_enforcement_flags where scope_key = 'ownerless_guards';
+}
+
+# t: the FK holder. `for key share` is taken directly rather than by inserting a referencing row,
+# because it is EXACTLY the lock mode an FK reference takes and it names the board without dragging
+# a second RPC's own locking into the probe. Taken as the connecting role (not `authenticated`,
+# which holds no UPDATE on boards and so cannot take a row lock at all); the acquire that follows
+# drops into `authenticated`, which is the role the ownerless guards actually run for.
+session "t"
+step "t_begin"    { BEGIN; }
+step "t_keyshare" { select slug from agent_board.boards where slug = 'cpr-ks-board' for key share; }
+step "t_acq"      {
+  SET LOCAL ROLE authenticated;
+  SET LOCAL "request.jwt.claim.role" = 'authenticated';
+  SET LOCAL "request.jwt.claim.sub" = '40500000-0000-4000-8000-0000000000e1';
+  select resource_key
+    from agent_board.acquire_claim(null, 'file', 'cpr-ks-key', now() + interval '1 hour',
+                                  null, '40500000-0000-4000-8000-000000000060');
+}
+step "t_commit"   { COMMIT; }
+
+# w: the policy flip. Takes the advisory lock, then the `for no key update` row lock on the very
+# row t is holding KEY SHARE on.
+session "w"
+step "w_begin"  { BEGIN; SET LOCAL ROLE authenticated; SET LOCAL "request.jwt.claim.role" = 'authenticated'; SET LOCAL "request.jwt.claim.sub" = '40500000-0000-4000-8000-0000000000e1'; }
+step "w_flip"   {
+  select claim_policy
+    from agent_board.set_board_claim_policy(
+           (select id from agent_board.boards where slug = 'cpr-ks-board'), 'inherit');
+}
+step "w_commit" { COMMIT; }
+
+session "chk"
+step "chk" {
+  select coalesce(string_agg(resource_key, ',' order by resource_key), '<none>') as claims,
+         (select claim_policy from agent_board.boards where slug = 'cpr-ks-board') as policy
+    from agent_board.claims
+   where agent_id = '40500000-0000-4000-8000-000000000005'
+     and status = 'active' and released_at is null;
+}
+
+# KEY SHARE held, then the flip, then the acquire. With `for no key update` the writer does not
+# queue behind the FK holder, so there is exactly one wait edge and no cycle.
+permutation "t_begin" "t_keyshare" "w_begin" "w_flip" "t_acq" "w_commit" "t_commit" "chk"