@consiliency/agent-board-schema 1.25.0 → 1.28.0

package/migrations/20260909000100_agent_board_ledger_revoked_authority.sql

@@ -0,0 +1,1036 @@
+-- Consiliency/message-board#276 — a fleet-revoked agent loses BOARD AUTHORITY, not just SEND.
+--
+-- THE RATIFIED DECISION. Revoking a fleet agent removes its ability to GRANT BOARD ROLES as
+-- well as to send. Fleet revocation is a principal-level act, not merely a machine-binding
+-- change. This migration makes the schema say that.
+--
+-- THE DIVERGENCE THIS CLOSES, measured rather than recalled.
+-- `agent_board.revoke_fleet_subject('agent', X)` (newest definition 20260901000100:1062)
+-- writes an agent-subject `fleet_revocation_events` row and flips every
+-- `fleet_machine_agents` binding for X to 'revoked'. It does NOT touch `agents.status` and
+-- does NOT revoke X's signing keys — deliberately; `_revoke_agent_principal`
+-- (20260901000100:1277) is the primitive that does both, and it is a DIFFERENT act.
+-- `evaluate_fleet_sender_policy` (newest 20260826000100:120) consults the ledger, so X cannot
+-- SEND. Every board-authority predicate reads `agents.status` and the board membership, and
+-- NONE of the three authority chokepoints mentioned the ledger — enumerated from pg_proc, not
+-- from memory. So the same principal, under the same revocation, got two answers: refused a
+-- message, allowed to hand out `owner` on a board.
+--
+-- WHERE THE CHECK LIVES — ONE SITE PER CHOKEPOINT, BOTH ROUTES BY CONSTRUCTION.
+-- `agent_board.grant_board_role` is granted to `authenticated` (20260723000200:72) and is
+-- also the inner call of `signed_grant_board_role` (20260908000100:361). A catalog sweep over
+-- EVERY namespace (`prosrc ~ '\mgrant_board_role\s*\('`, plus pg_views and pg_trigger) finds
+-- exactly ONE other reference in the database: `agent_board.signed_grant_board_role`. So a
+-- check inside `grant_board_role` is inherited by the signed route by construction — it
+-- cannot be closed on one path and left open on the other. The same holds for
+-- `set_board_authority_ceiling` (sole other referrer: `signed_set_board_authority_ceiling`)
+-- and `set_board_role_gate` (no other referrer at all).
+--
+-- Putting the check in `_assert_signed_authority_signer_live` instead was rejected on the
+-- record: it would close the NARROWER door (signed, service_role-only, evidence-recorded)
+-- and leave the WIDER one (unsigned, `authenticated`, no evidence) open, while making both
+-- teams believe ledger revocation was enforced. `_grant_within_ceiling` was rejected as the
+-- single site for a different reason: `set_board_role_gate` never calls it, so it is not a
+-- chokepoint of the class, and widening it would change invite-redemption semantics for
+-- `create_invite_link` / `_redeem_unbounded_invite_for_agent` — the same shape as #269's
+-- refusal to extend `_signed_write_actor_id`.
+--
+-- ============================================================================
+-- JUDGEMENT 1 — WHAT "REVOKED" MEANS WHEN AN AGENT HAS SEVERAL FLEET BINDINGS.
+-- ============================================================================
+-- The predicate is the existence of an agent-subject `fleet_revocation_events` row. It
+-- inspects NO binding. That is not a simplification; it is the answer
+-- `evaluate_fleet_sender_policy` already gives to the identical question, and the two must
+-- agree or #276 ships a third inconsistency while fixing the second:
+--
+--   * The sender policy selects a binding with `fma.lifecycle_state='active' and
+--     fm.lifecycle_state='active'` and NO machine scope when `p_sender_machine_id` is null
+--     (20260826000100:161-170) — so an agent whose binding on machine A was revoked while a
+--     binding on machine B stays active still resolves a binding and still SENDS.
+--   * It then denies unconditionally on
+--     `fre.subject_kind='agent' and fre.subject_id = p_sender_agent_id`
+--     (20260826000100:189) — an agent-subject ledger row denies the agent everywhere, on
+--     every machine, regardless of surviving bindings.
+--
+-- So per-binding revocation (`revoke_fleet_machine_agent_binding`, and a machine or domain
+-- revocation) is a PER-MACHINE fact that the sender policy answers by candidate selection,
+-- while the agent-subject ledger row is the AGENT-WIDE fact. `revoke_fleet_subject('agent')`
+-- writes exactly that agent-wide row and revokes every binding in one statement
+-- (`where agent_id = p_subject_id`, no machine scope, 20260901000100:1251-1253) — the multi-binding
+-- case cannot arise FROM an agent revocation. Authority therefore keys on the same row the
+-- send path keys on, and "revoked from one machine, active on another" keeps board authority
+-- exactly as it keeps send.
+--
+-- NO SUPERSESSION CLAUSE, and that asymmetry is deliberate and copied. The sender policy
+-- honours `fleet_machines.reactivated_at` for MACHINE-subject events only (#146); its
+-- trust_domain and agent clauses have no supersession, and `reactivate_fleet_machine`'s own
+-- comment states it "never un-revokes the machine's trust_domain or sender agent". An
+-- `effective_at` comparison here would be a divergence, not a refinement.
+--
+-- ============================================================================
+-- JUDGEMENT 2 — AN AGENT WITH NO FLEET BINDING MUST NOT BE BLOCKED.
+-- ============================================================================
+-- Humans and non-fleet agents have no `fleet_machine_agents` row at all. A predicate phrased
+-- as "the actor has an active binding" would refuse EVERY non-fleet grantor — a capability
+-- regression far worse than the hole, and precisely the shape this repo's holes take (the
+-- exemption category becomes the defect). The predicate here is the PRESENCE of a revocation
+-- row, so a principal that was never in a fleet is unaffected by construction: there is no
+-- row to find, no binding is consulted, and the function returns without raising.
+--
+-- The exemption is asserted POSITIVELY in agent_board_ledger_authority.test.sql, never by the
+-- absence of a match: a non-fleet agent completes a real grant and the granted role is read
+-- back. The inverse mutation (make the helper raise when NO row exists) fails that assertion,
+-- which is what makes it load-bearing rather than decorative.
+--
+-- ============================================================================
+-- JUDGEMENT 3 — THE LOCK, AND THE TOTAL ORDER FOR BOTH ROUTES.
+-- ============================================================================
+-- The read IS locked. An unlocked `exists` would leave exactly the TOCTOU #269 refused to
+-- accept one function away: the gateway/authenticated caller reads "no revocation", a
+-- concurrent `revoke_fleet_subject('agent')` commits, and the grant lands anyway. #269 closed
+-- that window for `agents.status`; leaving it open for the ledger in the same call graph
+-- would be an inconsistency with a documented decision.
+--
+-- The lock is `agents` FOR SHARE on the ACTOR — the same row, in the same mode, that
+-- `_assert_signed_authority_signer_live` already takes, chosen for the same reasons (FOR KEY
+-- SHARE would not conflict with a plain status change's FOR NO KEY UPDATE; FOR UPDATE would
+-- block every concurrent FK insert referencing the agent). It serializes because BOTH writers
+-- of an agent-subject ledger row take `agents` FOR UPDATE BEFORE the write, enumerated from
+-- pg_proc rather than assumed:
+--
+--   agent_board.revoke_fleet_subject     fleet_machines(FOR UPDATE, uuid order)
+--                                     -> agents(FOR UPDATE)            :1116
+--                                     -> fleet_machine_agents(FOR UPDATE)
+--                                     -> fleet_revocation_events(write) :1195
+--   agent_board._revoke_agent_principal  agents(FOR UPDATE)             :1292
+--                                     -> agent_signing_keys(FOR UPDATE, uuid order)
+--                                     -> fleet_revocation_events(write) :1353
+--
+-- Both interleavings are fail-closed. A revocation that committed earlier is SEEN (the share
+-- lock reads the latest committed row). One that starts later BLOCKS on the share lock until
+-- the authority write commits, and lands afterwards — a grant that beat the revocation, which
+-- is the same outcome as a grant one millisecond earlier. That "every agent-subject ledger
+-- writer locks `agents` first" property is itself pinned by a catalog assertion, so a future
+-- writer that skips the lock fails the suite and names itself instead of silently reopening
+-- this window.
+--
+-- TOTAL ORDERS. The canonical order this schema already uses is
+--     boards -> auth.users -> agents -> board_memberships -> agent_signing_keys
+-- (#194 established boards before auth.users after a reproduced `deadlock detected`;
+-- onboard_federated_fleet_agent takes auth.users:751 -> agents:760 -> board_memberships:769,
+-- and later agents:945 -> agent_signing_keys:946). The new lock is inserted at `agents`'
+-- canonical slot in each function — which is BEFORE the write in `grant_board_role` (whose
+-- first lock is board_memberships) and AFTER the write in the two setters (whose first lock
+-- is boards). The placement is therefore not stylistic and must not be "tidied" to be uniform.
+--
+-- `grant_board_role` additionally takes the board advisory lock, which it did not before. That
+-- was not a design choice: adding the ledger gate makes it lock BOTH agents and
+-- board_memberships, and agent_board_signer_lifecycle.test.sql section 9 pins from the call
+-- graph that every member of that class takes the advisory lock. The assertion failed and named
+-- this function; the lock was added rather than the assertion weakened (see the comment at the
+-- call site). It also retires one of the three `UNSERIALIZED` ceiling-authorization readers
+-- 20260901000110 left open and declined to determine.
+--
+--   grant_board_role (unsigned, authenticated)
+--       advisory(board) -> agents(SHARE) -> board_memberships(UPDATE)
+--   signed_grant_board_role
+--       advisory(board) -> advisory(board, re-entrant no-op inside the inner grant)
+--                       -> agents(SHARE) -> board_memberships(UPDATE)
+--                       -> agents(SHARE, same row, no-op) -> agent_signing_keys(SHARE)
+--   set_board_authority_ceiling (unsigned and signed)
+--       advisory(board) -> boards(KEY SHARE, via board_authority_ceilings FK)
+--                       -> agents(SHARE) [-> agent_signing_keys(SHARE) on the signed route]
+--   set_board_role_gate (authenticated only — service_role has no owner membership)
+--       boards(UPDATE) -> agents(SHARE)
+--
+-- Checked by name against the three functions #269 F4 named:
+--   * revoke_fleet_subject       — fleet_machines -> agents -> fleet_machine_agents. It
+--     acquires `agents` while holding fleet_machines rows, which NO authority chokepoint
+--     touches, and it touches neither boards nor board_memberships. No shared second operand,
+--     so no cycle in either direction.
+--   * _revoke_agent_principal    — agents -> agent_signing_keys. Same order as every route
+--     above (agents before keys); it takes no boards or board_memberships lock.
+--   * onboard_federated_fleet_agent — advisory -> boards -> auth.users -> agents ->
+--     board_memberships -> agents -> agent_signing_keys. Every route above is a subsequence
+--     of that order, which is the point of siting the lock at the canonical slot. This is what
+--     makes the placement asymmetric: hoisting the check ABOVE the write in the two setters
+--     would give `agents -> boards`, inverting against onboarding and against the federated
+--     enroll routes on the (agents, boards) pair — the exact ABBA #269 F4 reproduced. Pushing
+--     it BELOW the write in `grant_board_role` would give `board_memberships -> agents`, which
+--     is the inversion #269's own header records reproducing as `deadlock detected` — and the
+--     unsigned route has no advisory lock to be rescued by.
+--
+-- Correctness is unaffected by the position in the two setters: the function is one
+-- transaction, so a raise after the write rolls the write back. This is #269's ratified
+-- argument for the same placement, not a new one.
+--
+-- ============================================================================
+-- THE INVITE PATHS — WHY MINT IS LOCKED AND REDEEM IS NOT.
+-- ============================================================================
+-- Gating the three chokepoints alone left an equivalent route open, and shipping that would
+-- have been worse than the gap: the header would have claimed a property the schema did not
+-- have. `board_invite_tokens_preset_role_check` permits an `admin` preset; `create_invite_link`
+-- refuses only `owner` presets (R-LINK-3) and otherwise gates on `_grant_within_ceiling`, which
+-- reads the creator's ROLE and never the ledger; `_redeem_unbounded_invite_for_agent` writes
+-- `preset_role` into `board_memberships`. So a ledger-revoked owner or admin — still active,
+-- still a member, keys intact, because revocation deliberately leaves all three alone — could
+-- mint an admin link and have the redeemer become admin. Conferring admin through a link is
+-- granting a board role; only the route differs. BOTH halves are gated: gating mint alone
+-- leaves outstanding links live for up to their TTL, and gating redeem alone lets a revoked
+-- agent keep stockpiling codes for later.
+--
+-- WHOSE LEDGER STATE GOVERNS REDEMPTION: THE CREATOR'S. This is not a new policy — the
+-- function already implements it twice. R-LINK-2 requires the CREATOR to still be an `active`
+-- agent, and the re-bind requires the CREATOR's current authority to still cover the preset.
+-- #276 adds a third clause to that same creator-governed block. The redeemer is RECEIVING a
+-- membership, not conferring one; its own standing is handled by `current_agent_id()` (which
+-- resolves only active agents) and by the R-LINK-7 removed-agent clause. A fleet-revoked
+-- redeemer therefore stays able to redeem, which is correct.
+--
+-- MINT IS LOCKED, REDEEM IS NOT, AND THE ASYMMETRY IS THE WHOLE POINT.
+--
+--   MINT. The actor IS the principal whose authority is spent, exactly as in the three
+--   chokepoints, so it gets the same share-locked assert. Placed AFTER the token insert, the
+--   order is boards(KEY SHARE, through board_invite_tokens.board_id) -> agents(SHARE), which is
+--   canonical. Its only in-schema caller, create_fleet_onboarding_invite, already holds
+--   boards(FOR UPDATE) -> fleet_machines(FOR UPDATE) -> fleet_trust_domains(FOR UPDATE) before
+--   it mints, so the agents acquisition is last in that path too; and revoke_fleet_subject
+--   takes fleet_machines -> agents in the SAME direction, so the pair cannot invert.
+--
+--   WHAT THE MINT LOCK ACTUALLY BUYS: nothing, on this path, and that is recorded rather than
+--   claimed. Mutation-tested by removing the FOR SHARE: the mint isolation permutation is
+--   BYTE-IDENTICAL — it still waits, still fails closed, still leaves no token. The reason is
+--   board_invite_tokens_created_by_agent_id_fkey: the token INSERT already takes FOR KEY SHARE
+--   on agents(creator), which conflicts with the revoker's FOR UPDATE, and the insert precedes
+--   the gate. So the atomicity on the mint path is supplied by the FK, and by the time the gate
+--   runs this transaction already holds that row. The assert is kept anyway — one helper and
+--   one discipline across all five gated sites beats a second, subtly different predicate, and
+--   upgrading KEY SHARE to SHARE on a row this transaction already holds adds no new wait — but
+--   nothing here should be read as "the FOR SHARE is what serializes the mint". It is not. The
+--   isolation permutation pins the OUTCOME (blocks, then fails closed, no token escapes); it
+--   does not pin this lock, and no permutation can, because the insert always precedes the gate.
+--
+--   REDEEM. Every way of taking a row lock on the creator here CLOSES A CYCLE. Enumerated
+--   rather than asserted:
+--
+--     * The board advisory lock — the fix signed_grant_board_role needed — is the one option
+--       that can be ruled out with a line number. `_redeem_unbounded_invite_for_agent` is
+--       reached from `enroll_federated_identity`, which takes `boards FOR KEY SHARE` at
+--       20260903000100:112-114 — hoisted to exactly that point by #194 to fix a REPRODUCED
+--       `deadlock detected` — and only reaches the redemption at :244. Taking the advisory
+--       lock inside the redemption therefore acquires it while `boards` is already held,
+--       giving boards -> advisory against onboard_federated_fleet_agent's advisory -> boards.
+--       That is #269 F4's shape, created by the fix rather than prevented by it.
+--     * `agents FOR SHARE` BEFORE the membership write gives, on the standalone
+--       `redeem_invite_link` path (which holds no boards lock of its own),
+--       agents -> boards(KEY SHARE via the membership FK) — inverting against onboarding's
+--       boards -> agents.
+--     * `agents FOR SHARE` AFTER the membership write gives board_memberships -> agents,
+--       inverting against onboarding's agents(FOR UPDATE) -> board_memberships; SHARE and
+--       FOR UPDATE do conflict, so that one is a real wait on both sides.
+--
+--   So the ledger read here is UNLOCKED, via _actor_fleet_revoked.
+--
+--   THE GENERAL RULE, stated because the next reader will ask why this check is unlocked when
+--   #269 locked and this migration locks four other sites: LOCK WHEN THE REVOKED PRINCIPAL IS
+--   THE TRANSACTION'S OWN ACTOR; DO NOT WHEN IT IS A THIRD PARTY. In a chokepoint the actor's
+--   `agents` row is already in the transaction's natural lock order, so the lock is free and
+--   refusing it would be gratuitous. In redemption the revoked principal is the link's CREATOR,
+--   who is not otherwise in this transaction at all, so acquiring its row is a brand-new
+--   cross-relation edge — and in this particular call graph, one with a reproduced ABBA
+--   history, every placement of that edge closes a cycle (enumerated above). Both decisions
+--   stay defensible under that rule; neither is defensible under "always lock" or "never lock".
+--
+--   Decisively, the ADJACENT check already follows it: R-LINK-2's creator-status test takes no
+--   lock at all, and this clause is the same predicate class about the same principal at the
+--   same point. Locking one and not the other would be incoherent whichever way it went.
+--
+--   THE EXACT RESIDUAL BOUND, because an inexact disclosure is worse than none. It is NOT
+--   "one redemption" — that was the first wording here and it was wrong in the general case.
+--   It is AT MOST ONE REDEMPTION PER OUTSTANDING TOKEN, and the reason is a lock that is
+--   already here: this function takes `board_invite_tokens FOR UPDATE` as its FIRST statement,
+--   before the ledger read. So two redemptions of the SAME token cannot both be between their
+--   ledger read and their commit — the second blocks on the token row, and when it proceeds it
+--   takes a fresh snapshot and sees the committed revocation. Redemptions of DIFFERENT tokens
+--   share no row and are independent, so a creator holding K outstanding links can have up to
+--   K redemptions slip, one per link. K is bounded by what that creator minted before it was
+--   revoked, and each link's own `max_uses` bounds nothing here (the cap limits total uses, not
+--   the size of this window). The mint gate means K cannot grow after the revocation.
+--
+--   Both halves of that bound are pinned rather than argued: a positional assertion requires
+--   the token lock to precede the ledger read (delete it and the per-token half of this
+--   sentence stops being true), and an isolation permutation drives two redemptions of ONE
+--   token across a committing revocation, recording the first succeeding and the second
+--   refused.
+--
+-- UNIFORM ERROR ON THE REDEEM SIDE. Every deny arm in the redemption raises the same
+-- 'invite is not usable' 42501 so a code-bearer cannot distinguish a revoked creator from a
+-- dead, expired or exhausted link. The #276 clause uses that same message: a `fleet_revoked:`
+-- prefix there would build the lifecycle oracle the function documents refusing to build, and
+-- would leak it to whoever holds the code — who is not the principal being described. Mint
+-- keeps the prefix, because there the caller is asking about ITSELF.
+--
+-- FLEET ONBOARDING INHERITS THE REDEEM GATE through `_redeem_fleet_invite_for_agent`: a fleet
+-- onboarding invite minted by a since-revoked owner stops admitting. That is a real behaviour
+-- change on a live path, and it is what R-LINK-2 already does on suspension. Asserted
+-- positively rather than left to be discovered.
+--
+-- ============================================================================
+-- SCOPE — THE CLASS, DETERMINED FROM pg_catalog.
+-- ============================================================================
+-- The issue names role grants. The class is every function that WRITES a board-authority
+-- relation, derived by scanning stripped bodies (never raw prosrc — #196/#199) for
+--   ANY `insert into agent_board.board_memberships`
+--   `update agent_board.board_memberships … set … role =`
+--   `insert into|update agent_board.board_authority_ceilings`
+--   `update agent_board.boards … set … role_gate_enforced =`
+--
+-- THE MEMBERSHIPS ARM IS SHAPE-BLIND ON PURPOSE, and it did not start that way. The first
+-- version matched only the UPDATE shape, and review found two writes it could not see:
+-- `create_board` — grant execute to `authenticated` (20260515000000:484, restated
+-- 20260723000100:118) — seeds `role = 'owner'` with an INSERT, and its
+-- `on conflict … do update set role = 'owner'` is an UPDATE of bm.role that the UPDATE-shaped
+-- regex STILL cannot match, because the table name precedes `do update`. So the arm now matches
+-- any insert into the relation at all. Measured against the shipped catalog, the shape-blind
+-- form costs nothing — it names exactly the same five membership writers the role-token form
+-- did — and it is strictly stronger: on-conflict clauses exist only inside an insert, so it
+-- subsumes that shape by construction, and it also catches a positional insert naming no
+-- columns, which any column-name-matching form would miss. Generalising the shape is the whole
+-- lesson: a guard that enumerates the syntax it expects is evaded by the syntax it did not.
+--
+-- A FOURTH ARM covers the invite MINT: any `insert into agent_board.board_invite_tokens`. A
+-- token carrying a preset_role IS a deferred grant, so the relation belongs in the class even
+-- though it is not a membership. INSERT only, deliberately: `revoke_invite_link` UPDATEs the
+-- same table to REDUCE authority, and a revoked agent killing its own outstanding links is
+-- desirable, not something to gate. The arm is shape-blind for the same reason the memberships
+-- arm is; the catalog confirms `create_invite_link` is its only inserter
+-- (`create_fleet_onboarding_invite` delegates to it rather than writing the table).
+--
+-- Against the shipped catalog that set is exactly nine:
+--   GATED HERE (5):  grant_board_role, set_board_authority_ceiling, set_board_role_gate,
+--                    create_invite_link, _redeem_unbounded_invite_for_agent
+--   EXEMPT (4):      _upsert_board_membership_state, create_board,
+--                    _fedsession_autojoin_default_board, bootstrap_board_owner_memberships
+-- All five gated: leaving either setter open would let a revoked owner refused a role grant
+-- still RAISE the board ceiling (which changes what every grantor may hand out) or flip
+-- `role_gate_enforced` (which disables the creator-exemption enforcement on invites), and
+-- leaving either invite half open would leave an equivalent route to conferring `admin`.
+--
+-- THE FOUR EXEMPTIONS, each disposed of POSITIVELY and never by absence of a match. Every
+-- clause below is a live assertion in agent_board_ledger_authority.test.sql that reads the
+-- catalog or drives the function, not a claim in this comment:
+--   * `_upsert_board_membership_state` — its INSERT branch omits `role` entirely (table
+--     default) and its UPDATE branch is the ROLERESET clamp: the literal 'member' on
+--     non-active -> active re-entry, `bm.role` otherwise, so it can only ever DEMOTE. Its
+--     EXACT identity-argument string is asserted (not a `role` word match — `_` is a word
+--     character in POSIX regex, so `\mrole\M` does NOT match `p_role`, and every parameter in
+--     this codebase is `p_*`; the word-match form was evadable by adding `p_role`). Not
+--     EXECUTE-able by authenticated/anon/public.
+--   * `create_board` — the one authenticated-callable exemption. It writes the literal 'owner'
+--     for the board's own `created_by_agent_id` (the resolved actor) on a board it just
+--     inserted; its exact identity-argument string is asserted, so it has no role parameter to
+--     be handed. The slug-COLLISION branch refuses any actor without an active owner membership
+--     and deliberately does NOT re-seed (20260723000100), so it cannot elevate a membership on
+--     a pre-existing board. What it CAN do is manufacture a brand-new board with the actor as
+--     owner while that actor is ledger-revoked. That is the residual below, and it is asserted
+--     as behaviour rather than described.
+--   * `_fedsession_autojoin_default_board` — service_role only; the literal 'member', the base
+--     role, so it cannot confer authority at all.
+--   * `bootstrap_board_owner_memberships` — service_role only, zero arguments; it backfills the
+--     board's own recorded `owner_agent_id`, conferring nothing the board did not already say.
+--
+-- NAMED RESIDUAL, deliberately out of scope (Consiliency/message-board#280). It is now ONE
+-- function, not three: the invite paths named in the first revision of this header are GATED
+-- above, so the only remaining way a ledger-revoked agent touches board authority is
+-- `create_board` — creating a fresh board and being seeded its owner (`agents.status` stays
+-- 'active' under fleet revocation, which is this migration's own precondition).
+--
+-- It is left open on a stated argument, not by omission: it confers nothing on ANYONE ELSE.
+-- The ratified criterion is about granting board roles, and here there is no grantee — the
+-- board did not exist a moment earlier, so no pre-existing principal or resource comes under
+-- the revoked agent's authority, and the collision branch already refuses a non-owner and does
+-- not re-seed. Both halves are asserted as behaviour in the pgTAP file (it CAN create the board
+-- and be seeded owner; it still CANNOT grant a role on the board it just created, nor mint a
+-- link there), so #280 closing flips a test deliberately rather than silently.
+--
+-- A SECOND BOUNDED RESIDUAL, recorded so the next reader does not have to re-derive it, and
+-- recorded CONDITIONALLY because the condition is the whole argument. The plain membership
+-- admission RPCs — `invite_board_member`, `update_board_membership`, `resolve_board_request`,
+-- and the rest of the `_upsert_board_membership_state` caller set — are NOT gated. A
+-- ledger-revoked agent that still holds a board seat can therefore still admit plain members
+-- to a board it already belongs to, and can still move membership STATE.
+--
+-- That is outside the ratified criterion, and the reason is mechanical rather than a judgement
+-- call: NONE of those functions declares a role-bearing parameter, so none of them can confer
+-- a ROLE. They admit at the membership floor, and a `member` holds no authority to grant
+-- anything onward — so no authority is transferred and there is nothing for the criterion
+-- ("removes its ability to grant board roles") to bite on. Extending the gate to them would be
+-- an extension of the owner's decision, not an application of it.
+--
+-- THE CONDITION IS ASSERTED, NOT ASSUMED. `EXEMPTION A4` in agent_board_ledger_authority.test.sql
+-- sweeps the ENTIRE caller set of `_upsert_board_membership_state` and pins each one's EXACT
+-- identity-argument string. If anybody ever adds a role parameter to one of those functions —
+-- or adds a new caller that has one — that assertion fails and names it, and the paragraph
+-- above stops being true at the same moment. This claim is deliberately written as conditional
+-- so that the day the condition breaks, the record already says so rather than having to be
+-- re-litigated.
+--
+-- KNOWN, DELIBERATE GAP, inherited and restated so the class assertion is not over-read:
+-- service_role retains direct INSERT/UPDATE grants on `board_authority_ceilings` and `boards`
+-- (operator provisioning, 20260717000400). A direct table write bypasses every function-level
+-- gate, including this one. Only the RPC path is covered. Closing that needs a table trigger
+-- and is a separate decision.
+--
+-- BLAST RADIUS. The three functions keep their signatures, so CREATE OR REPLACE preserves
+-- their ACLs; the revokes, grants and COMMENTs are restated anyway because the behaviour
+-- changed and because this repo has been bitten by a recreation that silently re-granted
+-- PUBLIC. The helper is a fresh CREATE and therefore restates revoke/grant/comment in this
+-- same migration. No caller signature changes: the SDK (`grantBoardRole`,
+-- `setBoardAuthorityCeiling`, `setBoardRoleGate`), the MCP tools and the CLI all call the
+-- same RPCs with the same arguments. The only behavioural delta is a new 42501 for a
+-- principal carrying an agent-subject revocation row — which is precisely the decision.
+-- A service_role caller that SUPPLIES a revoked `p_grantor_agent_id` is refused too: the
+-- check binds the PRINCIPAL the write is attributed to, not the connection role. That is
+-- correct under the ratified decision — a gateway acting for a revoked agent is the case
+-- #276 was filed about — and it is asserted, not assumed.
+
+-- ---------------------------------------------------------------------------
+-- 1a. The ledger predicate itself, WITHOUT a lock.
+--
+-- Split out from the assert helper for the invite REDEEM path, which must consult the ledger
+-- but must not take a row lock — see "THE INVITE PATHS" in the header for the reproduced
+-- cycles that lock would create. Keeping the predicate in one function means the locked and
+-- unlocked callers cannot drift into asking two different questions, and the class assertion
+-- can count both call shapes as "consults the ledger".
+-- ---------------------------------------------------------------------------
+create or replace function agent_board._actor_fleet_revoked(p_actor_agent_id uuid)
+returns boolean
+language sql
+stable
+security definer
+set search_path = agent_board, public
+as $$
+  select exists (
+    select 1
+      from agent_board.fleet_revocation_events fre
+     where fre.subject_kind = 'agent'
+       and fre.subject_id = p_actor_agent_id
+  );
+$$;
+
+comment on function agent_board._actor_fleet_revoked(uuid) is
+  '#276 fleet-revocation predicate: true when an agent-subject agent_board.fleet_revocation_events row exists for this principal. AGENT-WIDE and binding-blind, matching evaluate_fleet_sender_policy''s agent clause, with no effective_at/supersession term (the sender policy honours reactivated_at for MACHINE-subject events only). Takes NO lock: callers that can safely serialise go through _assert_actor_not_fleet_revoked, which share-locks the agents row first; the invite redeem path calls this directly because acquiring the creator''s agents row there closes a deadlock cycle against enroll_federated_identity and onboard_federated_fleet_agent (see 20260909000100 header). Internal: reads for an arbitrary agent id with no authorization of its own.';
+
+revoke all on function agent_board._actor_fleet_revoked(uuid) from public, anon, authenticated;
+grant execute on function agent_board._actor_fleet_revoked(uuid) to service_role;
+
+-- ---------------------------------------------------------------------------
+-- 1b. The LOCKED assert, for callers whose actor is the revoked principal itself.
+-- ---------------------------------------------------------------------------
+create or replace function agent_board._assert_actor_not_fleet_revoked(
+  p_actor_agent_id uuid,
+  p_operation text
+)
+returns void
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_revoked boolean;
+begin
+  -- Fail closed on an unresolved actor. Unreachable from the three chokepoints (each resolves
+  -- or gates its actor first), which is exactly why it is called DIRECTLY by a pgTAP assertion
+  -- rather than left as a branch no mutation could reach (CLAUDE.md rule 2).
+  if p_actor_agent_id is null then
+    raise exception 'fleet_revoked_unresolved: % requires a resolved actor',
+      coalesce(nullif(btrim(p_operation), ''), 'board authority write')
+      using errcode = '42501';
+  end if;
+
+  -- The serialization point. FOR SHARE on the actor's agents row, taken BEFORE the ledger
+  -- read: both agent-subject ledger writers take FOR UPDATE on this row before their write,
+  -- so a concurrent revocation either already committed (and is read below) or blocks here
+  -- until this transaction commits. A missing agents row takes no lock and raises nothing —
+  -- an id that names no agent has no ledger row either, and requiring existence here would be
+  -- a widening this issue did not decide.
+  perform 1 from agent_board.agents a where a.id = p_actor_agent_id for share;
+
+  v_revoked := agent_board._actor_fleet_revoked(p_actor_agent_id);
+
+  if v_revoked then
+    raise exception 'fleet_revoked: % is not permitted for a fleet-revoked agent',
+      coalesce(nullif(btrim(p_operation), ''), 'board authority write')
+      using errcode = '42501';
+  end if;
+end;
+$$;
+
+comment on function agent_board._assert_actor_not_fleet_revoked(uuid, text) is
+  '#276 fleet-revocation gate for the board AUTHORITY chokepoints. Takes FOR SHARE on the actor''s agents row and then refuses (42501, prefix ''fleet_revoked:'') when an agent-subject agent_board.fleet_revocation_events row exists for that actor. The predicate is the AGENT-WIDE ledger row and inspects no fleet_machine_agents binding, which is the same question evaluate_fleet_sender_policy answers the same way: a binding revoked on one machine while another stays active does not deny the agent, an agent-subject ledger row denies it everywhere. No effective_at/supersession clause — the sender policy honours reactivated_at for MACHINE-subject events only, and reactivate_fleet_machine never un-revokes a sender agent. A principal with NO fleet binding at all (a human, a non-fleet agent) has no such row and passes, so the gate cannot regress non-fleet grantors. The share lock is the serialization point: both writers of an agent-subject row (revoke_fleet_subject, _revoke_agent_principal) take FOR UPDATE on the same agents row before writing, so a racing revocation either is seen or blocks until this transaction commits. FOR SHARE, not FOR KEY SHARE (which would not conflict with a status change''s FOR NO KEY UPDATE) and not FOR UPDATE (which would block every concurrent FK insert naming the agent) — the same choice _assert_signed_authority_signer_live makes on the same row. A null actor raises fleet_revoked_unresolved. Internal: it locks and reads rows for an arbitrary agent id with no authorization of its own.';
+
+revoke all on function agent_board._assert_actor_not_fleet_revoked(uuid, text) from public, anon, authenticated;
+grant execute on function agent_board._assert_actor_not_fleet_revoked(uuid, text) to service_role;
+
+-- ---------------------------------------------------------------------------
+-- 2. grant_board_role — verbatim from 20260802000100:170 plus the gate, placed immediately
+--    after actor resolution and BEFORE the membership pre-check, so the function's lock order
+--    becomes agents -> board_memberships (see TOTAL ORDERS in the header).
+-- ---------------------------------------------------------------------------
+create or replace function agent_board.grant_board_role(
+  p_board_id uuid,
+  p_agent_id uuid,
+  p_grantee_role text,
+  p_grantor_agent_id uuid default null
+)
+returns table(board_id uuid, agent_id uuid, role text, updated_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_grantor uuid;
+  v_updated agent_board.board_memberships%rowtype;
+begin
+  if p_grantee_role not in ('owner', 'admin', 'member', 'observer') then
+    raise exception 'invalid grantee role' using errcode = '22023';
+  end if;
+
+  -- #276, FORCED BY AN EXISTING CLASS ASSERTION, not chosen. Adding the ledger gate makes this
+  -- function row-lock `agents` (transitively, through _assert_actor_not_fleet_revoked) as well
+  -- as board_memberships, which puts it in the class agent_board_signer_lifecycle.test.sql
+  -- section 9 pins from the call-graph closure: every function locking BOTH relations must take
+  -- the board advisory lock that serialises them against onboard_federated_fleet_agent. That
+  -- assertion FAILED and named this function when the gate was added without this line.
+  --
+  -- The tempting reply is that this function's order is agents -> board_memberships, the SAME
+  -- direction as onboarding, so it cannot close the F4 cycle. That is true today and is exactly
+  -- the ordering argument #269 refused: mutual exclusion survives a lock being added downstream,
+  -- a re-derived ordering does not. So the lock is taken rather than the assertion relaxed.
+  --
+  -- It also closes a gap 20260901000110 left open and explicitly declined to determine: this
+  -- function reads the ceiling for authorization (via _grant_within_ceiling below) and was one
+  -- of the three readers that did NOT take the lock serialising the ceiling row's ABSENCE, so a
+  -- concurrent first-ceiling insert could be missed and the read pass as default-owner. It is
+  -- now serialised, and agent_board_atomic_fleet_onboarding.test.sql's ceiling-reader registry
+  -- records it as such.
+  --
+  -- FIRST, before any row lock, so both routes are advisory -> agents -> board_memberships.
+  -- Re-taking it inside signed_grant_board_role (which already holds it) is a no-op: advisory
+  -- transaction locks are re-entrant within a session.
+  perform agent_board._lock_board_authority_ceiling(p_board_id);
+
+  -- Grantor is the RESOLVED actor. service_role -> supplied arg; authenticated ->
+  -- current_agent_id() and raises 42501 if null (suspended/unmapped) or if the
+  -- supplied arg <> current_agent_id(). This closes the single-principal escalation.
+  v_grantor := agent_board._resolved_actor_agent_id(p_grantor_agent_id, 'p_grantor_agent_id');
+
+  -- #276. Fleet revocation removes board authority, not only send. Sited HERE — inside the
+  -- chokepoint, not in the signed wrapper — because signed_grant_board_role is the only other
+  -- referrer of this function in the whole database, so the signed route inherits this check
+  -- by construction and the unsigned `authenticated` route (the wider door) is closed by the
+  -- same line. Before the membership pre-check so the lock order is agents -> board_memberships,
+  -- matching onboard_federated_fleet_agent; below the write it would be the inversion #269
+  -- reproduced as `deadlock detected`, and this route has no advisory lock to be rescued by.
+  perform agent_board._assert_actor_not_fleet_revoked(v_grantor, 'grant_board_role');
+
+  if not exists (
+    select 1 from agent_board.board_memberships bm
+     where bm.board_id = p_board_id and bm.agent_id = p_agent_id
+       and bm.membership_state in ('joined', 'subscribed')
+  ) then
+    raise exception 'grantee has no membership on this board' using errcode = 'P0002';
+  end if;
+
+  -- Ceiling consumption: grantee-bounded against min(grantor role, board ceiling).
+  if not agent_board._grant_within_ceiling(v_grantor, p_board_id, p_grantee_role) then
+    raise exception 'grant exceeds grantor role or board authority ceiling' using errcode = '42501';
+  end if;
+
+  update agent_board.board_memberships bm
+     set role = p_grantee_role,
+         updated_at = now()
+   where bm.board_id = p_board_id
+     and bm.agent_id = p_agent_id
+     and bm.membership_state in ('joined', 'subscribed')
+   returning * into v_updated;
+
+  -- CR finding: the state predicate above closes the unauthorized WRITE, but on its own it
+  -- CREATES a false-success path. If an eviction commits between the pre-check and this
+  -- UPDATE (the TOCTOU window the mirrored predicate exists for), the UPDATE matches zero
+  -- rows, v_updated stays NULL, and the RETURN QUERY below would emit ONE ALL-NULL ROW with
+  -- no error -- a caller that checks "did I get a row back?" reads that as a completed grant.
+  -- Fail closed with the same P0002 the pre-check raises, so the serial and racing cases are
+  -- indistinguishable to the caller.
+  if not found then
+    raise exception 'grantee has no membership on this board' using errcode = 'P0002';
+  end if;
+
+  return query
+  select v_updated.board_id, v_updated.agent_id, v_updated.role, v_updated.updated_at;
+end;
+$$;
+
+comment on function agent_board.grant_board_role(uuid, uuid, text, uuid) is
+  'Live board-role grant chokepoint. Grantor is the resolved actor (_resolved_actor_agent_id: '
+  'service_role uses the supplied arg, authenticated uses current_agent_id() and fails closed on '
+  'null/mismatch). #276: the resolved grantor is then checked against the fleet revocation ledger '
+  'by _assert_actor_not_fleet_revoked -- an agent carrying an agent-subject fleet_revocation_events '
+  'row cannot complete a grant (42501, ''fleet_revoked:''), which is the same answer '
+  'evaluate_fleet_sender_policy already gives that principal on the send path. The check sits in '
+  'THIS function rather than in signed_grant_board_role because signed_grant_board_role is the only '
+  'other referrer of it in the database, so the signed route inherits the gate and the wider '
+  'unsigned authenticated route is closed by the same line; it is placed before the membership '
+  'pre-check so the lock order is agents(FOR SHARE) -> board_memberships, matching '
+  'onboard_federated_fleet_agent. A principal with no fleet binding has no such row and is '
+  'unaffected. Then requires an ACTIVE grantee membership (joined|subscribed; P0002 otherwise) -- '
+  'predicate on both the pre-check and the UPDATE (TOCTOU). Then enforces '
+  '_grant_within_ceiling(grantor, board, grantee_role) before setting board_memberships.role. '
+  'ROLERESET (#79): non-active rows cannot be re-armed with an elevated role.';
+
+revoke all on function agent_board.grant_board_role(uuid, uuid, text, uuid) from public, anon;
+grant execute on function agent_board.grant_board_role(uuid, uuid, text, uuid) to authenticated, service_role;
+
+-- ---------------------------------------------------------------------------
+-- 3. set_board_authority_ceiling — verbatim from 20260907000100:59 plus the gate, placed
+--    AFTER the upsert so the order stays advisory -> boards -> agents. Hoisting it would give
+--    agents -> boards and invert against onboard_federated_fleet_agent and the federated
+--    enroll routes on the (agents, boards) pair. One transaction, so the raise rolls the
+--    upsert back.
+-- ---------------------------------------------------------------------------
+create or replace function agent_board.set_board_authority_ceiling(
+  p_board_id uuid,
+  p_max_grantable_role text,
+  p_actor_agent_id uuid default null
+)
+returns table(
+  ceiling_board_id uuid,
+  ceiling_max_grantable_role text
+)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_actor uuid;
+begin
+  if p_max_grantable_role not in ('owner', 'admin', 'member', 'observer') then
+    raise exception 'max_grantable_role must be one of owner/admin/member/observer' using errcode = '22023';
+  end if;
+
+  -- Same board-keyed advisory lock every ceiling READER for authorization takes.
+  -- Held to commit, it makes the insert of a first ceiling row serialize against a
+  -- concurrent authorization that would otherwise observe the pre-insert ABSENCE and
+  -- pass as default-owner. Taken before the owner gate so the gate and the write are
+  -- one critical section.
+  perform agent_board._lock_board_authority_ceiling(p_board_id);
+
+  -- #247. Actor resolution, NOT a widening of the gate. With p_actor_agent_id omitted this
+  -- is the pre-#247 expression for every role, so no existing caller changes behaviour
+  -- (D4). When it IS supplied, _resolved_actor_agent_id binds it: service_role takes the
+  -- argument (this is the signed_* gateway path, where the argument is the gateway-VERIFIED
+  -- signer, never a raw caller claim), while authenticated still resolves to
+  -- current_agent_id() and raises 42501 if the supplied id differs. The owner gate below is
+  -- untouched and remains the only thing that authorizes the write.
+  if p_actor_agent_id is null then
+    v_actor := agent_board.current_agent_id();
+  else
+    v_actor := agent_board._resolved_actor_agent_id(p_actor_agent_id, 'p_actor_agent_id');
+  end if;
+
+  if v_actor is null
+     or not exists (
+       select 1
+         from agent_board.board_memberships bm
+        where bm.board_id = p_board_id
+          and bm.agent_id = v_actor
+          and bm.role = 'owner'
+          and bm.membership_state in ('joined', 'subscribed')
+     ) then
+    raise exception 'only a board owner may set the board authority ceiling' using errcode = '42501';
+  end if;
+
+  insert into agent_board.board_authority_ceilings(board_id, max_grantable_role)
+  values (p_board_id, p_max_grantable_role)
+  on conflict (board_id) do update
+    set max_grantable_role = excluded.max_grantable_role,
+        updated_at = now();
+
+  -- #276, AFTER the upsert by design (see the header's TOTAL ORDERS). The ceiling insert
+  -- reaches boards through board_authority_ceilings' FK, so checking here keeps this
+  -- function's order advisory -> boards -> agents, which is onboard_federated_fleet_agent's
+  -- order and the signed wrapper's. Same transaction: this raise rolls the upsert back, so
+  -- position costs nothing in correctness. Raising the ceiling is a strictly larger authority
+  -- act than a single grant, so a ledger-revoked owner must not reach it either.
+  perform agent_board._assert_actor_not_fleet_revoked(v_actor, 'set_board_authority_ceiling');
+
+  return query
+  select p_board_id, p_max_grantable_role;
+end;
+$$;
+
+comment on function agent_board.set_board_authority_ceiling(uuid, text, uuid) is
+  'Owner-gated setter for a board''s authority ceiling: takes the board-keyed _lock_board_authority_ceiling advisory lock, then upserts board_authority_ceilings only when the resolved actor is an owner of the board (else raises 42501). The actor is current_agent_id() when p_actor_agent_id is omitted — the pre-#247 behaviour for every role — and _resolved_actor_agent_id(p_actor_agent_id) when it is supplied, which lets the service_role-only signed_set_board_authority_ceiling gateway act for the gateway-verified signer while still forcing an authenticated caller to match current_agent_id(). #276: after the upsert it calls _assert_actor_not_fleet_revoked, so an actor carrying an agent-subject fleet_revocation_events row cannot raise or lower a board ceiling (42501, ''fleet_revoked:'') — the same principal the send path already refuses. It sits AFTER the upsert, not before, so the lock order stays advisory -> boards -> agents; hoisting it would give agents -> boards and invert against onboard_federated_fleet_agent on the (agents, boards) pair. The function is one transaction, so the raise rolls the upsert back. Leaves _grant_within_ceiling semantics unchanged.';
+
+revoke all on function agent_board.set_board_authority_ceiling(uuid, text, uuid) from public, anon;
+grant execute on function agent_board.set_board_authority_ceiling(uuid, text, uuid) to authenticated, service_role;
+
+-- ---------------------------------------------------------------------------
+-- 4. set_board_role_gate — verbatim from 20260725000100:22 plus the gate, placed AFTER the
+--    boards UPDATE for the same lock-order reason (boards -> agents). This function has no
+--    signed wrapper and no other referrer anywhere in the database.
+-- ---------------------------------------------------------------------------
+create or replace function agent_board.set_board_role_gate(
+  p_board_id uuid,
+  p_enforced boolean
+)
+returns table(
+  board_id uuid,
+  role_gate_enforced boolean,
+  updated_at timestamptz
+)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_actor uuid := agent_board.current_agent_id();
+  v_row agent_board.boards%rowtype;
+begin
+  if p_enforced is null then
+    raise exception 'p_enforced must not be null' using errcode = '22023';
+  end if;
+
+  -- Owner gate: only an active owner-role member may flip the gate. service_role
+  -- (current_agent_id() = null) is not an owner and is rejected here (it keeps its
+  -- direct table-write grant for operator provisioning).
+  if v_actor is null
+     or not exists (
+       select 1
+         from agent_board.board_memberships bm
+        where bm.board_id = p_board_id
+          and bm.agent_id = v_actor
+          and bm.role = 'owner'
+          and bm.membership_state in ('joined', 'subscribed')
+     ) then
+    raise exception 'only a board owner may set the role gate' using errcode = '42501';
+  end if;
+
+  update agent_board.boards b
+     set role_gate_enforced = p_enforced,
+         updated_at = now()
+   where b.id = p_board_id
+  returning * into v_row;
+
+  if v_row.id is null then
+    raise exception 'board not found' using errcode = 'P0002';
+  end if;
+
+  -- #276, AFTER the boards UPDATE so this function's order is boards -> agents, the canonical
+  -- one (#194). Flipping role_gate_enforced decides whether the creator-identity exemption
+  -- applies to invite_board_member and resolve_board_request, so it is an authority write in
+  -- the same class as a grant. Same transaction: the raise rolls the UPDATE back.
+  perform agent_board._assert_actor_not_fleet_revoked(v_actor, 'set_board_role_gate');
+
+  return query
+  select v_row.id, v_row.role_gate_enforced, v_row.updated_at;
+end;
+$$;
+
+comment on function agent_board.set_board_role_gate(uuid, boolean) is
+  'Owner-gated setter for a board''s role_gate_enforced flag: UPDATEs boards.role_gate_enforced only when current_agent_id() is an active owner of the board (else 42501; null p_enforced -> 22023; missing board -> P0002). service_role is not an owner here. #276: after the UPDATE it calls _assert_actor_not_fleet_revoked, so an owner carrying an agent-subject fleet_revocation_events row cannot flip the gate (42501, ''fleet_revoked:''); the flag decides whether the creator-identity exemption applies to invite_board_member and resolve_board_request, which makes it an authority write in the same class as a role grant. Placed after the UPDATE so the lock order is boards -> agents, the canonical order (#194); the function is one transaction, so the raise rolls the UPDATE back.';
+
+revoke all on function agent_board.set_board_role_gate(uuid, boolean) from public, anon;
+grant execute on function agent_board.set_board_role_gate(uuid, boolean) to authenticated, service_role;
+
+-- ---------------------------------------------------------------------------
+-- 5. create_invite_link — the MINT half of the invite route. Verbatim from
+--    20260724000100 plus the gate, placed AFTER the token insert so the order is
+--    boards(KEY SHARE, via board_invite_tokens.board_id) -> agents(SHARE), the canonical
+--    direction. Hoisting it would give agents -> boards, inverting against
+--    onboard_federated_fleet_agent and the federated enroll routes.
+--
+--    LOCKED, like the three chokepoints, because the actor here IS the principal whose
+--    authority is being spent: minting an admin link is conferring admin on whoever redeems
+--    it, deferred. Checked acyclic against create_fleet_onboarding_invite (its only in-schema
+--    caller), which holds boards -> fleet_machines -> fleet_trust_domains before it mints, and
+--    against revoke_fleet_subject, which takes fleet_machines -> agents in that same direction.
+-- ---------------------------------------------------------------------------
+create or replace function agent_board.create_invite_link(
+  p_board_id uuid,
+  p_preset_role text,
+  p_preset_membership_state text default 'joined',
+  p_max_uses integer default null,
+  p_expires_at timestamptz default null,
+  p_created_by_agent_id uuid default null,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(
+  invite_id uuid, board_id uuid, code text, preset_role text,
+  preset_membership_state text, max_uses integer, uses_count integer,
+  expires_at timestamptz, created_at timestamptz
+)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_creator uuid;
+  v_expires timestamptz;
+  v_code text;
+  v_row agent_board.board_invite_tokens%rowtype;
+begin
+  if p_preset_role not in ('owner', 'admin', 'member', 'observer') then
+    raise exception 'invalid preset role' using errcode = '22023';
+  end if;
+  -- R-LINK-3: owner presets are not invite-linkable in v1 (a leaked owner link mints
+  -- co-owners). admin presets must be bounded: a use cap AND a short (<= 7d) TTL.
+  if p_preset_role = 'owner' then
+    raise exception 'owner presets are not invite-linkable' using errcode = '22023';
+  end if;
+  if coalesce(p_preset_membership_state, 'joined') not in ('joined', 'subscribed') then
+    raise exception 'invalid preset membership state' using errcode = '22023';
+  end if;
+
+  -- Effective creator: service_role -> supplied arg (create-on-behalf-of);
+  -- authenticated -> current_agent_id() and rejects arg <> current (42501).
+  v_creator := agent_board._resolved_actor_agent_id(p_created_by_agent_id, 'p_created_by_agent_id');
+
+  -- Grantor-bounded at mint: the creator's live authority must cover the preset role.
+  if not agent_board._grant_within_ceiling(v_creator, p_board_id, p_preset_role) then
+    raise exception 'preset role exceeds creator role or board authority ceiling' using errcode = '42501';
+  end if;
+
+  -- TTL: default 7d, hard cap 30d, reject a past/now expiry.
+  v_expires := coalesce(p_expires_at, now() + interval '7 days');
+  if v_expires <= now() then
+    raise exception 'invite expiry must be in the future' using errcode = '22023';
+  end if;
+  if v_expires > now() + interval '30 days' then
+    v_expires := now() + interval '30 days';
+  end if;
+
+  -- R-LINK-3 (admin): require a use cap and a <= 7d TTL.
+  if p_preset_role = 'admin' then
+    if p_max_uses is null then
+      raise exception 'admin invite links require a bounded p_max_uses' using errcode = '22023';
+    end if;
+    if v_expires > now() + interval '7 days' then
+      raise exception 'admin invite links require a TTL of at most 7 days' using errcode = '22023';
+    end if;
+  end if;
+
+  -- 256-bit opaque code, base64url (schema-qualify gen_random_bytes; encode/translate/
+  -- rtrim are pg_catalog builtins).
+  v_code := rtrim(translate(encode(extensions.gen_random_bytes(32), 'base64'), '+/', '-_'), '=');
+
+  insert into agent_board.board_invite_tokens as t(
+    code, board_id, preset_role, preset_membership_state, max_uses, expires_at,
+    created_by_agent_id, metadata
+  )
+  values (
+    v_code, p_board_id, p_preset_role, coalesce(p_preset_membership_state, 'joined'),
+    p_max_uses, v_expires, v_creator, coalesce(p_metadata, '{}'::jsonb)
+  )
+  returning * into v_row;
+
+  -- #276. AFTER the insert, so the order is boards(KEY SHARE via the token's board_id FK) ->
+  -- agents(SHARE) -- see the header. One transaction, so this raise discards the token; a
+  -- revoked creator never gets a code back. The `fleet_revoked:` prefix is kept here (unlike
+  -- the redeem side) because the caller is asking about ITSELF, so there is no oracle to leak.
+  perform agent_board._assert_actor_not_fleet_revoked(v_creator, 'create_invite_link');
+
+  return query
+  select v_row.id, v_row.board_id, v_row.code, v_row.preset_role,
+         v_row.preset_membership_state, v_row.max_uses, v_row.uses_count,
+         v_row.expires_at, v_row.created_at;
+end;
+$$;
+
+comment on function agent_board.create_invite_link(uuid, text, text, integer, timestamptz, uuid, jsonb) is
+  'Mints a shareable board invite link. Grantor-bounded (creator authority must cover the preset role via _grant_within_ceiling). Forbids owner presets; admin presets require a use cap + <=7d TTL. TTL default 7d, hard-capped 30d. Creator resolved via _resolved_actor_agent_id. Returns the opaque code (creator-only). #276: a creator carrying an agent-subject fleet_revocation_events row cannot mint at all (42501, ''fleet_revoked:'') — an admin-preset link is a deferred grant of admin, so minting one is conferring a board role by another route. The gate calls _assert_actor_not_fleet_revoked (share-locked) and sits AFTER the token insert so the lock order is boards(KEY SHARE via the board_id FK) -> agents; the raise discards the token in the same transaction, so a revoked creator never receives a code.';
+
+revoke all on function agent_board.create_invite_link(uuid, text, text, integer, timestamptz, uuid, jsonb) from public, anon;
+grant execute on function agent_board.create_invite_link(uuid, text, text, integer, timestamptz, uuid, jsonb) to authenticated, service_role;
+
+-- ---------------------------------------------------------------------------
+-- 6. _redeem_unbounded_invite_for_agent — the REDEEM half. Verbatim from 20260724000100
+--    (as amended) plus ONE clause added to the existing creator-lifecycle block.
+--
+--    UNLOCKED, and that is the deliberate half of this migration. See "THE INVITE PATHS" in
+--    the header: every way of taking a row lock on the CREATOR here closes a cycle, and the
+--    adjacent R-LINK-2 creator-status check has always been unlocked.
+--
+--    UNIFORM MESSAGE, not the `fleet_revoked:` prefix the other five gates use. Every deny arm
+--    in this function is the same 'invite is not usable' 42501 precisely so a code-bearer
+--    cannot tell a revoked creator from a dead, expired or exhausted link. A distinguishable
+--    message here would build the lifecycle oracle this function documents refusing to build,
+--    and it would leak it to whoever holds the code — who is not the principal being described.
+-- ---------------------------------------------------------------------------
+create or replace function agent_board._redeem_unbounded_invite_for_agent(
+  p_code text,
+  p_agent_id uuid
+)
+returns table(board_id uuid, agent_id uuid, role text, membership_state text, updated_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+-- OUT params board_id/agent_id/role/membership_state/updated_at share names with the
+-- membership columns referenced in the on-conflict target + update set below; prefer
+-- the column in any collision (mirrors ROOMOWN create_board).
+#variable_conflict use_column
+declare
+  v_inv agent_board.board_invite_tokens%rowtype;
+  v_led agent_board.board_invite_redemptions%rowtype;
+  v_m agent_board.board_memberships%rowtype;
+begin
+  -- Lock the token row FIRST (concurrency invariant: the exhaustion check and the
+  -- same-txn uses_count increment happen under this lock, and concurrent redeemers
+  -- of the same token serialize here).
+  select * into v_inv
+    from agent_board.board_invite_tokens t
+   where t.code = p_code
+   for update;
+  if not found then
+    raise exception 'invite is not usable' using errcode = '42501';
+  end if;
+
+  -- M1 idempotency ordering: an existing (invite, agent) ledger row means this is a
+  -- replay -> return the existing membership and SKIP every exhaustion/ceiling check
+  -- (a maxed link re-redeemed by the same agent is a no-op, NOT 42501).
+  select * into v_led
+    from agent_board.board_invite_redemptions r
+   where r.invite_id = v_inv.id
+     and r.agent_id = p_agent_id;
+  if found then
+    select * into v_m
+      from agent_board.board_memberships bm
+     where bm.id = v_led.membership_id;
+    return query
+    select v_m.board_id, v_m.agent_id, v_m.role, v_m.membership_state, v_m.updated_at;
+    return;
+  end if;
+
+  -- Genuinely new redemption: uniform 42501 for revoked / expired / exhausted
+  -- (no P0002-vs-42501 existence oracle).
+  if v_inv.revoked_at is not null then
+    raise exception 'invite is not usable' using errcode = '42501';
+  end if;
+  if v_inv.expires_at <= now() then
+    raise exception 'invite is not usable' using errcode = '42501';
+  end if;
+  if v_inv.max_uses is not null and v_inv.uses_count >= v_inv.max_uses then
+    raise exception 'invite is not usable' using errcode = '42501';
+  end if;
+
+  -- R-LINK-2 suspension containment: the creator must still be an ACTIVE agent
+  -- (revoke_agent suspends but does not drop memberships, so an outstanding link
+  -- from a compromised-then-suspended owner must stop minting).
+  if not exists (
+    select 1 from agent_board.agents a
+     where a.id = v_inv.created_by_agent_id and a.status = 'active'
+  ) then
+    -- Uniform message (see other 42501s) so a code-bearer cannot distinguish
+    -- "creator suspended" from a dead/expired/exhausted link (no lifecycle oracle).
+    raise exception 'invite is not usable' using errcode = '42501';
+  end if;
+
+  -- #276 fleet containment, the sibling of R-LINK-2 one column over. Fleet revocation
+  -- deliberately leaves agents.status = 'active', so the check above passes for a
+  -- ledger-revoked creator and an outstanding admin link kept conferring admin -- the same
+  -- principal the send path already refuses. Keyed on the CREATOR because the creator is who
+  -- confers here; the redeemer is receiving, and its own standing is handled by
+  -- current_agent_id() and by the R-LINK-7 clause below.
+  --
+  -- UNLOCKED (_actor_fleet_revoked, not the share-locking assert) and with the SAME uniform
+  -- message as every other arm. Both choices are load-bearing, not stylistic: see the header.
+  if agent_board._actor_fleet_revoked(v_inv.created_by_agent_id) then
+    raise exception 'invite is not usable' using errcode = '42501';
+  end if;
+
+  -- Re-bind: the creator's CURRENT authority must still cover the preset role
+  -- (stale admin-link auto-degrades if the creator was demoted).
+  if not agent_board._grant_within_ceiling(v_inv.created_by_agent_id, v_inv.board_id, v_inv.preset_role) then
+    raise exception 'invite is not usable' using errcode = '42501';
+  end if;
+
+  -- R-LINK-7 kicked-agent re-entry: refuse when the agent's CURRENT standing on the
+  -- board is 'removed' — i.e. a 'removed' row exists AND there is no active
+  -- (joined/subscribed) membership. The active partial-unique index does NOT cover
+  -- 'removed' rows, so a fresh 'joined' insert would otherwise bypass revocation +
+  -- join-approval. Scoping to "removed and not currently active" avoids a false
+  -- negative for an agent who was removed and then legitimately re-added (an active
+  -- row present ⇒ the rank-max upsert handles them correctly). Voluntary 'left' is
+  -- intentionally NOT blocked (self-departure).
+  if exists (
+    select 1 from agent_board.board_memberships bm
+     where bm.board_id = v_inv.board_id
+       and bm.agent_id = p_agent_id
+       and bm.membership_state = 'removed'
+  ) and not exists (
+    select 1 from agent_board.board_memberships bm
+     where bm.board_id = v_inv.board_id
+       and bm.agent_id = p_agent_id
+       and bm.membership_state in ('joined', 'subscribed')
+  ) then
+    raise exception 'invite is not usable' using errcode = '42501';
+  end if;
+
+  -- Record the ledger row (idempotent under concurrent same-agent redemption).
+  insert into agent_board.board_invite_redemptions as r(invite_id, agent_id)
+  values (v_inv.id, p_agent_id)
+  on conflict (invite_id, agent_id) do nothing;
+
+  -- B1 atomic rank-max membership upsert: never downgrade a higher existing role,
+  -- race-safe across concurrent tokens. On conflict targets the active partial-unique
+  -- index; the CASE lifts ONLY when the preset outranks the current role.
+  insert into agent_board.board_memberships (
+    board_id, agent_id, membership_state, role, created_by_agent_id
+  )
+  values (
+    v_inv.board_id, p_agent_id, v_inv.preset_membership_state, v_inv.preset_role,
+    v_inv.created_by_agent_id
+  )
+  on conflict (board_id, agent_id) where (membership_state in ('joined', 'subscribed'))
+    do update set
+      role = case
+        when agent_board._role_rank(excluded.role) > agent_board._role_rank(agent_board.board_memberships.role)
+          then excluded.role
+        else agent_board.board_memberships.role
+      end,
+      updated_at = now()
+  returning * into v_m;
+
+  -- The redeemer places THEMSELVES -- the public wrapper passes current_agent_id() and takes no
+  -- target parameter -- so this emits target-authored: redeeming a link IS the consenting act.
+  --
+  -- v_m.membership_state, NOT v_inv.preset_membership_state. The ON CONFLICT above lifts only
+  -- the ROLE and leaves an existing membership_state untouched, so an already-`subscribed`
+  -- member redeeming a `joined` link stays subscribed. Emitting the token's preset would
+  -- record a resulting state the row does not have -- a ledger that contradicts the table it
+  -- describes. Recording the redemption as a fresh consent act is right; recording the wrong
+  -- outcome is not.
+  perform agent_board._emit_membership_event(
+    v_inv.board_id, p_agent_id, v_m.membership_state, 'consent_link_redeem');
+
+  -- Consume one use and bind the ledger row to the resulting membership.
+  update agent_board.board_invite_tokens t
+     set uses_count = t.uses_count + 1
+   where t.id = v_inv.id;
+
+  update agent_board.board_invite_redemptions r
+     set membership_id = v_m.id
+   where r.invite_id = v_inv.id
+     and r.agent_id = p_agent_id;
+
+  return query
+  select v_m.board_id, v_m.agent_id, v_m.role, v_m.membership_state, v_m.updated_at;
+end;
+$$;
+
+comment on function agent_board._redeem_unbounded_invite_for_agent(text, uuid) is
+  'Internal ROOMLINK redemption core (service_role-only). Locks the token FOR UPDATE, no-ops idempotently on a replayed (invite, agent), then gates revoked/expired/exhausted (uniform 42501), creator-active (R-LINK-2), creator NOT fleet-revoked (#276), creator ceiling re-bind, and kicked-agent refusal (R-LINK-7) before an atomic rank-max membership upsert + uses_count increment. Shared by redeem_invite_link and the /enroll hook. #276 keys on the CREATOR, the principal who confers here, and is the sibling of R-LINK-2 one column over: fleet revocation leaves agents.status = ''active'', so an outstanding admin link from a ledger-revoked creator kept conferring admin. It calls _actor_fleet_revoked (UNLOCKED) rather than the share-locking assert the other five gates use, because this function is reached from enroll_federated_identity while a boards row lock is already held, and every placement of a creator row lock here closes a cycle against onboard_federated_fleet_agent; the adjacent R-LINK-2 check has likewise always been unlocked. It raises the same uniform ''invite is not usable'' message as every other arm so a code-bearer cannot distinguish a revoked creator from a dead link.';
+
+revoke all on function agent_board._redeem_unbounded_invite_for_agent(text, uuid) from public, anon, authenticated;
+grant execute on function agent_board._redeem_unbounded_invite_for_agent(text, uuid) to service_role;