@open-mercato/core 0.6.3-develop.3876.1.d40fe4ec2d → 0.6.3-develop.3881.1.0b590ac4eb

package/src/modules/workflows/data/validators.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod'
+import { parseDuration } from '../lib/duration'
 
 /**
  * Workflows Module - Zod Validators
@@ -8,6 +9,40 @@ import { z } from 'zod'
 
 const uuid = z.uuid()
 
+// Variable interpolation tokens (e.g., {{context.timeout}}) are resolved at
+// run time, so we must skip strict syntax checks on them at save time.
+const containsTemplate = (value: string) => value.includes('{{')
+
+export function isValidDurationString(value: unknown): boolean {
+  if (typeof value !== 'string' || value.length === 0) return false
+  if (containsTemplate(value)) return true
+  try {
+    const ms = parseDuration(value)
+    return Number.isFinite(ms) && ms > 0
+  } catch {
+    return false
+  }
+}
+
+export function isValidIsoDateString(value: unknown): boolean {
+  if (typeof value !== 'string' || value.length === 0) return false
+  if (containsTemplate(value)) return true
+  const d = new Date(value)
+  return !Number.isNaN(d.getTime())
+}
+
+export function isFutureIsoDateString(value: unknown): boolean {
+  if (typeof value !== 'string' || value.length === 0) return false
+  if (containsTemplate(value)) return true
+  const d = new Date(value)
+  if (Number.isNaN(d.getTime())) return false
+  return d.getTime() > Date.now()
+}
+
+const DURATION_ERROR = 'Invalid duration. Use ISO 8601 (e.g., PT5M, PT1H, P1D) or simple format (5m, 1h, 3d)'
+const UNTIL_ERROR = 'Invalid "until". Provide an ISO 8601 datetime string'
+const UNTIL_PAST_ERROR = '"until" must be a future datetime'
+
 // ============================================================================
 // Enum Schemas - Workflow Types and Statuses
 // ============================================================================
@@ -169,6 +204,49 @@ export const activityDefinitionSchema = z.object({
     activityId: z.string().min(1), // ID of compensation activity
     automatic: z.boolean().default(true).optional() // Auto-trigger on failure
   }).optional(), // Compensation configuration (Phase 8.2)
+}).superRefine((activity, ctx) => {
+  if (activity.activityType !== 'WAIT') return
+  const config = activity.config || {}
+  const hasDuration = config.duration != null && config.duration !== ''
+  const hasUntil = config.until != null && config.until !== ''
+  if (!hasDuration && !hasUntil) {
+    ctx.addIssue({
+      code: 'custom',
+      path: ['config'],
+      message: 'WAIT activity requires "duration" or "until"',
+    })
+    return
+  }
+  if (hasDuration && hasUntil) {
+    ctx.addIssue({
+      code: 'custom',
+      path: ['config'],
+      message: 'WAIT activity accepts "duration" OR "until", not both',
+    })
+    return
+  }
+  if (hasDuration && !isValidDurationString(config.duration)) {
+    ctx.addIssue({
+      code: 'custom',
+      path: ['config', 'duration'],
+      message: DURATION_ERROR,
+    })
+  }
+  if (hasUntil) {
+    if (!isValidIsoDateString(config.until)) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['config', 'until'],
+        message: UNTIL_ERROR,
+      })
+    } else if (!isFutureIsoDateString(config.until)) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['config', 'until'],
+        message: UNTIL_PAST_ERROR,
+      })
+    }
+  }
 })
 
 // Localized validation message schema (for START step pre-conditions)
@@ -201,6 +279,49 @@ export const workflowStepSchema = z.object({
   retryPolicy: retryPolicySchema.optional(),
   // Pre-conditions for START step (business rules to validate before workflow can be started)
   preConditions: z.array(startPreConditionSchema).optional(),
+}).superRefine((step, ctx) => {
+  if (step.stepType !== 'WAIT_FOR_TIMER') return
+  const config = step.config || {}
+  const hasDuration = config.duration != null && config.duration !== ''
+  const hasUntil = config.until != null && config.until !== ''
+  if (!hasDuration && !hasUntil) {
+    ctx.addIssue({
+      code: 'custom',
+      path: ['config'],
+      message: 'WAIT_FOR_TIMER step requires "duration" or "until"',
+    })
+    return
+  }
+  if (hasDuration && hasUntil) {
+    ctx.addIssue({
+      code: 'custom',
+      path: ['config'],
+      message: 'WAIT_FOR_TIMER step accepts "duration" OR "until", not both',
+    })
+    return
+  }
+  if (hasDuration && !isValidDurationString(config.duration)) {
+    ctx.addIssue({
+      code: 'custom',
+      path: ['config', 'duration'],
+      message: DURATION_ERROR,
+    })
+  }
+  if (hasUntil) {
+    if (!isValidIsoDateString(config.until)) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['config', 'until'],
+        message: UNTIL_ERROR,
+      })
+    } else if (!isFutureIsoDateString(config.until)) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['config', 'until'],
+        message: UNTIL_PAST_ERROR,
+      })
+    }
+  }
 })
 
 // Transition condition (reference to business rule)

package/src/modules/workflows/di.ts

@@ -11,6 +11,8 @@ import * as stepHandler from './lib/step-handler'
 import * as transitionHandler from './lib/transition-handler'
 import * as activityExecutor from './lib/activity-executor'
 import * as eventLogger from './lib/event-logger'
+import * as signalHandler from './lib/signal-handler'
+import * as timerHandler from './lib/timer-handler'
 
 export function register(container: AwilixContainer): void {
   container.register({
@@ -19,5 +21,7 @@ export function register(container: AwilixContainer): void {
     transitionHandler: asFunction(() => transitionHandler).scoped(),
     activityExecutor: asFunction(() => activityExecutor).scoped(),
     eventLogger: asFunction(() => eventLogger).scoped(),
+    signalHandler: asFunction(() => signalHandler).scoped(),
+    timerHandler: asFunction(() => timerHandler).scoped(),
   })
 }

package/src/modules/workflows/i18n/de.json

@@ -93,7 +93,13 @@
   "workflows.activities.types.EXECUTE_FUNCTION": "Funktion ausführen",
   "workflows.activities.types.SEND_EMAIL": "E-Mail senden",
   "workflows.activities.types.UPDATE_ENTITY": "Entität aktualisieren",
-  "workflows.activities.types.WAIT": "Warten",
+  "workflows.activities.types.WAIT": "Warten / Verzögerung",
+  "workflows.activities.waitDuration": "Dauer",
+  "workflows.activities.waitDurationDescription": "ISO 8601 Dauer (z.B. PT5M für 5 Minuten, PT1H für 1 Stunde, P1D für 1 Tag) oder einfaches Format (5m, 1h, 3d)",
+  "workflows.activities.waitDurationPlaceholder": "PT5M",
+  "workflows.activities.waitOr": "oder",
+  "workflows.activities.waitUntil": "Warten bis",
+  "workflows.activities.waitUntilDescription": "Bestimmtes Datum und Uhrzeit, bis zu dem gewartet werden soll",
   "workflows.backToList": "Zurück zu Workflows",
   "workflows.backend.definitions.visual_editor.title": "Visueller Workflow-Editor",
   "workflows.checkoutDemo.cart.empty.hint": "Füge Produkte aus dem Dropdown oben hinzu",
@@ -910,6 +916,7 @@
   "workflows.nodeTypes.subWorkflow": "SUB-WORKFLOW",
   "workflows.nodeTypes.userTask": "BENUTZERAUFGABE",
   "workflows.nodeTypes.waitForSignal": "AUF SIGNAL WARTEN",
+  "workflows.nodeTypes.waitForTimer": "AUF TIMER WARTEN",
   "workflows.notifications.task.assigned.body": "Ihnen wurde die Aufgabe \"{taskName}\" im Workflow \"{workflowName}\" zugewiesen{dueDate, select, other { (fällig: {dueDate})}}",
   "workflows.notifications.task.assigned.title": "Aufgabe zugewiesen",
   "workflows.orderApproval.approveButton": "Genehmigen",
@@ -1135,6 +1142,7 @@
   "workflows.triggers.status.disabled": "Deaktiviert",
   "workflows.triggers.title": "Ereignis-Trigger",
   "workflows.validation.descriptionMaxLength": "Beschreibung darf maximal 5000 Zeichen lang sein",
+  "workflows.validation.invalidDuration": "Ungültige Dauer. Verwenden Sie ISO 8601 (z. B. PT5M, PT1H, P1D) oder ein einfaches Format (5m, 1h, 3d).",
   "workflows.validation.invalidFormat": "Ungültiges Format",
   "workflows.validation.invalidTransition": "Ungültige Übergangskonfiguration",
   "workflows.validation.invalidWorkflowId": "Workflow-ID darf nur Kleinbuchstaben, Zahlen, Bindestriche und Unterstriche enthalten",
@@ -1144,6 +1152,7 @@
   "workflows.validation.noOrphanSteps": "Alle Schritte müssen verbunden sein",
   "workflows.validation.required": "Dieses Feld ist erforderlich",
   "workflows.validation.uniqueId": "ID muss eindeutig sein",
+  "workflows.validation.untilMustBeFuture": "„Warten bis“ muss ein Datum und eine Uhrzeit in der Zukunft sein.",
   "workflows.validation.workflowIdFormat": "Workflow-ID darf nur Kleinbuchstaben, Zahlen, Bindestriche und Unterstriche enthalten",
   "workflows.validation.workflowIdMaxLength": "Workflow-ID darf maximal 50 Zeichen lang sein",
   "workflows.validation.workflowIdRequired": "Workflow-ID ist erforderlich",

package/src/modules/workflows/i18n/en.json

@@ -93,7 +93,13 @@
   "workflows.activities.types.EXECUTE_FUNCTION": "Execute Function",
   "workflows.activities.types.SEND_EMAIL": "Send Email",
   "workflows.activities.types.UPDATE_ENTITY": "Update Entity",
-  "workflows.activities.types.WAIT": "Wait",
+  "workflows.activities.types.WAIT": "Wait / Delay",
+  "workflows.activities.waitDuration": "Duration",
+  "workflows.activities.waitDurationDescription": "ISO 8601 duration (e.g., PT5M for 5 minutes, PT1H for 1 hour, P1D for 1 day) or simple format (5m, 1h, 3d)",
+  "workflows.activities.waitDurationPlaceholder": "PT5M",
+  "workflows.activities.waitOr": "or",
+  "workflows.activities.waitUntil": "Wait Until",
+  "workflows.activities.waitUntilDescription": "Specific date and time to wait until",
   "workflows.backToList": "Back to workflows",
   "workflows.backend.definitions.visual_editor.title": "Visual Workflow Editor",
   "workflows.checkoutDemo.cart.empty.hint": "Add products from the dropdown above",
@@ -910,6 +916,7 @@
   "workflows.nodeTypes.subWorkflow": "SUB-WORKFLOW",
   "workflows.nodeTypes.userTask": "USER TASK",
   "workflows.nodeTypes.waitForSignal": "WAIT FOR SIGNAL",
+  "workflows.nodeTypes.waitForTimer": "WAIT FOR TIMER",
   "workflows.notifications.task.assigned.body": "You have been assigned to task \"{taskName}\" in workflow \"{workflowName}\"{dueDate, select, other { (due: {dueDate})}}",
   "workflows.notifications.task.assigned.title": "Task Assigned",
   "workflows.orderApproval.approveButton": "Approve",
@@ -1135,6 +1142,7 @@
   "workflows.triggers.status.disabled": "Disabled",
   "workflows.triggers.title": "Event Triggers",
   "workflows.validation.descriptionMaxLength": "Description must be 5000 characters or less",
+  "workflows.validation.invalidDuration": "Invalid duration. Use ISO 8601 (e.g., PT5M, PT1H, P1D) or simple format (5m, 1h, 3d).",
   "workflows.validation.invalidFormat": "Invalid format",
   "workflows.validation.invalidTransition": "Invalid transition configuration",
   "workflows.validation.invalidWorkflowId": "Workflow ID can only contain lowercase letters, numbers, hyphens, and underscores",
@@ -1144,6 +1152,7 @@
   "workflows.validation.noOrphanSteps": "All steps must be connected",
   "workflows.validation.required": "This field is required",
   "workflows.validation.uniqueId": "ID must be unique",
+  "workflows.validation.untilMustBeFuture": "Wait Until must be a date and time in the future.",
   "workflows.validation.workflowIdFormat": "Workflow ID must contain only lowercase letters, numbers, hyphens, and underscores",
   "workflows.validation.workflowIdMaxLength": "Workflow ID must be 50 characters or less",
   "workflows.validation.workflowIdRequired": "Workflow ID is required",

package/src/modules/workflows/i18n/es.json

@@ -93,7 +93,13 @@
   "workflows.activities.types.EXECUTE_FUNCTION": "Ejecutar funcion",
   "workflows.activities.types.SEND_EMAIL": "Enviar correo electronico",
   "workflows.activities.types.UPDATE_ENTITY": "Actualizar entidad",
-  "workflows.activities.types.WAIT": "Esperar",
+  "workflows.activities.types.WAIT": "Esperar / Retraso",
+  "workflows.activities.waitDuration": "Duración",
+  "workflows.activities.waitDurationDescription": "Duración ISO 8601 (ej. PT5M para 5 minutos, PT1H para 1 hora, P1D para 1 día) o formato simple (5m, 1h, 3d)",
+  "workflows.activities.waitDurationPlaceholder": "PT5M",
+  "workflows.activities.waitOr": "o",
+  "workflows.activities.waitUntil": "Esperar hasta",
+  "workflows.activities.waitUntilDescription": "Fecha y hora específica hasta la cual esperar",
   "workflows.backToList": "Volver a flujos de trabajo",
   "workflows.backend.definitions.visual_editor.title": "Editor visual de flujos de trabajo",
   "workflows.checkoutDemo.cart.empty.hint": "Añade productos desde el menú desplegable de arriba",
@@ -910,6 +916,7 @@
   "workflows.nodeTypes.subWorkflow": "SUBFLUJO DE TRABAJO",
   "workflows.nodeTypes.userTask": "TAREA DE USUARIO",
   "workflows.nodeTypes.waitForSignal": "ESPERAR SENAL",
+  "workflows.nodeTypes.waitForTimer": "ESPERAR TEMPORIZADOR",
   "workflows.notifications.task.assigned.body": "Se te ha asignado la tarea \"{taskName}\" en el flujo de trabajo \"{workflowName}\"{dueDate, select, other { (vence: {dueDate})}}",
   "workflows.notifications.task.assigned.title": "Tarea asignada",
   "workflows.orderApproval.approveButton": "Aprobar",
@@ -1135,6 +1142,7 @@
   "workflows.triggers.status.disabled": "Deshabilitado",
   "workflows.triggers.title": "Disparadores de eventos",
   "workflows.validation.descriptionMaxLength": "La descripcion debe tener 5000 caracteres o menos",
+  "workflows.validation.invalidDuration": "Duracion no valida. Use ISO 8601 (p. ej. PT5M, PT1H, P1D) o formato simple (5m, 1h, 3d).",
   "workflows.validation.invalidFormat": "Formato no valido",
   "workflows.validation.invalidTransition": "Configuracion de transicion no valida",
   "workflows.validation.invalidWorkflowId": "El ID del flujo de trabajo solo puede contener letras minusculas, numeros, guiones y guiones bajos",
@@ -1144,6 +1152,7 @@
   "workflows.validation.noOrphanSteps": "Todos los pasos deben estar conectados",
   "workflows.validation.required": "Este campo es obligatorio",
   "workflows.validation.uniqueId": "El ID debe ser unico",
+  "workflows.validation.untilMustBeFuture": "Esperar hasta debe ser una fecha y hora futura.",
   "workflows.validation.workflowIdFormat": "El ID del flujo de trabajo solo puede contener letras minusculas, numeros, guiones y guiones bajos",
   "workflows.validation.workflowIdMaxLength": "El ID del flujo de trabajo debe tener 50 caracteres o menos",
   "workflows.validation.workflowIdRequired": "El ID del flujo de trabajo es obligatorio",

package/src/modules/workflows/i18n/pl.json

@@ -93,7 +93,13 @@
   "workflows.activities.types.EXECUTE_FUNCTION": "Wykonaj Funkcję",
   "workflows.activities.types.SEND_EMAIL": "Wyślij Email",
   "workflows.activities.types.UPDATE_ENTITY": "Zaktualizuj Encję",
-  "workflows.activities.types.WAIT": "Czekaj",
+  "workflows.activities.types.WAIT": "Czekaj / Opóźnienie",
+  "workflows.activities.waitDuration": "Czas trwania",
+  "workflows.activities.waitDurationDescription": "Format ISO 8601 (np. PT5M dla 5 minut, PT1H dla 1 godziny, P1D dla 1 dnia) lub prosty format (5m, 1h, 3d)",
+  "workflows.activities.waitDurationPlaceholder": "PT5M",
+  "workflows.activities.waitOr": "lub",
+  "workflows.activities.waitUntil": "Czekaj do",
+  "workflows.activities.waitUntilDescription": "Konkretna data i godzina, do której czekać",
   "workflows.backToList": "Powrót do przepływów",
   "workflows.backend.definitions.visual_editor.title": "Wizualny Edytor Przepływów Pracy",
   "workflows.checkoutDemo.cart.empty.hint": "Dodaj produkty z listy powyżej",
@@ -910,6 +916,7 @@
   "workflows.nodeTypes.subWorkflow": "PODPRZEPŁYW",
   "workflows.nodeTypes.userTask": "ZADANIE UŻYTKOWNIKA",
   "workflows.nodeTypes.waitForSignal": "CZEKAJ NA SYGNAŁ",
+  "workflows.nodeTypes.waitForTimer": "CZEKAJ NA TIMER",
   "workflows.notifications.task.assigned.body": "Przypisano Ci zadanie \"{taskName}\" w przepływie \"{workflowName}\"{dueDate, select, other { (termin: {dueDate})}}",
   "workflows.notifications.task.assigned.title": "Przypisano Zadanie",
   "workflows.orderApproval.approveButton": "Zatwierdź",
@@ -1135,6 +1142,7 @@
   "workflows.triggers.status.disabled": "Wyłączony",
   "workflows.triggers.title": "Wyzwalacze Zdarzeń",
   "workflows.validation.descriptionMaxLength": "Opis musi mieć 5000 znaków lub mniej",
+  "workflows.validation.invalidDuration": "Nieprawidłowy czas trwania. Użyj formatu ISO 8601 (np. PT5M, PT1H, P1D) lub uproszczonego (5m, 1h, 3d).",
   "workflows.validation.invalidFormat": "Nieprawidłowy format",
   "workflows.validation.invalidTransition": "Nieprawidłowa konfiguracja przejścia",
   "workflows.validation.invalidWorkflowId": "ID przepływu może zawierać tylko małe litery, cyfry, myślniki i podkreślenia",
@@ -1144,6 +1152,7 @@
   "workflows.validation.noOrphanSteps": "Wszystkie kroki muszą być połączone",
   "workflows.validation.required": "To pole jest wymagane",
   "workflows.validation.uniqueId": "ID musi być unikalne",
+  "workflows.validation.untilMustBeFuture": "„Czekaj do” musi być datą i godziną w przyszłości.",
   "workflows.validation.workflowIdFormat": "ID przepływu może zawierać tylko małe litery, cyfry, myślniki i podkreślenia",
   "workflows.validation.workflowIdMaxLength": "ID przepływu musi mieć 50 znaków lub mniej",
   "workflows.validation.workflowIdRequired": "ID przepływu jest wymagane",

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

@@ -25,6 +25,7 @@ import { parseBooleanWithDefault } from '@open-mercato/shared/lib/boolean'
 import { callWebhookConfigSchema } from '../data/validators'
 import { WorkflowActivityJob, WORKFLOW_ACTIVITIES_QUEUE_NAME } from './activity-queue-types'
 import { logWorkflowEvent } from './event-logger'
+import { parseDuration } from './duration'
 
 export { isPrivateUrl } from '@open-mercato/shared/lib/network'
 
@@ -54,6 +55,7 @@ export type ActivityType =
   | 'UPDATE_ENTITY'
   | 'CALL_WEBHOOK'
   | 'EXECUTE_FUNCTION'
+  | 'WAIT'
 
 export interface ActivityDefinition {
   activityId: string // Unique identifier for activity
@@ -164,9 +166,12 @@ export async function enqueueActivity(
     userId: context.userId,
   }
 
-  // Enqueue to queue
+  // Enqueue to queue (WAIT activities use delayMs for the actual delay)
   const queue = getActivityQueue()
-  const jobId = await queue.enqueue(job)
+  const enqueueOptions = activity.activityType === 'WAIT' && (interpolatedConfig.duration || interpolatedConfig.until)
+    ? { delayMs: calculateWaitDelayMs(interpolatedConfig) }
+    : undefined
+  const jobId = await queue.enqueue(job, enqueueOptions)
 
   // Log event
   await logWorkflowEvent(em, {
@@ -187,6 +192,41 @@ export async function enqueueActivity(
   return jobId
 }
 
+/**
+ * Enqueue a delayed timer job for a WAIT_FOR_TIMER step.
+ *
+ * The activity worker handles `kind: 'timer'` jobs by calling
+ * `timerHandler.fireTimer`, which resumes the paused workflow instance.
+ */
+export async function enqueueTimerJob(params: {
+  workflowInstanceId: string
+  stepInstanceId: string
+  tenantId: string
+  organizationId: string
+  userId?: string
+  fireAt: string
+  delayMs: number
+}): Promise<string> {
+  const { workflowInstanceId, stepInstanceId, tenantId, organizationId, userId, fireAt, delayMs } =
+    params
+
+  const queue = getActivityQueue()
+  const jobId = await queue.enqueue(
+    {
+      kind: 'timer',
+      workflowInstanceId,
+      stepInstanceId,
+      tenantId,
+      organizationId,
+      userId,
+      fireAt,
+    },
+    { delayMs: delayMs > 0 ? delayMs : undefined }
+  )
+
+  return jobId
+}
+
 // ============================================================================
 // Main Activity Execution Functions
 // ============================================================================
