spine-framework 0.3.124 → 0.3.126

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

@@ -1,59 +1,51 @@
-/**
- * @module pipeline-runner
- * @audience both
- * @layer shared-core
- * @stability stable
- *
- * Sequential pipeline execution engine. A pipeline is a named list of stages
- * (`PipelineStage[]`) stored in `pipelines.stages`. Each stage references an
- * `action` record by `stage_type` slug. Stages run sequentially; a failed stage
- * halts execution unless `stage.continue_on_error` is set.
- *
- * Every execution creates a `pipeline_executions` row (status: running →
- * completed | failed) and emits an audit log on completion or failure.
- *
- * Built-in stage handlers (no external config required):
- *   - `update_item`      — update a record by ID
- *   - `create_record`    — insert a new record
- *   - `http_request`     — fetch any HTTP endpoint
- *   - `send_notification`— insert watchers notification rows
- *   - `run_pipeline`     — trigger a nested pipeline (self-recursion blocked)
- *   - `search_knowledge` — full-text + fallback search on embeddings table
- *   - `query_items`      — filtered query on any table
- *   - `agent_inference`  — call an external LLM webhook or return a mock
- *
- * INVARIANT: `adminDb` (service role) is used for all DB writes — stage
- *   execution runs as the pipeline's machine principal, not the end user.
- * INVARIANT: `run_pipeline` handler blocks self-referential execution
- *   (`config._pipelineId === pipeline_id`) to prevent infinite loops.
- * INVARIANT: `runPipeline` never throws — failures are captured in the
- *   returned `ExecutionResult` with `status: 'failed'`.
- *
- * @seeAlso trigger-engine.ts (calls runPipeline when a trigger fires)
- * @seeAlso agent-runner.ts (calls runPipeline for agentic tool calls)
- * @seeAlso audit.ts (emitAudit called on pipeline.completed / pipeline.failed)
- * @seeAlso index.ts (runPipeline re-exported for v2-custom/ and CLI)
- */
 
+
+
+
+
+
+
+
+
+// CIL[BEGIN chunk_id="pipelinerunner_imports_1784020784" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import dependencies for pipeline execution"]
+// CIL[DOC-RESPONSIBILITY responsibility="Import context, database, and audit modules"]
+// CIL[DOC-CONTEXT module="pipeline-runner" layer="shared" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/schema-utils.ts\",\"custom/apps/portal/pages/ContentPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="v" outputs="CoreContext, adminDb, emitAudit, UUID utilities" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Import required modules and UUID validation utilities" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="developer"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/functions/_shared/principal.ts, .framework/functions/_shared/schema-utils.ts, custom/apps/portal/pages/ContentPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 import { CoreContext } from './middleware'
 import { adminDb } from './db'
-import { emitAudit } from './audit'
+import { emitAudit, emitSpan } from './audit'
+import { emitOutcome } from './outcomes'
+import { withSpan } from './tracing'
+import { execute as executeOutbound } from '../integration-outbound'
 
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
 function isUuid(v: string | undefined | null): v is string { return !!v && UUID_RE.test(v) }
-
-// ─── TYPES ──────────────────────────────────────────────────────────────
-
-/**
- * Result of a single pipeline stage execution.
- *
- * @outputSpec stageIndex: number — 0-based position in the pipeline's stages array
- * @outputSpec stageType: string — action slug (e.g. 'update_item', 'http_request')
- * @outputSpec status: 'success' | 'failed' | 'skipped'
- * @outputSpec output: any | undefined — handler return value on success
- * @outputSpec error: string | undefined — error message on failure
- * @outputSpec durationMs: number — wall-clock time for this stage
- */
+// CIL[END chunk_id="pipelinerunner_imports_1784020784"]
+// CIL[BEGIN chunk_id="pipelinerunner_stageresult_1784020784" type="interface" identity="StageResult" parent="none"]
+// CIL[DOC-MACRO purpose="Define stage execution result interface"]
+// CIL[DOC-RESPONSIBILITY responsibility="Structure pipeline stage execution data"]
+// CIL[DOC-CONTEXT module="pipeline-runner" layer="shared" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/functions/_shared/principal.ts\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="StageResult interface" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Interface for tracking individual pipeline stage execution status" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/IntegrationsPage.tsx, .framework/functions/_shared/principal.ts, custom/apps/cortex/functions/custom_cil-embeddings.ts, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export interface StageResult {
   stageIndex: number
   stageType: string
