@elevasis/core 0.1.0

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

@@ -0,0 +1,280 @@
+/**
+ * Workflow utility functions
+ */
+
+import type { z } from 'zod'
+import type { ExecutionContext } from '../base/types'
+import type { WorkflowStep, ConditionalNext } from './types'
+import { StepType } from './types'
+import type {
+  WorkflowExecutionContext,
+  WorkflowFailureContext,
+  StepStartedContext,
+  StepCompletedContext,
+  StepFailedContext,
+  ConditionalRouteContext,
+  ExecutionPathContext
+} from './logging'
+import { errorToString } from '../../../platform/utils/error'
+import { truncateForLogging } from './log-truncate'
+import { WorkflowStepError, WorkflowValidationError } from './errors'
+
+/**
+ * Validation utilities
+ */
+
+export function validateEntryPoint(steps: Record<string, WorkflowStep>, entryPoint: string): void {
+  if (!(entryPoint in steps)) {
+    throw new WorkflowValidationError(`Entry point step '${entryPoint}' not found in workflow`, {
+      entryPoint
+    })
+  }
+}
+
+function findTerminalSteps(steps: Record<string, WorkflowStep>): WorkflowStep[] {
+  return Object.values(steps).filter((step) => step.next === null)
+}
+
+export function validateTerminalSteps(steps: Record<string, WorkflowStep>, workflowId: string): void {
+  const terminalSteps = findTerminalSteps(steps)
+  if (terminalSteps.length === 0) {
+    throw new WorkflowValidationError(`Workflow '${workflowId}' must have at least one terminal step (next: null)`, {
+      workflowId
+    })
+  }
+  // Validation passed - terminal steps exist
+  // (Previously logged in development, removed to eliminate process.env dependency)
+}
+
+export function validateStepReferences(steps: Record<string, WorkflowStep>): void {
+  for (const [id, step] of Object.entries(steps)) {
+    if (step.next === null) {
+      // Terminal step - no validation needed
+      continue
+    }
+
+    if (step.next.type === StepType.LINEAR) {
+      if (!(step.next.target in steps)) {
+        throw new WorkflowValidationError(`Step '${id}' references non-existent target '${step.next.target}'`, {
+          stepId: id,
+          target: step.next.target
+        })
+      }
+    } else if (step.next.type === StepType.CONDITIONAL) {
+      const targets = [...step.next.routes.map((r: { target: string }) => r.target), step.next.default]
+      for (const target of targets) {
+        if (!(target in steps)) {
+          throw new WorkflowValidationError(`Step '${id}' references non-existent target '${target}'`, {
+            stepId: id,
+            target
+          })
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Execution utilities
+ */
+
+export function detectCycle(visited: Set<string>, executionPath: string[], currentStepId: string): void {
+  if (visited.has(currentStepId)) {
+    const cycle = executionPath.slice(executionPath.indexOf(currentStepId))
+    throw new WorkflowStepError(`Cycle detected in workflow: ${cycle.join(' -> ')} -> ${currentStepId}`, {
+      stepId: currentStepId,
+      cycle: [...cycle, currentStepId]
+    })
+  }
+}
+
+export function validateTerminalOutput(stepId: string, output: unknown, outputSchema?: z.ZodSchema): void {
+  // Early return if no schema provided (fire-and-forget workflow)
+  if (!outputSchema) {
+    return
+  }
+
+  try {
+    outputSchema.parse(output)
+  } catch (error) {
+    throw new WorkflowValidationError(
+      `Terminal step '${stepId}' produced invalid output: ${error instanceof Error ? error.message : String(error)}`,
+      { stepId, validationError: error instanceof Error ? error.message : String(error) }
+    )
+  }
+}
+
+export async function determineNextStep(
+  step: WorkflowStep,
+  currentData: unknown,
+  context: ExecutionContext
+): Promise<string | null> {
+  const { next } = step
+
+  // Null means workflow ends here
+  if (next === null) {
+    return null
+  }
+
+  // Linear progression to specific step
+  if (next.type === StepType.LINEAR) {
+    return next.target
+  }
+
+  // Conditional routing
+  if (next.type === StepType.CONDITIONAL) {
+    return evaluateConditionalRoutes(step.id, next, currentData, context)
+  }
+
+  throw new WorkflowStepError(`Unknown next configuration type in step ${step.id}`, {
+    stepId: step.id
+  })
+}
+
+async function evaluateConditionalRoutes(
+  stepId: string,
+  next: ConditionalNext,
+  currentData: unknown,
+  context: ExecutionContext
+): Promise<string> {
+  // Evaluate conditions in order
+  for (const route of next.routes) {
+    try {
+      if (route.condition(currentData)) {
+        context.logger.debug(`Conditional route taken: ${stepId} -> ${route.target}`, {
+          type: 'workflow',
+          contextType: 'conditional-route',
+          stepId,
+          target: route.target
+        } as ConditionalRouteContext)
+        return route.target
+      }
+    } catch (error) {
+      context.logger.warn(`Error evaluating condition in step ${stepId}: ${error}`, {
+        type: 'workflow',
+        contextType: 'conditional-route',
+        stepId,
+        target: '',
+        error: errorToString(error)
+      } as ConditionalRouteContext)
+    }
+  }
+
+  // Use default if no conditions match
+  context.logger.debug(`Using default route: ${stepId} -> ${next.default}`, {
+    type: 'workflow',
+    contextType: 'conditional-route',
+    stepId,
+    target: next.default
+  } as ConditionalRouteContext)
+  return next.default
+}
+
+/**
+ * Graph analysis utilities
+ */
+
+/**
+ * Logging helper utilities
+ */
+
+export function logWorkflowStart(context: ExecutionContext, workflowId: string, workflowName: string): void {
+  context.logger.info(`Executing workflow: ${workflowId}`, {
+    type: 'workflow',
+    contextType: 'workflow-execution',
+    executionId: context.executionId,
+    workflowId,
+    workflowName,
+    organizationId: context.organizationId
+  } as WorkflowExecutionContext)
+}
+
+export function logWorkflowSuccess(context: ExecutionContext, workflowId: string, executionPath: string[]): void {
+  context.logger.info(`Workflow completed successfully: ${workflowId}`, {
+    type: 'workflow',
+    contextType: 'workflow-execution',
+    executionId: context.executionId,
+    workflowId,
+    organizationId: context.organizationId,
+    executionPath
+  } as WorkflowExecutionContext)
+}
+
+export function logWorkflowFailure(context: ExecutionContext, workflowId: string, error: unknown): void {
+  context.logger.error(`Execution failed: workflow/${workflowId}`, {
+    type: 'workflow',
+    contextType: 'workflow-failure',
+    executionId: context.executionId,
+    workflowId,
+    error: errorToString(error)
+  } as WorkflowFailureContext)
+}
+
+export function logStepStart(
+  context: ExecutionContext,
+  stepId: string,
+  stepName: string,
+  input: unknown,
+  startTime: number
+): void {
+  context.logger.info(`Step started: ${stepName}`, {
+    type: 'workflow',
+    contextType: 'step-started',
+    stepId,
+    stepStatus: 'started',
+    input: truncateForLogging(input),
+    startTime
+  } as StepStartedContext)
+}
+
+export function logStepSuccess(
+  context: ExecutionContext,
+  stepId: string,
+  stepName: string,
+  output: unknown,
+  duration: number,
+  isTerminal: boolean,
+  startTime: number,
+  endTime: number
+): void {
+  context.logger.info(`Step completed: ${stepName}`, {
+    type: 'workflow',
+    contextType: 'step-completed',
+    stepId,
+    stepStatus: 'completed',
+    output: truncateForLogging(output),
+    duration,
+    isTerminal,
+    startTime,
+    endTime
+  } as StepCompletedContext)
+}
+
+export function logStepFailure(
+  context: ExecutionContext,
+  stepId: string,
+  stepName: string,
+  error: unknown,
+  duration: number,
+  startTime: number,
+  endTime: number
+): void {
+  context.logger.error(`Step failed: ${stepName}`, {
+    type: 'workflow',
+    contextType: 'step-failed',
+    stepId,
+    stepStatus: 'failed',
+    error: errorToString(error),
+    duration,
+    startTime,
+    endTime
+  } as StepFailedContext)
+}
+
+export function logExecutionPath(context: ExecutionContext, executionPath: string[]): void {
+  context.logger.info(`Workflow completed. Execution path: ${executionPath.join(' -> ')}`, {
+    type: 'workflow',
+    contextType: 'execution-path',
+    executionPath
+  } as ExecutionPathContext)
+}

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

@@ -0,0 +1,168 @@
+/**
+ * Graph-based Workflow execution implementation
+ */
+
+import type { Contract, ExecutionContext } from '../base/types'
+import type { WorkflowConfig, WorkflowStep, WorkflowDefinition } from './types'
+import {
+  validateEntryPoint,
+  validateTerminalSteps,
+  validateStepReferences,
+  detectCycle,
+  validateTerminalOutput,
+  determineNextStep,
+  logWorkflowStart,
+  logWorkflowSuccess,
+  logWorkflowFailure,
+  logStepStart,
+  logStepSuccess,
+  logStepFailure,
+  logExecutionPath
+} from './utils'
+import { errorToString } from '../../../platform/utils/error'
+import { WorkflowStepError } from './errors'
+
+/**
+ * Workflow class with type-safe input/output
+ *
+ * @template TInput - Input type validated by contract.inputSchema
+ * @template TOutput - Output type validated by contract.outputSchema
+ */
+export class Workflow<TInput = unknown, TOutput = unknown> {
+  public readonly config: WorkflowConfig
+  public readonly contract: Contract
+  public readonly steps: Record<string, WorkflowStep>
+  public readonly entryPoint: string
+
+  // Derived properties (computed from definition)
+  private readonly shouldGenerateOutput: boolean
+
+  /**
+   * Create a new workflow instance from definition
+   *
+   * @param definition - Workflow definition with config, contract, steps, and entryPoint
+   */
+  constructor(definition: WorkflowDefinition) {
+    this.config = definition.config
+    this.contract = definition.contract
+    this.steps = definition.steps
+    this.entryPoint = definition.entryPoint
+
+    // Derive shouldGenerateOutput from outputSchema presence
+    this.shouldGenerateOutput = !!definition.contract.outputSchema
+
+    // Run all validations
+    validateEntryPoint(this.steps, this.entryPoint)
+    validateTerminalSteps(this.steps, this.config.resourceId)
+    validateStepReferences(this.steps)
+  }
+
+  /**
+   * Execute the workflow with graph-based flow control
+   * Context is required for execution tracking, logging, and organization isolation
+   * @returns Validated output matching contract.outputSchema, or null if no output schema
+   */
+  async execute(input: TInput, context: ExecutionContext): Promise<TOutput | null> {
+    // Log workflow start
+    logWorkflowStart(context, this.config.resourceId, this.config.name)
+
+    try {
+      // Validate input
+      const validated = this.contract.inputSchema.parse(input) as TInput
+
+      // Track visited steps to detect cycles
+      const visited = new Set<string>()
+      const executionPath: string[] = []
+
+      // Start execution from entry point
+      let currentData: unknown = validated
+      let currentStepId: string | null = this.entryPoint
+
+      while (currentStepId !== null) {
+        // Cycle detection
+        detectCycle(visited, executionPath, currentStepId)
+        visited.add(currentStepId)
+        executionPath.push(currentStepId)
+
+        // Get current step
+        const step = this.steps[currentStepId]
+        if (!step) {
+          throw new WorkflowStepError(`Step '${currentStepId}' not found in workflow`, {
+            stepId: currentStepId,
+            workflowId: this.config.resourceId,
+            executionId: context.executionId,
+            organizationId: context.organizationId,
+            executionPath
+          })
+        }
+
+        // Execute step
+        const stepStartTime = Date.now()
+        logStepStart(context, step.id, step.name, currentData, stepStartTime)
+
+        try {
+          // 1. Validate step input
+          const validatedInput = step.inputSchema.parse(currentData)
+
+          // 2. Execute the step handler with validated input
+          const rawOutput = await step.handler(validatedInput, context)
+
+          // 3. Validate step output
+          currentData = step.outputSchema.parse(rawOutput)
+
+          // 4. Validate terminal step output against workflow contract (if output generation enabled)
+          if (step.next === null && this.shouldGenerateOutput) {
+            validateTerminalOutput(step.id, currentData, this.contract.outputSchema)
+          }
+
+          // Log step completion
+          const stepEndTime = Date.now()
+          const duration = stepEndTime - stepStartTime
+          logStepSuccess(
+            context,
+            step.id,
+            step.name,
+            currentData,
+            duration,
+            step.next === null,
+            stepStartTime,
+            stepEndTime
+          )
+
+          // Determine next step (currentData is now validated)
+          currentStepId = await determineNextStep(step, currentData, context)
+        } catch (error) {
+          // Log step failure
+          const stepEndTime = Date.now()
+          const duration = stepEndTime - stepStartTime
+          logStepFailure(context, step.id, step.name, error, duration, stepStartTime, stepEndTime)
+
+          throw new WorkflowStepError(`Step failed [${step.id}:${step.name}]: ${errorToString(error)}`, {
+            stepId: step.id,
+            stepName: step.name,
+            workflowId: this.config.resourceId,
+            executionId: context.executionId,
+            duration: stepEndTime - stepStartTime
+          })
+        }
+      }
+
+      // Log execution path
+      logExecutionPath(context, executionPath)
+
+      // Log workflow success
+      logWorkflowSuccess(context, this.config.resourceId, executionPath)
+
+      // Return null if no output generation (fire-and-forget), otherwise return validated result
+      if (!this.shouldGenerateOutput) {
+        return null
+      }
+
+      return currentData as TOutput
+    } catch (error) {
+      // Log workflow failure
+      logWorkflowFailure(context, this.config.resourceId, error)
+      throw error
+    }
+  }
+}

package/src/execution/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Execution group barrel - browser-safe exports
+ *
+ * Execution engine, core types, scheduler, calibration
+ */
+
+// Execution Engine
+export * from './engine/index'
+
+// Execution utilities and validation (shared by TaskScheduler, CommandQueue, Sessions)
+export * from './core/index'
+
+// Scheduler types
+export * from './scheduler/index'
+
+// Calibration types and schemas
+export * from './calibration/index'
+
+// Integration types (browser-safe param/result interfaces for adapters)
+export * from './engine/tools/integration/types'