@open-mercato/core 0.7.1-develop.7193.1.910a5b0a1e → 0.7.1-develop.7195.1.b5efd1d51a

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

@@ -13,16 +13,47 @@ import { EntityManager } from '@mikro-orm/core'
 import {
   WorkflowInstance,
   WorkflowBranchInstance,
+  WorkflowDefinition,
   StepInstance,
   UserTask,
   WorkflowEvent,
   type StepInstanceStatus,
   type WorkflowStepType,
 } from '../data/entities'
-import { parseDuration } from './duration'
+import { emitWorkflowsEvent } from '../events'
+import { calculateDueDate, parseDuration } from './duration'
+import {
+  CONDITION_STEP_TYPE,
+  conditionReadContext,
+  evaluateConditionExpression,
+  readWaitForConditionConfig,
+} from './condition-handler'
+import { mapAgentResultToContext } from './agent-result-mapping'
+import {
+  WORKFLOW_AGENT_OUTCOME_CONTEXT_KEY,
+  buildAgentOutcomeContextEntry,
+  mapDispositionToAgentOutcome,
+} from './outcome-routing'
 import { logWorkflowEvent } from './event-logger'
+import { DRY_RUN_EVENT_TYPES, isDryRunInstance } from './dry-run'
 import { findDefinitionForInstance } from './find-definition'
+import { resolveDefinitionInterpolationMode, type WorkflowInterpolationMode } from './interpolation-pipeline'
+import {
+  collectResolvedEntityTypes,
+  flattenTaskText,
+  resolveTaskAssignment,
+  resolveTaskDeadlineDuration,
+  resolveTaskDecisions,
+  resolveTaskEntityBindings,
+  resolveTaskText,
+  type TaskInterpolate,
+} from './task-resolution'
+import { scheduleUserTaskSla } from './task-sla'
+import type { TaskQuickActionInput } from './task-quick-action'
 import { createLogger } from '@open-mercato/shared/lib/logger'
+import { findWorkflowDefinition } from './find-definition'
+import { validateAgainstPorts } from './port-contract'
+import type { WorkflowIoContract } from '../data/validators'
 
 const logger = createLogger('workflows')
 
@@ -34,13 +65,18 @@ export interface StepExecutionContext {
   workflowContext: Record<string, any>
   userId?: string
   triggerData?: any
+  // Populated by executeStep from the loaded definition; absent means lenient.
+  interpolationMode?: WorkflowInterpolationMode
+  // Populated by executeStep from the loaded definition so task notifications
+  // can name the workflow the way its author did.
+  workflowName?: string
 }
 
 export interface StepExecutionResult {
   status: 'COMPLETED' | 'WAITING' | 'FAILED'
   outputData?: any
   nextSteps?: string[] // For parallel forks (Phase 7)
-  waitReason?: 'USER_TASK' | 'SIGNAL' | 'TIMER' | 'FORK'
+  waitReason?: 'USER_TASK' | 'SIGNAL' | 'TIMER' | 'FORK' | 'CONDITION'
   error?: string
 }
 
