@consiliency/agent-board-schema 1.12.0 → 1.23.0

package/migrations/20260831000100_agent_board_fleet_domain_reclaim.sql

@@ -0,0 +1,389 @@
+-- #153 whole-domain squatting arbitration — reassign a squatted fleet_trust_domain's owner.
+--
+-- #150 (20260829000100) closed the MACHINE-level kill switch: reclaim_fleet_machine can MOVE a
+-- reclaimed machine into a domain the new owner controls, so a squatter who still owns the machine's
+-- ORIGINAL domain can no longer revoke_fleet_subject('trust_domain') to deny it. Two residuals #150
+-- explicitly left open (see its header + issue #153):
+--   (1) the arbitrated new owner may have NO domain to move a reclaimed machine into; and
+--   (2) a squatter can squat a WHOLE domain — there was no operator arbitration path to reassign a
+--       contested domain's OWNER (revoke_fleet_subject('trust_domain') revokes but does not TRANSFER).
+-- This migration adds the domain-level arbitration path for (2), and documents the operator path
+-- for (1) (see the "DOMAINLESS NEW OWNER" note below).
+--
+-- AUTHORITY MODEL (verified against evaluate_fleet_sender_policy / register_fleet_machine /
+-- set_fleet_receive_policy / revoke_fleet_subject). Domain authority is conferred ENTIRELY by
+-- fleet_trust_domains.owner_agent_id — every authz site reads it LIVE:
+--   * revoke_fleet_subject('trust_domain', D): authenticated path requires ftd.owner_agent_id =
+--     current_agent_id() (the squatter's kill switch).
+--   * register_fleet_machine into D: requires ftd.owner_agent_id = actor.
+--   * set_fleet_receive_policy scoped to D: requires ftd.owner_agent_id = actor.
+-- So REASSIGNING owner_agent_id is the exact-and-complete revocation of the squatter's domain
+-- authority: the instant it commits, the squatter fails every one of those checks and the new owner
+-- passes them. There is deliberately NO fleet_revocation_events row written here — mirroring #150's
+-- machine-reclaim divergence rationale: a subject_kind='trust_domain' ledger row OVER-denies (the
+-- policy's trust_domain clause denies EVERY machine in the domain, including the NEW owner's), which
+-- is the opposite of handing the domain over live. The reassignment IS the revocation; the audit
+-- (who/why/prior owner/prior lifecycle) is APPENDED to fleet_trust_domains.metadata.reclaim_history
+-- (same append-not-overwrite shape as #150, so repeated arbitrations do not clobber prior records).
+--
+-- SERIALIZATION CAVEAT (#159 — the claim is NARROWED here, do not overstate it). The ownership
+-- reassignment is atomic AT THE DOMAIN ROW, and reclaim locks that row `for update`. ONE
+-- domain-owner-gated writer is serialized against that lock: revoke_fleet_subject('trust_domain')
+-- takes the same domain-row lock before its authz check (below), so a squatter cannot pass a
+-- stale-owner gate and revoke the just-reclaimed domain. The OTHER two domain-owner-gated writers —
+-- register_fleet_machine and set_fleet_receive_policy — are NOT yet serialized against reclaim: they
+-- authorize on ftd.owner_agent_id without locking the domain row, so a squatter racing an IN-FLIGHT
+-- reclaim can read the pre-commit owner, pass the gate, and land a squatter-owned machine or a
+-- squatter-authored receive policy that SURVIVES the handoff and needs operator cleanup. This is a
+-- narrow, operator-recoverable race, NOT the atomic-transfer-of-all-powers this migration must NOT
+-- claim. Serializing that whole class safely requires re-ordering the merged reclaim_fleet_machine
+-- (its machine-first FOR UPDATE + the implicit FK FOR KEY SHARE on the destination domain from its
+-- trust_domain_id UPDATE make a naive domain-lock on register a machine→domain vs domain→machine
+-- DEADLOCK) and is tracked holistically in #159. Post-commit, all authz reads see the new owner.
+--
+-- OPERATOR-ONLY (arbitration, not self-service). Deciding the rightful owner of a contested domain
+-- requires out-of-band verification only an OPERATOR can perform, so reclaim_fleet_trust_domain is
+-- service_role-only and raises 42501 for any other caller — there is deliberately no owner- or
+-- victim-facing self-reclaim (that would re-create the squatting race in the other direction).
+--
+-- SCOPE / non-goals (matches issue #153's domain-vs-machine split):
+--   * This reassigns the DOMAIN's owner ONLY. It does NOT touch the owner_agent_id of the
+--     constituent fleet_machines — those keep owner=squatter and remain the machine-level
+--     reclaim_fleet_machine (#150) path. Taking a domain does not silently seize every machine in it;
+--     an operator who also wants the machines reclaims them individually. (A squatter left owning
+--     machines in a domain they no longer own can still revoke_fleet_subject('machine', M) on those
+--     machines — a machine-scoped lever, not the domain kill switch this closes.)
+--   * REVOKED-DOMAIN RESIDUAL — a domain the squatter already revoked STAYS revoked after reclaim.
+--     THIS IS INTENTIONAL, NOT AN OVERSIGHT — do not "fix" it by adding a revive here. If a squatter
+--     had ALREADY fired revoke_fleet_subject('trust_domain', D) BEFORE arbitration, D is lifecycle
+--     'revoked' with a denying fleet_revocation_events row, and the policy's trust_domain clause is a
+--     pure EXISTENCE check with no supersession point (unlike the machine clause's effective_at >
+--     reactivated_at). reclaim reassigns owner REGARDLESS of lifecycle (it does NOT raise on a
+--     revoked domain) and records the prior lifecycle in the audit, but it does NOT revive a
+--     pre-revoked domain. Three reasons this is the correct boundary, not a gap:
+--       (a) SEPARATE OPERATOR ACT. For machines, reactivation (#149, which built the reactivated_at
+--           supersession mechanism as its own phase) and reclaim (#150) are DISTINCT acts — #150 only
+--           bundles revival because #149 shipped the mechanism first. Domains have no such mechanism;
+--           domain-reactivation is the #149-parallel follow-up, tracked separately, NOT this build.
+--       (b) LEDGER AUTHORITY (#141/#149 lesson). The only in-scope ways to revive would be to mutate/
+--           delete the trust_domain revocation event (contradicts append-only ledger authority) or to
+--           add a supersession clause to evaluate_fleet_sender_policy (a change to a load-bearing
+--           security fn). Both are out of scope for an ownership-arbitration build.
+--       (c) SECURITY. Ownership transfer must NOT silently un-revoke a domain that may have been
+--           revoked FOR CAUSE — reviving is a deliberate second decision, not a side effect of who
+--           owns it. The transfer still removes the squatter's ability to fire OR re-fire the kill
+--           switch going forward.
+--     (agent_board_fleet_domain_reclaim.test.sql pins this boundary positively: reclaim of a revoked
+--     domain succeeds + transfers owner + the
+--     domain stays revoked — a known/tested edge, not a silent gap.)
+--
+-- DOMAINLESS NEW OWNER (issue #153 residual 1). No create_fleet_trust_domain RPC exists — trust
+-- domains are seeded by direct table INSERT, and service_role already holds INSERT on
+-- fleet_trust_domains (20260628000004 grant). So the operator path for "new owner has no domain to
+-- move a reclaimed machine into" is: (a) service_role INSERTs an active fleet_trust_domains row owned
+-- by the new owner, then (b) reclaim_fleet_machine(..., p_new_trust_domain_id => <that domain>) moves
+-- the reclaimed machine into it (#150). No redundant RPC is added here — the seed is one INSERT the
+-- operator already has the grant for.
+--
+-- TOCTOU (mirror of #150 MUST-FIX 1). reclaim_fleet_trust_domain reassigns owner under
+-- `select ... for update` on the fleet_trust_domains row. revoke_fleet_subject's trust_domain
+-- ownership check was UNLOCKED, so a squatter's concurrent revoke('trust_domain', D) could pass its
+-- ownership SELECT on the pre-reclaim snapshot and land its lifecycle UPDATE AFTER a concurrent
+-- reclaim reassigned the domain — revoking the domain the operator just handed to the new owner.
+-- revoke_fleet_subject is recreated below to LOCK the owning fleet_trust_domains row BEFORE the
+-- trust_domain ownership check (matching reclaim's lock-first order → they serialize deadlock-free on
+-- the same row). Pinned by the domain_reclaim_revoke_race isolation spec.
+--
+-- #118 discipline: reclaim_fleet_trust_domain (and the recreated revoke_fleet_subject) are SECURITY
+-- DEFINER — restate the revoke-from-public and the grant and the comment in this same migration.
+
+create or replace function agent_board.reclaim_fleet_trust_domain(
+  p_domain_id uuid,
+  p_new_owner_agent_id uuid,
+  p_reclaimed_by_agent_id uuid,
+  p_reason text default null
+)
+returns table(domain_id uuid, owner_agent_id uuid, lifecycle_state text, prior_owner_agent_id uuid)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_domain agent_board.fleet_trust_domains%rowtype;
+  v_prior_owner uuid;
+  v_prior_lifecycle text;
+begin
+  -- Operator-only: ownership arbitration for a contested domain is not self-service.
+  if not agent_board._is_service_role() then
+    raise exception 'reclaim_fleet_trust_domain is operator-only (service_role)' using errcode = '42501';
+  end if;
+
+  -- Provenance is required and must name a real agent (audit lands in metadata).
+  if p_reclaimed_by_agent_id is null then
+    raise exception 'p_reclaimed_by_agent_id is required' using errcode = '22023';
+  end if;
+  if not exists (
+    select 1 from agent_board.agents a where a.id = p_reclaimed_by_agent_id
+  ) then
+    raise exception 'p_reclaimed_by_agent_id is not a known agent' using errcode = '22023';
+  end if;
+
+  -- The arbitrated new owner must exist (validate before we reassign anything).
+  if p_new_owner_agent_id is null then
+    raise exception 'p_new_owner_agent_id is required' using errcode = '22023';
+  end if;
+  if not exists (
+    select 1 from agent_board.agents a where a.id = p_new_owner_agent_id
+  ) then
+    raise exception 'p_new_owner_agent_id is not a known agent' using errcode = '22023';
+  end if;
+
+  -- Lock the domain row so this read-reassign serializes against a concurrent
+  -- revoke_fleet_subject('trust_domain', D) (which, post-#153, also takes a row lock on this same
+  -- fleet_trust_domains row before its ownership check). Without it a stale-owner revoke could
+  -- interleave and nuke the just-reassigned domain (see the TOCTOU note in the header).
+  select * into v_domain from agent_board.fleet_trust_domains ftd where ftd.id = p_domain_id for update;
+  if v_domain.id is null then
+    raise exception 'fleet trust domain not found' using errcode = '22023';
+  end if;
+
+  v_prior_owner := v_domain.owner_agent_id;
+  v_prior_lifecycle := v_domain.lifecycle_state;
+
+  -- Reassign ownership. This is the ONLY function-writer of fleet_trust_domains.owner_agent_id
+  -- (no RPC INSERTs a domain — see the EC-4 class assertion in the test). owner_agent_id is the
+  -- domain's authority surface (header AUTHORITY MODEL): post-commit, every authz site reads the new
+  -- owner. The reassignment is atomic at THIS row; it is NOT a fully-serialized transfer of every
+  -- domain power (register_fleet_machine / set_fleet_receive_policy are not yet locked against an
+  -- in-flight reclaim — see header SERIALIZATION CAVEAT / #159).
+  -- LIFECYCLE: reclaim does NOT change lifecycle_state / revoked_at — a domain the squatter already
+  -- revoked STAYS revoked. This is INTENTIONAL (see header REVOKED-DOMAIN RESIDUAL): domain-
+  -- reactivation is a separate #149-parallel act, and ownership transfer must not silently un-revoke
+  -- a domain possibly revoked for cause. Do NOT add a revive here. Leaving both untouched also keeps
+  -- fleet_trust_domains_revoked_shape satisfied without extra care.
+  -- AUDIT: APPEND to metadata.reclaim_history (never overwrite) so repeated arbitrations preserve
+  -- prior records; prior_lifecycle is recorded so the revoked-domain residual is visible in audit.
+  update agent_board.fleet_trust_domains ftd
+     set owner_agent_id = p_new_owner_agent_id,
+         metadata = coalesce(ftd.metadata, '{}'::jsonb)
+           || jsonb_build_object(
+                'reclaim_history',
+                coalesce(ftd.metadata -> 'reclaim_history', '[]'::jsonb)
+                  || jsonb_build_array(jsonb_build_object(
+                       'reclaimed_by', p_reclaimed_by_agent_id,
+                       'reclaim_reason', nullif(trim(coalesce(p_reason, '')), ''),
+                       'prior_owner', v_prior_owner,
+                       'prior_lifecycle_state', v_prior_lifecycle,
+                       'reclaimed_at', now()
+                     ))
+              )
+           || jsonb_build_object('redacted', true, 'metadata-safe', true),
+         updated_at = now()
+   where ftd.id = p_domain_id
+  returning * into v_domain;
+
+  return query select v_domain.id, v_domain.owner_agent_id, v_domain.lifecycle_state, v_prior_owner;
+end;
+$$;
+
+-- #118 discipline: a SECURITY DEFINER function grants EXECUTE to PUBLIC on create. Restate the
+-- revokes/grant and the comment. Operator-only ⇒ granted to service_role ALONE (not authenticated).
+revoke all on function agent_board.reclaim_fleet_trust_domain(uuid, uuid, uuid, text) from public, anon, authenticated;
+grant execute on function agent_board.reclaim_fleet_trust_domain(uuid, uuid, uuid, text) to service_role;
+
+comment on function agent_board.reclaim_fleet_trust_domain(uuid, uuid, uuid, text) is
+  'Operator-only (#153): reclaims a squatted fleet trust domain (whole-domain squatting — the residual #150''s machine-level reclaim could not cover). Reassigns fleet_trust_domains.owner_agent_id to the arbitrated new owner under a row lock — the only function-writer of that column. The reassignment is atomic at the domain row and post-commit every authz site (revoke_fleet_subject(''trust_domain''), register_fleet_machine, set_fleet_receive_policy) reads the new owner. SERIALIZATION CAVEAT (#159): only revoke_fleet_subject(''trust_domain'') is locked against an in-flight reclaim; register_fleet_machine and set_fleet_receive_policy are NOT yet serialized, so a squatter racing an in-flight reclaim may land a machine/policy that survives handoff and needs operator cleanup (tracked in #159). Writes NO fleet_revocation_events row (a trust_domain ledger row over-denies the whole domain incl. the new owner — same divergence rationale as #150); the audit is APPENDED to metadata.reclaim_history. Does NOT reassign the constituent machines'' owners (machine-level reclaim is #150) and INTENTIONALLY does NOT revive a domain the squatter already revoked (a pre-revoked domain STAYS revoked — domain-reactivation is a separate #149-parallel act, and ownership transfer must not silently un-revoke a domain possibly revoked for cause; reassign happens regardless of lifecycle, prior lifecycle is audited). service_role only (raises 42501 otherwise).';
+
+-- ============================================================================================
+-- #153 TOCTOU: revoke_fleet_subject('trust_domain') vs reclaim_fleet_trust_domain.
+-- Reproduced VERBATIM from 20260829000100 (#150) EXCEPT: the trust_domain lock block added below,
+-- and the comment. The trust_domain authz branch derives ownership from
+-- fleet_trust_domains.owner_agent_id and previously read it WITHOUT a lock, so a squatter's
+-- revoke('trust_domain', D) could pass its ownership check on the pre-reclaim snapshot and have its
+-- lifecycle UPDATE apply AFTER a concurrent reclaim_fleet_trust_domain reassigned the domain —
+-- nuking the domain the operator just handed to the new owner. We now LOCK the owning
+-- fleet_trust_domains row FIRST (before the authz re-read and before the event write, matching
+-- reclaim's lock-first order → the two serialize deadlock-free on the same row). The machine/harness/
+-- repo_scope lock (#150 MUST-FIX 1) is preserved verbatim. #118 grants/comment restated.
+-- ============================================================================================
+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;
+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;
+
+  -- #150 MUST-FIX 1: lock the owning fleet_machines row for machine-derived kinds BEFORE the
+  -- unlocked ownership check below, so a concurrent reclaim_fleet_machine (which holds `for update`
+  -- on that row) serializes this call and the authz re-read sees committed ownership. Placed ahead
+  -- of the event write; reclaim also locks this row first, so acquisition order matches (no cycle).
+  if p_subject_kind in ('machine', 'harness', 'repo_scope') then
+    declare
+      v_lock_machine_id uuid;
+    begin
+      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;
+    end;
+  end if;
+
+  -- #153 TOCTOU: lock the owning fleet_trust_domains row for the trust_domain kind BEFORE the
+  -- unlocked ownership check below, so a concurrent reclaim_fleet_trust_domain (which holds
+  -- `for update` on that row) serializes this call and the authz re-read sees committed ownership —
+  -- a stale-owner (squatter) revoke is then refused 42501 rather than nuking a just-reclaimed domain.
+  -- reclaim also locks this row first, so acquisition order matches (no cycle).
+  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 a fleet revocation into the append-only fleet_revocation_events ledger (one row per subject) and flips the subject''s lifecycle to revoked. Re-revoking a subject advances the event''s effective_at to now() (#146). For machine-derived subject kinds (machine/harness/repo_scope) it locks the owning fleet_machines row before the ownership check (#150), and for trust_domain it locks the owning fleet_trust_domains row before the ownership check (#153), so a concurrent reclaim_fleet_machine / reclaim_fleet_trust_domain serializes and a stale-owner revoke is refused (42501) rather than nuking a just-reclaimed machine or domain.';