spine-framework 0.3.145 → 0.4.0

package/.framework/migrations/017_cil_stable_ids.sql

@@ -0,0 +1,37 @@
+-- CIL[BEGIN stable_id="~/.framework/migrations/017_cil_stable_ids.sql:module_header:module_header" type="module_header" identity="module_header" parent="none"]
+-- CIL[DOC-MACRO purpose="Deprecated migration header for CIL stable IDs"]
+-- CIL[DOC-RESPONSIBILITY responsibility="Document the migration purpose and deprecation status"]
+-- CIL[DOC-CONTEXT module="migrations" layer="database" related_files=".framework/migrations/017_cil_stable_ids.sql"]
+-- CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+-- CIL[DOC-MICRO logic_summary="Contains a deprecation notice and a no-op SELECT statement for applied databases" notable_decisions="[]"]
+-- CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+-- CIL[DOC-STABILITY stability="deprecated"]
+-- CIL[DOC-AUDIENCE audience="installer"]
+-- 017_cil_stable_ids.sql
+-- Deprecated: stable IDs and versions are now generated at ingest time.
+-- The old hard-coded backfill is no longer run on new installs.
+-- Existing databases that already applied this migration are unaffected.
+-- CIL[DOC-VECTOR type="context" content="purpose='Deprecated migration header for CIL stable IDs'; No verified external callers; imports: none"]
+-- CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+-- CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+-- CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+-- CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+-- CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+-- CIL[END stable_id="~/.framework/migrations/017_cil_stable_ids.sql:module_header:module_header"]
+
+-- CIL[BEGIN stable_id="~/.framework/migrations/017_cil_stable_ids.sql:noop:statement" type="statement" identity="noop" parent="none"]
+-- CIL[DOC-MACRO purpose="No-op migration placeholder statement"]
+-- CIL[DOC-RESPONSIBILITY responsibility="Satisfy migration runner with a harmless SELECT"]
+-- CIL[DOC-CONTEXT module="migrations" layer="database" related_files=".framework/migrations/017_cil_stable_ids.sql"]
+-- CIL[DOC-CONTRACT inputs="none" outputs="scalar 1" errors="none" side_effects="none"]
+-- CIL[DOC-MICRO logic_summary="Executes SELECT 1 to mark the migration as applied" notable_decisions="[]"]
+-- CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+-- CIL[DOC-STABILITY stability="deprecated"]
+SELECT 1;
+-- CIL[DOC-VECTOR type="context" content="purpose='No-op migration placeholder statement'; No verified external callers; imports: none"]
+-- CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+-- CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+-- CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+-- CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+-- CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+-- CIL[END stable_id="~/.framework/migrations/017_cil_stable_ids.sql:noop:statement"]

package/.framework/migrations/018_runtime_tables.sql