@@ -143,6 +179,49 @@ export async function enterStep(
  * @param stepInstance - Step instance to exit
  * @param outputData - Optional output data from step execution
  */
+/**
+ * Announces the BUSINESS milestone a completing step carries, if it carries one.
+ *
+ * Resolved here rather than plumbed through every `exitStep` caller because a
+ * milestone must be announced from EVERY completion path — the inline advance,
+ * a signal resume, a task completion, a timer, a condition wake, a parallel
+ * branch — and a per-caller argument would silently miss whichever path was
+ * added next. Both reads are by primary key and the executor already loaded both
+ * rows, so in practice they resolve from the identity map rather than the
+ * database.
+ *
+ * Best-effort by construction: a step that completed HAS completed, and a failure
+ * to announce that fact must never undo it.
+ */
+async function emitStepMilestone(em: EntityManager, stepInstance: StepInstance): Promise<void> {
+  try {
+    const instance = await em.findOne(WorkflowInstance, { id: stepInstance.workflowInstanceId })
+    if (!instance) return
+    const definition = await em.findOne(WorkflowDefinition, { id: instance.definitionId })
+    const stepDef = definition?.definition?.steps?.find((step: any) => step.stepId === stepInstance.stepId)
+    const milestoneKey = typeof stepDef?.milestone === 'string' ? stepDef.milestone : null
+    if (!milestoneKey) return
+    await emitWorkflowsEvent(
+      'workflows.instance.milestone_reached',
+      {
+        instanceId: instance.id,
+        workflowId: instance.workflowId,
+        milestoneKey,
+        // For the trace only. A consumer matches on `milestoneKey`; matching on
+        // the step is exactly the coupling the milestone model removes.
+        stepId: stepInstance.stepId,
+        occurredAt: new Date().toISOString(),
+        data: stepInstance.outputData ?? null,
+        tenantId: instance.tenantId,
+        organizationId: instance.organizationId,
+      },
+      { persistent: true },
+    )
+  } catch {
+    // ignore — announcing a milestone can never fail a step that completed
+  }
+}
+
 export async function exitStep(
   em: EntityManager,
   stepInstance: StepInstance,
@@ -179,6 +258,55 @@ export async function exitStep(
     tenantId: stepInstance.tenantId,
     organizationId: stepInstance.organizationId,
   })
+
+  await emitStepMilestone(em, stepInstance)
+}
+
+/**
+ * Mark a step instance FAILED and log `STEP_FAILED`.
+ *
+ * The ONE place a step row becomes FAILED, so a failure the run went on to
+ * tolerate leaves the same durable trace a fatal one does. Tolerating a failure
+ * is a routing decision, not a reason to forget it happened: without the row and
+ * the event there is nothing for the run verdict to be computed from, and
+ * rerun-from-step refuses the step it exists for because its latest attempt
+ * still reads ACTIVE.
+ *
+ * Idempotent — a second call on an already-FAILED row is a no-op, so a handler
+ * that reported the failure itself never produces two `STEP_FAILED` rows.
+ */
+export async function markStepInstanceFailed(
+  em: EntityManager,
+  stepInstance: StepInstance,
+  failure: {
+    error: string
+    details?: unknown
+    branchInstanceId?: string | null
+    userId?: string
+  }
+): Promise<void> {
+  if (stepInstance.status === 'FAILED') return
+
+  const now = new Date()
+  stepInstance.status = 'FAILED'
+  stepInstance.errorData = {
+    error: failure.error,
+    details: failure.details ?? undefined,
+  }
+  stepInstance.exitedAt = now
+  stepInstance.updatedAt = now
+  await em.flush()
+
+  await logStepEvent(em, {
+    workflowInstanceId: stepInstance.workflowInstanceId,
+    stepInstanceId: stepInstance.id,
+    ...(failure.branchInstanceId ? { branchInstanceId: failure.branchInstanceId } : {}),
+    eventType: 'STEP_FAILED',
+    eventData: { stepId: stepInstance.stepId, error: failure.error },
+    ...(failure.userId ? { userId: failure.userId } : {}),
+    tenantId: stepInstance.tenantId,
+    organizationId: stepInstance.organizationId,
+  })
 }
 
 /**
@@ -236,7 +364,11 @@ export async function executeStep(
       instance,
       stepInstance,
       stepDef,
-      context,
+      {
+        ...context,
+        interpolationMode: resolveDefinitionInterpolationMode(definition.definition),
+        workflowName: definition.workflowName,
+      },
       container,
       branch
     )
@@ -244,6 +376,18 @@ export async function executeStep(
     // If step completed, exit it
     if (result.status === 'COMPLETED') {
       await exitStep(em, stepInstance, result.outputData)
+    } else if (result.status === 'FAILED') {
+      // A handler that REPORTS a failure (`handleAutomatedStep` returns
+      // `{status:'FAILED'}` for a failed sync activity) never reaches the catch
+      // below, so before this the row stayed ACTIVE for ever and no
+      // `STEP_FAILED` was logged — the failure existed only in a value the
+      // caller was free to tolerate. The row is now terminal on both paths.
+      await markStepInstanceFailed(em, stepInstance, {
+        error: result.error ?? 'Step execution failed',
+        details: result.outputData,
+        branchInstanceId: branch?.id ?? null,
+        userId: context.userId,
+      })
     }
 
     return result
@@ -260,22 +404,11 @@ export async function executeStep(
       })
 
       if (failedStepInstance) {
-        failedStepInstance.status = 'FAILED'
-        failedStepInstance.errorData = {
+        await markStepInstanceFailed(em, failedStepInstance, {
           error: errorMessage,
           details: error instanceof StepExecutionError ? error.details : undefined,
-        }
-        failedStepInstance.exitedAt = new Date()
-        failedStepInstance.updatedAt = new Date()
-        await em.flush()
-
-        await logStepEvent(em, {
-          workflowInstanceId: instance.id,
-          stepInstanceId: failedStepInstance.id,
-          eventType: 'STEP_FAILED',
-          eventData: { error: errorMessage },
-          tenantId: instance.tenantId,
-          organizationId: instance.organizationId,
+          branchInstanceId: branch?.id ?? null,
+          userId: context.userId,
         })
       }
     } catch (updateError) {
@@ -338,12 +471,19 @@ async function executeStepByType(
       }
       return await handleSubWorkflowStep(em, container, instance, stepInstance, stepDef, context)
 
+    case 'IF_ELSE':
+    case 'SWITCH':
+      return handleBranchingStep(stepType)
+
     case 'WAIT_FOR_SIGNAL':
       return await handleWaitForSignalStep(em, instance, stepInstance, stepDef, context, branch)
 
     case 'WAIT_FOR_TIMER':
       return await handleWaitForTimerStep(em, instance, stepInstance, stepDef, context, branch)
 
+    case 'WAIT_FOR_CONDITION':
+      return await handleWaitForConditionStep(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.
@@ -416,6 +556,25 @@ function handleEndStep(
   }
 }
 
+/**
+ * Handle IF_ELSE / SWITCH steps - pure transition sugar.
+ *
+ * Branching nodes carry NO runtime semantics of their own: they behave exactly
+ * like an AUTOMATED step with no activities and complete immediately. Every
+ * routing decision stays in `findValidTransitions`, which already evaluates the
+ * business_rules condition language and orders candidates by priority, so the
+ * unconditioned "otherwise" route wins only when no cased route matches.
+ */
+function handleBranchingStep(stepType: 'IF_ELSE' | 'SWITCH'): StepExecutionResult {
+  return {
+    status: 'COMPLETED',
+    outputData: {
+      stepType,
+      timestamp: new Date().toISOString(),
+    },
+  }
+}
+
 /**
  * Handle AUTOMATED step - execute activities
  *
@@ -446,7 +605,35 @@ async function handleAutomatedStep(
   }
 
   // Import activity executor
-  const { executeActivities } = await import('./activity-executor')
+  const { executeActivities, interpolateVariables } = await import('./activity-executor')
+
+  // Persist the resolved INVOKE_AGENT input so the run inspector shows what this
+  // step actually received. `inputData` was seeded at step entry from the
+  // workflow trigger data (null for a manually-started run), never the agent's
+  // real, interpolated `config.input` — the same value the executor computes via
+  // `interpolateActivityConfig` (a thin wrapper over `interpolateVariables`), so
+  // re-interpolating the input field here yields exactly what the agent runs on.
+  const agentActivity = activities.find(
+    (activity: any) => activity.activityType === 'INVOKE_AGENT' && activity?.config?.input !== undefined,
+  )
+  if (agentActivity) {
+    try {
+      const resolvedInput = interpolateVariables(
+        (agentActivity as any).config.input,
+        context.workflowContext,
+        instance,
+        { mode: context.interpolationMode },
+      )
+      if (resolvedInput !== undefined) {
+        stepInstance.inputData = resolvedInput
+        stepInstance.updatedAt = new Date()
+        await em.flush()
+      }
+    } catch {
+      // Display-only capture: an interpolation error is surfaced by the actual
+      // activity run below, so it must never abort the step here.
+    }
+  }
 
   try {
     // Execute activities with proper context
@@ -456,6 +643,7 @@ async function handleAutomatedStep(
       stepContext: { stepId: stepDef.stepId, stepName: stepDef.stepName },
       stepInstanceId: stepInstance.id,
       userId: context.userId,
+      interpolationMode: context.interpolationMode,
     })
 
     // Check if there are pending async activities
@@ -504,6 +692,103 @@ async function handleAutomatedStep(
       }
     }
 
+    // INVOKE_AGENT (agent_orchestrator) integration:
+    // A `__park` marker means the agent's proposal was routed to a human — park
+    // the instance on the signal exactly like handleWaitForSignalStep. The step
+    // declares `signalConfig.signalName`, so sendSignal (relaxed) resumes it when
+    // agent_orchestrator's dispose path fires `agent_orchestrator.proposal.ready`.
+    const parkResult = results.find((r) => r.output && (r.output as any).__park)
+    if (parkResult) {
+      const signalName = (parkResult.output as any).__park.signalName as string
+      const proposalId = (parkResult.output as any).proposalId
+      const now = new Date()
+      await logStepEvent(em, {
+        workflowInstanceId: instance.id,
+        stepInstanceId: stepInstance.id,
+        ...(branch ? { branchInstanceId: branch.id } : {}),
+        eventType: 'SIGNAL_AWAITING',
+        eventData: { signalName, proposalId, reason: 'INVOKE_AGENT' },
+        userId: context.userId,
+        tenantId: instance.tenantId,
+        organizationId: instance.organizationId,
+      })
+      if (branch) {
+        branch.status = 'PAUSED'
+        branch.updatedAt = now
+      } else {
+        instance.status = 'PAUSED'
+        instance.pausedAt = now
+        instance.updatedAt = now
+      }
+      await em.flush()
+      return {
+        status: 'WAITING',
+        waitReason: 'SIGNAL',
+        outputData: { signalName, proposalId, awaitingSince: now },
+      }
+    }
+
+    // Inline-resolved agent result (auto_approved / researcher / artifact):
+    // surface the disposition into context (top-level, matching the human-path
+    // signal merge) so the outgoing transition can branch (effector vs skip)
+    // uniformly.
+    const inlineAgent = results.find(
+      (r) => r.output && typeof (r.output as any).kind === 'string' && 'agentId' in (r.output as any),
+    )
+    if (inlineAgent && !branch) {
+      const out = inlineAgent.output as any
+      const agentActivity = activities.find(
+        (a: any) => a.activityType === 'INVOKE_AGENT' && a.activityId === inlineAgent.activityId,
+      )
+      const mappedPatch = mapAgentResultToContext(
+        {
+          kind: out.kind,
+          agentId: out.agentId,
+          proposalId: out.proposalId,
+          proposalPayload: out.proposalPayload,
+          data: out.data,
+          artifacts: out.artifacts,
+        },
+        agentActivity?.config?.outputMapping,
+      )
+      const contextPatch =
+        mappedPatch ??
+        (out.kind === 'auto_approved'
+          ? {
+              disposition: 'auto_approved',
+              agentProposalId: out.proposalId,
+              proposalPayload: out.proposalPayload,
+            }
+          : out.kind === 'artifact'
+            ? {
+                disposition: 'researcher',
+                [`${stepInstance.stepId}_agent`]: { artifacts: out.artifacts, summary: out.summary },
+              }
+            : null)
+      // Outcome routing (spec 7.2): record which of the five fixed disposition
+      // kinds this step resolved to under an ENGINE-OWNED context key. The
+      // executor routes on this marker alone — never on the author-visible
+      // `disposition` key — which is what makes branching on a disposition
+      // wiring rather than context string-matching.
+      const resolvedOutcome = mapDispositionToAgentOutcome(out.kind)
+      const outcomeMarker = resolvedOutcome
+        ? {
+            [WORKFLOW_AGENT_OUTCOME_CONTEXT_KEY]: buildAgentOutcomeContextEntry(
+              stepInstance.stepId,
+              resolvedOutcome,
+              out.proposalId,
+            ),
+          }
+        : null
+
+      const nextContext = { ...instance.context, ...(contextPatch ?? {}), ...(outcomeMarker ?? {}) }
+      if (contextPatch || outcomeMarker) {
+        instance.context = nextContext
+        instance.updatedAt = new Date()
+        await em.flush()
+      }
+    }
+
     // All activities completed successfully
     const activityOutputs = results.reduce((acc, r) => {
       if (r.output) {
@@ -529,6 +814,99 @@ async function handleAutomatedStep(
   }
 }
 
+/**
+ * Resolve a user task's deadline from its authored duration.
+ *
+ * An unparseable duration fails the step with an actionable message instead of
+ * quietly resolving to some default the author never asked for.
+ */
+function resolveUserTaskDeadline(stepId: string, slaDuration: string): Date {
+  try {
+    return calculateDueDate(slaDuration)
+  } catch (error) {
+    throw new StepExecutionError(
+      `Invalid user task deadline "${slaDuration}": ${error instanceof Error ? error.message : String(error)}`,
+      'INVALID_USER_TASK_DEADLINE',
+      { stepId, slaDuration }
+    )
+  }
+}
+
+/**
+ * Publish the declared `workflows.task.assigned` domain event for a freshly
+ * created task, alongside (never instead of) the internal `USER_TASK_CREATED`
+ * audit row. It carries both the individual assignee and the role queue so the
+ * notification subscriber can reach role-assigned tasks too.
+ *
+ * Delivery is at-least-once and consumers must be idempotent; a bus failure
+ * must never break workflow execution, so this is strictly best-effort.
+ */
+async function emitTaskAssignedEvent(
+  userTask: UserTask,
+  instance: WorkflowInstance,
+  context: StepExecutionContext,
+  quickAction?: TaskQuickActionInput
+): Promise<void> {
+  try {
+    await emitWorkflowsEvent(
+      'workflows.task.assigned',
+      {
+        // Everything the notification quick-action rule needs, and nothing more.
+        // ABSENT means "unknown", and the subscriber falls back to the deep
+        // link — a quick action must never be offered on a guess.
+        ...(quickAction ? { quickAction } : {}),
+        taskId: userTask.id,
+        taskName: userTask.taskName,
+        workflowInstanceId: instance.id,
+        workflowId: instance.workflowId,
+        workflowName: context.workflowName ?? instance.workflowId,
+        assignedUserId: userTask.assignedTo ?? null,
+        assignedToRoles: userTask.assignedToRoles ?? null,
+        dueDate: userTask.dueDate ? userTask.dueDate.toISOString() : null,
+        // Additive: the records the task is about. Modules that own those
+        // records subscribe and surface the task on their own turf — the
+        // customers module writes a `CustomerTodoLink` from this. Workflows
+        // never reaches into another module's tables to do it itself.
+        entityBindings: userTask.entityBindings ?? null,
+        tenantId: instance.tenantId,
+        organizationId: instance.organizationId ?? null,
+      },
+      { persistent: true }
+    )
+  } catch (error) {
+    logger.error('Failed to emit workflows.task.assigned', {
+      component: 'step-handler',
+      taskId: userTask.id,
+      err: error,
+    })
+  }
+
+  if (userTask.assigneeKind !== 'customer' || !userTask.assignedTo) return
+
+  try {
+    // Addressed to ONE portal principal (`recipientUserId` is what narrows the
+    // SSE audience) and carrying an id and nothing else. The receiver asks the
+    // authorized portal API what the task is; the bridge never carries the
+    // answer, so a mis-scoped connection learns nothing from it.
+    await emitWorkflowsEvent(
+      'workflows.task.portal_assigned',
+      {
+        taskId: userTask.id,
+        recipientUserId: userTask.assignedTo,
+        tenantId: instance.tenantId,
+        organizationId: instance.organizationId ?? null,
+      },
+      { persistent: false }
+    )
+  } catch (error) {
+    logger.error('Failed to emit workflows.task.portal_assigned', {
+      component: 'step-handler',
+      taskId: userTask.id,
+      err: error,
+    })
+  }
+}
+
 /**
  * Handle USER_TASK step - create user task and enter waiting state
  *
@@ -545,29 +923,124 @@ async function handleUserTaskStep(
 ): Promise<StepExecutionResult> {
   const userTaskConfig = stepDef.userTaskConfig || {}
 
-  // Handle assignedTo - if it's an array, treat it as roles
-  let assignedTo = userTaskConfig.assignedTo || null
-  let assignedToRoles = userTaskConfig.assignedToRoles || null
+  // Everything an author can write on a task — its title, its instructions, its
+  // decision labels, its dynamic assignee and its entity bindings — is resolved
+  // HERE, once, against the context the run has at creation time. Resolving
+  // later would let a definition edit retro-change what a running task says.
+  // Lenient on purpose: an unresolved dynamic assignee is what the fallback role
+  // queue exists for, not a reason to fail the step.
+  //
+  // Imported dynamically like every other activity-executor use in this file, so
+  // the module graph stays acyclic.
+  const { interpolateVariables } = await import('./activity-executor')
+  const interpolate: TaskInterpolate = (value) =>
+    interpolateVariables(value, context.workflowContext, instance)
+
+  const assignment = resolveTaskAssignment(userTaskConfig, interpolate)
+  if (assignment.fellBackToRoles) {
+    logger.warn('Dynamic task assignee resolved to nothing; falling back to the role queue', {
+      component: 'step-handler',
+      stepId: stepDef.stepId,
+      workflowInstanceId: instance.id,
+      assignedToRoles: assignment.assignedToRoles,
+    })
+  }
+  if (assignment.fellBackFromCustomer) {
+    // The author addressed this to a portal principal and no id resolved, so it
+    // landed in the backoffice namespace instead. The work is still reachable,
+    // but by a different audience than intended — that is worth saying out loud.
+    logger.warn('Portal task assignee resolved to nothing; task created for the backoffice instead', {
+      component: 'step-handler',
+      stepId: stepDef.stepId,
+      workflowInstanceId: instance.id,
+    })
+  }
 
-  if (Array.isArray(assignedTo)) {
-    assignedToRoles = assignedTo
-    assignedTo = null
+  const { bindings, unresolved } = resolveTaskEntityBindings(userTaskConfig.entityBindings, interpolate)
+  if (unresolved.length) {
+    logger.warn('Task entity bindings skipped because their ids did not resolve', {
+      component: 'step-handler',
+      stepId: stepDef.stepId,
+      workflowInstanceId: instance.id,
+      unresolved,
+    })
   }
 
+  const taskName = String(interpolate(stepDef.stepName) ?? stepDef.stepName)
+  const instructions = resolveTaskText(userTaskConfig.instructions, interpolate)
+  const decisions = resolveTaskDecisions(userTaskConfig.decisions, interpolate)
+  const deadlineDuration = resolveTaskDeadlineDuration(userTaskConfig)
+
   // Create user task
   const now = new Date()
+
+  // Dry run (spec section 8.2): a simulation raises NO real task. The row is
+  // what everything else hangs off — the `workflows.task.assigned` event and
+  // therefore the notification subscriber, the SLA reminder/breach queue jobs,
+  // and every Work Inbox and task-list query — so suppressing the row is what
+  // suppresses all of them, rather than a filter at each read site that a new
+  // reader could forget. Everything above still runs, so the report says
+  // exactly who the task WOULD have gone to. The step still WAITS: the author
+  // simulates the decision through step-through or the advance action.
+  if (isDryRunInstance(instance)) {
+    await logStepEvent(em, {
+      workflowInstanceId: instance.id,
+      stepInstanceId: stepInstance.id,
+      ...(branch ? { branchInstanceId: branch.id } : {}),
+      eventType: DRY_RUN_EVENT_TYPES.userTaskSimulated,
+      eventData: {
+        taskName,
+        assignedTo: assignment.assignedTo,
+        assignedToRoles: assignment.assignedToRoles,
+        assigneeKind: assignment.assigneeKind,
+        ...(bindings.length ? { entityBindings: bindings } : {}),
+        ...(decisions.length ? { decisions } : {}),
+        ...(deadlineDuration ? { deadlineDuration } : {}),
+      },
+      tenantId: instance.tenantId,
+      organizationId: instance.organizationId,
+    })
+
+    if (branch) {
+      branch.status = 'PAUSED'
+      branch.updatedAt = now
+    } else {
+      instance.status = 'PAUSED'
+      instance.updatedAt = now
+    }
+    await em.flush()
+
+    return {
+      status: 'WAITING',
+      waitReason: 'USER_TASK',
+      outputData: { simulated: true, wouldRaiseTask: taskName },
+    }
+  }
+
   const userTask = em.create(UserTask, {
     workflowInstanceId: instance.id,
     stepInstanceId: stepInstance.id,
     branchInstanceId: branch ? branch.id : null,
-    taskName: stepDef.stepName,
-    description: stepDef.description || null,
+    taskName,
+    description: flattenTaskText(instructions) ?? stepDef.description ?? null,
     status: 'PENDING',
     formSchema: userTaskConfig.formSchema || null,
     formData: null,
-    assignedTo: assignedTo,
-    assignedToRoles: assignedToRoles,
-    dueDate: userTaskConfig.slaDuration ? calculateDueDate(userTaskConfig.slaDuration) : null,
+    assignedTo: assignment.assignedTo,
+    // Decided by `resolveTaskAssignment` from the authored `assigneeKind`, and
+    // `'customer'` only when an individual assignee actually resolved. Written
+    // explicitly rather than left to the column default so the discriminator is
+    // a decision at every creation site, not an accident.
+    assigneeKind: assignment.assigneeKind,
+    assignedToRoles: assignment.assignedToRoles,
+    entityBindings: bindings.length ? bindings : null,
+    // Denormalized from the SAME resolved bindings, so the two can never drift.
+    // Null for a task about nothing, which is what the vacuous-pass rule reads.
+    entityTypes: bindings.length ? collectResolvedEntityTypes(bindings) : null,
+    priority: userTaskConfig.priority ?? null,
+    dueDate: deadlineDuration
+      ? resolveUserTaskDeadline(stepDef.stepId, deadlineDuration)
+      : null,
     tenantId: instance.tenantId,
     organizationId: instance.organizationId,
     createdAt: now,
@@ -587,11 +1060,37 @@ async function handleUserTaskStep(
       taskName: userTask.taskName,
       assignedTo: userTask.assignedTo,
       assignedToRoles: userTask.assignedToRoles,
+      ...(bindings.length ? { entityBindings: bindings } : {}),
+      ...(userTask.priority ? { priority: userTask.priority } : {}),
+      ...(decisions.length ? { decisions } : {}),
+      ...(assignment.fellBackToRoles ? { assignmentFallback: 'roles' } : {}),
     },
     tenantId: instance.tenantId,
     organizationId: instance.organizationId,
   })
 
+  await emitTaskAssignedEvent(userTask, instance, context, {
+    decisions: decisions.map((decision) => ({ id: decision.id })),
+    formSchema: userTask.formSchema ?? null,
+    editablePrefilled: userTaskConfig.editablePrefilled ?? null,
+  })
+
+  // Reminders and the deadline breach are scheduled HERE, once, with the
+  // deadline already absolute on each job payload — see `lib/task-sla.ts`. A
+  // task with no deadline schedules nothing at all.
+  await scheduleUserTaskSla({
+    workflowInstanceId: instance.id,
+    stepInstanceId: stepInstance.id,
+    branchInstanceId: branch ? branch.id : null,
+    userTaskId: userTask.id,
+    dueDate: userTask.dueDate ?? null,
+    reminders: userTaskConfig.reminders ?? null,
+    tenantId: instance.tenantId,
+    organizationId: instance.organizationId,
+    userId: context.userId,
+    now,
+  })
+
   // Pause execution - waits for user task completion. For a branch, only the
   // branch pauses; sibling branches keep running.
   if (branch) {
@@ -636,12 +1135,43 @@ async function handleSubWorkflowStep(
   }
 
   // Map input data from parent context to child context
-  const childContext = mapInputData(instance.context, inputMapping || {})
+  let childContext = mapInputData(instance.context, inputMapping || {})
 
   // Import workflow executor functions
   const { startWorkflow, executeWorkflow } = await import('./workflow-executor')
 
   try {
+    // Resolve the child definition to read its declared port contract (if any).
+    // Validation is opt-in by contract presence: only children that declare
+    // `definition.io` ports are checked, so legacy untyped sub-workflows behave
+    // exactly as before.
+    const childDefinition = await findWorkflowDefinition(em, {
+      workflowId: subWorkflowId,
+      version,
+      tenantId: instance.tenantId,
+      organizationId: instance.organizationId,
+    })
+    const ioContract = (childDefinition?.definition as { io?: WorkflowIoContract } | undefined)?.io
+
+    // Validate/coerce mapped inputs against the child's declared input ports.
+    if (ioContract?.inputs?.length) {
+      const { coerced, errors } = validateAgainstPorts(childContext, ioContract.inputs)
+      if (errors.length > 0) {
+        const message = `Sub-workflow input validation failed: ${errors.map((e) => e.message).join('; ')}`
+        await logStepEvent(em, {
+          workflowInstanceId: instance.id,
+          stepInstanceId: stepInstance.id,
+          eventType: 'SUB_WORKFLOW_FAILED',
+          eventData: { subWorkflowId, reason: 'INPUT_VALIDATION', error: message },
+          userId: context.userId,
+          tenantId: instance.tenantId,
+          organizationId: instance.organizationId,
+        })
+        return { status: 'FAILED', error: message }
+      }
+      childContext = coerced
+    }
+
     // Start child workflow with parent metadata
     const childInstance = await startWorkflow(em, {
       workflowId: subWorkflowId,
@@ -684,8 +1214,23 @@ async function handleSubWorkflowStep(
 
     // Handle child workflow result
     if (result.status === 'COMPLETED') {
-      // Map output data from child context to parent context
-      const outputData = mapOutputData(result.context, outputMapping || {})
+      // Map output data from child context to parent context (+ io-port
+      // validation). Shared with the async resume path so both apply identical
+      // mapping/validation rules.
+      const mapped = mapSubWorkflowOutput(result.context, outputMapping || {}, ioContract)
+      if (mapped.error) {
+        await logStepEvent(em, {
+          workflowInstanceId: instance.id,
+          stepInstanceId: stepInstance.id,
+          eventType: 'SUB_WORKFLOW_FAILED',
+          eventData: { childInstanceId: childInstance.id, reason: 'OUTPUT_VALIDATION', error: mapped.error },
+          userId: context.userId,
+          tenantId: instance.tenantId,
+          organizationId: instance.organizationId,
+        })
+        return { status: 'FAILED', error: mapped.error }
+      }
+      const outputData = mapped.outputData
 
       await logStepEvent(em, {
         workflowInstanceId: instance.id,
@@ -723,10 +1268,34 @@ async function handleSubWorkflowStep(
         error: `Sub-workflow failed: ${result.errors?.join(', ')}`,
       }
     } else {
-      // WAITING, PAUSED, etc. - For synchronous execution, treat as error
+      // The child parked at its first async/agent step (RUNNING / PAUSED /
+      // WAITING_FOR_ACTIVITIES). Make the SUB_WORKFLOW step suspendable: park the
+      // parent on SUB_WORKFLOW_SIGNAL_NAME. The child's terminal completeWorkflow
+      // enqueues a resume job that resumes this parent (mirrors the INVOKE_AGENT
+      // __park branch above).
+      const { SUB_WORKFLOW_SIGNAL_NAME } = await import('./activity-executor')
+      const now = new Date()
+      await logStepEvent(em, {
+        workflowInstanceId: instance.id,
+        stepInstanceId: stepInstance.id,
+        eventType: 'SIGNAL_AWAITING',
+        eventData: {
+          signalName: SUB_WORKFLOW_SIGNAL_NAME,
+          childInstanceId: childInstance.id,
+          reason: 'SUB_WORKFLOW',
+        },
+        userId: context.userId,
+        tenantId: instance.tenantId,
+        organizationId: instance.organizationId,
+      })
+      instance.status = 'PAUSED'
+      instance.pausedAt = now
+      instance.updatedAt = now
+      await em.flush()
       return {
-        status: 'FAILED',
-        error: `Sub-workflow ended in unexpected state: ${result.status}`,
+        status: 'WAITING',
+        waitReason: 'SIGNAL',
+        outputData: { childInstanceId: childInstance.id },
       }
     }
   } catch (error: any) {
@@ -925,6 +1494,120 @@ async function handleWaitForTimerStep(
   }
 }
 
+/**
+ * Handle WAIT_FOR_CONDITION step - pause until a context predicate holds.
+ *
+ * Evaluates the step's ConditionExpression against the token read context. A
+ * predicate that already holds completes the step inline with no queue job at
+ * all. Otherwise the token parks and a delayed `kind: 'condition'` poll job is
+ * enqueued carrying an ABSOLUTE `deadlineAt`, so neither a slow queue nor a
+ * re-enqueue can extend the configured timeout. The event-driven wake
+ * (`conditionHandler.wakeConditionWaiters`) is the fast path on top of it.
+ */
+async function handleWaitForConditionStep(
+  em: EntityManager,
+  instance: WorkflowInstance,
+  stepInstance: StepInstance,
+  stepDef: any,
+  context: StepExecutionContext,
+  branch?: WorkflowBranchInstance | null
+): Promise<StepExecutionResult> {
+  const config = readWaitForConditionConfig(stepDef)
+
+  const data = {
+    ...conditionReadContext(instance, branch ?? null),
+    ...(context.workflowContext || {}),
+  }
+
+  const met = await evaluateConditionExpression({
+    condition: config.condition,
+    data,
+    instanceId: instance.id,
+    userId: context.userId,
+  })
+
+  const now = new Date()
+
+  if (met) {
+    await logWorkflowEvent(em, {
+      workflowInstanceId: instance.id,
+      stepInstanceId: stepInstance.id,
+      ...(branch ? { branchInstanceId: branch.id } : {}),
+      eventType: 'CONDITION_MET',
+      eventData: { stepId: stepDef.stepId, attempts: 1, waitedMs: 0, wokenBy: 'immediate' },
+      userId: context.userId,
+      tenantId: instance.tenantId,
+      organizationId: instance.organizationId,
+    })
+
+    return {
+      status: 'COMPLETED',
+      outputData: {
+        stepType: CONDITION_STEP_TYPE,
+        conditionMet: true,
+        attempts: 1,
+        waitedMs: 0,
+        wokenBy: 'immediate',
+      },
+    }
+  }
+
+  const deadlineAt = new Date(now.getTime() + config.timeoutMs)
+
+  const { enqueueConditionCheckJob } = await import('./activity-executor')
+  const jobId = await enqueueConditionCheckJob({
+    workflowInstanceId: instance.id,
+    stepInstanceId: stepInstance.id,
+    branchInstanceId: branch ? branch.id : undefined,
+    tenantId: instance.tenantId,
+    organizationId: instance.organizationId,
+    userId: context.userId,
+    deadlineAt: deadlineAt.toISOString(),
+    attempt: 1,
+    delayMs: Math.min(config.pollIntervalMs, config.timeoutMs),
+  })
+
+  await logWorkflowEvent(em, {
+    workflowInstanceId: instance.id,
+    stepInstanceId: stepInstance.id,
+    ...(branch ? { branchInstanceId: branch.id } : {}),
+    eventType: 'CONDITION_AWAITING',
+    eventData: {
+      stepId: stepDef.stepId,
+      condition: config.condition,
+      deadlineAt: deadlineAt.toISOString(),
+      pollIntervalMs: config.pollIntervalMs,
+      onTimeout: config.onTimeout,
+      jobId,
+    },
+    userId: context.userId,
+    tenantId: instance.tenantId,
+    organizationId: instance.organizationId,
+  })
+
+  if (branch) {
+    branch.status = 'PAUSED'
+    branch.updatedAt = now
+  } else {
+    instance.status = 'PAUSED'
+    instance.pausedAt = now
+    instance.updatedAt = now
+  }
+  await em.flush()
+
+  return {
+    status: 'WAITING',
+    waitReason: 'CONDITION',
+    outputData: {
+      stepType: CONDITION_STEP_TYPE,
+      deadlineAt: deadlineAt.toISOString(),
+      pollIntervalMs: config.pollIntervalMs,
+      onTimeout: config.onTimeout,
+      jobId,
+    },
+  }
+}
+
 // ============================================================================
 // Helper Functions
 // ============================================================================
