@consiliency/agent-board-schema 1.2.0 → 1.4.0

package/migrations/20260718001000_agent_board_delegation_enforcement.sql

@@ -0,0 +1,296 @@
+-- MBDELEG SL-1 (IF-0-MBDELEG-2): per-child delegation grant table + bounded
+-- root-minted spinoff RPCs.
+--
+-- Additive, forward-only. First consumer of delegation_policies (20260717000400).
+--
+-- Scope model (FROZEN): a root's scope IS delegation_policies.allowed_scopes (the
+-- only machine-readable scope a root carries). allowed_scopes / granted_scopes are
+-- JSON ARRAYS; "child scope ⊆ root scope" is exactly the jsonb array-containment
+-- check `allowed_scopes @> requested_scopes`.
+--
+-- Two clocks: delegation_grants.grant_expires_at is the HOURS-SCALE working/grant
+-- clock (bounded by delegation_policies.child_ttl_ceiling), distinct from the
+-- <=900s fleet_agent_session token clock minted by mint_fleet_agent_session.
+--
+-- independent_auth is the default mode and opts out of ALL of the below: an
+-- independent_auth subagent is provisioned lineage-independent (parent_agent_id and
+-- root_agent_id NULL, sharing only owner_user_id), holds no delegation_grants row,
+-- and enrolls its own key + PoP. Because it carries no parent, _agent_principal_active
+-- reduces to its own status='active' on the up-walk, so it survives any other
+-- agent's/root's revocation. Only mint_delegated_child (root_minted) rows are
+-- created here.
+
+-- 1. delegation_grants (per-child) -------------------------------------------
+create table if not exists agent_board.delegation_grants (
+  id uuid primary key default gen_random_uuid(),
+  child_agent_id uuid not null unique references agent_board.agents(id) on delete cascade,
+  root_agent_id uuid not null references agent_board.agents(id) on delete cascade,
+  parent_agent_id uuid not null references agent_board.agents(id),
+  delegation_policy_id uuid not null references agent_board.delegation_policies(id),
+  granted_scopes jsonb not null,
+  -- Hours-scale working/grant clock, bounded by delegation_policies.child_ttl_ceiling.
+  grant_expires_at timestamptz not null,
+  last_renewed_at timestamptz,
+  revoked_at timestamptz,
+  created_at timestamptz not null default now()
+);
+
+comment on table agent_board.delegation_grants is
+  'Per-child root-minted delegation grant. grant_expires_at is the hours-scale working clock (<= root policy child_ttl_ceiling), distinct from the <=900s session-token clock. independent_auth children hold NO row here.';
+
+create index if not exists idx_agent_board_delegation_grants_root
+  on agent_board.delegation_grants(root_agent_id)
+  where revoked_at is null;
+
+alter table agent_board.delegation_grants enable row level security;
+
+drop policy if exists agent_board_authenticated_select_delegation_grants on agent_board.delegation_grants;
+create policy agent_board_authenticated_select_delegation_grants
+on agent_board.delegation_grants
+as permissive
+for select
+to authenticated
+using (root_agent_id = agent_board.current_agent_id());
+
+grant select on agent_board.delegation_grants to authenticated;
+grant select, insert, update on agent_board.delegation_grants to service_role;
+
+-- 2. mint_delegated_child ----------------------------------------------------
+-- service_role-only. Mints a bounded root_minted child ONLY when: the root's
+-- delegation_policies row exists, is unrevoked, and mode='root_minted'; the root
+-- principal is active; requested scopes ⊆ allowed_scopes; the root is a TRUE
+-- lineage root (parent_agent_id NULL and holds no delegation_grants row of its own
+-- => max_depth=1, no transitive minting); and max_active_children is not exceeded.
+-- Provisions the child (parent = root = p_root_agent_id, same owner_user_id, own
+-- auth binding), enrolls a scoped ephemeral REVOCABLE signing key when the policy
+-- requires it, and inserts a delegation_grants row with a ceiling-bounded
+-- grant_expires_at.
+create or replace function agent_board.mint_delegated_child(
+  p_root_agent_id uuid,
+  p_child_slug text,
+  p_requested_scopes jsonb,
+  p_child_public_key text default null,
+  p_ttl interval default null
+)
+returns table(
+  child_agent_id uuid,
+  grant_expires_at timestamptz,
+  signing_key_id uuid
+)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_policy agent_board.delegation_policies%rowtype;
+  v_root agent_board.agents%rowtype;
+  v_slug text;
+  v_requested jsonb := coalesce(p_requested_scopes, '[]'::jsonb);
+  v_allowed jsonb;
+  v_active_children int;
+  v_child_auth_user_id uuid;
+  v_child_id uuid;
+  v_key_id uuid := null;
+  v_grant_expires_at timestamptz;
+begin
+  if not agent_board._is_service_role() then
+    raise exception 'mint_delegated_child is service_role-only' using errcode = '42501';
+  end if;
+
+  v_slug := agent_board._normalize_provision_slug(p_child_slug);
+
+  -- Root must exist.
+  select * into v_root from agent_board.agents where id = p_root_agent_id;
+  if not found then
+    raise exception 'root agent not found' using errcode = 'P0002';
+  end if;
+
+  -- Root policy must exist, be unrevoked, and be root_minted. #11: take a row lock
+  -- on the policy up front so a concurrent mint against the same root serializes
+  -- here — the max_active_children count->insert below cannot then be raced past
+  -- the ceiling (TOCTOU close).
+  select * into v_policy
+    from agent_board.delegation_policies dp
+   where dp.root_agent_id = p_root_agent_id
+     and dp.revoked_at is null
+   order by dp.created_at desc
+   limit 1
+   for update;
+  if not found then
+    raise exception 'no active delegation policy for root agent' using errcode = '42501';
+  end if;
+  if v_policy.mode <> 'root_minted' then
+    raise exception 'delegation policy mode is not root_minted (independent_auth children self-provision)' using errcode = '42501';
+  end if;
+
+  -- Root principal must be active (self + lineage).
+  if not agent_board._agent_principal_active(p_root_agent_id) then
+    raise exception 'principal_inactive: root agent principal is not fully active' using errcode = '42501';
+  end if;
+
+  -- max_depth = 1 / no transitive minting: p_root_agent_id must be a TRUE lineage
+  -- root (unparented) and must not itself be a delegated child.
+  if v_root.parent_agent_id is not null then
+    raise exception 'max_depth: only a true lineage root may mint (no transitive delegation)' using errcode = '42501';
+  end if;
+  if exists (select 1 from agent_board.delegation_grants g where g.child_agent_id = p_root_agent_id) then
+    raise exception 'max_depth: a delegated child may not mint further children' using errcode = '42501';
+  end if;
+
+  -- Scope subset: requested ⊆ allowed (JSON array containment). A NULL allowed_scopes
+  -- means the root carries no delegable scope, so only an empty request is a subset.
+  v_allowed := coalesce(v_policy.allowed_scopes, '[]'::jsonb);
+  if not (v_allowed @> v_requested) then
+    raise exception 'scope_exceeded: requested scopes are not a subset of the root allowed_scopes' using errcode = '42501';
+  end if;
+
+  -- max_active_children: when set, the root's live (non-revoked, unexpired) grant
+  -- count must remain <= max_active_children after this mint.
+  if v_policy.max_active_children is not null then
+    select count(*) into v_active_children
+      from agent_board.delegation_grants g
+     where g.root_agent_id = p_root_agent_id
+       and g.revoked_at is null
+       and g.grant_expires_at > now();
+    if v_active_children >= v_policy.max_active_children then
+      raise exception 'max_active_children: root has reached its active delegated-child ceiling' using errcode = '42501';
+    end if;
+  end if;
+
+  -- Provision the child: parent = root = p_root_agent_id, same owner_user_id, own
+  -- auth binding (distinct auth_user_id for the active-unique index).
+  v_child_auth_user_id := 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, parent_agent_id, root_agent_id, metadata
+  )
+  values (
+    'agent', 'agent'::agent_board.agent_kind, v_slug,
+    agent_board._default_provision_display_name(v_slug), 'active',
+    v_child_auth_user_id, v_root.owner_user_id, p_root_agent_id, p_root_agent_id,
+    jsonb_build_object('delegatedByRootAgentId', p_root_agent_id, 'grantedScopes', v_requested)
+  )
+  returning id into v_child_id;
+
+  -- Scoped REVOCABLE signing key when the policy requires it. #5: the child's
+  -- public key MUST be supplied by the caller (generated client-side; the private
+  -- key never touches the DB). We NEVER seed a placeholder/zero key and NEVER
+  -- generate a key in-DB. status='active' + proof_state='proven' so the child can
+  -- immediately re-sign with the private key it already holds. The fingerprint is
+  -- derived deterministically from the supplied public key.
+  if v_policy.require_child_signing_key then
+    if p_child_public_key is null then
+      raise exception 'a child public key is required when the delegation policy requires a signing key' using errcode = '22023';
+    end if;
+    -- Raw Ed25519 public keys are 32 bytes => 43 base64url chars (no padding).
+    if p_child_public_key !~ '^[A-Za-z0-9_-]{43}$' then
+      raise exception 'malformed child public key: expected a 43-char base64url raw Ed25519 key' using errcode = '22023';
+    end if;
+    -- Reject the all-''A'' key: 43 base64url ''A''s decode to 32 zero bytes (a
+    -- small-order point), which is exactly the retired placeholder.
+    if p_child_public_key = repeat('A', 43) then
+      raise exception 'child public key is the all-zero small-order placeholder and is rejected' using errcode = '22023';
+    end if;
+
+    insert into agent_board.agent_signing_keys(
+      id, agent_id, key_id, key_version, public_key, public_key_format, fingerprint,
+      status, proof_state, metadata
+    )
+    values (
+      gen_random_uuid(), v_child_id, 'delegated-ephemeral', 1, p_child_public_key,
+      'raw_ed25519_base64url',
+      'sha256:' || rtrim(translate(encode(extensions.digest(convert_to(p_child_public_key, 'UTF8'), 'sha256'), 'base64'), '+/', '-_'), '='),
+      'active', 'proven',
+      jsonb_build_object('ephemeral', true, 'scopes', v_requested)
+    )
+    returning id into v_key_id;
+  end if;
+
+  -- Grant row: ceiling-bounded hours-scale working clock.
+  v_grant_expires_at := now() + least(coalesce(p_ttl, v_policy.child_ttl_ceiling), v_policy.child_ttl_ceiling);
+
+  insert into agent_board.delegation_grants(
+    child_agent_id, root_agent_id, parent_agent_id, delegation_policy_id,
+    granted_scopes, grant_expires_at
+  )
+  values (
+    v_child_id, p_root_agent_id, p_root_agent_id, v_policy.id,
+    v_requested, v_grant_expires_at
+  );
+
+  return query select v_child_id, v_grant_expires_at, v_key_id;
+end;
+$$;
+
+comment on function agent_board.mint_delegated_child(uuid, text, jsonb, text, interval) is
+  'Mints a bounded root_minted delegated child (scope ⊆ root allowed_scopes, max_depth=1, policy-row-locked max_active_children, ceiling-bounded grant TTL) enrolling the CALLER-SUPPLIED Ed25519 public key (never a placeholder; private key stays client-side) as a revocable signing key. service_role-only.';
+
+revoke all on function agent_board.mint_delegated_child(uuid, text, jsonb, text, interval) from public, anon, authenticated;
+grant execute on function agent_board.mint_delegated_child(uuid, text, jsonb, text, interval) to service_role;
+
+-- 3. renew_delegated_grant ---------------------------------------------------
+-- service_role-only. Extends grant_expires_at to now() + least(coalesce(p_extend,
+-- child_ttl_ceiling), child_ttl_ceiling) ONLY while the root principal is active,
+-- the root policy is unrevoked, and the grant is unrevoked. A revoked/inactive root
+-- => renewal raises, so the grant can never outlive the root's authority.
+create or replace function agent_board.renew_delegated_grant(
+  p_child_agent_id uuid,
+  p_extend interval default null
+)
+returns table(
+  grant_expires_at timestamptz
+)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_grant agent_board.delegation_grants%rowtype;
+  v_policy agent_board.delegation_policies%rowtype;
+  v_new_expires_at timestamptz;
+begin
+  if not agent_board._is_service_role() then
+    raise exception 'renew_delegated_grant is service_role-only' using errcode = '42501';
+  end if;
+
+  select * into v_grant
+    from agent_board.delegation_grants g
+   where g.child_agent_id = p_child_agent_id
+   for update;
+  if not found then
+    raise exception 'delegation grant not found for child' using errcode = 'P0002';
+  end if;
+  if v_grant.revoked_at is not null then
+    raise exception 'grant_revoked: cannot renew a revoked delegation grant' using errcode = '42501';
+  end if;
+
+  select * into v_policy
+    from agent_board.delegation_policies dp
+   where dp.id = v_grant.delegation_policy_id;
+  if not found or v_policy.revoked_at is not null then
+    raise exception 'policy_revoked: the root delegation policy is revoked' using errcode = '42501';
+  end if;
+
+  -- The operational meaning of "<= root's remaining authority": a revoked/inactive
+  -- root makes _agent_principal_active(root) false, so renewal raises.
+  if not agent_board._agent_principal_active(v_grant.root_agent_id) then
+    raise exception 'principal_inactive: root agent principal is not active; grant cannot outlive its root' using errcode = '42501';
+  end if;
+
+  v_new_expires_at := now() + least(coalesce(p_extend, v_policy.child_ttl_ceiling), v_policy.child_ttl_ceiling);
+
+  update agent_board.delegation_grants
+     set grant_expires_at = v_new_expires_at,
+         last_renewed_at = now()
+   where child_agent_id = p_child_agent_id;
+
+  return query select v_new_expires_at;
+end;
+$$;
+
+comment on function agent_board.renew_delegated_grant(uuid, interval) is
+  'Extends a child grant''s hours-scale grant_expires_at only while the root principal is active and unrevoked; raises otherwise so a grant cannot outlive the root''s authority. service_role-only.';
+
+revoke all on function agent_board.renew_delegated_grant(uuid, interval) from public, anon, authenticated;
+grant execute on function agent_board.renew_delegated_grant(uuid, interval) to service_role;