@@ -0,0 +1,129 @@
+-- CIL[BEGIN stable_id="~/.framework/migrations/018_runtime_tables.sql:runtime_tables:file" type="file" identity="runtime_tables" parent="~/.framework/migrations/018_runtime_tables.sql"]
+-- CIL[DOC-MACRO purpose="Create the runtime action/schedule/test-result tables that the live chain references but never created"]
+-- CIL[DOC-RESPONSIBILITY responsibility="Create actions, schedules, schedule_executions, and test_results with foreign keys, indexes, and RLS enabled"]
+-- CIL[DOC-CONTEXT module="migrations" layer="database" related_files=".framework/functions/system-cron.ts,.framework/functions/trigger-scheduler.ts,.framework/functions/tests.ts,.framework/migrations/043_policy_actor_cleanup.sql,.framework/migrations/046_security_missing_rls.sql"]
+-- CIL[DOC-CONTRACT inputs="none" outputs="Four tables matching archive-era schema" errors="none — CREATE TABLE IF NOT EXISTS and guarded constraints are idempotent" side_effects="Enables RLS; 043/046 then attach policies"]
+-- CIL[DOC-MICRO logic_summary="These tables existed only in archive migrations, so dev databases carry them but fresh installs did not — 043/046 failed on missing relations. Definitions are pulled verbatim from archive/002e_system_tables.sql, archive/003_foreign_keys.sql, and archive/008_test_runs.sql; FK constraints are guarded by pg_constraint checks so the file is a no-op where tables already exist" notable_decisions="numbered 018 to run before 043/046 which attach the RLS policies; test_results keeps its run_id FK to test_runs"]
+-- CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+-- CIL[DOC-STABILITY stability="stable"]
+
+-- Runtime tables that archive migrations created but the live chain only
+-- referenced (043 policies, 046 RLS, system-cron/trigger-scheduler/agent-runner/
+-- tests.ts consumers). IF NOT EXISTS makes this a no-op on databases that
+-- already carry them.
+
+CREATE TABLE IF NOT EXISTS public.actions (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  account_id uuid, name text NOT NULL, slug text NOT NULL,
+  description text, handler text NOT NULL, handler_module text DEFAULT 'functions',
+  config jsonb DEFAULT '{}', input_schema jsonb DEFAULT '{}', output_schema jsonb DEFAULT '{}',
+  ownership text DEFAULT 'tenant', is_system boolean DEFAULT false,
+  default_machine_principal_id uuid, required_scopes text[] DEFAULT '{}',
+  is_active boolean DEFAULT true, timeout_seconds integer DEFAULT 300,
+  retry_count integer DEFAULT 3, created_by uuid, created_at timestamptz DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS public.schedules (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  account_id uuid, action_id uuid NOT NULL, name text NOT NULL,
+  schedule_type text NOT NULL, cron_expression text,
+  next_run_at timestamptz, last_run_at timestamptz,
+  ownership text DEFAULT 'tenant', is_system boolean DEFAULT false,
+  is_active boolean DEFAULT true, machine_principal_id uuid,
+  created_by uuid, created_at timestamptz DEFAULT now(), updated_at timestamptz DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS public.schedule_executions (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  schedule_id uuid NOT NULL, account_id uuid NOT NULL, machine_principal_id uuid,
+  status text DEFAULT 'pending', input_params jsonb DEFAULT '{}',
+  output_result jsonb DEFAULT '{}', error_message text, duration_ms integer,
+  created_at timestamptz DEFAULT now()
+);
+
+-- test_runs carries two historical shapes: the archive runner shape
+-- (suite/status/counts, consumed by tests.ts) and the generic registry shape
+-- created in 001. Add the runner columns additively so both consumers work
+-- regardless of which lineage built the database.
+ALTER TABLE public.test_runs ADD COLUMN IF NOT EXISTS suite text;
+ALTER TABLE public.test_runs ADD COLUMN IF NOT EXISTS status text;
+ALTER TABLE public.test_runs ADD COLUMN IF NOT EXISTS started_at timestamptz;
+ALTER TABLE public.test_runs ADD COLUMN IF NOT EXISTS finished_at timestamptz;
+ALTER TABLE public.test_runs ADD COLUMN IF NOT EXISTS duration_ms integer;
+ALTER TABLE public.test_runs ADD COLUMN IF NOT EXISTS total integer;
+ALTER TABLE public.test_runs ADD COLUMN IF NOT EXISTS passed integer;
+ALTER TABLE public.test_runs ADD COLUMN IF NOT EXISTS failed integer;
+ALTER TABLE public.test_runs ADD COLUMN IF NOT EXISTS skipped integer;
+ALTER TABLE public.test_runs ADD COLUMN IF NOT EXISTS triggered_by text DEFAULT 'agent';
+
+CREATE TABLE IF NOT EXISTS public.test_results (
+  id          uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  run_id      uuid NOT NULL REFERENCES public.test_runs(id) ON DELETE CASCADE,
+  suite       text NOT NULL,
+  file        text,
+  describe    text,
+  name        text NOT NULL,
+  status      text NOT NULL,
+  duration_ms integer,
+  error       text,
+  created_at  timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS idx_test_results_run_id ON public.test_results(run_id);
+CREATE INDEX IF NOT EXISTS idx_test_runs_suite ON public.test_runs(suite);
+CREATE INDEX IF NOT EXISTS idx_test_runs_started_at ON public.test_runs(started_at DESC);
+
+-- Foreign keys from archive/003_foreign_keys.sql, guarded for idempotency
+DO $$
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'fk_actions_account') THEN
+    ALTER TABLE public.actions ADD CONSTRAINT fk_actions_account
+      FOREIGN KEY (account_id) REFERENCES public.accounts(id) ON DELETE CASCADE;
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'fk_actions_machine_principal') THEN
+    ALTER TABLE public.actions ADD CONSTRAINT fk_actions_machine_principal
+      FOREIGN KEY (default_machine_principal_id) REFERENCES public.api_keys(id) ON DELETE SET NULL;
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'fk_actions_created_by') THEN
+    ALTER TABLE public.actions ADD CONSTRAINT fk_actions_created_by
+      FOREIGN KEY (created_by) REFERENCES public.people(id) ON DELETE SET NULL;
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'fk_schedules_account') THEN
+    ALTER TABLE public.schedules ADD CONSTRAINT fk_schedules_account
+      FOREIGN KEY (account_id) REFERENCES public.accounts(id) ON DELETE CASCADE;
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'fk_schedules_action') THEN
+    ALTER TABLE public.schedules ADD CONSTRAINT fk_schedules_action
+      FOREIGN KEY (action_id) REFERENCES public.actions(id) ON DELETE CASCADE;
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'fk_schedules_machine') THEN
+    ALTER TABLE public.schedules ADD CONSTRAINT fk_schedules_machine
+      FOREIGN KEY (machine_principal_id) REFERENCES public.api_keys(id) ON DELETE SET NULL;
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'fk_schedules_created_by') THEN
+    ALTER TABLE public.schedules ADD CONSTRAINT fk_schedules_created_by
+      FOREIGN KEY (created_by) REFERENCES public.people(id) ON DELETE SET NULL;
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'fk_se_schedule') THEN
+    ALTER TABLE public.schedule_executions ADD CONSTRAINT fk_se_schedule
+      FOREIGN KEY (schedule_id) REFERENCES public.schedules(id) ON DELETE CASCADE;
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'fk_se_account') THEN
+    ALTER TABLE public.schedule_executions ADD CONSTRAINT fk_se_account
+      FOREIGN KEY (account_id) REFERENCES public.accounts(id) ON DELETE CASCADE;
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'fk_se_machine') THEN
+    ALTER TABLE public.schedule_executions ADD CONSTRAINT fk_se_machine
+      FOREIGN KEY (machine_principal_id) REFERENCES public.api_keys(id) ON DELETE SET NULL;
+  END IF;
+END $$;
+
+-- RLS enabled here; 043/046 attach the actual policies
+ALTER TABLE public.actions ENABLE ROW LEVEL SECURITY;
+ALTER TABLE public.schedules ENABLE ROW LEVEL SECURITY;
+ALTER TABLE public.schedule_executions ENABLE ROW LEVEL SECURITY;
+ALTER TABLE public.test_results ENABLE ROW LEVEL SECURITY;
+-- CIL[DOC-VECTOR type="context" content="purpose='Create runtime tables (actions/schedules/schedule_executions/test_results) that archive migrations owned but the live chain never created.'; No verified external callers; imports: none"]
+-- CIL[DOC-VECTOR type="blast_radius" content="Fresh installs gain the tables that system-cron, trigger-scheduler, agent-runner, pipeline-runner, and tests.ts query; existing databases are untouched via IF NOT EXISTS" status="ready"]
+-- CIL[DOC-VECTOR type="configuration" content="None — runs position 018 so 043/046 policy migrations apply cleanly after it" status="ready"]
+-- CIL[END stable_id="~/.framework/migrations/018_runtime_tables.sql:runtime_tables:file"]

