@consiliency/agent-board-schema 1.22.0 → 1.23.0

package/migrations/20260901000100_agent_board_atomic_fleet_onboarding.sql

@@ -0,0 +1,1496 @@
+-- Consiliency/message-board#162: atomic, bounded fleet onboarding.
+--
+-- A fleet invite is not merely a ROOMLINK bearer.  Its immutable server-side
+-- bounds are creator-authorized at mint time and the service-role-only composed
+-- RPC validates those exact bytes before creating any identity or fleet row.
+
+create table agent_board.fleet_onboarding_invite_bounds (
+  invite_id uuid primary key references agent_board.board_invite_tokens(id) on delete cascade,
+  machine_id uuid not null references agent_board.fleet_machines(id) on delete restrict,
+  harness_kind text not null,
+  harness_label text not null,
+  repo_slug text not null,
+  repo_fingerprint text not null,
+  repo_scope_role text not null,
+  agent_role text not null,
+  expected_agent_handle text not null,
+  created_by_agent_id uuid not null references agent_board.agents(id) on delete restrict,
+  created_at timestamptz not null default now(),
+  constraint fleet_onboarding_bounds_harness_kind_shape check (
+    harness_kind = lower(harness_kind)
+    and harness_kind = btrim(harness_kind)
+    and length(harness_kind) between 1 and 64
+    and harness_kind ~ '^[a-z0-9][a-z0-9_.-]*$'
+  ),
+  constraint fleet_onboarding_bounds_text_shape check (
+    harness_label = btrim(harness_label) and length(harness_label) between 1 and 128
+    and repo_slug = btrim(repo_slug) and length(repo_slug) between 1 and 255
+    and repo_fingerprint = btrim(repo_fingerprint) and length(repo_fingerprint) between 1 and 255
+    and expected_agent_handle = btrim(expected_agent_handle) and length(expected_agent_handle) between 1 and 255
+  ),
+  constraint fleet_onboarding_bounds_role_pair check (
+    (agent_role = 'phase_worker' and repo_scope_role = 'worker')
+    or (agent_role = 'reviewer' and repo_scope_role = 'reviewer')
+  )
+);
+
+comment on table agent_board.fleet_onboarding_invite_bounds is
+  'Immutable creator-authorized bounds for atomic fleet onboarding. A bounded invite is reserved from generic ROOMLINK redemption and legacy enrollment.';
+
+alter table agent_board.fleet_onboarding_invite_bounds enable row level security;
+revoke all on agent_board.fleet_onboarding_invite_bounds from public, anon, authenticated;
+grant select on agent_board.fleet_onboarding_invite_bounds to service_role;
+
+create table agent_board.fleet_human_revocations (
+  issuer text not null,
+  subject text not null,
+  owner_user_id uuid references auth.users(id) on delete set null,
+  revoked_by_agent_id uuid not null references agent_board.agents(id) on delete restrict,
+  revocation_reason text not null,
+  effective_at timestamptz not null default now(),
+  primary key (issuer, subject)
+);
+
+comment on table agent_board.fleet_human_revocations is
+  'Durable total-revocation marker keyed by stable federation principal. The optional owner UUID may be nulled by auth-user deletion without erasing the marker.';
+
+alter table agent_board.fleet_human_revocations enable row level security;
+revoke all on agent_board.fleet_human_revocations from public, anon, authenticated;
+grant select on agent_board.fleet_human_revocations to service_role;
+
+create function agent_board._protect_federation_contract()
+returns trigger
+language plpgsql
+set search_path = agent_board, public
+as $$
+begin
+  if not agent_board._is_service_role()
+     and new.metadata #> '{federation}' is distinct from old.metadata #> '{federation}' then
+    raise exception 'authenticated agents may not mutate reserved federation metadata' using errcode = '42501';
+  end if;
+  if not agent_board._is_service_role()
+     and old.metadata #> '{federation,replay}' is not null
+     and new.handle is distinct from old.handle then
+    raise exception 'federated replay handle is immutable' using errcode = '42501';
+  end if;
+  return new;
+end;
+$$;
+
+create trigger agents_protect_federation_contract
+before update of handle, metadata on agent_board.agents
+for each row execute function agent_board._protect_federation_contract();
+
+revoke all on function agent_board._protect_federation_contract() from public, anon, authenticated;
+
+create function agent_board._fleet_onboarding_bounds_immutable()
+returns trigger
+language plpgsql
+set search_path = agent_board, public
+as $$
+begin
+  raise exception 'fleet onboarding invite bounds are immutable' using errcode = '55000';
+end;
+$$;
+
+create trigger fleet_onboarding_invite_bounds_immutable
+before update on agent_board.fleet_onboarding_invite_bounds
+for each row execute function agent_board._fleet_onboarding_bounds_immutable();
+
+revoke all on function agent_board._fleet_onboarding_bounds_immutable() from public, anon, authenticated;
+
+create function agent_board.create_fleet_onboarding_invite(
+  p_board_id uuid,
+  p_machine_id uuid,
+  p_harness_kind text,
+  p_harness_label text,
+  p_repo_slug text,
+  p_repo_fingerprint text,
+  p_repo_scope_role text,
+  p_agent_role text,
+  p_expected_agent_handle text,
+  p_max_uses int default 1,
+  p_expires_at timestamptz default null,
+  p_created_by_agent_id uuid default null,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(
+  invite_id uuid,
+  board_id uuid,
+  code text,
+  preset_role text,
+  preset_membership_state text,
+  max_uses int,
+  uses_count int,
+  expires_at timestamptz,
+  created_at timestamptz,
+  machine_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
+)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+#variable_conflict use_column
+declare
+  v_creator uuid;
+  v_board agent_board.boards%rowtype;
+  v_machine agent_board.fleet_machines%rowtype;
+  v_domain agent_board.fleet_trust_domains%rowtype;
+  v_inv record;
+  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, ''));
+begin
+  v_creator := agent_board._resolved_actor_agent_id(p_created_by_agent_id, 'p_created_by_agent_id');
+
+  if p_board_id is null or p_machine_id is null then
+    raise exception 'board and machine are required' using errcode = '22023';
+  end if;
+  if v_kind !~ '^[a-z0-9][a-z0-9_.-]{0,63}$'
+     or length(v_label) not between 1 and 128
+     or length(v_repo_slug) not between 1 and 255
+     or length(v_repo_fingerprint) not between 1 and 255
+     or length(v_expected_handle) not between 1 and 255 then
+    raise exception 'invalid fleet onboarding bounds' using errcode = '22023';
+  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 'invalid fleet onboarding role pair' using errcode = '22023';
+  end if;
+  if p_max_uses is null or p_max_uses < 1 then
+    raise exception 'fleet onboarding invites require a positive use cap' using errcode = '22023';
+  end if;
+
+  select * into v_board
+    from agent_board.boards b
+   where b.id = p_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;
+
+  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_creator 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_creator or v_domain.lifecycle_state <> 'active' then
+    raise exception 'fleet onboarding trust domain is not usable' using errcode = '42501';
+  end if;
+
+  select * into v_inv
+    from agent_board.create_invite_link(
+      p_board_id, 'member', 'joined', p_max_uses, p_expires_at,
+      v_creator, coalesce(p_metadata, '{}'::jsonb) || jsonb_build_object('purpose', 'fleet_onboarding.v1')
+    );
+
+  insert into agent_board.fleet_onboarding_invite_bounds(
+    invite_id, machine_id, harness_kind, harness_label, repo_slug,
+    repo_fingerprint, repo_scope_role, agent_role, expected_agent_handle,
+    created_by_agent_id
+  ) values (
+    v_inv.invite_id, p_machine_id, v_kind, v_label, v_repo_slug,
+    v_repo_fingerprint, p_repo_scope_role, p_agent_role, v_expected_handle,
+    v_creator
+  );
+
+  return query select
+    v_inv.invite_id, v_inv.board_id, v_inv.code, v_inv.preset_role,
+    v_inv.preset_membership_state, v_inv.max_uses, v_inv.uses_count,
+    v_inv.expires_at, v_inv.created_at, p_machine_id, v_kind, v_label,
+    v_repo_slug, v_repo_fingerprint, p_repo_scope_role, p_agent_role,
+    v_expected_handle;
+end;
+$$;
+
+comment on function agent_board.create_fleet_onboarding_invite(uuid, uuid, text, text, text, text, text, text, text, int, timestamptz, uuid, jsonb) is
+  'Mints a member-only ROOMLINK and immutable creator-owned machine/harness/repo/role/handle bounds in one transaction. The bearer code is returned only to the authorized creator.';
+revoke all on function agent_board.create_fleet_onboarding_invite(uuid, uuid, text, text, text, text, text, text, text, int, timestamptz, uuid, jsonb) from public, anon;
+grant execute on function agent_board.create_fleet_onboarding_invite(uuid, uuid, text, text, text, text, text, text, text, int, timestamptz, uuid, jsonb) to authenticated, service_role;
+
+-- Keep the released ROOMLINK core byte-for-byte and put class selection in two
+-- non-interchangeable wrappers.  The renamed primitive remains service-role-only.
+alter function agent_board._redeem_invite_for_agent(text, uuid)
+  rename to _redeem_unbounded_invite_for_agent;
+revoke all on function agent_board._redeem_unbounded_invite_for_agent(text, uuid) from public, anon, authenticated;
+grant execute on function agent_board._redeem_unbounded_invite_for_agent(text, uuid) to service_role;
+
+create function agent_board._redeem_invite_for_agent(p_code text, p_agent_id uuid)
+returns table(board_id uuid, agent_id uuid, role text, membership_state text, updated_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+begin
+  if 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 = p_code
+  ) then
+    raise exception 'invite is reserved for atomic fleet onboarding' using errcode = '42501';
+  end if;
+  return query select * from agent_board._redeem_unbounded_invite_for_agent(p_code, p_agent_id);
+end;
+$$;
+
+create function agent_board._redeem_fleet_invite_for_agent(p_code text, p_agent_id uuid)
+returns table(board_id uuid, agent_id uuid, role text, membership_state text, updated_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+begin
+  if not 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 = p_code
+  ) then
+    raise exception 'fleet onboarding requires a bounded invite' using errcode = '42501';
+  end if;
+  return query select * from agent_board._redeem_unbounded_invite_for_agent(p_code, p_agent_id);
+end;
+$$;
+
+comment on function agent_board._redeem_invite_for_agent(text, uuid) is
+  'Generic ROOMLINK redemption guard. Fleet-bounded invites are categorically rejected before the released redemption core can write.';
+comment on function agent_board._redeem_fleet_invite_for_agent(text, uuid) is
+  'Fleet-only ROOMLINK redemption guard used exclusively by onboard_federated_fleet_agent.';
+revoke all on function agent_board._redeem_invite_for_agent(text, uuid) from public, anon, authenticated;
+revoke all on function agent_board._redeem_fleet_invite_for_agent(text, uuid) from public, anon, authenticated;
+grant execute on function agent_board._redeem_invite_for_agent(text, uuid) to service_role;
+grant execute on function agent_board._redeem_fleet_invite_for_agent(text, uuid) to service_role;
+
+-- Preserve the released enrollment implementation as the one-time creator and
+-- wrap it with a serialized exact-key replay contract.
+alter function agent_board.enroll_federated_identity(
+  text, text, text, jsonb, text, text, text, text, boolean, text, text, text[], text[], text)
+  rename to _enroll_federated_identity_once;
+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;
+
+create function agent_board._normalized_federation_audience(p_claim jsonb)
+returns jsonb
+language plpgsql
+immutable
+strict
+set search_path = agent_board, public
+as $$
+declare
+  v_aud jsonb := p_claim -> 'aud';
+  v_result jsonb;
+begin
+  if jsonb_typeof(v_aud) = 'string' then
+    if length(btrim(v_aud #>> '{}')) = 0 then return null; end if;
+    return jsonb_build_array(v_aud #>> '{}');
+  end if;
+  if jsonb_typeof(v_aud) <> 'array'
+     or jsonb_array_length(v_aud) = 0
+     or exists (select 1 from jsonb_array_elements(v_aud) e where jsonb_typeof(e) <> 'string') then
+    return null;
+  end if;
+  select jsonb_agg(value order by value)
+    into v_result
+    from (select distinct btrim(value) as value from jsonb_array_elements_text(v_aud)) normalized
+   where length(value) > 0;
+  if jsonb_array_length(v_result) <> jsonb_array_length(v_aud) then return null; end if;
+  return v_result;
+end;
+$$;
+revoke all on function agent_board._normalized_federation_audience(jsonb) from public, anon, authenticated;
+grant execute on function agent_board._normalized_federation_audience(jsonb) to service_role;
+
+-- Shipped backfill: only rows with a complete, unambiguous legacy federation
+-- record, exactly one proven key, and exactly one immutable audit claim gain replay
+-- authority. Any historically agent-writable replay object is overwritten. Stable
+-- identity and requested scopes come from the audit/key evidence; fields absent
+-- from that append-only record are pinned to least privilege. The original audit
+-- claim remains untouched.
+update agent_board.agents
+   set metadata = metadata #- '{federation,replay}'::text[]
+ where (metadata #> '{federation}') ? 'replay';
+
+with legacy as (
+  select a.id,
+         e.human_identity_claim,
+         e.issuer,
+         e.subject,
+         e.provider_id,
+         e.requested_scopes,
+         agent_board._normalized_federation_audience(e.human_identity_claim) as audience
+    from agent_board.agents a
+    join agent_board.enrollment_federation_audit e on e.agent_id = a.id
+    join agent_board.identity_providers ip on ip.id = e.provider_id
+   where (select count(*) from agent_board.enrollment_federation_audit ea where ea.agent_id = a.id) = 1
+     and (select count(*) from agent_board.agent_signing_keys k where k.agent_id = a.id) = 1
+     and e.issuer is not null
+     and e.audience is not null
+     and e.subject is not null
+     and ip.issuer = e.issuer
+     and ip.audience = e.audience
+     and e.human_identity_claim ->> 'iss' = e.issuer
+     and e.human_identity_claim ->> ip.subject_claim = e.subject
+     and agent_board._normalized_federation_audience(e.human_identity_claim) ? e.audience
+     and exists (
+       select 1 from agent_board.agent_signing_keys k
+        where k.agent_id = a.id
+          and k.status = 'active' and k.proof_state = 'proven'
+          and k.fingerprint = a.metadata #>> '{federation,signingKeyFingerprint}'
+     )
+)
+update agent_board.agents a
+   set metadata = jsonb_set(
+     a.metadata,
+     '{federation,replay}',
+     jsonb_build_object(
+       'issuer', legacy.issuer,
+       'audience', legacy.audience,
+       'subject', legacy.subject,
+       'providerId', legacy.provider_id,
+       'actorSub', 'null'::jsonb,
+       'requestedSlug', a.handle,
+       'agentKind', a.agent_type,
+       'requestedScopes', to_jsonb(coalesce(legacy.requested_scopes, '{}'::text[])),
+       'requestedBoardScopes', '[]'::jsonb
+     ),
+     true
+   )
+ from legacy
+ where a.id = legacy.id
+   and legacy.issuer = a.metadata #>> '{federation,issuer}'
+   and legacy.subject = a.metadata #>> '{federation,subject}'
+   and legacy.provider_id = a.metadata #>> '{federation,providerId}'
+   and legacy.audience ? (a.metadata #>> '{federation,audience}')
+   and legacy.requested_scopes is not null;
+
+create 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_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;
+
+  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
+        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.';
+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;
+
+create 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,
+  p_agent_kind text default 'agent',
+  p_requested_scopes text[] default '{}',
+  p_requested_board_scopes text[] default '{}',
+  p_invite_code text default null,
+  p_board_id uuid default null,
+  p_machine_id uuid default null,
+  p_harness_kind text default null,
+  p_harness_label text default null,
+  p_repo_slug text default null,
+  p_repo_fingerprint text default null,
+  p_repo_scope_role text default null,
+  p_agent_role text default null,
+  p_expected_agent_handle text default null
+)
+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 int,
+  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 = agent_board, public
+as $$
+#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;
+
+  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(
+    '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;
+  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. Absence retains default-owner semantics.
+  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;
+$$;
+
+comment on function agent_board.onboard_federated_fleet_agent(text, text, text, jsonb, text, text, text, text, boolean, text, text, text[], text[], text, uuid, uuid, text, text, text, text, text, text, text) is
+  'Service-role-only atomic fleet onboarding. Locks invite, machine, domain, principal, key, and binding in canonical order; validates immutable creator bounds; enrolls/replays identity; redeems member ROOMLINK; and creates/reuses the exact harness, repo, and key-bound machine-agent chain in one transaction.';
+revoke all on function agent_board.onboard_federated_fleet_agent(text, text, text, jsonb, text, text, text, text, boolean, text, text, text[], text[], text, uuid, uuid, text, text, text, text, text, text, text) from public, anon, authenticated;
+grant execute on function agent_board.onboard_federated_fleet_agent(text, text, text, jsonb, text, text, text, text, boolean, text, text, text[], text[], text, uuid, uuid, text, text, text, text, text, text, text) to service_role;
+
+create function agent_board.revoke_fleet_machine_agent_binding(
+  p_binding_id uuid,
+  p_revoked_by_agent_id uuid default null,
+  p_revocation_reason text default null,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(binding_id uuid, lifecycle_state text, revoked_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+#variable_conflict use_column
+declare
+  v_actor uuid;
+  v_machine_id uuid;
+  v_binding agent_board.fleet_machine_agents%rowtype;
+begin
+  v_actor := agent_board._resolved_actor_agent_id(p_revoked_by_agent_id, 'p_revoked_by_agent_id');
+  if nullif(btrim(coalesce(p_revocation_reason, '')), '') is null then
+    raise exception 'revocation reason is required' using errcode = '22023';
+  end if;
+  select b.machine_id into v_machine_id from agent_board.fleet_machine_agents b where b.id = p_binding_id;
+  if v_machine_id is null then raise exception 'binding not found' using errcode = 'P0002'; end if;
+  perform 1 from agent_board.fleet_machines m
+   where m.id = v_machine_id and (agent_board._is_service_role() or m.owner_agent_id = v_actor)
+   for update;
+  if not found then raise exception 'binding revocation is not authorized' using errcode = '42501'; end if;
+  select * into v_binding from agent_board.fleet_machine_agents b where b.id = p_binding_id for update;
+  if v_binding.lifecycle_state = 'revoked' then
+    return query select v_binding.id, v_binding.lifecycle_state, v_binding.revoked_at;
+    return;
+  end if;
+  update agent_board.fleet_machine_agents b
+     set lifecycle_state = 'revoked', revoked_at = now(), updated_at = now(),
+         metadata = b.metadata || jsonb_build_object(
+           'bindingRevocation', jsonb_build_object(
+             'revokedByAgentId', v_actor, 'reason', btrim(p_revocation_reason),
+             'metadata', coalesce(p_metadata, '{}'::jsonb), 'revokedAt', now()
+           )
+         )
+   where b.id = p_binding_id returning * into v_binding;
+  return query select v_binding.id, v_binding.lifecycle_state, v_binding.revoked_at;
+end;
+$$;
+
+comment on function agent_board.revoke_fleet_machine_agent_binding(uuid, uuid, text, jsonb) is
+  'Sole writer for permanent exact fleet-machine-agent binding revocation. Locks the owning machine before the binding, rechecks owner/service authority, and never deletes or reactivates the row.';
+revoke all on function agent_board.revoke_fleet_machine_agent_binding(uuid, uuid, text, jsonb) from public, anon;
+grant execute on function agent_board.revoke_fleet_machine_agent_binding(uuid, uuid, text, jsonb) to authenticated, service_role;
+
+-- Refresh the public fleet revocation writer so onboarding and revocation share a
+-- single lock order.  Machine-derived subjects already locked their machine first;
+-- agent subjects now lock all existing bound machines before the principal and
+-- bindings, while signing-key subjects lock their owning principal before the key.
+create or replace function agent_board.revoke_fleet_subject(
+  p_subject_kind text,
+  p_subject_id uuid,
+  p_revoked_by_agent_id uuid,
+  p_revocation_reason text,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(revocation_event_id uuid, subject_kind text, effective_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_event agent_board.fleet_revocation_events%rowtype;
+  v_actor_agent_id uuid;
+  v_lock_machine_id uuid;
+  v_lock_agent_id uuid;
+begin
+  if p_subject_kind not in ('trust_domain', 'machine', 'harness', 'repo_scope', 'agent', 'signing_key', 'credential') then
+    raise exception 'unsupported fleet revocation subject' using errcode = '22023';
+  end if;
+
+  if p_subject_kind in ('machine', 'harness', 'repo_scope') then
+    v_lock_machine_id := case
+      when p_subject_kind = 'machine' then p_subject_id
+      when p_subject_kind = 'harness' then (
+        select fhr.machine_id
+          from agent_board.fleet_harness_registrations fhr
+         where fhr.id = p_subject_id)
+      when p_subject_kind = 'repo_scope' then (
+        select fhr.machine_id
+          from agent_board.fleet_repo_scopes frs
+          join agent_board.fleet_harness_registrations fhr
+            on fhr.id = frs.harness_registration_id
+         where frs.id = p_subject_id)
+    end;
+    if v_lock_machine_id is not null then
+      perform 1
+        from agent_board.fleet_machines fm
+       where fm.id = v_lock_machine_id
+       for update;
+    end if;
+  elsif p_subject_kind = 'agent' then
+    for v_lock_machine_id in
+      select distinct fma.machine_id
+        from agent_board.fleet_machine_agents fma
+       where fma.agent_id = p_subject_id
+       order by fma.machine_id
+    loop
+      perform 1
+        from agent_board.fleet_machines fm
+       where fm.id = v_lock_machine_id
+       for update;
+    end loop;
+    perform 1 from agent_board.agents a where a.id = p_subject_id for update;
+    perform 1
+      from agent_board.fleet_machine_agents fma
+     where fma.agent_id = p_subject_id
+     order by fma.id
+     for update;
+  elsif p_subject_kind = 'signing_key' then
+    select ask.agent_id
+      into v_lock_agent_id
+      from agent_board.agent_signing_keys ask
+     where ask.id = p_subject_id;
+    if v_lock_agent_id is not null then
+      perform 1 from agent_board.agents a where a.id = v_lock_agent_id for update;
+    end if;
+    perform 1 from agent_board.agent_signing_keys ask where ask.id = p_subject_id for update;
+  end if;
+
+  if p_subject_kind = 'trust_domain' then
+    perform 1
+      from agent_board.fleet_trust_domains ftd
+     where ftd.id = p_subject_id
+     for update;
+  end if;
+
+  v_actor_agent_id := agent_board._resolved_actor_agent_id(
+    p_revoked_by_agent_id,
+    'p_revoked_by_agent_id'
+  );
+
+  if not agent_board._is_service_role() then
+    if p_subject_kind = 'trust_domain' and not exists (
+      select 1 from agent_board.fleet_trust_domains ftd
+       where ftd.id = p_subject_id and ftd.owner_agent_id = v_actor_agent_id
+    ) then
+      raise exception 'trust domain is not owned by current_agent_id()' using errcode = '42501';
+    elsif p_subject_kind = 'machine' and not exists (
+      select 1 from agent_board.fleet_machines fm
+       where fm.id = p_subject_id and fm.owner_agent_id = v_actor_agent_id
+    ) then
+      raise exception 'machine is not owned by current_agent_id()' using errcode = '42501';
+    elsif p_subject_kind = 'harness' and not exists (
+      select 1
+        from agent_board.fleet_harness_registrations fhr
+        join agent_board.fleet_machines fm on fm.id = fhr.machine_id
+       where fhr.id = p_subject_id and fm.owner_agent_id = v_actor_agent_id
+    ) then
+      raise exception 'harness is not owned by current_agent_id()' using errcode = '42501';
+    elsif p_subject_kind = 'repo_scope' and not exists (
+      select 1
+        from agent_board.fleet_repo_scopes frs
+        join agent_board.fleet_harness_registrations fhr
+          on fhr.id = frs.harness_registration_id
+        join agent_board.fleet_machines fm on fm.id = fhr.machine_id
+       where frs.id = p_subject_id and fm.owner_agent_id = v_actor_agent_id
+    ) then
+      raise exception 'repo scope is not owned by current_agent_id()' using errcode = '42501';
+    elsif p_subject_kind = 'agent' and p_subject_id <> v_actor_agent_id then
+      raise exception 'agent revocation must target current_agent_id()' using errcode = '42501';
+    elsif p_subject_kind = 'signing_key' and not exists (
+      select 1 from agent_board.agent_signing_keys ask
+       where ask.id = p_subject_id and ask.agent_id = v_actor_agent_id
+    ) then
+      raise exception 'signing key is not owned by current_agent_id()' using errcode = '42501';
+    elsif p_subject_kind = 'credential' and not exists (
+      select 1 from agent_board.agent_credentials ac
+       where ac.id = p_subject_id and ac.agent_id = v_actor_agent_id
+    ) then
+      raise exception 'credential is not owned by current_agent_id()' using errcode = '42501';
+    end if;
+  end if;
+
+  select *
+    into v_event
+    from agent_board.fleet_revocation_events fre
+   where fre.subject_kind = p_subject_kind
+     and fre.subject_id = p_subject_id
+   limit 1;
+
+  if v_event.id is null then
+    insert into agent_board.fleet_revocation_events(
+      subject_kind,
+      subject_id,
+      trust_domain_id,
+      machine_id,
+      harness_registration_id,
+      repo_scope_id,
+      agent_id,
+      signing_key_id,
+      revoked_by_agent_id,
+      revocation_reason,
+      metadata
+    )
+    values (
+      p_subject_kind,
+      p_subject_id,
+      case when p_subject_kind = 'trust_domain' then p_subject_id end,
+      case when p_subject_kind = 'machine' then p_subject_id end,
+      case when p_subject_kind = 'harness' then p_subject_id end,
+      case when p_subject_kind = 'repo_scope' then p_subject_id end,
+      case when p_subject_kind = 'agent' then p_subject_id end,
+      case when p_subject_kind = 'signing_key' then p_subject_id end,
+      p_revoked_by_agent_id,
+      trim(coalesce(p_revocation_reason, 'operator revocation')),
+      coalesce(p_metadata, '{}'::jsonb)
+        || jsonb_build_object('redacted', true, 'metadata-safe', true)
+    )
+    returning * into v_event;
+  else
+    update agent_board.fleet_revocation_events fre
+       set effective_at = now(),
+           revoked_by_agent_id = p_revoked_by_agent_id,
+           revocation_reason = trim(coalesce(p_revocation_reason, 'operator revocation')),
+           metadata = coalesce(p_metadata, '{}'::jsonb)
+             || jsonb_build_object('redacted', true, 'metadata-safe', true)
+     where fre.id = v_event.id
+    returning * into v_event;
+  end if;
+
+  if p_subject_kind = 'trust_domain' then
+    update agent_board.fleet_trust_domains
+       set lifecycle_state = 'revoked', revoked_at = v_event.effective_at, updated_at = now()
+     where id = p_subject_id;
+  elsif p_subject_kind = 'machine' then
+    update agent_board.fleet_machines
+       set lifecycle_state = 'revoked', revoked_at = v_event.effective_at, updated_at = now()
+     where id = p_subject_id;
+  elsif p_subject_kind = 'harness' then
+    update agent_board.fleet_harness_registrations
+       set lifecycle_state = 'revoked', revoked_at = v_event.effective_at, updated_at = now()
+     where id = p_subject_id;
+  elsif p_subject_kind = 'repo_scope' then
+    update agent_board.fleet_repo_scopes
+       set lifecycle_state = 'revoked', revoked_at = v_event.effective_at, updated_at = now()
+     where id = p_subject_id;
+  elsif p_subject_kind = 'agent' then
+    update agent_board.fleet_machine_agents
+       set lifecycle_state = 'revoked', revoked_at = v_event.effective_at, updated_at = now()
+     where agent_id = p_subject_id;
+  elsif p_subject_kind = 'signing_key' then
+    update agent_board.agent_signing_keys
+       set status = case when status = 'compromised' then status else 'revoked' end,
+           proof_state = 'revoked',
+           revoked_at = coalesce(revoked_at, v_event.effective_at),
+           revoked_by_agent_id = p_revoked_by_agent_id,
+           revocation_reason = trim(coalesce(p_revocation_reason, 'operator revocation')),
+           updated_at = now()
+     where id = p_subject_id;
+  end if;
+
+  return query select v_event.id, v_event.subject_kind, v_event.effective_at;
+end;
+$$;
+
+revoke all on function agent_board.revoke_fleet_subject(text, uuid, uuid, text, jsonb) from public, anon;
+grant execute on function agent_board.revoke_fleet_subject(text, uuid, uuid, text, jsonb) to authenticated, service_role;
+
+comment on function agent_board.revoke_fleet_subject(text, uuid, uuid, text, jsonb) is
+  'Records effective fleet revocation while sharing atomic onboarding lock order: machine-derived subjects lock the machine first, agent revocation locks affected machines in UUID order before the agent and bindings, and signing-key revocation locks agent before key.';
+
+-- Refresh the subtree primitive and its public entrypoints.  The primitive locks
+-- agent before keys; both entrypoints visit agents in UUID order.
+create or replace function agent_board._revoke_agent_principal(
+  p_agent_id uuid,
+  p_revoked_by_agent_id uuid,
+  p_reason text
+)
+returns integer
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_key record;
+  v_key_count integer := 0;
+  v_agent_flipped boolean := false;
+begin
+  perform 1 from agent_board.agents a where a.id = p_agent_id for update;
+
+  for v_key in
+    select id
+      from agent_board.agent_signing_keys
+     where agent_id = p_agent_id
+       and status not in ('revoked', 'compromised')
+     order by id
+     for update
+  loop
+    update agent_board.agent_signing_keys
+       set status = 'revoked',
+           proof_state = 'revoked',
+           revoked_at = now(),
+           revoked_by_agent_id = p_revoked_by_agent_id,
+           revocation_reason = p_reason,
+           updated_at = now()
+     where id = v_key.id;
+
+    insert into agent_board.fleet_revocation_events(
+      subject_kind, subject_id, signing_key_id, agent_id,
+      revoked_by_agent_id, revocation_reason, metadata
+    )
+    values (
+      'signing_key', v_key.id, v_key.id, p_agent_id,
+      p_revoked_by_agent_id, p_reason,
+      jsonb_build_object('source', 'revoke_agent_subtree')
+    )
+    on conflict (subject_kind, subject_id) do update
+      set revoked_by_agent_id = excluded.revoked_by_agent_id,
+          revocation_reason = excluded.revocation_reason,
+          signing_key_id = excluded.signing_key_id,
+          agent_id = excluded.agent_id,
+          effective_at = now(),
+          metadata = excluded.metadata;
+
+    v_key_count := v_key_count + 1;
+  end loop;
+
+  update agent_board.agents
+     set status = 'revoked', updated_at = now()
+   where id = p_agent_id and status <> 'revoked';
+  if found then
+    v_agent_flipped := true;
+  end if;
+
+  update agent_board.delegation_grants
+     set revoked_at = now()
+   where child_agent_id = p_agent_id and revoked_at is null;
+
+  update agent_board.agent_credentials ac
+     set revoked_at = coalesce(ac.revoked_at, now()),
+         updated_at = now(),
+         metadata = coalesce(ac.metadata, '{}'::jsonb)
+           || jsonb_build_object(
+             'revokedByAgentId', p_revoked_by_agent_id,
+             'revocationReason', p_reason,
+             'source', 'revoke_agent_subtree'
+           )
+   where ac.agent_id = p_agent_id and ac.revoked_at is null;
+
+  insert into agent_board.fleet_revocation_events(
+    subject_kind, subject_id, agent_id,
+    revoked_by_agent_id, revocation_reason, metadata
+  )
+  values (
+    'agent', p_agent_id, p_agent_id,
+    p_revoked_by_agent_id, p_reason,
+    jsonb_build_object('source', 'revoke_agent_subtree', 'statusFlipped', v_agent_flipped)
+  )
+  on conflict (subject_kind, subject_id) do update
+    set revoked_by_agent_id = excluded.revoked_by_agent_id,
+        revocation_reason = excluded.revocation_reason,
+        agent_id = excluded.agent_id,
+        effective_at = now(),
+        metadata = excluded.metadata;
+
+  return v_key_count;
+end;
+$$;
+
+comment on function agent_board._revoke_agent_principal(uuid, uuid, text) is
+  'Per-principal revocation primitive. Locks agent before signing keys in UUID order, then preserves the existing key, status, grant, credential, and audit effects.';
+revoke all on function agent_board._revoke_agent_principal(uuid, uuid, text) from public, anon, authenticated;
+grant execute on function agent_board._revoke_agent_principal(uuid, uuid, text) to service_role;
+
+create or replace function agent_board.revoke_agent_subtree(
+  p_root_agent_id uuid,
+  p_revoked_by_agent_id uuid,
+  p_reason text default 'root revocation'
+)
+returns table(revoked_agent_count integer, revoked_key_count integer)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_agent uuid;
+  v_agent_count integer := 0;
+  v_key_count integer := 0;
+begin
+  if not agent_board._is_service_role() then
+    raise exception 'revoke_agent_subtree is service_role-only' using errcode = '42501';
+  end if;
+  if not exists (select 1 from agent_board.agents where id = p_root_agent_id) then
+    raise exception 'root agent not found' using errcode = 'P0002';
+  end if;
+
+  for v_agent in
+    with recursive subtree(agent_id) as (
+      select p_root_agent_id
+      union
+      select g.child_agent_id
+        from agent_board.delegation_grants g
+        join subtree s on g.parent_agent_id = s.agent_id
+    )
+    select agent_id from subtree order by agent_id
+  loop
+    v_key_count := v_key_count
+      + agent_board._revoke_agent_principal(v_agent, p_revoked_by_agent_id, p_reason);
+    v_agent_count := v_agent_count + 1;
+  end loop;
+
+  return query select v_agent_count, v_key_count;
+end;
+$$;
+
+comment on function agent_board.revoke_agent_subtree(uuid, uuid, text) is
+  'DOWN-walking refresh-checked cascade. Visits the root and every grant-derived descendant in UUID order before the agent-before-key primitive. service_role-only.';
+revoke all on function agent_board.revoke_agent_subtree(uuid, uuid, text) from public, anon, authenticated;
+grant execute on function agent_board.revoke_agent_subtree(uuid, uuid, text) to service_role;
+
+create or replace function agent_board.revoke_human_subtree(
+  p_owner_user_id uuid,
+  p_revoked_by_agent_id uuid,
+  p_reason text default 'human revocation'
+)
+returns table(revoked_agent_count integer, revoked_key_count integer)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_agent uuid;
+  v_agent_count integer := 0;
+  v_key_count integer := 0;
+begin
+  if not agent_board._is_service_role() then
+    raise exception 'revoke_human_subtree is service_role-only' using errcode = '42501';
+  end if;
+
+  perform 1 from auth.users u where u.id = p_owner_user_id for update;
+  if not found then
+    raise exception 'human owner not found' using errcode = 'P0002';
+  end if;
+
+  if exists (
+    select 1
+      from agent_board.agents a
+     where a.owner_user_id = p_owner_user_id
+       and jsonb_typeof(a.metadata -> 'federation') = 'object'
+  ) and not exists (
+    select 1
+      from agent_board.enrollment_federation_audit e
+      join agent_board.agents a on a.id = e.agent_id
+     where a.owner_user_id = p_owner_user_id
+       and nullif(btrim(e.issuer), '') is not null
+       and nullif(btrim(e.subject), '') is not null
+  ) then
+    raise exception 'stable federation evidence not found for human owner' using errcode = 'P0002';
+  end if;
+
+  insert into agent_board.fleet_human_revocations(
+    issuer, subject, owner_user_id, revoked_by_agent_id, revocation_reason
+  )
+  select distinct
+    e.issuer,
+    e.subject,
+    p_owner_user_id, p_revoked_by_agent_id, p_reason
+    from agent_board.enrollment_federation_audit e
+    join agent_board.agents a on a.id = e.agent_id
+   where a.owner_user_id = p_owner_user_id
+     and nullif(btrim(e.issuer), '') is not null
+     and nullif(btrim(e.subject), '') is not null
+  on conflict (issuer, subject) do nothing;
+
+  for v_agent in
+    select id
+      from agent_board.agents
+     where owner_user_id = p_owner_user_id
+     order by id
+  loop
+    v_key_count := v_key_count
+      + agent_board._revoke_agent_principal(v_agent, p_revoked_by_agent_id, p_reason);
+    v_agent_count := v_agent_count + 1;
+  end loop;
+
+  return query select v_agent_count, v_key_count;
+end;
+$$;
+
+comment on function agent_board.revoke_human_subtree(uuid, uuid, text) is
+  'TOTAL human revocation. Locks the human owner, derives durable issuer/subject markers only from append-only enrollment audit evidence, then visits every owned agent in UUID order before the agent-before-key primitive. service_role-only.';
+revoke all on function agent_board.revoke_human_subtree(uuid, uuid, text) from public, anon, authenticated;
+grant execute on function agent_board.revoke_human_subtree(uuid, uuid, text) to service_role;