@consiliency/agent-board-schema 1.25.0 → 1.27.0

package/fixtures/already-applied.json

@@ -500,6 +500,10 @@
     {
       "id": "20260907000100_agent_board_signed_authority_provenance",
       "sha256": "21111e289e0bb70ac3236f5422476c0c51d0bca5a815c11dd4e48b6932cf7c6b"
+    },
+    {
+      "id": "20260908000100_agent_board_signer_lifecycle_revalidation",
+      "sha256": "bfb1ae60f69dae0a0aaf1007dbf14e171f324cdced1caf9f4d490f41a60c14e5"
     }
   ]
 }

package/migrations/20260908000100_agent_board_signer_lifecycle_revalidation.sql

@@ -0,0 +1,451 @@
+-- #269 — atomic signer-lifecycle revalidation for the two signed AUTHORITY wrappers.
+--
+-- WHAT THIS CLOSES. Portal verifies the Ed25519 signature, reads agents.status and the
+-- signing key's lifecycle, and reserves replay — then calls
+-- agent_board.signed_grant_board_role / signed_set_board_authority_ceiling in a SEPARATE
+-- PostgREST round trip. A suspension or key revocation that commits between those two calls
+-- is invisible to the wrapper: #247 (20260907000100) binds the gateway-verified actor and
+-- rechecks BOARD authority, but reads nothing about the SIGNER's own lifecycle. Enumerated
+-- from the shipped source rather than from memory: neither wrapper mentions agents.status,
+-- agent_signing_keys, proof_state or expires_at. So a revoked or suspended owner completes an
+-- authority mutation inside that window. Portal cannot make verification and the wrapper call
+-- one transaction across two HTTP calls; the fix is schema-owned.
+--
+-- WHERE THE CHECK LIVES, AND WHY NOT IN _signed_write_actor_id.
+-- _signed_write_actor_id (20260710000000) is the shared chokepoint of SEVEN wrappers
+-- (enumerated from pg_proc: the five message/task wrappers of 20260628000003 and
+-- 20260711000100, plus the two #247 authority wrappers). Extending IT is the tempting move
+-- and it is wrong, for a reason that is empirical rather than stylistic: Portal's
+-- dispatchSignedWrite still calls the three message wrappers when the write is NOT verified
+-- and the enforcement mode allows unsigned (`observe`), with a decision whose signing_key_id
+-- is null. A live-key requirement in the shared helper would fail-close that path — a
+-- capability regression on five wrappers, none of which #269 is about.
+--
+-- So the revalidation is its own helper called by the two authority wrappers, and the CLASS
+-- is pinned from the catalog instead of by hand: agent_board_signer_lifecycle.test.sql
+-- asserts that among all `signed\_%` wrappers, the set whose stripped body calls an authority
+-- chokepoint (grant_board_role / set_board_authority_ceiling / set_board_role_gate) is
+-- EXACTLY the set whose stripped body calls this helper — both directions. A future signed
+-- authority wrapper that forgets the call fails that assertion and names itself.
+--
+-- WHY THE CALL SITE IS AFTER THE INNER FUNCTION, NOT BEFORE. Two independent reasons; do not
+-- "optimize" it earlier.
+--
+--   1. LOCK ORDER. The revalidation takes agents then agent_signing_keys. Placed AFTER the
+--      inner call, the ceiling wrapper's total order is
+--          advisory(board) -> boards -> agents -> agent_signing_keys
+--      which is onboard_federated_fleet_agent's order verbatim (20260901000110: advisory
+--      hoisted above the boards row lock; 20260901000100:1277 locks agent before key). Placed
+--      BEFORE, it becomes agents -> advisory -> boards, inverting against onboarding on
+--      (advisory, agents) — and the two transactions plausibly share both operands, because
+--      the fleet invite creator and the board owner signing a ceiling change are routinely
+--      the same agent on the same board. That is the exact ABBA shape 20260901000110
+--      documents having introduced and then fixed.
+--
+--      THAT ARGUMENT WAS RIGHT ABOUT THE CEILING WRAPPER AND WRONG ABOUT THE GRANT WRAPPER,
+--      which does not reach the advisory lock at all. See TOTAL ORDERS below: the grant
+--      wrapper's own order was board_memberships -> agents, an ABBA against onboarding that
+--      the "verbatim" claim above obscured by reasoning only about the ceiling path. It is
+--      fixed by acquiring the board advisory lock in the grant wrapper, not by moving the
+--      revalidation.
+--   2. IT PRESERVES EVERY EXISTING #247 ASSERTION. Two of them drive a wrapper with a
+--      decision whose agent_id is agent 3 while signing_key_id is agent 1's key, and assert
+--      the INNER gate's message ('%exceeds grantor role%', '%only a board owner%'). Checking
+--      first would raise signer_key_not_owned before the inner gate ever runs and rewrite
+--      both.
+--
+-- Correctness is unaffected by the position: the wrapper is one transaction, so a raise here
+-- rolls back the inner write. The three interleavings are all fail-closed — a revocation that
+-- committed earlier is SEEN (the row lock reads the latest committed row), one that starts
+-- later BLOCKS on the share lock until this transaction commits, and one already in flight
+-- makes this transaction block and then observe the revoked row.
+--
+-- TOTAL ORDERS, stated explicitly so no future reader has to reconstruct them from two
+-- migrations. Every lock either authority wrapper takes, in acquisition order:
+--
+--   signed_grant_board_role
+--     advisory(board) -> board_memberships(grantee, UPDATE) -> agents(signer, FOR SHARE)
+--       -> agent_signing_keys(decision key, FOR SHARE)
+--   signed_set_board_authority_ceiling
+--     advisory(board) -> board_authority_ceilings (+ boards via FK) -> agents(signer, FOR SHARE)
+--       -> agent_signing_keys(decision key, FOR SHARE)
+--   onboard_federated_fleet_agent (20260901000110, for comparison)
+--     board_invite_tokens(:274) -> fleet_onboarding_invite_bounds(:281) -> advisory(board)(:290)
+--       -> boards -> fleet_machines -> fleet_trust_domains -> advisory(fingerprint)
+--       -> auth.users -> agents(:349) -> board_memberships(creator)(:367)
+--       -> board_authority_ceilings(:369) -> board_memberships(enrollee)(:397)
+--       -> agents(enrolled)(:543) -> agent_signing_keys(:544)
+--
+-- WHY THIS IS ACYCLIC, and why the argument is mutual exclusion rather than ordering. Both
+-- wrappers take advisory(board) as their FIRST lock. Onboarding requests it holding only
+-- board_invite_tokens and fleet_onboarding_invite_bounds, two relations no authority wrapper
+-- ever touches. So on any shared board the three transactions are serialised at the advisory
+-- lock, and nothing either does afterwards can close a cycle. An ordering argument would have
+-- to be re-verified every time a lock is added anywhere downstream; this one does not.
+--
+-- THE CEILING WRAPPER NEEDS NO CODE CHANGE — its inner set_board_authority_ceiling already
+-- takes the advisory lock first (20260901000110:146, preserved through the #247 recreation).
+-- Only the grant wrapper had to acquire it. Do not "symmetrise" this by adding a second
+-- acquisition to the ceiling wrapper: it would be redundant, not safer.
+--
+-- LOCK MODE — FOR SHARE, on both rows, and neither weaker nor stronger.
+--   * FOR KEY SHARE is too weak. Every lifecycle write here is a plain UPDATE of a non-key
+--     column (agents.status, agent_signing_keys.status), which takes FOR NO KEY UPDATE — and
+--     FOR NO KEY UPDATE does NOT conflict with FOR KEY SHARE. The suspend would sail past.
+--   * FOR UPDATE is too strong, and the cost is not hypothetical: FOR UPDATE conflicts with
+--     FOR KEY SHARE, which is what EVERY concurrent insert of a row referencing this agent
+--     takes through its foreign key (a message, an inbox item, a membership). One signed
+--     authority write would block unrelated traffic for its whole transaction. FOR SHARE
+--     conflicts with FOR NO KEY UPDATE and FOR UPDATE — exactly the lifecycle writers — and
+--     not with FOR KEY SHARE, so FK traffic is untouched. It also lets two concurrent signed
+--     writes by the same signer proceed, which FOR UPDATE would needlessly serialize.
+--
+-- LOCK ORDER — agents BEFORE agent_signing_keys, taken from the NEWEST definitions, not the
+-- first. 20260718001100's _revoke_agent_principal locked keys first; the live one
+-- (20260901000100:1277) locks `agents ... for update` and THEN loops the keys in id order,
+-- and revoke_fleet_subject's signing_key branch does the same (agent, then key). Matching the
+-- transaction this gate exists to serialize against is the whole point, so this helper takes
+-- agents first too.
+--
+-- KNOWN AND STATED: today every RPC that REVOKES a key (_revoke_agent_principal,
+-- revoke_fleet_subject) locks the agent row first, so the agents lock alone would already
+-- serialize them. The agent_signing_keys FOR SHARE is load-bearing against a key-ONLY writer:
+-- issue_signing_key_challenge locks the key row and no agent row, and the table's UPDATE
+-- privilege is held by the owner alone (service_role has SELECT only), so owner-level
+-- incident DML is the other. The isolation spec pins that lock with the challenge RPC rather
+-- than claiming it from the code.
+--
+-- WHAT IS CHECKED, AND WHAT IS DELIBERATELY NOT RE-CHECKED. The predicate is: the decision's
+-- verification_status is EXACTLY 'verified'; agents.status = 'active'; the key row identified
+-- by the decision exists, is owned by that same actor, has status = 'active', and is
+-- unexpired.
+--
+-- THE verification_status HALF, AND THE ARGUMENT IT REPLACES. The first version of this
+-- helper checked no outcome at all, and the header argued that refusing an ABSENT key was
+-- sufficient because "granting a role is not an operation with an observe-only meaning".
+-- That argument was wrong in a way worth recording: key-absence is a PROXY for unsigned, and
+-- the proxy leaks. A verification that FAILED plausibly still names the key it resolved, so a
+-- decision reading {agent_id: <live owner>, signing_key_id: <live key>,
+-- verification_status: 'failed'} satisfied every check in the chain -- _signed_write_actor_id
+-- (20260710000000:53-63) asks only that an actor be named, this helper asked only that a key
+-- be named and live, and _record_signed_write_evidence explicitly ADMITS 'failed'
+-- (20260710000000:88). Reproduced on a database built from the manifest: the grant COMPLETED
+-- and the evidence row recorded 'failed' beside a mutation that had succeeded. The proxy is
+-- now a second line behind the outcome itself.
+--
+-- WHY EXACTLY 'verified' AND NOT A SET. The column vocabulary is
+-- ('unsigned','observed','warn','verified','failed') -- the CHECK at 20260628000000:89,
+-- mirrored by the client's catalog_vocabularies.ts. It is tempting to admit 'warn' as a
+-- "verified with a caveat", and that reading is simply false:
+-- specs/agent-provenance-signing.md:258-259 defines 'observed' and 'warn' as the labels an
+-- UNSIGNED write receives under enforcement_mode 'observe' and 'warn'. They are enforcement
+-- artifacts, not verification outcomes, so admitting either would re-open this hole under a
+-- different name. 'verified' is the only value meaning a signature was checked and passed.
+-- The comparison is `is distinct from`, so absent, empty and unknown values fail CLOSED in
+-- the same branch -- including the values of the DIFFERENT, client-side
+-- SigningVerificationStatus vocabulary ('signed', 'valid_signature': contract.ts:268), which
+-- must never satisfy a gate written against the evidence vocabulary.
+--
+-- NOT HOISTED INTO _signed_write_actor_id, for the reason the next section gives at length:
+-- the five message/task wrappers legitimately dispatch unsigned under 'observe'. This gate is
+-- authority-only, and the class assertion in agent_board_signer_lifecycle.test.sql section 6
+-- is what keeps "authority-only" true as wrappers are added.
+--
+-- The two fleet-policy call sites that accept ('verified','warn','observed')
+-- (20260628000005:305, 20260826000100:242, 20260629000101:305) are a DIFFERENT function class
+-- with a weaker bar and are deliberately not touched here. `proof_state = 'proven'` and
+-- `revoked_at is null` are NOT repeated in the predicate: the table CHECKs
+-- agent_signing_keys_active_requires_proof (status <> 'active' or proof_state = 'proven') and
+-- agent_signing_keys_revoked_shape (revoked_at is not null exactly when status is
+-- revoked/compromised) make both consequences of status = 'active'. Restating them would add
+-- two branches that NO mutation could make an assertion fail on — an unpinnable construct
+-- (CLAUDE.md rule 2). The reliance is asserted instead: the pgTAP file proves each CHECK
+-- positively, by trying to write an active-unproven and an active-with-revoked_at row and
+-- requiring the constraint to reject it, so dropping a CHECK fails the suite rather than
+-- silently unguarding this predicate.
+--
+-- WHICH IDENTIFIER NAMES THE KEY. `signing_key_id` — the primary key — not key_id/key_version.
+-- It is the row identity Portal already resolved to verify the signature and the one it hands
+-- reserve_signed_write_replay(p_signing_key_id), so it is the only identifier that names the
+-- SAME row the signature was checked against. key_id and key_version are unique only PER
+-- AGENT, so resolving by them would need the actor to disambiguate and would silently pick a
+-- different row if the decision's actor and key disagreed. They are still validated, as a
+-- consistency assertion: _record_signed_write_evidence copies key_id and key_version from the
+-- decision into signature_evidence verbatim, so a decision whose text identifiers disagree
+-- with the row this helper just revalidated would mint an evidence row naming a key that was
+-- never checked. That is refused, not recorded.
+--
+-- BLAST RADIUS. Zero on the five pre-existing wrappers: _signed_write_actor_id is untouched
+-- and they gain no call. The two authority wrappers keep their (jsonb, jsonb) signature, so
+-- CREATE OR REPLACE preserves their ACLs; their COMMENTs are restated because their behaviour
+-- changed. The new helper is a fresh CREATE and therefore restates revoke/grant/comment in
+-- this same migration — a SECURITY DEFINER function grants EXECUTE to PUBLIC by default.
+
+-- 1. The revalidation chokepoint.
+create or replace function agent_board._assert_signed_authority_signer_live(
+  p_actor_agent_id uuid,
+  p_gateway_decision jsonb
+)
+returns void
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_signing_key_id uuid := nullif(p_gateway_decision ->> 'signing_key_id', '')::uuid;
+  v_decision_key_id text := nullif(p_gateway_decision ->> 'key_id', '');
+  v_decision_key_version integer := nullif(p_gateway_decision ->> 'key_version', '')::integer;
+  v_verification_status text := nullif(p_gateway_decision ->> 'verification_status', '');
+  v_agent_status text;
+  v_key record;
+begin
+  if p_actor_agent_id is null then
+    raise exception 'signer_not_active: signed authority write requires a resolved signer'
+      using errcode = '42501';
+  end if;
+
+  -- THE OUTCOME ITSELF, checked before anything else. Everything below revalidates the
+  -- signer's LIFECYCLE; none of it asks whether the signature actually verified, and the
+  -- gateway's own verdict is the only thing that can answer that. Refusing an absent key
+  -- (below) is a PROXY for "unsigned" and it leaks: a verification that FAILED plausibly
+  -- still names the key it resolved, so a decision carrying verification_status='failed'
+  -- beside a live signer and a live key passed every other check here and COMPLETED the
+  -- authority mutation, leaving an evidence row that recorded 'failed' next to a write that
+  -- succeeded. Checked first, and before any row lock, because an unverified decision has no
+  -- standing regardless of whose key it names.
+  --
+  -- EXACTLY 'verified', not a set. The column vocabulary is
+  -- ('unsigned','observed','warn','verified','failed') (20260628000000:89, mirrored in the
+  -- client's catalog_vocabularies.ts). Of those, 'observed' and 'warn' are NOT weaker
+  -- verifications -- specs/agent-provenance-signing.md:258-259 defines both as the labels an
+  -- UNSIGNED write receives under enforcement_mode 'observe' and 'warn' respectively. So
+  -- 'verified' is the only value that means a signature was checked and passed, and the
+  -- accepted set has exactly one member. `is distinct from` makes absent, empty and unknown
+  -- fail CLOSED in the same branch -- which also covers the client-side
+  -- SigningVerificationStatus vocabulary ('signed', 'valid_signature': contract.ts:268), a
+  -- DIFFERENT vocabulary whose values must never satisfy this gate.
+  if v_verification_status is distinct from 'verified' then
+    raise exception 'signer_not_verified: signed authority write requires a verified gateway decision, got %',
+      coalesce(v_verification_status, '(absent)')
+      using errcode = '42501';
+  end if;
+
+  -- A signed AUTHORITY write must name the key it was signed with. The message wrappers
+  -- deliberately accept an unsigned decision under enforcement_mode='observe'; granting a
+  -- role is not an operation with an observe-only meaning, so an absent key is refused here
+  -- rather than recorded as 'unsigned'. This is now a SECOND line behind the verification
+  -- check above, not the thing standing in for it.
+  if v_signing_key_id is null then
+    raise exception 'signer_key_absent: signed authority write requires a gateway-verified signing key'
+      using errcode = '42501';
+  end if;
+
+  -- agents BEFORE agent_signing_keys (see header). FOR SHARE, not FOR UPDATE.
+  select a.status
+    into v_agent_status
+    from agent_board.agents a
+   where a.id = p_actor_agent_id
+   for share;
+
+  if not found then
+    raise exception 'signer_not_active: signed authority write signer is not a known agent'
+      using errcode = '42501';
+  end if;
+  if v_agent_status <> 'active' then
+    raise exception 'signer_not_active: signed authority write signer is %, not active', v_agent_status
+      using errcode = '42501';
+  end if;
+
+  select k.agent_id, k.key_id, k.key_version, k.status, k.expires_at
+    into v_key
+    from agent_board.agent_signing_keys k
+   where k.id = v_signing_key_id
+   for share;
+
+  if not found then
+    raise exception 'signer_key_absent: signed authority write names a signing key that does not exist'
+      using errcode = '42501';
+  end if;
+
+  -- The ownership half. A key that is perfectly live but belongs to somebody else authorizes
+  -- nobody: without this, a decision could pair actor A with agent B's healthy key and pass
+  -- the liveness predicate on a key A never held.
+  if v_key.agent_id <> p_actor_agent_id then
+    raise exception 'signer_key_not_owned: signed authority write signing key belongs to another agent'
+      using errcode = '42501';
+  end if;
+
+  if v_key.status <> 'active' then
+    raise exception 'signer_key_not_live: signed authority write signing key is %, not active', v_key.status
+      using errcode = '42501';
+  end if;
+
+  if v_key.expires_at is not null and v_key.expires_at <= now() then
+    raise exception 'signer_key_expired: signed authority write signing key expired at %', v_key.expires_at
+      using errcode = '42501';
+  end if;
+
+  -- Evidence integrity: the identifiers copied into signature_evidence must name the row that
+  -- was just revalidated.
+  if v_decision_key_id is not null and v_decision_key_id <> v_key.key_id then
+    raise exception 'signer_key_mismatch: gateway decision key_id does not match the revalidated signing key'
+      using errcode = '42501';
+  end if;
+  if v_decision_key_version is not null and v_decision_key_version <> v_key.key_version then
+    raise exception 'signer_key_mismatch: gateway decision key_version does not match the revalidated signing key'
+      using errcode = '42501';
+  end if;
+end;
+$$;
+
+comment on function agent_board._assert_signed_authority_signer_live(uuid, jsonb) is
+  '#269 signer-lifecycle revalidation for the signed AUTHORITY wrappers. Requires the gateway decision''s verification_status to be EXACTLY ''verified'' before anything else and before any row lock (''observed'' and ''warn'' label UNSIGNED writes accepted under those enforcement modes, not weaker verifications, so the accepted set has one member; absent/empty/unknown fail closed). Then, inside the wrapper''s own transaction, takes FOR SHARE on the signer''s agents row and then on the agent_signing_keys row named by p_gateway_decision->>''signing_key_id'' (agents first, matching _revoke_agent_principal and revoke_fleet_subject), and requires the agent to be active and the key to exist, be owned by that same agent, be active and unexpired, with key_id/key_version agreeing with the decision. FOR SHARE is chosen deliberately: FOR KEY SHARE would not conflict with the FOR NO KEY UPDATE a status change takes, and FOR UPDATE would block every concurrent FK insert referencing the agent. proof_state=''proven'' and revoked_at is null are implied by the agent_signing_keys_active_requires_proof and agent_signing_keys_revoked_shape CHECKs and are asserted there rather than duplicated here. Raises 42501 with a signer_not_active / signer_key_absent / signer_key_not_owned / signer_key_not_live / signer_key_expired / signer_key_mismatch prefix. Internal: it locks rows for an arbitrary agent id with no authorization of its own.';
+
+revoke all on function agent_board._assert_signed_authority_signer_live(uuid, jsonb) from public, anon, authenticated;
+grant execute on function agent_board._assert_signed_authority_signer_live(uuid, jsonb) to service_role;
+
+-- 2. signed_grant_board_role — verbatim from 20260907000100 plus the revalidation, placed
+--    after the inner grant and before the evidence row.
+create or replace function agent_board.signed_grant_board_role(
+  p_payload jsonb,
+  p_gateway_decision jsonb
+)
+returns table(
+  board_id uuid,
+  agent_id uuid,
+  role text,
+  signature_evidence_id uuid,
+  verification_status text,
+  updated_at timestamptz
+)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_row record;
+  v_actor uuid;
+  v_evidence_id uuid;
+  v_board uuid := (p_payload ->> 'p_board_id')::uuid;
+  v_grantee uuid := (p_payload ->> 'p_agent_id')::uuid;
+begin
+  -- The grantor is the gateway-verified signer. _signed_write_actor_id raises 42501 when
+  -- the gateway names no actor, and raises actor_mismatch when the payload names a
+  -- DIFFERENT one -- so a payload p_grantor_agent_id can never become the grantor. This
+  -- value is what grant_board_role binds (through its own _resolved_actor_agent_id) and
+  -- what the evidence row names; they cannot diverge.
+  v_actor := agent_board._signed_write_actor_id(p_payload, p_gateway_decision, 'p_grantor_agent_id');
+
+  -- BOARD ADVISORY LOCK FIRST -- this is what makes the wrapper acyclic against
+  -- onboard_federated_fleet_agent. Without it the wrapper's order is
+  -- board_memberships(grantee) -> agents(signer), while onboarding takes
+  -- agents(20260901000110:349) -> board_memberships(:397): a genuine ABBA between two HONEST
+  -- callers, reproduced as `deadlock detected` on board_memberships with an owner who both
+  -- created a fleet invite and concurrently grants the enrollee a role -- routine operands on
+  -- one board. The inner grant_board_role takes no advisory lock (the catalog-pinned set of
+  -- ceiling-advisory takers is exactly onboard_federated_fleet_agent and
+  -- set_board_authority_ceiling), so the wrapper must take it.
+  --
+  -- Mutual exclusion, NOT a re-derived ordering. Both authority wrappers now take this as
+  -- their FIRST lock; onboarding takes it at :290 holding only board_invite_tokens and
+  -- fleet_onboarding_invite_bounds -- relations no authority wrapper ever touches -- so the
+  -- two cannot form a cycle whatever either does afterwards. That property survives a new lock
+  -- being added downstream, which an ordering argument would not.
+  --
+  -- Cost, accepted: a signed grant now serialises with onboarding and with ceiling writes on
+  -- the SAME board. Boards are the unit of contention and these are all authority mutations.
+  perform agent_board._lock_board_authority_ceiling(v_board);
+
+  select *
+    into v_row
+    from agent_board.grant_board_role(
+      v_board,
+      v_grantee,
+      p_payload ->> 'p_grantee_role',
+      v_actor
+    );
+
+  -- #269. The gateway's decision was made in an EARLIER transaction; a suspension or key
+  -- revocation can have committed since. Revalidate the signer under a share lock so a
+  -- concurrent revoke serializes against this write instead of racing it. After the inner
+  -- call by design (lock order, and it keeps the inner gates' errors first) -- same
+  -- transaction, so a raise here rolls the grant back.
+  perform agent_board._assert_signed_authority_signer_live(v_actor, p_gateway_decision);
+
+  v_evidence_id := agent_board._record_signed_write_evidence(
+    'external',
+    null,
+    'grant_board_role',
+    p_payload,
+    p_gateway_decision || jsonb_build_object(
+      'external_evidence_ref',
+      'board-authority:grant_board_role:' || v_board::text || ':' || v_grantee::text
+    )
+  );
+
+  return query
+  select v_row.board_id, v_row.agent_id, v_row.role, v_evidence_id,
+         coalesce(p_gateway_decision ->> 'verification_status', 'unsigned'), v_row.updated_at;
+end;
+$$;
+
+comment on function agent_board.signed_grant_board_role(jsonb, jsonb) is
+  '#247 signed-write gateway wrapper for grant_board_role. Takes the board-keyed _lock_board_authority_ceiling advisory lock FIRST, before the inner grant: without it the wrapper''s order is board_memberships(grantee) then agents(signer) while onboard_federated_fleet_agent takes agents then board_memberships, a reproduced ABBA deadlock between two honest callers. Both authority wrappers now take that advisory lock first, and onboarding requests it holding only invite-scoped rows no wrapper touches, so they are serialised per board rather than merely ordered. Resolves the grantor with _signed_write_actor_id (gateway actor required; a payload p_grantor_agent_id that differs raises actor_mismatch 42501), passes THAT principal to grant_board_role so the bound grantor and the recorded one cannot diverge, and records a signature_evidence row via _record_signed_write_evidence with source_kind=external and a server-derived external_evidence_ref naming the board and grantee. #269: after the grant and before the evidence row it calls _assert_signed_authority_signer_live, which requires the decision''s verification_status to be exactly ''verified'' (so a FAILED verification can no longer complete the grant and record ''failed'' beside it), then share-locks and revalidates the signer''s agents row and the decision''s signing key inside this transaction, so a suspension or key revocation racing the gateway''s separate verification call either serializes behind this write or fails it closed. Adds no authority: grant_board_role''s membership, ceiling and TOCTOU gates are untouched. service_role only, like every other signed_* wrapper (#118).';
+
+-- 3. signed_set_board_authority_ceiling — same change, same position.
+create or replace function agent_board.signed_set_board_authority_ceiling(
+  p_payload jsonb,
+  p_gateway_decision jsonb
+)
+returns table(
+  ceiling_board_id uuid,
+  ceiling_max_grantable_role text,
+  signature_evidence_id uuid,
+  verification_status text
+)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_row record;
+  v_actor uuid;
+  v_evidence_id uuid;
+  v_board uuid := (p_payload ->> 'p_board_id')::uuid;
+begin
+  v_actor := agent_board._signed_write_actor_id(p_payload, p_gateway_decision, 'p_actor_agent_id');
+
+  select *
+    into v_row
+    from agent_board.set_board_authority_ceiling(
+      v_board,
+      p_payload ->> 'p_max_grantable_role',
+      v_actor
+    );
+
+  -- #269. See signed_grant_board_role. The position matters most here: the inner setter takes
+  -- the board-keyed advisory lock and then reaches boards through the ceiling FK, so
+  -- revalidating afterwards gives advisory -> boards -> agents -> keys, which is
+  -- onboard_federated_fleet_agent's order. Hoisting this above the inner call would invert
+  -- against it on (advisory, agents).
+  perform agent_board._assert_signed_authority_signer_live(v_actor, p_gateway_decision);
+
+  v_evidence_id := agent_board._record_signed_write_evidence(
+    'external',
+    null,
+    'set_board_authority_ceiling',
+    p_payload,
+    p_gateway_decision || jsonb_build_object(
+      'external_evidence_ref',
+      'board-authority:set_board_authority_ceiling:' || v_board::text || ':' || v_actor::text
+    )
+  );
+
+  return query
+  select v_row.ceiling_board_id, v_row.ceiling_max_grantable_role, v_evidence_id,
+         coalesce(p_gateway_decision ->> 'verification_status', 'unsigned');
+end;
+$$;
+
+comment on function agent_board.signed_set_board_authority_ceiling(jsonb, jsonb) is
+  '#247 signed-write gateway wrapper for set_board_authority_ceiling. Resolves the actor with _signed_write_actor_id (gateway actor required; a differing payload p_actor_agent_id raises actor_mismatch 42501) and passes it as p_actor_agent_id, so the owner gate authorizes the SAME principal the evidence row names. Records a signature_evidence row via _record_signed_write_evidence with source_kind=external and a server-derived external_evidence_ref. #269: between the ceiling upsert and the evidence row it calls _assert_signed_authority_signer_live, which requires the decision''s verification_status to be exactly ''verified'' and then share-locks and revalidates the signer''s agents row and the decision''s signing key inside this transaction; it sits after the inner call so the wrapper''s lock order stays advisory -> boards -> agents -> agent_signing_keys, matching onboard_federated_fleet_agent. Adds no authority: the owner gate still rejects any actor that is not an active board owner. service_role only, like every other signed_* wrapper (#118).';

package/package.json

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

package/schema-manifest.json

@@ -2,7 +2,7 @@
   "schema": "agent_board_schema_manifest.v1",
   "interface": "IF-0-MBPLANE-BUNDLE-1",
   "package": "@consiliency/agent-board-schema",
-  "packageVersion": "1.25.0",
+  "packageVersion": "1.27.0",
   "schemaVersion": 8,
   "minClientVersion": "1.1.0",
   "source": {
@@ -46,8 +46,8 @@
       "usage": "upsert (retention/monitoring defaults; on conflict do nothing)"
     }
   ],
-  "migrationCount": 125,
-  "aggregateSha256": "0ce03fcc8b0ae0113e9b6de2c8e8bc346cf735a86fcca0221ffc8103d604969f",
+  "migrationCount": 126,
+  "aggregateSha256": "7fbe4374b98783d1b88a075fd5b6c11723b40fccd6a4b4a7c7a80d3d1666ea2f",
   "migrations": [
     {
       "order": 0,
@@ -1173,6 +1173,15 @@
       "sourceRef": "message-board",
       "bytes": 12633,
       "sha256": "21111e289e0bb70ac3236f5422476c0c51d0bca5a815c11dd4e48b6932cf7c6b"
+    },
+    {
+      "order": 125,
+      "id": "20260908000100_agent_board_signer_lifecycle_revalidation",
+      "filename": "20260908000100_agent_board_signer_lifecycle_revalidation.sql",
+      "origin": "message-board-forward",
+      "sourceRef": "message-board",
+      "bytes": 29336,
+      "sha256": "bfb1ae60f69dae0a0aaf1007dbf14e171f324cdced1caf9f4d490f41a60c14e5"
     }
   ],
   "excludedBridge": {

package/src/tooling.test.mjs

@@ -38,9 +38,9 @@ describe('manifest integrity', () => {
     expect(manifest.schemaVersion).toBe(8);
     expect(manifest.minClientVersion).toMatch(/^\d+\.\d+\.\d+$/);
   });
-  it('registers the four MBAUTHZ + four MBSENDAUTHZ + four MBSESSION + four MBDELEG + three MBFED + three MBHARDEN + two MBPORTALGATE + two MBPORTAL-PR32 + two ROOMOWN + two ROOMLINK + one ROOMDELEG + one LOCALAUTH + one ROOMUIAPI + one FEDSESSION + one FEDSESSION-AUTOJOIN + one GATENULL + one MEMBSTATE + one AGENTSDIR + one LEAVEIDEM + one ROLERESET + one MBROWID + one MBHYGIENE + one MBCONSENT-A + one MBCONSENT-B(a) + one MBCONSENT-B(i) + one MBCONSENT-B(ii) + one MBCONSENT-B(iii) + one MBHARDEN-#97 + one MBHARDEN-#118 + one INVITEPOLICY + one OBSGATE + one OBSGATE-2 + one OBSGATE-3 + one OBSGATE-4 + one FLEETMACHINERLS + one RESOLVENOOP + one ROOMDELEG-LANEB + one CLAIMKEY + two MINTHARDEN + one FLEETMACHINEHIJACK + one CLAIMGATE-SHADOW + one CLAIMGATE-ENFORCE + one FLEETMACHINEREACTIVATION + one DELEGCAPCEILING + one FLEETMACHINERECLAIM + one DELEGSOLEWRITER + one FLEETDOMAINRECLAIM + five ATOMICFLEETONBOARDING (onboarding + ceiling-lock + revocation-evidence + fedsession-gate + fedsession-lock-order) + one OUTBOXWAKE + one ENROLLLOCKORDER + one FEDPROVIDERABSENCE + one WAKERECOVERY + one CONSENTRECONCILE + one ENROLLRESUMPTION + one SIGNEDAUTHORITY forward migrations (migrationCount = prior 113 + 5 + 1 + 1 + 1 + 1 + 1 + 1 + 1 = 125)', () => {
+  it('registers the four MBAUTHZ + four MBSENDAUTHZ + four MBSESSION + four MBDELEG + three MBFED + three MBHARDEN + two MBPORTALGATE + two MBPORTAL-PR32 + two ROOMOWN + two ROOMLINK + one ROOMDELEG + one LOCALAUTH + one ROOMUIAPI + one FEDSESSION + one FEDSESSION-AUTOJOIN + one GATENULL + one MEMBSTATE + one AGENTSDIR + one LEAVEIDEM + one ROLERESET + one MBROWID + one MBHYGIENE + one MBCONSENT-A + one MBCONSENT-B(a) + one MBCONSENT-B(i) + one MBCONSENT-B(ii) + one MBCONSENT-B(iii) + one MBHARDEN-#97 + one MBHARDEN-#118 + one INVITEPOLICY + one OBSGATE + one OBSGATE-2 + one OBSGATE-3 + one OBSGATE-4 + one FLEETMACHINERLS + one RESOLVENOOP + one ROOMDELEG-LANEB + one CLAIMKEY + two MINTHARDEN + one FLEETMACHINEHIJACK + one CLAIMGATE-SHADOW + one CLAIMGATE-ENFORCE + one FLEETMACHINEREACTIVATION + one DELEGCAPCEILING + one FLEETMACHINERECLAIM + one DELEGSOLEWRITER + one FLEETDOMAINRECLAIM + five ATOMICFLEETONBOARDING (onboarding + ceiling-lock + revocation-evidence + fedsession-gate + fedsession-lock-order) + one OUTBOXWAKE + one ENROLLLOCKORDER + one FEDPROVIDERABSENCE + one WAKERECOVERY + one CONSENTRECONCILE + one ENROLLRESUMPTION + one SIGNEDAUTHORITY + one SIGNERLIFECYCLE forward migrations (migrationCount = prior 113 + 5 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 = 126)', () => {
     expect(manifest.migrationCount).toBe(manifest.migrations.length);
-    expect(manifest.migrationCount).toBe(125);
+    expect(manifest.migrationCount).toBe(126);
     // MBSESSION switched enforcement on (scoped-send re-grant): the client-visible
     // schema version bumped to 8. MBDELEG tightens delegation and MBFED adds only
     // enrollment-only additive surface (identity_providers registry, enrollment audit,

package/tests/agent_board_atomic_fleet_onboarding.test.sql

@@ -581,7 +581,12 @@ select is( -- pgtap-allow-raise-checked: catalog read only; the RPC names below
     'agent_board.reactivate_fleet_machine(uuid,uuid,text) [definer] => service_role',
     'agent_board.revoke_fleet_subject(text,uuid,uuid,text,jsonb) [definer] => authenticated,service_role',
     'agent_board.revoke_human_subtree(uuid,uuid,text) [definer] => service_role',
-    'agent_board.set_board_authority_ceiling(uuid,text,uuid) [definer] => authenticated,service_role'
+    'agent_board.set_board_authority_ceiling(uuid,text,uuid) [definer] => authenticated,service_role',
+    -- Joined this class in #269 F4: the signed grant wrapper now takes the board advisory lock
+    -- FIRST, because its order was board_memberships(grantee) -> agents(signer) against
+    -- onboard_federated_fleet_agent's agents -> board_memberships -- a reproduced ABBA between
+    -- two honest callers. It is service_role-only like every other signed_* wrapper (#118).
+    'agent_board.signed_grant_board_role(jsonb,jsonb) [definer] => service_role'
   ]::text[],
   'every function on this migration set''s surface is declared with its definer flag and exact EXECUTE grantees'
 );

package/tests/agent_board_signed_authority_provenance.test.sql

@@ -26,7 +26,7 @@ set search_path = extensions, public, agent_board;
 
 begin;
 
-select plan(38);
+select plan(40);
 
 create function pg_temp.claims(p_sub text) returns void language plpgsql as $$
 begin
@@ -293,6 +293,9 @@ select throws_like(
   '%exceeds grantor role or board authority ceiling%',
   'the wrapper grants no authority: a member signer still cannot mint an owner');
 
+-- This probe named a 'failed' verification but carried NO agent_id, so it was refused for
+-- ACTOR ABSENCE and never once exercised the failed status -- a description claiming what no
+-- assertion backed. It is now two probes, each refused for the reason it names.
 select throws_like(
   $$select * from agent_board.signed_grant_board_role(
       jsonb_build_object(
@@ -303,6 +306,26 @@ select throws_like(
   '%actor_mismatch%',
   'a gateway decision naming no actor cannot write evidence at all');
 
+-- The status probe proper: the SAME decision the allow-side probes use -- verified signer,
+-- live key, an owner granting a role the inner gates permit -- with only verification_status
+-- flipped to 'failed'. Without the #269 verification check this grant COMPLETES and mints an
+-- evidence row recording 'failed' beside a mutation that succeeded.
+select throws_like(
+  $$select * from agent_board.signed_grant_board_role(
+      jsonb_build_object(
+        'p_board_id', '24720000-0000-4000-8000-000000000001',
+        'p_agent_id', '24710000-0000-4000-8000-000000000002',
+        'p_grantee_role', 'admin'),
+      pg_temp.gw('24710000-0000-4000-8000-000000000001')
+        || jsonb_build_object('verification_status','failed'))$$,
+  '%signer_not_verified%',
+  'a FAILED verification is refused for its STATUS, by a signer who is otherwise fully entitled');
+
+select is(
+  (select count(*)::int from agent_board.signature_evidence where operation = 'grant_board_role'),
+  1,
+  'and the failed-verification attempt minted no evidence row');
+
 -- ===========================================================================
 -- 5. signed_set_board_authority_ceiling.
 -- ===========================================================================