package/.framework/migrations/019_agent_prompt_columns.sql

@@ -0,0 +1,56 @@
+-- CIL[BEGIN stable_id="~/.framework/migrations/019_agent_prompt_columns.sql:agent_prompt_columns:file" type="file" identity="agent_prompt_columns" parent="~/.framework/migrations/019_agent_prompt_columns.sql"]
+-- CIL[DOC-MACRO purpose="Reconcile ai_agents/prompt_configs column divergence between archive-era and live-chain table shapes"]
+-- CIL[DOC-RESPONSIBILITY responsibility="Add the rich agent/prompt columns the archive schema carried that the live generic registry shape lacks, plus the slug column and uniqueness index dev databases are missing"]
+-- CIL[DOC-CONTEXT module="migrations" layer="database" related_files=".framework/functions/_shared/agent-runner.ts,.framework/functions/ai-agents.ts,.framework/migrations/archive/002e_system_tables.sql,.framework/migrations/001_core_schema.sql"]
+-- CIL[DOC-CONTRACT inputs="none" outputs="Both tables carry the union of archive and live columns" errors="none — ADD COLUMN IF NOT EXISTS is idempotent" side_effects="Unique indexes enable seedApp upserts on (app_id,slug)"]
+-- CIL[DOC-MICRO logic_summary="agent-runner.ts reads agent.system_prompt/model_config/agent_type and promptConfig.context_template/confidence_threshold/knowledge_sources/etc directly — columns the live 001 generic shape never created but dev databases carry via archive. Adds every archive column additively plus slug/unique-index on ai_agents (dev's table predates the slug convention; fresh installs get NOT NULL from 001 and skip this)" notable_decisions="columns added nullable because existing dev rows cannot retroactively satisfy NOT NULL; the (app_id,slug) unique index tolerates existing NULL slugs so it can be created on dev lineage"]
+-- CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+-- CIL[DOC-STABILITY stability="stable"]
+
+-- ai_agents: archive columns the live generic shape lacks.
+-- slug is added nullable for dev lineage (existing rows have no slug);
+-- fresh installs already have it NOT NULL from 001.
+ALTER TABLE public.ai_agents ADD COLUMN IF NOT EXISTS slug text;
+ALTER TABLE public.ai_agents ADD COLUMN IF NOT EXISTS type_id uuid;
+ALTER TABLE public.ai_agents ADD COLUMN IF NOT EXISTS agent_type text;
+ALTER TABLE public.ai_agents ADD COLUMN IF NOT EXISTS model_config jsonb DEFAULT '{}';
+ALTER TABLE public.ai_agents ADD COLUMN IF NOT EXISTS system_prompt text;
+ALTER TABLE public.ai_agents ADD COLUMN IF NOT EXISTS tools jsonb DEFAULT '[]';
+ALTER TABLE public.ai_agents ADD COLUMN IF NOT EXISTS capabilities jsonb DEFAULT '[]';
+ALTER TABLE public.ai_agents ADD COLUMN IF NOT EXISTS constraints jsonb DEFAULT '{}';
+ALTER TABLE public.ai_agents ADD COLUMN IF NOT EXISTS ownership text DEFAULT 'tenant';
+ALTER TABLE public.ai_agents ADD COLUMN IF NOT EXISTS updated_by uuid;
+
+-- prompt_configs: archive columns the live generic shape lacks.
+ALTER TABLE public.prompt_configs ADD COLUMN IF NOT EXISTS type_id uuid;
+ALTER TABLE public.prompt_configs ADD COLUMN IF NOT EXISTS description text;
+ALTER TABLE public.prompt_configs ADD COLUMN IF NOT EXISTS system_prompt text;
+ALTER TABLE public.prompt_configs ADD COLUMN IF NOT EXISTS context_template text;
+ALTER TABLE public.prompt_configs ADD COLUMN IF NOT EXISTS model text;
+ALTER TABLE public.prompt_configs ADD COLUMN IF NOT EXISTS temperature numeric;
+ALTER TABLE public.prompt_configs ADD COLUMN IF NOT EXISTS max_tokens integer;
+ALTER TABLE public.prompt_configs ADD COLUMN IF NOT EXISTS is_multi_turn boolean DEFAULT false;
+ALTER TABLE public.prompt_configs ADD COLUMN IF NOT EXISTS max_history_messages integer;
+ALTER TABLE public.prompt_configs ADD COLUMN IF NOT EXISTS confidence_threshold numeric;
+ALTER TABLE public.prompt_configs ADD COLUMN IF NOT EXISTS escalation_action text;
+ALTER TABLE public.prompt_configs ADD COLUMN IF NOT EXISTS escalation_target text;
+ALTER TABLE public.prompt_configs ADD COLUMN IF NOT EXISTS output_mode text;
+ALTER TABLE public.prompt_configs ADD COLUMN IF NOT EXISTS output_field text;
+ALTER TABLE public.prompt_configs ADD COLUMN IF NOT EXISTS requires_review boolean DEFAULT false;
+ALTER TABLE public.prompt_configs ADD COLUMN IF NOT EXISTS knowledge_sources jsonb DEFAULT '[]';
+ALTER TABLE public.prompt_configs ADD COLUMN IF NOT EXISTS available_tools jsonb DEFAULT '[]';
+ALTER TABLE public.prompt_configs ADD COLUMN IF NOT EXISTS tool_constraints jsonb DEFAULT '{}';
+ALTER TABLE public.prompt_configs ADD COLUMN IF NOT EXISTS ownership text DEFAULT 'tenant';
+ALTER TABLE public.prompt_configs ADD COLUMN IF NOT EXISTS updated_by uuid;
+
+-- Uniqueness indexes so seedApp upserts on (app_id,slug) work on both lineages.
+-- NULL slugs on dev lineage are allowed (NULLs are distinct) and get backfilled
+-- by future seed writes.
+CREATE UNIQUE INDEX IF NOT EXISTS ux_ai_agents_app_slug
+  ON public.ai_agents (app_id, slug);
+CREATE UNIQUE INDEX IF NOT EXISTS ux_prompt_configs_app_slug
+  ON public.prompt_configs (app_id, slug);
+-- CIL[DOC-VECTOR type="context" content="purpose='Add missing archive-shape columns to ai_agents and prompt_configs so agent-runner and seed upserts work on fresh installs.'; No verified external callers; imports: none"]
+-- CIL[DOC-VECTOR type="blast_radius" content="Fresh installs gain the columns agent-runner.ts reads; dev databases gain slug/unique-index so the same seed files work on both" status="ready"]
+-- CIL[DOC-VECTOR type="constraint" content="slug added nullable rather than NOT NULL because existing dev rows cannot satisfy the constraint retroactively" status="ready"]
+-- CIL[END stable_id="~/.framework/migrations/019_agent_prompt_columns.sql:agent_prompt_columns:file"]