package/migrations/20260718001100_agent_board_revoke_agent_subtree.sql

@@ -0,0 +1,238 @@
+-- MBDELEG SL-1 (IF-0-MBDELEG-3): refresh-checked subtree revocation cascade.
+--
+-- Additive, forward-only. Net-new. Requires the 'revoked' agents.status literal
+-- from 20260718000900 (this file writes agents.status='revoked').
+--
+-- Two cascades share one per-principal primitive, _revoke_agent_principal:
+--   * revoke_agent_subtree(root) walks DOWN the grant-derived lineage (the root
+--     itself + every descendant that holds a delegation_grants row). This is the
+--     OPPOSITE direction to _agent_principal_active (20260718000500), which walks UP
+--     to ancestors — do not invert either. Because independent_auth principals carry
+--     NULL parent_agent_id and hold no grant row, they are structurally NOT
+--     descendants of any root and are never in this set: they survive a root/parent
+--     revocation and are killed only by a self-revoke or by revoke_human_subtree.
+--   * revoke_human_subtree(owner) is TOTAL for the human: it resolves EVERY agent
+--     owned by owner_user_id (all lineage roots AND every lineage-independent
+--     independent_auth principal) and revokes each. It is deliberately broader than
+--     revoke_agent_subtree because current_agent_id() joins on the agent's own
+--     auth_user_id, so disabling the human's auth.users row alone flips no agent.
+--
+-- Per revoked principal, in one transaction: flip every non-revoked signing key to
+-- status='revoked'/proof_state='revoked' (revoked_at=now()), flip agents.status to
+-- 'revoked', revoke any live delegation_grants row, and append fleet_revocation_events
+-- rows (subject_kind='agent' per principal, 'signing_key' per key) FOR AUDIT ONLY —
+-- no refresh/send path reads that ledger, so a ledger row alone is inert. The kill is
+-- delivered by the key + status flips: the next <=15-min mint_fleet_agent_session
+-- re-mint FAILS (revoked key => 42501; non-active status => _agent_principal_active
+-- false), so the subtree dies within one token TTL even though its grant lifetime was
+-- hours.
+
+-- Per-principal revocation primitive. Returns the number of signing keys it flipped.
+create or replace function agent_board._revoke_agent_principal(
+  p_agent_id uuid,
+  p_revoked_by_agent_id uuid,
+  p_reason text
+)
+returns integer
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_key record;
+  v_key_count integer := 0;
+  v_agent_flipped boolean := false;
+begin
+  -- Flip every live signing key + emit a signing_key audit row per key.
+  for v_key in
+    select id
+      from agent_board.agent_signing_keys
+     where agent_id = p_agent_id
+       and status not in ('revoked', 'compromised')
+     for update
+  loop
+    update agent_board.agent_signing_keys
+       set status = 'revoked',
+           proof_state = 'revoked',
+           revoked_at = now(),
+           revoked_by_agent_id = p_revoked_by_agent_id,
+           revocation_reason = p_reason,
+           updated_at = now()
+     where id = v_key.id;
+
+    insert into agent_board.fleet_revocation_events(
+      subject_kind, subject_id, signing_key_id, agent_id,
+      revoked_by_agent_id, revocation_reason, metadata
+    )
+    values (
+      'signing_key', v_key.id, v_key.id, p_agent_id,
+      p_revoked_by_agent_id, p_reason,
+      jsonb_build_object('source', 'revoke_agent_subtree')
+    )
+    on conflict (subject_kind, subject_id) do update
+      set revoked_by_agent_id = excluded.revoked_by_agent_id,
+          revocation_reason = excluded.revocation_reason,
+          signing_key_id = excluded.signing_key_id,
+          agent_id = excluded.agent_id,
+          effective_at = now(),
+          metadata = excluded.metadata;
+
+    v_key_count := v_key_count + 1;
+  end loop;
+
+  -- Flip the agent status (idempotent: only count a genuine active->revoked flip).
+  update agent_board.agents
+     set status = 'revoked',
+         updated_at = now()
+   where id = p_agent_id
+     and status <> 'revoked';
+  if found then
+    v_agent_flipped := true;
+  end if;
+
+  -- Revoke any live grant this principal holds as a child.
+  update agent_board.delegation_grants
+     set revoked_at = now()
+   where child_agent_id = p_agent_id
+     and revoked_at is null;
+
+  -- Also revoke the principal's legacy agent_credentials (mirrors revoke_agent in
+  -- 20260512000000). Without this, a later status flip-back would re-open the
+  -- refresh-token credential path that the key/status flips did not touch.
+  update agent_board.agent_credentials ac
+     set revoked_at = coalesce(ac.revoked_at, now()),
+         updated_at = now(),
+         metadata = coalesce(ac.metadata, '{}'::jsonb)
+           || jsonb_build_object(
+             'revokedByAgentId', p_revoked_by_agent_id,
+             'revocationReason', p_reason,
+             'source', 'revoke_agent_subtree'
+           )
+   where ac.agent_id = p_agent_id
+     and ac.revoked_at is null;
+
+  -- Audit row for the principal itself.
+  insert into agent_board.fleet_revocation_events(
+    subject_kind, subject_id, agent_id,
+    revoked_by_agent_id, revocation_reason, metadata
+  )
+  values (
+    'agent', p_agent_id, p_agent_id,
+    p_revoked_by_agent_id, p_reason,
+    jsonb_build_object('source', 'revoke_agent_subtree', 'statusFlipped', v_agent_flipped)
+  )
+  on conflict (subject_kind, subject_id) do update
+    set revoked_by_agent_id = excluded.revoked_by_agent_id,
+        revocation_reason = excluded.revocation_reason,
+        agent_id = excluded.agent_id,
+        effective_at = now(),
+        metadata = excluded.metadata;
+
+  return v_key_count;
+end;
+$$;
+
+comment on function agent_board._revoke_agent_principal(uuid, uuid, text) is
+  'Per-principal revocation primitive: flips all live signing keys + agents.status to revoked, revokes any child grant, appends audit-only fleet_revocation_events. Shared by revoke_agent_subtree and revoke_human_subtree.';
+
+revoke all on function agent_board._revoke_agent_principal(uuid, uuid, text) from public, anon, authenticated;
+grant execute on function agent_board._revoke_agent_principal(uuid, uuid, text) to service_role;
+
+-- revoke_agent_subtree: DOWN-walking grant-derived cascade from a root.
+create or replace function agent_board.revoke_agent_subtree(
+  p_root_agent_id uuid,
+  p_revoked_by_agent_id uuid,
+  p_reason text default 'root revocation'
+)
+returns table(
+  revoked_agent_count integer,
+  revoked_key_count integer
+)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_agent uuid;
+  v_agent_count integer := 0;
+  v_key_count integer := 0;
+begin
+  if not agent_board._is_service_role() then
+    raise exception 'revoke_agent_subtree is service_role-only' using errcode = '42501';
+  end if;
+
+  if not exists (select 1 from agent_board.agents where id = p_root_agent_id) then
+    raise exception 'root agent not found' using errcode = 'P0002';
+  end if;
+
+  -- DOWN walk: the root itself (the revocation target) plus every descendant whose
+  -- authority derives from the root (it holds a delegation_grants row parented at a
+  -- member of the set). Recurses child.parent_agent_id -> parent.id via the grant
+  -- table, so lineage-independent independent_auth principals (no grant row) are
+  -- never reached.
+  for v_agent in
+    with recursive subtree(agent_id) as (
+      select p_root_agent_id
+      union
+      select g.child_agent_id
+        from agent_board.delegation_grants g
+        join subtree s on g.parent_agent_id = s.agent_id
+    )
+    select agent_id from subtree
+  loop
+    v_key_count := v_key_count + agent_board._revoke_agent_principal(v_agent, p_revoked_by_agent_id, p_reason);
+    v_agent_count := v_agent_count + 1;
+  end loop;
+
+  return query select v_agent_count, v_key_count;
+end;
+$$;
+
+comment on function agent_board.revoke_agent_subtree(uuid, uuid, text) is
+  'DOWN-walking refresh-checked cascade: revokes a root and every grant-derived descendant (keys + agents.status + grants + audit rows). independent_auth principals are structurally excluded (NULL lineage / no grant). service_role-only.';
+
+revoke all on function agent_board.revoke_agent_subtree(uuid, uuid, text) from public, anon, authenticated;
+grant execute on function agent_board.revoke_agent_subtree(uuid, uuid, text) to service_role;
+
+-- revoke_human_subtree: TOTAL for the human — every principal owned by owner_user_id.
+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;
+
+  -- Total human revocation: every agent owned by this human — lineage roots,
+  -- their delegated descendants, AND every lineage-independent independent_auth
+  -- principal — because current_agent_id() joins on the agent's own auth_user_id.
+  for v_agent in
+    select id from agent_board.agents where owner_user_id = p_owner_user_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: revokes every agent owned by owner_user_id (lineage roots AND lineage-independent independent_auth principals). Broader than revoke_agent_subtree. 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;