@@ -62,17 +54,21 @@ export interface StageResult {
   error?: string
   durationMs: number
 }
-
-/**
- * Top-level result of a `runPipeline` call. Stored in `pipeline_executions.result`.
- *
- * @outputSpec executionId: string — UUID of the pipeline_executions row
- * @outputSpec pipelineId: string — UUID of the pipeline that was run
- * @outputSpec status: 'completed' | 'failed' | 'cancelled'
- * @outputSpec stages: StageResult[] — per-stage results in execution order
- * @outputSpec durationMs: number — total wall-clock time
- * @outputSpec error: string | undefined — top-level error message on failure
- */
+// CIL[END chunk_id="pipelinerunner_stageresult_1784020784"]
+// CIL[BEGIN chunk_id="pipelinerunner_executionresult_1784020784" type="interface" identity="ExecutionResult" parent="none"]
+// CIL[DOC-MACRO purpose="Define pipeline execution result interface"]
+// CIL[DOC-RESPONSIBILITY responsibility="Structure complete pipeline execution data"]
+// CIL[DOC-CONTEXT module="pipeline-runner" layer="shared" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/functions/_shared/principal.ts\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="ExecutionResult interface" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Interface for tracking overall pipeline execution with all stages" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/IntegrationsPage.tsx, .framework/functions/_shared/principal.ts, custom/apps/cortex/functions/custom_cil-embeddings.ts, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export interface ExecutionResult {
   executionId: string
   pipelineId: string
@@ -81,79 +77,49 @@ export interface ExecutionResult {
   durationMs: number
   error?: string
 }
-
-/**
- * Single stage definition as stored in `pipelines.stages` JSONB array.
- *
- * @inputSpec stage_type: string — action.slug to look up the handler
- * @inputSpec config: Record<string, any> | undefined — merged with action defaults
- * @inputSpec continue_on_error: boolean | undefined — if true, failure doesn’t halt
- */
+// CIL[END chunk_id="pipelinerunner_executionresult_1784020784"]
+// CIL[BEGIN chunk_id="pipelinerunner_pipelinestage_1784020784" type="interface" identity="PipelineStage" parent="none"]
+// CIL[DOC-MACRO purpose="Define pipeline stage configuration interface"]
+// CIL[DOC-RESPONSIBILITY responsibility="Structure individual pipeline stage definition"]
+// CIL[DOC-CONTEXT module="pipeline-runner" layer="shared" related_files="[\".framework/functions/_shared/schema-utils.ts\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/functions/_shared/principal.ts\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="PipelineStage interface" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Interface for defining pipeline stage type and configuration" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, custom/apps/cortex/functions/custom_cil-embeddings.ts, .framework/src/pages/admin/IntegrationsPage.tsx, .framework/functions/_shared/principal.ts, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 interface PipelineStage {
   stage_type: string
   config?: Record<string, any>
   continue_on_error?: boolean
 }