package/.framework/migrations/020_schema_reconciliation.sql

@@ -0,0 +1,67 @@
+-- CIL[BEGIN stable_id="~/.framework/migrations/020_schema_reconciliation.sql:schema_reconciliation:file" type="file" identity="schema_reconciliation" parent="~/.framework/migrations/020_schema_reconciliation.sql"]
+-- CIL[DOC-MACRO purpose="Reconcile archive-era columns the live generic registry shape dropped from nine runtime tables"]
+-- CIL[DOC-RESPONSIBILITY responsibility="Add dev-lineage columns to triggers, timers, pipelines, trigger_executions, pipeline_executions, api_keys, item_progress, logs, and messages so runtime functions work on live-chain schemas"]
+-- CIL[DOC-CONTEXT module="migrations" layer="database" related_files=".framework/functions/_shared/trigger-engine.ts,.framework/functions/trigger-scheduler.ts,.framework/functions/system-cron.ts,.framework/functions/_shared/pipeline-runner.ts,.framework/migrations/018_runtime_tables.sql,.framework/migrations/019_agent_prompt_columns.sql"]
+-- CIL[DOC-CONTRACT inputs="none" outputs="Nine tables carry the union of both lineage shapes" errors="none — ADD COLUMN IF NOT EXISTS is idempotent" side_effects="Trigger engine, pipeline runner, system cron, API-key auth, and admin-data PATCH can read/write the columns they expect"]
+-- CIL[DOC-MICRO logic_summary="Dev databases were built by archive migrations whose rich table shapes (event_type/pipeline_id on triggers, timer_type/next_execution on timers, stages on pipelines, key_value on api_keys, etc.) were dropped when 001 re-created tables in the generic registry shape. Runtime code reads these columns directly, so fresh installs could not fire triggers, run pipelines, or auth machine principals. Column types are copied verbatim from a live dev information_schema dump" notable_decisions="integration_routes deliberately excluded — 004 drops it as dead schema; NOT NULL clauses preserved from dev types, safe because these tables are empty on fresh installs"]
+-- CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+-- CIL[DOC-STABILITY stability="stable"]
+
+-- triggers: columns the trigger engine reads/writes
+ALTER TABLE public.triggers ADD COLUMN IF NOT EXISTS trigger_type text NOT NULL;
+ALTER TABLE public.triggers ADD COLUMN IF NOT EXISTS event_type text;
+ALTER TABLE public.triggers ADD COLUMN IF NOT EXISTS pipeline_id uuid;
+ALTER TABLE public.triggers ADD COLUMN IF NOT EXISTS ownership text DEFAULT 'tenant';
+ALTER TABLE public.triggers ADD COLUMN IF NOT EXISTS trigger_count integer DEFAULT 0;
+ALTER TABLE public.triggers ADD COLUMN IF NOT EXISTS last_triggered timestamp with time zone;
+
+-- timers: columns the scheduler/cron path reads/writes
+ALTER TABLE public.timers ADD COLUMN IF NOT EXISTS timer_type text NOT NULL;
+ALTER TABLE public.timers ADD COLUMN IF NOT EXISTS pipeline_id uuid;
+ALTER TABLE public.timers ADD COLUMN IF NOT EXISTS ownership text DEFAULT 'tenant';
+ALTER TABLE public.timers ADD COLUMN IF NOT EXISTS last_execution timestamp with time zone;
+ALTER TABLE public.timers ADD COLUMN IF NOT EXISTS next_execution timestamp with time zone;
+ALTER TABLE public.timers ADD COLUMN IF NOT EXISTS execution_count integer DEFAULT 0;
+ALTER TABLE public.timers ADD COLUMN IF NOT EXISTS success_count integer DEFAULT 0;
+ALTER TABLE public.timers ADD COLUMN IF NOT EXISTS failure_count integer DEFAULT 0;
+
+-- pipelines: columns the pipeline runner reads
+ALTER TABLE public.pipelines ADD COLUMN IF NOT EXISTS trigger_type text;
+ALTER TABLE public.pipelines ADD COLUMN IF NOT EXISTS stages jsonb DEFAULT '[]';
+ALTER TABLE public.pipelines ADD COLUMN IF NOT EXISTS ownership text DEFAULT 'tenant';
+
+-- trigger_executions / pipeline_executions: execution record fields
+ALTER TABLE public.trigger_executions ADD COLUMN IF NOT EXISTS triggered_at timestamp with time zone DEFAULT now();
+ALTER TABLE public.trigger_executions ADD COLUMN IF NOT EXISTS trigger_data jsonb DEFAULT '{}';
+ALTER TABLE public.trigger_executions ADD COLUMN IF NOT EXISTS result jsonb DEFAULT '{}';
+ALTER TABLE public.trigger_executions ADD COLUMN IF NOT EXISTS duration_ms integer;
+
+ALTER TABLE public.pipeline_executions ADD COLUMN IF NOT EXISTS trigger_data jsonb DEFAULT '{}';
+ALTER TABLE public.pipeline_executions ADD COLUMN IF NOT EXISTS result jsonb DEFAULT '{}';
+ALTER TABLE public.pipeline_executions ADD COLUMN IF NOT EXISTS duration_ms integer;
+
+-- api_keys: machine-principal credential
+ALTER TABLE public.api_keys ADD COLUMN IF NOT EXISTS key_value text;
+
+-- item_progress: runtime record columns
+ALTER TABLE public.item_progress ADD COLUMN IF NOT EXISTS person_id uuid NOT NULL;
+ALTER TABLE public.item_progress ADD COLUMN IF NOT EXISTS title text;
+ALTER TABLE public.item_progress ADD COLUMN IF NOT EXISTS status text DEFAULT 'not_started' NOT NULL;
+ALTER TABLE public.item_progress ADD COLUMN IF NOT EXISTS score integer;
+ALTER TABLE public.item_progress ADD COLUMN IF NOT EXISTS data jsonb DEFAULT '{}' NOT NULL;
+ALTER TABLE public.item_progress ADD COLUMN IF NOT EXISTS design_schema jsonb DEFAULT '{}' NOT NULL;
+ALTER TABLE public.item_progress ADD COLUMN IF NOT EXISTS validation_schema jsonb DEFAULT '{}' NOT NULL;
+ALTER TABLE public.item_progress ADD COLUMN IF NOT EXISTS updated_by uuid;
+
+-- logs: source attribution
+ALTER TABLE public.logs ADD COLUMN IF NOT EXISTS source text;
+ALTER TABLE public.logs ADD COLUMN IF NOT EXISTS source_type text;
+ALTER TABLE public.logs ADD COLUMN IF NOT EXISTS source_id uuid;
+ALTER TABLE public.logs ADD COLUMN IF NOT EXISTS person_id uuid;
+
+-- messages: same updated_by gap 047 fixed for people/watchers/attachments
+ALTER TABLE public.messages ADD COLUMN IF NOT EXISTS updated_by uuid;
+-- CIL[DOC-VECTOR type="context" content="purpose='Add archive-era columns missing from the live generic registry shape across nine runtime tables.'; No verified external callers; imports: none"]
+-- CIL[DOC-VECTOR type="blast_radius" content="Trigger engine, pipeline runner, scheduler, API-key auth, item progress, logging, and message updates work on fresh installs; dev lineage is a no-op" status="ready"]
+-- CIL[DOC-VECTOR type="constraint" content="Column types copied verbatim from dev information_schema — dev lineage keeps its NOT NULL constraints, fresh installs add identical definitions" status="ready"]
+-- CIL[END stable_id="~/.framework/migrations/020_schema_reconciliation.sql:schema_reconciliation:file"]

