@team-semicolon/semicolony-cli 4.18.95 → 4.18.96

package/migrations/194_worker_agent_note_capture.sql

@@ -0,0 +1,222 @@
+-- 194_worker_agent_note_capture.sql
+--
+-- Give the two fixed Hermes actors one self-authorized, append-only fact lane.
+--
+-- Decision capture (186) requires an operator to pre-issue an authorization that
+-- pins actor, target, content digest, and authority. That is the right contract
+-- for a decision, but it leaves the actors with no way to record a plain fact
+-- when a human asks them to. This migration adds that lane and bounds it
+-- structurally instead of by pre-authorization: the recorder pins key='note' as
+-- a literal, refuses to touch a row that already exists, requires a domain that
+-- is already in the ontology, and enforces a rolling hourly quota per actor.
+--
+-- Blast radius is therefore one namespace. Curated knowledge (decision, process,
+-- infra, ...) is unreachable from this function, and every row it writes carries
+-- reported_by so the whole lane can be recalled with a single predicate.
+--
+-- The migration runner owns BEGIN/COMMIT.
+
+-- ---------------------------------------------------------------------------
+-- 1. Widen the actor credential scope contract from three scopes to four.
+--
+-- Both the decision recorder and the credential issuer compare gc.scopes by
+-- exact array equality. Adding a scope without moving them in the same
+-- transaction would break decision capture the moment a credential is rotated,
+-- so the two are repaired here rather than in a follow-up.
+--
+-- The repair rewrites only the scope array inside the installed definition
+-- (the 187 pattern). Copying the function bodies would silently revert 187's
+-- pg_catalog.sha256 correction.
+-- ---------------------------------------------------------------------------
+
+DO $scope_widen$
+DECLARE
+  v_targets constant text[] := ARRAY[
+    'semicolony.record_worker_agent_decision(uuid,uuid,text,text,text,text)',
+    'semicolony.issue_worker_agent_actor_credential(uuid,text,text,text,text,integer)'
+  ];
+  v_old constant text :=
+    'ARRAY[''kb:read'', ''feedback:write'', ''decision:write'']::text[]';
+  v_new constant text :=
+    'ARRAY[''kb:read'', ''feedback:write'', ''decision:write'', ''note:write'']::text[]';
+  v_target text;
+  v_definition text;
+  v_old_occurrences integer;
+BEGIN
+  FOREACH v_target IN ARRAY v_targets LOOP
+    SELECT pg_get_functiondef(v_target::regprocedure::oid) INTO STRICT v_definition;
+
+    v_old_occurrences :=
+      (char_length(v_definition) - char_length(replace(v_definition, v_old, '')))
+      / char_length(v_old);
+
+    IF v_old_occurrences = 0 AND position(v_new IN v_definition) > 0 THEN
+      CONTINUE;
+    END IF;
+    IF v_old_occurrences <> 1 THEN
+      RAISE EXCEPTION 'unexpected Worker-agent actor scope definition in %', v_target;
+    END IF;
+
+    EXECUTE replace(v_definition, v_old, v_new);
+  END LOOP;
+END;
+$scope_widen$;
+
+-- Existing active actor credentials keep working only if their stored scope
+-- array moves with the contract above.
+UPDATE semicolony.gateway_credentials AS gc
+   SET scopes = ARRAY['kb:read', 'feedback:write', 'decision:write', 'note:write']::text[]
+  FROM semicolony.worker_agent_actor_bindings AS binding
+ WHERE binding.gateway_credential_id = gc.id
+   AND binding.installation_id = 'hermes-principals@hermes'
+   AND binding.profile_id = 'semo-ops-worker-agent'
+   AND binding.runtime_kind = 'hermes-cli'
+   AND binding.actor_id IN ('semi', 'colony')
+   AND binding.status = 'active'
+   AND gc.status = 'active'
+   AND coalesce(gc.expires_at, 'infinity'::timestamptz) > clock_timestamp()
+   AND gc.metadata ->> 'credential_kind' = 'worker-agent-actor'
+   AND gc.metadata ->> 'actor_id' = binding.actor_id
+   AND gc.metadata ->> 'installation_id' = binding.installation_id
+   AND gc.metadata ->> 'profile_id' = binding.profile_id
+   AND gc.metadata ->> 'runtime_kind' = binding.runtime_kind
+   AND gc.metadata ->> 'runtime_profile' = binding.runtime_profile
+   AND gc.scopes
+       IS DISTINCT FROM
+       ARRAY['kb:read', 'feedback:write', 'decision:write', 'note:write']::text[];
+
+-- ---------------------------------------------------------------------------
+-- 2. The note recorder.
+-- ---------------------------------------------------------------------------
+
+CREATE OR REPLACE FUNCTION semicolony.record_worker_agent_note(
+  p_credential_id uuid,
+  p_domain text,
+  p_slug text,
+  p_content text,
+  p_embedding text
+)
+RETURNS TABLE(
+  kb_id bigint,
+  actor_id text,
+  quota_remaining integer
+)
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = pg_catalog
+AS $function$
+DECLARE
+  -- The note lane never accepts a caller-supplied key. Anything outside this
+  -- namespace is unreachable from this function.
+  c_key constant text := 'note';
+  c_quota_per_hour constant integer := 20;
+  v_actor_id text;
+  v_runtime_profile text;
+  v_recent_notes integer;
+  v_kb_id bigint;
+BEGIN
+  IF p_credential_id IS NULL THEN
+    RAISE EXCEPTION 'trusted credential is required' USING ERRCODE = '22023';
+  END IF;
+  IF p_domain IS NULL OR p_domain !~ '^[a-z][a-z0-9-]{1,62}$'
+     OR p_domain = 'semo' OR p_domain ~ '^t-' THEN
+    RAISE EXCEPTION 'invalid note domain' USING ERRCODE = '22023';
+  END IF;
+  IF p_slug IS NULL OR p_slug !~ '^[a-z0-9][a-z0-9-]{2,99}$' THEN
+    RAISE EXCEPTION 'invalid note slug' USING ERRCODE = '22023';
+  END IF;
+  IF p_content IS NULL OR p_content <> btrim(p_content)
+     OR char_length(p_content) < 30 OR char_length(p_content) > 10000
+     OR translate(p_content, E'\n\t', '') ~ '[[:cntrl:]]'
+     OR p_content ~* '(DATABASE_URL|postgres://|SEMO_OPS_WORKER_KB_TOKEN|Authorization:[[:space:]]*Bearer|wck_[A-Za-z0-9_-]+)' THEN
+    RAISE EXCEPTION 'invalid note content' USING ERRCODE = '22023';
+  END IF;
+  PERFORM p_embedding::public.vector;
+
+  SELECT binding.actor_id, binding.runtime_profile
+    INTO v_actor_id, v_runtime_profile
+    FROM semicolony.worker_agent_actor_bindings AS binding
+    JOIN semicolony.gateway_credentials AS gc
+      ON gc.id = binding.gateway_credential_id
+   WHERE binding.gateway_credential_id = p_credential_id
+     AND binding.installation_id = 'hermes-principals@hermes'
+     AND binding.profile_id = 'semo-ops-worker-agent'
+     AND binding.runtime_kind = 'hermes-cli'
+     AND binding.actor_id IN ('semi', 'colony')
+     AND binding.status = 'active'
+     AND gc.status = 'active'
+     AND coalesce(gc.expires_at, 'infinity'::timestamptz) > clock_timestamp()
+     AND gc.metadata ->> 'credential_kind' = 'worker-agent-actor'
+     AND gc.metadata ->> 'actor_id' = binding.actor_id
+     AND gc.metadata ->> 'installation_id' = binding.installation_id
+     AND gc.metadata ->> 'profile_id' = binding.profile_id
+     AND gc.metadata ->> 'runtime_kind' = binding.runtime_kind
+     AND gc.metadata ->> 'runtime_profile' = binding.runtime_profile
+     AND gc.scopes = ARRAY['kb:read', 'feedback:write', 'decision:write', 'note:write']::text[]
+   FOR UPDATE OF binding, gc;
+  IF NOT FOUND THEN
+    RAISE EXCEPTION 'active note credential binding not found' USING ERRCODE = '42501';
+  END IF;
+
+  -- A note may only attach to a domain the team already curates. A typo would
+  -- otherwise mint a new domain that no ontology consumer knows about.
+  PERFORM 1 FROM semicolony.ontology AS o WHERE o.domain = p_domain;
+  IF NOT FOUND THEN
+    RAISE EXCEPTION 'note domain is not registered in the ontology' USING ERRCODE = 'P0002';
+  END IF;
+
+  -- Serialize this actor so concurrent calls cannot both pass the quota check.
+  PERFORM pg_advisory_xact_lock(hashtextextended('worker-agent-note:' || v_actor_id, 0));
+
+  SELECT count(*)::integer
+    INTO v_recent_notes
+    FROM semicolony.knowledge_base AS kb
+   WHERE kb.key = c_key
+     AND kb.metadata ->> 'reported_by' = v_actor_id
+     AND kb.metadata ->> 'note_kind' = 'actor-self-reported'
+     AND kb.created_at > clock_timestamp() - interval '1 hour';
+  IF v_recent_notes >= c_quota_per_hour THEN
+    RAISE EXCEPTION 'note quota exhausted for this actor' USING ERRCODE = '53400';
+  END IF;
+
+  -- Append-only: an existing coordinate is never rewritten, not even with
+  -- identical content. Corrections are new slugs.
+  PERFORM 1
+     FROM semicolony.knowledge_base AS kb
+    WHERE kb.domain = p_domain AND kb.key = c_key AND kb.sub_key = p_slug;
+  IF FOUND THEN
+    RAISE EXCEPTION 'note target already exists' USING ERRCODE = '23505';
+  END IF;
+
+  INSERT INTO semicolony.knowledge_base (
+    domain, key, sub_key, content, created_by, embedding, metadata
+  ) VALUES (
+    p_domain,
+    c_key,
+    p_slug,
+    p_content,
+    'note-pipeline:' || v_actor_id,
+    p_embedding::public.vector,
+    jsonb_build_object(
+      'source', 'runtime-native-tool',
+      'note_kind', 'actor-self-reported',
+      'reported_by', v_actor_id,
+      'installation_id', 'hermes-principals@hermes',
+      'runtime_kind', 'hermes-cli',
+      'profile_id', 'semo-ops-worker-agent',
+      'runtime_profile', v_runtime_profile
+    )
+  )
+  RETURNING knowledge_base.kb_id INTO v_kb_id;
+
+  RETURN QUERY
+    SELECT v_kb_id, v_actor_id, c_quota_per_hour - v_recent_notes - 1;
+END;
+$function$;
+
+REVOKE ALL ON FUNCTION semicolony.record_worker_agent_note(
+  uuid, text, text, text, text
+) FROM PUBLIC, app, sc_provider;
+GRANT EXECUTE ON FUNCTION semicolony.record_worker_agent_note(
+  uuid, text, text, text, text
+) TO sc_app;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@team-semicolon/semicolony-cli",
-  "version": "4.18.95",
+  "version": "4.18.96",
   "description": "SemiColony CLI - AI operations and agent orchestration installer",
   "main": "dist/bundle.js",
   "bin": {