@elevasis/core 0.23.0 → 0.24.0

package/src/execution/engine/workflow/types.ts

@@ -1,202 +1,202 @@
-// Import z for schema types
-import type { z } from 'zod'
-
-/**
- * Workflow-specific type definitions
- */
-
-import type { ExecutionContext } from '../base/types'
-import type { ResourceDefinition } from '../../../platform/registry/types'
-import type { WorkflowResourceEntry } from '../../../organization-model/domains/resources'
-import type { ResourceMetricsConfig } from '../../../operations/observability/types'
-import type { ExecutionInterface } from '../interface/types'
-
-// Workflow configuration
-export interface WorkflowConfig extends ResourceDefinition {
-  type: 'workflow'
-  /** OM descriptor backing canonical identity and governance metadata. */
-  resource?: WorkflowResourceEntry
-  /** Lead-gen action key for registry derivation (e.g. 'lead-gen.company.apollo-import') */
-  actionKey?: string
-}
-
-export type DescriptorBackedWorkflowConfig = Omit<WorkflowConfig, 'resourceId' | 'type' | 'resource'> & {
-  resource: WorkflowResourceEntry
-}
-
-// Workflow step definition
-export interface WorkflowStepDefinition {
-  id: string
-  name: string
-  description: string
-}
-
-// Step handler function type
-export type StepHandler = (input: unknown, context: ExecutionContext) => Promise<unknown>
-
-// Step type for flow control
-export const StepType = {
-  LINEAR: 'linear',
-  CONDITIONAL: 'conditional'
-} as const
-export type StepType = (typeof StepType)[keyof typeof StepType]
-
-// Next step configuration types
-export interface LinearNext {
-  type: 'linear'
-  target: string
-}
-
-export interface ConditionalNext {
-  type: 'conditional'
-  routes: Array<{
-    condition: (data: unknown) => boolean
-    target: string
-  }>
-  default: string // Required to avoid ambiguity
-}
-
-export type NextConfig =
-  | LinearNext // Go to specific step
-  | ConditionalNext // Conditional routing
-  | null // Explicitly end workflow
-
-// Workflow step with graph-based flow
-export interface WorkflowStep extends WorkflowStepDefinition {
-  handler: StepHandler
-
-  // I/O validation (BOTH REQUIRED for complete type safety)
-  inputSchema: z.ZodSchema // Validates input from previous step or workflow
-  outputSchema: z.ZodSchema // Validates output before next step
-
-  next: NextConfig // Required - explicit flow decision for every step
-}
-
-// Workflow definition - pure configuration without instance state
-// Used by registry to define workflows that can be instantiated
-export interface WorkflowDefinition {
-  config: WorkflowConfig
-  contract: import('../base/types').Contract
-  steps: Record<string, WorkflowStep>
-  entryPoint: string
-
-  /**
-   * Metrics configuration for ROI calculations
-   * Optional: Only needed if tracking automation savings
-   */
-  metricsConfig?: ResourceMetricsConfig
-
-  /**
-   * Execution interface configuration (optional)
-   * If provided, workflow appears in Execution Runner UI
-   */
-  interface?: ExecutionInterface
-
-  /**
-   * Lead-gen processing stage this workflow implements (optional).
-   * Must match a key in the platform lead-gen stage catalog.
-   * Used by org-os graph derivation to surface workflow→stage edges and
-   * by pipeline_config validation to confirm each catalog stage has an
-   * implementing workflow before a list is activated.
-   *
-   * Example: stageImplemented: 'verified' on the email-verification workflow.
-   */
-  stageImplemented?: string
-}
-
-/**
- * Workflow timeline and observability types
- * Used for UI timeline visualization and backend processing
- */
-
-import type { WorkflowLogMessage } from './logging'
-
-/**
- * Workflow step state
- * Aggregates step context events with timing and logs
- */
-export interface StepState {
-  stepId: string
-  stepName: string
-  status: 'pending' | 'running' | 'completed' | 'failed'
-
-  // Timeline visualization timing
-  startTime?: number // From step-started context
-  endTime?: number // From step-completed/failed context
-  duration?: number // From step-completed/failed context
-
-  // Step data
-  input?: unknown
-  output?: unknown
-  error?: unknown
-  logs: WorkflowLogMessage[]
-}
-
-/**
- * Complete workflow execution data for node visualization
- * Parsed from execution logs
- */
-export interface WorkflowNodeVisualizerData {
-  steps: StepState[]
-  totalDuration: number
-  isRunning: boolean
-}
-
-/**
- * Step data extracted from execution logs
- * Used to provide detailed step information in unified graph nodes
- */
-export interface StepExecutionData {
-  /** Final execution status for this step */
-  status: 'pending' | 'running' | 'completed' | 'failed'
-
-  /** Step execution duration in milliseconds */
-  duration?: number
-
-  /** Step input data */
-  input?: unknown
-
-  /** Step output data */
-  output?: unknown
-
-  /** Error data if step failed */
-  error?: unknown
-
-  /** Log messages from this step (reserved for future use) */
-  logs?: unknown[]
-}
-
-/**
- * Execution path tracking state
- *
- * Tracks which steps have been executed and which edges were taken during workflow
- * execution. This state is built from SSE execution log events and used to compute
- * the visual dimming/highlighting of nodes and edges.
- *
- * Algorithm:
- * - `executedSteps` provides O(1) lookup for "has this step been reached?"
- * - `executedStepsOrdered` preserves execution order for edge inference
- * - `takenEdges` comes from `conditional-route` SSE events + linear step inference
- * - `currentStepId` tracks the actively running step for animation
- * - `stepStatusMap` provides final status for each executed step
- * - `stepDataMap` provides detailed execution data (duration, input, output, error)
- */
-export interface ExecutionPathState {
-  /** Set of step IDs that have been executed (O(1) lookup) */
-  executedSteps: Set<string>
-
-  /** Step IDs in execution order (for inferring linear edges) */
-  executedStepsOrdered: string[]
-
-  /** Set of edge IDs that were traversed (format: "edge-{source}-{target}") */
-  takenEdges: Set<string>
-
-  /** Currently running step ID (undefined if no step is running) */
-  currentStepId?: string
-
-  /** Map of step IDs to their final execution status */
-  stepStatusMap?: Map<string, 'pending' | 'running' | 'completed' | 'failed'>
-
-  /** Map of step IDs to their execution data (duration, input, output, error) */
-  stepDataMap?: Map<string, StepExecutionData>
-}
+// Import z for schema types
+import type { z } from 'zod'
+
+/**
+ * Workflow-specific type definitions
+ */
+
+import type { ExecutionContext } from '../base/types'
+import type { ResourceDefinition } from '../../../platform/registry/types'
+import type { WorkflowResourceEntry } from '../../../organization-model/domains/resources'
+import type { ResourceMetricsConfig } from '../../../operations/observability/types'
+import type { ExecutionInterface } from '../interface/types'
+
+// Workflow configuration
+export interface WorkflowConfig extends ResourceDefinition {
+  type: 'workflow'
+  /** OM descriptor backing canonical identity and governance metadata. */
+  resource?: WorkflowResourceEntry
+  /** Lead-gen action key for registry derivation (e.g. 'lead-gen.company.apollo-import') */
+  actionKey?: string
+}
+
+export type DescriptorBackedWorkflowConfig = Omit<WorkflowConfig, 'resourceId' | 'type' | 'resource'> & {
+  resource: WorkflowResourceEntry
+}
+
+// Workflow step definition
+export interface WorkflowStepDefinition {
+  id: string
+  name: string
+  description: string
+}
+
+// Step handler function type
+export type StepHandler = (input: unknown, context: ExecutionContext) => Promise<unknown>
+
+// Step type for flow control
+export const StepType = {
+  LINEAR: 'linear',
+  CONDITIONAL: 'conditional'
+} as const
+export type StepType = (typeof StepType)[keyof typeof StepType]
+
+// Next step configuration types
+export interface LinearNext {
+  type: 'linear'
+  target: string
+}
+
+export interface ConditionalNext {
+  type: 'conditional'
+  routes: Array<{
+    condition: (data: unknown) => boolean
+    target: string
+  }>
+  default: string // Required to avoid ambiguity
+}
+
+export type NextConfig =
+  | LinearNext // Go to specific step
+  | ConditionalNext // Conditional routing
+  | null // Explicitly end workflow
+
+// Workflow step with graph-based flow
+export interface WorkflowStep extends WorkflowStepDefinition {
+  handler: StepHandler
+
+  // I/O validation (BOTH REQUIRED for complete type safety)
+  inputSchema: z.ZodSchema // Validates input from previous step or workflow
+  outputSchema: z.ZodSchema // Validates output before next step
+
+  next: NextConfig // Required - explicit flow decision for every step
+}
+
+// Workflow definition - pure configuration without instance state
+// Used by registry to define workflows that can be instantiated
+export interface WorkflowDefinition {
+  config: WorkflowConfig
+  contract: import('../base/types').Contract
+  steps: Record<string, WorkflowStep>
+  entryPoint: string
+
+  /**
+   * Metrics configuration for ROI calculations
+   * Optional: Only needed if tracking automation savings
+   */
+  metricsConfig?: ResourceMetricsConfig
+
+  /**
+   * Execution interface configuration (optional)
+   * If provided, workflow appears in Execution Runner UI
+   */
+  interface?: ExecutionInterface
+
+  /**
+   * Lead-gen processing stage this workflow implements (optional).
+   * Must match a key in the platform lead-gen stage catalog.
+   * Used by org-os graph derivation to surface workflow→stage edges and
+   * by pipeline_config validation to confirm each catalog stage has an
+   * implementing workflow before a list is activated.
+   *
+   * Example: stageImplemented: 'verified' on the email-verification workflow.
+   */
+  stageImplemented?: string
+}
+
+/**
+ * Workflow timeline and observability types
+ * Used for UI timeline visualization and backend processing
+ */
+
+import type { WorkflowLogMessage } from './logging'
+
+/**
+ * Workflow step state
+ * Aggregates step context events with timing and logs
+ */
+export interface StepState {
+  stepId: string
+  stepName: string
+  status: 'pending' | 'running' | 'completed' | 'failed'
+
+  // Timeline visualization timing
+  startTime?: number // From step-started context
+  endTime?: number // From step-completed/failed context
+  duration?: number // From step-completed/failed context
+
+  // Step data
+  input?: unknown
+  output?: unknown
+  error?: unknown
+  logs: WorkflowLogMessage[]
+}
+
+/**
+ * Complete workflow execution data for node visualization
+ * Parsed from execution logs
+ */
+export interface WorkflowNodeVisualizerData {
+  steps: StepState[]
+  totalDuration: number
+  isRunning: boolean
+}
+
+/**
+ * Step data extracted from execution logs
+ * Used to provide detailed step information in unified graph nodes
+ */
+export interface StepExecutionData {
+  /** Final execution status for this step */
+  status: 'pending' | 'running' | 'completed' | 'failed'
+
+  /** Step execution duration in milliseconds */
+  duration?: number
+
+  /** Step input data */
+  input?: unknown
+
+  /** Step output data */
+  output?: unknown
+
+  /** Error data if step failed */
+  error?: unknown
+
+  /** Log messages from this step (reserved for future use) */
+  logs?: unknown[]
+}
+
+/**
+ * Execution path tracking state
+ *
+ * Tracks which steps have been executed and which edges were taken during workflow
+ * execution. This state is built from SSE execution log events and used to compute
+ * the visual dimming/highlighting of nodes and edges.
+ *
+ * Algorithm:
+ * - `executedSteps` provides O(1) lookup for "has this step been reached?"
+ * - `executedStepsOrdered` preserves execution order for edge inference
+ * - `takenEdges` comes from `conditional-route` SSE events + linear step inference
+ * - `currentStepId` tracks the actively running step for animation
+ * - `stepStatusMap` provides final status for each executed step
+ * - `stepDataMap` provides detailed execution data (duration, input, output, error)
+ */
+export interface ExecutionPathState {
+  /** Set of step IDs that have been executed (O(1) lookup) */
+  executedSteps: Set<string>
+
+  /** Step IDs in execution order (for inferring linear edges) */
+  executedStepsOrdered: string[]
+
+  /** Set of edge IDs that were traversed (format: "edge-{source}-{target}") */
+  takenEdges: Set<string>
+
+  /** Currently running step ID (undefined if no step is running) */
+  currentStepId?: string
+
+  /** Map of step IDs to their final execution status */
+  stepStatusMap?: Map<string, 'pending' | 'running' | 'completed' | 'failed'>
+
+  /** Map of step IDs to their execution data (duration, input, output, error) */
+  stepDataMap?: Map<string, StepExecutionData>
+}

