spine-framework 0.4.2 → 0.4.4

package/.framework/functions/_shared/cil.ts

@@ -192,7 +192,8 @@ export function computeContentHash(raw: string): string {
            !trimmed.match(/^\/\*\*?\s*CIL\[DOC-/) &&
            !trimmed.match(/^<!--\s*CIL\[(BEGIN|END)/) &&
            !trimmed.match(/^<!--\s*CIL\[DOC-/) &&
-           !trimmed.match(/^#\s*CIL\[(BEGIN|END|DOC-)/)
+           !trimmed.match(/^#\s*CIL\[(BEGIN|END|DOC-)/) &&
+           !trimmed.match(/^--\s*CIL\[(BEGIN|END|DOC-)/)
   })
   const collapsed: string[] = []
   let lastBlank = false

package/.framework/functions/_shared/db.ts

@@ -3,7 +3,7 @@
 // CIL[DOC-RESPONSIBILITY responsibility="Owns the shared Supabase client exports and common query joins."]
 // CIL[DOC-CONTEXT module="functions/_shared/db" layer="data-access" related_files=".framework/functions/_shared/db.ts"]
 // CIL[DOC-CONTRACT inputs="[]" outputs="adminDb, getUserDb, DbResult, joins, constants" errors="[]" side_effects="[]"]
-// CIL[DOC-MICRO logic_summary="Imports the Supabase client and WebSocket transport, then exports configured admin/user clients, a result type, and join mappings." notable_decisions="Falls back to placeholder credentials when environment values are absent."]
+// CIL[DOC-MICRO logic_summary="Imports the Supabase client and exports configured admin/user clients, a result type, and join mappings. WebSocket/ws realtime transport removed — server-side functions never subscribe to Supabase channels." notable_decisions="Falls back to placeholder credentials when environment values are absent. Realtime transport removed to reduce bundle size and eliminate unnecessary module-level initialization."]
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
 // CIL[DOC-AUDIENCE audience="human"]
@@ -14,7 +14,6 @@
 
 
 import { createClient } from '@supabase/supabase-js'
-import WebSocket from 'ws'
 // CIL[DOC-VECTOR type="context" content="purpose='Supabase client and database relation join module'; 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"]
@@ -241,12 +240,11 @@ const dbSchema: string = _env.DB_SCHEMA || 'public'
 // CIL[DOC-RESPONSIBILITY responsibility="Exports the admin-authorized Supabase client for backend use."]
 // CIL[DOC-CONTEXT module="functions/_shared/db" layer="data-access" related_files=".framework/functions/_shared/db.ts"]
 // CIL[DOC-CONTRACT inputs="[]" outputs="SupabaseClient adminDb" errors="[]" side_effects="[]"]
-// CIL[DOC-MICRO logic_summary="Creates a createClient instance using supabaseUrl and supabaseServiceKey, sets the schema and WebSocket transport." notable_decisions="Uses service role key for elevated privileges and WebSocket for realtime."]
+// CIL[DOC-MICRO logic_summary="Creates a createClient instance using supabaseUrl and supabaseServiceKey and sets the schema. No realtime transport: server-side functions never subscribe to Supabase channels — omitting the ws transport shrinks every function bundle and eliminates an unnecessary module-level init." notable_decisions="Realtime transport removed: ws import added ~10KB to every bundle and could attempt a WebSocket handshake on module load. REST/PostgREST queries are unaffected."]
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
 export const adminDb = createClient(supabaseUrl, supabaseServiceKey, {
   db: { schema: dbSchema },
-  realtime: { transport: WebSocket as any }
 })
 // CIL[DOC-VECTOR type="context" content="purpose='Admin Supabase client'; No verified external callers; imports: none"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
@@ -262,14 +260,13 @@ export const adminDb = createClient(supabaseUrl, supabaseServiceKey, {
 // CIL[DOC-CONTEXT module="db" layer="functions" related_files=".framework/functions/_shared/db.ts"]
 // CIL[DOC-RESPONSIBILITY responsibility="Creates a Supabase client scoped to an end-user JWT."]
 // CIL[DOC-CONTRACT inputs="jwt: string" outputs="SupabaseClient" errors="[]" side_effects="[]"]
-// CIL[DOC-MICRO logic_summary="Returns a createClient instance using supabaseUrl and supabaseAnonKey, schema, WebSocket transport, and an Authorization header." notable_decisions="Uses the anon key plus Bearer token for row-level security."]
+// CIL[DOC-MICRO logic_summary="Returns a createClient instance using supabaseUrl and supabaseAnonKey, schema, and an Authorization header." notable_decisions="Uses the anon key plus Bearer token for row-level security. Realtime transport omitted for same reasons as adminDb."]
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
 export function getUserDb(jwt: string) {
   return createClient(supabaseUrl, supabaseAnonKey, {
     db: { schema: dbSchema },
     global: { headers: { Authorization: `Bearer ${jwt}` } },
-    realtime: { transport: WebSocket as any }
   })
 }
 // CIL[END stable_id="~/.framework/functions/_shared/db.ts:getUserDb:function"]

package/.framework/functions/_shared/kb.ts

@@ -218,6 +218,43 @@ function getFieldValue(record: any, field: string): string {
   }
   return ''
 }
+
+const UUID_TOKEN_RE = /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/gi
+const HTML_TAG_RE = /<[^>]*>/g
+const HTML_LOOKS_LIKE_RE = /<\/?[a-z][^>]*>/i
+
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/kb.ts:getembeddablefieldvalue:function" type="function" identity="getEmbeddableFieldValue" parent="~/.framework/functions/_shared/kb.ts"]
+// CIL[DOC-MACRO purpose="Normalize a record field into embeddable plain text — strips rich-text HTML and bare UUID tokens"]
+// CIL[DOC-RESPONSIBILITY responsibility="Produce the exact text that feeds both the content-hash lease and the embedder so neither markup nor identifier-only chunks enter the corpus"]
+// CIL[DOC-CONTEXT module="functions/_shared" layer="kb" related_files=".framework/functions/_shared/kb.ts"]
+// CIL[DOC-CONTRACT inputs="record: any, field: string, designSchema: any" outputs="string — normalized text, '' when nothing embeddable remains" errors="[]" side_effects="[]"]
+// CIL[DOC-MICRO logic_summary="rich_text fields (or any value containing tags) run through an HTML-to-text pass; every field then drops bare UUID tokens — reference-id arrays like tag item ids collapse to empty and are skipped" notable_decisions="applied uniformly to all vector fields so the content hash dedupes on the same text the embedder sees"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.85" flags="none"]
+// CIL[DOC-STABILITY stability="internal"]
+function getEmbeddableFieldValue(record: any, field: string, designSchema: any): string {
+  let text = getFieldValue(record, field)
+  if (!text) return ''
+  const dataType = designSchema?.fields?.[field]?.data_type
+  if (dataType === 'rich_text' || HTML_LOOKS_LIKE_RE.test(text)) {
+    text = text
+      .replace(/<\/(p|div|h[1-6]|li|ul|ol|section|article|header|footer|blockquote|tr|table)>/gi, '\n')
+      .replace(/<br\s*\/?>/gi, '\n')
+      .replace(/<li[^>]*>/gi, '\n- ')
+      .replace(HTML_TAG_RE, ' ')
+      .replace(/&nbsp;/gi, ' ')
+      .replace(/&amp;/g, '&')
+      .replace(/&lt;/g, '<')
+      .replace(/&gt;/g, '>')
+      .replace(/&quot;/g, '"')
+      .replace(/&#0?39;|&apos;/g, "'")
+  }
+  return text
+    .replace(UUID_TOKEN_RE, ' ')
+    .replace(/[ \t]+/g, ' ')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim()
+}
+// CIL[END stable_id="~/.framework/functions/_shared/kb.ts:getembeddablefieldvalue:function"]
 // CIL[DOC-VECTOR type="context" content="purpose='Retrieves a flattened string value from a record or its data object.'; No verified external callers; imports: .framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/permissions.ts"]
 // 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"]
@@ -596,7 +633,7 @@ async function clearEmbeddingsForItem(documentId: string): Promise<number> {
 // CIL[DOC-RESPONSIBILITY responsibility="Processes a published KB item, chunks vector fields, and persists embeddings under a content-hash document lease."]
 // CIL[DOC-CONTEXT module="functions/_shared" layer="kb" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/kb.ts,.framework/functions/_shared/llm.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/permissions.ts,.framework/migrations/054_kb_ingest_lease.sql"]
 // CIL[DOC-CONTRACT inputs="ctx: CoreContext, body with id: string and optional account_id" outputs="ok: boolean; message: string; count?: number; in_progress?: boolean" errors="id is required; record not found; database errors" side_effects="revokes previous embeddings; inserts rows into embeddings table; acquires/releases a document_leases row; archives+revokes superseded documents"]
-// CIL[DOC-MICRO logic_summary="Fetches the item, validates status, hashes the declared vector-field values, acquires a document lease ('reused' skips unchanged work, 'processing' reports another worker owns it), then inside try/finally clears stale embeddings, batches chunks into one embeddings call, inserts, and runs supersede_keys-driven supersession before releasing the lease token." notable_decisions="Revokes existing embeddings via clearEmbeddingsForItem (not kbRevoke — that would delete the caller's own lease); supersession is driven by functionality.kb.supersede_keys declared data fields instead of a hardcoded type-slug gate; a fenced release (token mismatch) warns without throwing — the work was written but ownership was lost to a superseding acquire."]
+// CIL[DOC-MICRO logic_summary="Fetches the item, validates status, hashes the normalized vector-field values (rich_text HTML stripped, bare UUID tokens dropped), acquires a document lease ('reused' skips unchanged work, 'processing' reports another worker owns it), then inside try/finally clears stale embeddings, batches chunks into one embeddings call, inserts, and runs supersede_keys-driven supersession before releasing the lease token." notable_decisions="Revokes existing embeddings via clearEmbeddingsForItem (not kbRevoke — that would delete the caller's own lease); supersession is driven by functionality.kb.supersede_keys declared data fields instead of a hardcoded type-slug gate; a fenced release (token mismatch) warns without throwing — the work was written but ownership was lost to a superseding acquire."]
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="internal"]
 // CIL[DOC-NOTE type="contract" content="Lease outcomes: 'reused' returns a live-embeddings count so callers may stamp freshness; 'processing' returns in_progress:true with NO success marker — callers that stamp embedding state must not stamp success or failure for it, the owning worker's completion reconciles the corpus."]
@@ -660,11 +697,12 @@ export async function kbIngest(ctx: CoreContext, body: { id: string; account_id?
   const securityLevel = resolveSecurityLevel(designSchema)
 
   // Content-hash lease (document_leases, migration 054): sha256 over the
-  // declared vector-field values in order — the same text that feeds the
-  // embedder. The lease dedupes unchanged re-embeds and fences concurrent
-  // workers (publish trigger + detached ingest both arrive here).
+  // declared vector-field values in order — the same NORMALIZED text that
+  // feeds the embedder (HTML stripped, bare UUIDs dropped). The lease
+  // dedupes unchanged re-embeds and fences concurrent workers (publish
+  // trigger + detached ingest both arrive here).
   const contentHash = createHash('sha256')
-    .update(vectorFields.map((field: string) => getFieldValue(record, field)).join('\n'))
+    .update(vectorFields.map((field: string) => getEmbeddableFieldValue(record, field, designSchema)).join('\n'))
     .digest('hex')
 
   const { data: lease, error: leaseError } = await adminDb.rpc('acquire_document_lease', {
@@ -703,7 +741,7 @@ export async function kbIngest(ctx: CoreContext, body: { id: string; account_id?
 
     const toEmbed: Array<{ field: string; chunk: string }> = []
     for (const field of vectorFields) {
-      const raw = getFieldValue(record, field)
+      const raw = getEmbeddableFieldValue(record, field, designSchema)
       if (!raw.trim()) continue
 
       const isChunked = field === chunkField && raw.length > chunkSize
@@ -837,10 +875,26 @@ export async function kbIngest(ctx: CoreContext, body: { id: string; account_id?
  * @calls       clearEmbeddingsForItem, adminDb.from('document_leases').delete()
  * @cil-generated
  */
-export async function kbRevoke(ctx: CoreContext, body: { id: string }): Promise<{ ok: boolean; message: string; count?: number }> {
+export async function kbRevoke(ctx: CoreContext, body: { id: string }): Promise<{ ok: boolean; message: string; count?: number; skipped?: boolean }> {
   const { id } = body
   if (!id) throw new Error('id is required')
 
+  // Execution-time fence: a revoke queued by an intermediate
+  // item_updated event (e.g. auto_revoke_on_unpublish fired while a
+  // publish pipeline was mid-flight) executes long after the trigger
+  // condition was true. Re-check the document's CURRENT status — if it
+  // is published now, its embeddings are fresh and must be kept.
+  // Trigger-time evaluation is always stale by the time work runs.
+  const { data: doc } = await adminDb
+    .from('items')
+    .select('status, data')
+    .eq('id', id)
+    .maybeSingle()
+  const docStatus = doc?.status ?? doc?.data?.status
+  if (doc && docStatus === 'published') {
+    return { ok: true, skipped: true, message: 'document is published — embeddings retained', count: 0 }
+  }
+
   const count = await clearEmbeddingsForItem(id)
 
   // Clear any stored lease — a 'completed' lease would otherwise force

package/.framework/functions/_shared/message-sequence.ts

@@ -0,0 +1,53 @@
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/message-sequence.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/functions/_shared/message-sequence.ts"]
+// CIL[DOC-MACRO purpose="Race-safe message sequence allocation for writers outside the agent runner's per-instance counter"]
+// CIL[DOC-RESPONSIBILITY responsibility="Allocate the next sequence value for a thread and retry the caller's insert when a concurrent write collides on UNIQUE(thread_id, sequence)"]
+// CIL[DOC-CONTEXT module="functions/_shared/message-sequence" layer="data-access" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/agent-runner.ts"]
+// CIL[DOC-CONTRACT inputs="threadId: string, insert: (sequence: number) => Promise<T>, maxAttempts?: number" outputs="T — the insert result" errors="rethrows non-duplicate errors and 23505 once attempts are exhausted" side_effects="one sequence read per attempt plus the caller's insert"]
+// CIL[DOC-MICRO logic_summary="Each attempt reads MAX(sequence) fresh then runs the caller's insert; a 23505 means the allocation went stale between read and write, so the loop re-reads and retries" notable_decisions="MAX(sequence)+1 rather than COUNT+1 — sparse or deleted sequences can't cause under-allocation; the insert callback keeps the caller's own create path (admin-data stamping, direct insert) so no shared module reaches into admin-data"]
+// CIL[DOC-LEARNING topic="sequence_allocation" content="Any non-runner writer that computes COUNT(*)+1 then inserts is racy — a concurrent writer on the same thread lands the same sequence and the UNIQUE(thread_id, sequence) constraint throws 23505. All such sites must allocate through insertMessageSequenced (or the runner's allocSequence/persist path). Production evidence: case-analysis finalize 500'd when the detached chain's finalize overlapped the client resumer's kick('finalized')."]
+// CIL[DOC-NOTE type="caution" content="The agent runner has its own per-instance counter (threadSeqCounter + allocSequence) — do not route runner message writes through this helper; this is for custom-app and finalize-path writers that persist one message at a time."]
+// CIL[DOC-AUDIENCE audience="custom app developers writing messages into threads outside runAgent"]
+// CIL[DOC-STABILITY stability="stable"]
+import { adminDb } from './db'
+// CIL[END stable_id="~/.framework/functions/_shared/message-sequence.ts:module_header:module_header"]
+
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/message-sequence.ts:isduplicatekeyerror:function" type="function" identity="isDuplicateKeyError" parent="~/.framework/functions/_shared/message-sequence.ts"]
+// CIL[DOC-MACRO purpose="Detect Postgres 23505 unique-violation errors from admin-data throws or supabase-js error objects"]
+// CIL[DOC-CONTRACT inputs="err: any (thrown error or PostgrestError)" outputs="boolean" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Checks error.code === '23505' and falls back to message matching for wrapped errors" notable_decisions="[]"]
+// CIL[DOC-STABILITY stability="stable"]
+function isDuplicateKeyError(err: any): boolean {
+  return err?.code === '23505' || /23505|duplicate key/i.test(String(err?.message || err || ''))
+}
+// CIL[END stable_id="~/.framework/functions/_shared/message-sequence.ts:isduplicatekeyerror:function"]
+
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/message-sequence.ts:insertmessagesequenced:function" type="function" identity="insertMessageSequenced" parent="~/.framework/functions/_shared/message-sequence.ts"]
+// CIL[DOC-MACRO purpose="Allocate the next message sequence for a thread and run the caller's insert, retrying on unique-violation"]
+// CIL[DOC-RESPONSIBILITY responsibility="Replace the read-count-then-insert pattern (COUNT+1) that collides whenever two writers race on one thread"]
+// CIL[DOC-CONTRACT inputs="threadId, insert: (sequence:number)=>Promise<T>, maxAttempts=3" outputs="insert result" errors="rethrows final error" side_effects="messages read + caller insert"]
+// CIL[DOC-MICRO logic_summary="Reads MAX(sequence) fresh each attempt so a retried insert re-allocates above whatever the racing writer landed" notable_decisions="callback carries the sequence so type stamping/audit stays inside the caller's existing create call"]
+// CIL[DOC-STABILITY stability="stable"]
+export async function insertMessageSequenced<T>(
+  threadId: string,
+  insert: (sequence: number) => Promise<T>,
+  maxAttempts = 3
+): Promise<T> {
+  let lastErr: any = null
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    const { data } = await adminDb
+      .from('messages')
+      .select('sequence')
+      .eq('thread_id', threadId)
+      .order('sequence', { ascending: false })
+      .limit(1)
+    const sequence = (data?.[0]?.sequence ?? 0) + 1
+    try {
+      return await insert(sequence)
+    } catch (err: any) {
+      lastErr = err
+      if (!isDuplicateKeyError(err)) throw err
+    }
+  }
+  throw lastErr
+}
+// CIL[END stable_id="~/.framework/functions/_shared/message-sequence.ts:insertmessagesequenced:function"]

package/.framework/functions/_shared/pipeline-runner.ts

@@ -262,6 +262,47 @@ interface PipelineStage {
  * @errorHandling Handles errors at each stage and decides whether to continue based on stage configuration.
  * @cil-generated
  */
+// CIL[BEGIN stable_id="~/.framework/functions/_shared/pipeline-runner.ts:persistExecutionResult:function" type="function" identity="persistExecutionResult" parent="~/.framework/functions/_shared/pipeline-runner.ts"]
+/**
+ * Writes the terminal status of a pipeline execution. The update result
+ * is checked and retried once — an unchecked failure is what previously
+ * left rows stuck 'running' forever while the audit span still claimed
+ * 'pipeline.completed'. A retry failure is logged loudly so the row can
+ * be found and reconciled.
+ *
+ * @inputSpec
+ *   ctx: CoreContext (required) — context for request-id logging.
+ *   executionId: string (required) — the pipeline_executions row to update.
+ *   patch: Record<string, any> (required) — terminal status payload.
+ * @outputSpec  Promise<void>
+ * @sideEffects Updates public.pipeline_executions; logs on failure.
+ * @stability   stable
+ * @calls       adminDb.from('pipeline_executions').update
+ * @cil-generated
+ */
+async function persistExecutionResult(
+  ctx: CoreContext,
+  executionId: string,
+  patch: Record<string, any>
+): Promise<void> {
+  let { error } = await adminDb
+    .from('pipeline_executions')
+    .update(patch)
+    .eq('id', executionId)
+  if (error) {
+    console.error(`[${ctx.requestId}] pipeline_executions final update failed for ${executionId}: ${error.message} — retrying`)
+    const retry = await adminDb
+      .from('pipeline_executions')
+      .update(patch)
+      .eq('id', executionId)
+    error = retry.error
+    if (error) {
+      console.error(`[${ctx.requestId}] pipeline_executions final update retry failed for ${executionId}: ${error.message}`)
+    }
+  }
+}
+// CIL[END stable_id="~/.framework/functions/_shared/pipeline-runner.ts:persistExecutionResult:function"]
+
 // CIL[BEGIN stable_id="~/.framework/functions/_shared/pipeline-runner.ts:runpipeline:function" type="function" identity="runPipeline" parent="~/.framework/functions/_shared/pipeline-runner.ts"]
 // CIL[DOC-MACRO purpose="runPipeline function"]
 // CIL[DOC-RESPONSIBILITY responsibility="Implements the runPipeline function."]
@@ -270,14 +311,40 @@ interface PipelineStage {
 // CIL[DOC-MICRO logic_summary="Implements the runPipeline function." notable_decisions="[]"]
 // CIL[DOC-CONFIDENCE pass="first" score="0.8" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
+// An execution row whose runner died mid-flight (detached process killed,
+// function timeout) can never write its own terminal status — it wedges
+// 'running' forever. Sweep rows that have not been touched within the
+// staleness window whenever a new pipeline run starts. Fire-and-forget:
+// the sweep is bookkeeping, never on the critical path, and a failed
+// sweep retries on the next run.
+const STALE_EXECUTION_MS = 10 * 60 * 1000
+
+export async function sweepStaleExecutions(): Promise<void> {
+  const cutoff = new Date(Date.now() - STALE_EXECUTION_MS).toISOString()
+  const { error } = await adminDb
+    .from('pipeline_executions')
+    .update({
+      status: 'failed',
+      error_message: 'stale execution: runner died before terminal write (swept)',
+      completed_at: new Date().toISOString(),
+      updated_at: new Date().toISOString()
+    })
+    .in('status', ['running', 'pending', 'queued'])
+    .lt('updated_at', cutoff)
+  if (error) console.warn('pipeline_executions stale sweep failed:', error.message)
+}
+
 export async function runPipeline(
   pipelineId: string,
   triggerData: any,
-  ctx: CoreContext
+  ctx: CoreContext,
+  opts?: { executionId?: string }
 ): Promise<ExecutionResult> {
   return withSpan(ctx, 'pipeline.run', async (ctx) => {
   const startTime = Date.now()
 
+  void sweepStaleExecutions().catch(() => {})
+
   const { data: pipeline, error: pipelineError } = await adminDb
     .from('pipelines')
     .select('*')
@@ -289,24 +356,76 @@ export async function runPipeline(
     throw new Error(`Pipeline not found or inactive: ${pipelineId}`)
   }
 
-  const { data: execution, error: execError } = await adminDb
-    .from('pipeline_executions')
-    .insert({
-      pipeline_id: pipelineId,
-      status: 'running',
-      trigger_data: triggerData || {},
-      account_id: ctx.accountId,
-      created_by: isUuid(ctx.principal?.id) ? ctx.principal?.id : null,
-      started_at: new Date().toISOString()
-    })
-    .select()
-    .single()
+  // When a pre-created execution ID is supplied (dispatched trigger
+  // pipelines), claim that row — transitioning queued → running — rather
+  // than inserting a duplicate. The row was created by checkAndFireTriggers
+  // with status='queued' immediately before dispatch.
+  let executionId: string
+  if (opts?.executionId) {
+    const { data: claimed, error: claimError } = await adminDb
+      .from('pipeline_executions')
+      .update({
+        status: 'running',
+        trigger_data: triggerData || {},
+        started_at: new Date().toISOString(),
+        updated_at: new Date().toISOString()
+      })
+      .eq('id', opts.executionId)
+      .eq('status', 'queued')
+      .select('id')
 
-  if (execError || !execution) {
-    throw new Error(`Failed to create execution: ${execError?.message}`)
-  }
+    if (claimError) {
+      throw new Error(`Failed to claim queued execution ${opts.executionId}: ${claimError.message}`)
+    }
+    if (claimed && claimed.length > 0) {
+      executionId = opts.executionId
+    } else {
+      // Claimed nothing — either the queued insert never landed (caller's
+      // fallback UUID) or a duplicate/swept dispatch arrived. Try inserting
+      // the row ourselves with the same ID: succeeds only when the row is
+      // genuinely absent, so duplicate deliveries die on the PK conflict
+      // instead of running the pipeline twice.
+      const { data: execution, error: execError } = await adminDb
+        .from('pipeline_executions')
+        .insert({
+          id: opts.executionId,
+          pipeline_id: pipelineId,
+          status: 'running',
+          trigger_data: triggerData || {},
+          account_id: ctx.accountId,
+          created_by: isUuid(ctx.principal?.id) ? ctx.principal?.id : null,
+          started_at: new Date().toISOString(),
+          updated_at: new Date().toISOString()
+        })
+        .select()
+        .single()
+      if (execError || !execution) {
+        throw new Error(`Failed to create execution: ${execError?.message}`)
+      }
+      executionId = execution.id
+    }
+  } else {
+    const { data: execution, error: execError } = await adminDb
+      .from('pipeline_executions')
+      .insert({
+        pipeline_id: pipelineId,
+        status: 'running',
+        trigger_data: triggerData || {},
+        account_id: ctx.accountId,
+        created_by: isUuid(ctx.principal?.id) ? ctx.principal?.id : null,
+        started_at: new Date().toISOString(),
+        // Seed updated_at so the stale-execution sweep has a baseline from
+        // t=0 — the row is 'running' the moment it exists.
+        updated_at: new Date().toISOString()
+      })
+      .select()
+      .single()
 
-  const executionId = execution.id
+    if (execError || !execution) {
+      throw new Error(`Failed to create execution: ${execError?.message}`)
+    }
+    executionId = execution.id
+  }
   const stageResults: StageResult[] = []
   const stages: PipelineStage[] = pipeline.stages || []
 
@@ -365,15 +484,12 @@ export async function runPipeline(
 
     const durationMs = Date.now() - startTime
     
-    await adminDb
-      .from('pipeline_executions')
-      .update({
-        status: 'completed',
-        result: { stages: stageResults },
-        completed_at: new Date().toISOString(),
-        duration_ms: durationMs
-      })
-      .eq('id', executionId)
+    await persistExecutionResult(ctx, executionId, {
+      status: 'completed',
+      result: { stages: stageResults },
+      completed_at: new Date().toISOString(),
+      duration_ms: durationMs
+    })
 
     await emitAudit(ctx, 'pipeline.completed', {
       type: 'pipeline_execution',
@@ -402,16 +518,13 @@ export async function runPipeline(
   } catch (error: any) {
     const durationMs = Date.now() - startTime
     
-    await adminDb
-      .from('pipeline_executions')
-      .update({
-        status: 'failed',
-        result: { stages: stageResults },
-        error_message: error.message,
-        completed_at: new Date().toISOString(),
-        duration_ms: durationMs
-      })
-      .eq('id', executionId)
+    await persistExecutionResult(ctx, executionId, {
+      status: 'failed',
+      result: { stages: stageResults },
+      error_message: error.message,
+      completed_at: new Date().toISOString(),
+      duration_ms: durationMs
+    })
 
     await emitAudit(ctx, 'pipeline.failed', {
       type: 'pipeline_execution',
@@ -1192,7 +1305,7 @@ const stageHandlers: Record<string, Function> = {
     if (!itemId) throw new Error('kb_ingest: could not resolve item_id from trigger data')
 
     const { kbIngest } = await import('./kb')
-    return await kbIngest(ctx, { id: itemId })
+    return await kbIngest(ctx, { id: itemId, account_id: triggerData?.entity?.data?.account_id })
   },
 
   'kb_revoke': async (ctx: CoreContext, config: any) => {

package/.framework/functions/_shared/principal.ts

@@ -27,7 +27,7 @@
 
 import { getUserDb, adminDb } from './db'
 import { createClient } from '@supabase/supabase-js'
-import WebSocket from 'ws'
+
 import { timingSafeEqual, createHash } from 'crypto'
 // CIL[DOC-VECTOR type="context" content="purpose='Shared principal and authorization module for Spine functions'; No verified external callers; imports: .framework/functions/_shared/db.ts"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
@@ -96,10 +96,10 @@ const env = (globalThis as any).process?.env || {}
 
 // CIL[BEGIN stable_id="~/.framework/functions/_shared/principal.ts:supabase:constant" type="constant" identity="supabase" parent="~/.framework/functions/_shared/principal.ts"]
 // CIL[DOC-MACRO purpose="Create a Supabase client configured for function use"]
-// CIL[DOC-RESPONSIBILITY responsibility="Provide an authenticated Supabase client with realtime transport"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide an anon-key Supabase client for auth.getUser JWT verification"]
 // CIL[DOC-CONTEXT module="functions/_shared/principal" layer="shared" related_files=".framework/functions/_shared/db.ts,.framework/functions/_shared/principal.ts"]
 // CIL[DOC-CONTRACT inputs="none" outputs="Supabase client" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Instantiate createClient with URL, anon key and auth/realtime options" notable_decisions="[]"]
+// CIL[DOC-MICRO logic_summary="Instantiate createClient with URL, anon key, and auth options. Realtime transport omitted — this client is used only for supabase.auth.getUser; no realtime channels are opened server-side." notable_decisions="ws realtime transport removed to reduce bundle size and eliminate unnecessary module-level init overhead across every function"]
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
 const supabase = createClient(
@@ -107,10 +107,7 @@ const supabase = createClient(
   env.SUPABASE_ANON_KEY || 'placeholder',
   {
     auth: { autoRefreshToken: false, persistSession: false },
-    realtime: { transport: WebSocket as any }
   }
-
-
 )
 // CIL[DOC-VECTOR type="context" content="purpose='Create a Supabase client configured for function use'; No verified external callers; imports: .framework/functions/_shared/db.ts"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
@@ -269,6 +266,12 @@ export async function resolvePrincipal(event: any): Promise<Principal> {
     if (triggerId) {
       return resolveTriggerPrincipal(triggerId, event)
     }
+
+    // A bare internal-invoke secret is itself a first-class credential —
+    // function-to-function calls without a cron/trigger principal to
+    // impersonate (e.g. manual system-cron runs) get the privileged
+    // system principal rather than falling through to anonymous.
+    return SYSTEM_PRINCIPAL
   }
 
   const authHeader = event.headers?.authorization || event.headers?.Authorization