@open-mercato/core 0.6.5-develop.4516.1.88e6ab71a9 → 0.6.5-develop.4534.1.b459babe6d

package/src/modules/shipping_carriers/lib/status-sync.ts

@@ -2,13 +2,32 @@ import type { UnifiedShipmentStatus } from './adapter'
 import type { CarrierShipment } from '../data/entities'
 import type { ShippingEventId } from '../events'
 
+// Use Symbol.for so the marker survives module duplication across bundle
+// boundaries — production builds can split this class into separate chunks,
+// which breaks `instanceof` (see isCrudHttpError in
+// @open-mercato/shared/lib/crud/errors for the same pattern).
+const SHIPMENT_CANCEL_NOT_ALLOWED_MARKER = Symbol.for('@open-mercato/shipping_carriers/ShipmentCancelNotAllowedError')
+
 export class ShipmentCancelNotAllowedError extends Error {
+  readonly [SHIPMENT_CANCEL_NOT_ALLOWED_MARKER] = true
+
   constructor(status: string) {
     super(`Shipment cannot be cancelled in its current status: ${status}`)
     this.name = 'ShipmentCancelNotAllowedError'
   }
 }
 
+/**
+ * Type-safe check that works across module/bundle boundaries. Prefer this over
+ * `instanceof ShipmentCancelNotAllowedError` in route handlers, where the thrown
+ * error may originate from a different bundle than the one performing the check.
+ */
+export function isShipmentCancelNotAllowedError(error: unknown): error is ShipmentCancelNotAllowedError {
+  return !!error
+    && typeof error === 'object'
+    && (error as Record<symbol, unknown>)[SHIPMENT_CANCEL_NOT_ALLOWED_MARKER] === true
+}
+
 const VALID_SHIPPING_TRANSITIONS: Record<string, UnifiedShipmentStatus[]> = {
   label_created: ['picked_up', 'in_transit', 'cancelled'],
   picked_up: ['in_transit', 'cancelled'],

package/src/modules/workflows/components/NodeEditDialog.tsx

@@ -499,6 +499,8 @@ export function NodeEditDialog({ node, isOpen, onClose, onSave, onDelete }: Node
     waitForSignal: t('workflows.nodeTypes.waitForSignal'),
     waitForTimer: t('workflows.nodeTypes.waitForTimer'),
     subWorkflow: t('workflows.nodeTypes.subWorkflow'),
+    parallelFork: t('workflows.nodeTypes.parallelFork'),
+    parallelJoin: t('workflows.nodeTypes.parallelJoin'),
   }[node.type || 'automated']
 
   // START nodes are partially editable (pre-conditions only), END nodes are not editable

package/src/modules/workflows/components/WorkflowGraphImpl.tsx

@@ -19,7 +19,7 @@ import {
   ConnectionMode,
   MarkerType,
 } from '@xyflow/react'
-import {StartNode, EndNode, UserTaskNode, AutomatedNode, SubWorkflowNode, WaitForSignalNode, WaitForTimerNode} from './nodes'
+import {StartNode, EndNode, UserTaskNode, AutomatedNode, SubWorkflowNode, WaitForSignalNode, WaitForTimerNode, ParallelForkNode, ParallelJoinNode} from './nodes'
 import { WorkflowTransitionEdge } from './WorkflowTransitionEdge'
 import { STATUS_COLORS } from '../lib/status-colors'
 import { Alert, AlertDescription } from '@open-mercato/ui/primitives/alert'
@@ -133,6 +133,8 @@ export default function WorkflowGraphImpl({
       subWorkflow: SubWorkflowNode,
       waitForSignal: WaitForSignalNode,
       waitForTimer: WaitForTimerNode,
+      parallelFork: ParallelForkNode,
+      parallelJoin: ParallelJoinNode,
     }),
     []
   )

package/src/modules/workflows/components/nodes/ParallelForkNode.tsx

@@ -0,0 +1,66 @@
+'use client'
+
+import { Handle, Position, NodeProps } from '@xyflow/react'
+import { WorkflowNodeCard } from '../WorkflowNodeCard'
+import { WorkflowStatus } from '../../lib/status-colors'
+
+/**
+ * ParallelForkNode display data.
+ *
+ * A PARALLEL_FORK splits execution into N branches (one per outgoing `auto`
+ * transition) that run concurrently and converge at the paired PARALLEL_JOIN
+ * referenced by `joinStepId`.
+ */
+export interface ParallelForkNodeData {
+  label: string
+  description?: string
+  joinStepId?: string
+  status?: 'pending' | 'running' | 'completed' | 'error' | 'not_started' | 'in_progress'
+  stepNumber?: number
+  badge?: string
+  tooltip?: string
+  executionStatus?: 'completed' | 'active' | 'pending' | 'failed' | 'skipped'
+}
+
+function mapStatus(status?: string): WorkflowStatus {
+  if (!status || status === 'pending') return 'not_started'
+  if (status === 'running' || status === 'in_progress') return 'in_progress'
+  if (status === 'completed') return 'completed'
+  return 'not_started'
+}
+
+/**
+ * ParallelForkNode - splits the workflow into concurrent branches.
+ * One target handle (in); one source handle (out) that fans out to each branch.
+ */
+export function ParallelForkNode({ data, isConnectable, selected }: NodeProps) {
+  const nodeData = data as unknown as ParallelForkNodeData
+
+  return (
+    <div className="parallel-fork-node" title={nodeData.tooltip}>
+      <Handle
+        type="target"
+        position={Position.Top}
+        id="target"
+        isConnectable={isConnectable}
+        className="!w-3 !h-3 !bg-primary !border-2 !border-background"
+      />
+
+      <WorkflowNodeCard
+        title={nodeData.label}
+        description={nodeData.description}
+        status={mapStatus(nodeData.status)}
+        nodeType="parallelFork"
+        selected={selected}
+      />
+
+      <Handle
+        type="source"
+        position={Position.Bottom}
+        id="source"
+        isConnectable={isConnectable}
+        className="!w-3 !h-3 !bg-primary !border-2 !border-background"
+      />
+    </div>
+  )
+}