package/src/execution/external/__tests__/api-schemas.test.ts

@@ -1,127 +1,127 @@
-import { describe, expect, it } from 'vitest'
-import { ExecuteAsyncEnvelopeSchema, GetExecutionsQuerySchema } from '../api-schemas'
-
-// ---------------------------------------------------------------------------
-// ExecuteAsyncEnvelopeSchema
-// ---------------------------------------------------------------------------
-
-describe('ExecuteAsyncEnvelopeSchema', () => {
-  it('accepts a minimal payload with only resourceId', () => {
-    const result = ExecuteAsyncEnvelopeSchema.safeParse({ resourceId: 'my-workflow' })
-    expect(result.success).toBe(true)
-  })
-
-  it('accepts resourceId with optional input passthrough', () => {
-    const result = ExecuteAsyncEnvelopeSchema.safeParse({
-      resourceId: 'my-workflow',
-      input: { foo: 'bar', nested: { count: 5 } }
-    })
-    expect(result.success).toBe(true)
-    if (result.success) {
-      expect(result.data.resourceId).toBe('my-workflow')
-      expect(result.data.input).toEqual({ foo: 'bar', nested: { count: 5 } })
-    }
-  })
-
-  it('accepts any arbitrary input shape (unknown passthrough)', () => {
-    const result = ExecuteAsyncEnvelopeSchema.safeParse({
-      resourceId: 'some-resource',
-      input: [1, 2, 3]
-    })
-    expect(result.success).toBe(true)
-  })
-
-  it('accepts input as null (unknown type allows null)', () => {
-    const result = ExecuteAsyncEnvelopeSchema.safeParse({ resourceId: 'r', input: null })
-    expect(result.success).toBe(true)
-  })
-
-  it('accepts payload without input field (input is optional)', () => {
-    const result = ExecuteAsyncEnvelopeSchema.safeParse({ resourceId: 'r' })
-    expect(result.success).toBe(true)
-    if (result.success) {
-      expect(result.data.input).toBeUndefined()
-    }
-  })
-
-  it('rejects an empty resourceId (minLength 1)', () => {
-    expect(ExecuteAsyncEnvelopeSchema.safeParse({ resourceId: '' }).success).toBe(false)
-  })
-
-  it('rejects a missing resourceId', () => {
-    expect(ExecuteAsyncEnvelopeSchema.safeParse({}).success).toBe(false)
-    expect(ExecuteAsyncEnvelopeSchema.safeParse({ input: { x: 1 } }).success).toBe(false)
-  })
-
-  it('rejects resourceId as a non-string type', () => {
-    expect(ExecuteAsyncEnvelopeSchema.safeParse({ resourceId: 42 }).success).toBe(false)
-    expect(ExecuteAsyncEnvelopeSchema.safeParse({ resourceId: null }).success).toBe(false)
-  })
-})
-
-// ---------------------------------------------------------------------------
-// GetExecutionsQuerySchema
-// ---------------------------------------------------------------------------
-
-describe('GetExecutionsQuerySchema', () => {
-  it('accepts an empty query and applies default limit of 50', () => {
-    const result = GetExecutionsQuerySchema.safeParse({})
-    expect(result.success).toBe(true)
-    if (result.success) {
-      expect(result.data.limit).toBe(50)
-    }
-  })
-
-  it('coerces limit from string "10" to number 10', () => {
-    const result = GetExecutionsQuerySchema.safeParse({ limit: '10' })
-    expect(result.success).toBe(true)
-    if (result.success) expect(result.data.limit).toBe(10)
-  })
-
-  it('coerces limit from string "100" to number 100 (upper boundary)', () => {
-    const result = GetExecutionsQuerySchema.safeParse({ limit: '100' })
-    expect(result.success).toBe(true)
-    if (result.success) expect(result.data.limit).toBe(100)
-  })
-
-  it('coerces limit from string "1" to number 1 (lower boundary)', () => {
-    const result = GetExecutionsQuerySchema.safeParse({ limit: '1' })
-    expect(result.success).toBe(true)
-    if (result.success) expect(result.data.limit).toBe(1)
-  })
-
-  it('rejects limit of 101 (above max 100)', () => {
-    expect(GetExecutionsQuerySchema.safeParse({ limit: '101' }).success).toBe(false)
-  })
-
-  it('rejects limit of 0 (below min 1)', () => {
-    expect(GetExecutionsQuerySchema.safeParse({ limit: '0' }).success).toBe(false)
-  })
-
-  it('rejects a negative limit', () => {
-    expect(GetExecutionsQuerySchema.safeParse({ limit: '-1' }).success).toBe(false)
-  })
-
-  it('rejects a non-numeric string for limit', () => {
-    expect(GetExecutionsQuerySchema.safeParse({ limit: 'abc' }).success).toBe(false)
-  })
-
-  it('accepts status as an optional string filter', () => {
-    const result = GetExecutionsQuerySchema.safeParse({ status: 'running' })
-    expect(result.success).toBe(true)
-    if (result.success) expect(result.data.status).toBe('running')
-  })
-
-  it('accepts status as undefined (optional field omitted)', () => {
-    const result = GetExecutionsQuerySchema.safeParse({})
-    expect(result.success).toBe(true)
-    if (result.success) expect(result.data.status).toBeUndefined()
-  })
-
-  it('note: GetExecutionsQuerySchema does not have an offset field', () => {
-    // The schema only defines limit and status -- no offset field exists.
-    // Passing offset is neither rejected nor coerced (schema is not strict).
-    const result = GetExecutionsQuerySchema.safeParse({ limit: '10', offset: '5' })
-    expect(result.success).toBe(true)
-  })
-})
+import { describe, expect, it } from 'vitest'
+import { ExecuteAsyncEnvelopeSchema, GetExecutionsQuerySchema } from '../api-schemas'
+
+// ---------------------------------------------------------------------------
+// ExecuteAsyncEnvelopeSchema
+// ---------------------------------------------------------------------------
+
+describe('ExecuteAsyncEnvelopeSchema', () => {
+  it('accepts a minimal payload with only resourceId', () => {
+    const result = ExecuteAsyncEnvelopeSchema.safeParse({ resourceId: 'my-workflow' })
+    expect(result.success).toBe(true)
+  })
+
+  it('accepts resourceId with optional input passthrough', () => {
+    const result = ExecuteAsyncEnvelopeSchema.safeParse({
+      resourceId: 'my-workflow',
+      input: { foo: 'bar', nested: { count: 5 } }
+    })
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data.resourceId).toBe('my-workflow')
+      expect(result.data.input).toEqual({ foo: 'bar', nested: { count: 5 } })
+    }
+  })
+
+  it('accepts any arbitrary input shape (unknown passthrough)', () => {
+    const result = ExecuteAsyncEnvelopeSchema.safeParse({
+      resourceId: 'some-resource',
+      input: [1, 2, 3]
+    })
+    expect(result.success).toBe(true)
+  })
+
+  it('accepts input as null (unknown type allows null)', () => {
+    const result = ExecuteAsyncEnvelopeSchema.safeParse({ resourceId: 'r', input: null })
+    expect(result.success).toBe(true)
+  })
+
+  it('accepts payload without input field (input is optional)', () => {
+    const result = ExecuteAsyncEnvelopeSchema.safeParse({ resourceId: 'r' })
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data.input).toBeUndefined()
+    }
+  })
+
+  it('rejects an empty resourceId (minLength 1)', () => {
+    expect(ExecuteAsyncEnvelopeSchema.safeParse({ resourceId: '' }).success).toBe(false)
+  })
+
+  it('rejects a missing resourceId', () => {
+    expect(ExecuteAsyncEnvelopeSchema.safeParse({}).success).toBe(false)
+    expect(ExecuteAsyncEnvelopeSchema.safeParse({ input: { x: 1 } }).success).toBe(false)
+  })
+
+  it('rejects resourceId as a non-string type', () => {
+    expect(ExecuteAsyncEnvelopeSchema.safeParse({ resourceId: 42 }).success).toBe(false)
+    expect(ExecuteAsyncEnvelopeSchema.safeParse({ resourceId: null }).success).toBe(false)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// GetExecutionsQuerySchema
+// ---------------------------------------------------------------------------
+
+describe('GetExecutionsQuerySchema', () => {
+  it('accepts an empty query and applies default limit of 50', () => {
+    const result = GetExecutionsQuerySchema.safeParse({})
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data.limit).toBe(50)
+    }
+  })
+
+  it('coerces limit from string "10" to number 10', () => {
+    const result = GetExecutionsQuerySchema.safeParse({ limit: '10' })
+    expect(result.success).toBe(true)
+    if (result.success) expect(result.data.limit).toBe(10)
+  })
+
+  it('coerces limit from string "100" to number 100 (upper boundary)', () => {
+    const result = GetExecutionsQuerySchema.safeParse({ limit: '100' })
+    expect(result.success).toBe(true)
+    if (result.success) expect(result.data.limit).toBe(100)
+  })
+
+  it('coerces limit from string "1" to number 1 (lower boundary)', () => {
+    const result = GetExecutionsQuerySchema.safeParse({ limit: '1' })
+    expect(result.success).toBe(true)
+    if (result.success) expect(result.data.limit).toBe(1)
+  })
+
+  it('rejects limit of 101 (above max 100)', () => {
+    expect(GetExecutionsQuerySchema.safeParse({ limit: '101' }).success).toBe(false)
+  })
+
+  it('rejects limit of 0 (below min 1)', () => {
+    expect(GetExecutionsQuerySchema.safeParse({ limit: '0' }).success).toBe(false)
+  })
+
+  it('rejects a negative limit', () => {
+    expect(GetExecutionsQuerySchema.safeParse({ limit: '-1' }).success).toBe(false)
+  })
+
+  it('rejects a non-numeric string for limit', () => {
+    expect(GetExecutionsQuerySchema.safeParse({ limit: 'abc' }).success).toBe(false)
+  })
+
+  it('accepts status as an optional string filter', () => {
+    const result = GetExecutionsQuerySchema.safeParse({ status: 'running' })
+    expect(result.success).toBe(true)
+    if (result.success) expect(result.data.status).toBe('running')
+  })
+
+  it('accepts status as undefined (optional field omitted)', () => {
+    const result = GetExecutionsQuerySchema.safeParse({})
+    expect(result.success).toBe(true)
+    if (result.success) expect(result.data.status).toBeUndefined()
+  })
+
+  it('note: GetExecutionsQuerySchema does not have an offset field', () => {
+    // The schema only defines limit and status -- no offset field exists.
+    // Passing offset is neither rejected nor coerced (schema is not strict).
+    const result = GetExecutionsQuerySchema.safeParse({ limit: '10', offset: '5' })
+    expect(result.success).toBe(true)
+  })
+})