@consiliency/agent-board-schema 1.12.0 → 1.22.0

package/migrations/20260821000100_agent_board_claimgate_claimkey.sql

@@ -0,0 +1,372 @@
+-- CLAIMGATE Phase 1 — CLAIMKEY (#133): a frozen, fleet-fingerprint-carrying canonical
+-- claim-key grammar so the SHADOW/ENFORCE authority predicate has stable identity to
+-- resolve against. KEY FORMAT ONLY — no authorization, no predicate here.
+--
+-- =====================================================================================
+-- IF-0-CLAIMKEY-1 — canonical claim-key grammar (FROZEN; SHADOW/ENFORCE consume it)
+-- =====================================================================================
+-- The active-resource uniqueness index is on (resource_kind, resource_key) — the
+-- resource_kind column already namespaces the key space, so the canonical key MUST NOT
+-- repeat the kind. (This freezes the divergence flagged by the design panel: the North
+-- Star prose writes `machine:<fp>` / `repo_file:<fp>:<path>` with a kind prefix, but the
+-- ratified amendment — "resource_kind already namespaces the uniqueness index, so bare
+-- <fp> suffices" — governs. We take the internally-consistent kind-never-in-key reading.)
+--
+--   resource_kind   canonical resource_key            example
+--   -------------   -----------------------------     ------------------------------------
+--   machine         <machine_fingerprint>             fp_9a1c…                (bare fp)
+--   repository      <repo_fingerprint>                fp_repo_7b2…            (bare fp)
+--   repo_file       <repo_fingerprint>:<path>         fp_repo_7b2…:src/db.sql (fp, ':' , path)
+--   task            <task uuid>                        unchanged
+--   file/tool/custom free-form                         unchanged (VERBATIM — not even trimmed)
+--
+-- repo_file parse rule (SHADOW's future predicate MUST extract fp from the same position):
+-- the FIRST ':' splits the key — everything before it is the repo_fingerprint, everything
+-- after it is the path (which may itself contain ':'). e.g. `fp_repo_7b2…:src/db.sql`
+-- -> fp = `fp_repo_7b2…`, path = `src/db.sql`.
+--
+-- Legacy tolerance: an accidental leading `machine:` / `repository:` / `repo:` /
+-- `repo_file:` prefix is stripped so a pre-CLAIMKEY prefixed key normalizes to the same
+-- canonical value as its bare twin.
+--
+-- =====================================================================================
+-- NORMALIZE-ONLY (design-panel amendment) — this phase NEVER rejects a non-canonical key.
+-- =====================================================================================
+-- Rejecting is a behavior change and belongs to ENFORCE. `_canonical_claim_key` is a pure,
+-- deterministic string transform: it reads NO tables (fingerprint identity is validated by
+-- the authority predicate in SHADOW/ENFORCE, not here). An unmappable key is shadow-logged
+-- (RAISE NOTICE) and returned UNCHANGED, so CLAIMKEY is behavior-preserving for every key
+-- already in flight.
+--
+-- Wired into acquire_claim (normalizes the supplied key before the sweep/insert; its sweep AND
+-- conflict check are ALIAS-AWARE so a legacy row cannot be dual-held — MUST-FIX 3) AND
+-- renew_claim + release_claim (self-heal the STORED key of an existing lease). renew attempts
+-- canonicalization and, on a uniqueness collision (a committed alias twin OR a concurrent
+-- renew/acquire race at READ COMMITTED), retries ONCE keeping the current key — non-raising
+-- UNCONDITIONALLY, not merely "by construction" (MUST-FIX 1; a check-then-act guard is not
+-- race-safe). The surviving legacy key is the deferred dual-key alias ENFORCE closes. release
+-- always canonicalizes — the released tuple leaves the partial unique index, so it can never collide.
+--
+-- resource_key WRITER CLASS (catalog-derived, repo rule #1): at final replay state the only
+-- function that INSERTs resource_key is acquire_claim below; renew_claim/release_claim are
+-- the only functions that UPDATE it (added here). The completeness test asserts this
+-- POSITIVELY from pg_proc (every claims-key writer routes through _canonical_claim_key).
+--
+-- #118 class: _canonical_claim_key is SECURITY DEFINER — revoke PUBLIC + grant + comment in
+-- THIS migration. Additive, forward-only. schema_version stays 8.
+
+-- =====================================================================================
+-- 0. Census (one-shot, non-canonical keys per kind) — run against a target DB to confirm
+--    the migration set is bounded before ENFORCE. Committed as the report artifact for the
+--    CLAIMKEY exit criterion; on a fresh local replay it returns zero rows (no legacy keys).
+--
+--   select resource_kind,
+--          count(*)                                                as active_claims,
+--          count(*) filter (
+--            where resource_key
+--              is distinct from agent_board._canonical_claim_key(resource_kind, resource_key)
+--          )                                                       as non_canonical,
+--          array_agg(distinct resource_key) filter (
+--            where resource_key
+--              is distinct from agent_board._canonical_claim_key(resource_kind, resource_key)
+--          )                                                       as sample_non_canonical_keys
+--     from agent_board.claims
+--    where status = 'active' and released_at is null
+--    group by resource_kind
+--    order by resource_kind;
+-- =====================================================================================
+
+-- 1. _canonical_claim_key — the sole normalizer (IF-0-CLAIMKEY-1) ---------------------
+create or replace function agent_board._canonical_claim_key(
+  p_resource_kind text,
+  p_resource_key text
+)
+returns text
+language plpgsql
+security definer
+set search_path to 'agent_board', 'public'
+immutable
+as $function$
+declare
+  v_key  text;
+  v_fp   text;
+  v_path text;
+  v_sep  int;
+begin
+  -- Pure deterministic string transform. NORMALIZE-ONLY: never raises; an unmappable key is
+  -- shadow-logged and returned unchanged (trimmed) so behavior is preserved.
+  if p_resource_key is null then
+    return p_resource_key;
+  end if;
+  v_key := btrim(p_resource_key);
+
+  if p_resource_kind = 'machine' then
+    -- canonical: bare <machine_fingerprint>; tolerate a legacy 'machine:' prefix.
+    v_key := btrim(regexp_replace(v_key, '^machine:', ''));
+    if v_key = '' then
+      raise notice 'claimgate/CLAIMKEY: unmappable machine claim key %', p_resource_key;
+      return btrim(p_resource_key);
+    end if;
+    return v_key;
+
+  elsif p_resource_kind = 'repository' then
+    -- canonical: bare <repo_fingerprint>; tolerate a legacy 'repository:'/'repo:' prefix.
+    v_key := btrim(regexp_replace(v_key, '^(repository|repo):', ''));
+    if v_key = '' then
+      raise notice 'claimgate/CLAIMKEY: unmappable repository claim key %', p_resource_key;
+      return btrim(p_resource_key);
+    end if;
+    return v_key;
+
+  elsif p_resource_kind = 'repo_file' then
+    -- canonical: <repo_fingerprint>:<path>; tolerate a legacy 'repo_file:' prefix. The FIRST
+    -- ':' splits fp | path (path may contain further ':').
+    v_key := btrim(regexp_replace(v_key, '^repo_file:', ''));
+    v_sep := position(':' in v_key);
+    if v_sep <= 1 or v_sep = length(v_key) then
+      -- no fp/path split (or an empty side) — cannot canonicalize; leave intact.
+      raise notice 'claimgate/CLAIMKEY: unmappable repo_file claim key %', p_resource_key;
+      return btrim(p_resource_key);
+    end if;
+    v_fp   := btrim(substring(v_key from 1 for v_sep - 1));
+    v_path := btrim(substring(v_key from v_sep + 1));
+    if v_fp = '' or v_path = '' then
+      raise notice 'claimgate/CLAIMKEY: unmappable repo_file claim key %', p_resource_key;
+      return btrim(p_resource_key);
+    end if;
+    return v_fp || ':' || v_path;
+
+  else
+    -- task / file / tool / custom: identity intact — pass through VERBATIM (no trim).
+    -- Pre-CLAIMKEY acquire stored these keys unmodified, so " x " and "x" are DISTINCT
+    -- resources; trimming would silently alias them (SHOULD-FIX 4, codex). Only the
+    -- fleet-backed kinds above are canonicalized.
+    return p_resource_key;
+  end if;
+end;
+$function$;
+revoke all on function agent_board._canonical_claim_key(text, text) from public, anon;
+grant execute on function agent_board._canonical_claim_key(text, text) to authenticated, service_role;
+comment on function agent_board._canonical_claim_key(text, text) is
+  'CLAIMGATE/CLAIMKEY (#133, IF-0-CLAIMKEY-1): sole canonical claim-key normalizer. '
+  'machine/repository -> bare <fingerprint>; repo_file -> <fp>:<path> (first colon splits); '
+  'task/file/tool/custom pass through VERBATIM (no trim). NORMALIZE-ONLY — never rejects; unmappable keys are '
+  'shadow-logged (NOTICE) and returned unchanged. Pure string transform, reads no tables.';
+
+-- 2. acquire_claim — normalize the supplied key before the sweep/insert ----------------
+--    Reproduced verbatim from 20260817000100 (OBSGATE-4) except the CLAIMKEY normalize line.
+create or replace function agent_board.acquire_claim(
+  p_agent_id uuid,
+  p_resource_kind text,
+  p_resource_key text,
+  p_lease_expires_at timestamp with time zone,
+  p_task_id uuid default null,
+  p_thread_id uuid default null,
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(claim_id uuid, task_id uuid, thread_id uuid, agent_id uuid, resource_kind text, resource_key text, status text, lease_token uuid, lease_expires_at timestamp with time zone, released_at timestamp with time zone, created_at timestamp with time zone, updated_at timestamp with time zone)
+language plpgsql
+security definer
+set search_path to 'agent_board', 'public'
+as $function$
+declare
+  v_thread_id uuid;
+  v_claim_id uuid;
+  v_actor_agent_id uuid;
+begin
+  v_actor_agent_id := agent_board._resolved_actor_agent_id(p_agent_id, 'p_agent_id');
+
+  if nullif(trim(p_resource_key), '') is null then
+    raise exception 'resource key is required' using errcode = '22023';
+  end if;
+
+  -- CLAIMKEY (#133): normalize the resource key to its canonical, fleet-fingerprint-carrying
+  -- form BEFORE any lookup/insert, so the row stored (and the uniqueness index contended)
+  -- carry canonical identity. NORMALIZE-ONLY — this never rejects (rejection is ENFORCE).
+  p_resource_key := agent_board._canonical_claim_key(p_resource_kind, p_resource_key);
+
+  if p_task_id is not null then
+    select tasks.thread_id into v_thread_id from agent_board.tasks where id = p_task_id;
+    if v_thread_id is null then
+      raise exception 'task not found' using errcode = 'P0002';
+    end if;
+    if not agent_board._current_agent_can_access_task(p_task_id) then
+      raise exception 'task not accessible to current agent' using errcode = '42501';
+    end if;
+  else
+    v_thread_id := p_thread_id;
+  end if;
+
+  if v_thread_id is not null and not agent_board._current_agent_can_access_thread(v_thread_id) then
+    raise exception 'thread not accessible to current agent' using errcode = '42501';
+  end if;
+
+  -- OBSGATE-4 (#127): a claim on a TASK resource is authorized on the LOCKED task = the task
+  -- named by RESOURCE_KEY (resource_kind='task'). The active-resource uniqueness is on
+  -- (resource_kind, resource_key), so that is the task a squat contends for — gating resource_key
+  -- (NOT p_task_id, which only associates the claim/event) prevents locking task B's key while
+  -- authorizing on an unrelated task A passed as p_task_id. A non-uuid 'task' key cannot collide
+  -- with a uuid-keyed legitimate claim.
+  --
+  -- The composition MIRRORS append_task_event's: ACCESS then MUTATE. mutate alone is
+  -- insufficient — _current_agent_can_mutate_task admits any non-observer board member via
+  -- _current_agent_can_post_to_thread (board send-role), which is NOT thread access; on a
+  -- RESTRICTED thread a board member lacking thread access would pass mutate but must still be
+  -- denied (they cannot access the task). Requiring access too closes that gap and matches the
+  -- authorization a task-BOUND acquire already gets through append_task_event.
+  if p_resource_kind = 'task'
+     and p_resource_key ~ '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$' then
+    if not agent_board._current_agent_can_access_task(p_resource_key::uuid) then
+      raise exception 'task not accessible to current agent' using errcode = '42501';
+    end if;
+    if not agent_board._current_agent_can_mutate_task(p_resource_key::uuid) then
+      raise exception 'claiming a task resource requires a non-observer board role, or task assignment/creation'
+        using errcode = '42501';
+    end if;
+  end if;
+
+  -- CLAIMKEY (#133) MUST-FIX 3: the sweep AND the conflict check are ALIAS-AWARE. p_resource_key
+  -- is already canonical (above); comparing against the CANONICAL form of each existing row's key
+  -- matches both a canonical row AND an un-healed LEGACY row for the same physical resource. Without
+  -- this, acquire('machine','machine:fpDH') would normalize to 'fpDH', see no exact-'fpDH' conflict
+  -- against a still-active legacy 'machine:fpDH' row, and INSERT a second live hold — breaking mutual
+  -- exclusion during the legacy window. Closing it here in code does NOT depend on the operator-owned
+  -- live census.
+  update agent_board.claims c
+     set status = 'expired',
+         updated_at = now()
+   where c.resource_kind = p_resource_kind
+     and agent_board._canonical_claim_key(c.resource_kind, c.resource_key) = p_resource_key
+     and c.status = 'active'
+     and c.released_at is null
+     and c.lease_expires_at <= now();
+
+  if exists (
+    select 1 from agent_board.claims
+     where claims.resource_kind = p_resource_kind
+       and agent_board._canonical_claim_key(claims.resource_kind, claims.resource_key) = p_resource_key
+       and claims.status = 'active'
+       and claims.released_at is null
+       and claims.lease_expires_at > now()
+  ) then
+    raise exception 'conflicting active claim' using errcode = '23505';
+  end if;
+
+  insert into agent_board.claims(task_id, thread_id, agent_id, resource_kind, resource_key, lease_expires_at, metadata)
+  values (p_task_id, v_thread_id, v_actor_agent_id, p_resource_kind, p_resource_key, p_lease_expires_at, coalesce(p_metadata, '{}'::jsonb))
+  returning id into v_claim_id;
+
+  if p_task_id is not null then
+    perform agent_board.append_task_event(p_task_id, v_actor_agent_id, 'claimed', jsonb_build_object('claim_id', v_claim_id, 'resource_kind', p_resource_kind, 'resource_key', p_resource_key));
+  end if;
+
+  return query
+  select c.id, c.task_id, c.thread_id, c.agent_id, c.resource_kind, c.resource_key, c.status, c.lease_token, c.lease_expires_at, c.released_at, c.created_at, c.updated_at
+    from agent_board.claims c
+   where c.id = v_claim_id;
+end;
+$function$;
+revoke all on function agent_board.acquire_claim(uuid, text, text, timestamp with time zone, uuid, uuid, jsonb) from public, anon;
+grant execute on function agent_board.acquire_claim(uuid, text, text, timestamp with time zone, uuid, uuid, jsonb) to authenticated, service_role;
+
+-- 3. renew_claim — self-heal the STORED key, non-raising UNCONDITIONALLY (retry-once) ----
+--    Reproduced verbatim from 20260512000001 except the CLAIMKEY re-canonicalization.
+create or replace function agent_board.renew_claim(p_lease_token uuid, p_lease_expires_at timestamptz)
+returns table(claim_id uuid, task_id uuid, thread_id uuid, agent_id uuid, resource_kind text, resource_key text, status text, lease_token uuid, lease_expires_at timestamptz, released_at timestamptz, created_at timestamptz, updated_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_actor_agent_id uuid;
+begin
+  if not agent_board._is_service_role() then
+    v_actor_agent_id := agent_board._resolved_actor_agent_id(null, 'current_agent_id');
+    if not exists (
+      select 1
+        from agent_board.claims c
+       where c.lease_token = p_lease_token
+         and c.agent_id = v_actor_agent_id
+    ) then
+      raise exception 'claim not accessible to current agent' using errcode = '42501';
+    end if;
+  end if;
+
+  -- CLAIMKEY (#133) MUST-FIX 1: re-canonicalize the STORED key as the lease is renewed, but
+  -- NEVER propagate a uniqueness collision. A check-then-act guard is NOT race-safe: two aliased
+  -- legacy rows renewed concurrently at READ COMMITTED can both observe the canonical key free
+  -- and one loses on claims_active_resource_unique (23505). So attempt the canonicalization and,
+  -- on unique_violation (deterministic alias OR concurrent race), retry ONCE keeping the CURRENT
+  -- key. That makes renew non-raising UNCONDITIONALLY (true normalize-only); the surviving legacy
+  -- key is the deferred dual-key alias the ENFORCE phase closes.
+  begin
+    return query
+    update agent_board.claims c
+       set lease_expires_at = p_lease_expires_at,
+           resource_key = agent_board._canonical_claim_key(c.resource_kind, c.resource_key),
+           updated_at = now()
+     where c.lease_token = p_lease_token
+       and c.status = 'active'
+       and c.released_at is null
+       and c.lease_expires_at > now()
+    returning c.id, c.task_id, c.thread_id, c.agent_id, c.resource_kind, c.resource_key, c.status, c.lease_token, c.lease_expires_at, c.released_at, c.created_at, c.updated_at;
+  exception when unique_violation then
+    -- the canonical key is already held (by a committed twin or a concurrent renew/acquire):
+    -- renew the lease keeping the current key, aliasing deferred to ENFORCE. Only the key change
+    -- can raise unique_violation (the lease/timestamp columns are unconstrained), so the retry
+    -- cannot itself collide.
+    return query
+    update agent_board.claims c
+       set lease_expires_at = p_lease_expires_at,
+           updated_at = now()
+     where c.lease_token = p_lease_token
+       and c.status = 'active'
+       and c.released_at is null
+       and c.lease_expires_at > now()
+    returning c.id, c.task_id, c.thread_id, c.agent_id, c.resource_kind, c.resource_key, c.status, c.lease_token, c.lease_expires_at, c.released_at, c.created_at, c.updated_at;
+  end;
+end;
+$$;
+revoke all on function agent_board.renew_claim(uuid, timestamptz) from public, anon;
+grant execute on function agent_board.renew_claim(uuid, timestamptz) to authenticated, service_role;
+
+-- 4. release_claim — canonicalize the STORED key (always safe; row leaves the index) ----
+--    Reproduced verbatim from 20260512000001 except the CLAIMKEY re-canonicalization line.
+create or replace function agent_board.release_claim(p_lease_token uuid)
+returns table(claim_id uuid, task_id uuid, thread_id uuid, agent_id uuid, resource_kind text, resource_key text, status text, lease_token uuid, lease_expires_at timestamptz, released_at timestamptz, created_at timestamptz, updated_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_actor_agent_id uuid;
+begin
+  if not agent_board._is_service_role() then
+    v_actor_agent_id := agent_board._resolved_actor_agent_id(null, 'current_agent_id');
+    if not exists (
+      select 1
+        from agent_board.claims c
+       where c.lease_token = p_lease_token
+         and c.agent_id = v_actor_agent_id
+    ) then
+      raise exception 'claim not accessible to current agent' using errcode = '42501';
+    end if;
+  end if;
+
+  -- CLAIMKEY (#133): canonicalize the STORED key on release. The tuple transitions to
+  -- status='released', leaving the claims_active_resource_unique partial index, so this can
+  -- never collide — normalize unconditionally.
+  return query
+  update agent_board.claims c
+     set status = 'released',
+         released_at = now(),
+         resource_key = agent_board._canonical_claim_key(c.resource_kind, c.resource_key),
+         updated_at = now()
+   where c.lease_token = p_lease_token
+     and c.status = 'active'
+     and c.released_at is null
+  returning c.id, c.task_id, c.thread_id, c.agent_id, c.resource_kind, c.resource_key, c.status, c.lease_token, c.lease_expires_at, c.released_at, c.created_at, c.updated_at;
+end;
+$$;
+revoke all on function agent_board.release_claim(uuid) from public, anon;
+grant execute on function agent_board.release_claim(uuid) to authenticated, service_role;