@consiliency/agent-board-schema 1.27.0 → 1.35.0

package/migrations/20260916000100_agent_board_federated_identity_injective_slug.sql

@@ -0,0 +1,1646 @@
+-- Consiliency/message-board#246 (change 2 of 3): the federated identity is derived
+-- through ONE injective serialization, and the ambiguous one is gone.
+--
+-- WHAT WAS WRONG. Every federated site derived the owner slug as
+--
+--   'fed-human-' || substr(encode(digest(convert_to(p_issuer || '|' || p_subject,
+--                                        'UTF8'), 'sha256'), 'hex'), 1, 32)
+--
+-- A single-character separator with no length prefix and no escaping is NOT an
+-- injective serialization: the delimiter can also occur inside either component, so
+-- the concatenation does not determine the pair. Concretely, and measured on this
+-- schema rather than asserted:
+--
+--   issuer='https://idp.example'       subject='user|123'  -> fed-human-7abc9cea64fb2629f7780b96c4570573
+--   issuer='https://idp.example|user'  subject='123'       -> fed-human-7abc9cea64fb2629f7780b96c4570573
+--
+-- Two distinct principals, one slug. And the slug is not a label: it is fed to
+-- _ensure_agent_auth_user, which turns it into 'agent+<slug>@agent-board.local' and
+-- finds-or-creates the auth.users row. The ambiguous value IS the account key.
+--
+-- WHAT IS INJECTIVE ABOUT THE REPLACEMENT. The new serialization is the netstring
+-- form
+--
+--   length(issuer) || ':' || issuer || ':' || length(subject) || ':' || subject
+--
+-- and its injectivity is a decoding argument, not a "looks different" argument:
+-- reading left to right, the digits before the first ':' are a decimal count n1 (the
+-- delimiter is unambiguous because a decimal count contains no ':'); consume exactly
+-- the next n1 characters -- whatever they contain, including ':' or '|' -- and that
+-- IS the issuer; require a ':'; repeat for the subject; require end of string. Every
+-- serialized string therefore has exactly one preimage pair, so distinct pairs
+-- produce distinct serializations, and convert_to(..., 'UTF8') is itself injective on
+-- text. Under the old form no such decoder exists, which is the whole defect.
+--
+-- The 32-hex truncation is UNCHANGED and is a different property. Truncating SHA-256
+-- to 128 bits bounds collisions at ~2^64 birthday work -- not constructible. The
+-- defect being fixed here was constructible with a text editor. Widening the digest
+-- would have moved every slug for a second, unrelated reason; it is deliberately not
+-- bundled in.
+--
+-- ONE HELPER, NOT SIX COPIES. agent_board._federated_identity_slug(issuer, subject)
+-- is the only place the serialization exists. Catalog-derived, at the vintage this
+-- migration was written (2026-08-16), the live derivation sites were:
+--
+--   mqccjfqngptkemnchlko (canonical/prod, older bundle): 2 functions, 2 occurrences
+--     enroll_federated_human, enroll_federated_identity
+--   bxrbtugitzwgazmoslrx (Portal) and repo HEAD:         5 functions, 6 occurrences
+--     enroll_federated_human, _enroll_federated_human_after_revocation_gate,
+--     enroll_federated_identity (x2), _enroll_federated_identity_once,
+--     onboard_federated_fleet_agent
+--
+-- The two lists differ because 20260903000100 / 20260906000100 / 20260915000100
+-- restructured the call chain after prod's bundle was cut. Nobody hand-ports: prod
+-- adopts the bundle IN ORDER, so it is already at the 5-function shape by the time
+-- this migration applies. All 5 are rebuilt below from their catalog definitions
+-- (pg_get_functiondef on a full replay), not from the migration files that first
+-- introduced them -- the file that introduced a derivation is usually not the file
+-- holding the live one.
+--
+-- THE HELPER RAISES ON A NULL OR EMPTY COMPONENT. These are two different cases and an
+-- earlier version of this comment ran them together; separating them, because one of them
+-- IS a behaviour change to a path that previously succeeded.
+--
+-- NULL is the harmless half. 'fed-human-' || NULL is NULL, _ensure_agent_auth_user(NULL)
+-- builds 'agent+@agent-board.local', and every null-issuer caller converges on ONE
+-- degenerate shared owner. Four of the five sites gate on identity_providers (which a NULL
+-- issuer can never match) before deriving, so the raise is unreachable for them;
+-- onboard_federated_fleet_agent derives BEFORE any issuer check, so there it fires earlier
+-- than the delegate's own 22023 null-subject refusal. Nothing that succeeded stops
+-- succeeding.
+--
+-- EMPTY STRING IS NOT THAT, and this migration DOES change it. The identity path's guard
+-- is `if p_subject is null then raise` (enroll_federated_identity, live catalog) -- `is
+-- null`, not `= ''`. So an allowlisted issuer presenting subject = '' passed every gate,
+-- and under the old encoding derived issuer || '|' || '' -- an ISSUER-SPECIFIC slug, not
+-- the degenerate shared one: two different issuers with an empty subject derived two
+-- different owners. That was a genuine success and it now raises 22023. It is judged the
+-- right refusal -- an empty subject identifies no principal, and an owner keyed on the
+-- issuer alone is a whole-issuer account rather than a person's -- but it is a REFUSAL OF
+-- SOMETHING THAT WORKED, not a no-op, and any adopter with such a row must be told rather
+-- than discover it. Measured on the canonical project 2026-08-16: 0 agents reachable from
+-- a fed-human owner carry an empty subject, so the live population is unaffected.
+--
+-- The backfill inherits the same distinction, and imperfectly: its recovery filter below
+-- requires the stamp fields to be `is not null`, not non-empty, so a PRE-EXISTING
+-- subject = '' stamp is accepted as a candidate and then raises inside the helper at the
+-- v_new := line -- a correct refusal reached by an awkward route, because that raise
+-- carries the helper's generic message and not the loop's uid-naming one. The population
+-- for this is 0 on both projects; it is recorded rather than fixed because tightening the
+-- filter is a behavioural change to a body four review seats have already cleared, and it
+-- belongs in its own change with its own mutation.
+--
+-- NO DUAL DERIVATION, DELIBERATELY. There is no legacy arm, no fallback lookup, and
+-- no legacy decoder left in the catalog. A permanent compatibility path would preserve
+-- exactly the ambiguity this change exists to remove -- a caller who can still be
+-- resolved by the old encoding is still a caller whose pair is unrecoverable. The old
+-- expression appears exactly once more in this file, inside the backfill's DO block,
+-- as the PROOF that each row being re-keyed is the row its recovered pair derives to.
+-- That text is not a function; nothing in pg_proc retains it, which the pgTAP class
+-- assertion checks catalog-side rather than by reading this file.
+--
+-- THE BACKFILL IS THE POINT, NOT A TIDY-UP. Changing the derivation without moving
+-- auth.users.email ORPHANS the existing owner: the email still encodes the old slug,
+-- so enroll_federated_identity's #244 resumption lookup (a pure lookup on
+-- 'agent+<slug>@agent-board.local') misses, v_derived_owner_user_id comes back null,
+-- the non-null owner_user_id conjunct fails, and the owner cannot resume. That reads
+-- like a cosmetic relabel and is a break. Four surfaces carry the slug and all four
+-- move together: auth.users.email, auth.users.raw_user_meta_data->>'slug',
+-- auth.identities (provider_id and identity_data->>'sub'/'slug'), and
+-- agent_board.agents.handle where the handle IS the slug (the human path's own agent
+-- row; agents enrolled on the identity/fleet paths carry their own handles and only
+-- reference the owner by uuid).
+--
+-- THE OWNER UUID NEVER CHANGES. The backfill rewrites the email that keys the lookup,
+-- not the auth.users.id it resolves to. Every agents.owner_user_id, every
+-- agents.auth_user_id, every issued session and every foreign key still points at the
+-- same uuid. This is a re-key of the lookup value, not a re-mint of the principal.
+--
+-- POPULATION, RE-MEASURED READ-ONLY ON 2026-08-16 (management API, no writes):
+--   mqccjfqngptkemnchlko : 1 auth.users row matching agent+fed-human-%@agent-board.local
+--                          uid bdd9671f-df9e-4ee5-8115-2a22b7daa441
+--                          slug 77213f39... -> 4fa7e7ad... under the new serialization
+--                          1 agent on that auth_user_id, 6 agents owned by it,
+--                          5 signing keys, 5 board memberships, ONE distinct
+--                          (issuer, subject) pair across all six stamps, and that pair
+--                          re-derives 77213f39... under the OLD encoding exactly.
+--   bxrbtugitzwgazmoslrx : 0 rows. Portal's side of this change is code-only.
+-- The count is taken on the OWNER UID, not on agents.handle: the resumption path
+-- selects on auth_user_id, so a handle-keyed count is the wrong denominator.
+-- The raw (issuer, subject) is a real person's identity and is deliberately NOT
+-- recorded here; the slugs above are one-way digests of it.
+--
+-- THIS MIGRATION MUST BE APPLIED INSIDE A TRANSACTION, and the fail-closed argument below
+-- is only true if it is. Every raise in the backfill assumes that aborting rolls the WHOLE
+-- file back. Applied statement-at-a-time -- which is what `psql -v ON_ERROR_STOP=1 -f`
+-- does, autocommit per statement, and it is how this repo's own replay harness runs
+-- (scripts/run-agent-board-schema-tests.sh) -- an abort in the backfill leaves the six
+-- CREATE OR REPLACE statements COMMITTED and every auth.users.email unmoved. That is
+-- exactly the orphaned-owner state the TRAP paragraph above exists to prevent, reached by
+-- the guard that was supposed to prevent it; and an enrollment of the same pair during
+-- that window would mint a SECOND owner under the new email and then permanently trip the
+-- collision guard on any retry. Supabase's migration runner wraps each file in a
+-- transaction, which is why the replay is safe in practice -- but an operator applying
+-- this file by hand must wrap it (BEGIN; \i <file>; COMMIT;) or run it through a runner
+-- that does. This precondition is load-bearing and was previously unwritten.
+--
+-- FAIL CLOSED ON A ROW IT CANNOT PROVE. For each affected auth.users row the backfill
+-- recovers the pair from the federation stamps of the agents that reference it (by
+-- auth_user_id -- the human path -- or by owner_user_id -- the identity/fleet paths),
+-- KEEPING ONLY pairs whose OLD derivation reproduces that row's current slug, and
+-- requires exactly one DISTINCT such pair. Zero (no stamp, or no stamp that
+-- reproduces) or more than one (a genuine collision) raises and aborts the migration
+-- rather than guessing, because guessing here silently binds an account to the wrong
+-- human. DISTINCT is load-bearing and is not count(*): production's row has six agents
+-- carrying the same pair, and a count of rows would refuse it.
+
+create or replace function agent_board._federated_identity_slug(
+  p_issuer text,
+  p_subject text
+)
+returns text
+language plpgsql
+immutable
+set search_path = ''
+as $fn$
+begin
+  -- Fail closed rather than derive a degenerate shared slug from a missing component.
+  if p_issuer is null or p_issuer = '' or p_subject is null or p_subject = '' then
+    raise exception 'federated identity slug requires a non-empty issuer and subject'
+      using errcode = '22023';
+  end if;
+
+  -- Netstring serialization: <len>:<value>:<len>:<value>. Injective -- see the header.
+  -- The components are hashed VERBATIM; no trimming or case folding, because any
+  -- normalization here would silently move an existing identity.
+  return 'fed-human-' || substr(
+    encode(
+      extensions.digest(
+        convert_to(
+          length(p_issuer)::text  || ':' || p_issuer || ':' ||
+          length(p_subject)::text || ':' || p_subject,
+          'UTF8'),
+        'sha256'),
+      'hex'),
+    1, 32);
+end;
+$fn$;
+
+comment on function agent_board._federated_identity_slug(text, text) is
+  'message-board#246: the ONE injective (issuer, subject) -> fed-human-<32hex> serialization. Netstring length-prefixed, so the pair is recoverable from the preimage and distinct pairs cannot share a slug. Every federated derivation site calls this; the expression exists nowhere else. Raises 22023 on a null/empty component rather than deriving a shared degenerate slug.';
+
+revoke all on function agent_board._federated_identity_slug(text, text) from public;
+grant execute on function agent_board._federated_identity_slug(text, text) to service_role;
+
+-- ---------------------------------------------------------------------------
+-- The five live derivation sites, rebuilt from their catalog definitions with the
+-- inline expression replaced by the helper call. create or replace (never drop)
+-- so each function keeps its ACL and its COMMENT.
+-- ---------------------------------------------------------------------------
+
+CREATE OR REPLACE FUNCTION agent_board.enroll_federated_human(p_issuer text, p_audience text, p_subject text, p_human_identity_claim jsonb, p_display_name text DEFAULT NULL::text)
+ RETURNS TABLE(agent_id uuid, auth_user_id uuid, handle text, kind text, status text, provider_id text, created_at timestamp with time zone)
+ LANGUAGE plpgsql
+ SECURITY DEFINER
+ SET search_path TO 'agent_board', 'public'
+AS $function$
+declare
+  v_provider_id agent_board.identity_providers.id%type;
+  v_default_board_id uuid;
+  v_locked_default_board_id uuid;
+  v_handle text;
+  v_uid uuid;
+begin
+  if not agent_board._is_service_role() then
+    raise exception 'service_role required for enroll_federated_human' using errcode = '42501';
+  end if;
+  if p_subject is null then
+    raise exception 'verified subject is required' using errcode = '22023';
+  end if;
+
+  -- Snapshot the provider's auto-join target without a row lock so a non-null
+  -- target can be locked in canonical board -> provider order. Then lock the
+  -- provider row and require that the target did not change across the gap. A
+  -- concurrent NULL -> board designation is rejected for retry rather than
+  -- falling back to provider -> board and recreating the cross-route cycle.
+  select ip.id, ip.default_board_id
+    into v_provider_id, v_default_board_id
+    from agent_board.identity_providers ip
+   where ip.issuer = p_issuer
+     and ip.audience = p_audience
+   limit 1;
+
+  -- #193 PROVIDER-ABSENCE GATE, and it must come BEFORE the owner is provisioned
+  -- or locked. PostgreSQL cannot row-lock a row that does not exist, so an absent
+  -- provider left NOTHING to serialize on: this function used to skip the whole
+  -- board/provider ordering, lock the owner, and delegate -- and under READ
+  -- COMMITTED the delegate takes a FRESH snapshot, so a provider committed in that
+  -- gap became visible and its default board was auto-joined while this
+  -- transaction held auth.users. That is owner -> board, inverted against fleet
+  -- onboarding's board -> owner, and it deadlocked.
+  --
+  -- Rejecting here is a VALID serialization -- it orders this call before the
+  -- provider's creation, which is exactly what its own snapshot saw -- and it is
+  -- the same verdict _enroll_federated_human_after_revocation_gate step (4) would
+  -- have reached anyway for an allowlist miss, only now reached before any lock.
+  -- The message differs from the delegate's so a test can tell which gate fired.
+  -- NOTE: this is a permanent 42501, not a retryable 40001. A genuinely
+  -- unallowlisted issuer is a configuration error, and telling a caller to retry it
+  -- forever is worse than telling it no; the rare loser of a real provider-creation
+  -- race succeeds on its next /portal-session call.
+  if v_provider_id is null then
+    raise exception 'issuer/audience not in the identity-provider allowlist (rejected before any owner or board lock)'
+      using errcode = '42501';
+  end if;
+
+  if v_default_board_id is not null then
+    perform 1 from agent_board.boards b
+     where b.id = v_default_board_id
+     for update;
+    if not found then
+      raise exception 'federated human default board changed during enrollment'
+        using errcode = '40001';
+    end if;
+  end if;
+
+  -- Freeze the designation this transaction will delegate against. The provider row
+  -- is held FOR UPDATE through commit, and (issuer, audience) is UNIQUE, so the
+  -- delegate's own lookup cannot resolve to a different row or a changed
+  -- default_board_id than the one locked above.
+  select ip.default_board_id
+    into v_locked_default_board_id
+    from agent_board.identity_providers ip
+   where ip.id = v_provider_id
+   for update;
+  if not found or v_locked_default_board_id is distinct from v_default_board_id then
+    raise exception 'federated human default board changed during enrollment'
+      using errcode = '40001';
+  end if;
+
+  v_handle := agent_board._federated_identity_slug(p_issuer, p_subject);
+  v_uid := agent_board._ensure_agent_auth_user(v_handle);
+
+  perform 1 from auth.users u where u.id = v_uid for update;
+  if not found then
+    raise exception 'federated human owner not found after provisioning' using errcode = 'P0002';
+  end if;
+  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 identity is durably revoked' using errcode = '42501';
+  end if;
+
+  return query
+  select * from agent_board._enroll_federated_human_after_revocation_gate(
+    p_issuer, p_audience, p_subject, p_human_identity_claim, p_display_name
+  );
+end;
+$function$
+
+;
+
+CREATE OR REPLACE FUNCTION agent_board._enroll_federated_human_after_revocation_gate(p_issuer text, p_audience text, p_subject text, p_human_identity_claim jsonb, p_display_name text DEFAULT NULL::text)
+ RETURNS TABLE(agent_id uuid, auth_user_id uuid, handle text, kind text, status text, provider_id text, created_at timestamp with time zone)
+ LANGUAGE plpgsql
+ SECURITY DEFINER
+ SET search_path TO 'agent_board', 'public'
+AS $function$
+declare
+  v_provider agent_board.identity_providers%rowtype;
+  v_handle text;
+  v_uid uuid;
+  v_agent agent_board.agents%rowtype;
+  v_existing agent_board.agents%rowtype;
+  v_email text := nullif(trim(coalesce(p_human_identity_claim->>'email', '')), '');
+  v_email_verified boolean;
+begin
+  -- Derive the verified-email boolean from the claim (never trust it as board-proven
+  -- possession; it only records what the Portal asserted). A non-boolean/absent value
+  -- collapses to false.
+  begin
+    v_email_verified := coalesce((p_human_identity_claim->>'email_verified')::boolean, false);
+  exception when others then
+    v_email_verified := false;
+  end;
+
+  -- (1) 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_human' using errcode = '42501';
+  end if;
+
+  -- (2) 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;
+
+  -- (3) F-11: the synthetic-uid preimage is issuer||'|'||subject. Guard the separator so a
+  -- subject cannot inject a '|' to collide two distinct (issuer, subject) pairs onto one
+  -- owner uid. ALSO reject an email-shaped subject ('@'): the subject is stored VERBATIM in
+  -- agents.metadata.federation.subject, and the agents SELECT RLS is not row-scoped, so an
+  -- email `sub` would be a fleet-harvestable PII leak — the exact hazard the email is kept
+  -- out of agents.metadata to avoid. The operator's ENROLL_SUBJECT_CLAIM must resolve to an
+  -- opaque id; this is the fail-closed backstop, and the pgTAP PII guard asserts BOTH the
+  -- '@'-rejection and metadata carrying no '@'.
+  if position('|' in p_subject) > 0 then
+    raise exception 'verified subject must not contain a pipe separator character'
+      using errcode = '22023';
+  end if;
+  if position('@' in p_subject) > 0 then
+    raise exception 'verified subject must be an opaque id, not an email/@-bearing value'
+      using errcode = '22023';
+  end if;
+
+  -- (4) provider gate on (issuer, audience): must exist + supported + policy_approved.
+  -- Defense in depth atop the EF's signature verify (mirrors 20260719001200:154-181).
+  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) HUMAN-ONLY ceiling. allowed_agent_kinds is permissive on empty/null (the ceiling
+  -- is "unset"); reject ONLY when it is non-empty AND does not include 'human'.
+  if array_length(v_provider.allowed_agent_kinds, 1) is not null
+     and not ('human' = any (v_provider.allowed_agent_kinds)) then
+    raise exception 'provider ceiling does not permit the human kind' using errcode = '42501';
+  end if;
+
+  -- (6) SYNTHETIC uid — derived by agent_board._federated_identity_slug, the ONE
+  -- serialization every federated site shares (#246). "Byte-identical to
+  -- enroll_federated_identity" was a copied expression and a promise; it is now a single
+  -- call, so the sites cannot drift apart and the old line citation cannot go stale.
+  -- Idempotent per (issuer, sub) so re-provisioning converges to ONE owner auth.users row
+  -- = the shared IDLINK uid. Pass issuer/subject VERBATIM (no trim/normalize): the helper
+  -- length-prefixes them before hashing, so normalizing here would move the identity.
+  v_handle := agent_board._federated_identity_slug(p_issuer, p_subject);
+  v_uid := agent_board._ensure_agent_auth_user(v_handle);
+
+  -- (7) Idempotent + no-self-reactivation, keyed on auth_user_id = the synthetic uid (ANY
+  -- status). An ACTIVE row -> return it (idempotent). A NON-active row -> fail closed
+  -- (42501): a suspended/revoked human must NOT re-mint a session (mirrors
+  -- 20260726000100:78-81 and reinforces the F-13 revocation lever). F-5: assert the row is
+  -- human before returning it as a human session (a non-human agent on this owner uid must
+  -- never yield a "human" provision).
+  select *
+    into v_existing
+    from agent_board.agents a
+   where a.auth_user_id = v_uid
+   order by (a.status = 'active') desc, a.created_at asc
+   limit 1;
+  if found then
+    -- (7a) #246 STORED-IDENTITY EQUALITY. The select above keys on the DERIVED uid
+    -- and nothing else, and the derivation is not injective, so `found` does not
+    -- mean "the caller's own agent". Require the pair this row was stamped with at
+    -- creation to equal the pair the caller presented. coalesce(..., false): a row
+    -- with no stored stamp yields NULL, which must read as NOT-mine, not as
+    -- unchecked. First, before the status and kind branches, so a mismatching
+    -- caller learns only that it was refused.
+    if not coalesce(
+         v_existing.metadata #>> '{federation,issuer}'  = p_issuer
+     and v_existing.metadata #>> '{federation,subject}' = p_subject, false) then
+      raise exception 'federated identity mismatch: the owner derived for this issuer/subject is already bound to a different verified identity; refusing to issue a session'
+        using errcode = '42501';
+    end if;
+    if v_existing.status = 'active' then
+      if v_existing.kind <> 'human' then
+        raise exception 'existing agent on this identity is not human; refusing human session'
+          using errcode = '42501';
+      end if;
+      v_agent := v_existing;
+      -- Refresh the verified-email snapshot on re-provision (MERGE, see step 9).
+      if v_email is not null then
+        update auth.users u
+           set raw_user_meta_data = coalesce(u.raw_user_meta_data, '{}'::jsonb)
+             || jsonb_build_object(
+                  'fedsession_email', v_email,
+                  'fedsession_email_verified', v_email_verified,
+                  'fedsession_email_provenance', 'portal-claim-unverified')
+         where u.id = v_uid;
+      end if;
+      -- (auto-join before the idempotent return — see step 11 for the rationale).
+      perform agent_board._fedsession_autojoin_default_board(v_provider, v_agent.id);
+      insert into agent_board.enrollment_federation_audit(
+        issuer, audience, subject, human_identity_claim, provider_id,
+        agent_id, auth_user_id, requested_scopes, granted_scopes, mode)
+      values (
+        p_issuer, p_audience, p_subject, p_human_identity_claim, v_provider.id,
+        v_agent.id, v_uid, '{}', '{}', 'fedsession');
+      return query
+      select v_agent.id, v_agent.auth_user_id, v_agent.handle,
+             v_agent.kind::text, v_agent.status, v_provider.id, v_agent.created_at;
+      return;
+    else
+      raise exception 'a non-active identity already exists for this human; contact an operator'
+        using errcode = '42501';
+    end if;
+  end if;
+
+  -- (8) Create the kind='human' agent (self-owned: auth_user_id = owner_user_id = uid).
+  -- No agent_signing_keys row (humans hold no key). metadata.federation carries ONLY the
+  -- boolean email_verified — never the address (PII / fleet-readable RLS).
+  begin
+    insert into agent_board.agents(
+      agent_type,
+      kind,
+      handle,
+      display_name,
+      status,
+      auth_user_id,
+      owner_user_id,
+      metadata
+    )
+    values (
+      'human',
+      'human'::agent_board.agent_kind,
+      v_handle,
+      coalesce(nullif(trim(p_display_name), ''), 'Human'),
+      'active',
+      v_uid,
+      v_uid,
+      jsonb_build_object(
+        'federation', jsonb_build_object(
+          'mode', 'fedsession',
+          'issuer', p_issuer,
+          'audience', p_audience,
+          'subject', p_subject,
+          'providerId', v_provider.id,
+          'email_verified', v_email_verified,
+          'enrolledAt', now()
+        )
+      )
+    )
+    returning * into v_agent;
+  exception when unique_violation then
+    -- Concurrent first-provision race on the synthetic uid. F-5: re-select the ACTIVE row
+    -- and ASSERT it is human (fail closed otherwise) — never return a non-human agent as a
+    -- human session.
+    select *
+      into v_existing
+      from agent_board.agents a
+     where a.auth_user_id = v_uid
+       and a.status = 'active'
+       and a.kind = 'human'
+     limit 1;
+    if found then
+      -- (8a) #246 STORED-IDENTITY EQUALITY, second return site. Same gate, same
+      -- shape, same message as (7a): this handler returns an EXISTING row on the
+      -- derived uid, so it needs the same proof that the row is the caller's. The
+      -- interleaving that reaches it is concurrency-only -- (7)'s unfiltered select
+      -- intercepts any already-committed row on this uid -- which is why this site
+      -- is pinned structurally by the class assertion rather than differentially by
+      -- a single-session test.
+      if not coalesce(
+           v_existing.metadata #>> '{federation,issuer}'  = p_issuer
+       and v_existing.metadata #>> '{federation,subject}' = p_subject, false) then
+        raise exception 'federated identity mismatch: the owner derived for this issuer/subject is already bound to a different verified identity; refusing to issue a session'
+          using errcode = '42501';
+      end if;
+      v_agent := v_existing;
+    else
+      raise exception 'could not provision federated human (race or non-human on owner uid), please retry'
+        using errcode = '40001';
+    end if;
+  end;
+
+  -- (9) F-12/F-4: store the verified email ONLY in auth.users.raw_user_meta_data
+  -- (service-role-only), MERGED so _ensure_agent_auth_user's {slug, issuer} is preserved,
+  -- tagged provenance='portal-claim-unverified'. The definer owner (postgres) owns auth.*.
+  if v_email is not null then
+    update auth.users u
+       set raw_user_meta_data = coalesce(u.raw_user_meta_data, '{}'::jsonb)
+         || jsonb_build_object(
+              'fedsession_email', v_email,
+              'fedsession_email_verified', v_email_verified,
+              'fedsession_email_provenance', 'portal-claim-unverified')
+     where u.id = v_uid;
+  end if;
+
+  -- (10) FEDSESSION auto-join (new). Baseline default-board membership for a fresh fed-human.
+  perform agent_board._fedsession_autojoin_default_board(v_provider, v_agent.id);
+
+  -- (11) F-6: append the audit row (mode='fedsession'). No requested/granted scopes on the
+  -- human path (authority is membership/role, not enrollment scopes) -> empty arrays.
+  insert into agent_board.enrollment_federation_audit(
+    issuer, audience, subject, human_identity_claim, provider_id,
+    agent_id, auth_user_id, requested_scopes, granted_scopes, mode)
+  values (
+    p_issuer, p_audience, p_subject, p_human_identity_claim, v_provider.id,
+    v_agent.id, v_uid, '{}', '{}', 'fedsession');
+
+  return query
+  select v_agent.id, v_agent.auth_user_id, v_agent.handle,
+         v_agent.kind::text, v_agent.status, v_provider.id, v_agent.created_at;
+end;
+$function$
+
+;
+
+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::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$
+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;
+  v_existing_handle text;
+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
+  -- HERE. #176: this is a BACKSTOP, not the resumption decision. enroll_federated_identity
+  -- is this function's only caller (pg_proc-verified) and it resolves an already-enrolled
+  -- fingerprint before ever reaching here, so a caller that lands on this raise reached the
+  -- internal creator directly. Resumption is deliberately NOT duplicated into this
+  -- function: it has no claim-projection equality gate, so an ownership decision made here
+  -- would rest on bare parameters rather than on the verified claim. What DID change is
+  -- that the raise is actionable -- it names the identity that already holds the key and
+  -- says enrollment need not be repeated.
+  --
+  -- The GATE is still the unchanged `exists` over agent_signing_keys alone. The handle is
+  -- looked up separately, for the MESSAGE only, through a join that a hypothetical
+  -- agent-less key would not satisfy: folding that join into the gate would have turned a
+  -- rendering nicety into a hole that lets such a key be re-bound.
+  if exists (select 1 from agent_board.agent_signing_keys k where k.fingerprint = v_fingerprint) then
+    select a.handle into v_existing_handle
+      from agent_board.agent_signing_keys k
+      join agent_board.agents a on a.id = k.agent_id
+     where k.fingerprint = v_fingerprint
+     limit 1;
+    raise exception 'this signing key is already enrolled (duplicate fingerprint) as agent "%"; enrollment need not be repeated; call agent_board.enroll_federated_identity, which RESUMES an enrollment whose key is owned by the same verified (issuer, subject)',
+      coalesce(v_existing_handle, '(unknown)')
+      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(
+    agent_board._federated_identity_slug(p_issuer, p_subject));
+
+  -- (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;
+$function$
+
+;
+
+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::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;
+
+  -- #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_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_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$
+
+;
+
+-- ---------------------------------------------------------------------------
+-- BACKFILL: move every existing federated owner identity onto the new slug.
+--
+-- The old slug is a one-way digest, so it cannot be inverted; the pair is
+-- recovered from the federation stamps the enrollment paths wrote at creation
+-- (metadata->'federation'), and each candidate pair must REPRODUCE the row's
+-- current slug under the OLD encoding before it is trusted. That reproduction
+-- test is the only place the old expression survives, and it survives as a
+-- proof, not as a derivation: nothing keyed by it is created here.
+-- ---------------------------------------------------------------------------
+do $backfill$
+declare
+  v_row     record;
+  v_iss     text;
+  v_sub     text;
+  v_pairs   int;
+  v_old     text;
+  v_new     text;
+  v_moved   int := 0;
+  v_unproven int;
+begin
+  for v_row in
+    select u.id as uid,
+           substring(lower(u.email) from '^agent\+(fed-human-[0-9a-f]{32})@agent-board\.local$') as slug
+      from auth.users u
+     where lower(u.email) like 'agent+fed-human-%@agent-board.local'
+     order by u.id
+  loop
+    v_old := v_row.slug;
+    if v_old is null then
+      raise exception
+        '#246 backfill: auth.users % carries a fed-human email that does not parse as a slug',
+        v_row.uid using errcode = '22023';
+    end if;
+
+    -- Recover the pair from the stamps of every agent that references this owner --
+    -- by auth_user_id (the human path's own row) or owner_user_id (identity/fleet) --
+    -- keeping only pairs that reproduce this row's slug under the OLD encoding.
+    select count(*), min(t.iss), min(t.sub)
+      into v_pairs, v_iss, v_sub
+      from (
+        select distinct
+               a.metadata->'federation'->>'issuer'  as iss,
+               a.metadata->'federation'->>'subject' as sub
+          from agent_board.agents a
+         where (a.auth_user_id = v_row.uid or a.owner_user_id = v_row.uid)
+           and a.metadata->'federation'->>'issuer'  is not null
+           and a.metadata->'federation'->>'subject' is not null
+           and 'fed-human-' || substr(
+                 encode(extensions.digest(convert_to(
+                   (a.metadata->'federation'->>'issuer') || '|' ||
+                   (a.metadata->'federation'->>'subject'), 'UTF8'), 'sha256'), 'hex'),
+                 1, 32) = v_old
+      ) t;
+
+    -- DISTINCT pairs, not rows: production's owner carries six agents stamped with the
+    -- same pair, and a row count would refuse it. 0 = unrecoverable, >1 = a real
+    -- collision. Either way, refuse rather than bind an account to a guessed human.
+    if v_pairs <> 1 then
+      raise exception
+        '#246 backfill: auth.users % (%) has % distinct stamped (issuer, subject) pairs reproducing its slug; exactly 1 required',
+        v_row.uid, v_old, v_pairs using errcode = '22023';
+    end if;
+
+    v_new := agent_board._federated_identity_slug(v_iss, v_sub);
+    if v_new = v_old then
+      continue;
+    end if;
+
+    if exists (
+      select 1 from auth.users u2
+       where lower(u2.email) = 'agent+' || v_new || '@agent-board.local'
+         and u2.id <> v_row.uid
+    ) then
+      raise exception
+        '#246 backfill: re-keying auth.users % to % would collide with an existing owner row',
+        v_row.uid, v_new using errcode = '23505';
+    end if;
+
+    -- (1) the account key itself, and (2) the slug _ensure_agent_auth_user recorded
+    -- alongside it. The uuid is untouched: sessions, owner_user_id and every FK survive.
+    update auth.users u
+       set email = 'agent+' || v_new || '@agent-board.local',
+           raw_user_meta_data = case
+             when u.raw_user_meta_data->>'slug' = v_old
+               then jsonb_set(u.raw_user_meta_data, '{slug}', to_jsonb(v_new))
+             else u.raw_user_meta_data end,
+           updated_at = now()
+     where u.id = v_row.uid;
+
+    -- (3) the auth.identities row the same helper created, which keys on the slug in
+    -- three places.
+    update auth.identities i
+       set provider_id = v_new,
+           identity_data = i.identity_data
+             || case when i.identity_data->>'sub'  = v_old
+                     then jsonb_build_object('sub',  v_new) else '{}'::jsonb end
+             || case when i.identity_data->>'slug' = v_old
+                     then jsonb_build_object('slug', v_new) else '{}'::jsonb end,
+           updated_at = now()
+     where i.user_id = v_row.uid
+       and i.provider = 'agent_board'
+       and i.provider_id = v_old;
+
+    -- (4) the human path's own agent row, whose handle IS the slug. Agents enrolled on
+    -- the identity/fleet paths keep their own handles and reference the owner by uuid.
+    update agent_board.agents a
+       set handle = v_new
+     where a.handle = v_old;
+
+    v_moved := v_moved + 1;
+  end loop;
+
+  -- Post-condition, asserted over the WHOLE population rather than the rows this loop
+  -- happened to touch: every remaining fed-human owner email must be reproducible from
+  -- a stamp under the NEW derivation. Old and new slugs are shape-identical
+  -- (fed-human-<32hex>), so "no old-form rows remain" is not something a pattern can
+  -- see; this is the check that can.
+  select count(*) into v_unproven
+    from auth.users u
+   where lower(u.email) like 'agent+fed-human-%@agent-board.local'
+     and not exists (
+       select 1
+         from agent_board.agents a
+        where (a.auth_user_id = u.id or a.owner_user_id = u.id)
+          and a.metadata->'federation'->>'issuer'  is not null
+          and a.metadata->'federation'->>'subject' is not null
+          and agent_board._federated_identity_slug(
+                a.metadata->'federation'->>'issuer',
+                a.metadata->'federation'->>'subject')
+              = substring(lower(u.email) from '^agent\+(fed-human-[0-9a-f]{32})@agent-board\.local$'));
+  if v_unproven <> 0 then
+    raise exception
+      '#246 backfill: % federated owner row(s) are not reproducible under the new derivation after re-keying',
+      v_unproven using errcode = '22023';
+  end if;
+
+  raise notice '#246 backfill: re-keyed % federated owner identity row(s)', v_moved;
+end
+$backfill$;