@consiliency/agent-board-schema 1.53.0 → 1.55.0

package/migrations/20261005000100_agent_board_enroll_token_single_use.sql

@@ -0,0 +1,886 @@
+-- Consiliency/message-board#521: a verified Portal access token enrolls AT MOST ONE key.
+--
+-- WHAT WAS WRONG. /enroll RS256-verifies a Portal access token and checks an Ed25519
+-- proof-of-possession: the NEW key's signature over the token string. Nothing recorded
+-- that a token had been used. The PoP does not stop reuse -- whoever holds the token can
+-- generate a fresh keypair and sign the same token again -- and the existing replay
+-- mechanism (enroll_federated_identity's #176 resumption) is keyed on the KEY, so a fresh
+-- key per request walks straight past it. One held token therefore enrolled an unbounded
+-- number of agents under the same human until it expired: an undesigned delegation path
+-- with none of the bounds the designed one (mint_delegated_child, capped by
+-- delegation_policies) carries.
+--
+-- THE INVARIANT. A verified token binds to at most one agent key, created OR resumed,
+-- enforced atomically in the database:
+--
+--   * agent_board.enroll_token_uses records (token_sha256 -> key fingerprint). The
+--     fingerprint is known before any write, so no reservation state is needed and the
+--     agent is recoverable through agent_signing_keys.fingerprint. No FK: revoking or
+--     deleting a key must never un-consume a token.
+--   * agent_board._enroll_token_bind is the ONLY writer. Same token + same fingerprint
+--     is a no-op and the caller continues into its UNCHANGED body; same token + a
+--     different fingerprint raises SQLSTATE MBT01, which the Edge Function maps to
+--     409 token_already_used. MBT01 is outside every SQLSTATE this schema already uses
+--     (23505 already means "key enrolled / not resumable / frozen contract"), and it is
+--     not PTxxx, which PostgREST would turn into an HTTP status.
+--   * It is called from EXACTLY ONE site: enroll_federated_identity, immediately after the
+--     owner lock and the human-revocation gate and BEFORE the found/not-found split, so
+--     it covers creation (-> _enroll_federated_identity_once) AND resumption. There is no
+--     early return: a same-key retry falls through into the existing (a)/(b)/(c) gates
+--     and redemption exactly as before. onboard_federated_fleet_agent reaches it through
+--     its nested enroll_federated_identity call and only forwards the two arguments; a
+--     second call site there would be a no-op under fall-through, and a mutation removing
+--     either site could then redden nothing.
+--
+-- WHY NO NEW LOCK. Same token => same verified (issuer, subject) => same derived owner O,
+-- and every path that reaches the bind already holds O FOR UPDATE (the identity route at
+-- its owner lock; the fleet route at its own owner lock before the nested call, then
+-- re-entrantly). The owner is coalesce(existing key's owner, derived owner): that is O for
+-- a new key, a key the caller owns, and a legacy null-owner key. The only other case is a
+-- key owned by another principal, which raises at resumption gate (a) in the same
+-- transaction. Two same-token requests are therefore already serialised by an existing
+-- row lock before the bind, and the second one's bind statement sees the first one's
+-- committed row. The primary key is the backstop: were that argument ever broken, the
+-- second insert waits on the first's uncommitted key and fails 23505 -- closed, loud.
+-- Placing the bind ABOVE the owner lock would deadlock the identity route against the
+-- fleet route (fleet holds O, then reaches the token; identity would hold the token, then
+-- wait for O). Placement after the owner lock is what makes the loser a clean MBT01.
+--
+-- THE TOKEN IDENTITY is lowercase hex sha256 over the RS256 SIGNING INPUT
+-- (header "." payload), computed by the Edge Function, which also refuses non-canonical
+-- token encodings. RS256 is deterministic and the signing input is fixed by the
+-- signature, so the hash is invariant under any re-encoding of the signature segment.
+-- The expiry is the token's verified `exp`.
+--
+-- BOUNDED TABLE. Each bind prunes up to 50 rows whose token expired more than an hour
+-- ago. Deleting a row is safe ONLY because an expired token can never pass again: the
+-- Edge Function rejects exp <= now, and the bind itself refuses p_token_expires_at <=
+-- clock_timestamp(). The hour absorbs Edge-Function/database clock skew.
+--
+-- BOTH SIDES READ clock_timestamp(), NEVER now(). now() is fixed at TRANSACTION START, and a
+-- request can start, wait on the owner lock for as long as another transaction holds it, and
+-- only then bind. With now() on the refusal, a request that started before exp and waited
+-- past exp + 1 hour while another enrollment pruned the token's row would find the row gone,
+-- pass its stale expiry check, and bind a SECOND key. The bind runs after the owner lock is
+-- held, so clock_timestamp() there is the time the decision is actually made; and the prune
+-- deletes only rows with exp < clock_timestamp() - 1 hour, each of which the refusal above
+-- already rejects at any later clock_timestamp(). (Review finding, #524 round 1.)
+--
+-- SIGNATURES. enroll_federated_identity and onboard_federated_fleet_agent gain
+-- (p_token_sha256 text, p_token_expires_at timestamptz) immediately after p_pop_verified,
+-- with NO defaults, and the old signatures are DROPPED -- `create or replace` with a
+-- changed argument list would leave the unguarded overload callable. An old Edge Function
+-- calling with the old named arguments therefore resolves to no function (PGRST202) and
+-- fails closed rather than falling through to an unguarded path.
+-- _enroll_federated_identity_once is unchanged in signature and body; its service_role
+-- EXECUTE grant is revoked. service_role has no direct INSERT on agent_signing_keys or
+-- agents, so that grant was a real, unguarded creation path, and its only caller is a
+-- postgres-owned definer that needs no grant.
+--
+-- DROP DISCARDS THE ACL AND THE COMMENT, and a recreated function grants EXECUTE to
+-- PUBLIC by default, so every revoke/grant/comment is restated below in this file.
+--
+-- THIS MIGRATION MUST BE APPLIED INSIDE ONE TRANSACTION. The live apply path is one
+-- Management-API request per migration, which is one implicit transaction, so the drop,
+-- the create, the ACL and the comment commit together and no caller ever sees a missing
+-- function. Applied statement-at-a-time (the local replay harness) there is a
+-- drop-to-create gap on a scratch database; that gap is an AVAILABILITY gap only --
+-- both recreated bodies raise 42501 on `not _is_service_role()` before anything else, so
+-- the transient PUBLIC EXECUTE is not exploitable on its own.
+--
+-- The function bodies below are pg_get_functiondef of the live definers on a fresh bundle
+-- built from this tree (20260916000100, written in UPPERCASE), NOT copies from a
+-- migration file, plus exactly: the two parameters, the bind call (enroll_federated_identity
+-- only), and onboard_federated_fleet_agent forwarding the two arguments to its nested call.
+
+create table if not exists agent_board.enroll_token_uses (
+  token_sha256 text primary key check (token_sha256 ~ '^[0-9a-f]{64}$'),
+  agent_public_key_fingerprint text not null,
+  token_expires_at timestamptz not null,
+  created_at timestamptz not null default now()
+);
+
+create index if not exists enroll_token_uses_token_expires_at_idx
+  on agent_board.enroll_token_uses (token_expires_at);
+
+alter table agent_board.enroll_token_uses enable row level security;
+revoke all on table agent_board.enroll_token_uses from public, anon, authenticated, service_role;
+
+comment on table agent_board.enroll_token_uses is
+  'One row per verified Portal access token that has enrolled or resumed a key (#521): token_sha256 is lowercase hex sha256 of the RS256 signing input (header.payload), bound to exactly one agent_public_key_fingerprint. Written ONLY by _enroll_token_bind, called ONLY from enroll_federated_identity. No FK to keys or agents by design: revoking or deleting a key must not un-consume a token. RLS on with zero policies and no API-role grants. Rows are pruned by _enroll_token_bind once token_expires_at is more than an hour past, which is safe only because an expired token can never pass /enroll or the bind again.';
+
+create or replace function agent_board._enroll_token_bind(
+  p_token_sha256 text,
+  p_token_expires_at timestamptz,
+  p_fingerprint text
+)
+returns void
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_bound_fingerprint text;
+begin
+  -- Not reachable through the API once the revoke below applies. This guard covers the one
+  -- gap the revoke cannot: applied statement-at-a-time (the local replay harness), this
+  -- CREATE commits with PUBLIC EXECUTE before the next statement revokes it.
+  if not agent_board._is_service_role() then
+    raise exception 'service_role required for _enroll_token_bind' using errcode = '42501';
+  end if;
+  if p_token_sha256 is null or p_token_sha256 !~ '^[0-9a-f]{64}$' then
+    raise exception 'enroll token hash is missing or malformed' using errcode = '22023';
+  end if;
+  if p_token_expires_at is null then
+    raise exception 'enroll token expiry is required' using errcode = '22023';
+  end if;
+  -- Defence in depth, and what makes the prune below safe from the database side: a
+  -- token whose row could already have been pruned is refused here, not re-bound.
+  -- clock_timestamp(), not now(): this runs after the caller's owner-lock WAIT, and now()
+  -- is the transaction's START time (see the header).
+  if p_token_expires_at <= clock_timestamp() then
+    raise exception 'enroll token has expired' using errcode = '22023';
+  end if;
+  if p_fingerprint is null then
+    raise exception 'agent public key fingerprint is required' using errcode = '22023';
+  end if;
+
+  select u.agent_public_key_fingerprint into v_bound_fingerprint
+    from agent_board.enroll_token_uses u
+   where u.token_sha256 = p_token_sha256;
+
+  if found then
+    -- Same key: a no-op. The caller continues into its unchanged body, which re-runs
+    -- every existing gate; nothing returns early from here.
+    if v_bound_fingerprint is distinct from p_fingerprint then
+      raise exception 'enroll token already bound to a different key' using errcode = 'MBT01';
+    end if;
+  else
+    -- A plain insert, deliberately WITHOUT `on conflict`. The caller's owner lock
+    -- serialises same-token requests, so a conflict here needs two requests holding
+    -- DIFFERENT owner locks -- reachable only when one presents a key owned by another
+    -- principal, which resumption gate (a) refuses in the same transaction anyway. When
+    -- it does happen it must surface as a loud 23505, never pass silently. It is not
+    -- claimed to be impossible.
+    insert into agent_board.enroll_token_uses (token_sha256, agent_public_key_fingerprint, token_expires_at)
+    values (p_token_sha256, p_fingerprint, p_token_expires_at);
+  end if;
+
+  -- Bounded prune. DELETE has no LIMIT, so it is keyed through the primary key;
+  -- `skip locked` keeps concurrent enrollments from queueing on each other's cleanup.
+  delete from agent_board.enroll_token_uses d
+   where d.token_sha256 in (
+     select u.token_sha256
+       from agent_board.enroll_token_uses u
+      where u.token_expires_at < clock_timestamp() - interval '1 hour'
+      order by u.token_expires_at
+      limit 50
+      for update skip locked
+   );
+end;
+$$;
+
+revoke all on function agent_board._enroll_token_bind(text, timestamptz, text) from public, anon, authenticated, service_role;
+
+comment on function agent_board._enroll_token_bind(text, timestamptz, text) is
+  'Binds a verified Portal access token (lowercase hex sha256 of its RS256 signing input) to exactly one agent key fingerprint (#521). Same token + same fingerprint: no-op, the caller continues into its unchanged body. Same token + a different fingerprint: raises SQLSTATE MBT01 (the Edge Function maps it to 409 token_already_used). Not found: a plain insert WITHOUT on conflict -- the caller''s owner lock serialises same-token requests, and the primary key is the fail-closed backstop (23505). Raises 22023 on a null or malformed hash, a null expiry, an expiry <= clock_timestamp() (never now(): the bind runs after an owner-lock wait), or a null fingerprint; raises 42501 unless the caller is service_role. Prunes up to 50 rows expired more than an hour before clock_timestamp(). Called ONLY from enroll_federated_identity, after its owner lock and revocation gate; not EXECUTE-able by any API role.';
+
+-- ---------------------------------------------------------------------------
+-- Drop the token-less signatures. Nothing may keep resolving to them.
+-- ---------------------------------------------------------------------------
+drop function agent_board.onboard_federated_fleet_agent(text, text, text, jsonb, text, text, text, text, boolean, text, text, text[], text[], text, uuid, uuid, text, text, text, text, text, text, text);
+drop function agent_board.enroll_federated_identity(text, text, text, jsonb, text, text, text, text, boolean, text, text, text[], text[], text);
+
+CREATE OR REPLACE FUNCTION agent_board.enroll_federated_identity(p_issuer text, p_audience text, p_subject text, p_human_identity_claim jsonb, p_slug text, p_agent_public_key text, p_agent_public_key_format text, p_agent_public_key_fingerprint text, p_pop_verified boolean, p_token_sha256 text, p_token_expires_at timestamp with time zone, p_actor_sub text DEFAULT NULL::text, p_agent_kind text DEFAULT 'agent'::text, p_requested_scopes text[] DEFAULT '{}'::text[], p_requested_board_scopes text[] DEFAULT '{}'::text[], p_invite_code text DEFAULT NULL::text)
+ RETURNS TABLE(agent_id uuid, auth_user_id uuid, provider_id text, signing_key_id uuid, granted_scopes text[], key_id text, key_version integer, agent_handle text, invite_redeemed boolean)
+ LANGUAGE plpgsql
+ SECURITY DEFINER
+ SET search_path TO 'agent_board', 'public'
+AS $function$
+#variable_conflict use_column
+declare
+  v_fingerprint text;
+  v_existing record;
+  v_created record;
+  v_replay jsonb;
+  v_invite_redeemed boolean := false;
+  v_slug text;
+  v_kind text := lower(btrim(coalesce(p_agent_kind, 'agent')));
+  v_requested_scopes text[] := coalesce(p_requested_scopes, '{}');
+  v_requested_board_scopes text[] := coalesce(p_requested_board_scopes, '{}');
+  v_provider agent_board.identity_providers%rowtype;
+  v_invite_board_id uuid;
+  v_claim_audience jsonb;
+  v_owner_user_id uuid;
+  -- #176 resumption. `v_derived_owner_user_id` is the auth user the CALLER's verified
+  -- (issuer, subject) derives to; `v_creation_federation` is the federation object the
+  -- ORIGINAL enrollment stamped on the agent; `v_owned_by_caller` is the conjunction of
+  -- the three stored-evidence tests, coalesced so missing evidence reads as NOT-owned.
+  v_derived_owner_user_id uuid;
+  v_creation_federation jsonb;
+  v_owned_by_caller boolean;
+begin
+  if not agent_board._is_service_role() then
+    raise exception 'service_role required for enroll_federated_identity' using errcode = '42501';
+  end if;
+  if p_pop_verified is not true then
+    raise exception 'proof-of-possession was not verified' using errcode = '42501';
+  end if;
+  if p_subject is null then
+    raise exception 'verified subject is required' using errcode = '22023';
+  end if;
+  if p_human_identity_claim is null then
+    raise exception 'human identity claim is required' using errcode = '22023';
+  end if;
+
+  select * into v_provider from agent_board.identity_providers ip
+   where ip.issuer = p_issuer and ip.audience = p_audience limit 1;
+  if v_provider.id is null then
+    raise exception 'issuer/audience not in the identity-provider allowlist' using errcode = '42501';
+  end if;
+
+  v_claim_audience := agent_board._normalized_federation_audience(p_human_identity_claim);
+  if p_human_identity_claim ->> 'iss' is distinct from p_issuer
+     or p_human_identity_claim ->> v_provider.subject_claim is distinct from p_subject
+     or v_claim_audience is null
+     or not (v_claim_audience ? p_audience) then
+    raise exception 'verified stable claim projection does not match enrollment inputs' using errcode = '22023';
+  end if;
+  if p_agent_public_key_format is distinct from 'raw_ed25519_base64url'
+     or p_agent_public_key is null or p_agent_public_key !~ '^[A-Za-z0-9_-]{43}$' then
+    raise exception 'malformed agent public key' using errcode = '22023';
+  end if;
+  v_fingerprint := agent_board._raw_key_fingerprint(p_agent_public_key);
+  if p_agent_public_key_fingerprint is distinct from v_fingerprint then
+    raise exception 'agent public key fingerprint mismatch' using errcode = '22023';
+  end if;
+  v_slug := agent_board._normalize_provision_slug(p_slug);
+
+  if not v_provider.supported or not v_provider.policy_approved then
+    raise exception 'identity provider is not approved' using errcode = '42501';
+  end if;
+  if v_kind = 'system' then
+    raise exception 'the system kind cannot be federated' using errcode = '42501';
+  end if;
+  if v_kind not in ('human', 'agent') then
+    raise exception 'agent kind must be human or agent' using errcode = '22023';
+  end if;
+  if array_length(v_provider.allowed_agent_kinds, 1) is not null
+     and not (v_kind = any(v_provider.allowed_agent_kinds)) then
+    raise exception 'agent kind is outside the provider ceiling' using errcode = '42501';
+  end if;
+  if not (v_requested_scopes <@ v_provider.allowed_scopes)
+     or not (v_requested_board_scopes <@ v_provider.allowed_board_scopes) then
+    raise exception 'requested scopes exceed the provider ceiling' using errcode = '42501';
+  end if;
+
+  if nullif(btrim(coalesce(p_invite_code, '')), '') is not null and exists (
+    select 1 from agent_board.board_invite_tokens bit
+    join agent_board.fleet_onboarding_invite_bounds b on b.invite_id = bit.id
+    where bit.code = btrim(p_invite_code)
+  ) then
+    raise exception 'fleet invite requires atomic fleet onboarding' using errcode = '42501';
+  end if;
+
+
+  -- #194 LOCK ORDER -- BOARD BEFORE OWNER, and the reason is an FK this function
+  -- never names. The redemption below inserts board_memberships, which takes FOR
+  -- KEY SHARE on the invite's agent_board.boards row through
+  -- board_memberships_board_id_fkey. That acquisition used to land AFTER the
+  -- auth.users owner lock, inverting against enroll_federated_human and
+  -- onboard_federated_fleet_agent -- both of which take board -> owner -- and the
+  -- resulting cycle was reproduced as `deadlock detected ... while locking tuple
+  -- in relation "boards"`. Acquire the invite row and its board here, in the same
+  -- relative order _redeem_unbounded_invite_for_agent and
+  -- onboard_federated_fleet_agent take them (invite -> board), and in the SAME mode
+  -- the redemption itself uses, so the redemption below acquires nothing new. Absence is deliberately NOT fatal: a missing,
+  -- revoked, expired or exhausted code still falls through to redemption, which
+  -- stays the sole authority on invite usability (soft-honor contract).
+  if nullif(btrim(coalesce(p_invite_code, '')), '') is not null then
+    select bit.board_id into v_invite_board_id
+      from agent_board.board_invite_tokens bit
+     where bit.code = nullif(btrim(coalesce(p_invite_code, '')), '')
+     for update;
+    if v_invite_board_id is not null then
+      perform 1 from agent_board.boards b
+       where b.id = v_invite_board_id
+       for key share;
+    end if;
+  end if;
+
+  perform pg_advisory_xact_lock(hashtextextended(v_fingerprint, 0));
+
+  select a.owner_user_id into v_owner_user_id
+    from agent_board.agent_signing_keys k
+    join agent_board.agents a on a.id = k.agent_id
+   where k.fingerprint = v_fingerprint;
+  v_owner_user_id := coalesce(v_owner_user_id, agent_board._ensure_agent_auth_user(
+    agent_board._federated_identity_slug(p_issuer, p_subject)
+  ));
+  perform 1 from auth.users u where u.id = v_owner_user_id for update;
+  if exists (
+    select 1 from agent_board.fleet_human_revocations r
+     where r.issuer = p_issuer and r.subject = p_subject
+  ) then
+    raise exception 'human owner has been revoked' using errcode = '42501';
+  end if;
+
+  -- #521 THE TOKEN BINDING -- one site, here, for BOTH branches below. The owner lock
+  -- above already serialises every request carrying this token (same token => same
+  -- verified (issuer, subject) => same owner), so the bind needs no lock of its own; and
+  -- it sits AFTER that lock deliberately -- above it, the identity route would hold the
+  -- token and wait for the owner while the fleet route holds the owner and waits for the
+  -- token. A different key under a used token raises MBT01 here. The same key falls
+  -- THROUGH: nothing returns early, so resumption gates (a)/(b)/(c) and redemption below
+  -- run exactly as they did before this call existed.
+  perform agent_board._enroll_token_bind(p_token_sha256, p_token_expires_at, v_fingerprint);
+
+  -- #176 (i): the auth user the CALLER's verified (issuer, subject) derives to, by the
+  -- SAME derivation _enroll_federated_identity_once step (7) used to mint the owner --
+  -- now literally the same function, agent_board._federated_identity_slug (#246), not a
+  -- second copy of the expression. Resolved by a PURE LOOKUP against the deterministic
+  -- email _ensure_agent_auth_user builds -- calling THAT function here would MINT an owner
+  -- row for whatever principal a squat attempt claimed. The slug helper is pure and mints
+  -- nothing, so computing the slug here is safe; only _ensure_agent_auth_user writes. Read-only: no FOR UPDATE, no row
+  -- lock, so the #194 board -> owner order above is untouched.
+  select u.id into v_derived_owner_user_id
+    from auth.users u
+   where lower(u.email) = format('agent+%s@agent-board.local',
+           agent_board._federated_identity_slug(p_issuer, p_subject))
+   limit 1;
+
+  select a.id as agent_id, a.auth_user_id, a.handle, a.agent_type, a.status,
+         a.metadata, a.owner_user_id, k.id as signing_key_id, k.key_id, k.key_version,
+         k.public_key, k.public_key_format, k.status as key_status, k.proof_state,
+         (select e.granted_scopes
+            from agent_board.enrollment_federation_audit e
+           where e.agent_id = a.id
+             and e.issuer = p_issuer
+             and e.subject = p_subject
+             and e.provider_id = v_provider.id) as granted_scopes
+    into v_existing
+    from agent_board.agent_signing_keys k
+    join agent_board.agents a on a.id = k.agent_id
+   where k.fingerprint = v_fingerprint
+   for update of a, k;
+
+  if found then
+    v_replay := v_existing.metadata #> '{federation,replay}';
+    v_creation_federation := v_existing.metadata #> '{federation}';
+
+    -- #176 OWNERSHIP, from evidence written at the ORIGINAL enrollment -- never from a
+    -- caller argument asserting who acted. (i) the one-way-derived owner, (ii) the
+    -- creation-time federation stamp, (iii) the original enrollment's audit row. All
+    -- three must agree, and the whole conjunction is coalesced to FALSE: any NULL here
+    -- (absent metadata, absent owner) means ownership is UNPROVEN, and unproven must
+    -- read as not-owned rather than leaving the `if not` below untaken.
+    v_owned_by_caller := coalesce(
+          v_creation_federation ->> 'issuer' = p_issuer
+      and v_creation_federation ->> 'subject' = p_subject
+      and v_creation_federation ->> 'providerId' = v_provider.id
+      and exists (
+        select 1
+          from agent_board.enrollment_federation_audit e
+         where e.agent_id = v_existing.agent_id
+           and e.issuer = p_issuer
+           and e.subject = p_subject
+           and e.provider_id = v_provider.id
+      )
+      -- (i) is REQUIRED WHENEVER IT EXISTS and is the one conjunct with an exemption,
+      -- so its claim is stated positively rather than left as "unless". A row whose
+      -- owner_user_id is NULL predates the owner model entirely (the atomic-fleet
+      -- backfill fixture is exactly that shape, and replaying such a row is released,
+      -- asserted behaviour): (i) is UNAVAILABLE there, not contradicted. It is also not
+      -- the binding that does the work. (ii) and (iii) already name the principal, and
+      -- reaching them at all requires a claim the edge function VERIFIED for that same
+      -- issuer and subject, so a null owner narrows corroboration without widening who
+      -- may resume. A NON-NULL owner that disagrees with the derived one is a hard
+      -- refusal, which is what keeps this from being a hole.
+      and (
+        v_existing.owner_user_id is null
+        or (v_derived_owner_user_id is not null
+            and v_existing.owner_user_id = v_derived_owner_user_id)
+      ), false);
+
+    -- (a) THE KEY-SQUAT this check exists to prevent, and the FIRST thing decided, so a
+    -- caller that does not own the key learns nothing else about it. No handle is named:
+    -- telling a squatter which agent holds the key it just probed is the leak this
+    -- ordering avoids. Everything below runs only for the proven owner.
+    if not v_owned_by_caller then
+      raise exception 'this signing key is already enrolled to a different principal; enrollment is refused; generate a NEW key rather than re-presenting this one'
+        using errcode = '23505';
+    end if;
+
+    -- (b) the owner is asking to resume, but the identity is not in a resumable state.
+    -- Resumption returns an existing identity; it never revives a revoked, unproven or
+    -- drifted one, and it never invents an audit trail that is not there.
+    if v_existing.public_key is distinct from p_agent_public_key
+       or v_existing.public_key_format is distinct from p_agent_public_key_format
+       or v_existing.key_status <> 'active'
+       or v_existing.proof_state <> 'proven'
+       or v_existing.status <> 'active'
+       or v_existing.granted_scopes is null then
+      raise exception 'this signing key is already enrolled to you as agent "%", but that identity is not resumable (its key or agent is inactive or unproven, its stored public key differs, or its enrollment audit records no granted scopes); enrollment need not be repeated; report this handle to an operator',
+        v_existing.handle using errcode = '23505';
+    end if;
+
+    -- (c) a STAMPED enrollment (20260901000100 and later) still holds its frozen identity
+    -- contract exactly as before -- the check is unchanged, only its message improves to
+    -- name the handle and say the enrollment already exists. An UNSTAMPED enrollment
+    -- (every identity created before 20260901000100, including the #176 victim) has no
+    -- frozen contract to check and resumes on the ownership evidence alone; that absence
+    -- used to be the raise that trapped it.
+    if v_replay is not null
+       and (v_replay ->> 'issuer' is distinct from p_issuer
+         or v_replay -> 'audience' is distinct from v_claim_audience
+         or v_replay ->> 'subject' is distinct from p_subject
+         or v_replay ->> 'requestedSlug' is distinct from v_slug
+         or v_replay ->> 'agentKind' is distinct from v_kind
+         or v_replay -> 'actorSub' is distinct from coalesce(to_jsonb(p_actor_sub), 'null'::jsonb)
+         or v_replay -> 'requestedScopes' is distinct from to_jsonb(v_requested_scopes)
+         or v_replay -> 'requestedBoardScopes' is distinct from to_jsonb(v_requested_board_scopes)
+         or v_replay ->> 'providerId' is distinct from v_provider.id) then
+      raise exception 'this signing key is already enrolled to you as agent "%" (enrollment need not be repeated), but this request differs from that enrollment''s frozen identity contract (slug, agent kind, actor or requested scopes); re-send the original inputs, or use the existing identity as-is',
+        v_existing.handle using errcode = '23505';
+    end if;
+
+    if nullif(btrim(coalesce(p_invite_code, '')), '') is not null then
+      begin
+        perform agent_board._redeem_invite_for_agent(btrim(p_invite_code), v_existing.agent_id);
+        v_invite_redeemed := true;
+      exception when others then
+        -- #194: a serialization failure is NOT "the invite was not redeemed".
+        -- Swallowing class 40 here reported enrollment SUCCESS to the caller with
+        -- invite_redeemed=false and no membership row, while the deadlock counter
+        -- ticked and no error reached the client. Re-raise the whole class
+        -- (40001 serialization_failure, 40P01 deadlock_detected, 40003, 40002)
+        -- and keep the soft-honor contract for every deterministic failure.
+        if left(sqlstate, 2) = '40' then
+          raise;
+        end if;
+        v_invite_redeemed := false;
+      end;
+    end if;
+
+    -- provider_id comes from STORED evidence, not the request: the replay stamp when
+    -- there is one, otherwise the creation-time federation object. The ownership gate
+    -- already pinned that value to v_provider.id, so the two agree by construction --
+    -- but reading it from the row keeps the returned receipt sourced where every other
+    -- returned field is.
+    return query select v_existing.agent_id, v_existing.auth_user_id,
+      coalesce(v_replay ->> 'providerId', v_creation_federation ->> 'providerId'), v_existing.signing_key_id,
+      v_existing.granted_scopes, v_existing.key_id, v_existing.key_version,
+      v_existing.handle, v_invite_redeemed;
+    return;
+  end if;
+
+  select * into v_created from agent_board._enroll_federated_identity_once(
+    p_issuer, p_audience, p_subject, p_human_identity_claim, p_slug,
+    p_agent_public_key, p_agent_public_key_format, p_agent_public_key_fingerprint,
+    p_pop_verified, p_actor_sub, p_agent_kind, v_requested_scopes,
+    v_requested_board_scopes, p_invite_code
+  );
+
+  update agent_board.agents a
+     set metadata = jsonb_set(a.metadata, '{federation,replay}', jsonb_build_object(
+       'issuer', p_issuer, 'audience', v_claim_audience, 'subject', p_subject,
+       'providerId', v_created.provider_id,
+       'actorSub', coalesce(to_jsonb(p_actor_sub), 'null'::jsonb),
+       'requestedSlug', v_slug, 'agentKind', v_kind,
+       'requestedScopes', to_jsonb(v_requested_scopes),
+       'requestedBoardScopes', to_jsonb(v_requested_board_scopes)
+     ), true)
+   where a.id = v_created.agent_id;
+
+  return query select v_created.agent_id, v_created.auth_user_id,
+    v_created.provider_id, v_created.signing_key_id, v_created.granted_scopes,
+    v_created.key_id, v_created.key_version, v_created.agent_handle,
+    v_created.invite_redeemed;
+end;
+$function$;
+
+CREATE OR REPLACE FUNCTION agent_board.onboard_federated_fleet_agent(p_issuer text, p_audience text, p_subject text, p_human_identity_claim jsonb, p_slug text, p_agent_public_key text, p_agent_public_key_format text, p_agent_public_key_fingerprint text, p_pop_verified boolean, p_token_sha256 text, p_token_expires_at timestamp with time zone, p_actor_sub text DEFAULT NULL::text, p_agent_kind text DEFAULT 'agent'::text, p_requested_scopes text[] DEFAULT '{}'::text[], p_requested_board_scopes text[] DEFAULT '{}'::text[], p_invite_code text DEFAULT NULL::text, p_board_id uuid DEFAULT NULL::uuid, p_machine_id uuid DEFAULT NULL::uuid, p_harness_kind text DEFAULT NULL::text, p_harness_label text DEFAULT NULL::text, p_repo_slug text DEFAULT NULL::text, p_repo_fingerprint text DEFAULT NULL::text, p_repo_scope_role text DEFAULT NULL::text, p_agent_role text DEFAULT NULL::text, p_expected_agent_handle text DEFAULT NULL::text)
+ RETURNS TABLE(onboarding_contract_version text, agent_id uuid, auth_user_id uuid, provider_id text, signing_key_id uuid, granted_scopes text[], key_id text, key_version integer, agent_handle text, public_key_fingerprint text, board_id uuid, membership_role text, membership_state text, machine_id uuid, harness_registration_id uuid, repo_scope_id uuid, fleet_machine_agent_id uuid, binding_signing_key_id uuid, harness_kind text, harness_label text, repo_slug text, repo_fingerprint text, repo_scope_role text, agent_role text, expected_agent_handle text, identity_disposition text, membership_disposition text, harness_disposition text, repo_scope_disposition text, binding_disposition text)
+ LANGUAGE plpgsql
+ SECURITY DEFINER
+ SET search_path TO 'agent_board', 'public'
+AS $function$
+#variable_conflict use_column
+declare
+  v_inv agent_board.board_invite_tokens%rowtype;
+  v_bounds agent_board.fleet_onboarding_invite_bounds%rowtype;
+  v_board agent_board.boards%rowtype;
+  v_machine agent_board.fleet_machines%rowtype;
+  v_domain agent_board.fleet_trust_domains%rowtype;
+  v_enroll record;
+  v_membership record;
+  v_harness agent_board.fleet_harness_registrations%rowtype;
+  v_repo agent_board.fleet_repo_scopes%rowtype;
+  v_binding agent_board.fleet_machine_agents%rowtype;
+  v_kind text := lower(btrim(coalesce(p_harness_kind, '')));
+  v_label text := btrim(coalesce(p_harness_label, ''));
+  v_repo_slug text := btrim(coalesce(p_repo_slug, ''));
+  v_repo_fingerprint text := btrim(coalesce(p_repo_fingerprint, ''));
+  v_expected_handle text := btrim(coalesce(p_expected_agent_handle, ''));
+  v_existing_agent_id uuid;
+  v_owner_user_id uuid;
+  v_identity_disposition text;
+  v_membership_disposition text;
+  v_harness_disposition text;
+  v_repo_disposition text;
+  v_binding_disposition text;
+  v_completed_replay boolean := false;
+begin
+  if not agent_board._is_service_role() then
+    raise exception 'service_role required for onboard_federated_fleet_agent' using errcode = '42501';
+  end if;
+  if nullif(btrim(coalesce(p_invite_code, '')), '') is null then
+    raise exception 'bounded invite code is required' using errcode = '22023';
+  end if;
+
+  select bit.* into v_inv
+    from agent_board.board_invite_tokens bit
+   where bit.code = btrim(p_invite_code)
+   for update;
+  if not found then
+    raise exception 'fleet onboarding invite is not usable' using errcode = '42501';
+  end if;
+  select * into v_bounds
+    from agent_board.fleet_onboarding_invite_bounds b
+   where b.invite_id = v_inv.id
+   for update;
+  if not found then
+    raise exception 'fleet onboarding requires a bounded invite' using errcode = '42501';
+  end if;
+
+  -- ADVISORY BEFORE BOARDS. set_board_authority_ceiling holds this lock and then
+  -- reaches this same boards row through board_authority_ceilings' FK (FOR KEY SHARE
+  -- on INSERT). Taking the boards lock first would invert the order against it and
+  -- deadlock -- it did, until this line was hoisted above the select below.
+  perform agent_board._lock_board_authority_ceiling(v_inv.board_id);
+
+  select * into v_board
+    from agent_board.boards b
+   where b.id = v_inv.board_id
+   for update;
+  if not found or v_board.status <> 'active' then
+    raise exception 'fleet onboarding board is not usable' using errcode = '42501';
+  end if;
+
+  if v_inv.board_id is distinct from p_board_id
+     or v_bounds.machine_id is distinct from p_machine_id
+     or v_bounds.harness_kind is distinct from v_kind
+     or v_bounds.harness_label is distinct from v_label
+     or v_bounds.repo_slug is distinct from v_repo_slug
+     or v_bounds.repo_fingerprint is distinct from v_repo_fingerprint
+     or v_bounds.repo_scope_role is distinct from p_repo_scope_role
+     or v_bounds.agent_role is distinct from p_agent_role
+     or v_bounds.expected_agent_handle is distinct from v_expected_handle then
+    raise exception 'fleet onboarding bounds mismatch' using errcode = '42501';
+  end if;
+  if not ((p_agent_role = 'phase_worker' and p_repo_scope_role = 'worker')
+          or (p_agent_role = 'reviewer' and p_repo_scope_role = 'reviewer')) then
+    raise exception 'fleet onboarding authority is elevated' using errcode = '42501';
+  end if;
+
+  select * into v_machine from agent_board.fleet_machines fm
+   where fm.id = p_machine_id for update;
+  if not found or v_machine.owner_agent_id <> v_inv.created_by_agent_id
+     or v_machine.lifecycle_state <> 'active' then
+    raise exception 'fleet onboarding machine is not usable' using errcode = '42501';
+  end if;
+  select * into v_domain from agent_board.fleet_trust_domains td
+   where td.id = v_machine.trust_domain_id for update;
+  if not found or v_domain.owner_agent_id <> v_inv.created_by_agent_id
+     or v_domain.lifecycle_state <> 'active' then
+    raise exception 'fleet onboarding trust domain is not usable' using errcode = '42501';
+  end if;
+
+  -- Serialize cross-route identity classification before locking principals. For
+  -- a replay, lock the creator and enrolled principal in UUID order so a human or
+  -- agent subtree revocation that visits the same pair cannot invert their order.
+  perform pg_advisory_xact_lock(hashtextextended(p_agent_public_key_fingerprint, 0));
+  select k.agent_id, a.owner_user_id into v_existing_agent_id, v_owner_user_id
+    from agent_board.agent_signing_keys k
+    join agent_board.agents a on a.id = k.agent_id
+   where k.fingerprint = p_agent_public_key_fingerprint;
+  v_owner_user_id := coalesce(v_owner_user_id, agent_board._ensure_agent_auth_user(
+    agent_board._federated_identity_slug(p_issuer, p_subject)
+  ));
+  perform 1 from auth.users u where u.id = v_owner_user_id for update;
+  if exists (
+    select 1 from agent_board.fleet_human_revocations r
+     where r.issuer = p_issuer and r.subject = p_subject
+  ) then
+    raise exception 'human owner has been revoked' using errcode = '42501';
+  end if;
+  perform 1 from agent_board.agents a
+   where a.id = any(array[v_inv.created_by_agent_id, v_existing_agent_id])
+   order by a.id for update;
+
+  -- Creator authority is part of the invite's live authorization, not merely a
+  -- snapshot from mint time. Lock every membership row and the current ceiling
+  -- before evaluating its role so revocation, eviction, or demotion must serialize
+  -- on one side of this transaction.
+  --
+  -- The ceiling ROW lock below covers demotion of an EXISTING ceiling only. No row
+  -- lock can cover the ABSENCE of a row, and absence is the normal default-owner
+  -- state, so a concurrent set_board_authority_ceiling inserting 'observer' used to
+  -- interleave: this transaction read "no ceiling", passed as owner, and committed a
+  -- 'member' membership after the ceiling committed. The board-keyed advisory lock
+  -- that serializes the ABSENCE is already held -- it is taken far above, BEFORE the
+  -- boards row lock, because the ceiling writer reaches boards through its FK and the
+  -- two must agree on order.
+  perform 1 from agent_board.board_memberships bm
+   where bm.board_id = v_inv.board_id
+     and bm.agent_id = v_inv.created_by_agent_id
+   order by bm.id for update;
+  perform 1 from agent_board.board_authority_ceilings c
+   where c.board_id = v_inv.board_id for update;
+
+  -- Concurrent legacy enrollment or onboarding on another machine has committed
+  -- before this snapshot decides whether the identity was created here.
+  if exists (select 1 from agent_board.agent_signing_keys k where k.fingerprint = p_agent_public_key_fingerprint) then
+    v_identity_disposition := 'reused';
+  else
+    v_identity_disposition := 'created';
+  end if;
+
+  select * into v_enroll from agent_board.enroll_federated_identity(
+    p_issuer, p_audience, p_subject, p_human_identity_claim, p_slug,
+    p_agent_public_key, p_agent_public_key_format, p_agent_public_key_fingerprint,
+    p_pop_verified, p_token_sha256, p_token_expires_at, p_actor_sub, p_agent_kind, p_requested_scopes,
+    p_requested_board_scopes, null
+  );
+  if v_enroll.agent_handle is distinct from v_expected_handle then
+    raise exception 'server-assigned handle does not match the authorized handle' using errcode = '23505';
+  end if;
+
+  -- A complete replay may bypass expiry/exhaustion only while its redemption and
+  -- active membership remain true through commit. Lock both ledgers before the
+  -- proof; the invite row already serializes first redemption for an absent row.
+  perform 1 from agent_board.board_invite_redemptions red
+   where red.invite_id = v_inv.id and red.agent_id = v_enroll.agent_id
+   order by red.id for update;
+  perform 1 from agent_board.board_memberships bm
+   where bm.board_id = v_inv.board_id and bm.agent_id = v_enroll.agent_id
+   order by bm.id for update;
+
+  -- The released ROOMLINK core deliberately returns an existing redemption before
+  -- checking current token authority.  Fleet onboarding has a narrower replay
+  -- contract: only an exact, fully active chain may ignore expiry/exhaustion.  A
+  -- partial chain must pass every current invite gate before any missing suffix is
+  -- written, and revocation/current creator authority always apply.
+  select exists (
+    select 1
+      from agent_board.board_invite_redemptions red
+      join agent_board.board_memberships mem on mem.id = red.membership_id
+      join agent_board.fleet_harness_registrations h
+        on h.machine_id = p_machine_id
+       and h.harness_kind = v_kind
+       and h.harness_label = v_label
+      join agent_board.fleet_repo_scopes repo
+        on repo.harness_registration_id = h.id
+       and repo.repo_slug = v_repo_slug
+       and repo.repo_fingerprint = v_repo_fingerprint
+       and repo.scope_role = p_repo_scope_role
+      join agent_board.fleet_machine_agents binding
+        on binding.machine_id = p_machine_id
+       and binding.agent_id = v_enroll.agent_id
+       and binding.repo_scope_id = repo.id
+       and binding.signing_key_id = v_enroll.signing_key_id
+       and binding.agent_role = p_agent_role
+      join agent_board.agents principal on principal.id = v_enroll.agent_id
+      join agent_board.agent_signing_keys signing_key on signing_key.id = v_enroll.signing_key_id
+     where red.invite_id = v_inv.id
+       and red.agent_id = v_enroll.agent_id
+       and mem.board_id = v_inv.board_id
+       and mem.agent_id = v_enroll.agent_id
+       and mem.role = 'member'
+       and mem.membership_state in ('joined', 'subscribed')
+       and h.lifecycle_state = 'active'
+       and repo.lifecycle_state = 'active'
+       and binding.lifecycle_state = 'active'
+       and principal.status = 'active'
+       and signing_key.status = 'active'
+       and signing_key.proof_state = 'proven'
+       and signing_key.revoked_at is null
+       and not exists (
+         select 1 from agent_board.fleet_revocation_events e
+          where (e.subject_kind = 'agent' and e.subject_id = v_enroll.agent_id)
+             or (e.subject_kind = 'signing_key' and e.subject_id = v_enroll.signing_key_id)
+             or (e.subject_kind = 'harness' and e.subject_id = h.id)
+             or (e.subject_kind = 'repo_scope' and e.subject_id = repo.id)
+       )
+  ) into v_completed_replay;
+
+  if v_inv.revoked_at is not null
+     or not exists (
+       select 1 from agent_board.agents a
+        where a.id = v_inv.created_by_agent_id and a.status = 'active'
+     )
+     or not agent_board._grant_within_ceiling(
+       v_inv.created_by_agent_id, v_inv.board_id, v_inv.preset_role
+     )
+     or (
+       exists (
+         select 1 from agent_board.board_memberships bm
+          where bm.board_id = v_inv.board_id
+            and bm.agent_id = v_enroll.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 = v_enroll.agent_id
+            and bm.membership_state in ('joined', 'subscribed')
+       )
+     ) then
+    raise exception 'fleet onboarding invite is not usable' using errcode = '42501';
+  end if;
+  if not v_completed_replay
+     and (
+       v_inv.expires_at <= now()
+       or (v_inv.max_uses is not null and v_inv.uses_count >= v_inv.max_uses)
+     ) then
+    raise exception 'fleet onboarding invite is not usable' using errcode = '42501';
+  end if;
+
+  if exists (
+    select 1 from agent_board.board_invite_redemptions r
+     where r.invite_id = v_inv.id and r.agent_id = v_enroll.agent_id
+  ) then v_membership_disposition := 'reused'; else v_membership_disposition := 'created'; end if;
+
+  select * into v_membership
+    from agent_board._redeem_fleet_invite_for_agent(btrim(p_invite_code), v_enroll.agent_id);
+  if v_membership.role <> 'member' or v_membership.membership_state not in ('joined', 'subscribed') then
+    raise exception 'fleet onboarding requires an active member membership' using errcode = '42501';
+  end if;
+
+  perform 1 from agent_board.fleet_harness_registrations h
+   where h.machine_id = p_machine_id and h.harness_kind = v_kind and h.harness_label = v_label
+   order by h.id for update;
+  if exists (
+    select 1 from agent_board.fleet_harness_registrations h
+     where h.machine_id = p_machine_id and h.harness_kind = v_kind and h.harness_label = v_label
+       and h.lifecycle_state <> 'active'
+  ) then
+    raise exception 'revoked harness registration cannot be replaced' using errcode = '42501';
+  end if;
+  select * into v_harness
+    from agent_board.fleet_harness_registrations h
+   where h.machine_id = p_machine_id and h.harness_kind = v_kind and h.harness_label = v_label
+     and h.lifecycle_state = 'active'
+   order by h.id;
+  if found then
+    v_harness_disposition := 'reused';
+  else
+    insert into agent_board.fleet_harness_registrations(machine_id, harness_kind, harness_label)
+      values (p_machine_id, v_kind, v_label) returning * into v_harness;
+    v_harness_disposition := case when v_identity_disposition = 'reused' then 'recovered' else 'created' end;
+  end if;
+
+  perform 1 from agent_board.fleet_repo_scopes r
+   where r.harness_registration_id = v_harness.id
+     and r.repo_fingerprint = v_repo_fingerprint and r.scope_role = p_repo_scope_role
+   order by r.id for update;
+  if exists (
+    select 1 from agent_board.fleet_repo_scopes r
+     where r.harness_registration_id = v_harness.id
+       and r.repo_fingerprint = v_repo_fingerprint and r.scope_role = p_repo_scope_role
+       and (r.lifecycle_state <> 'active' or r.repo_slug <> v_repo_slug)
+  ) then
+    raise exception 'conflicting or revoked repo scope cannot be replaced' using errcode = '42501';
+  end if;
+  select * into v_repo
+    from agent_board.fleet_repo_scopes r
+   where r.harness_registration_id = v_harness.id
+     and r.repo_fingerprint = v_repo_fingerprint and r.scope_role = p_repo_scope_role
+     and r.lifecycle_state = 'active' and r.repo_slug = v_repo_slug
+   order by r.id;
+  if found then
+    v_repo_disposition := 'reused';
+  else
+    insert into agent_board.fleet_repo_scopes(
+      harness_registration_id, repo_slug, repo_fingerprint, scope_role
+    ) values (v_harness.id, v_repo_slug, v_repo_fingerprint, p_repo_scope_role)
+      returning * into v_repo;
+    v_repo_disposition := case when v_identity_disposition = 'reused' then 'recovered' else 'created' end;
+  end if;
+
+  -- Machine -> agent/key/binding lock order.  Any tombstone for this natural key
+  -- blocks replacement authority even though the active unique index would allow it.
+  perform 1 from agent_board.agents a where a.id = v_enroll.agent_id for update;
+  perform 1 from agent_board.agent_signing_keys k where k.id = v_enroll.signing_key_id for update;
+  perform 1 from agent_board.fleet_machine_agents b
+   where b.machine_id = p_machine_id and b.agent_id = v_enroll.agent_id
+     and b.repo_scope_id = v_repo.id
+   order by b.id for update;
+  if exists (
+    select 1 from agent_board.fleet_machine_agents b
+     where b.machine_id = p_machine_id and b.agent_id = v_enroll.agent_id
+       and b.repo_scope_id = v_repo.id
+       and (
+         b.lifecycle_state <> 'active'
+         or b.signing_key_id is distinct from v_enroll.signing_key_id
+         or b.agent_role is distinct from p_agent_role
+       )
+  ) then
+    raise exception 'conflicting or revoked fleet binding cannot be replaced' using errcode = '42501';
+  end if;
+  select * into v_binding
+    from agent_board.fleet_machine_agents b
+   where b.machine_id = p_machine_id and b.agent_id = v_enroll.agent_id
+     and b.repo_scope_id = v_repo.id and b.lifecycle_state = 'active'
+     and b.signing_key_id = v_enroll.signing_key_id and b.agent_role = p_agent_role
+   order by b.id;
+  if found then
+    v_binding_disposition := 'reused';
+  else
+    insert into agent_board.fleet_machine_agents(
+      machine_id, agent_id, repo_scope_id, signing_key_id, agent_role
+    ) values (
+      p_machine_id, v_enroll.agent_id, v_repo.id, v_enroll.signing_key_id, p_agent_role
+    ) returning * into v_binding;
+    v_binding_disposition := case when v_identity_disposition = 'reused' then 'recovered' else 'created' end;
+  end if;
+
+  if exists (
+    select 1 from agent_board.fleet_revocation_events e
+     where (e.subject_kind = 'agent' and e.subject_id = v_enroll.agent_id)
+        or (e.subject_kind = 'signing_key' and e.subject_id = v_enroll.signing_key_id)
+        or (e.subject_kind = 'harness' and e.subject_id = v_harness.id)
+        or (e.subject_kind = 'repo_scope' and e.subject_id = v_repo.id)
+  ) then
+    raise exception 'fleet onboarding authority has effective revocation evidence' using errcode = '42501';
+  end if;
+
+  return query select
+    'fleet_onboarding.v1'::text, v_enroll.agent_id, v_enroll.auth_user_id,
+    v_enroll.provider_id, v_enroll.signing_key_id, v_enroll.granted_scopes,
+    v_enroll.key_id, v_enroll.key_version, v_enroll.agent_handle,
+    p_agent_public_key_fingerprint, v_membership.board_id, v_membership.role,
+    v_membership.membership_state, p_machine_id, v_harness.id, v_repo.id,
+    v_binding.id, v_binding.signing_key_id, v_kind, v_label, v_repo_slug, v_repo_fingerprint,
+    p_repo_scope_role, p_agent_role, v_expected_handle,
+    v_identity_disposition, v_membership_disposition, v_harness_disposition,
+    v_repo_disposition, v_binding_disposition;
+end;
+$function$;
+
+revoke all on function agent_board.enroll_federated_identity(text, text, text, jsonb, text, text, text, text, boolean, text, timestamptz, text, text, text[], text[], text) from public, anon, authenticated;
+grant execute on function agent_board.enroll_federated_identity(text, text, text, jsonb, text, text, text, text, boolean, text, timestamptz, text, text, text[], text[], text) to service_role;
+comment on function agent_board.enroll_federated_identity(text, text, text, jsonb, text, text, text, text, boolean, text, timestamptz, text, text, text[], text[], text) is
+  'Service-role federated enrollment with exact fingerprint replay AND owner-scoped resumption (#176). An already-enrolled key re-presented by the principal that OWNS it RESUMES: the existing agent identity is returned so a client whose post-enroll provisioning failed can finish, rather than being refused forever. Ownership is decided against evidence written at the ORIGINAL enrollment: the creation-time federation stamp (issuer/subject/providerId) and the enrollment_federation_audit row are both REQUIRED, and agents.owner_user_id must equal the auth user derived from sha256(issuer|subject) whenever that column is populated (a null owner_user_id predates the owner model and is the one exemption; such a row still resumes only for the principal the stamp and audit row name). The caller''s (issuer, subject) is trusted only because it is equality-gated against the verified claim projection above; the conjunction is coalesced to false so unproven ownership is not-owned. A key held by a DIFFERENT principal still raises 23505 and the message names no handle. Stable owner, actor, slug, kind, and scope inputs stay frozen for a STAMPED enrollment (unchanged check, message now names the handle); an enrollment predating the stamp has no frozen contract and resumes on the ownership evidence alone, returning its ORIGINAL granted_scopes. Rotating presentation claims are revalidated upstream but are not equality-gated. Fleet-bounded codes are rejected before writes. Takes the invite row and its board (invite -> board) BEFORE the auth.users owner lock so every federated write route agrees on board -> owner (#194); the resumption additions are read-only and acquire no lock. A serialization failure or deadlock during redemption propagates instead of being reported as invite_redeemed=false. #521: p_token_sha256 (lowercase hex sha256 of the verified Portal token''s RS256 signing input) and p_token_expires_at (its verified exp) are REQUIRED and have no default; immediately after the owner lock and the revocation gate, and before the found/not-found split, _enroll_token_bind binds the token to this key''s fingerprint, so a token enrolls or resumes AT MOST ONE key. A different key under a used token raises SQLSTATE MBT01 and nothing is created; the same key falls through into the unchanged resumption gates. This is the ONLY call site of _enroll_token_bind and the only caller of _enroll_federated_identity_once.';
+
+revoke all on function agent_board.onboard_federated_fleet_agent(text, text, text, jsonb, text, text, text, text, boolean, text, timestamptz, text, text, text[], text[], text, uuid, uuid, text, text, text, text, text, text, text) from public, anon, authenticated;
+grant execute on function agent_board.onboard_federated_fleet_agent(text, text, text, jsonb, text, text, text, text, boolean, text, timestamptz, text, text, text[], text[], text, uuid, uuid, text, text, text, text, text, text, text) to service_role;
+comment on function agent_board.onboard_federated_fleet_agent(text, text, text, jsonb, text, text, text, text, boolean, text, timestamptz, text, text, text[], text[], text, uuid, uuid, text, text, text, text, text, text, text) is
+  'Service-role-only atomic fleet onboarding. Locks invite, machine, domain, principal, key, and binding in canonical order; takes the board-keyed _lock_board_authority_ceiling advisory lock so the ceiling''s ABSENCE serializes against a concurrent set_board_authority_ceiling before creator authority is evaluated; validates immutable creator bounds; enrolls/replays identity; redeems member ROOMLINK; and creates/reuses the exact harness, repo, and key-bound machine-agent chain in one transaction. #521: p_token_sha256 and p_token_expires_at are REQUIRED (no default) and are only forwarded to the nested enroll_federated_identity call, which binds the token to the key after this function''s owner lock; a used token presented with a different key raises MBT01 there and the whole onboarding rolls back.';
+
+-- _enroll_federated_identity_once: signature and body unchanged. Its only caller is the
+-- postgres-owned definer above, so the service_role grant was a bypass of the token bind
+-- and nothing else.
+revoke execute on function agent_board._enroll_federated_identity_once(text, text, text, jsonb, text, text, text, text, boolean, text, text, text[], text[], text) from service_role;
+comment on function agent_board._enroll_federated_identity_once(text, text, text, jsonb, text, text, text, text, boolean, text, text, text[], text[], text) is
+  'Internal one-time federated-identity creator (the released 20260724000200/20260822000100 implementation, renamed by 20260901000100). Call only through enroll_federated_identity, which holds the invite/board and owner locks. Takes the invite row and its board BEFORE the owner is provisioned so the board -> owner order holds even on a direct service_role call (#194); the optional trailing p_invite_code is still soft-honored via _redeem_invite_for_agent in a BEGIN/EXCEPTION subtransaction (bad code -> enrollment still succeeds, invite_redeemed=false), EXCEPT for SQLSTATE class 40, which propagates rather than being reported as a non-redemption. CREATES ONLY: step (6) still refuses an already-enrolled fingerprint unconditionally and does NOT resume (#176) -- resumption has exactly one implementation and it lives in enroll_federated_identity, which is this function''s only caller and which gates the (issuer, subject) against the verified claim projection first. The step (6) raise names the agent that already holds the key and says enrollment need not be repeated. #521: not EXECUTE-able by service_role (or any API role). The Portal-token binding lives in its only caller, enroll_federated_identity, and a direct service_role call would have been an unguarded creation path, since service_role holds no direct INSERT on agent_signing_keys or agents.';