@consiliency/agent-board-schema 1.25.0 → 1.28.0

package/tests/isolation/specs/ledger_authority_revoke.spec

@@ -0,0 +1,290 @@
+# Consiliency/message-board#276 — a board AUTHORITY write reads the fleet revocation ledger
+# under a share lock on the actor's agents row, so a concurrent revoke_fleet_subject('agent')
+# serializes against the write instead of racing it.
+#
+# WHY THIS CANNOT BE A pgTAP FILE. The predicate ("a ledger-revoked grantor is refused") is
+# provable in one transaction and is proved in agent_board_ledger_authority.test.sql. The
+# property THIS file exists for is not the predicate: it is that the read is LOCKED. An
+# unlocked `exists (select 1 from fleet_revocation_events ...)` passes every pgTAP assertion in
+# that file and still leaves the TOCTOU wide open — the authority write reads "not revoked", a
+# revocation commits, and the grant lands anyway. A single rolled-back transaction cannot
+# produce that interleaving. isolationtester prints `<waiting ...>` / `<... completed>` whenever
+# a step blocks, so the lock is a byte in the golden rather than a claim in a comment.
+#
+# THE ADVERSARY IS THE SHIPPED FUNCTION, not a stand-in. `revoke_fleet_subject('agent', X)`
+# (20260901000100:1062) is the exact call the issue is about: it locks the machines X is bound
+# to, then the agents row FOR UPDATE, then the bindings, then writes the agent-subject ledger
+# row. That `agents` FOR UPDATE is what the gate's FOR SHARE conflicts with, and it is the sole
+# reason the two orders below produce different outcomes.
+#
+# BOTH ROUTES ARE DRIVEN, because the whole point of siting the check inside grant_board_role
+# was that the wide `authenticated` door and the narrow signed one could not diverge:
+#   ugrant  — grant_board_role called directly by the authenticated owner. No gateway.
+#   sgrant  — signed_grant_board_role called by the service_role gateway, with a decision
+#             naming a live, owned, verified key so a refusal can only be #276's gate and
+#             never #269's signer revalidation.
+#
+# The check session also reads agents.status: it must stay 'active' throughout. If a future
+# change made fleet revocation flip the status, these permutations would still pass — but for
+# a different reason — and that column in the golden is what makes the substitution visible.
+#
+# MUTATION-VERIFIED: dropping `for share` from _assert_actor_not_fleet_revoked (leaving the
+# ledger read unlocked) changes permutations 2 and 4 — the authority write no longer waits.
+# Clean schema -> byte-identical across 10 runs.
+
+setup
+{
+  insert into auth.users (id) values
+    ('27700000-0000-0000-0000-0000000000a1'),
+    ('27700000-0000-0000-0000-0000000000a2'),
+    ('27700000-0000-0000-0000-0000000000a3');
+
+  insert into agent_board.agents(id, agent_type, kind, handle, display_name, status, auth_user_id)
+  values
+    ('27710000-0000-4000-8000-000000000001','agent','agent','k276iso-owner','K276 ISO Owner','active','27700000-0000-0000-0000-0000000000a1'),
+    ('27710000-0000-4000-8000-000000000002','agent','agent','k276iso-grantee','K276 ISO Grantee','active','27700000-0000-0000-0000-0000000000a2'),
+    ('27710000-0000-4000-8000-000000000003','agent','agent','k276iso-revoker','K276 ISO Revoker','active','27700000-0000-0000-0000-0000000000a3');
+
+  insert into agent_board.boards(id, slug, name, created_by_agent_id, visibility, status)
+  values ('27720000-0000-4000-8000-000000000001','k276-iso-board','K276 ISO Board',
+          '27710000-0000-4000-8000-000000000001','private','active');
+
+  insert into agent_board.board_memberships(board_id, agent_id, role, membership_state, created_by_agent_id)
+  values
+    ('27720000-0000-4000-8000-000000000001','27710000-0000-4000-8000-000000000001','owner','joined','27710000-0000-4000-8000-000000000001'),
+    ('27720000-0000-4000-8000-000000000001','27710000-0000-4000-8000-000000000002','member','joined','27710000-0000-4000-8000-000000000001');
+
+  insert into agent_board.agent_signing_keys(
+    id, agent_id, key_id, key_version, public_key, public_key_format, fingerprint, status, proof_state)
+  values ('27730000-0000-4000-8000-000000000001','27710000-0000-4000-8000-000000000001',
+          'primary', 1, public.test_pubkey('k276-iso'), 'raw_ed25519_base64url',
+          public.test_key_fingerprint('k276-iso'), 'active', 'proven');
+
+  -- A real fleet binding, so revoke_fleet_subject('agent') walks its full path (machine locks,
+  -- agents lock, binding revocation, ledger write) rather than a degenerate one.
+  insert into agent_board.fleet_trust_domains(id, slug, display_name, domain_kind, owner_agent_id, lifecycle_state, approved_at)
+  values ('27740000-0000-4000-8000-000000000001','k276-iso-domain','K276 ISO Domain','tailnet',
+          '27710000-0000-4000-8000-000000000003','active', now());
+  insert into agent_board.fleet_machines(id, trust_domain_id, owner_agent_id, machine_label, machine_fingerprint, lifecycle_state, enrolled_at)
+  values ('27750000-0000-4000-8000-000000000001','27740000-0000-4000-8000-000000000001',
+          '27710000-0000-4000-8000-000000000003','k276-iso-machine','fp-k276-iso','active', now());
+  insert into agent_board.fleet_machine_agents(id, machine_id, agent_id, agent_role, lifecycle_state)
+  values ('27760000-0000-4000-8000-000000000001','27750000-0000-4000-8000-000000000001',
+          '27710000-0000-4000-8000-000000000001','phase_worker','active');
+
+  -- An OUTSTANDING admin link, modelled as a pre-existing row because that is what it is: a
+  -- link minted before its creator was revoked, which the mint gate structurally cannot reach.
+  -- Seeded rather than minted through create_invite_link for two reasons, both mechanical: the
+  -- generated code is random (a golden must not contain one), and board_invite_tokens carries
+  -- a CREATOR-ONLY read policy (board_invite_tokens_creator_read), so a redeem session running
+  -- as `authenticated` cannot look the code up -- it holds the code out of band, as a real
+  -- redeemer does. An earlier revision of this spec did look it up and every redemption failed
+  -- 'invite is not usable' on a null code, which the uniform error made indistinguishable from
+  -- the gate firing. The code is a literal here for exactly that reason.
+  insert into agent_board.board_invite_tokens(
+    code, board_id, preset_role, preset_membership_state, max_uses, expires_at, created_by_agent_id)
+  values ('k276isolink', '27720000-0000-4000-8000-000000000001', 'admin', 'joined', 5,
+          now() + interval '2 days', '27710000-0000-4000-8000-000000000001');
+}
+
+teardown
+{
+  delete from agent_board.signature_evidence
+   where agent_id in (select id from agent_board.agents where handle like 'k276iso-%');
+  delete from agent_board.board_invite_redemptions
+   where invite_id in (select id from agent_board.board_invite_tokens
+                        where board_id = '27720000-0000-4000-8000-000000000001');
+  delete from agent_board.board_invite_tokens
+   where board_id = '27720000-0000-4000-8000-000000000001';
+  delete from agent_board.board_membership_events
+   where board_id = '27720000-0000-4000-8000-000000000001';
+  delete from agent_board.fleet_revocation_events
+   where agent_id in (select id from agent_board.agents where handle like 'k276iso-%')
+      or subject_id in (select id from agent_board.agents where handle like 'k276iso-%')
+      or revoked_by_agent_id in (select id from agent_board.agents where handle like 'k276iso-%');
+  delete from agent_board.fleet_machine_agents where id='27760000-0000-4000-8000-000000000001';
+  delete from agent_board.fleet_machines where id='27750000-0000-4000-8000-000000000001';
+  delete from agent_board.fleet_trust_domains where id='27740000-0000-4000-8000-000000000001';
+  delete from agent_board.agent_signing_keys
+   where agent_id in (select id from agent_board.agents where handle like 'k276iso-%');
+  delete from agent_board.board_authority_ceilings where board_id='27720000-0000-4000-8000-000000000001';
+  delete from agent_board.board_memberships where board_id='27720000-0000-4000-8000-000000000001';
+  delete from agent_board.boards where id='27720000-0000-4000-8000-000000000001';
+  delete from agent_board.agents where handle like 'k276iso-%';
+  delete from auth.users where id in (
+    '27700000-0000-0000-0000-0000000000a1',
+    '27700000-0000-0000-0000-0000000000a2',
+    '27700000-0000-0000-0000-0000000000a3');
+}
+
+# The WIDE door: the authenticated owner calling the chokepoint directly, no gateway involved.
+session "ugrant"
+step "ugrant_begin" {
+  BEGIN;
+  SET LOCAL ROLE authenticated;
+  SET LOCAL "request.jwt.claim.role" = 'authenticated';
+  SET LOCAL "request.jwt.claim.sub" = '27700000-0000-0000-0000-0000000000a1';
+}
+step "ugrant_grant" {
+  select g.role as granted_role
+    from agent_board.grant_board_role(
+      '27720000-0000-4000-8000-000000000001',
+      '27710000-0000-4000-8000-000000000002',
+      'admin') g;
+}
+step "ugrant_commit" { COMMIT; }
+
+# The NARROW door. Only the deterministic column is selected -- signature_evidence_id is a
+# fresh uuid and a golden must not contain a random value.
+session "sgrant"
+step "sgrant_begin" { BEGIN; SET LOCAL "request.jwt.claim.role" = 'service_role'; }
+step "sgrant_grant" {
+  select w.role as granted_role
+    from agent_board.signed_grant_board_role(
+      jsonb_build_object(
+        'p_board_id', '27720000-0000-4000-8000-000000000001',
+        'p_agent_id', '27710000-0000-4000-8000-000000000002',
+        'p_grantee_role', 'admin'),
+      jsonb_build_object(
+        'agent_id', '27710000-0000-4000-8000-000000000001',
+        'signing_key_id', '27730000-0000-4000-8000-000000000001',
+        'key_id', 'primary',
+        'key_version', 1,
+        'algorithm', 'Ed25519',
+        'verification_status', 'verified',
+        'payload_digest', 'sha256:k276',
+        'enforcement_mode', 'require_for_agent_writes')) w;
+}
+step "sgrant_commit" { COMMIT; }
+
+session "revoke"
+step "revoke_begin" { BEGIN; SET LOCAL "request.jwt.claim.role" = 'service_role'; }
+step "revoke_agent" {
+  select subject_kind
+    from agent_board.revoke_fleet_subject(
+      'agent',
+      '27710000-0000-4000-8000-000000000001',
+      '27710000-0000-4000-8000-000000000003',
+      'k276 iso fleet revocation');
+}
+step "revoke_commit" { COMMIT; }
+
+# The invite MINT half (#276 G3). Locked like the three chokepoints: the actor IS the principal
+# whose authority is being spent, since an admin-preset link is a deferred grant of admin.
+session "mint"
+step "mint_begin" {
+  BEGIN;
+  SET LOCAL ROLE authenticated;
+  SET LOCAL "request.jwt.claim.role" = 'authenticated';
+  SET LOCAL "request.jwt.claim.sub" = '27700000-0000-0000-0000-0000000000a1';
+}
+step "mint_link" {
+  select m.preset_role
+    from agent_board.create_invite_link(
+      '27720000-0000-4000-8000-000000000001', 'admin', 'joined', 5,
+      now() + interval '2 days') m;
+}
+step "mint_commit" { COMMIT; }
+
+# The invite REDEEM half. DELIBERATELY UNLOCKED -- every way of row-locking the creator here
+# closes a cycle (enroll_federated_identity reaches this function holding a boards lock; see the
+# migration header). This session exists to record the ACCEPTED window as bytes rather than
+# prose: with the revocation in flight and uncommitted, the redemption does NOT block and
+# succeeds on its own snapshot. Permutation 6 then shows the very next redemption refused.
+session "redeem"
+step "redeem_begin" {
+  BEGIN;
+  SET LOCAL ROLE authenticated;
+  SET LOCAL "request.jwt.claim.role" = 'authenticated';
+  SET LOCAL "request.jwt.claim.sub" = '27700000-0000-0000-0000-0000000000a2';
+}
+step "redeem_link" {
+  select r.role as redeemed_role
+    from agent_board.redeem_invite_link('k276isolink') r;
+}
+step "redeem_commit" { COMMIT; }
+
+# A SECOND redeemer of the SAME token. Exists to bound the accepted window: two redemptions of
+# one token cannot both sit between their ledger read and their commit, because the token
+# FOR UPDATE is the redeem path's first statement. Permutation 8 drives exactly that.
+session "redeem2"
+step "redeem2_begin" {
+  BEGIN;
+  SET LOCAL ROLE authenticated;
+  SET LOCAL "request.jwt.claim.role" = 'authenticated';
+  SET LOCAL "request.jwt.claim.sub" = '27700000-0000-0000-0000-0000000000a3';
+}
+step "redeem2_link" {
+  select r.role as redeemed_role
+    from agent_board.redeem_invite_link('k276isolink') r;
+}
+step "redeem2_commit" { COMMIT; }
+
+session "check"
+step "check" {
+  select
+    (select role from agent_board.board_memberships
+      where board_id = '27720000-0000-4000-8000-000000000001'
+        and agent_id = '27710000-0000-4000-8000-000000000002') as grantee_role,
+    (select status from agent_board.agents
+      where id = '27710000-0000-4000-8000-000000000001') as owner_status,
+    (select count(*) from agent_board.fleet_revocation_events
+      where subject_kind = 'agent'
+        and subject_id = '27710000-0000-4000-8000-000000000001') as agent_ledger_rows,
+    (select count(*) from agent_board.fleet_machine_agents
+      where agent_id = '27710000-0000-4000-8000-000000000001'
+        and lifecycle_state = 'active') as active_bindings,
+    (select count(*) from agent_board.board_invite_tokens
+      where board_id = '27720000-0000-4000-8000-000000000001'
+        and code <> 'k276isolink') as minted_tokens,
+    (select uses_count from agent_board.board_invite_tokens
+      where code = 'k276isolink') as outstanding_link_uses;
+}
+
+# 1. Write first (UNSIGNED). The revocation must WAIT on the share-locked agents row rather
+#    than committing underneath a grant that has already been authorized. The grant stands and
+#    the revocation lands after it -- a grant that beat the revocation, which is the same
+#    outcome as a grant one millisecond earlier.
+permutation "ugrant_begin" "ugrant_grant" "revoke_begin" "revoke_agent" "ugrant_commit" "revoke_commit" "check"
+
+# 2. THE DEFECT'S OWN INTERLEAVING, unsigned route. The revocation is in flight when the
+#    authority write runs; the write blocks on the agents row, then observes the committed
+#    revocation and fails closed. Before #276 this permutation COMPLETED the grant: the
+#    chokepoint read no ledger at all, so there was nothing to block on and nothing to see.
+permutation "revoke_begin" "revoke_agent" "ugrant_begin" "ugrant_grant" "revoke_commit" "ugrant_commit" "check"
+
+# 3. Write first, SIGNED route. Same property through the gateway wrapper, which reaches the
+#    gate only because the check lives inside the inner chokepoint.
+permutation "sgrant_begin" "sgrant_grant" "revoke_begin" "revoke_agent" "sgrant_commit" "revoke_commit" "check"
+
+# 4. The defect's interleaving through the SIGNED route. #269 already made this wrapper block
+#    on the agents row for a STATUS change; this permutation is what proves it also fails
+#    closed on a LEDGER revocation, which leaves agents.status untouched.
+permutation "revoke_begin" "revoke_agent" "sgrant_begin" "sgrant_grant" "revoke_commit" "sgrant_commit" "check"
+
+# 5. The MINT half, revoke-in-flight. The mint blocks on the creator's agents row, then observes
+#    the committed revocation and fails closed -- and leaves no token, so no code escapes. This
+#    is the permutation the FOR SHARE in _assert_actor_not_fleet_revoked exists for on this path.
+permutation "revoke_begin" "revoke_agent" "mint_begin" "mint_link" "revoke_commit" "mint_commit" "check"
+
+# 6. THE ACCEPTED WINDOW, recorded rather than described. The outstanding link exists, the
+#    revocation is IN FLIGHT and uncommitted, and the redemption does NOT block -- it reads its
+#    own snapshot and succeeds. That is the TOCTOU this migration deliberately accepts on the
+#    redeem path, because every row lock that would close it closes a deadlock cycle instead
+#    (see the header). The check row shows the use consumed; the pgTAP file shows the NEXT
+#    redemption, after the revocation commits, refused.
+permutation "revoke_begin" "revoke_agent" "redeem_begin" "redeem_link" "redeem_commit" "revoke_commit" "check"
+
+# 7. ...and the same interleaving with the revocation COMMITTED first: now the redemption is
+#    refused. The pair is what makes permutation 6 a bounded window rather than an open door.
+permutation "revoke_begin" "revoke_agent" "revoke_commit" "redeem_begin" "redeem_link" "redeem_commit" "check"
+
+# 8. THE RESIDUAL BOUND, driven rather than argued. Two redeemers of the SAME token with the
+#    revocation in flight: the first reads the ledger before the revocation commits and slips
+#    through; the second BLOCKS on the token row -- board_invite_tokens FOR UPDATE is the redeem
+#    path's first statement -- and by the time it proceeds the revocation has committed, so its
+#    own ledger read refuses it. That is why the disclosure says "at most one redemption per
+#    outstanding token" and not "one redemption": tokens serialise redemptions of themselves,
+#    but a creator holding K links has K independent windows. outstanding_link_uses = 1 in the
+#    check row is the byte that says exactly one slipped.
+permutation "revoke_begin" "revoke_agent" "redeem_begin" "redeem_link" "redeem2_begin" "redeem2_link" "revoke_commit" "redeem_commit" "redeem2_commit" "check"