package/migrations/20260718001200_agent_board_resigning_refresh.sql

@@ -0,0 +1,129 @@
+-- MBDELEG SL-2 (IF-0-MBDELEG-4): re-signing refresh; demote the 30-day
+-- agent_credentials refresh token to an enrollment/lineage record.
+--
+-- Additive, forward-only. Redefines two existing functions via CREATE OR REPLACE in
+-- this NEW file — no released historical bytes are edited:
+--
+--   * rotate_agent_token(uuid) — the 30-day session-exchange RPC — now RAISES a
+--     deprecation error (0A000). Session refresh is SOLELY re-signing through the
+--     already-built PoP -> mint_fleet_agent_session loop (MBSESSION, 20260718000600).
+--     The RETURNS-TABLE signature is preserved (CREATE OR REPLACE cannot change it),
+--     but the body raises before returning any row.
+--
+--   * _issue_agent_credential(...) — the single choke point every issuer funnels
+--     through (provision_agent still routes here) — now tags every minted credential
+--     with metadata.credential_role = 'enrollment', demoting it to an
+--     enrollment/lineage record: it is NO LONGER a session-exchangeable refresh token
+--     (the only exchange RPC, rotate_agent_token, now raises). The body is carried
+--     forward from the latest definition (20260711000000 system-principal fail-closed
+--     guard) so that guard is preserved.
+--
+-- Maintainer decision (recommended, surfaced in the closeout): demotion mechanism is
+-- raise-on-exchange (rotate_agent_token) + enrollment-only reissue
+-- (_issue_agent_credential), rather than dropping the column/table.
+
+-- 1. _issue_agent_credential: preserve system-principal fail-closed guard, tag
+--    every credential as an enrollment/lineage record.
+create or replace function agent_board._issue_agent_credential(
+  p_agent_id uuid,
+  p_credential_label text,
+  p_replaces_credential_id uuid default null,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(
+  credential_id uuid,
+  refresh_token text,
+  expires_at timestamptz,
+  created_at timestamptz,
+  replaces_credential_id uuid
+)
+language plpgsql
+security definer
+set search_path = ''
+as $$
+declare
+  v_refresh_token text;
+  v_expires_at timestamptz := now() + interval '30 days';
+  v_created_at timestamptz := now();
+  v_credential_id uuid;
+begin
+  -- Fail closed for system principals (carried forward from 20260711000000): they
+  -- have no auth binding, so any credential minted here is un-exchangeable.
+  if exists (
+    select 1
+      from agent_board.agents a
+     where a.id = p_agent_id
+       and a.kind = 'system'::agent_board.agent_kind
+  ) then
+    raise exception 'cannot issue an exchangeable credential for a system principal (no auth binding)'
+      using errcode = '22023';
+  end if;
+
+  v_refresh_token := agent_board._mint_agent_refresh_token();
+
+  insert into agent_board.agent_credentials(
+    agent_id,
+    refresh_token_hash,
+    hash_version,
+    credential_label,
+    expires_at,
+    replaces_credential_id,
+    metadata,
+    created_at,
+    updated_at
+  )
+  values (
+    p_agent_id,
+    extensions.digest(v_refresh_token, 'sha256'),
+    1,
+    p_credential_label,
+    v_expires_at,
+    p_replaces_credential_id,
+    -- MBDELEG: demote to an enrollment/lineage record. No session is exchangeable
+    -- from it (rotate_agent_token now raises).
+    coalesce(p_metadata, '{}'::jsonb) || jsonb_build_object('credential_role', 'enrollment'),
+    v_created_at,
+    v_created_at
+  )
+  returning id into v_credential_id;
+
+  if p_replaces_credential_id is not null then
+    update agent_board.agent_credentials
+       set revoked_at = coalesce(revoked_at, v_created_at),
+           rotated_at = coalesce(rotated_at, v_created_at),
+           replaced_by_credential_id = v_credential_id,
+           updated_at = v_created_at
+     where id = p_replaces_credential_id;
+  end if;
+
+  return query
+  select v_credential_id, v_refresh_token, v_expires_at, v_created_at, p_replaces_credential_id;
+end;
+$$;
+
+-- 2. rotate_agent_token: retire the 30-day session-exchange path. Raise on call.
+create or replace function agent_board.rotate_agent_token(
+  p_agent_id uuid
+)
+returns table(
+  agent_id uuid,
+  credential_id uuid,
+  refresh_token text,
+  expires_at timestamptz,
+  rotated_at timestamptz,
+  replaces_credential_id uuid
+)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+begin
+  -- MBDELEG (no-long-lived-tokens): the 30-day refresh-token exchange is retired.
+  -- Session refresh is solely re-signing: PoP -> agent_board.mint_fleet_agent_session.
+  raise exception 'rotate_agent_token is deprecated: session refresh is re-signing (PoP -> mint_fleet_agent_session), not a 30-day refresh-token exchange'
+    using errcode = '0A000';
+end;
+$$;
+
+comment on function agent_board.rotate_agent_token(uuid) is
+  'DEPRECATED (MBDELEG): raises 0A000. The 30-day refresh-token exchange is retired; session refresh is re-signing via PoP -> mint_fleet_agent_session.';