spine-framework 0.3.145 → 0.4.1

package/.framework/migrations/035_rate_limits.sql

@@ -0,0 +1,55 @@
+-- CIL[BEGIN stable_id="~/.framework/migrations/035_rate_limits.sql:rate_limits:file" type="file" identity="rate_limits" parent="~/.framework/migrations/035_rate_limits.sql"]
+-- CIL[DOC-MACRO purpose="DB-backed fixed-window rate limiting primitives"]
+-- CIL[DOC-RESPONSIBILITY responsibility="Provide a rate_limits counter table and an atomic rate_limit_hit RPC used by _shared/rate-limit.ts"]
+-- CIL[DOC-CONTEXT module="migrations" layer="data" related_files=".framework/functions/_shared/rate-limit.ts"]
+-- CIL[DOC-CONTRACT inputs="none" outputs="public.rate_limits table, public.rate_limit_hit function" errors="none" side_effects="Creates table, index, grants"]
+-- CIL[DOC-MICRO logic_summary="Create rate_limits(key, window_start, count) with composite PK; rate_limit_hit upserts and increments the counter atomically inside one statement" notable_decisions="Atomic increment via INSERT ON CONFLICT so concurrent serverless invocations cannot double-spend a window"]
+-- CIL[DOC-STABILITY stability="stable"]
+
+-- Rate-limit counters are infrastructure state, not domain records — a plain
+-- table, service-role only. Never readable by tenant principals.
+CREATE TABLE IF NOT EXISTS public.rate_limits (
+  key          text        NOT NULL,
+  window_start timestamptz NOT NULL,
+  count        integer     NOT NULL DEFAULT 0,
+  updated_at   timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (key, window_start)
+);
+
+ALTER TABLE public.rate_limits ENABLE ROW LEVEL SECURITY;
+
+-- No policies: tenant principals get no access. All access is via the
+-- SECURITY DEFINER function below or the service role.
+
+-- Atomic hit: inserts or increments the counter for (key, window_start) and
+-- returns the new count. One round-trip, safe under concurrency.
+CREATE OR REPLACE FUNCTION public.rate_limit_hit(p_key text, p_window_start timestamptz)
+RETURNS integer
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+DECLARE
+  v_count integer;
+BEGIN
+  INSERT INTO public.rate_limits (key, window_start, count)
+  VALUES (p_key, p_window_start, 1)
+  ON CONFLICT (key, window_start)
+  DO UPDATE SET count = public.rate_limits.count + 1,
+                updated_at = now()
+  RETURNING count INTO v_count;
+  RETURN v_count;
+END;
+$$;
+
+REVOKE ALL ON FUNCTION public.rate_limit_hit(text, timestamptz) FROM PUBLIC;
+REVOKE ALL ON FUNCTION public.rate_limit_hit(text, timestamptz) FROM anon;
+REVOKE ALL ON FUNCTION public.rate_limit_hit(text, timestamptz) FROM authenticated;
+GRANT EXECUTE ON FUNCTION public.rate_limit_hit(text, timestamptz) TO service_role;
+-- CIL[DOC-VECTOR type="context" content="purpose='DB-backed fixed-window rate limiting primitives'; 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="Table is RLS-enabled with no tenant policies; only the SECURITY DEFINER RPC or service role may touch it"]
+-- 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/035_rate_limits.sql:rate_limits:file"]

package/.framework/migrations/036_demo_record_flags.sql

@@ -0,0 +1,72 @@
+-- CIL[BEGIN stable_id="~/.framework/migrations/036_demo_record_flags.sql:demo_record_flags:file" type="file" identity="demo_record_flags" parent="~/.framework/migrations/036_demo_record_flags.sql"]
+-- CIL[DOC-MACRO purpose="Auto-stamp data.is_demo / data.demo_run_id on runtime records created under demo accounts"]
+-- CIL[DOC-RESPONSIBILITY responsibility="Provide apply_demo_flag() trigger function and attach it to runtime tables so every write path (admin-data, adminDb, seeds) flags demo-owned records"]
+-- CIL[DOC-CONTEXT module="migrations" layer="data" related_files=".framework/functions/_shared/funnel.ts,.framework/functions/admin-data.ts"]
+-- CIL[DOC-CONTRACT inputs="accounts.data.is_demo + accounts.data.demo_run_id on the row's account" outputs="NEW.data with reserved keys is_demo/demo_run_id set or stripped" errors="none — missing account defaults to non-demo" side_effects="Mutates NEW.data on INSERT/UPDATE"]
+-- CIL[DOC-MICRO logic_summary="BEFORE INSERT OR UPDATE: look up NEW.account_id's account flag; demo accounts get is_demo=true + demo_run_id merged into data, non-demo accounts get the reserved keys stripped so clients cannot forge them" notable_decisions="DB trigger chosen over admin-data stamping so agent-runner/support-triage adminDb writes are flagged identically; strip on non-demo makes the flag unforgeable"]
+-- CIL[DOC-STABILITY stability="stable"]
+
+CREATE OR REPLACE FUNCTION public.apply_demo_flag()
+RETURNS trigger
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+DECLARE
+  v_is_demo boolean;
+  v_run_id  text;
+BEGIN
+  -- accounts has no account_id; nothing to derive from.
+  IF NEW.account_id IS NULL THEN
+    RETURN NEW;
+  END IF;
+
+  SELECT (a.data->>'is_demo')::boolean, a.data->>'demo_run_id'
+    INTO v_is_demo, v_run_id
+    FROM public.accounts a
+   WHERE a.id = NEW.account_id;
+
+  IF COALESCE(v_is_demo, false) THEN
+    NEW.data := COALESCE(NEW.data, '{}'::jsonb)
+                || jsonb_build_object('is_demo', true);
+    IF v_run_id IS NOT NULL THEN
+      NEW.data := NEW.data || jsonb_build_object('demo_run_id', v_run_id);
+    END IF;
+  ELSE
+    -- Reserved keys are server-owned; strip any client-supplied values.
+    NEW.data := COALESCE(NEW.data, '{}'::jsonb) - 'is_demo' - 'demo_run_id';
+  END IF;
+
+  RETURN NEW;
+END;
+$$;
+
+-- Attach to every runtime entity that carries an account_id + data payload.
+DO $$
+DECLARE
+  t text;
+BEGIN
+  FOREACH t IN ARRAY ARRAY['items', 'threads', 'messages', 'links', 'attachments', 'watchers', 'people']
+  LOOP
+    EXECUTE format('DROP TRIGGER IF EXISTS trg_demo_flag ON public.%I', t);
+    EXECUTE format(
+      'CREATE TRIGGER trg_demo_flag BEFORE INSERT OR UPDATE ON public.%I FOR EACH ROW EXECUTE FUNCTION public.apply_demo_flag()',
+      t
+    );
+  END LOOP;
+END $$;
+
+-- Backfill: flag existing rows belonging to demo accounts that predate the trigger.
+UPDATE public.items i
+   SET data = i.data || jsonb_build_object('is_demo', true)
+  FROM public.accounts a
+ WHERE i.account_id = a.id
+   AND (a.data->>'is_demo')::boolean IS TRUE
+   AND COALESCE(i.data->>'is_demo', 'false') <> 'true';
+-- CIL[DOC-VECTOR type="context" content="purpose='Auto-stamp data.is_demo / data.demo_run_id on runtime records created under demo accounts'; 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="Reserved keys is_demo/demo_run_id are server-owned on all runtime tables; clients cannot set or clear them"]
+-- 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/036_demo_record_flags.sql:demo_record_flags:file"]

package/.framework/migrations/037_kb_types_canonical.sql

@@ -0,0 +1,244 @@
+-- 037_kb_types_canonical.sql
+-- Canonical knowledge-base item types. kb-account and kb-spine-public were
+-- previously created only by the archived 046_kb_types.sql consolidation, so
+-- fresh installs never received them even though 007_kb_article_list.sql
+-- references both slugs. This migration:
+--   1. Inserts the types when missing (idempotent).
+--   2. Merges demo-flag fields (is_demo, demo_run_id) and the member_admin
+--      grant into existing design_schema rows without clobbering them.
+--   3. Adds source_ticket_id to kb-account for ticket→article candidate links.
+
+-- ─── INSERT: kb-account (fresh installs) ────────────────────────────────────
+
+INSERT INTO public.types (app_id, kind, slug, name, description, icon, color, design_schema, validation_schema, ownership, is_active)
+VALUES (
+  NULL,
+  'item',
+  'kb-account',
+  'KB Account',
+  'Account-specific knowledge base articles',
+  'briefcase',
+  '#3B82F6',
+  $DS$
+  {
+    "scope": "account",
+    "fields": {
+      "title": { "data_type": "text", "label": "Title", "required": true, "system": true },
+      "description": { "data_type": "textarea", "label": "Description", "required": false, "system": true },
+      "status": { "data_type": "select", "label": "Status", "required": true, "system": true, "options": ["draft", "published", "archived"] },
+      "content": { "data_type": "textarea", "label": "Content", "required": true },
+      "tags": { "data_type": "multiselect", "label": "Tags", "required": false, "options": ["support", "how-to", "faq", "tutorial"] },
+      "category": { "data_type": "multiselect", "label": "Category", "required": false, "options": ["how-to", "runbook", "policy", "faq", "tutorial"] },
+      "product": { "data_type": "multiselect", "label": "Product", "required": false, "options": ["spine-framework", "cortex", "workbench", "portal"] },
+      "version": { "data_type": "text", "label": "Version", "required": false },
+      "last_reviewed_at": { "data_type": "datetime", "label": "Last Reviewed", "required": false },
+      "reviewer_id": { "data_type": "text", "label": "Reviewer ID", "required": false },
+      "is_ai_generated": { "data_type": "boolean", "label": "AI Generated", "required": false },
+      "customer_segment": { "data_type": "multiselect", "label": "Customer Segment", "required": false, "options": ["enterprise", "startup", "all"] },
+      "feature_flag": { "data_type": "text", "label": "Feature Flag", "required": false },
+      "work_ticket_id": { "data_type": "text", "label": "Work Ticket ID", "required": false },
+      "source_ticket_id": { "data_type": "text", "label": "Source Ticket ID", "required": false },
+      "source_file": { "data_type": "text", "label": "Source File Path", "required": false },
+      "source_function": { "data_type": "text", "label": "Source Function", "required": false },
+      "is_demo": { "data_type": "boolean", "label": "Is Demo", "required": false },
+      "demo_run_id": { "data_type": "text", "label": "Demo Run ID", "required": false }
+    },
+    "views": {
+      "default_list": {
+        "type": "list",
+        "display": "table",
+        "label": "Account Articles",
+        "fields": {
+          "title": { "sortable": true, "display_type": "text" },
+          "status": { "sortable": true, "display_type": "badge" },
+          "product": { "sortable": true, "display_type": "text" },
+          "created_at": { "sortable": true, "display_type": "timestamp" }
+        },
+        "default_sort": { "field": "created_at", "direction": "desc" }
+      },
+      "default_detail": {
+        "type": "detail",
+        "label": "Article",
+        "sections": [
+          { "title": "Core", "fields": { "title": { "display_type": "input" }, "status": { "display_type": "select" }, "description": { "display_type": "textarea" }, "content": { "display_type": "textarea" } } },
+          { "title": "Categorization", "fields": { "tags": { "display_type": "multiselect" }, "category": { "display_type": "multiselect" }, "product": { "display_type": "multiselect" }, "version": { "display_type": "text" } } },
+          { "title": "Review", "fields": { "last_reviewed_at": { "display_type": "timestamp" }, "reviewer_id": { "display_type": "text" }, "is_ai_generated": { "display_type": "checkbox" } } },
+          { "title": "Context", "fields": { "work_ticket_id": { "display_type": "text" }, "source_ticket_id": { "display_type": "text" }, "source_file": { "display_type": "text" }, "source_function": { "display_type": "text" } } }
+        ]
+      }
+    },
+    "record_permissions": {
+      "system_admin": ["create", "read", "update", "delete"],
+      "support": ["create", "read", "update"],
+      "support_admin": ["create", "read", "update", "delete"],
+      "engineering_admin": ["create", "read", "update"],
+      "engineering": ["create", "read", "update"],
+      "devops": ["create", "read", "update"],
+      "incident_commander": ["create", "read", "update"],
+      "member": ["create", "read", "update"],
+      "member_admin": ["create", "read", "update", "delete"]
+    },
+    "functionality": {
+      "kb": {
+        "vector_fields": ["title", "description", "content", "tags"],
+        "chunk_field": "content",
+        "chunk_size": 800,
+        "chunk_overlap": 100
+      }
+    }
+  }
+  $DS$::jsonb,
+  '{}'::jsonb,
+  'system',
+  true
+)
+ON CONFLICT (kind, slug) DO NOTHING;
+
+-- ─── INSERT: kb-spine-public (fresh installs) ───────────────────────────────
+-- Minimal canonical definition; deployed databases already carry the full
+-- schema from 046 and take the UPDATE path below instead.
+
+INSERT INTO public.types (app_id, kind, slug, name, description, icon, color, design_schema, validation_schema, ownership, is_active)
+VALUES (
+  NULL,
+  'item',
+  'kb-spine-public',
+  'Spine KB Public',
+  'Public Spine knowledge base articles readable by all accounts',
+  'book-open',
+  '#10B981',
+  $DS$
+  {
+    "scope": "platform",
+    "fields": {
+      "title": { "data_type": "text", "label": "Title", "required": true, "system": true },
+      "description": { "data_type": "textarea", "label": "Description", "required": false, "system": true },
+      "status": { "data_type": "select", "label": "Status", "required": true, "system": true, "options": ["draft", "published", "archived"] },
+      "content": { "data_type": "textarea", "label": "Content", "required": true },
+      "tags": { "data_type": "multiselect", "label": "Tags", "required": false, "options": ["support", "how-to", "faq", "tutorial"] },
+      "category": { "data_type": "multiselect", "label": "Category", "required": false, "options": ["how-to", "runbook", "policy", "faq", "tutorial"] },
+      "product": { "data_type": "multiselect", "label": "Product", "required": false, "options": ["spine-framework", "cortex", "workbench", "portal"] },
+      "version": { "data_type": "text", "label": "Version", "required": false },
+      "is_demo": { "data_type": "boolean", "label": "Is Demo", "required": false },
+      "demo_run_id": { "data_type": "text", "label": "Demo Run ID", "required": false }
+    },
+    "views": {
+      "default_list": {
+        "type": "list",
+        "display": "table",
+        "label": "Public Articles",
+        "fields": {
+          "title": { "sortable": true, "display_type": "text" },
+          "status": { "sortable": true, "display_type": "badge" },
+          "created_at": { "sortable": true, "display_type": "timestamp" }
+        },
+        "default_sort": { "field": "created_at", "direction": "desc" }
+      },
+      "default_detail": {
+        "type": "detail",
+        "label": "Article",
+        "sections": [
+          { "title": "Core", "fields": { "title": { "display_type": "input" }, "status": { "display_type": "select" }, "description": { "display_type": "textarea" }, "content": { "display_type": "textarea" } } }
+        ]
+      }
+    },
+    "record_permissions": {
+      "system_admin": ["create", "read", "update", "delete"],
+      "support": ["create", "read", "update"],
+      "support_admin": ["create", "read", "update", "delete"],
+      "engineering_admin": ["create", "read", "update"],
+      "engineering": ["create", "read", "update"],
+      "devops": ["create", "read", "update"],
+      "incident_commander": ["create", "read", "update"],
+      "member": ["read"],
+      "member_admin": ["read"]
+    },
+    "functionality": {
+      "kb": {
+        "vector_fields": ["title", "description", "content", "tags"],
+        "chunk_field": "content",
+        "chunk_size": 800,
+        "chunk_overlap": 100
+      }
+    }
+  }
+  $DS$::jsonb,
+  '{}'::jsonb,
+  'system',
+  true
+)
+ON CONFLICT (kind, slug) DO NOTHING;
+
+-- ─── UPDATE: converge existing rows ─────────────────────────────────────────
+-- Merge demo-flag + linkage fields and the member_admin grant into existing
+-- design_schema JSON without replacing fields added since 046.
+
+UPDATE public.types
+SET design_schema = jsonb_set(
+      jsonb_set(
+        design_schema,
+        '{fields}',
+        (design_schema->'fields') || $F${
+          "is_demo": { "data_type": "boolean", "label": "Is Demo", "required": false },
+          "demo_run_id": { "data_type": "text", "label": "Demo Run ID", "required": false },
+          "source_ticket_id": { "data_type": "text", "label": "Source Ticket ID", "required": false }
+        }$F$::jsonb,
+        true
+      ),
+      '{record_permissions}',
+      (design_schema->'record_permissions') || $P${
+        "member_admin": ["create", "read", "update", "delete"],
+        "member": ["create", "read", "update"]
+      }$P$::jsonb,
+      true
+    )
+WHERE slug = 'kb-account' AND kind = 'item';
+
+UPDATE public.types
+SET design_schema = jsonb_set(
+      jsonb_set(
+        design_schema,
+        '{fields}',
+        (design_schema->'fields') || $F${
+          "is_demo": { "data_type": "boolean", "label": "Is Demo", "required": false },
+          "demo_run_id": { "data_type": "text", "label": "Demo Run ID", "required": false }
+        }$F$::jsonb,
+        true
+      ),
+      '{record_permissions}',
+      (design_schema->'record_permissions') || $P${
+        "member_admin": ["read"],
+        "member": ["read"]
+      }$P$::jsonb,
+      true
+    )
+WHERE slug = 'kb-spine-public' AND kind = 'item';
+
+-- Merge the same flag fields into the Portal-owned support types so the demo
+-- flag survives sanitizeRecordData on reads. These UPDATEs are no-ops on
+-- databases where the seed has not installed the slugs yet — the portal seed
+-- types.json now carries the fields for fresh installs.
+UPDATE public.types
+SET design_schema = jsonb_set(
+      design_schema,
+      '{fields}',
+      (design_schema->'fields') || $F${
+        "is_demo": { "data_type": "boolean", "label": "Is Demo", "required": false },
+        "demo_run_id": { "data_type": "text", "label": "Demo Run ID", "required": false }
+      }$F$::jsonb,
+      true
+    )
+WHERE (kind, slug) IN (('item', 'support_ticket'), ('thread', 'support_thread'));
+
+UPDATE public.types
+SET design_schema = jsonb_set(
+      design_schema,
+      '{fields}',
+      (design_schema->'fields') || $F${
+        "is_demo": { "data_type": "boolean", "label": "Is Demo", "required": false },
+        "demo_run_id": { "data_type": "text", "label": "Demo Run ID", "required": false },
+        "escalation_notice": { "data_type": "boolean", "label": "Escalation Notice", "required": false }
+      }$F$::jsonb,
+      true
+    )
+WHERE kind = 'message' AND slug = 'support_reply';

package/.framework/migrations/038_drop_demo_record_flags.sql

@@ -0,0 +1,38 @@
+-- CIL[BEGIN stable_id="~/.framework/migrations/038_drop_demo_record_flags.sql:drop_demo_record_flags:file" type="file" identity="drop_demo_record_flags" parent="~/.framework/migrations/038_drop_demo_record_flags.sql"]
+-- CIL[DOC-MACRO purpose="Remove record-level is_demo flagging in favor of demo-specific types for content isolation"]
+-- CIL[DOC-RESPONSIBILITY responsibility="Drop trg_demo_flag triggers and apply_demo_flag() (migration 036); strip is_demo/demo_run_id from existing runtime records. Record visibility is now isolated by demo_* types; accounts.data.is_demo remains a lifecycle-only marker (expiry, rate-limit policy, funnel tagging)"]
+-- CIL[DOC-CONTEXT module="migrations" layer="data" related_files="custom/apps/demo/seed/types.json,custom/apps/demo/functions/custom_demo-journey.ts,custom/apps/portal/functions/custom_support-triage.ts"]
+-- CIL[DOC-CONTRACT inputs="trg_demo_flag triggers + apply_demo_flag() from migration 036" outputs="triggers/function dropped; records unflagged" errors="none" side_effects="Runtime records can no longer be marked is_demo; accounts.data.is_demo is managed solely by demo provision"]
+-- CIL[DOC-MICRO logic_summary="Demo content isolation moved to type-based scoping (demo_support_ticket, demo_support_thread). Accounts and people are never demo-flagged — they are real leads for Cortex." notable_decisions="Type isolation chosen over record flags so demo play can run inside shared accounts without hiding real records"]
+-- CIL[DOC-STABILITY stability="stable"]
+
+DO $$
+DECLARE
+  t text;
+BEGIN
+  FOREACH t IN ARRAY ARRAY['items', 'threads', 'messages', 'links', 'attachments', 'watchers', 'people']
+  LOOP
+    EXECUTE format('DROP TRIGGER IF EXISTS trg_demo_flag ON public.%I', t);
+  END LOOP;
+END $$;
+
+DROP FUNCTION IF EXISTS public.apply_demo_flag();
+
+-- Unflag any runtime records that were stamped while the trigger was active.
+DO $$
+DECLARE
+  t text;
+BEGIN
+  FOREACH t IN ARRAY ARRAY['items', 'threads', 'messages', 'links', 'attachments', 'watchers', 'people']
+  LOOP
+    EXECUTE format(
+      'UPDATE public.%I SET data = data - ''is_demo'' - ''demo_run_id'' WHERE data ? ''is_demo'' OR data ? ''demo_run_id''',
+      t
+    );
+  END LOOP;
+END $$;
+-- CIL[DOC-VECTOR type="context" content="purpose='Remove record-level is_demo flagging in favor of demo-specific types'; No verified external callers; imports: none" status="ready"]
+-- CIL[DOC-VECTOR type="blast_radius" content="admin-data demo_only/exclude_demo params become no-ops; demo visibility now enforced by type_slug scoping" status="ready"]
+-- CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified" status="ready"]
+-- CIL[DOC-VECTOR type="constraint" content="accounts.data.is_demo is still written by demo provision for lifecycle (expiry/rate-limits); it is no longer propagated to records" status="ready"]
+-- CIL[END stable_id="~/.framework/migrations/038_drop_demo_record_flags.sql:drop_demo_record_flags:file"]