@@ -377,6 +417,9 @@ async function executeActivityByType(
     case 'EXECUTE_FUNCTION':
       return await executeFunction(interpolatedConfig, context, container)
 
+    case 'WAIT':
+      return await executeWait(interpolatedConfig)
+
     default:
       throw new ActivityExecutionError(
         `Unknown activity type: ${activity.activityType}`,
@@ -750,6 +793,47 @@ export async function executeFunction(
   }
 }
 
+/**
+ * Calculate delay in milliseconds from a WAIT activity config.
+ * Supports either `duration` (relative, e.g. "PT5M") or `until` (absolute ISO 8601 datetime).
+ */
+function calculateWaitDelayMs(config: { duration?: string; until?: string }): number {
+  if (config.until) {
+    const targetDate = new Date(config.until)
+    if (isNaN(targetDate.getTime())) {
+      throw new Error(`WAIT activity: invalid "until" datetime: ${config.until}`)
+    }
+    const delayMs = targetDate.getTime() - Date.now()
+    return Math.max(0, delayMs)
+  }
+
+  if (config.duration) {
+    return parseDuration(config.duration)
+  }
+
+  throw new Error('WAIT activity requires "duration" (e.g., "PT5M", "1h") or "until" (ISO 8601 datetime)')
+}
+
+/**
+ * WAIT activity handler
+ *
+ * Delays workflow execution for a configured duration or until a specific datetime.
+ * - `duration`: relative delay (e.g. "PT5M", "1h", "30s")
+ * - `until`: absolute datetime (e.g. "2026-04-15T10:00:00Z")
+ * - Sync mode: blocks via sleep (suitable for short delays)
+ * - Async mode: delay is handled by the queue's delayMs option;
+ *   this handler returns immediately when called from the worker
+ */
+async function executeWait(config: any): Promise<any> {
+  const durationMs = calculateWaitDelayMs(config)
+
+  // In sync mode, actually sleep for the duration
+  // In async mode (called from worker), the delay already happened via queue scheduling
+  await sleep(durationMs)
+
+  return { waited: true, durationMs }
+}
+
 /**
  * CALL_API activity handler
  *

package/src/modules/workflows/lib/activity-queue-types.ts

@@ -2,25 +2,31 @@
  * Workflow Activity Queue Types
  *
  * Type definitions for async activity execution via queue system.
+ * Jobs are discriminated by the optional `kind` field:
+ *   - `'activity'` (default, back-compat): background execution of a workflow activity
+ *   - `'timer'`: delayed fire-timer job for a WAIT_FOR_TIMER step
  */
 
-export interface WorkflowActivityJob {
-  // Execution context
+export interface WorkflowActivityJobBase {
   workflowInstanceId: string
   stepInstanceId?: string
+  tenantId: string
+  organizationId: string
+  userId?: string
+}
+
+export interface WorkflowActivityJobActivity extends WorkflowActivityJobBase {
+  kind?: 'activity'
   transitionId?: string
 
-  // Activity definition
   activityId: string
   activityName: string
   activityType: string
   activityConfig: any
 
-  // Workflow context (for execution)
   workflowContext: Record<string, any>
   stepContext?: Record<string, any>
 
-  // Retry & timeout config
   retryPolicy?: {
     maxAttempts: number
     initialIntervalMs: number
@@ -28,13 +34,14 @@ export interface WorkflowActivityJob {
     maxIntervalMs: number
   }
   timeoutMs?: number
+}
 
-  // Multi-tenant
-  tenantId: string
-  organizationId: string
-
-  // Metadata
-  userId?: string
+export interface WorkflowActivityJobTimer extends WorkflowActivityJobBase {
+  kind: 'timer'
+  stepInstanceId: string
+  fireAt: string // ISO 8601 timestamp for when the timer should fire
 }
 
+export type WorkflowActivityJob = WorkflowActivityJobActivity | WorkflowActivityJobTimer
+
 export const WORKFLOW_ACTIVITIES_QUEUE_NAME = 'workflow-activities'

package/src/modules/workflows/lib/activity-worker-handler.ts

@@ -34,6 +34,31 @@ export function createActivityWorkerHandler(
     const { payload } = job
     const startTime = Date.now()
 
+    // Timer jobs (kind: 'timer') are a distinct flow — they resume a paused
+    // workflow instance rather than executing an activity. Handle them first.
+    if (payload.kind === 'timer') {
+      console.log(
+        `[ActivityWorker] Firing timer for instance ${payload.workflowInstanceId} (job ${ctx.jobId})`
+      )
+      try {
+        const { fireTimer } = await import('./timer-handler')
+        await fireTimer(em, container, {
+          instanceId: payload.workflowInstanceId,
+          stepInstanceId: payload.stepInstanceId,
+          tenantId: payload.tenantId,
+          organizationId: payload.organizationId,
+          userId: payload.userId,
+        })
+      } catch (error: any) {
+        console.error(
+          `[ActivityWorker] Failed to fire timer for instance ${payload.workflowInstanceId}:`,
+          error.message
+        )
+        throw error
+      }
+      return
+    }
+
     console.log(
       `[ActivityWorker] Processing activity ${payload.activityId} (job ${ctx.jobId})`
     )
@@ -79,6 +104,10 @@ export function createActivityWorkerHandler(
             return await executeCallWebhook(payload.activityConfig, activityContext)
           case 'EXECUTE_FUNCTION':
             return await executeFunction(payload.activityConfig, activityContext, container)
+          case 'WAIT':
+            // Delay already applied by the queue via delayMs; the worker
+            // only needs to record completion so the workflow can resume.
+            return { waited: true, async: true }
           default:
             throw new Error(`Unsupported activity type: ${payload.activityType}`)
         }

package/src/modules/workflows/lib/duration.ts

@@ -0,0 +1,51 @@
+/**
+ * Parse ISO 8601 duration to milliseconds
+ *
+ * Supports:
+ * - ISO 8601: PT5M (5 minutes), PT1H (1 hour), P1D (1 day), P3D (3 days)
+ * - Simple formats: 5m, 1h, 3d, 30s
+ *
+ * @param duration - Duration string
+ * @returns Duration in milliseconds
+ */
+export function parseDuration(duration: string): number {
+  // Try ISO 8601 format first: P[n]DT[n]H[n]M[n]S
+  const iso8601Regex = /P(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?)?/
+  const iso8601Match = duration.match(iso8601Regex)
+
+  if (iso8601Match && iso8601Match[0] === duration) {
+    const days = parseInt(iso8601Match[1] || '0')
+    const hours = parseInt(iso8601Match[2] || '0')
+    const minutes = parseInt(iso8601Match[3] || '0')
+    const seconds = parseInt(iso8601Match[4] || '0')
+
+    return (
+      days * 24 * 60 * 60 * 1000 +
+      hours * 60 * 60 * 1000 +
+      minutes * 60 * 1000 +
+      seconds * 1000
+    )
+  }
+
+  // Try simple format: 1d, 5h, 30m, 45s
+  const simpleRegex = /^(\d+)(d|h|m|s)$/
+  const simpleMatch = duration.match(simpleRegex)
+
+  if (simpleMatch) {
+    const value = parseInt(simpleMatch[1])
+    const unit = simpleMatch[2]
+
+    switch (unit) {
+      case 'd':
+        return value * 24 * 60 * 60 * 1000
+      case 'h':
+        return value * 60 * 60 * 1000
+      case 'm':
+        return value * 60 * 1000
+      case 's':
+        return value * 1000
+    }
+  }
+
+  throw new Error(`Invalid duration format: ${duration}`)
+}

package/src/modules/workflows/lib/event-logger.ts

@@ -73,6 +73,7 @@ export const WorkflowEventTypes = {
   SIGNAL_TIMEOUT: 'SIGNAL_TIMEOUT',
 
   // Timer events (Phase 9)
+  TIMER_AWAITING: 'TIMER_AWAITING',
   TIMER_FIRED: 'TIMER_FIRED',
   TIMER_CANCELLED: 'TIMER_CANCELLED',
 } as const

package/src/modules/workflows/lib/format-validation-error.ts

@@ -0,0 +1,30 @@
+type ZodIssueLite = {
+  path?: Array<string | number>
+  message?: string
+}
+
+type ApiErrorBody = {
+  error?: string
+  details?: ZodIssueLite[]
+}
+
+/**
+ * Format an API validation error body into a user-readable message.
+ *
+ * The workflow definitions API returns `{ error: 'Validation failed', details: ZodIssue[] }`
+ * for schema failures. The generic `error` string is useless to the user — the actionable
+ * information lives in `details[0].path` and `details[0].message`. This helper mirrors the
+ * visual editor's `Schema error: <path> - <message>` format so both editors surface the
+ * same diagnostic.
+ */
+export function formatWorkflowValidationError(
+  body: ApiErrorBody | null | undefined,
+  fallback: string,
+): string {
+  const issue = body?.details?.[0]
+  if (issue?.message) {
+    const path = (issue.path ?? []).join('.')
+    return path ? `${path} - ${issue.message}` : issue.message
+  }
+  return body?.error || fallback
+}

package/src/modules/workflows/lib/graph-utils.ts

@@ -452,6 +452,7 @@ function mapNodeTypeToStepType(nodeType: string): string {
     automated: 'AUTOMATED',
     decision: 'DECISION',
     waitForSignal: 'WAIT_FOR_SIGNAL',
+    waitForTimer: 'WAIT_FOR_TIMER',
   }
   return mapping[nodeType] || 'AUTOMATED'
 }
@@ -467,6 +468,7 @@ function mapStepTypeToNodeType(stepType: string): string {
     AUTOMATED: 'automated',
     DECISION: 'decision',
     WAIT_FOR_SIGNAL: 'waitForSignal',
+    WAIT_FOR_TIMER: 'waitForTimer',
   }
   return mapping[stepType] || 'automated'
 }
@@ -482,6 +484,7 @@ function getBadgeForNodeType(nodeType: string): string {
     automated: 'Automated',
     decision: 'Decision',
     waitForSignal: 'Wait for Signal',
+    waitForTimer: 'Wait for Timer',
   }
   return badges[nodeType] || 'Task'
 }