package/.framework/migrations/021_kb_embedding_lifecycle.sql

@@ -0,0 +1,31 @@
+-- ============================================================================
+-- 021: KB embedding lifecycle RPC
+-- ----------------------------------------------------------------------------
+-- kbRevoke (functions/_shared/kb.ts) calls revoke_embeddings_for_item during
+-- KB ingest/unpublish. The function existed in the dev database (created by the
+-- archived embedding-lifecycle migration) but was never present in the live
+-- chain, so fresh installs failed with "function not found in schema cache".
+-- Definition copied verbatim from the working dev database.
+-- ============================================================================
+
+CREATE OR REPLACE FUNCTION public.revoke_embeddings_for_item(p_item_id uuid)
+RETURNS integer
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path TO 'public'
+AS $function$
+DECLARE
+  v_count integer;
+BEGIN
+  UPDATE public.embeddings
+  SET    revoked_at = now()
+  WHERE  document_id = p_item_id::text
+  AND    revoked_at  IS NULL;
+
+  GET DIAGNOSTICS v_count = ROW_COUNT;
+  RETURN v_count;
+END;
+$function$;
+
+GRANT EXECUTE ON FUNCTION public.revoke_embeddings_for_item(uuid)
+  TO service_role;

package/.framework/migrations/032_cil_status_migration.sql

