@consiliency/agent-board-schema 1.22.0 → 1.23.0

package/migrations/20260901000110_agent_board_fleet_onboarding_ceiling_lock.sql

@@ -0,0 +1,604 @@
+-- Consiliency/message-board#186 — make the ceiling-ABSENCE serialization EXPLICIT.
+--
+-- THE REPORTED DEFECT, AND WHY IT IS NOT REACHABLE TODAY. The #186 review held that
+-- 20260901000100 locks the board's ceiling row before evaluating creator authority:
+--
+--     perform 1 from agent_board.board_authority_ceilings c
+--      where c.board_id = v_inv.board_id for update;
+--
+-- and that this lock exists only when the row does. That part is true: absence is
+-- the NORMAL default-owner state (_grant_within_ceiling coalesces a missing row to
+-- rank 4 = owner), and PostgreSQL cannot row-lock a row that is not there. The
+-- conclusion drawn from it — that a concurrent set_board_authority_ceiling
+-- inserting 'observer' can interleave and let a 'member' membership commit under a
+-- ceiling that forbids it — does NOT follow, and was refuted empirically before
+-- this migration was written:
+--
+--   * board_authority_ceilings.board_id has an FK to boards. INSERTing a FIRST
+--     ceiling row therefore takes a FOR KEY SHARE lock on that boards row.
+--   * onboard_federated_fleet_agent already holds that same boards row FOR UPDATE
+--     (`select * into v_board from agent_board.boards b where b.id = v_inv.board_id
+--     for update`), acquired well BEFORE it reads the ceiling.
+--   * FOR UPDATE conflicts with FOR KEY SHARE, so the two transactions already
+--     mutually exclude. Verified with pg_locks: the ceiling INSERT waits on the
+--     onboarding transaction id.
+--   * The row-PRESENT case (ON CONFLICT DO UPDATE, no FK re-check, no parent lock)
+--     is covered by the existing ceiling-row FOR UPDATE.
+--
+-- Removing the advisory lock added below, with everything else intact, changes
+-- NOTHING observable in tests/isolation/specs/atomic_fleet_authority_races.spec —
+-- confirmed by mutation. The advisory lock is therefore NOT the load-bearing
+-- serializer today, and this migration must not be described as closing a live
+-- hole. What is load-bearing is the boards FOR UPDATE, and it is load-bearing only
+-- incidentally: nothing in 20260901000100 says the ceiling decision depends on a
+-- lock taken 150 lines earlier for an unrelated reason (board liveness).
+--
+-- WHAT THIS MIGRATION IS FOR, THEN. It converts an incidental guarantee into a
+-- stated one. A board-keyed pg_advisory_xact_lock, taken by BOTH sides before
+-- either evaluates or writes the ceiling, is the correct instrument precisely
+-- because the serialized thing is the ABSENCE of a row — it does not depend on an
+-- FK's parent-lock side effect surviving a future refactor. Mutation-proven to be
+-- genuinely redundant, not decorative: with the boards FOR UPDATE removed and this
+-- lock retained the isolation spec still passes; with BOTH removed it fails, the
+-- expired replay completing as reused/reused/reused under a committed observer
+-- ceiling. Rejected alternatives:
+--   * a sentinel ceiling row per board — changes default-owner semantics and needs
+--     a backfill over every existing board;
+--   * SERIALIZABLE — a repo-wide isolation posture change, out of scope.
+--
+-- The key derivation lives in ONE function (_lock_board_authority_ceiling) rather
+-- than being written out at each site: two hand-written keys that must be
+-- byte-identical to interlock are a silent-failure class, and a named helper also
+-- lets a catalog assertion enumerate the participants.
+--
+-- LOCK ORDER — ADVISORY FIRST ON BOTH SIDES, and the reason is the FK above.
+-- set_board_authority_ceiling takes the advisory lock, then reads board_memberships
+-- (unlocked), then UPSERTS board_authority_ceilings — and that upsert is NOT a bare
+-- write: on INSERT it takes FOR KEY SHARE on the parent boards row through
+-- board_authority_ceilings_board_id_fkey. Its true order is therefore
+-- advisory -> boards.
+--
+-- onboard_federated_fleet_agent must take the advisory lock in the same relative
+-- position, i.e. BEFORE its `select * into v_board from agent_board.boards ... for
+-- update`. The first cut of this migration did not: it left the advisory
+-- acquisition ~70 lines below the boards lock, giving onboarding boards -> advisory
+-- against the setter's advisory -> boards. That is an ABBA cycle, and it was a
+-- deadlock this migration INTRODUCED — base 20260901000100 has no advisory lock
+-- here and cannot exhibit it. Reproduced deterministically before the fix:
+--
+--   ERROR:  deadlock detected
+--   DETAIL:  Process A waits for ExclusiveLock on advisory lock [...]; blocked by B.
+--            Process B waits for ShareLock on transaction ...; blocked by A.
+--
+-- The lesson for the next reader: an `insert` into a child table is a lock
+-- acquisition on the parent. Do not reason about lock order from the statements
+-- that name a table explicitly.
+--
+-- KNOWN, DELIBERATE GAP. service_role retains a direct
+-- insert/update grant on board_authority_ceilings (operator provisioning,
+-- 20260717000400). A direct table write bypasses any function-level lock; only the
+-- RPC path is serialized. Closing that would require a table trigger and is a
+-- separate decision.
+--
+-- NOT recreated here (recorded so the class is not re-litigated). Enumerated from
+-- pg_proc, not from memory: exactly four agent_board functions call
+-- _grant_within_ceiling —
+--   agent_board.onboard_federated_fleet_agent(...)          <- serialized here
+--   agent_board.grant_board_role(uuid,uuid,text,uuid)
+--   agent_board.create_invite_link(uuid,text,text,integer,timestamptz,uuid,jsonb)
+--   agent_board._redeem_unbounded_invite_for_agent(text,uuid)
+-- The other three are UNCHANGED and are outside #186's scope. Whether they are
+-- exposed to the absence race was NOT determined here: each would need its own
+-- check for an equivalent incidental parent-row lock, and each recreation is a
+-- separate blast radius. Do not read their absence from this migration as evidence
+-- that they are safe. The catalog assertion in
+-- agent_board_atomic_fleet_onboarding.test.sql pins this exact set from pg_proc,
+-- so a NEW reader fails the suite and names itself rather than being silently
+-- admitted to an unexamined class.
+
+create or replace function agent_board._lock_board_authority_ceiling(p_board_id uuid)
+returns void
+language sql
+volatile
+as $$
+  select pg_advisory_xact_lock(
+    hashtextextended('agent_board.board_authority_ceilings:' || p_board_id::text, 0)
+  );
+$$;
+
+comment on function agent_board._lock_board_authority_ceiling(uuid) is
+  'Board-keyed transaction advisory lock serializing the ABSENCE of a board_authority_ceilings row: every RPC that writes the ceiling and every RPC that reads it for authorization takes this FIRST, before any boards row lock. Held to commit. Internal: it takes a lock with NO authorization check on an arbitrary board id, so it must never be grantable to authenticated.';
+-- NOT grantable to authenticated. This helper performs zero authorization and takes
+-- a transaction-scoped lock on any board id it is handed, so a direct grant is an
+-- onboarding DoS: any authenticated principal, with no membership on the board, can
+-- hold the key and block onboard_federated_fleet_agent for the life of its
+-- transaction. Proven, and proven unnecessary — set_board_authority_ceiling still
+-- works when called AS authenticated, because it is SECURITY DEFINER owned by the
+-- schema owner and the helper resolves against the DEFINER's privileges, not the
+-- caller's.
+revoke all on function agent_board._lock_board_authority_ceiling(uuid) from public, anon, authenticated;
+grant execute on function agent_board._lock_board_authority_ceiling(uuid) to service_role;
+
+create or replace function agent_board.set_board_authority_ceiling(
+  p_board_id uuid,
+  p_max_grantable_role text
+)
+returns table(
+  ceiling_board_id uuid,
+  ceiling_max_grantable_role text
+)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_actor uuid := agent_board.current_agent_id();
+begin
+  if p_max_grantable_role not in ('owner', 'admin', 'member', 'observer') then
+    raise exception 'max_grantable_role must be one of owner/admin/member/observer' using errcode = '22023';
+  end if;
+
+  -- Same board-keyed advisory lock every ceiling READER for authorization takes.
+  -- Held to commit, it makes the insert of a first ceiling row serialize against a
+  -- concurrent authorization that would otherwise observe the pre-insert ABSENCE and
+  -- pass as default-owner. Taken before the owner gate so the gate and the write are
+  -- one critical section.
+  perform agent_board._lock_board_authority_ceiling(p_board_id);
+
+  if v_actor is null
+     or not exists (
+       select 1
+         from agent_board.board_memberships bm
+        where bm.board_id = p_board_id
+          and bm.agent_id = v_actor
+          and bm.role = 'owner'
+          and bm.membership_state in ('joined', 'subscribed')
+     ) then
+    raise exception 'only a board owner may set the board authority ceiling' using errcode = '42501';
+  end if;
+
+  insert into agent_board.board_authority_ceilings(board_id, max_grantable_role)
+  values (p_board_id, p_max_grantable_role)
+  on conflict (board_id) do update
+    set max_grantable_role = excluded.max_grantable_role,
+        updated_at = now();
+
+  return query
+  select p_board_id, p_max_grantable_role;
+end;
+$$;
+
+comment on function agent_board.set_board_authority_ceiling(uuid, text) is
+  'Owner-gated setter for a board''s authority ceiling: takes the board-keyed _lock_board_authority_ceiling advisory lock, then upserts board_authority_ceilings only when current_agent_id() is an owner of the board (else raises 42501). Leaves _grant_within_ceiling semantics unchanged.';
+
+revoke all on function agent_board.set_board_authority_ceiling(uuid, text) from public, anon;
+grant execute on function agent_board.set_board_authority_ceiling(uuid, text) to authenticated, service_role;
+
+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,
+  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;
+
+  -- 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(
+    '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.
+  --
+  -- 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;
+$$;
+
+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; takes the board-keyed _lock_board_authority_ceiling advisory lock so the ceiling''s ABSENCE serializes against a concurrent set_board_authority_ceiling before creator authority is evaluated; validates immutable creator bounds; enrolls/replays identity; redeems member ROOMLINK; and creates/reuses the exact harness, repo, and key-bound machine-agent chain in one transaction.';
+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;

package/migrations/20260901000120_agent_board_human_revocation_evidence_completeness.sql

@@ -0,0 +1,78 @@
+-- Consiliency/message-board#162 follow-up: total-human revocation must have stable
+-- evidence for EVERY federation-linked principal before it mutates the subtree.
+-- Requiring only one evidenced principal for the owner lets a mixed owner pass the
+-- gate while an unaudited sibling receives no durable issuer/subject marker.
+
+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
+          where e.agent_id = a.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 every linked agent' 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; requires append-only stable federation evidence for every federation-linked owned agent before any mutation; derives durable issuer/subject markers only from that 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;