package/tests/isolation/specs/signed_grant_onboarding_deadlock.spec

@@ -0,0 +1,159 @@
+# Consiliency/message-board#269 (F4) — signed_grant_board_role must be ACYCLIC against
+# onboard_federated_fleet_agent.
+#
+# THE DEFECT. The grant wrapper's lock order was
+#     board_memberships(grantee, via the inner grant's UPDATE) -> agents(signer, FOR SHARE)
+# while onboard_federated_fleet_agent takes
+#     agents(20260901000110:349, FOR UPDATE) -> board_memberships(:397, FOR UPDATE)
+# — the opposite order, with no advisory lock on the grant side to serialize them. That is an
+# ABBA cycle between two HONEST callers: a board owner who created a fleet invite while
+# concurrently granting the enrollee a role. Both operands are routine on one board (the
+# collision needs enrolling agent == grantee and invite creator == signer). Reproduced before
+# the fix as a live `ERROR: deadlock detected ... while locking tuple in relation
+# "board_memberships"`, with the real wrapper on one side.
+#
+# THE FIX this spec pins: the wrapper takes the board-keyed _lock_board_authority_ceiling
+# advisory lock FIRST. Both authority wrappers now take it before anything else, and onboarding
+# takes it at :290 holding only board_invite_tokens and fleet_onboarding_invite_bounds — rows no
+# authority wrapper ever touches — so the transactions are serialized per board rather than
+# merely ordered. Mutual exclusion survives a new lock being added downstream; an ordering
+# argument would have to be re-derived each time.
+#
+# THE "onboard" SESSION IS A LOCK-EQUIVALENT STAND-IN, and here is the equivalence, stated the
+# way this suite requires rather than assumed.
+#   * It runs onboard_federated_fleet_agent's three cycle-relevant acquisitions, in its order
+#     and its modes: _lock_board_authority_ceiling(board) (:290), then `agents ... for update`
+#     (:349), then `board_memberships ... for update` (:397).
+#   * It omits that function's other locks — board_invite_tokens, fleet_onboarding_invite_bounds,
+#     boards, fleet_machines, fleet_trust_domains, the fingerprint-keyed advisory, auth.users,
+#     board_authority_ceilings, board_invite_redemptions, and the enrolled agent's own agents/
+#     agent_signing_keys rows. Every one of those is on a relation the grant wrapper never
+#     touches, so none can participate in a cycle with it; including them would change nothing
+#     observable and would require provisioning a full fleet invite, machine, trust domain and
+#     PoP-verified identity inside an isolation setup block.
+#   * A full onboarding replay was rejected for that reason alone, not because it would fail.
+#     The claim under test is a LOCK ORDER, and these are the locks.
+#   THE ADVISORY ACQUISITION IN THIS SESSION IS LOAD-BEARING, not decoration. Drop it and this
+#   spec deadlocks even against the FIXED wrapper — the stand-in would hold agents(signer) while
+#   taking no advisory lock, so the wrapper would sail through its own advisory acquisition and
+#   into the same cycle. A reader who "simplifies" this session by deleting the advisory step is
+#   not testing onboarding; they are testing a caller that does not exist, and they will read the
+#   resulting deadlock as a failed fix.
+#
+# WHY THE EXISTING signer_lifecycle_revoke.spec DOES NOT COVER THIS. Its three adversaries are
+# revoke_agent_subtree, a bare suspend, and a key-only update. NONE of them takes a
+# board_memberships lock, and board_memberships is one of the two operands in this cycle, so its
+# green golden is silent here. That is why this is a separate spec rather than a permutation
+# added there.
+
+setup
+{
+  insert into agent_board.agents(id, agent_type, kind, handle, display_name, status)
+  values
+    ('f4940000-0000-4000-8000-000000000001','agent','agent','f4iso-signer','F4 ISO Signer/Creator','active'),
+    ('f4940000-0000-4000-8000-000000000002','agent','agent','f4iso-grantee','F4 ISO Grantee/Enrollee','active');
+
+  insert into agent_board.boards(id, slug, name, created_by_agent_id, visibility, status)
+  values ('f4950000-0000-4000-8000-000000000001','f4-iso-board','F4 ISO Board',
+          'f4940000-0000-4000-8000-000000000001','private','active');
+
+  insert into agent_board.board_memberships(board_id, agent_id, role, membership_state, created_by_agent_id)
+  values
+    ('f4950000-0000-4000-8000-000000000001','f4940000-0000-4000-8000-000000000001','owner','joined','f4940000-0000-4000-8000-000000000001'),
+    ('f4950000-0000-4000-8000-000000000001','f4940000-0000-4000-8000-000000000002','member','joined','f4940000-0000-4000-8000-000000000001');
+
+  insert into agent_board.agent_signing_keys(
+    id, agent_id, key_id, key_version, public_key, public_key_format, fingerprint, status, proof_state)
+  values ('f4960000-0000-4000-8000-000000000001','f4940000-0000-4000-8000-000000000001',
+          'primary', 1, public.test_pubkey('f4-iso'), 'raw_ed25519_base64url',
+          public.test_key_fingerprint('f4-iso'), 'active', 'proven');
+}
+
+teardown
+{
+  delete from agent_board.signature_evidence
+   where agent_id in (select id from agent_board.agents where handle like 'f4iso-%');
+  delete from agent_board.board_authority_ceilings where board_id='f4950000-0000-4000-8000-000000000001';
+  delete from agent_board.board_memberships where board_id='f4950000-0000-4000-8000-000000000001';
+  delete from agent_board.boards where id='f4950000-0000-4000-8000-000000000001';
+  delete from agent_board.agent_signing_keys
+   where agent_id in (select id from agent_board.agents where handle like 'f4iso-%');
+  delete from agent_board.agents where handle like 'f4iso-%';
+}
+
+# The real signed authority write, unmodified. Only the deterministic column is selected: the
+# evidence id is a fresh uuid and must never reach a golden.
+session "auth"
+step "auth_begin" { BEGIN; SET LOCAL "request.jwt.claim.role" = 'service_role'; }
+step "auth_grant" {
+  select w.role as granted_role
+    from agent_board.signed_grant_board_role(
+      jsonb_build_object(
+        'p_board_id', 'f4950000-0000-4000-8000-000000000001',
+        'p_agent_id', 'f4940000-0000-4000-8000-000000000002',
+        'p_grantee_role', 'admin'),
+      jsonb_build_object(
+        'agent_id', 'f4940000-0000-4000-8000-000000000001',
+        'signing_key_id', 'f4960000-0000-4000-8000-000000000001',
+        'key_id', 'primary',
+        'key_version', 1,
+        'algorithm', 'Ed25519',
+        'verification_status', 'verified',
+        'payload_digest', 'sha256:f4iso',
+        'enforcement_mode', 'require_for_agent_writes')) w;
+}
+step "auth_commit" { COMMIT; }
+
+# onboard_federated_fleet_agent's cycle-relevant locks, in its order and modes. See the header
+# for the equivalence argument; the advisory step is load-bearing.
+session "onboard"
+step "onboard_begin" { BEGIN; SET LOCAL "request.jwt.claim.role" = 'service_role'; }
+step "onboard_advisory" {
+  select agent_board._lock_board_authority_ceiling('f4950000-0000-4000-8000-000000000001') is null as advisory_taken;
+}
+step "onboard_agents" {
+  select count(*)::int as locked_agents from (
+    select 1 from agent_board.agents a
+     where a.id = 'f4940000-0000-4000-8000-000000000001' for update) s;
+}
+step "onboard_membership" {
+  select count(*)::int as locked_memberships from (
+    select 1 from agent_board.board_memberships bm
+     where bm.board_id = 'f4950000-0000-4000-8000-000000000001'
+       and bm.agent_id = 'f4940000-0000-4000-8000-000000000002'
+     order by bm.id for update) s;
+}
+step "onboard_commit" { COMMIT; }
+
+session "check"
+step "check" {
+  select
+    (select role from agent_board.board_memberships
+      where board_id = 'f4950000-0000-4000-8000-000000000001'
+        and agent_id = 'f4940000-0000-4000-8000-000000000002') as grantee_role,
+    (select count(*)::int from agent_board.signature_evidence
+      where operation = 'grant_board_role'
+        and agent_id = 'f4940000-0000-4000-8000-000000000001') as evidence_rows;
+}
+
+# 1. THE CYCLE, in the order that produced the deadlock. onboard takes the advisory lock and
+#    then the signer's agents row; the wrapper then runs. UNFIXED, the wrapper acquires the
+#    grantee membership row (its inner UPDATE) and blocks wanting agents FOR SHARE, onboard
+#    then wants that same membership row, and the server aborts one of them with `deadlock
+#    detected`. FIXED, the wrapper blocks at its FIRST statement — the advisory lock onboard
+#    already holds — so it holds nothing, onboard completes, and the grant proceeds after.
+#    The difference between those two worlds is the whole golden.
+permutation "onboard_begin" "onboard_advisory" "onboard_agents" "auth_begin" "auth_grant" "onboard_membership" "onboard_commit" "auth_commit" "check"
+
+# 2. The same operands with the wrapper first. It holds the advisory lock, so onboard waits at
+#    its OWN first step and never reaches the rows; once the wrapper commits, onboard proceeds.
+#    auth_commit is scheduled while onboard is still waiting on purpose — with it ordered after
+#    onboard's row steps the wait is unresolvable and isolationtester cancels the step, which
+#    records a `canceling statement due to user request` in the golden rather than the
+#    serialization this permutation exists to show.
+permutation "auth_begin" "auth_grant" "onboard_begin" "onboard_advisory" "auth_commit" "onboard_agents" "onboard_membership" "onboard_commit" "check"
+
+# 3. onboard holds the advisory lock alone, with no row locks yet. The wrapper must still block
+#    on it — this is what proves the acquisition is FIRST in the wrapper rather than merely
+#    present somewhere in it.
+permutation "onboard_begin" "onboard_advisory" "auth_begin" "auth_grant" "onboard_agents" "onboard_membership" "onboard_commit" "auth_commit" "check"