-
-// ─── PRIMARY EXPORT ────────────────────────────────────────────────────────────
-
-/**
- * Executes a pipeline by ID, running its stages sequentially.
- *
- * Execution lifecycle:
- *   1. Load pipeline record (`pipelines` table, `is_active = true`)
- *   2. Insert `pipeline_executions` row with `status: 'running'`
- *   3. For each stage: load action → merge config → call `executeStage`
- *   4. On stage failure: push failed StageResult; stop unless `continue_on_error`
- *   5. Update `pipeline_executions` to `completed` or `failed`
- *   6. Emit `pipeline.completed` or `pipeline.failed` audit log
- *   7. Return `ExecutionResult` (never throws; failures are in result.status)
- *
- * @param pipelineId - UUID of the pipeline to run (must be active)
- * @param triggerData - Arbitrary context passed to each stage as `_triggerData`
- * @param ctx - CoreContext with principal and accountId for audit and stage writes
- * @returns Promise<ExecutionResult> — always resolves; never throws
- * @throws Error('Pipeline not found or inactive') — only if pipeline lookup fails
- *   before execution begins (throws before creating the execution row)
- * @throws Error('Failed to create execution') — if execution row insert fails
- * @inputSpec pipelineId: string — valid UUID of a pipeline in pipelines table
- * @inputSpec triggerData: any — JSON-serializable; stored in trigger_data column
- * @inputSpec ctx.accountId: string | null — stamped on execution row
- * @inputSpec ctx.principal.id: string — stamped as created_by on execution row
- * @outputSpec ExecutionResult with status, stages, durationMs
- * @sideEffects DB write: inserts pipeline_executions row; updates it on completion
- * @sideEffects DB write: emitAudit to logs table
- * @calledBy trigger-engine.ts (on trigger fire)
- * @calledBy agent-runner.ts (tool call dispatch)
- * @calledBy stageHandlers.run_pipeline (nested execution)
- * @calledBy v2-custom/ import callers and CLI
- * @calls executeStage, adminDb, emitAudit
- * @testUnit tests/unit/pipeline-runner.test.ts
- * @testIntegration tests/integration/pipeline-runner.test.ts
- *
- * @example API handler trigger
- * ```ts
- * import { runPipeline } from './_shared/index'
- * const result = await runPipeline(body.pipeline_id, body.data, ctx)
- * if (result.status === 'failed') return error(result.error!, 500)
- * return result
- * ```
- *
- * @example Import usage (v2-custom/)
- * ```ts
- * import { runPipeline, SYSTEM_PRINCIPAL, adminDb, CoreContext } from '../_shared/index'
- * const ctx: CoreContext = { principal: SYSTEM_PRINCIPAL, accountId: MY_ACCOUNT, db: adminDb, requestId: crypto.randomUUID() }
- * const result = await runPipeline('pipeline-uuid', { source: 'import' }, ctx)
- * ```
- */
+// CIL[END chunk_id="pipelinerunner_pipelinestage_1784020784"]
+// CIL[BEGIN chunk_id="pipelinerunner_runpipeline_1784020784" type="function" identity="runPipeline" parent="none"]
+// CIL[DOC-MACRO purpose="Execute complete pipeline with all stages"]
+// CIL[DOC-RESPONSIBILITY responsibility="Orchestrate pipeline execution and error handling"]
+// CIL[DOC-CONTEXT module="pipeline-runner" layer="shared" related_files="[\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/src/components/ui/dialog.tsx\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="ExecutionResult" errors="Pipeline not found, execution failed" side_effects="Database updates, audit events"]
+// CIL[DOC-MICRO logic_summary="Main pipeline executor handling stages, errors, and database tracking" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/IntegrationsPage.tsx, .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/RolesPage.tsx, .framework/src/components/ui/dialog.tsx."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export async function runPipeline(
   pipelineId: string,
   triggerData: any,
   ctx: CoreContext
 ): Promise<ExecutionResult> {
+  return withSpan(ctx, 'pipeline.run', async (ctx) => {
   const startTime = Date.now()
 
-  // Load pipeline definition
   const { data: pipeline, error: pipelineError } = await adminDb
     .from('pipelines')
     .select('*')
@@ -165,7 +131,6 @@ export async function runPipeline(
     throw new Error(`Pipeline not found or inactive: ${pipelineId}`)
   }
 
-  // Create execution record
   const { data: execution, error: execError } = await adminDb
     .from('pipeline_executions')
     .insert({
@@ -188,13 +153,11 @@ export async function runPipeline(
   const stages: PipelineStage[] = pipeline.stages || []
 
   try {
-    // Execute each stage sequentially
     for (let i = 0; i < stages.length; i++) {
       const stage = stages[i]
       const stageStartTime = Date.now()
 
       try {
-        // Load action for this stage type
         const { data: action, error: actionError } = await adminDb
           .from('actions')
           .select('*')
@@ -206,7 +169,6 @@ export async function runPipeline(
           throw new Error(`Action not found for stage type: ${stage.stage_type}`)
         }
 
-        // Merge stage config with action defaults
         const mergedConfig = {
           ...action.config,
           ...stage.config,
@@ -216,7 +178,6 @@ export async function runPipeline(
           _triggerData: triggerData
         }
 
-        // Execute the stage
         const output = await executeStage(ctx, action, mergedConfig)
 
         stageResults.push({
@@ -238,14 +199,12 @@ export async function runPipeline(
           durationMs: Date.now() - stageStartTime
         })
 
-        // Stop unless continue_on_error is set
         if (!stage.continue_on_error) {
           throw new Error(`Stage ${i} (${stage.stage_type}) failed: ${errorMessage}`)
         }
       }
     }
 
-    // Complete successfully
     const durationMs = Date.now() - startTime
     
     await adminDb
@@ -267,6 +226,12 @@ export async function runPipeline(
       duration_ms: durationMs,
       stages_completed: stageResults.length
     })
+    await emitOutcome(ctx, 'pipeline.outcome', 'success', {
+      pipeline_id: pipelineId,
+      execution_id: executionId,
+      stages_completed: stageResults.length,
+      duration_ms: durationMs
+    })
 
     return {
       executionId,
@@ -277,7 +242,6 @@ export async function runPipeline(
     }
 
   } catch (error: any) {
-    // Complete with failure
     const durationMs = Date.now() - startTime
     
     await adminDb
@@ -300,6 +264,12 @@ export async function runPipeline(
       error: error.message,
       stages_completed: stageResults.length
     })
+    await emitOutcome(ctx, 'pipeline.outcome', 'failure', {
+      pipeline_id: pipelineId,
+      execution_id: executionId,
+      error: error.message,
+      stages_completed: stageResults.length
+    })
 
     return {
       executionId,
@@ -310,76 +280,62 @@ export async function runPipeline(
       error: error.message
     }
   }
+}, { onEnd: emitSpan })
 }
-
-// ─── STAGE DISPATCH ────────────────────────────────────────────────────────────
-
-/**
- * Dispatches a single stage to the correct handler module.
- *
- * Routes based on `action.handler_module`:
- *   - `'functions'`    → `executeFunctionHandler` (built-in stageHandlers)
- *   - `'integrations'` → `executeIntegrationHandler` (loads integration by slug)
- *   - `'webhook'`      → `executeWebhookHandler` (calls action.config.url)
- *
- * @param ctx - CoreContext
- * @param action - Action record from the `actions` table
- * @param config - Merged stage + action config with `_pipelineId`, `_executionId`,
- *   `_stageIndex`, `_triggerData` injected by runPipeline
- * @returns Promise<any> — handler output
- * @throws Error('Unknown handler module') on unrecognised module string
- * @inputSpec action.handler_module: 'functions' | 'integrations' | 'webhook'
- * @inputSpec action.handler: string — handler name or integration slug
- * @sideEffects depends on handler module (DB writes, HTTP calls)
- * @calledBy runPipeline (per-stage loop)
- * @calls executeFunctionHandler | executeIntegrationHandler | executeWebhookHandler
- */
+// CIL[END chunk_id="pipelinerunner_runpipeline_1784020784"]
+// CIL[BEGIN chunk_id="pipelinerunner_executestage_1784020784" type="function" identity="executeStage" parent="none"]
+// CIL[DOC-MACRO purpose="Route stage execution to appropriate handler"]
+// CIL[DOC-RESPONSIBILITY responsibility="Dispatch stage execution based on handler module"]
+// CIL[DOC-CONTEXT module="pipeline-runner" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="stage execution result" errors="Unknown handler module" side_effects="Handler execution"]
+// CIL[DOC-MICRO logic_summary="Stage dispatcher routing to functions, integrations, or webhooks" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 async function executeStage(
   ctx: CoreContext,
   action: any,
   config: any
 ): Promise<any> {
-  const handlerModule = action.handler_module || 'functions'
-  const handlerName = action.handler
-
-  switch (handlerModule) {
-    case 'functions':
-      return await executeFunctionHandler(ctx, handlerName, config)
-    
-    case 'integrations':
-      return await executeIntegrationHandler(ctx, handlerName, config)
-    
-    case 'webhook':
-      return await executeWebhookHandler(ctx, action, config)
-    
-    default:
-      throw new Error(`Unknown handler module: ${handlerModule}`)
-  }
+  return withSpan(ctx, `pipeline.stage.${action.handler || action.stage_type || 'unknown'}`, async (ctx) => {
+    const handlerModule = action.handler_module || 'functions'
+    const handlerName = action.handler
+
+    switch (handlerModule) {
+      case 'functions':
+        return await executeFunctionHandler(ctx, handlerName, config)
+      
+      case 'integrations':
+        return await executeIntegrationHandler(ctx, handlerName, config)
+      
+      case 'webhook':
+        return await executeWebhookHandler(ctx, action, config)
+      
+      default:
+        throw new Error(`Unknown handler module: ${handlerModule}`)
+    }
+  }, { onEnd: emitSpan })
 }
-
-// ─── BUILT-IN STAGE HANDLERS ─────────────────────────────────────────────────────────
-
-/**
- * Map of built-in stage handler functions keyed by action slug.
- *
- * Each handler receives `(ctx: CoreContext, config: any)` and returns a
- * JSON-serializable result or throws on failure. Registered handlers:
- *
- * | Slug                | Required config keys              | Returns                        |
- * |---------------------|-----------------------------------|--------------------------------|
- * | `update_item`       | `entity`, `record_id`, `data`     | `{ success, record }`          |
- * | `create_record`     | `entity`, `data`                  | `{ success, record }`          |
- * | `http_request`      | `url`                             | `{ success, status, body }`    |
- * | `send_notification` | `message`, `recipients[]`         | `{ success, notified_count }`  |
- * | `run_pipeline`      | `pipeline_id`                     | `{ success, nested_result }`   |
- * | `search_knowledge`  | `query`                           | `{ results[], count, method }` |
- * | `query_items`       | `entity`                          | `{ items[], count }`           |
- * | `agent_inference`   | `context`                         | `{ content, confidence, ... }` |
- *
- * @sideEffects DB writes for update_item, create_record, send_notification
- * @sideEffects HTTP calls for http_request, agent_inference (webhook_url)
- * @calledBy executeFunctionHandler
- */
+// CIL[END chunk_id="pipelinerunner_executestage_1784020784"]
+// CIL[BEGIN chunk_id="pipelinerunner_stagehandlers_1784020784" type="variable" identity="stageHandlers" parent="none"]
+// CIL[DOC-MACRO purpose="Define all available pipeline stage handlers"]
+// CIL[DOC-RESPONSIBILITY responsibility="Implement core pipeline stage execution functions"]
+// CIL[DOC-CONTEXT module="pipeline-runner" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="stageHandlers object" errors="none" side_effects="Database operations, HTTP requests"]
+// CIL[DOC-MICRO logic_summary="Collection of handlers for database, HTTP, notification, and AI operations" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 const stageHandlers: Record<string, Function> = {
   'update_item': async (ctx: CoreContext, config: any) => {
     const { entity, record_id, data } = config
@@ -433,33 +389,21 @@ const stageHandlers: Record<string, Function> = {
       throw new Error('url is required for http_request')
     }
 
-    const fetchOptions: RequestInit = {
-      method,
-      headers: {
-        'Content-Type': 'application/json',
-        ...headers
-      }
-    }
-
-    if (body && ['POST', 'PUT', 'PATCH'].includes(method)) {
-      fetchOptions.body = JSON.stringify(body)
-    }
-
-    const response = await fetch(url, fetchOptions)
-    const responseBody = await response.json().catch(() => null)
+    const result = await executeOutbound(ctx, {
+      integration_slug: 'generic-http',
+      action_config: { url, method, headers, body: ['POST', 'PUT', 'PATCH'].includes(method) ? body : undefined }
+    })
 
     return {
-      success: response.ok,
-      status: response.status,
-      statusText: response.statusText,
-      body: responseBody
+      success: true,
+      status: result.response_status,
+      body: result.response_body
     }
   },
 
   'send_notification': async (ctx: CoreContext, config: any) => {
     const { message, entity_type, entity_id, recipients = [] } = config
     
-    // Create watcher notifications
     const notifications = recipients.map((recipientId: string) => ({
       account_id: ctx.accountId,
       person_id: recipientId,
@@ -488,7 +432,6 @@ const stageHandlers: Record<string, Function> = {
       throw new Error('pipeline_id is required for run_pipeline')
     }
 
-    // Prevent infinite recursion
     if (config._pipelineId === pipeline_id) {
       throw new Error('Recursive pipeline execution prevented')
     }
@@ -508,7 +451,6 @@ const stageHandlers: Record<string, Function> = {
       throw new Error('query is required for search_knowledge')
     }
 
-    // Text search fallback (when no embedding provided)
     let dbQuery = adminDb
       .from('embeddings')
       .select('*')
@@ -523,7 +465,6 @@ const stageHandlers: Record<string, Function> = {
       dbQuery = dbQuery.eq('model_id', model_id)
     }
 
-    // Try text search first
     const { data: textResults, error: textError } = await dbQuery
       .textSearch('content', query, { type: 'websearch', config: 'english' })
 
@@ -536,7 +477,6 @@ const stageHandlers: Record<string, Function> = {
       }
     }
 
-    // Fallback to ilike search
     const { data: fallbackResults, error: fallbackError } = await dbQuery
       .ilike('content', `%${query}%`)
 
@@ -565,12 +505,10 @@ const stageHandlers: Record<string, Function> = {
       .eq('account_id', ctx.accountId)
       .limit(parseInt(limit.toString()))
 
-    // Apply filters
     Object.entries(filters).forEach(([key, value]) => {
       dbQuery = dbQuery.eq(key, value)
     })
 
-    // Add text search if query provided
     if (query) {
       dbQuery = dbQuery.textSearch('data', query, { type: 'websearch', config: 'english' })
     }
@@ -588,37 +526,36 @@ const stageHandlers: Record<string, Function> = {
       throw new Error('context is required for agent_inference')
     }
 
-    // If webhook_url provided, call external LLM service
     if (webhook_url) {
-      const response = await fetch(webhook_url, {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-          ...headers
-        },
-        body: JSON.stringify({
-          context,
-          model: model || 'gpt-4o',
-          temperature: temperature ?? 0.7,
-          max_tokens: max_tokens ?? 4000
-        })
+      const result = await executeOutbound(ctx, {
+        integration_slug: 'generic-http',
+        action_config: {
+          url: webhook_url,
+          method: 'POST',
+          headers,
+          body: {
+            context,
+            model: model || 'gpt-4o',
+            temperature: temperature ?? 0.7,
+            max_tokens: max_tokens ?? 4000
+          }
+        }
       })
 
-      if (!response.ok) {
-        throw new Error(`Inference failed: ${response.status} ${response.statusText}`)
+      if (!result.success) {
+        throw new Error(`Inference failed: ${result.response_status} ${result.response_body}`)
       }
 
-      const result: any = await response.json()
+      const response: any = result.response_body
       return {
-        content: result.content || result.message || '',
-        confidence: result.confidence || 0.8,
-        tool_calls: result.tool_calls,
-        metadata: result.metadata,
+        content: response.content || response.message || '',
+        confidence: response.confidence || 0.8,
+        tool_calls: response.tool_calls,
+        metadata: response.metadata,
         model: model || 'gpt-4o'
       }
     }
 
-    // Fallback: return mock for development/testing
     return {
       content: `[Mock Response] Received ${context.length} chars of context. In production, configure webhook_url in action config.`,
       confidence: 0.9,
@@ -628,20 +565,11 @@ const stageHandlers: Record<string, Function> = {
     }
   },
 
-  // ── generate_embeddings ─────────────────────────────────────────────────────
-  // Generates embeddings for an item using the core embeddings.generate action.
-  // Supports {{trigger.entity_id}} template interpolation in config.item_id.
-  //
-  // Config: item_id (required — supports {{trigger.entity_id}}),
-  //         force_regenerate (bool, default false)
-  //
-  // Called by the auto_embed_on_publish and auto_revoke_on_unpublish pipelines.
   'generate_embeddings': async (ctx: CoreContext, config: any) => {
     const triggerData = config._triggerData || {}
     let itemId = config.item_id
     if (!itemId) throw new Error('item_id is required for generate_embeddings')
 
-    // Template interpolation: {{trigger.entity_id}} or {{entity_id}}
     if (typeof itemId === 'string' && itemId.includes('{{')) {
       itemId = itemId
         .replace(/\{\{trigger\.entity_id\}\}/g, triggerData?.entity_id || '')
@@ -651,23 +579,28 @@ const stageHandlers: Record<string, Function> = {
     if (!itemId) throw new Error('generate_embeddings: could not resolve item_id from trigger data')
 
     const { generate } = await import('../embeddings')
-    const genCtx = { ...ctx, query: { ...(ctx.query || {}), action: 'generate' } }
+    const genCtx = { ...ctx, query: { ...((ctx as any).query || {}), action: 'generate' } } as any
     return await generate(genCtx, {
       item_id: itemId,
       force_regenerate: config.force_regenerate ?? false,
     })
   },
 }
-
-// ─── MODULE DISPATCHERS ────────────────────────────────────────────────────────────
-
-/**
- * Looks up a built-in handler by name and calls it.
- *
- * @throws Error('Unknown function handler: <name>') if not in stageHandlers map
- * @calledBy executeStage (functions module)
- * @calls stageHandlers[handlerName]
- */
+// CIL[END chunk_id="pipelinerunner_stagehandlers_1784020784"]
+// CIL[BEGIN chunk_id="pipelinerunner_executefunctionhandler_1784020784" type="function" identity="executeFunctionHandler" parent="none"]
+// CIL[DOC-MACRO purpose="Execute built-in function stage handlers"]
+// CIL[DOC-RESPONSIBILITY responsibility="Dispatch to internal stage handler functions"]
+// CIL[DOC-CONTEXT module="pipeline-runner" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="handler execution result" errors="Unknown function handler" side_effects="Handler execution"]
+// CIL[DOC-MICRO logic_summary="Lookup and execute built-in stage handler by name" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 async function executeFunctionHandler(
   ctx: CoreContext,
   handlerName: string,
@@ -681,55 +614,48 @@ async function executeFunctionHandler(
 
   return await handler(ctx, config)
 }
-
-/**
- * Loads an integration record by slug and executes it.
- *
- * Currently a stub — logs the call and returns the integration ID.
- * Future: delegate to integration-specific executor based on integration type.
- *
- * @throws Error('Integration not found') if no active integration matches slug
- * @sideEffects DB read: integrations table
- * @calledBy executeStage (integrations module)
- */
+// CIL[END chunk_id="pipelinerunner_executefunctionhandler_1784020784"]
+// CIL[BEGIN chunk_id="pipelinerunner_executeintegrationhandler_1784020784" type="function" identity="executeIntegrationHandler" parent="none"]
+// CIL[DOC-MACRO purpose="Execute external integration stage handlers"]
+// CIL[DOC-RESPONSIBILITY responsibility="Dispatch to configured integration handlers"]
+// CIL[DOC-CONTEXT module="pipeline-runner" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="integration execution result" errors="Integration not found" side_effects="Integration execution"]
+// CIL[DOC-MICRO logic_summary="Lookup integration config and execute external handler" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 async function executeIntegrationHandler(
   ctx: CoreContext,
   handlerName: string,
   config: any
 ): Promise<any> {
-  // Load integration configuration
-  const { data: integration, error } = await adminDb
-    .from('integrations')
-    .select('*')
-    .eq('slug', handlerName)
-    .eq('is_active', true)
-    .single()
-
-  if (error || !integration) {
-    throw new Error(`Integration not found: ${handlerName}`)
-  }
-
-  // Execute based on integration type
-  // This is a placeholder for actual integration logic
-  console.log(`[${ctx.requestId}] Integration handler: ${handlerName}`, config)
-  
-  return { 
-    success: true, 
-    handler: handlerName,
-    integration_id: integration.id
-  }
+  const { execute } = await import('../integration-outbound')
+  return execute(ctx, {
+    integration_slug: handlerName,
+    record_id: config.record_id,
+    action_config: config
+  })
 }
-
-/**
- * POSTs the merged stage config as JSON to the webhook URL from action.config.url.
- *
- * Returns `{ success, status, body }` based on the HTTP response. Does not
- * throw on non-2xx responses — `success: false` is returned instead.
- *
- * @throws Error('Webhook URL not configured') if action.config.url is missing
- * @sideEffects HTTP call to action.config.url
- * @calledBy executeStage (webhook module)
- */
+// CIL[END chunk_id="pipelinerunner_executeintegrationhandler_1784020784"]
+// CIL[BEGIN chunk_id="pipelinerunner_executewebhookhandler_1784020784" type="function" identity="executeWebhookHandler" parent="none"]
+// CIL[DOC-MACRO purpose="Execute webhook stage handlers via HTTP"]
+// CIL[DOC-RESPONSIBILITY responsibility="Send stage execution data to webhook endpoints"]
+// CIL[DOC-CONTEXT module="pipeline-runner" layer="shared" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="webhook response" errors="Webhook URL not configured" side_effects="HTTP requests"]
+// CIL[DOC-MICRO logic_summary="Send configuration data to configured webhook endpoint" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: shared. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 async function executeWebhookHandler(
   ctx: CoreContext,
   action: any,
@@ -741,21 +667,22 @@ async function executeWebhookHandler(
     throw new Error('Webhook URL not configured in action')
   }
 
-  const fetchOptions: RequestInit = {
-    method,
-    headers: {
-      'Content-Type': 'application/json',
-      ...headers
-    },
-    body: JSON.stringify(config)
-  }
-
-  const response = await fetch(url, fetchOptions)
-  const body = await response.json().catch(() => null)
+  const { execute } = await import('../integration-outbound')
+  const result = await execute(ctx, {
+    integration_slug: 'generic-http',
+    action_config: {
+      url,
+      method,
+      headers,
+      body: config,
+      credential_field: 'api_token'
+    }
+  })
 
   return {
-    success: response.ok,
-    status: response.status,
-    body
+    success: result.success,
+    status: result.response_status,
+    body: result.response_body
   }
 }
+// CIL[END chunk_id="pipelinerunner_executewebhookhandler_1784020784"]