@@ -0,0 +1,73 @@
+-- CIL[BEGIN stable_id="~/.framework/migrations/032_cil_status_migration.sql:cil_status_migration:file" type="file" identity="cil_status_migration" parent="~/.framework/migrations/032_cil_status_migration.sql"]
+-- CIL[DOC-MACRO purpose="One-time SQL migration: collapse legacy CIL file_statuses into the canonical 0-8 model."]
+-- CIL[DOC-RESPONSIBILITY responsibility="Remap legacy status aliases in items.data->file_statuses to canonical statuses."]
+-- CIL[DOC-CONTEXT module="migrations" layer="data" related_files=".framework/migrations/032_cil_status_migration.sql"]
+-- CIL[DOC-CONTRACT inputs="items table rows with kb_type='cil_project' and active file_statuses JSONB" outputs="Updated items.data.file_statuses with canonical 0-8 statuses" errors="May leave unmapped statuses as 0-discovered; only affects active CIL project rows" side_effects="Updates items.data and sets updated_at to now()"]
+-- CIL[DOC-MICRO logic_summary="Builds a CTE mapping each file_statuses key to canonical status, then updates items rows in place." notable_decisions="[]"]
+-- CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+-- CIL[DOC-STABILITY stability="stable"]
+
+-- 032_cil_status_migration.sql
+-- One-time migration: collapse legacy CIL file_statuses into the canonical 0–8 model.
+-- This removes the need for the code to carry legacy status aliases.
+
+WITH mapped_statuses AS (
+  SELECT
+    i.id,
+    jsonb_object_agg(
+      kv.key,
+      CASE kv.value
+        WHEN '0-discovered'     THEN '0-discovered'
+        WHEN '1-selected'       THEN '1-selected'
+        WHEN '2-chunked'        THEN '2-chunked'
+        WHEN '3-documented'     THEN '3-documented'
+        WHEN '4-chunk-validated' THEN '4-chunk-validated'
+        WHEN '5-doc-validated'  THEN '5-doc-validated'
+        WHEN '6-enriched'       THEN '6-enriched'
+        WHEN '7-embedded-mapped' THEN '7-embedded-mapped'
+        WHEN '8-published'      THEN '8-published'
+        -- Legacy aliases
+        WHEN '2-discovered'     THEN '0-discovered'
+        WHEN '3-selected'       THEN '1-selected'
+        WHEN '4-chunked'        THEN '2-chunked'
+        WHEN '5-documented'     THEN '3-documented'
+        WHEN '4-embedded'       THEN '7-embedded-mapped'
+        WHEN '5-mapped'         THEN '7-embedded-mapped'
+        WHEN '6-embedded'       THEN '7-embedded-mapped'
+        WHEN '7-mapped'         THEN '7-embedded-mapped'
+        WHEN '7-embedded'       THEN '7-embedded-mapped'
+        WHEN '7-embedded-2'     THEN '7-embedded-mapped'
+        WHEN '7.5-selected'     THEN '1-selected'
+        WHEN '8-mapped'         THEN '7-embedded-mapped'
+        WHEN '8-mapped-2'       THEN '7-embedded-mapped'
+        WHEN '8-enriched'       THEN '6-enriched'
+        WHEN '9-embedded'       THEN '7-embedded-mapped'
+        WHEN '10-mapped'        THEN '7-embedded-mapped'
+        -- Anything else (e.g. stale timestamps or _updated entries) becomes discovered
+        ELSE '0-discovered'
+      END
+    ) AS new_file_statuses
+  FROM items i
+  JOIN jsonb_each_text(i.data -> 'file_statuses') kv
+    ON kv.key NOT LIKE '%\\_updated'
+  WHERE i.data ->> 'kb_type' = 'cil_project'
+    AND i.is_active = true
+  GROUP BY i.id
+)
+UPDATE items
+SET data = jsonb_set(
+        items.data,
+        '{file_statuses}',
+        mapped_statuses.new_file_statuses,
+        true
+      ),
+    updated_at = now()
+FROM mapped_statuses
+WHERE items.id = mapped_statuses.id;
+-- CIL[DOC-VECTOR type="context" content="purpose='One-time SQL migration: collapse legacy CIL file_statuses into the canonical 0-8 model.'; No verified external callers; imports: none"]
+-- CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+-- CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+-- CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+-- CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+-- CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+-- CIL[END stable_id="~/.framework/migrations/032_cil_status_migration.sql:cil_status_migration:file"]

package/.framework/migrations/033_cil_versioning.sql