package/tests/isolation/specs/signer_lifecycle_revoke.spec

@@ -0,0 +1,186 @@
+# Consiliency/message-board#269 — a signed AUTHORITY write revalidates its signer inside
+# its OWN transaction, and the lifecycle rows it reads are share-locked so a concurrent
+# revoke/suspend serializes against the mutation instead of racing it.
+#
+# WHY THIS CANNOT BE A pgTAP FILE. The defect is a window BETWEEN two committed
+# transactions: Portal verifies the signature and reads lifecycle in one PostgREST call,
+# a revocation commits, and the wrapper runs in a second call. A pgTAP file is one
+# rolled-back transaction and can only reach the predicate ("a suspended signer is
+# refused"), never the interleaving or the blocking. Both are the point here, and both are
+# observable in the trace: isolationtester prints `<waiting ...>` / `<... completed>`
+# whenever a step blocks, so the lock is a byte in the golden rather than a claim.
+#
+# THE THREE ADVERSARIES, and why each is the real thing and not a stand-in.
+#   revoke_agent_subtree  — the shipped cascade. Its primitive _revoke_agent_principal
+#                           (20260901000100:1277, the NEWEST definition) locks the agents
+#                           row FOR UPDATE and then the signing keys, which is why this
+#                           helper takes agents first: matching the transaction the gate
+#                           exists to serialize against is what keeps the order acyclic.
+#   suspend               — a bare `update agent_board.agents set status='suspended'`. This
+#                           is lock-identical to the platform-admin RPC revoke_agent
+#                           (20260512000000:569), whose suspension is likewise a plain
+#                           UPDATE of a non-key column taking FOR NO KEY UPDATE. It is used
+#                           directly only to avoid provisioning a platform-admin JWT inside
+#                           an isolation session; the lock interaction under test is the
+#                           same byte for byte.
+#   keyrevoke             — a key-only `update agent_board.agent_signing_keys set
+#                           status='revoked'...`, which is the UPDATE statement
+#                           revoke_fleet_subject's signing_key branch runs, minus the agent
+#                           row lock that function takes first. Every shipped key-revoking
+#                           path locks the agent first, so only a key-ONLY writer can pin
+#                           the agent_signing_keys FOR SHARE at all -- and it must be a
+#                           PLAIN update. issue_signing_key_challenge was tried here and
+#                           rejected: it takes FOR UPDATE on the key, which also conflicts
+#                           with the FOR KEY SHARE the evidence row's foreign key already
+#                           takes, so it blocks whether or not this change exists and
+#                           distinguishes nothing. A plain UPDATE takes FOR NO KEY UPDATE,
+#                           which the FK's KEY SHARE does NOT block and FOR SHARE does --
+#                           so this session, and only this session, makes the key lock and
+#                           its MODE observable. The table's UPDATE privilege is the
+#                           owner's alone (service_role has SELECT), so this models
+#                           owner-level incident DML and any future key-only writer.
+#
+# GOLDEN CHANGE IN #276, recorded so it is not read as a #269 regression. Permutation 2's
+# refusal line moved from `signer_not_active` to `fleet_revoked`. `revoke_agent_subtree`'s
+# primitive produces BOTH conditions at once — it flips agents.status AND writes an
+# agent-subject fleet_revocation_events row — and #276's gate, which lives inside
+# grant_board_role, now runs before _assert_signed_authority_signer_live and wins the race to
+# raise. The blocking behaviour this permutation exists for is unchanged (`<waiting ...>` /
+# `<... completed>` are byte-identical), and `signer_not_active` is still exercised
+# EXCLUSIVELY by permutations 3 and 4, whose `suspend` session touches only agents.status and
+# writes no ledger row. Nothing here stopped being pinned.
+
+setup
+{
+  insert into agent_board.agents(id, agent_type, kind, handle, display_name, status)
+  values
+    ('26940000-0000-4000-8000-000000000001','agent','agent','k269iso-signer','K269 ISO Signer','active'),
+    ('26940000-0000-4000-8000-000000000002','agent','agent','k269iso-grantee','K269 ISO Grantee','active'),
+    ('26940000-0000-4000-8000-000000000003','agent','agent','k269iso-revoker','K269 ISO Revoker','active');
+
+  insert into agent_board.boards(id, slug, name, created_by_agent_id, visibility, status)
+  values ('26950000-0000-4000-8000-000000000001','k269-iso-board','K269 ISO Board',
+          '26940000-0000-4000-8000-000000000001','private','active');
+
+  insert into agent_board.board_memberships(board_id, agent_id, role, membership_state, created_by_agent_id)
+  values
+    ('26950000-0000-4000-8000-000000000001','26940000-0000-4000-8000-000000000001','owner','joined','26940000-0000-4000-8000-000000000001'),
+    ('26950000-0000-4000-8000-000000000001','26940000-0000-4000-8000-000000000002','member','joined','26940000-0000-4000-8000-000000000001');
+
+  insert into agent_board.agent_signing_keys(
+    id, agent_id, key_id, key_version, public_key, public_key_format, fingerprint, status, proof_state)
+  values ('26960000-0000-4000-8000-000000000001','26940000-0000-4000-8000-000000000001',
+          'primary', 1, public.test_pubkey('k269-iso'), 'raw_ed25519_base64url',
+          public.test_key_fingerprint('k269-iso'), 'active', 'proven');
+}
+
+teardown
+{
+  delete from agent_board.signature_evidence
+   where agent_id in (select id from agent_board.agents where handle like 'k269iso-%');
+  delete from agent_board.agent_signing_key_challenges
+   where agent_id in (select id from agent_board.agents where handle like 'k269iso-%');
+  delete from agent_board.fleet_revocation_events
+   where agent_id in (select id from agent_board.agents where handle like 'k269iso-%')
+      or revoked_by_agent_id in (select id from agent_board.agents where handle like 'k269iso-%');
+  delete from agent_board.board_authority_ceilings where board_id='26950000-0000-4000-8000-000000000001';
+  delete from agent_board.board_memberships where board_id='26950000-0000-4000-8000-000000000001';
+  delete from agent_board.boards where id='26950000-0000-4000-8000-000000000001';
+  delete from agent_board.agent_signing_keys
+   where agent_id in (select id from agent_board.agents where handle like 'k269iso-%');
+  delete from agent_board.agents where handle like 'k269iso-%';
+}
+
+# The signed authority write. The signature_evidence_id it returns is a fresh uuid, so only
+# the deterministic column is selected — a golden must not contain a random value.
+session "auth"
+step "auth_begin" { BEGIN; SET LOCAL "request.jwt.claim.role" = 'service_role'; }
+step "auth_grant" {
+  select w.role as granted_role
+    from agent_board.signed_grant_board_role(
+      jsonb_build_object(
+        'p_board_id', '26950000-0000-4000-8000-000000000001',
+        'p_agent_id', '26940000-0000-4000-8000-000000000002',
+        'p_grantee_role', 'admin'),
+      jsonb_build_object(
+        'agent_id', '26940000-0000-4000-8000-000000000001',
+        'signing_key_id', '26960000-0000-4000-8000-000000000001',
+        'key_id', 'primary',
+        'key_version', 1,
+        'algorithm', 'Ed25519',
+        'verification_status', 'verified',
+        'payload_digest', 'sha256:k269',
+        'enforcement_mode', 'require_for_agent_writes')) w;
+}
+step "auth_commit" { COMMIT; }
+
+session "revoke"
+step "revoke_begin" { BEGIN; SET LOCAL "request.jwt.claim.role" = 'service_role'; }
+step "revoke_signer" {
+  select revoked_agent_count, revoked_key_count
+    from agent_board.revoke_agent_subtree(
+      '26940000-0000-4000-8000-000000000001',
+      '26940000-0000-4000-8000-000000000003',
+      'k269 iso revoke');
+}
+step "revoke_commit" { COMMIT; }
+
+session "suspend"
+step "suspend_begin" { BEGIN; SET LOCAL "request.jwt.claim.role" = 'service_role'; }
+step "suspend_signer" {
+  update agent_board.agents set status = 'suspended', updated_at = now()
+   where id = '26940000-0000-4000-8000-000000000001';
+}
+step "suspend_commit" { COMMIT; }
+
+# Key-only writer: a PLAIN update of the signing key, touching no agents row.
+session "keyrevoke"
+step "keyrevoke_begin" { BEGIN; SET LOCAL "request.jwt.claim.role" = 'service_role'; }
+step "keyrevoke_key" {
+  update agent_board.agent_signing_keys
+     set status = 'revoked', proof_state = 'revoked', revoked_at = now(), updated_at = now()
+   where id = '26960000-0000-4000-8000-000000000001';
+}
+step "keyrevoke_commit" { COMMIT; }
+
+session "check"
+step "check" {
+  select
+    (select role from agent_board.board_memberships
+      where board_id = '26950000-0000-4000-8000-000000000001'
+        and agent_id = '26940000-0000-4000-8000-000000000002') as grantee_role,
+    (select status from agent_board.agents
+      where id = '26940000-0000-4000-8000-000000000001') as signer_status,
+    (select status from agent_board.agent_signing_keys
+      where id = '26960000-0000-4000-8000-000000000001') as key_status,
+    (select count(*) from agent_board.signature_evidence
+      where operation = 'grant_board_role') as evidence_rows;
+}
+
+# 1. Write first: the revocation must WAIT on the share-locked lifecycle rows rather than
+#    committing underneath a grant that has already been authorized. The grant stands and
+#    the revocation lands after it.
+permutation "auth_begin" "auth_grant" "revoke_begin" "revoke_signer" "auth_commit" "revoke_commit" "check"
+
+# 2. The defect's own interleaving, in the order that exposes it. The revocation is in
+#    flight when the wrapper runs; the wrapper blocks on the agents row, then observes the
+#    committed revocation and fails closed. Before #269 this permutation completed the
+#    grant: the wrapper read no lifecycle at all, so there was nothing to block on.
+permutation "revoke_begin" "revoke_signer" "auth_begin" "auth_grant" "revoke_commit" "auth_commit" "check"
+
+# 3. Suspension, which touches the agents row and NOT the key — so it isolates the agents
+#    FOR SHARE from the key FOR SHARE.
+permutation "suspend_begin" "suspend_signer" "auth_begin" "auth_grant" "suspend_commit" "auth_commit" "check"
+
+# 4. Suspension the other way round: the write holds the agents row and the suspension waits.
+permutation "auth_begin" "auth_grant" "suspend_begin" "suspend_signer" "auth_commit" "suspend_commit" "check"
+
+# 5. The key half, isolated. Nothing here touches the agents row, so the wait is produced by
+#    the agent_signing_keys FOR SHARE and by nothing else -- and by its MODE: FOR KEY SHARE
+#    would not conflict with this plain UPDATE's FOR NO KEY UPDATE.
+permutation "auth_begin" "auth_grant" "keyrevoke_begin" "keyrevoke_key" "auth_commit" "keyrevoke_commit" "check"
+
+# 6. And the key revocation's own race: revoked in flight, the authority write blocks on the
+#    key row, then observes the committed revocation and fails closed -- the key-side twin of
+#    permutation 2.
+permutation "keyrevoke_begin" "keyrevoke_key" "auth_begin" "auth_grant" "keyrevoke_commit" "auth_commit" "check"