@open-mercato/core 0.6.4-develop.4371.1.8f3030407e → 0.6.4

package/src/modules/workflows/lib/step-handler.ts

@@ -12,6 +12,7 @@
 import { EntityManager } from '@mikro-orm/core'
 import {
   WorkflowInstance,
+  WorkflowBranchInstance,
   WorkflowDefinition,
   StepInstance,
   UserTask,
@@ -36,7 +37,7 @@ export interface StepExecutionResult {
   status: 'COMPLETED' | 'WAITING' | 'FAILED'
   outputData?: any
   nextSteps?: string[] // For parallel forks (Phase 7)
-  waitReason?: 'USER_TASK' | 'SIGNAL' | 'TIMER'
+  waitReason?: 'USER_TASK' | 'SIGNAL' | 'TIMER' | 'FORK'
   error?: string
 }
 
@@ -68,7 +69,8 @@ export async function enterStep(
   em: EntityManager,
   instance: WorkflowInstance,
   stepId: string,
-  context: StepExecutionContext
+  context: StepExecutionContext,
+  branch?: WorkflowBranchInstance | null
 ): Promise<StepInstance> {
   // Load workflow definition to get step details
   const definition = await em.findOne(WorkflowDefinition, {
@@ -98,6 +100,7 @@ export async function enterStep(
   // Create step instance
   const stepInstance = em.create(StepInstance, {
     workflowInstanceId: instance.id,
+    branchInstanceId: branch ? branch.id : null,
     stepId: stepDef.stepId,
     stepName: stepDef.stepName,
     stepType: stepDef.stepType,
@@ -117,6 +120,7 @@ export async function enterStep(
   await logStepEvent(em, {
     workflowInstanceId: instance.id,
     stepInstanceId: stepInstance.id,
+    ...(branch ? { branchInstanceId: branch.id } : {}),
     eventType: 'STEP_ENTERED',
     eventData: {
       stepId: stepDef.stepId,
@@ -198,11 +202,12 @@ export async function executeStep(
   instance: WorkflowInstance,
   stepId: string,
   context: StepExecutionContext,
-  container?: any
+  container?: any,
+  branch?: WorkflowBranchInstance | null
 ): Promise<StepExecutionResult> {
   try {
     // Enter the step (create step instance)
-    const stepInstance = await enterStep(em, instance, stepId, context)
+    const stepInstance = await enterStep(em, instance, stepId, context, branch)
 
     // Load workflow definition to get step configuration
     const definition = await em.findOne(WorkflowDefinition, {
@@ -233,7 +238,8 @@ export async function executeStep(
       stepInstance,
       stepDef,
       context,
-      container
+      container,
+      branch
     )
 
     // If step completed, exit it
@@ -305,7 +311,8 @@ async function executeStepByType(
   stepInstance: StepInstance,
   stepDef: any,
   context: StepExecutionContext,
-  container?: any
+  container?: any,
+  branch?: WorkflowBranchInstance | null
 ): Promise<StepExecutionResult> {
   const stepType: WorkflowStepType = stepDef.stepType
 
@@ -317,10 +324,10 @@ async function executeStepByType(
       return handleEndStep(stepDef, context)
 
     case 'AUTOMATED':
-      return await handleAutomatedStep(em, instance, stepInstance, stepDef, context, container)
+      return await handleAutomatedStep(em, instance, stepInstance, stepDef, context, container, branch)
 
     case 'USER_TASK':
-      return await handleUserTaskStep(em, instance, stepInstance, stepDef, context)
+      return await handleUserTaskStep(em, instance, stepInstance, stepDef, context, branch)
 
     case 'SUB_WORKFLOW':
       if (!container) {
@@ -333,19 +340,40 @@ async function executeStepByType(
       return await handleSubWorkflowStep(em, container, instance, stepInstance, stepDef, context)
 
     case 'WAIT_FOR_SIGNAL':
-      return await handleWaitForSignalStep(em, instance, stepInstance, stepDef, context)
+      return await handleWaitForSignalStep(em, instance, stepInstance, stepDef, context, branch)
 
     case 'WAIT_FOR_TIMER':
-      return await handleWaitForTimerStep(em, instance, stepInstance, stepDef, context)
+      return await handleWaitForTimerStep(em, instance, stepInstance, stepDef, context, branch)
+
+    case 'PARALLEL_FORK': {
+      // Entering a fork opens branch tokens and parks the root token in the
+      // FORKED state; the interleaved loop in the executor drives the branches.
+      if (branch) {
+        // Nested forks are rejected by definition validation; fail closed.
+        throw new StepExecutionError(
+          'Nested PARALLEL_FORK is not supported',
+          'NESTED_FORK_NOT_SUPPORTED',
+          { stepType, stepId: stepDef.stepId }
+        )
+      }
+      const definition = await em.findOne(WorkflowDefinition, { id: instance.definitionId })
+      if (!definition) {
+        throw new StepExecutionError(
+          `Workflow definition not found: ${instance.definitionId}`,
+          'DEFINITION_NOT_FOUND',
+          { definitionId: instance.definitionId }
+        )
+      }
+      const { openFork } = await import('./parallel-handler')
+      await openFork(em, instance, definition, stepDef)
+      return { status: 'WAITING', waitReason: 'FORK', outputData: { stepType: 'PARALLEL_FORK', forkStepId: stepDef.stepId } }
+    }
 
-    case 'PARALLEL_FORK':
     case 'PARALLEL_JOIN':
-      // These will be implemented in later phases
-      throw new StepExecutionError(
-        `Step type not yet implemented: ${stepType}`,
-        'STEP_TYPE_NOT_IMPLEMENTED',
-        { stepType }
-      )
+      // The join is a synchronization point handled by the parallel loop
+      // (branches are marked COMPLETED on arrival; the loop fires the join).
+      // Executing the step itself is a no-op.
+      return { status: 'COMPLETED', outputData: { stepType: 'PARALLEL_JOIN', timestamp: new Date().toISOString() } }
 
     default:
       throw new StepExecutionError(
@@ -401,7 +429,8 @@ async function handleAutomatedStep(
   stepInstance: StepInstance,
   stepDef: any,
   context: StepExecutionContext,
-  container?: any
+  container?: any,
+  branch?: WorkflowBranchInstance | null
 ): Promise<StepExecutionResult> {
   // Extract activities from step definition
   const activities = stepDef.activities || []
@@ -434,9 +463,15 @@ async function handleAutomatedStep(
     const pendingActivities = results.filter(r => r.async && !r.success)
     if (pendingActivities.length > 0) {
       // Workflow should pause and wait for async activities
-      instance.status = 'WAITING_FOR_ACTIVITIES'
-      instance.pausedAt = new Date()
-      instance.updatedAt = new Date()
+      const now = new Date()
+      if (branch) {
+        branch.status = 'WAITING_FOR_ACTIVITIES'
+        branch.updatedAt = now
+      } else {
+        instance.status = 'WAITING_FOR_ACTIVITIES'
+        instance.pausedAt = now
+        instance.updatedAt = now
+      }
       await em.flush()
 
       return {
@@ -506,7 +541,8 @@ async function handleUserTaskStep(
   instance: WorkflowInstance,
   stepInstance: StepInstance,
   stepDef: any,
-  context: StepExecutionContext
+  context: StepExecutionContext,
+  branch?: WorkflowBranchInstance | null
 ): Promise<StepExecutionResult> {
   const userTaskConfig = stepDef.userTaskConfig || {}
 
@@ -524,6 +560,7 @@ async function handleUserTaskStep(
   const userTask = em.create(UserTask, {
     workflowInstanceId: instance.id,
     stepInstanceId: stepInstance.id,
+    branchInstanceId: branch ? branch.id : null,
     taskName: stepDef.stepName,
     description: stepDef.description || null,
     status: 'PENDING',
@@ -544,6 +581,7 @@ async function handleUserTaskStep(
   await logStepEvent(em, {
     workflowInstanceId: instance.id,
     stepInstanceId: stepInstance.id,
+    ...(branch ? { branchInstanceId: branch.id } : {}),
     eventType: 'USER_TASK_CREATED',
     eventData: {
       userTaskId: userTask.id,
@@ -555,9 +593,15 @@ async function handleUserTaskStep(
     organizationId: instance.organizationId,
   })
 
-  // Pause workflow execution - workflow waits for user task completion
-  instance.status = 'PAUSED'
-  instance.updatedAt = now
+  // Pause execution - waits for user task completion. For a branch, only the
+  // branch pauses; sibling branches keep running.
+  if (branch) {
+    branch.status = 'PAUSED'
+    branch.updatedAt = now
+  } else {
+    instance.status = 'PAUSED'
+    instance.updatedAt = now
+  }
   await em.flush()
 
   return {
@@ -719,7 +763,8 @@ async function handleWaitForSignalStep(
   instance: WorkflowInstance,
   stepInstance: StepInstance,
   stepDef: any,
-  context: StepExecutionContext
+  context: StepExecutionContext,
+  branch?: WorkflowBranchInstance | null
 ): Promise<StepExecutionResult> {
   const signalConfig = stepDef.signalConfig || {}
   const signalName = signalConfig.signalName || stepDef.stepId
@@ -731,6 +776,7 @@ async function handleWaitForSignalStep(
   await logStepEvent(em, {
     workflowInstanceId: instance.id,
     stepInstanceId: stepInstance.id,
+    ...(branch ? { branchInstanceId: branch.id } : {}),
     eventType: 'SIGNAL_AWAITING',
     eventData: {
       signalName,
@@ -742,10 +788,15 @@ async function handleWaitForSignalStep(
     organizationId: instance.organizationId,
   })
 
-  // Pause workflow execution
-  instance.status = 'PAUSED'
-  instance.pausedAt = now
-  instance.updatedAt = now
+  // Pause execution (branch-scoped when running inside a parallel branch)
+  if (branch) {
+    branch.status = 'PAUSED'
+    branch.updatedAt = now
+  } else {
+    instance.status = 'PAUSED'
+    instance.pausedAt = now
+    instance.updatedAt = now
+  }
   await em.flush()
 
   // Return WAITING status to halt executor
@@ -774,7 +825,8 @@ async function handleWaitForTimerStep(
   instance: WorkflowInstance,
   stepInstance: StepInstance,
   stepDef: any,
-  context: StepExecutionContext
+  context: StepExecutionContext,
+  branch?: WorkflowBranchInstance | null
 ): Promise<StepExecutionResult> {
   const timerConfig = stepDef.config || stepDef.timerConfig || {}
   const duration: string | undefined = timerConfig.duration
@@ -828,6 +880,7 @@ async function handleWaitForTimerStep(
   const jobId = await enqueueTimerJob({
     workflowInstanceId: instance.id,
     stepInstanceId: stepInstance.id,
+    branchInstanceId: branch ? branch.id : undefined,
     tenantId: instance.tenantId,
     organizationId: instance.organizationId,
     userId: context.userId,
@@ -838,6 +891,7 @@ async function handleWaitForTimerStep(
   await logWorkflowEvent(em, {
     workflowInstanceId: instance.id,
     stepInstanceId: stepInstance.id,
+    ...(branch ? { branchInstanceId: branch.id } : {}),
     eventType: 'TIMER_AWAITING',
     eventData: {
       fireAt: fireAt.toISOString(),
@@ -850,9 +904,14 @@ async function handleWaitForTimerStep(
     organizationId: instance.organizationId,
   })
 
-  instance.status = 'PAUSED'
-  instance.pausedAt = now
-  instance.updatedAt = now
+  if (branch) {
+    branch.status = 'PAUSED'
+    branch.updatedAt = now
+  } else {
+    instance.status = 'PAUSED'
+    instance.pausedAt = now
+    instance.updatedAt = now
+  }
   await em.flush()
 
   return {
@@ -881,6 +940,7 @@ async function logStepEvent(
   event: {
     workflowInstanceId: string
     stepInstanceId: string
+    branchInstanceId?: string | null
     eventType: string
     eventData: any
     userId?: string

package/src/modules/workflows/lib/task-handler.ts

@@ -120,6 +120,37 @@ export async function completeUserTask(
     )
   }
 
+  // Branch-scoped completion: when the task belongs to a parallel branch,
+  // merge form data into the branch namespace and resume just that branch.
+  if (task.branchInstanceId) {
+    await logWorkflowEvent(em, {
+      workflowInstanceId: instance.id,
+      stepInstanceId: task.stepInstanceId,
+      branchInstanceId: task.branchInstanceId,
+      eventType: 'USER_TASK_COMPLETED',
+      eventData: { taskId: task.id, taskName: task.taskName, completedBy: userId, formData },
+      userId,
+      tenantId: instance.tenantId,
+      organizationId: instance.organizationId,
+    })
+
+    const { resumeBranch } = await import('./parallel-handler')
+    const resumed = await resumeBranch(em, {
+      instanceId: instance.id,
+      branchInstanceId: task.branchInstanceId,
+      tenantId: instance.tenantId,
+      organizationId: instance.organizationId,
+      contextMerge: formData,
+      exitStepInstanceId: task.stepInstanceId,
+      exitOutput: { userTaskId: task.id, formData },
+    })
+
+    if (resumed) {
+      await executeWorkflow(em, container, instance.id, { userId })
+    }
+    return
+  }
+
   // Merge form data into workflow context
   instance.context = {
     ...instance.context,
@@ -307,6 +338,7 @@ async function logWorkflowEvent(
   event: {
     workflowInstanceId: string
     stepInstanceId: string | null
+    branchInstanceId?: string | null
     eventType: string
     eventData: any
     userId?: string

package/src/modules/workflows/lib/timer-handler.ts

@@ -18,6 +18,7 @@ import type * as workflowExecutorModule from './workflow-executor'
 export interface FireTimerOptions {
   instanceId: string
   stepInstanceId?: string
+  branchInstanceId?: string | null
   userId?: string
   tenantId: string
   organizationId: string
@@ -46,13 +47,41 @@ export async function fireTimer(
   container: AwilixContainer,
   options: FireTimerOptions
 ): Promise<void> {
-  const { instanceId, stepInstanceId, userId, tenantId, organizationId } = options
+  const { instanceId, stepInstanceId, branchInstanceId, userId, tenantId, organizationId } = options
 
   const eventLogger = container.resolve<typeof eventLoggerModule>('eventLogger')
   const stepHandler = container.resolve<typeof stepHandlerModule>('stepHandler')
   const transitionHandler = container.resolve<typeof transitionHandlerModule>('transitionHandler')
   const workflowExecutor = container.resolve<typeof workflowExecutorModule>('workflowExecutor')
 
+  // Branch-scoped timer: the instance is FORKED and the branch is PAUSED at the
+  // WAIT_FOR_TIMER step. Resume just that branch, then drive the parallel loop.
+  if (branchInstanceId) {
+    await eventLogger.logWorkflowEvent(em, {
+      workflowInstanceId: instanceId,
+      stepInstanceId,
+      branchInstanceId,
+      eventType: 'TIMER_FIRED',
+      eventData: { firedAt: new Date().toISOString(), branch: true },
+      userId,
+      tenantId,
+      organizationId,
+    })
+    const { resumeBranch } = await import('./parallel-handler')
+    const resumed = await resumeBranch(em, {
+      instanceId,
+      branchInstanceId,
+      tenantId,
+      organizationId,
+      exitStepInstanceId: stepInstanceId,
+      exitOutput: { firedAt: new Date().toISOString() },
+    })
+    if (resumed) {
+      await workflowExecutor.executeWorkflow(em, container, instanceId, { userId })
+    }
+    return
+  }
+
   const instance = await findOneWithDecryption(
     em as PostgreSqlEntityManager,
     WorkflowInstance,

package/src/modules/workflows/lib/transition-handler.ts

@@ -23,6 +23,18 @@ import * as ruleEngine from '../../business_rules/lib/rule-engine'
 import * as activityExecutor from './activity-executor'
 import type { ActivityDefinition } from './activity-executor'
 import * as stepHandler from './step-handler'
+import {
+  type ExecutionToken,
+  rootToken,
+  tokenBranchInstanceId,
+  tokenReadContext,
+  setTokenCurrentStepId,
+  applyTokenContextWrites,
+  mergeTokenContext,
+  setTokenWaitingForActivities,
+  setTokenPendingTransition,
+  touchToken,
+} from './execution-token'
 
 // ============================================================================
 // Types and Interfaces
@@ -311,6 +323,28 @@ export async function executeTransition(
   toStepId: string,
   context: TransitionExecutionContext
 ): Promise<TransitionExecutionResult> {
+  // Public DI signature preserved: the root token adapts the instance, so the
+  // single-token path is behaviourally unchanged.
+  return executeTransitionForToken(em, container, rootToken(instance), fromStepId, toStepId, context)
+}
+
+/**
+ * Token-aware transition execution. The root token wraps a WorkflowInstance
+ * (legacy single-token path); a branch token wraps a WorkflowBranchInstance so
+ * a parallel branch advances independently with its own context namespace,
+ * status and pending transition.
+ */
+export async function executeTransitionForToken(
+  em: EntityManager,
+  container: AwilixContainer,
+  token: ExecutionToken,
+  fromStepId: string,
+  toStepId: string,
+  context: TransitionExecutionContext
+): Promise<TransitionExecutionResult> {
+  const instance = token.instance
+  const branch = token.kind === 'branch' ? token.branch : null
+  const branchInstanceId = tokenBranchInstanceId(token)
   try {
     let eventBus: Pick<EventBus, 'emitEvent'> | null = null
     try {
@@ -394,9 +428,10 @@ export async function executeTransition(
       const activityContext: activityExecutor.ActivityContext = {
         workflowInstance: instance,
         workflowContext: {
-          ...instance.context,
+          ...tokenReadContext(token),
           ...context.workflowContext,
         },
+        branchInstanceId,
         userId: context.userId,
       }
 
@@ -466,29 +501,27 @@ export async function executeTransition(
         .filter(a => a.async && a.jobId)
         .map(a => ({ activityId: a.activityId, jobId: a.jobId }))
 
-      // Store pending transition state
-      instance.pendingTransition = {
+      // Store pending transition state (per-token: branch or instance)
+      setTokenPendingTransition(token, {
         toStepId,
         activityResults,
         timestamp: new Date(),
-      }
+      })
 
-      // Store pending activities in context for tracking
-      instance.context = {
-        ...instance.context,
-        ...context.workflowContext,
-        ...activityOutputs,
-        _pendingAsyncActivities: pendingJobIds,
-      }
+      // Store activity outputs + pending-activity tracking in the token's own
+      // context scope (instance.context for root, branch namespace for a branch)
+      applyTokenContextWrites(token, context.workflowContext, activityOutputs)
+      mergeTokenContext(token, { _pendingAsyncActivities: pendingJobIds })
 
-      // Set status to waiting
-      instance.status = 'WAITING_FOR_ACTIVITIES'
-      instance.updatedAt = new Date()
+      // Set status to waiting (branch-scoped when running inside a branch)
+      setTokenWaitingForActivities(token)
+      touchToken(token, new Date())
       await em.flush()
 
       // Log event
       await logTransitionEvent(em, {
         workflowInstanceId: instance.id,
+        branchInstanceId,
         eventType: 'TRANSITION_PAUSED_FOR_ACTIVITIES',
         eventData: {
           fromStepId,
@@ -514,14 +547,11 @@ export async function executeTransition(
       }
     }
 
-    // Update workflow instance - set current step and update context atomically
-    instance.currentStepId = toStepId
-    instance.context = {
-      ...instance.context,
-      ...context.workflowContext,
-      ...activityOutputs, // Include activity outputs
-    }
-    instance.updatedAt = new Date()
+    // Advance the token cursor and update context atomically (instance for the
+    // root token; branch cursor + namespace for a branch token).
+    setTokenCurrentStepId(token, toStepId)
+    applyTokenContextWrites(token, context.workflowContext, activityOutputs)
+    touchToken(token, new Date())
 
     await em.flush()
 
@@ -531,11 +561,12 @@ export async function executeTransition(
       instance,
       toStepId,
       {
-        workflowContext: instance.context || {},
+        workflowContext: tokenReadContext(token),
         userId: context.userId,
         triggerData: context.triggerData,
       },
-      container
+      container,
+      branch
     )
 
     // Flush to database after step execution completes to make state visible to UI
@@ -958,6 +989,7 @@ async function logTransitionEvent(
   em: EntityManager,
   event: {
     workflowInstanceId: string
+    branchInstanceId?: string | null
     eventType: string
     eventData: any
     userId?: string

package/src/modules/workflows/lib/workflow-executor.ts

@@ -302,6 +302,43 @@ export async function executeWorkflow(
           )
         }
 
+        // Parallel execution: while the instance is FORKED, drive the branches.
+        if (currentInstance.status === 'FORKED') {
+          const { advanceBranches } = await import('./parallel-handler')
+          const branchResult = await advanceBranches(trx, container, currentInstance, definition, {
+            userId: context?.userId,
+          })
+
+          if (branchResult.outcome === 'joined') {
+            // Instance resumed at the post-join step; continue single-token.
+            continue
+          }
+
+          if (branchResult.outcome === 'failed') {
+            errors.push(branchResult.error || 'Parallel branch failed')
+            await completeWorkflow(trx, container, instanceId, 'FAILED', {
+              error: branchResult.error || 'Parallel branch failed',
+            })
+            return {
+              status: 'FAILED',
+              currentStep: currentInstance.currentStepId,
+              context: currentInstance.context,
+              events,
+              errors,
+              executionTime: Date.now() - startTime,
+            }
+          }
+
+          // 'waiting' — all branches paused for external resume (task/signal/timer/async).
+          return {
+            status: 'RUNNING',
+            currentStep: currentInstance.currentStepId,
+            context: currentInstance.context,
+            events,
+            executionTime: Date.now() - startTime,
+          }
+        }
+
         const currentStep = definition.definition.steps.find(
           (s: any) => s.stepId === currentInstance.currentStepId
         )
@@ -396,6 +433,14 @@ export async function executeWorkflow(
             console.error(`[WORKFLOW] Transition rejected (instance: ${currentInstance.id}, workflow: ${currentInstance.workflowId}, step: ${currentInstance.currentStepId} → ${selectedTransition.toStepId}): ${rejectionMessage}`)
             errors.push(rejectionMessage)
 
+            await completeWorkflow(trx, container, instanceId, 'FAILED', {
+              error: rejectionMessage,
+            })
+            events.push({
+              eventType: 'WORKFLOW_FAILED',
+              occurredAt: new Date(),
+            })
+
             return {
               status: 'FAILED',
               currentStep: currentInstance.currentStepId,
@@ -464,6 +509,15 @@ export async function executeWorkflow(
             },
           })
 
+          await completeWorkflow(trx, container, instanceId, 'FAILED', {
+            error: errorMessage,
+            details: error instanceof WorkflowExecutionError ? error.details : undefined,
+          })
+          events.push({
+            eventType: 'WORKFLOW_FAILED',
+            occurredAt: new Date(),
+          })
+
           return {
             status: 'FAILED',
             currentStep: currentInstance.currentStepId,
@@ -643,12 +697,27 @@ export async function completeWorkflow(
 export async function resumeWorkflowAfterActivities(
   em: EntityManager,
   container: AwilixContainer,
-  instanceId: string
+  instanceId: string,
+  branchInstanceId?: string | null
 ): Promise<void> {
   const transactionalEm = em as EntityManager & {
     transactional?: <TResult>(callback: (trx: EntityManager) => Promise<TResult>) => Promise<TResult>
   }
 
+  // Branch-scoped async resume: the instance is FORKED and the branch (not the
+  // instance) is WAITING_FOR_ACTIVITIES. Resume just that branch, then let the
+  // interleaved loop continue. Missing branchInstanceId → legacy instance path.
+  if (branchInstanceId) {
+    const { resumeBranchAfterActivities } = await import('./parallel-handler')
+    const branchResume = typeof transactionalEm.transactional === 'function'
+      ? await transactionalEm.transactional((trx) => resumeBranchAfterActivities(trx, container, instanceId, branchInstanceId))
+      : await resumeBranchAfterActivities(em, container, instanceId, branchInstanceId)
+    if (branchResume.continueExecution) {
+      await executeWorkflow(em, container, instanceId)
+    }
+    return
+  }
+
   const runResume = async (trx: EntityManager): Promise<{ continueExecution: boolean }> => {
     const instance = await trx.findOne(WorkflowInstance, {
       id: instanceId,