@@ -0,0 +1,73 @@
+-- CIL[BEGIN stable_id="~/.framework/migrations/033_cil_versioning.sql:cil_versioning:file" type="file" identity="cil_versioning" parent="~/.framework/migrations/033_cil_versioning.sql"]
+-- CIL[DOC-MACRO purpose="Add manifest, diff, and customer/version packaging fields to CIL versioning schema"]
+-- CIL[DOC-RESPONSIBILITY responsibility="Applies design_schema metadata updates for cil_version, cil_project, cil_file, and cil_chunk types"]
+-- CIL[DOC-CONTEXT module="migrations" layer="data" related_files=".framework/migrations/033_cil_versioning.sql"]
+-- CIL[DOC-CONTRACT inputs="spine-core app slug; existing public.types rows for cil_version, cil_project, cil_file, cil_chunk" outputs="updated design_schema with new fields" errors="app not found; type not found or missing design_schema fields" side_effects="modifies public.types.design_schema in place"]
+-- CIL[DOC-MICRO logic_summary="Lookup the spine-core app id, then use jsonb_set to append new json/text/boolean fields to each target type's design_schema fields" notable_decisions="[]"]
+-- CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+-- CIL[DOC-STABILITY stability="stable"]
+-- CIL versioning schema: add manifest, diff, and customer/version packaging fields to existing CIL types.
+-- This migration only updates design_schema metadata; runtime data is stored in items.data as jsonb.
+DO $$
+DECLARE
+  v_spine_core_app_id uuid;
+BEGIN
+  SELECT id INTO v_spine_core_app_id FROM public.apps WHERE slug = 'spine-core' LIMIT 1;
+
+  -- Extend cil_version with manifest, diff, and packaging fields
+  UPDATE public.types
+  SET design_schema = jsonb_set(
+    design_schema,
+    '{fields}'::text[],
+    (design_schema->'fields') || '{
+      "manifest": {"data_type": "json", "label": "Version Manifest", "required": false},
+      "diff": {"data_type": "json", "label": "Version Diff", "required": false},
+      "parent_version_id": {"data_type": "text", "label": "Parent Version ID", "required": false},
+      "npm_name": {"data_type": "text", "label": "NPM Package Name", "required": false},
+      "npm_version": {"data_type": "text", "label": "NPM Version", "required": false},
+      "is_customer": {"data_type": "boolean", "label": "Is Customer Version", "required": false},
+      "base_spine_version_id": {"data_type": "text", "label": "Base Spine Version ID", "required": false},
+      "spine_source_version_id": {"data_type": "text", "label": "Spine Source Version ID", "required": false}
+    }'::jsonb
+  )
+  WHERE kind = 'item' AND slug = 'cil_version' AND app_id = v_spine_core_app_id;
+
+  -- Extend cil_project with customer versioning fields
+  UPDATE public.types
+  SET design_schema = jsonb_set(
+    design_schema,
+    '{fields}'::text[],
+    (design_schema->'fields') || '{
+      "installed_spine_version_id": {"data_type": "text", "label": "Installed Spine Version ID", "required": false},
+      "target_spine_version_id": {"data_type": "text", "label": "Target Spine Version ID", "required": false},
+      "customer_version_id": {"data_type": "text", "label": "Customer Version ID", "required": false},
+      "customer_npm_name": {"data_type": "text", "label": "Customer NPM Name", "required": false},
+      "customized_paths": {"data_type": "json", "label": "Customized Paths", "required": false},
+      "pending_merges": {"data_type": "json", "label": "Pending Merges", "required": false}
+    }'::jsonb
+  )
+  WHERE kind = 'item' AND slug = 'cil_project' AND app_id = v_spine_core_app_id;
+
+  -- Extend cil_file and cil_chunk with spine/customer version tracking fields
+  UPDATE public.types
+  SET design_schema = jsonb_set(
+    design_schema,
+    '{fields}'::text[],
+    (design_schema->'fields') || '{
+      "spine_version_id": {"data_type": "text", "label": "Spine Version ID", "required": false},
+      "customer_version_id": {"data_type": "text", "label": "Customer Version ID", "required": false},
+      "customized": {"data_type": "boolean", "label": "Customized", "required": false},
+      "pending_spine_version_id": {"data_type": "text", "label": "Pending Spine Version ID", "required": false},
+      "pending_spine_source_id": {"data_type": "text", "label": "Pending Spine Source ID", "required": false}
+    }'::jsonb
+  )
+  WHERE kind = 'item' AND slug IN ('cil_file', 'cil_chunk') AND app_id = v_spine_core_app_id;
+
+END $$;
+-- CIL[DOC-VECTOR type="context" content="purpose='Add manifest, diff, and customer/version packaging fields to CIL versioning schema'; No verified external callers; imports: none"]
+-- CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+-- CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+-- CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+-- CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+-- CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+-- CIL[END stable_id="~/.framework/migrations/033_cil_versioning.sql:cil_versioning:file"]

package/.framework/migrations/034_match_embeddings_knn.sql

