@consiliency/agent-board-schema 1.12.0 → 1.23.0

package/migrations/20260903000100_agent_board_enroll_identity_board_owner_lock_order.sql

@@ -0,0 +1,604 @@
+-- Consiliency/message-board#194 -- enroll_federated_identity took the human owner
+-- BEFORE the board, inverting the canonical order the other two federated write
+-- routes already use, and then SWALLOWED the resulting serialization failure.
+--
+-- THE CYCLE (reproduced on a private database, real `deadlock detected` output):
+--   enroll_federated_identity  auth.users FOR UPDATE  ->  boards FOR KEY SHARE
+--                              (:504)                     (via board_memberships_board_id_fkey,
+--                                                          inside the invite redemption)
+--   enroll_federated_human     boards FOR UPDATE      ->  auth.users FOR UPDATE
+--   onboard_federated_fleet_agent
+--                              boards FOR UPDATE      ->  auth.users FOR UPDATE
+-- Two of three routes already took board -> owner, so board -> owner is canonical
+-- and this migration moves the third onto it rather than moving the other two.
+--
+-- WHY NO TEXTUAL CHECK FOUND IT: enroll_federated_identity never names `boards`.
+-- Its boards lock arrives through an FK on a table it inserts into via a callee.
+-- The class assertion added with this migration
+-- (agent_board_federated_lock_order_class.test.sql) is therefore derived from
+-- pg_constraint FK edges plus the pg_proc call graph, not from prosrc text: it
+-- enumerates every agent_board function that acquires BOTH a boards row lock and
+-- an auth.users row lock -- through an explicit lock OR through an INSERT into a
+-- direct FK child of either table -- and requires the board acquisition first.
+-- Against the pre-fix schema it flags exactly the two functions this migration
+-- changes, and names them.
+--
+-- THE MASKING, which is the more serious half. The redemption sub-block caught
+-- `others` and set invite_redeemed := false. That catches 40P01/40001, so under
+-- contention the RPC returned SUCCESS with no board membership and no error to
+-- the client (measured: uncontended invite_redeemed=t + membership row; under the
+-- cycle invite_redeemed=f + none). Class 40 is now re-raised at BOTH sites -- the
+-- wrapper's replay branch and _enroll_federated_identity_once step (13) -- while
+-- every deterministic failure (bad/expired/exhausted/unauthorized code) keeps the
+-- released soft-honor behaviour.
+--
+-- Both functions are recreated with CREATE OR REPLACE (ACL and COMMENT survive);
+-- the grants and comments are restated below regardless, per the repo rule.
+-- The bodies are otherwise byte-identical to their released sources
+-- (20260901000100 for the wrapper, 20260822000100 for the renamed core).
+--
+-- WHY THE HOISTED LOCK IS *FOR KEY SHARE*. It stands in for an acquisition the
+-- redemption makes through board_memberships_board_id_fkey, and that acquisition IS
+-- FOR KEY SHARE. Taking the same mode early establishes the identical ordering
+-- point -- KEY SHARE conflicts with the FOR UPDATE that enroll_federated_human and
+-- onboard_federated_fleet_agent take on a boards row, which is the conflict the
+-- ordering needs -- without serializing two concurrent enrollments that merely share
+-- a board. A FOR UPDATE here (the first cut) would have been strictly stronger than
+-- the thing it replaces and would have blocked every concurrent membership write on
+-- that board for the length of an enrollment: throughput, not correctness, but not
+-- a cost this migration needs to impose.
+--
+-- TWO ADVISORY-LOCK EDGES THIS ROUTE NOW HAS, recorded so the next person to move a
+-- lock does not have to rediscover them:
+--   * pg_advisory_xact_lock(hashtextextended(<key fingerprint>, 0)) is taken by BOTH
+--     enroll_federated_identity (below) and onboard_federated_fleet_agent
+--     (20260901000110:332). After this migration enroll runs boards -> fp-advisory,
+--     and onboard runs boards -> ... -> fp-advisory: SAME direction, so the pair
+--     holds. It holds because onboard takes its boards lock first for its own
+--     reasons, not because anything enforced it -- moving either acquisition across
+--     the other reopens a cycle.
+--   * This route does NOT take _lock_board_authority_ceiling. It never acquires that
+--     advisory lock at all, so taking boards without it cannot form the
+--     advisory<->boards cycle 20260901000110's header describes; only
+--     onboard_federated_fleet_agent and set_board_authority_ceiling participate in
+--     that lock (enumerated from pg_proc).
+
+-- 1. the internal one-time creator (renamed core).
+create or replace function agent_board._enroll_federated_identity_once(
+  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_actor_sub text default null,
+  p_agent_kind text default 'agent',
+  p_requested_scopes text[] default '{}',
+  p_requested_board_scopes text[] default '{}',
+  p_invite_code text default null
+)
+returns table(
+  agent_id uuid,
+  auth_user_id uuid,
+  provider_id text,
+  signing_key_id uuid,
+  granted_scopes text[],
+  key_id text,
+  key_version int,
+  agent_handle text,
+  invite_redeemed boolean
+)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_slug text;
+  v_kind text;
+  v_provider agent_board.identity_providers%rowtype;
+  v_owner_user_id uuid;
+  v_auth_user_id uuid;
+  v_agent_handle text;
+  v_agent_id uuid;
+  v_signing_key_id uuid;
+  v_fingerprint text;
+  v_key_hex text;
+  v_raw_key bytea;
+  v_reencoded text;
+  v_key_id text := 'portal-enroll';
+  v_key_version int := 1;
+  v_requested_scopes text[] := coalesce(p_requested_scopes, '{}');
+  v_requested_board_scopes text[] := coalesce(p_requested_board_scopes, '{}');
+  v_invite_code text := nullif(trim(coalesce(p_invite_code, '')), '');
+  v_invite_redeemed boolean := false;
+  v_invite_board_id uuid;
+begin
+  -- service_role-only (defense in depth on top of the execute-grant revocation).
+  if not agent_board._is_service_role() then
+    raise exception 'service_role required for enroll_federated_identity' using errcode = '42501';
+  end if;
+
+  -- A verified subject + human identity claim are always present from the EF.
+  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;
+
+  -- (0) PoP gate — the EF Ed25519-verified the proof-of-possession over the token
+  -- bytes and passes true. Refuse false BEFORE any write (no agent/key/audit row).
+  if p_pop_verified is not true then
+    raise exception 'proof-of-possession was not verified; enrollment refused'
+      using errcode = '42501';
+  end if;
+
+  -- (1) Public-key shape gate. The enroll contract is raw Ed25519 (32 bytes -> 43
+  -- base64url chars).
+  if p_agent_public_key_format is distinct from 'raw_ed25519_base64url' then
+    raise exception 'agent public key format must be raw_ed25519_base64url' using errcode = '22023';
+  end if;
+  if p_agent_public_key is null or p_agent_public_key !~ '^[A-Za-z0-9_-]{43}$' then
+    raise exception 'malformed agent public key: expected a 43-char base64url raw Ed25519 key'
+      using errcode = '22023';
+  end if;
+
+  -- (1a) B2 — decode base64url -> raw 32 bytes and REJECT any non-canonical encoding.
+  v_raw_key := decode(translate(p_agent_public_key, '-_', '+/') || '=', 'base64');
+  if octet_length(v_raw_key) <> 32 then
+    raise exception 'agent public key must decode to exactly 32 raw Ed25519 bytes'
+      using errcode = '22023';
+  end if;
+  v_reencoded := rtrim(translate(encode(v_raw_key, 'base64'), '+/', '-_'), '=');
+  if v_reencoded is distinct from p_agent_public_key then
+    raise exception 'agent public key is not canonical base64url (aliased encoding rejected)'
+      using errcode = '22023';
+  end if;
+
+  -- (1b) Reject the all-zero small-order placeholder over the RAW bytes.
+  if v_raw_key = decode(repeat('00', 32), 'hex') then
+    raise exception 'agent public key is the all-zero small-order placeholder and is rejected'
+      using errcode = '22023';
+  end if;
+
+  -- (2) Recompute-and-assert the fingerprint in-DB over the RAW 32 bytes. Derived through
+  -- the shared _raw_key_fingerprint helper (single source of truth; catalog-sweep-pinned).
+  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 (recompute != supplied)'
+      using errcode = '22023';
+  end if;
+
+  -- (3) act.sub is audit-only, but when present it must be a real value.
+  if p_actor_sub is not null and length(trim(p_actor_sub)) = 0 then
+    raise exception 'actor sub, when present, must be non-empty' using errcode = '22023';
+  end if;
+
+  v_slug := agent_board._normalize_provision_slug(p_slug);
+  v_kind := lower(coalesce(trim(p_agent_kind), ''));
+
+  -- (4) allowlist lookup by (issuer, audience); must exist + supported + policy-approved.
+  select *
+    into v_provider
+    from agent_board.identity_providers
+   where issuer = p_issuer
+     and 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;
+  if not v_provider.supported then
+    raise exception 'identity provider is not supported' using errcode = '42501';
+  end if;
+  if not v_provider.policy_approved then
+    raise exception 'identity provider is not policy-approved' using errcode = '42501';
+  end if;
+
+  -- (5) scope-ceiling + kind gate. 'system' is never federatable.
+  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', v_kind using errcode = '42501';
+  end if;
+  if not (v_requested_scopes <@ v_provider.allowed_scopes) then
+    raise exception 'requested scopes exceed the provider allowed_scopes ceiling' using errcode = '42501';
+  end if;
+  if not (v_requested_board_scopes <@ v_provider.allowed_board_scopes) then
+    raise exception 'requested board scopes exceed the provider allowed_board_scopes ceiling' using errcode = '42501';
+  end if;
+
+  -- (6) dedup on the enrolled key: a fingerprint already enrolled cannot be re-bound.
+  if exists (select 1 from agent_board.agent_signing_keys k where k.fingerprint = v_fingerprint) then
+    raise exception 'this signing key is already enrolled (duplicate fingerprint)'
+      using errcode = '23505';
+  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 v_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 = v_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;
+
+  -- (7) HUMAN OWNER — established idempotently per (issuer, sub).
+  v_owner_user_id := agent_board._ensure_agent_auth_user(
+    'fed-human-' || substr(encode(extensions.digest(convert_to(p_issuer || '|' || p_subject, 'UTF8'), 'sha256'), 'hex'), 1, 32));
+
+  -- (8) AGENT handle — unique per enrolled key.
+  v_key_hex := encode(extensions.digest(v_raw_key, 'sha256'), 'hex');
+  v_agent_handle := v_slug;
+  if exists (select 1 from agent_board.agents a where a.handle = v_agent_handle) then
+    v_agent_handle := v_slug || '-' || substr(v_key_hex, 1, 12);
+  end if;
+
+  -- (9) the agent's OWN board principal (session-usable via its enrolled key).
+  v_auth_user_id := agent_board._ensure_agent_auth_user(v_agent_handle);
+
+  -- (10) create the SEPARATE agent row (never keyed on sub; owner = the human).
+  insert into agent_board.agents(
+    agent_type,
+    kind,
+    handle,
+    display_name,
+    status,
+    auth_user_id,
+    owner_user_id,
+    metadata
+  )
+  values (
+    v_kind,
+    v_kind::agent_board.agent_kind,
+    v_agent_handle,
+    agent_board._default_provision_display_name(v_agent_handle),
+    'active',
+    v_auth_user_id,
+    v_owner_user_id,
+    jsonb_build_object(
+      'federation', jsonb_build_object(
+        'issuer', p_issuer,
+        'audience', p_audience,
+        'subject', p_subject,
+        'actorSub', p_actor_sub,
+        'providerId', v_provider.id,
+        'signingKeyFingerprint', v_fingerprint,
+        'requestedScopes', to_jsonb(v_requested_scopes),
+        'requestedBoardScopes', to_jsonb(v_requested_board_scopes),
+        'popVerified', true,
+        'enrolledAt', now()
+      )
+    )
+  )
+  returning id into v_agent_id;
+
+  -- (11) enroll the public key as active + proven (satisfies active_requires_proof).
+  insert into agent_board.agent_signing_keys(
+    id, agent_id, key_id, key_version, public_key, public_key_format, fingerprint,
+    status, proof_state, metadata
+  )
+  values (
+    gen_random_uuid(), v_agent_id, v_key_id, v_key_version, p_agent_public_key,
+    p_agent_public_key_format, v_fingerprint,
+    'active', 'proven',
+    jsonb_build_object('enrolledVia', 'federated_identity', 'popVerified', true)
+  )
+  returning id into v_signing_key_id;
+
+  -- (12) one static claim-snapshot audit row (the verified claim contains act.sub).
+  insert into agent_board.enrollment_federation_audit(
+    issuer, audience, subject, human_identity_claim, provider_id,
+    agent_id, auth_user_id, requested_scopes, granted_scopes
+  )
+  values (
+    p_issuer, p_audience, p_subject, p_human_identity_claim, v_provider.id,
+    v_agent_id, v_auth_user_id, v_requested_scopes, v_requested_scopes
+  );
+
+  -- (13) ROOMLINK soft-honor: if a code is present, redeem it into a bounded board
+  -- membership for the freshly-created agent. Wrapped in a subtransaction so a
+  -- bad/expired/exhausted/unauthorized code rolls back ONLY this sub-block — the
+  -- agent-create above persists and enrollment still succeeds (invite_redeemed=false).
+  if v_invite_code is not null then
+    begin
+      perform agent_board._redeem_invite_for_agent(v_invite_code, v_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;
+
+  -- Server-authoritative identity: the client mints /session with the RETURNED
+  -- key_id/key_version/agent_handle (its private key stays in the keystore).
+  return query
+  select v_agent_id, v_auth_user_id, v_provider.id, v_signing_key_id, v_requested_scopes,
+         v_key_id, v_key_version, v_agent_handle, v_invite_redeemed;
+end;
+$$;
+
+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.';
+revoke all on function agent_board._enroll_federated_identity_once(
+  text, text, text, jsonb, text, text, text, text, boolean, text, text, text[], text[], text)
+  from public, anon, authenticated;
+grant execute on function agent_board._enroll_federated_identity_once(
+  text, text, text, jsonb, text, text, text, text, boolean, text, text, text[], text[], text)
+  to service_role;
+
+-- 2. the replay wrapper -- the route the Portal /enroll endpoint calls.
+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_actor_sub text default null,
+  p_agent_kind text default 'agent',
+  p_requested_scopes text[] default '{}',
+  p_requested_board_scopes text[] default '{}',
+  p_invite_code text default null
+)
+returns table(
+  agent_id uuid,
+  auth_user_id uuid,
+  provider_id text,
+  signing_key_id uuid,
+  granted_scopes text[],
+  key_id text,
+  key_version int,
+  agent_handle text,
+  invite_redeemed boolean
+)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+#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;
+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(
+    'fed-human-' || substr(encode(extensions.digest(convert_to(p_issuer || '|' || p_subject, 'UTF8'), 'sha256'), 'hex'), 1, 32)
+  ));
+  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;
+
+  select a.id as agent_id, a.auth_user_id, a.handle, a.agent_type, a.status,
+         a.metadata, 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}';
+    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
+       or v_replay is null
+       or 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 'enrollment replay conflicts with the frozen identity contract' 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;
+
+    return query select v_existing.agent_id, v_existing.auth_user_id,
+      v_replay ->> '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;
+$$;
+
+comment on function agent_board.enroll_federated_identity(text, text, text, jsonb, text, text, text, text, boolean, text, text, text[], text[], text) is
+  'Service-role federated enrollment with exact fingerprint replay. Stable owner, actor, slug, kind, and scope inputs are frozen; 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); a serialization failure or deadlock during redemption propagates instead of being reported as invite_redeemed=false.';
+revoke all on function agent_board.enroll_federated_identity(text, text, text, jsonb, text, text, text, text, boolean, 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, text, text[], text[], text) to service_role;