@@ -956,39 +1639,6 @@ async function logStepEvent(
   return workflowEvent
 }
 
-/**
- * Calculate due date from ISO 8601 duration string
- *
- * @param duration - ISO 8601 duration (e.g., "P1D" for 1 day)
- * @returns Due date
- */
-function calculateDueDate(duration: string): Date {
-  // Simple implementation for MVP
-  // Supports: P1D (1 day), P1H (1 hour), P1W (1 week)
-  const now = new Date()
-
-  const daysMatch = duration.match(/P(\d+)D/)
-  if (daysMatch) {
-    const days = parseInt(daysMatch[1], 10)
-    return new Date(now.getTime() + days * 24 * 60 * 60 * 1000)
-  }
-
-  const hoursMatch = duration.match(/PT(\d+)H/)
-  if (hoursMatch) {
-    const hours = parseInt(hoursMatch[1], 10)
-    return new Date(now.getTime() + hours * 60 * 60 * 1000)
-  }
-
-  const weeksMatch = duration.match(/P(\d+)W/)
-  if (weeksMatch) {
-    const weeks = parseInt(weeksMatch[1], 10)
-    return new Date(now.getTime() + weeks * 7 * 24 * 60 * 60 * 1000)
-  }
-
-  // Default: 1 day
-  return new Date(now.getTime() + 24 * 60 * 60 * 1000)
-}
-
 /**
  * Get nested value from object using dot notation
  *
@@ -1064,3 +1714,29 @@ function mapOutputData(
   // If no mapping provided, pass entire child context
   return Object.keys(result).length > 0 ? result : childContext
 }
+
+/**
+ * Map a completed sub-workflow's child context to parent output and validate it
+ * against the child's declared output ports. Shared by the synchronous
+ * (inline) completion branch in `handleSubWorkflowStep` and the async parent
+ * resume path so both apply identical mapping/validation rules. Returns the
+ * mapped `outputData` on success or an `error` message on port-validation
+ * failure (never throws).
+ */
+export function mapSubWorkflowOutput(
+  childContext: Record<string, any>,
+  outputMapping: Record<string, string>,
+  ioContract?: WorkflowIoContract
+): { outputData: Record<string, any>; error?: undefined } | { outputData?: undefined; error: string } {
+  let outputData = mapOutputData(childContext, outputMapping || {})
+
+  if (ioContract?.outputs?.length) {
+    const { coerced, errors } = validateAgainstPorts(outputData, ioContract.outputs)
+    if (errors.length > 0) {
+      return { error: `Sub-workflow output validation failed: ${errors.map((e) => e.message).join('; ')}` }
+    }
+    outputData = coerced
+  }
+
+  return { outputData }
+}