package/src/modules/workflows/components/nodes/ParallelJoinNode.tsx

@@ -0,0 +1,66 @@
+'use client'
+
+import { Handle, Position, NodeProps } from '@xyflow/react'
+import { WorkflowNodeCard } from '../WorkflowNodeCard'
+import { WorkflowStatus } from '../../lib/status-colors'
+
+/**
+ * ParallelJoinNode display data.
+ *
+ * A PARALLEL_JOIN synchronizes the branches created by its paired
+ * PARALLEL_FORK (`forkStepId`) using wait-all semantics, then continues the
+ * single outgoing transition once every branch has completed.
+ */
+export interface ParallelJoinNodeData {
+  label: string
+  description?: string
+  forkStepId?: string
+  status?: 'pending' | 'running' | 'completed' | 'error' | 'not_started' | 'in_progress'
+  stepNumber?: number
+  badge?: string
+  tooltip?: string
+  executionStatus?: 'completed' | 'active' | 'pending' | 'failed' | 'skipped'
+}
+
+function mapStatus(status?: string): WorkflowStatus {
+  if (!status || status === 'pending') return 'not_started'
+  if (status === 'running' || status === 'in_progress') return 'in_progress'
+  if (status === 'completed') return 'completed'
+  return 'not_started'
+}
+
+/**
+ * ParallelJoinNode - synchronizes concurrent branches (wait-all).
+ * One target handle (in) collecting all branches; one source handle (out).
+ */
+export function ParallelJoinNode({ data, isConnectable, selected }: NodeProps) {
+  const nodeData = data as unknown as ParallelJoinNodeData
+
+  return (
+    <div className="parallel-join-node" title={nodeData.tooltip}>
+      <Handle
+        type="target"
+        position={Position.Top}
+        id="target"
+        isConnectable={isConnectable}
+        className="!w-3 !h-3 !bg-primary !border-2 !border-background"
+      />
+
+      <WorkflowNodeCard
+        title={nodeData.label}
+        description={nodeData.description}
+        status={mapStatus(nodeData.status)}
+        nodeType="parallelJoin"
+        selected={selected}
+      />
+
+      <Handle
+        type="source"
+        position={Position.Bottom}
+        id="source"
+        isConnectable={isConnectable}
+        className="!w-3 !h-3 !bg-primary !border-2 !border-background"
+      />
+    </div>
+  )
+}

package/src/modules/workflows/components/nodes/index.ts

@@ -18,3 +18,9 @@ export type { WaitForSignalNodeData } from './WaitForSignalNode'
 
 export { WaitForTimerNode } from './WaitForTimerNode'
 export type { WaitForTimerNodeData } from './WaitForTimerNode'
+
+export { ParallelForkNode } from './ParallelForkNode'
+export type { ParallelForkNodeData } from './ParallelForkNode'
+
+export { ParallelJoinNode } from './ParallelJoinNode'
+export type { ParallelJoinNodeData } from './ParallelJoinNode'

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

@@ -31,6 +31,15 @@ export type WorkflowInstanceStatus =
   | 'COMPENSATING'
   | 'COMPENSATED'
   | 'WAITING_FOR_ACTIVITIES'
+  | 'FORKED'
+
+export type WorkflowBranchInstanceStatus =
+  | 'ACTIVE'
+  | 'PAUSED'
+  | 'WAITING_FOR_ACTIVITIES'
+  | 'COMPLETED'
+  | 'FAILED'
+  | 'CANCELLED'
 
 export type StepInstanceStatus =
   | 'PENDING'
@@ -275,6 +284,11 @@ export class WorkflowInstance {
     timestamp: Date
   } | null
 
+  // When the instance is FORKED, points at the open PARALLEL_FORK step whose
+  // branches are currently executing. Null for single-token instances.
+  @Property({ name: 'active_fork_step_id', type: 'varchar', length: 100, nullable: true })
+  activeForkStepId?: string | null
+
   @Property({ name: 'retry_count', type: 'integer', default: 0 })
   retryCount: number = 0
 
@@ -294,6 +308,88 @@ export class WorkflowInstance {
   deletedAt?: Date | null
 }
 
