@open-mercato/core 0.6.5-develop.4516.1.88e6ab71a9 → 0.6.5-develop.4544.1.71c003c861

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

@@ -69,9 +69,20 @@ export const workflowInstanceStatusSchema = z.enum([
   'COMPENSATING',
   'COMPENSATED',
   'WAITING_FOR_ACTIVITIES',
+  'FORKED',
 ])
 export type WorkflowInstanceStatus = z.infer<typeof workflowInstanceStatusSchema>
 
+export const workflowBranchInstanceStatusSchema = z.enum([
+  'ACTIVE',
+  'PAUSED',
+  'WAITING_FOR_ACTIVITIES',
+  'COMPLETED',
+  'FAILED',
+  'CANCELLED',
+])
+export type WorkflowBranchInstanceStatus = z.infer<typeof workflowBranchInstanceStatusSchema>
+
 export const stepInstanceStatusSchema = z.enum([
   'PENDING',
   'ACTIVE',
@@ -376,6 +387,210 @@ export const workflowDefinitionTriggerSchema = z.object({
 })
 export type WorkflowDefinitionTrigger = z.infer<typeof workflowDefinitionTriggerSchema>
 
+// ============================================================================
+// PARALLEL_FORK / PARALLEL_JOIN definition validation
+// ============================================================================
+
+// Error codes surfaced by FORK/JOIN definition validation. Stable identifiers
+// so the visual editor and tests can match on them.
+export type ForkJoinValidationCode =
+  | 'MISSING_JOIN_STEP_ID'
+  | 'JOIN_STEP_NOT_FOUND'
+  | 'JOIN_STEP_WRONG_TYPE'
+  | 'MISSING_FORK_STEP_ID'
+  | 'FORK_JOIN_MISMATCH'
+  | 'FORK_TOO_FEW_BRANCHES'
+  | 'JOIN_TOO_FEW_INCOMING'
+  | 'DUPLICATE_BRANCH_KEY'
+  | 'NESTED_FORK_NOT_SUPPORTED'
+  | 'NO_CONVERGENCE_TO_JOIN'
+  | 'FORK_JOIN_CYCLE'
+  | 'UNPAIRED_JOIN'
+
+export interface ForkJoinValidationIssue {
+  code: ForkJoinValidationCode
+  message: string
+  stepId?: string
+}
+
+interface ForkJoinStepLike {
+  stepId: string
+  stepType: string
+  config?: Record<string, unknown> | null
+}
+
+interface ForkJoinTransitionLike {
+  transitionId: string
+  fromStepId: string
+  toStepId: string
+  trigger: string
+}
+
+interface ForkJoinDefinitionLike {
+  steps: ForkJoinStepLike[]
+  transitions: ForkJoinTransitionLike[]
+}
+
+/**
+ * Validates PARALLEL_FORK / PARALLEL_JOIN structure of a workflow definition.
+ * Pure and side-effect-free so it can be unit tested and reused by the editor.
+ *
+ * Rules (this iteration — wait-all, no nesting):
+ *  1. Every FORK declares config.joinStepId pointing at an existing PARALLEL_JOIN.
+ *  2. The paired JOIN back-references the fork via config.forkStepId.
+ *  3. A FORK has >= 2 outgoing `auto` transitions (branch keys unique); a JOIN has >= 2 incoming.
+ *  4. Every path from a FORK converges to its JOIN — no END inside a branch, no dead ends,
+ *     no path bypassing the JOIN, no path to a different JOIN.
+ *  5. No nesting: no FORK appears on a path between a FORK and its JOIN.
+ *  6. No cycles back to the FORK within its branch region.
+ *  7. Every PARALLEL_JOIN is paired with exactly one FORK.
+ */
+export function validateParallelForkJoin(definition: ForkJoinDefinitionLike): ForkJoinValidationIssue[] {
+  const issues: ForkJoinValidationIssue[] = []
+  const steps = definition.steps ?? []
+  const transitions = definition.transitions ?? []
+
+  const stepById = new Map<string, ForkJoinStepLike>()
+  for (const step of steps) stepById.set(step.stepId, step)
+
+  const outgoingByStep = new Map<string, ForkJoinTransitionLike[]>()
+  const incomingCountByStep = new Map<string, number>()
+  for (const transition of transitions) {
+    const list = outgoingByStep.get(transition.fromStepId) ?? []
+    list.push(transition)
+    outgoingByStep.set(transition.fromStepId, list)
+    incomingCountByStep.set(transition.toStepId, (incomingCountByStep.get(transition.toStepId) ?? 0) + 1)
+  }
+
+  const forkSteps = steps.filter((step) => step.stepType === 'PARALLEL_FORK')
+  const joinSteps = steps.filter((step) => step.stepType === 'PARALLEL_JOIN')
+
+  // Track which JOIN steps are paired with a FORK so we can flag orphan joins.
+  const pairedJoinIds = new Set<string>()
+
+  for (const fork of forkSteps) {
+    const joinStepId = (fork.config?.joinStepId as string | undefined) ?? undefined
+    if (!joinStepId) {
+      issues.push({ code: 'MISSING_JOIN_STEP_ID', stepId: fork.stepId, message: `PARALLEL_FORK "${fork.stepId}" must declare config.joinStepId` })
+      continue
+    }
+    const joinStep = stepById.get(joinStepId)
+    if (!joinStep) {
+      issues.push({ code: 'JOIN_STEP_NOT_FOUND', stepId: fork.stepId, message: `PARALLEL_FORK "${fork.stepId}" references missing join step "${joinStepId}"` })
+      continue
+    }
+    if (joinStep.stepType !== 'PARALLEL_JOIN') {
+      issues.push({ code: 'JOIN_STEP_WRONG_TYPE', stepId: fork.stepId, message: `Step "${joinStepId}" referenced by fork "${fork.stepId}" is not a PARALLEL_JOIN` })
+      continue
+    }
+
+    pairedJoinIds.add(joinStepId)
+
+    const backForkStepId = (joinStep.config?.forkStepId as string | undefined) ?? undefined
+    if (!backForkStepId) {
+      issues.push({ code: 'MISSING_FORK_STEP_ID', stepId: joinStepId, message: `PARALLEL_JOIN "${joinStepId}" must declare config.forkStepId` })
+    } else if (backForkStepId !== fork.stepId) {
+      issues.push({ code: 'FORK_JOIN_MISMATCH', stepId: joinStepId, message: `PARALLEL_JOIN "${joinStepId}" back-reference forkStepId "${backForkStepId}" does not match fork "${fork.stepId}"` })
+    }
+
+    const autoBranches = (outgoingByStep.get(fork.stepId) ?? []).filter((transition) => transition.trigger === 'auto')
+    if (autoBranches.length < 2) {
+      issues.push({ code: 'FORK_TOO_FEW_BRANCHES', stepId: fork.stepId, message: `PARALLEL_FORK "${fork.stepId}" must have at least 2 outgoing auto transitions (found ${autoBranches.length})` })
+    }
+    const branchKeys = new Set<string>()
+    for (const branch of autoBranches) {
+      if (branchKeys.has(branch.transitionId)) {
+        issues.push({ code: 'DUPLICATE_BRANCH_KEY', stepId: fork.stepId, message: `PARALLEL_FORK "${fork.stepId}" has duplicate branch key "${branch.transitionId}"` })
+      }
+      branchKeys.add(branch.transitionId)
+    }
+
+    if ((incomingCountByStep.get(joinStepId) ?? 0) < 2) {
+      issues.push({ code: 'JOIN_TOO_FEW_INCOMING', stepId: joinStepId, message: `PARALLEL_JOIN "${joinStepId}" must have at least 2 incoming transitions` })
+    }
+
+    // Convergence + no-nesting + no-cycle traversal over the branch region.
+    const fullyExplored = new Set<string>()
+    const onStack = new Set<string>()
+    let reportedNesting = false
+    let reportedNoConvergence = false
+    let reportedCycle = false
+
+    const visit = (stepId: string): void => {
+      if (stepId === joinStepId) return // converged
+      if (stepId === fork.stepId) {
+        if (!reportedCycle) {
+          issues.push({ code: 'FORK_JOIN_CYCLE', stepId: fork.stepId, message: `A branch of fork "${fork.stepId}" loops back to the fork before reaching join "${joinStepId}"` })
+          reportedCycle = true
+        }
+        return
+      }
+      const step = stepById.get(stepId)
+      if (!step) {
+        if (!reportedNoConvergence) {
+          issues.push({ code: 'NO_CONVERGENCE_TO_JOIN', stepId: fork.stepId, message: `A branch of fork "${fork.stepId}" reaches missing step "${stepId}" instead of join "${joinStepId}"` })
+          reportedNoConvergence = true
+        }
+        return
+      }
+      if (step.stepType === 'END') {
+        if (!reportedNoConvergence) {
+          issues.push({ code: 'NO_CONVERGENCE_TO_JOIN', stepId: fork.stepId, message: `A branch of fork "${fork.stepId}" reaches an END step before join "${joinStepId}"` })
+          reportedNoConvergence = true
+        }
+        return
+      }
+      if (step.stepType === 'PARALLEL_FORK') {
+        if (!reportedNesting) {
+          issues.push({ code: 'NESTED_FORK_NOT_SUPPORTED', stepId: fork.stepId, message: `Nested PARALLEL_FORK "${stepId}" inside fork "${fork.stepId}" is not supported` })
+          reportedNesting = true
+        }
+        return
+      }
+      if (step.stepType === 'PARALLEL_JOIN') {
+        // Reached a join that is not this fork's join → it does not converge correctly.
+        if (!reportedNoConvergence) {
+          issues.push({ code: 'NO_CONVERGENCE_TO_JOIN', stepId: fork.stepId, message: `A branch of fork "${fork.stepId}" reaches join "${stepId}" instead of its own join "${joinStepId}"` })
+          reportedNoConvergence = true
+        }
+        return
+      }
+      if (onStack.has(stepId)) {
+        if (!reportedCycle) {
+          issues.push({ code: 'FORK_JOIN_CYCLE', stepId: fork.stepId, message: `A branch of fork "${fork.stepId}" contains a cycle at step "${stepId}"` })
+          reportedCycle = true
+        }
+        return
+      }
+      if (fullyExplored.has(stepId)) return
+
+      const outgoing = outgoingByStep.get(stepId) ?? []
+      if (outgoing.length === 0) {
+        if (!reportedNoConvergence) {
+          issues.push({ code: 'NO_CONVERGENCE_TO_JOIN', stepId: fork.stepId, message: `A branch of fork "${fork.stepId}" dead-ends at step "${stepId}" without reaching join "${joinStepId}"` })
+          reportedNoConvergence = true
+        }
+        return
+      }
+      onStack.add(stepId)
+      for (const transition of outgoing) visit(transition.toStepId)
+      onStack.delete(stepId)
+      fullyExplored.add(stepId)
+    }
+
+    for (const branch of autoBranches) visit(branch.toStepId)
+  }
+
+  // Any PARALLEL_JOIN not paired with a fork is an orphan.
+  for (const join of joinSteps) {
+    if (!pairedJoinIds.has(join.stepId)) {
+      issues.push({ code: 'UNPAIRED_JOIN', stepId: join.stepId, message: `PARALLEL_JOIN "${join.stepId}" is not paired with any PARALLEL_FORK` })
+    }
+  }
+
+  return issues
+}
+
 // Workflow definition data (JSONB structure)
 export const workflowDefinitionDataSchema = z.object({
   steps: z.array(workflowStepSchema).min(2, 'Workflow must have at least START and END steps'),
@@ -384,6 +599,14 @@ export const workflowDefinitionDataSchema = z.object({
   queries: z.array(z.any()).optional(), // For Phase 7
   signals: z.array(z.any()).optional(), // For Phase 9
   timers: z.array(z.any()).optional(), // For Phase 9
+}).superRefine((definition, ctx) => {
+  for (const issue of validateParallelForkJoin(definition as ForkJoinDefinitionLike)) {
+    ctx.addIssue({
+      code: 'custom',
+      path: ['steps'],
+      message: `[${issue.code}] ${issue.message}`,
+    })
+  }
 })
 
 // Workflow metadata

package/src/modules/workflows/di.ts

@@ -6,6 +6,9 @@
 
 import type { AwilixContainer } from 'awilix'
 import { asFunction } from 'awilix'
+import { createGenericOptimisticLockReader } from '@open-mercato/shared/lib/crud/optimistic-lock'
+import { registerOptimisticLockReaders } from '@open-mercato/shared/lib/crud/optimistic-lock-store'
+import { WorkflowDefinition } from './data/entities'
 import * as workflowExecutor from './lib/workflow-executor'
 import * as stepHandler from './lib/step-handler'
 import * as transitionHandler from './lib/transition-handler'
@@ -14,6 +17,23 @@ import * as eventLogger from './lib/event-logger'
 import * as signalHandler from './lib/signal-handler'
 import * as timerHandler from './lib/timer-handler'
 
+// Register the `workflows.definition` optimistic-lock reader at module-DI load
+// time (top-level, like sales/customers) so it is present in the global reader
+// store before any request-scoped `crudMutationGuardService` snapshots
+// `getAllOptimisticLockReaders()`. Registering it only as a side-effect of
+// importing the definition route module left it absent from that snapshot, so
+// the guard short-circuited and the visual editor's stale saves overwrote with
+// no 409 and no conflict bar.
+registerOptimisticLockReaders({
+  'workflows.definition': createGenericOptimisticLockReader({
+    entity: WorkflowDefinition,
+    idField: 'id',
+    tenantField: 'tenantId',
+    orgField: 'organizationId',
+    softDeleteField: 'deletedAt',
+  }),
+})
+
 export function register(container: AwilixContainer): void {
   container.register({
     workflowExecutor: asFunction(() => workflowExecutor).scoped(),

package/src/modules/workflows/events.ts

@@ -35,6 +35,13 @@ const events = [
   { id: 'workflows.trigger.created', label: 'Trigger Created', entity: 'trigger', category: 'crud' },
   { id: 'workflows.trigger.updated', label: 'Trigger Updated', entity: 'trigger', category: 'crud' },
   { id: 'workflows.trigger.deleted', label: 'Trigger Deleted', entity: 'trigger', category: 'crud' },
+
+  // Parallel Fork / Join (branch lifecycle)
+  { id: 'workflows.branch.opened', label: 'Parallel Branch Opened', entity: 'branch', category: 'lifecycle' },
+  { id: 'workflows.branch.completed', label: 'Parallel Branch Completed', entity: 'branch', category: 'lifecycle' },
+  { id: 'workflows.branch.cancelled', label: 'Parallel Branch Cancelled', entity: 'branch', category: 'lifecycle' },
+  { id: 'workflows.branch.failed', label: 'Parallel Branch Failed', entity: 'branch', category: 'lifecycle' },
+  { id: 'workflows.join.completed', label: 'Parallel Join Completed', entity: 'branch', category: 'lifecycle' },
 ] as const
 
 export const eventsConfig = createModuleEvents({

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

@@ -860,6 +860,7 @@
   "workflows.messages.instanceStarted": "Workflow-Instanz gestartet",
   "workflows.messages.invalidWorkflow": "Ungültige Workflow-Definition",
   "workflows.messages.loadFailed": "Workflows konnten nicht geladen werden",
+  "workflows.messages.saveFailed": "Speichern fehlgeschlagen",
   "workflows.messages.taskAlreadyClaimed": "Aufgabe wurde bereits von einem anderen Benutzer übernommen",
   "workflows.messages.taskClaimed": "Aufgabe erfolgreich übernommen",
   "workflows.messages.taskCompleted": "Aufgabe erfolgreich abgeschlossen",
@@ -913,6 +914,8 @@
   "workflows.nodeTypes.automated": "AUTOMATISIERT",
   "workflows.nodeTypes.decision": "ENTSCHEIDUNG",
   "workflows.nodeTypes.end": "ENDE",
+  "workflows.nodeTypes.parallelFork": "Parallele Verzweigung",
+  "workflows.nodeTypes.parallelJoin": "Parallele Zusammenführung",
   "workflows.nodeTypes.start": "START",
   "workflows.nodeTypes.subWorkflow": "SUB-WORKFLOW",
   "workflows.nodeTypes.userTask": "BENUTZERAUFGABE",
@@ -937,6 +940,16 @@
   "workflows.orderApproval.requestApproval": "Genehmigung anfordern",
   "workflows.orderApproval.startError": "Genehmigungsworkflow konnte nicht gestartet werden.",
   "workflows.orderApproval.submitDecision": "Entscheidung einreichen",
+  "workflows.parallel.branch.label": "Zweig",
+  "workflows.parallel.branch.status.ACTIVE": "Aktiv",
+  "workflows.parallel.branch.status.CANCELLED": "Abgebrochen",
+  "workflows.parallel.branch.status.COMPLETED": "Abgeschlossen",
+  "workflows.parallel.branch.status.FAILED": "Fehlgeschlagen",
+  "workflows.parallel.branch.status.PAUSED": "Pausiert",
+  "workflows.parallel.branch.status.WAITING_FOR_ACTIVITIES": "Warten auf Aktivitäten",
+  "workflows.parallel.fork.label": "Parallele Verzweigung",
+  "workflows.parallel.join.label": "Parallele Zusammenführung",
+  "workflows.parallel.validation.title": "Validierung der parallelen Verzweigung/Zusammenführung fehlgeschlagen",
   "workflows.signals.awaiting": "Wartet auf Signal",
   "workflows.signals.correlationKey": "Korrelationsschlüssel",
   "workflows.signals.payload": "Signal-Nutzlast",

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

@@ -860,6 +860,7 @@
   "workflows.messages.instanceStarted": "Workflow instance started",
   "workflows.messages.invalidWorkflow": "Invalid workflow definition",
   "workflows.messages.loadFailed": "Failed to load workflows",
+  "workflows.messages.saveFailed": "Failed to save",
   "workflows.messages.taskAlreadyClaimed": "Task is already claimed by another user",
   "workflows.messages.taskClaimed": "Task claimed successfully",
   "workflows.messages.taskCompleted": "Task completed successfully",
@@ -913,6 +914,8 @@
   "workflows.nodeTypes.automated": "AUTOMATED",
   "workflows.nodeTypes.decision": "DECISION",
   "workflows.nodeTypes.end": "END",
+  "workflows.nodeTypes.parallelFork": "Parallel Fork",
+  "workflows.nodeTypes.parallelJoin": "Parallel Join",
   "workflows.nodeTypes.start": "START",
   "workflows.nodeTypes.subWorkflow": "SUB-WORKFLOW",
   "workflows.nodeTypes.userTask": "USER TASK",
@@ -937,6 +940,16 @@
   "workflows.orderApproval.requestApproval": "Request Approval",
   "workflows.orderApproval.startError": "Failed to start approval workflow.",
   "workflows.orderApproval.submitDecision": "Submit Decision",
+  "workflows.parallel.branch.label": "Branch",
+  "workflows.parallel.branch.status.ACTIVE": "Active",
+  "workflows.parallel.branch.status.CANCELLED": "Cancelled",
+  "workflows.parallel.branch.status.COMPLETED": "Completed",
+  "workflows.parallel.branch.status.FAILED": "Failed",
+  "workflows.parallel.branch.status.PAUSED": "Paused",
+  "workflows.parallel.branch.status.WAITING_FOR_ACTIVITIES": "Waiting for activities",
+  "workflows.parallel.fork.label": "Parallel Fork",
+  "workflows.parallel.join.label": "Parallel Join",
+  "workflows.parallel.validation.title": "Parallel fork/join validation failed",
   "workflows.signals.awaiting": "Waiting for signal",
   "workflows.signals.correlationKey": "Correlation Key",
   "workflows.signals.payload": "Signal Payload",

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

@@ -860,6 +860,7 @@
   "workflows.messages.instanceStarted": "Instancia del flujo de trabajo iniciada",
   "workflows.messages.invalidWorkflow": "Definicion de flujo de trabajo no valida",
   "workflows.messages.loadFailed": "No se pudieron cargar los flujos de trabajo",
+  "workflows.messages.saveFailed": "Error al guardar",
   "workflows.messages.taskAlreadyClaimed": "La tarea ya ha sido reclamada por otro usuario",
   "workflows.messages.taskClaimed": "Tarea reclamada correctamente",
   "workflows.messages.taskCompleted": "Tarea completada correctamente",
@@ -913,6 +914,8 @@
   "workflows.nodeTypes.automated": "AUTOMATIZADO",
   "workflows.nodeTypes.decision": "DECISIÓN",
   "workflows.nodeTypes.end": "FIN",
+  "workflows.nodeTypes.parallelFork": "Bifurcación paralela",
+  "workflows.nodeTypes.parallelJoin": "Unión paralela",
   "workflows.nodeTypes.start": "INICIO",
   "workflows.nodeTypes.subWorkflow": "SUBFLUJO DE TRABAJO",
   "workflows.nodeTypes.userTask": "TAREA DE USUARIO",
@@ -937,6 +940,16 @@
   "workflows.orderApproval.requestApproval": "Solicitar aprobación",
   "workflows.orderApproval.startError": "Error al iniciar el flujo de aprobación.",
   "workflows.orderApproval.submitDecision": "Enviar decisión",
+  "workflows.parallel.branch.label": "Rama",
+  "workflows.parallel.branch.status.ACTIVE": "Activa",
+  "workflows.parallel.branch.status.CANCELLED": "Cancelada",
+  "workflows.parallel.branch.status.COMPLETED": "Completada",
+  "workflows.parallel.branch.status.FAILED": "Fallida",
+  "workflows.parallel.branch.status.PAUSED": "En pausa",
+  "workflows.parallel.branch.status.WAITING_FOR_ACTIVITIES": "Esperando actividades",
+  "workflows.parallel.fork.label": "Bifurcación paralela",
+  "workflows.parallel.join.label": "Unión paralela",
+  "workflows.parallel.validation.title": "La validación de la bifurcación/unión paralela falló",
   "workflows.signals.awaiting": "Esperando senal",
   "workflows.signals.correlationKey": "Clave de correlacion",
   "workflows.signals.payload": "Carga de la senal",

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

@@ -860,6 +860,7 @@
   "workflows.messages.instanceStarted": "Instancja przepływu rozpoczęta",
   "workflows.messages.invalidWorkflow": "Nieprawidłowa definicja przepływu",
   "workflows.messages.loadFailed": "Nie udało się załadować przepływów",
+  "workflows.messages.saveFailed": "Nie udało się zapisać",
   "workflows.messages.taskAlreadyClaimed": "Zadanie zostało już przejęte przez innego użytkownika",
   "workflows.messages.taskClaimed": "Zadanie przejęte pomyślnie",
   "workflows.messages.taskCompleted": "Zadanie ukończone pomyślnie",
@@ -913,6 +914,8 @@
   "workflows.nodeTypes.automated": "AUTOMATYCZNE",
   "workflows.nodeTypes.decision": "DECYZJA",
   "workflows.nodeTypes.end": "KONIEC",
+  "workflows.nodeTypes.parallelFork": "Rozgałęzienie równoległe",
+  "workflows.nodeTypes.parallelJoin": "Połączenie równoległe",
   "workflows.nodeTypes.start": "START",
   "workflows.nodeTypes.subWorkflow": "PODPRZEPŁYW",
   "workflows.nodeTypes.userTask": "ZADANIE UŻYTKOWNIKA",
@@ -937,6 +940,16 @@
   "workflows.orderApproval.requestApproval": "Poproś o zatwierdzenie",
   "workflows.orderApproval.startError": "Nie udało się uruchomić przepływu zatwierdzania.",
   "workflows.orderApproval.submitDecision": "Zatwierdź decyzję",
+  "workflows.parallel.branch.label": "Gałąź",
+  "workflows.parallel.branch.status.ACTIVE": "Aktywna",
+  "workflows.parallel.branch.status.CANCELLED": "Anulowana",
+  "workflows.parallel.branch.status.COMPLETED": "Zakończona",
+  "workflows.parallel.branch.status.FAILED": "Niepowodzenie",
+  "workflows.parallel.branch.status.PAUSED": "Wstrzymana",
+  "workflows.parallel.branch.status.WAITING_FOR_ACTIVITIES": "Oczekuje na aktywności",
+  "workflows.parallel.fork.label": "Rozgałęzienie równoległe",
+  "workflows.parallel.join.label": "Połączenie równoległe",
+  "workflows.parallel.validation.title": "Walidacja równoległego rozgałęzienia/połączenia nie powiodła się",
   "workflows.signals.awaiting": "Oczekiwanie na sygnał",
   "workflows.signals.correlationKey": "Klucz Korelacji",
   "workflows.signals.payload": "Zawartość Sygnału",

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

@@ -80,6 +80,9 @@ export interface ActivityContext {
   workflowContext: Record<string, any>
   stepContext?: Record<string, any>
   stepInstanceId?: string
+  // Set when the activity runs inside a parallel branch; carried on the queue
+  // payload so async resume targets the branch rather than the instance.
+  branchInstanceId?: string | null
   transitionId?: string
   userId?: string
 }
@@ -142,7 +145,7 @@ export async function enqueueActivity(
   activity: ActivityDefinition,
   context: ActivityContext
 ): Promise<string> {
-  const { workflowInstance, workflowContext, stepContext, transitionId, stepInstanceId } =
+  const { workflowInstance, workflowContext, stepContext, transitionId, stepInstanceId, branchInstanceId } =
     context
 
   // Interpolate config variables NOW (before queuing)
@@ -152,6 +155,7 @@ export async function enqueueActivity(
   const job: WorkflowActivityJob = {
     workflowInstanceId: workflowInstance.id,
     stepInstanceId,
+    branchInstanceId: branchInstanceId ?? undefined,
     transitionId,
     activityId: activity.activityId,
     activityName: activity.activityName || activity.activityType,
@@ -201,13 +205,14 @@ export async function enqueueActivity(
 export async function enqueueTimerJob(params: {
   workflowInstanceId: string
   stepInstanceId: string
+  branchInstanceId?: string | null
   tenantId: string
   organizationId: string
   userId?: string
   fireAt: string
   delayMs: number
 }): Promise<string> {
-  const { workflowInstanceId, stepInstanceId, tenantId, organizationId, userId, fireAt, delayMs } =
+  const { workflowInstanceId, stepInstanceId, branchInstanceId, tenantId, organizationId, userId, fireAt, delayMs } =
     params
 
   const queue = getActivityQueue()
@@ -216,6 +221,7 @@ export async function enqueueTimerJob(params: {
       kind: 'timer',
       workflowInstanceId,
       stepInstanceId,
+      branchInstanceId: branchInstanceId ?? undefined,
       tenantId,
       organizationId,
       userId,

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

@@ -10,6 +10,9 @@
 export interface WorkflowActivityJobBase {
   workflowInstanceId: string
   stepInstanceId?: string
+  // Set when the job belongs to a parallel branch; resume targets that branch.
+  // Absent on jobs enqueued before parallel support shipped → instance-level resume.
+  branchInstanceId?: string | null
   tenantId: string
   organizationId: string
   userId?: string

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

@@ -87,6 +87,7 @@ export type WorkflowEventType = typeof WorkflowEventTypes[keyof typeof WorkflowE
 export interface WorkflowEventInput {
   workflowInstanceId: string
   stepInstanceId?: string
+  branchInstanceId?: string | null
   eventType: WorkflowEventType | string
   eventData: any
   userId?: string
@@ -128,6 +129,7 @@ export async function logWorkflowEvent(
   const workflowEvent = em.create(WorkflowEvent, {
     workflowInstanceId: event.workflowInstanceId,
     stepInstanceId: event.stepInstanceId || null,
+    branchInstanceId: event.branchInstanceId ?? null,
     eventType: event.eventType,
     eventData: event.eventData || {},
     userId: event.userId || null,
@@ -156,6 +158,7 @@ export async function logWorkflowEvents(
     em.create(WorkflowEvent, {
       workflowInstanceId: event.workflowInstanceId,
       stepInstanceId: event.stepInstanceId || null,
+      branchInstanceId: event.branchInstanceId ?? null,
       eventType: event.eventType,
       eventData: event.eventData || {},
       userId: event.userId || null,