@consiliency/agent-board-schema 1.58.0 → 1.60.0

package/migrations/20261009000100_agent_board_hosted_followups.sql

@@ -0,0 +1,665 @@
+-- HOSTED follow-ups (Consiliency/message-board#591, items 4, 8 and 9): the owner's verified
+-- (iss, sub) is recorded on every delegate instance and revoke_human_subtree derives a durable
+-- marker from it; tombstone_delegate_instance takes the delegate's agents row before its
+-- credentials, so it serialises with revoke_human_subtree and revoke_agent_subtree (both
+-- agent-before-credentials) instead of deadlocking against them; the exchange takes the delegate's
+-- agents row before the credentials for the same reason. schema_version stays 8.
+--
+-- THE CONTRACT is the HOSTED section of specs/agent-client-contract.md, amendment AB15.
+--
+-- Sources, each at its LATEST definition, read from the catalog of a replay of this tree
+-- (pg_get_functiondef / md5(prosrc) compared with the file text before editing):
+--   * exchange_delegate_credential, tombstone_delegate_instance -- 20261008000100
+--   * revoke_human_subtree                                      -- 20260901000120
+-- Each is redefined below VERBATIM plus the lines marked `HOSTED #591`. create or replace keeps
+-- the ACL and COMMENT; both are restated anyway so this file says what each function is.
+--
+-- SUPERSEDED COMMENT. add_delegate_to_board's body comment (20261008000100, section 9) says the
+-- tombstone takes "its own owner-keyed advisory lock, then the instance row". That is still
+-- true; the tombstone now takes the delegate's agents row (FOR NO KEY UPDATE, its status UPDATE)
+-- right after the instance row instead of last. add_delegate_to_board's only lock on that row is
+-- the foreign-key FOR KEY SHARE of the sink's insert, which FOR NO KEY UPDATE does not block, so
+-- that comment's conclusion -- the instance row is the only lock the two contend on -- still
+-- holds (measured: hosted_delegate_add_tombstone_race). add_delegate_to_board is not redefined.
+
+-- =============================================================================
+-- 1. The owner's verified identity on each instance (#591 item 4)
+-- =============================================================================
+-- revoke_human_subtree writes the durable marker fleet_human_revocations (issuer, subject) only
+-- from enrollment_federation_audit. An owner whose only principals are hosted delegates has no
+-- such row, so revoking it left no marker, and -- with no human agents row either -- a fresh first
+-- exchange passed the exchange's owner_inactive check and created a new active delegate.
+--
+-- The marker is keyed by (issuer, subject) and the owner uid is a one-way derivation of them
+-- (_federated_identity_slug, then the auth user of that slug), so revoke_human_subtree cannot
+-- rebuild the pair from the uid. The exchange and the tombstone both have the verified pair; they
+-- now record it. It is REVOCATION EVIDENCE, never identity: owner_mismatch still compares the uid,
+-- and nothing compares these columns with a token.
+--
+-- NULLABLE, not NOT NULL. A 1.58.0 adopter may already have rows, and no backfill exists: the
+-- subject is not derivable from the uid, and a delegate-only owner has no other row that carries
+-- it. NOT NULL would therefore fail this migration on exactly the databases it must upgrade. The
+-- two columns are paired (both or neither, neither empty), every write path of both RPCs fills
+-- them, and both fill a legacy row's null pair when they write it (sound because owner_mismatch
+-- has just proved the row's uid is the one this (iss, sub) derives): the exchange on a successful
+-- exchange, the tombstone on any call, including a repeat of an existing tombstone (the only write
+-- a legacy TOMBSTONED row can ever get, since the exchange refuses it before writing). A legacy row
+-- not filled before its owner is revoked gives revoke_human_subtree nothing: stated in AB15.
+alter table agent_board.delegate_instances
+  add column if not exists owner_issuer text,
+  add column if not exists owner_subject text;
+
+alter table agent_board.delegate_instances
+  drop constraint if exists delegate_instances_owner_identity_shape;
+alter table agent_board.delegate_instances
+  add constraint delegate_instances_owner_identity_shape check (
+    (owner_issuer is null and owner_subject is null)
+    or (owner_issuer is not null and owner_subject is not null
+        and owner_issuer <> '' and owner_subject <> '')
+  );
+
+comment on column agent_board.delegate_instances.owner_issuer is
+  'HOSTED #591 (AB15): the verified issuer of the owner token that created or last wrote this instance, recorded by exchange_delegate_credential and tombstone_delegate_instance. Revocation evidence only: revoke_human_subtree derives a fleet_human_revocations marker from (owner_issuer, owner_subject). Paired with owner_subject; never changes once set (trg_delegate_instances_owner_identity_immutable). Null only on a row written before 1.59.0 and not filled since (any tombstone call for it, or a successful exchange of it, fills it).';
+comment on column agent_board.delegate_instances.owner_subject is
+  'HOSTED #591 (AB15): the verified owner subject (the Portal sub) paired with owner_issuer. Revocation evidence only, never compared for identity: the owner identity is owner_user_id. Never changes once set.';
+
+-- Once set, never changed. A null legacy pair may be filled once.
+create or replace function agent_board._delegate_instances_owner_identity_immutable()
+returns trigger
+language plpgsql
+set search_path = ''
+as $fn$
+begin
+  if old.owner_issuer is not null
+     and (new.owner_issuer is distinct from old.owner_issuer
+          or new.owner_subject is distinct from old.owner_subject) then
+    raise exception 'delegate_instances owner identity never changes once recorded'
+      using errcode = '23514';
+  end if;
+  return new;
+end;
+$fn$;
+
+revoke all on function agent_board._delegate_instances_owner_identity_immutable() from public;
+
+comment on function agent_board._delegate_instances_owner_identity_immutable() is
+  'HOSTED #591 (AB15): trigger function refusing any UPDATE that changes delegate_instances.owner_issuer or owner_subject once owner_issuer is set. A null legacy pair may be filled once. EXECUTE revoked from PUBLIC; a trigger function needs none at fire time.';
+
+drop trigger if exists trg_delegate_instances_owner_identity_immutable on agent_board.delegate_instances;
+create trigger trg_delegate_instances_owner_identity_immutable
+  before update of owner_issuer, owner_subject on agent_board.delegate_instances
+  for each row execute function agent_board._delegate_instances_owner_identity_immutable();
+
+-- =============================================================================
+-- 2. exchange_delegate_credential -- records the owner's (iss, sub) (#591 item 4)
+-- =============================================================================
+create or replace function agent_board.exchange_delegate_credential(p_claims jsonb)
+returns table(agent_id uuid, auth_user_id uuid, credential_id uuid, expires_at timestamptz)
+language plpgsql
+security definer
+set search_path = ''
+as $fn$
+#variable_conflict use_column
+declare
+  v_iss text;
+  v_sub text;
+  v_slot text;
+  v_claim jsonb;
+  v_instance_id text;
+  v_grant_id text;
+  v_generation bigint;
+  v_client_id text;
+  v_change jsonb;
+  v_change_gen bigint;
+  v_owner uuid;
+  v_owner_slug text;
+  v_row agent_board.delegate_instances%rowtype;
+  v_first boolean;
+  v_live integer;
+  v_slug text;
+  v_auth uuid;
+  v_agent uuid;
+  v_status text;
+  v_credential uuid;
+  v_expires timestamptz;
+begin
+  if not agent_board._is_service_role() then
+    raise exception 'exchange_delegate_credential is service_role-only' using errcode = '42501';
+  end if;
+
+  -- SHAPE. The Edge Function refuses every malformed token first; this is the database's own
+  -- refusal of the same shape, so a caller that skips it cannot write a malformed instance.
+  if jsonb_typeof(p_claims) is distinct from 'object'
+     or jsonb_typeof(p_claims -> 'iss') is distinct from 'string'
+     or jsonb_typeof(p_claims -> 'sub') is distinct from 'string'
+     or coalesce(p_claims ->> 'iss', '') = ''
+     or coalesce(p_claims ->> 'sub', '') = ''
+     or jsonb_typeof(p_claims -> 'slot_resource') not in ('string', 'null')
+     or jsonb_typeof(p_claims -> 'agent_board_delegate_instance') is distinct from 'object' then
+    raise exception 'claims_malformed' using errcode = '22023';
+  end if;
+  v_iss := p_claims ->> 'iss';
+  v_sub := p_claims ->> 'sub';
+  v_slot := p_claims ->> 'slot_resource';
+  v_claim := p_claims -> 'agent_board_delegate_instance';
+
+  -- The instance claim: exactly these seven fields, each of its type.
+  if (select array_agg(k order by k) from jsonb_object_keys(v_claim) k)
+       is distinct from array['client_change', 'client_id', 'generation', 'grant_id', 'instance_id', 'owner_sub', 'status']
+     or jsonb_typeof(v_claim -> 'instance_id') is distinct from 'string'
+     or (v_claim ->> 'instance_id') !~ '^[A-Za-z0-9_-]{16,128}$'
+     or jsonb_typeof(v_claim -> 'grant_id') is distinct from 'string'
+     or (v_claim ->> 'grant_id') !~ '^[A-Za-z0-9_-]{16,128}$'
+     or jsonb_typeof(v_claim -> 'generation') is distinct from 'number'
+     or (v_claim ->> 'generation') !~ '^[1-9][0-9]{0,15}$'
+     or jsonb_typeof(v_claim -> 'owner_sub') is distinct from 'string'
+     or (v_claim ->> 'owner_sub') is distinct from v_sub
+     or jsonb_typeof(v_claim -> 'client_id') is distinct from 'string'
+     or char_length(v_claim ->> 'client_id') not between 1 and 512
+     or jsonb_typeof(v_claim -> 'status') is distinct from 'string'
+     or (v_claim ->> 'status') not in ('active', 'revoked')
+     or jsonb_typeof(v_claim -> 'client_change') not in ('object', 'null') then
+    raise exception 'claims_malformed' using errcode = '22023';
+  end if;
+  v_generation := (v_claim ->> 'generation')::bigint;
+  if v_generation > 9007199254740991 then
+    raise exception 'claims_malformed' using errcode = '22023';
+  end if;
+  v_instance_id := v_claim ->> 'instance_id';
+  v_grant_id := v_claim ->> 'grant_id';
+  v_client_id := v_claim ->> 'client_id';
+
+  v_change := case when jsonb_typeof(v_claim -> 'client_change') = 'object' then v_claim -> 'client_change' end;
+  if v_change is not null then
+    if (select array_agg(k order by k) from jsonb_object_keys(v_change) k)
+         is distinct from array['confirmed_at', 'confirmed_generation', 'from_client_id']
+       or jsonb_typeof(v_change -> 'from_client_id') is distinct from 'string'
+       or jsonb_typeof(v_change -> 'confirmed_at') is distinct from 'number'
+       or (v_change ->> 'confirmed_at') !~ '^[0-9]{1,16}$'
+       or jsonb_typeof(v_change -> 'confirmed_generation') is distinct from 'number'
+       or (v_change ->> 'confirmed_generation') !~ '^[1-9][0-9]{0,15}$'
+       or (v_change ->> 'confirmed_generation')::bigint > 9007199254740991 then
+      raise exception 'claims_malformed' using errcode = '22023';
+    end if;
+    v_change_gen := (v_change ->> 'confirmed_generation')::bigint;
+  end if;
+
+  if v_slot is not null and v_slot !~ '^https://[^/?#@[:space:]]+(/[^?#[:space:]]*)?/s/[A-Za-z0-9_-]{22,64}$' then
+    raise exception 'claims_malformed' using errcode = '22023';
+  end if;
+
+  -- A token the Portal itself reports revoked is refused, and changes nothing here: only a
+  -- Portal revocation (tombstone_delegate_instance) tombstones.
+  if v_claim ->> 'status' <> 'active' then
+    raise exception 'instance_revoked' using errcode = '42501';
+  end if;
+
+  -- THE OWNER LOCK, before anything else. A transaction-scoped advisory lock keyed by the
+  -- owner's identity serialises every exchange of one owner: it is what serialises D13's count
+  -- below, and tombstone_delegate_instance takes it too, in the same position, so the order is
+  -- always: owner lock, then the owner's auth.users row, then the instance row. (HOSTED #591: "the
+  -- owner's auth.users row" in that order is the exchange's alone; the tombstone takes the owner
+  -- lock and then the instance row, and no auth.users row: section 3.) It was first added for the
+  -- owner-provisioning race (two first exchanges each creating an auth user for
+  -- one owner, measured by hosted_delegate_first_exchange_race); that class is now closed for
+  -- every caller inside _ensure_agent_auth_user itself (section 5), which this lock alone could
+  -- not do: a first human enroll never takes it.
+  --
+  -- THE OWNER, derived exactly as enroll_federated_human derives the human's auth user, from
+  -- the verified issuer and subject. The raw sub is never compared for identity.
+  -- HOSTED #591: it IS stored, on the instance row, as revocation evidence (section 1).
+  v_owner_slug := agent_board._federated_identity_slug(v_iss, v_sub);
+  perform pg_catalog.pg_advisory_xact_lock(pg_catalog.hashtextextended('agent_board.delegate_owner:' || v_owner_slug, 0));
+  v_owner := agent_board._ensure_agent_auth_user(v_owner_slug);
+
+  -- THE OWNER MUST BE LIVE (fix N2). enroll_federated_human refuses a durably revoked human
+  -- (fleet_human_revocations (iss, sub)) and a non-active human row, and so does this: a
+  -- revoked human whose Portal still signs tokens must not bring up a NEW delegate instance, and
+  -- a suspended owner's existing delegates must not keep exchanging. Refused owner_inactive,
+  -- before the instance row is touched (so it wins over every instance-level code, including a
+  -- tombstone), and nothing is tombstoned.
+  --
+  -- UNDER THE OWNER'S auth.users ROW LOCK, which revoke_human_subtree takes FOR UPDATE first and
+  -- holds while it writes the marker and revokes every agent it then lists. FOR KEY SHARE
+  -- conflicts with that and with nothing an ordinary auth.users update takes. Without it an
+  -- exchange reads the marker before the revocation commits, and the revocation's agent list
+  -- (read once, at its loop) misses the delegate this exchange creates: an active delegate of a
+  -- revoked human, or a fresh credential for a delegate the revocation just revoked
+  -- (hosted_delegate_owner_revoke_race). revoke_human_subtree never takes the owner advisory
+  -- lock or an instance row, so no cycle closes. revoke_agent (suspension) does not take this
+  -- row and does not touch delegate credentials; an exchange racing it is simply ordered before
+  -- it.
+  --
+  -- The owner's human row is the agents row whose auth_user_id is the owner uid
+  -- (idx_agent_board_agents_auth_user_id_unique: at most one), the row enroll_federated_human
+  -- creates. None is not a refusal: an owner the board has never enrolled as a human is allowed
+  -- here, as before (it cannot add a delegate to a board without a session of its own).
+  perform 1 from auth.users u where u.id = v_owner for key share;
+  if exists (
+       select 1 from agent_board.fleet_human_revocations r
+        where r.issuer = v_iss and r.subject = v_sub
+     )
+     or exists (
+       select 1 from agent_board.agents a
+        where a.auth_user_id = v_owner and a.status <> 'active'
+     ) then
+    raise exception 'owner_inactive' using errcode = '42501';
+  end if;
+
+  -- INSERT-THEN-LOCK. A bare `select ... for update` locks nothing when the row does not yet
+  -- exist, so two first exchanges would both create an agent. Inserting first makes the
+  -- second block on the primary key until the first commits; both then lock the same row.
+  -- HOSTED #591: the owner's verified (iss, sub), recorded with the row (section 1).
+  insert into agent_board.delegate_instances(instance_id, owner_user_id, owner_issuer, owner_subject)
+  values (v_instance_id, v_owner, v_iss, v_sub)
+  on conflict (instance_id) do nothing;
+
+  select * into v_row
+    from agent_board.delegate_instances di
+   where di.instance_id = v_instance_id
+   for update;
+
+  -- A tombstone is permanent, whatever else the token says.
+  if v_row.tombstoned_at is not null then
+    raise exception 'instance_revoked' using errcode = '42501';
+  end if;
+  if v_row.owner_user_id is distinct from v_owner then
+    raise exception 'owner_mismatch' using errcode = '42501';
+  end if;
+
+  -- FIRST EXCHANGE is decided UNDER the lock, by whether the row has an agent yet -- never by
+  -- whether this transaction's insert happened: the loser of two concurrent first exchanges
+  -- finds the winner's agent after it blocks, and takes the ordinary path.
+  v_first := v_row.agent_id is null;
+
+  if not v_first then
+    -- HOSTED #591: FOR KEY SHARE on the delegate's agents row, BEFORE any credential. This is the
+    -- lock the credential insert below takes anyway (its foreign key), moved ahead of the
+    -- credential UPDATE that revokes lower generations. Taken after the credentials, it made an
+    -- exchange that supersedes a generation deadlock against revoke_agent_subtree of the same
+    -- delegate, which takes the agents row FOR UPDATE and then the credentials
+    -- (hosted_delegate_exchange_agent_revoke_race). It conflicts with nothing it did not already
+    -- conflict with.
+    select a.status into v_status from agent_board.agents a where a.id = v_row.agent_id for key share;
+    if v_status is distinct from 'active' then
+      -- Revoked by revoke_agent_subtree or revoke_human_subtree, or suspended. Refused, and
+      -- NOT tombstoned: only a Portal revocation tombstones.
+      raise exception 'agent_inactive' using errcode = '42501';
+    end if;
+  else
+    -- D13: at most 20 live instances per owner. The owner lock taken at the top serialises two
+    -- first exchanges of DIFFERENT instances of one owner (their instance rows are different
+    -- rows), so the count cannot be passed twice.
+    select count(*) into v_live
+      from agent_board.delegate_instances di
+     where di.owner_user_id = v_owner
+       and di.tombstoned_at is null
+       and di.instance_id <> v_instance_id;
+    if v_live >= 20 then
+      raise exception 'instance_cap' using errcode = '42501';
+    end if;
+  end if;
+
+  -- THE RESOURCE (D8), S = the recorded slot_resource.
+  if not v_first then
+    if v_row.slot_resource is not null then
+      if v_slot is distinct from v_row.slot_resource then
+        raise exception 'resource_mismatch' using errcode = '42501';
+      end if;
+    elsif v_slot is not null and not (v_generation > v_row.generation) then
+      -- The one move, base URL -> slot, needs a new grant (a strictly higher generation).
+      raise exception 'resource_mismatch' using errcode = '42501';
+    end if;
+  end if;
+
+  -- THE CLIENT AND GENERATION, r = recorded generation, g = the token's, C = the recorded
+  -- client_change_generation.
+  if not v_first then
+    if v_generation < v_row.generation then
+      raise exception 'generation_superseded' using errcode = '42501';
+    elsif v_generation = v_row.generation then
+      if v_grant_id is distinct from v_row.grant_id then
+        raise exception 'grant_conflict' using errcode = '42501';
+      end if;
+      if v_client_id is distinct from v_row.client_id
+         or v_change_gen is distinct from v_row.client_change_generation then
+        raise exception 'client_mismatch' using errcode = '42501';
+      end if;
+    elsif v_client_id is distinct from v_row.client_id then
+      -- g > r from another client: only with the owner's confirmation of a client change made
+      -- AFTER the last binding the board saw (r < confirmed_generation <= g). from_client_id
+      -- is recorded for audit but not compared: the board may have missed an intermediate
+      -- reconnect.
+      if v_change_gen is null
+         or not (v_row.generation < v_change_gen and v_change_gen <= v_generation) then
+        raise exception 'client_mismatch' using errcode = '42501';
+      end if;
+    end if;
+  end if;
+
+  -- FIRST USE: the instance's own auth user and agents row. One auth user per instance.
+  if v_first then
+    v_slug := agent_board._delegate_instance_slug(v_iss, v_instance_id);
+    -- A second agent on this auth user is impossible: idx_agent_board_agents_auth_user_id_unique
+    -- refuses the insert (23505), and the whole exchange with it.
+    v_auth := agent_board._ensure_agent_auth_user(v_slug);
+    insert into agent_board.agents(
+      agent_type, kind, handle, display_name, status, auth_user_id, owner_user_id, is_delegate, metadata)
+    values (
+      'agent', 'agent', v_slug, 'Hosted assistant ' || left(v_instance_id, 8), 'active',
+      v_auth, v_owner, true,
+      jsonb_build_object('hosted_delegate', jsonb_build_object('instance_id', v_instance_id)))
+    returning id into v_agent;
+  else
+    v_agent := v_row.agent_id;
+    select a.auth_user_id into v_auth from agent_board.agents a where a.id = v_agent;
+  end if;
+
+  begin
+    update agent_board.delegate_instances di
+       set agent_id = v_agent,
+           client_id = v_client_id,
+           grant_id = v_grant_id,
+           generation = v_generation,
+           slot_resource = coalesce(di.slot_resource, v_slot),
+           client_change_generation = v_change_gen,
+           -- HOSTED #591: fills a legacy (pre-1.59.0) row's null pair; a recorded pair is kept.
+           -- Sound because owner_mismatch above proved this row's uid is the one (iss, sub)
+           -- derives.
+           owner_issuer = coalesce(di.owner_issuer, v_iss),
+           owner_subject = coalesce(di.owner_subject, v_sub),
+           updated_at = now()
+     where di.instance_id = v_instance_id;
+  exception when unique_violation then
+    -- D8: a slot belongs to one instance. Raising aborts the whole call, so nothing in this
+    -- transaction is kept.
+    raise exception 'slot_in_use' using errcode = '42501';
+  end;
+
+  -- A higher generation supersedes every lower one, in this transaction.
+  if not v_first and v_generation > v_row.generation then
+    update agent_board.agent_credentials ac
+       set revoked_at = now(),
+           updated_at = now(),
+           metadata = coalesce(ac.metadata, '{}'::jsonb)
+             || jsonb_build_object('revocationReason', 'generation_superseded', 'supersededByGeneration', v_generation)
+     where ac.agent_id = v_agent
+       and ac.revoked_at is null
+       and coalesce(ac.generation, 0) < v_generation;
+  end if;
+
+  -- The board credential row. No refresh token exists for it: the hash is random and never
+  -- disclosed, so the refresh path can never match it. expires_at <= now() + 900 s, and the
+  -- Edge Function mints exp = min(iat + 900, expires_at).
+  v_expires := now() + interval '900 seconds';
+  insert into agent_board.agent_credentials(
+    agent_id, refresh_token_hash, hash_version, credential_label, expires_at, metadata, grant_id, generation)
+  values (
+    v_agent,
+    extensions.digest(extensions.gen_random_bytes(32), 'sha256'),
+    1,
+    'hosted-delegate',
+    v_expires,
+    jsonb_build_object(
+      'source', 'exchange_delegate_credential',
+      'instance_id', v_instance_id,
+      'client_id', v_client_id,
+      'client_change', coalesce(v_change, 'null'::jsonb)),
+    v_grant_id,
+    v_generation)
+  returning id into v_credential;
+
+  return query select v_agent, v_auth, v_credential, v_expires;
+end;
+$fn$;
+
+revoke all on function agent_board.exchange_delegate_credential(jsonb) from public, anon, authenticated;
+grant execute on function agent_board.exchange_delegate_credential(jsonb) to service_role;
+
+comment on function agent_board.exchange_delegate_credential(jsonb) is
+  'HOSTED (IF-0-HOSTED-7): turns a verified Portal delegate access token into a board credential row, in one transaction: under the owner lock and the owner''s auth.users row (FOR KEY SHARE), refuse a durably revoked or non-active owner (owner_inactive); insert-then-lock the instance; refuse a tombstone, another owner, an inactive agent, a 21st live instance (D13), a resource other than the recorded one (D8), a lower generation, an equal generation with another grant, and a client change without the owner''s confirmation; create the agent and auth user on first use; revoke lower generations; issue a credential with expires_at <= now()+900s. Records the owner''s verified (iss, sub) on the instance as revocation evidence (AB15; filled once on a legacy row, never changed). Returns (agent_id, auth_user_id, credential_id, expires_at). service_role only; called by the delegate-exchange Edge Function after it verified the token and rate-limited (D9).';
+
+-- =============================================================================
+-- 3. tombstone_delegate_instance -- records (iss, sub); owner row and agent row first (#591
+--    items 4 and 8)
+-- =============================================================================
+create or replace function agent_board.tombstone_delegate_instance(
+  p_instance_id text, p_issuer text, p_owner_sub text, p_reason text)
+returns table(instance_id text, tombstoned_at timestamptz, first boolean)
+language plpgsql
+security definer
+set search_path = ''
+as $fn$
+#variable_conflict use_column
+declare
+  v_owner uuid;
+  v_owner_slug text;
+  v_inserted boolean;
+  v_row agent_board.delegate_instances%rowtype;
+  v_board uuid;
+begin
+  if not agent_board._is_service_role() then
+    raise exception 'tombstone_delegate_instance is service_role-only' using errcode = '42501';
+  end if;
+  if p_instance_id is null or p_instance_id !~ '^[A-Za-z0-9_-]{16,128}$'
+     or coalesce(p_issuer, '') = '' or coalesce(p_owner_sub, '') = ''
+     or p_reason is null
+     or p_reason not in ('owner_revoked', 'owner_retired_after_upgrade', 'owner_account_closed', 'portal_admin') then
+    raise exception 'revocation_malformed' using errcode = '22023';
+  end if;
+
+  -- The owner lock, then the owner, exactly as the exchange takes and derives them (same key,
+  -- same position: before the instance row), so a revocation and an exchange of a new owner's
+  -- instance never provision two auth users for one owner.
+  v_owner_slug := agent_board._federated_identity_slug(p_issuer, p_owner_sub);
+  perform pg_catalog.pg_advisory_xact_lock(pg_catalog.hashtextextended('agent_board.delegate_owner:' || v_owner_slug, 0));
+  v_owner := agent_board._ensure_agent_auth_user(v_owner_slug);
+
+  -- HOSTED #591: NO auth.users ROW LOCK here, deliberately, unlike the exchange. This function
+  -- reaches boards (update_board_membership below writes board_membership_events, whose foreign
+  -- key takes FOR KEY SHARE on the board), and every route that locks both a board and an owner
+  -- row must take the board first (agent_board_federated_lock_order_class EC-3):
+  -- enroll_federated_human holds its default board FOR UPDATE and then wants the owner's row FOR
+  -- UPDATE, so an owner-row lock taken here first closes a cycle with it. The deadlock against
+  -- revoke_human_subtree (#591 item 8) is closed by the agents-row order below instead
+  -- (hosted_delegate_tombstone_revoke_race P1, P2). What the owner-row lock would have added is
+  -- stated in AB15: see revoke_human_subtree (section 4).
+
+  -- A revocation BEFORE the first exchange creates the tombstoned row, so the first exchange
+  -- is refused. Insert-then-lock, as the exchange does, so a concurrent exchange serialises.
+  -- HOSTED #591: with the owner's verified (iss, sub) (section 1).
+  insert into agent_board.delegate_instances as di(
+    instance_id, owner_user_id, owner_issuer, owner_subject, tombstoned_at, tombstone_reason)
+  values (p_instance_id, v_owner, p_issuer, p_owner_sub, now(), p_reason)
+  on conflict (instance_id) do nothing
+  returning true into v_inserted;
+
+  if v_inserted then
+    return query select p_instance_id, now(), true;
+    return;
+  end if;
+
+  select * into v_row
+    from agent_board.delegate_instances di
+   where di.instance_id = p_instance_id
+   for update;
+
+  if v_row.owner_user_id is distinct from v_owner then
+    raise exception 'owner_mismatch' using errcode = '42501';
+  end if;
+
+  -- Idempotent: the key is the instance, and a tombstone is permanent.
+  if v_row.tombstoned_at is not null then
+    -- HOSTED #591: a legacy (pre-1.59.0) tombstoned row has no owner pair, and nothing else ever
+    -- writes it again: the exchange refuses it (instance_revoked) before its UPDATE. So a repeated
+    -- revocation fills the pair here, and nothing else about the row changes. Sound for the same
+    -- reason as the fill below: owner_mismatch above proved this row's uid is the one
+    -- (p_issuer, p_owner_sub) derives. A recorded pair is never touched (the trigger refuses).
+    if v_row.owner_issuer is null then
+      update agent_board.delegate_instances di
+         set owner_issuer = p_issuer,
+             owner_subject = p_owner_sub
+       where di.instance_id = p_instance_id;
+    end if;
+    return query select v_row.instance_id, v_row.tombstoned_at, false;
+    return;
+  end if;
+
+  update agent_board.delegate_instances di
+     set tombstoned_at = now(),
+         tombstone_reason = p_reason,
+         -- HOSTED #591: fills a legacy row's null pair; sound because owner_mismatch above
+         -- proved this row's uid is the one (p_issuer, p_owner_sub) derives.
+         owner_issuer = coalesce(di.owner_issuer, p_issuer),
+         owner_subject = coalesce(di.owner_subject, p_owner_sub),
+         updated_at = now()
+   where di.instance_id = p_instance_id;
+
+  if v_row.agent_id is not null then
+    -- HOSTED #591 (item 8): THE DELEGATE'S agents ROW FIRST, before any credential. Every other
+    -- writer of a delegate's agents row and its credentials takes the agents row first
+    -- (_revoke_agent_principal, for revoke_agent_subtree and revoke_human_subtree: FOR UPDATE,
+    -- then credentials; revoke_agent: its UPDATE, then credentials). This UPDATE used to come
+    -- last, after the credentials and the memberships, so either subtree revoker interleaved
+    -- with a tombstone of the same delegate deadlocked (hosted_delegate_tombstone_revoke_race
+    -- P1, P2). It is the same statement and the same FOR NO KEY UPDATE lock the 1.58.0 function
+    -- took, moved ahead; it adds no lock. FOR NO KEY UPDATE does not block the FOR KEY SHARE of a
+    -- foreign-key check, so add_delegate_to_board's sink insert is not newly blocked (the two
+    -- already serialise on the instance row above). An agent already revoked and committed is
+    -- not matched and not locked; its revoker has finished, so there is nothing to order against.
+    update agent_board.agents a
+       set status = 'revoked', updated_at = now()
+     where a.id = v_row.agent_id
+       and a.status <> 'revoked';
+
+    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('revocationReason', 'instance_tombstoned', 'tombstoneReason', p_reason)
+     where ac.agent_id = v_row.agent_id
+       and ac.revoked_at is null;
+
+    -- Every active membership ends through update_board_membership(..., 'left') under
+    -- service_role, so each ends with an append-only operator_removal event.
+    for v_board in
+      select bm.board_id
+        from agent_board.board_memberships bm
+       where bm.agent_id = v_row.agent_id
+         and bm.membership_state in ('joined', 'subscribed')
+       order by bm.board_id
+    loop
+      perform agent_board.update_board_membership(v_board, v_row.agent_id, 'left');
+    end loop;
+  end if;
+
+  return query select p_instance_id, now(), true;
+end;
+$fn$;
+
+revoke all on function agent_board.tombstone_delegate_instance(text, text, text, text) from public, anon, authenticated;
+grant execute on function agent_board.tombstone_delegate_instance(text, text, text, text) to service_role;
+
+comment on function agent_board.tombstone_delegate_instance(text, text, text, text) is
+  'HOSTED (IF-0-HOSTED-8, D10): tombstones a hosted delegate instance, idempotently and permanently. Before the first exchange it creates the tombstoned row; otherwise, in one transaction, it revokes every credential, ends every active membership through update_board_membership(..., ''left'') (operator_removal events) and moves the agent to revoked. A revocation naming an existing instance of another owner raises owner_mismatch. Lock order (AB15): the owner advisory lock, the instance row FOR UPDATE, the delegate''s agents row (its status UPDATE, FOR NO KEY UPDATE), then credentials and memberships; no auth.users row lock, because it reaches boards (board before owner, EC-3). Records the owner''s verified (iss, sub) on the instance as revocation evidence, filling a legacy row''s null pair on any call, including a repeat of an existing tombstone (which otherwise changes nothing). Returns (instance_id, tombstoned_at, first). service_role only; called by the delegate-revoke Edge Function with the verified revocation JWT''s iss, owner_sub and reason.';
+
+-- =============================================================================
+-- 4. revoke_human_subtree -- a marker from every recorded delegate owner identity (#591 item 4)
+-- =============================================================================
+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;
+
+  -- HOSTED #591 (item 4): the markers come from TWO kinds of verified evidence: the federated
+  -- enrollment audit of an agent the human owns, and the owner (iss, sub) a hosted delegate
+  -- instance of this human recorded from the Portal token that created or last wrote it. An
+  -- owner whose only principals are hosted delegates has none of the first, and before this
+  -- got no marker, so a fresh first exchange passed owner_inactive after the revocation. The
+  -- instance rows are read unlocked. An exchange that creates one holds this owner's auth.users
+  -- row FOR KEY SHARE, which the FOR UPDATE above excludes. A tombstone does not (it reaches
+  -- boards, so it may not lock the owner first: section 3), so a pre-exchange tombstone that
+  -- commits after this read records a pair this revocation does not see. That misses a marker
+  -- only when nothing else gives one: the owner has no audit row, no human agents row (which
+  -- the loop below revokes, and which the exchange's owner_inactive reads), and no earlier
+  -- instance row with a pair -- i.e. its only evidence is pre-1.59.0 (AB15). A legacy instance
+  -- with no recorded pair gives nothing, and does NOT gate the revocation as missing audit
+  -- evidence does: refusing would leave that owner unrevocable, since only an exchange or a
+  -- tombstone call can fill the pair (AB15). A pair filled after this revocation commits marks
+  -- nothing: markers are written here only.
+  insert into agent_board.fleet_human_revocations(
+    issuer, subject, owner_user_id, revoked_by_agent_id, revocation_reason
+  )
+  select distinct
+    ev.issuer,
+    ev.subject,
+    p_owner_user_id, p_revoked_by_agent_id, p_reason
+    from (
+      select e.issuer, e.subject
+        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
+      union all
+      select di.owner_issuer, di.owner_subject
+        from agent_board.delegate_instances di
+       where di.owner_user_id = p_owner_user_id
+         and di.owner_issuer is not null
+    ) ev
+  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 from that audit evidence and from the owner (iss, sub) each of the human''s hosted delegate instances recorded (HOSTED #591, AB15; a legacy instance with none gives no marker and does not gate); 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;