@@ -0,0 +1,115 @@
+-- CIL[BEGIN stable_id="~/.framework/migrations/034_match_embeddings_knn.sql:match_embeddings_knn:file" type="file" identity="match_embeddings_knn" parent="~/.framework/migrations/034_match_embeddings_knn.sql"]
+-- CIL[DOC-MACRO purpose="Rework match_embeddings to use KNN-first oversampling and a higher statement timeout"]
+-- CIL[DOC-RESPONSIBILITY responsibility="Replace the match_embeddings RPC so filtered semantic search uses the HNSW index instead of a filtered btree scan + heapsort"]
+-- CIL[DOC-CONTEXT module="migrations" layer="database" related_files=".framework/migrations/005_core_observability.sql,.framework/functions/_shared/agent-runner.ts"]
+-- CIL[DOC-CONTRACT inputs="existing public.match_embeddings function and embeddings table" outputs="replaced function with same signature and result shape" errors="requires pgvector >= 0.8 for hnsw.iterative_scan" side_effects="drops the superseded 5-arg overload; raises the function statement_timeout to 25s"]
+-- CIL[DOC-MICRO logic_summary="When filter_document_ids is set, keep the filter-first query (document-targeted lookup). Otherwise oversample the HNSW KNN index (match_count*10, min 100) with hnsw.iterative_scan=strict_order, then apply account/vector_type/item_type/similarity filters outside the subquery" notable_decisions="Filters moved outside the ORDER BY subquery because the planner mis-estimates account_id selectivity (rows=23 vs ~3k actual) and picks embeddings_active_idx, scanning+sorting every matching row and intermittently exceeding the 8s PostgREST statement_timeout"]
+-- CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+-- CIL[DOC-STABILITY stability="stable"]
+-- CIL[DOC-LEARNING topic="filtered_knn" content="On Postgres + pgvector, putting a selective filter (account_id) in the same query as ORDER BY embedding <=> q lets the planner pick a btree + heapsort over the HNSW index; isolate the KNN ORDER BY/LIMIT in a subquery it cannot flatten, then post-filter. hnsw.iterative_scan=strict_order (pgvector 0.8) is required or the scan stops at ef_search (40) rows"]
+-- CIL[DOC-VECTOR type="context" content="purpose='Rework match_embeddings to use KNN-first oversampling and a higher statement timeout'; no verified external callers; imports: none"]
+-- CIL[DOC-VECTOR type="blast_radius" content="Affects all callers of the match_embeddings RPC: agent-runner retrieveKnowledge, kb.ts, cil-embeddings, embeddings.ts, eval-harness, custom_kb-embeddings"]
+-- CIL[DOC-VECTOR type="configuration" content="Requires pgvector 0.8+; function statement_timeout set to 25s (under the 30s lambda cap)"]
+-- CIL[DOC-VECTOR type="constraint" content="Result shape and parameter signature unchanged; empty filter_document_ids array returns no rows as before"]
+-- CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+-- CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+
+-- match_embeddings was intermittently exceeding the 8s statement_timeout on
+-- PostgREST roles: the planner mis-estimates the account_id filter
+-- (rows=23 vs ~3k actual) and picks embeddings_active_idx, scanning and
+-- sorting every matching row. Restructure so the KNN scan runs through the
+-- HNSW index first (oversampled), with filters applied to the candidates.
+
+DROP FUNCTION IF EXISTS public.match_embeddings(vector, integer, uuid[], text, double precision);
+DROP FUNCTION IF EXISTS public.match_embeddings(vector, integer, uuid[], text, real);
+
+CREATE OR REPLACE FUNCTION public.match_embeddings(
+  query_embedding      vector(1536),
+  match_count          int            DEFAULT 10,
+  filter_account_ids   uuid[]         DEFAULT NULL,
+  filter_vector_type   text           DEFAULT NULL,
+  similarity_threshold float          DEFAULT 0.15,
+  filter_item_types    text[]         DEFAULT NULL,
+  filter_document_ids  text[]         DEFAULT NULL
+)
+RETURNS TABLE (
+  id              uuid,
+  document_id     text,
+  content         text,
+  metadata        jsonb,
+  account_id      uuid,
+  similarity      float
+)
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+SET statement_timeout = '25s'
+AS $$
+BEGIN
+  -- Document-targeted lookups stay filter-first: a global KNN oversample
+  -- would crowd out the requested documents before they can be scored.
+  IF filter_document_ids IS NOT NULL THEN
+    RETURN QUERY
+    SELECT
+      e.id,
+      e.document_id,
+      e.content,
+      e.metadata,
+      e.account_id,
+      1 - (e.embedding <=> query_embedding) AS similarity
+    FROM public.embeddings e
+    WHERE
+      (filter_account_ids IS NULL OR e.account_id = ANY(filter_account_ids))
+      AND (filter_vector_type IS NULL OR e.metadata->>'vector_type' = filter_vector_type)
+      AND (filter_item_types IS NULL OR e.metadata->>'item_type' = ANY(filter_item_types))
+      AND e.document_id = ANY(filter_document_ids)
+      AND e.approved_at IS NOT NULL
+      AND e.revoked_at IS NULL
+      AND (1 - (e.embedding <=> query_embedding)) >= similarity_threshold
+    ORDER BY e.embedding <=> query_embedding
+    LIMIT match_count;
+    RETURN;
+  END IF;
+
+  -- KNN-first: oversample the HNSW index, then apply filters. Keeping the
+  -- filters out of the ORDER BY subquery stops the planner choosing the
+  -- account btree; strict_order lets the scan iterate past ef_search.
+  PERFORM set_config('hnsw.iterative_scan', 'strict_order', true);
+  RETURN QUERY
+  SELECT
+    t.id,
+    t.document_id,
+    t.content,
+    t.metadata,
+    t.account_id,
+    t.similarity
+  FROM (
+    SELECT
+      e.id,
+      e.document_id,
+      e.content,
+      e.metadata,
+      e.account_id,
+      e.approved_at,
+      e.revoked_at,
+      1 - (e.embedding <=> query_embedding) AS similarity
+    FROM public.embeddings e
+    ORDER BY e.embedding <=> query_embedding
+    LIMIT GREATEST(match_count * 10, 100)
+  ) t
+  WHERE
+    (filter_account_ids IS NULL OR t.account_id = ANY(filter_account_ids))
+    AND (filter_vector_type IS NULL OR t.metadata->>'vector_type' = filter_vector_type)
+    AND (filter_item_types IS NULL OR t.metadata->>'item_type' = ANY(filter_item_types))
+    AND t.approved_at IS NOT NULL
+    AND t.revoked_at IS NULL
+    AND t.similarity >= similarity_threshold
+  ORDER BY t.similarity DESC
+  LIMIT match_count;
+END
+$$;
+
+GRANT EXECUTE ON FUNCTION public.match_embeddings(
+  vector(1536), int, uuid[], text, float, text[], text[]
+) TO authenticated, service_role;
+-- CIL[END stable_id="~/.framework/migrations/034_match_embeddings_knn.sql:match_embeddings_knn:file"]