+// ============================================================================
+// Entity: WorkflowBranchInstance
+// ============================================================================
+
+/**
+ * WorkflowBranchInstance entity
+ *
+ * A single parallel branch token created by a PARALLEL_FORK step. Each branch
+ * advances independently (interleaved under the instance lock) with its own
+ * private context namespace, and converges to the paired PARALLEL_JOIN step.
+ * Branches are tenant/org scoped and never cross-tenant.
+ */
+@Entity({ tableName: 'workflow_branch_instances' })
+@Index({ name: 'workflow_branch_instances_instance_status_idx', properties: ['workflowInstanceId', 'status'] })
+@Index({ name: 'workflow_branch_instances_instance_fork_idx', properties: ['workflowInstanceId', 'forkStepId'] })
+@Index({ name: 'workflow_branch_instances_tenant_org_idx', properties: ['tenantId', 'organizationId'] })
+export class WorkflowBranchInstance {
+  [OptionalProps]?: 'createdAt' | 'updatedAt'
+
+  @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
+  id!: string
+
+  @Property({ name: 'workflow_instance_id', type: 'uuid' })
+  workflowInstanceId!: string
+
+  @Property({ name: 'fork_step_id', type: 'varchar', length: 100 })
+  forkStepId!: string
+
+  @Property({ name: 'join_step_id', type: 'varchar', length: 100 })
+  joinStepId!: string
+
+  // The transitionId of the FORK's outgoing transition that created this branch.
+  @Property({ name: 'branch_key', type: 'varchar', length: 100 })
+  branchKey!: string
+
+  // Reserved for nested-fork support (always null this iteration; validator blocks nesting).
+  @Property({ name: 'parent_branch_id', type: 'uuid', nullable: true })
+  parentBranchId?: string | null
+
+  @Property({ name: 'current_step_id', type: 'varchar', length: 100 })
+  currentStepId!: string
+
+  @Property({ name: 'status', type: 'varchar', length: 30 })
+  status!: WorkflowBranchInstanceStatus
+
+  // The branch's private write scope; merged back into instance.context at JOIN.
+  @Property({ name: 'context_namespace', type: 'jsonb' })
+  contextNamespace!: Record<string, any>
+
+  // Per-branch equivalent of WorkflowInstance.pendingTransition (async activities).
+  @Property({ name: 'pending_transition', type: 'jsonb', nullable: true })
+  pendingTransition?: {
+    toStepId: string
+    activityResults: any[]
+    timestamp: Date
+  } | null
+
+  @Property({ name: 'error_message', type: 'text', nullable: true })
+  errorMessage?: string | null
+
+  @Property({ name: 'error_details', type: 'jsonb', nullable: true })
+  errorDetails?: any | null
+
+  @Property({ name: 'started_at', type: Date, nullable: true })
+  startedAt?: Date | null
+
+  @Property({ name: 'completed_at', type: Date, nullable: true })
+  completedAt?: Date | null
+
+  @Property({ name: 'tenant_id', type: 'uuid' })
+  tenantId!: string
+
+  @Property({ name: 'organization_id', type: 'uuid' })
+  organizationId!: string
+
+  @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
+  createdAt: Date = new Date()
+
+  @Property({ name: 'updated_at', type: Date, onUpdate: () => new Date() })
+  updatedAt: Date = new Date()
+}
+
 // ============================================================================
 // Entity: StepInstance
 // ============================================================================
@@ -317,6 +413,10 @@ export class StepInstance {
   @Property({ name: 'workflow_instance_id', type: 'uuid' })
   workflowInstanceId!: string
 
+  // Set when this step executes inside a parallel branch; null for single-token.
+  @Property({ name: 'branch_instance_id', type: 'uuid', nullable: true })
+  branchInstanceId?: string | null
+
   @Property({ name: 'step_id', type: 'varchar', length: 100 })
   stepId!: string
 
@@ -390,6 +490,10 @@ export class UserTask {
   @Property({ name: 'step_instance_id', type: 'uuid' })
   stepInstanceId!: string
 
+  // Set when this task belongs to a parallel branch; null for single-token instances.
+  @Property({ name: 'branch_instance_id', type: 'uuid', nullable: true })
+  branchInstanceId?: string | null
+
   @Property({ name: 'task_name', type: 'varchar', length: 255 })
   taskName!: string
 
@@ -472,6 +576,10 @@ export class WorkflowEvent {
   @Property({ name: 'step_instance_id', type: 'uuid', nullable: true })
   stepInstanceId?: string | null
 
+  // Set when the event was logged within a parallel branch; null otherwise.
+  @Property({ name: 'branch_instance_id', type: 'uuid', nullable: true })
+  branchInstanceId?: string | null
+
   @Property({ name: 'event_type', type: 'varchar', length: 50 })
   eventType!: string
 
@@ -560,6 +668,7 @@ export class WorkflowEventTrigger {
 export default [
   WorkflowDefinition,
   WorkflowInstance,
+  WorkflowBranchInstance,
   StepInstance,
   UserTask,
   WorkflowEvent,

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/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

@@ -913,6 +913,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 +939,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

@@ -913,6 +913,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 +939,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",