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

package/src/modules/workflows/api/definitions/[id]/route.ts

@@ -21,6 +21,21 @@ import {
 import { serializeWorkflowDefinition, serializeCodeWorkflowDefinition } from '../serialize'
 import { invalidateTriggerCache } from '../../../lib/event-trigger-service'
 import { getCodeWorkflow } from '../../../lib/code-registry'
+import { createGenericOptimisticLockReader } from '@open-mercato/shared/lib/crud/optimistic-lock'
+import { registerOptimisticLockReaderIfAbsent } from '@open-mercato/shared/lib/crud/optimistic-lock-store'
+import { validateCrudMutationGuard, runCrudMutationGuardAfterSuccess } from '@open-mercato/shared/lib/crud/mutation-guard'
+import { enforceCommandOptimisticLock } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
+import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+
+registerOptimisticLockReaderIfAbsent({
+  'workflows.definition': createGenericOptimisticLockReader({
+    entity: WorkflowDefinition,
+    idField: 'id',
+    tenantField: 'tenantId',
+    orgField: 'organizationId',
+    softDeleteField: 'deletedAt',
+  }),
+})
 
 export const metadata = {
   requireAuth: true,
@@ -151,6 +166,20 @@ export async function PUT(
     }
 
     const input: UpdateWorkflowDefinitionApiInput = validation.data
+    const guardResult = await validateCrudMutationGuard(container, {
+      tenantId: tenantId ?? '',
+      organizationId: organizationId ?? null,
+      userId: auth.sub ?? '',
+      resourceKind: 'workflows.definition',
+      resourceId: params.id,
+      operation: 'update',
+      requestMethod: 'PUT',
+      requestHeaders: request.headers,
+      mutationPayload: input as Record<string, unknown>,
+    })
+    if (guardResult && !guardResult.ok) {
+      return NextResponse.json(guardResult.body, { status: guardResult.status })
+    }
 
     // Handle customizing a code-based workflow definition
     if (params.id.startsWith('code:')) {
@@ -171,6 +200,19 @@ export async function PUT(
 
       let savedOverride: WorkflowDefinition
       if (existingOverride) {
+        try {
+          enforceCommandOptimisticLock({
+            resourceKind: 'workflows.definition',
+            resourceId: existingOverride.id,
+            current: existingOverride.updatedAt ?? null,
+            request,
+          })
+        } catch (lockError) {
+          if (isCrudHttpError(lockError)) {
+            return NextResponse.json(lockError.body, { status: lockError.status })
+          }
+          throw lockError
+        }
         // Revive if soft-deleted, then apply updates
         existingOverride.deletedAt = null
         existingOverride.workflowName = codeDef.workflowName
@@ -230,6 +272,20 @@ export async function PUT(
         console.error('Failed to emit workflows.definition.customized event:', eventError)
       }
 
+      if (guardResult?.shouldRunAfterSuccess) {
+        await runCrudMutationGuardAfterSuccess(container, {
+          tenantId: tenantId ?? '',
+          organizationId: organizationId ?? null,
+          userId: auth.sub ?? '',
+          resourceKind: 'workflows.definition',
+          resourceId: String(savedOverride.id),
+          operation: 'update',
+          requestMethod: 'PUT',
+          requestHeaders: request.headers,
+          metadata: guardResult.metadata,
+        })
+      }
+
       return NextResponse.json({
         data: serializeWorkflowDefinition(savedOverride),
         message: 'Workflow definition customized successfully',
@@ -251,6 +307,20 @@ export async function PUT(
       )
     }
 
+    try {
+      enforceCommandOptimisticLock({
+        resourceKind: 'workflows.definition',
+        resourceId: definition.id,
+        current: definition.updatedAt ?? null,
+        request,
+      })
+    } catch (lockError) {
+      if (isCrudHttpError(lockError)) {
+        return NextResponse.json(lockError.body, { status: lockError.status })
+      }
+      throw lockError
+    }
+
     // Update fields. workflowId is intentionally ignored — it identifies the
     // row and renaming would break references. Version is user-managed and
     // applied when supplied so the edit form can bump it explicitly.
@@ -283,6 +353,20 @@ export async function PUT(
 
     await em.flush()
 
+    if (guardResult?.shouldRunAfterSuccess) {
+      await runCrudMutationGuardAfterSuccess(container, {
+        tenantId: tenantId ?? '',
+        organizationId: organizationId ?? null,
+        userId: auth.sub ?? '',
+        resourceKind: 'workflows.definition',
+        resourceId: String(definition.id),
+        operation: 'update',
+        requestMethod: 'PUT',
+        requestHeaders: request.headers,
+        metadata: guardResult.metadata,
+      })
+    }
+
     // Embedded triggers may have changed; invalidate the in-memory cache so
     // the wildcard event subscriber reloads them on the next event.
     if (tenantId) invalidateTriggerCache(tenantId, organizationId ?? undefined)
@@ -356,6 +440,20 @@ export async function DELETE(
       )
     }
 
+    const guardResult = await validateCrudMutationGuard(container, {
+      tenantId: tenantId ?? '',
+      organizationId: organizationId ?? null,
+      userId: auth.sub ?? '',
+      resourceKind: 'workflows.definition',
+      resourceId: params.id,
+      operation: 'delete',
+      requestMethod: 'DELETE',
+      requestHeaders: request.headers,
+    })
+    if (guardResult && !guardResult.ok) {
+      return NextResponse.json(guardResult.body, { status: guardResult.status })
+    }
+
     // Check if there are active workflow instances using this definition
     const { WorkflowInstance } = await import('../../../data/entities')
     const activeInstances = await em.count(WorkflowInstance, {
@@ -378,6 +476,20 @@ export async function DELETE(
 
     await em.flush()
 
+    if (guardResult?.shouldRunAfterSuccess) {
+      await runCrudMutationGuardAfterSuccess(container, {
+        tenantId: tenantId ?? '',
+        organizationId: organizationId ?? null,
+        userId: auth.sub ?? '',
+        resourceKind: 'workflows.definition',
+        resourceId: String(definition.id),
+        operation: 'delete',
+        requestMethod: 'DELETE',
+        requestHeaders: request.headers,
+        metadata: guardResult.metadata,
+      })
+    }
+
     if (tenantId) invalidateTriggerCache(tenantId, organizationId ?? undefined)
 
     return NextResponse.json({

package/src/modules/workflows/backend/definitions/[id]/page.tsx

@@ -8,8 +8,9 @@ import { CrudForm } from '@open-mercato/ui/backend/CrudForm'
 import { Spinner } from '@open-mercato/ui/primitives/spinner'
 import { Button } from '@open-mercato/ui/primitives/button'
 import { Alert, AlertDescription } from '@open-mercato/ui/primitives/alert'
+import { apiFetch, withScopedApiHeaders } from '@open-mercato/ui/backend/utils/api'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
 import { ErrorMessage, RecordNotFoundState } from '@open-mercato/ui/backend/detail'
-import { apiFetch } from '@open-mercato/ui/backend/utils/api'
 import { readJsonSafe } from '@open-mercato/ui/backend/utils/serverErrors'
 import { formatWorkflowValidationError } from '../../../lib/format-validation-error'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
@@ -95,17 +96,32 @@ export default function EditWorkflowDefinitionPage() {
 
   const handleSubmit = async (values: WorkflowDefinitionFormValues) => {
     const payload = buildWorkflowPayload({ ...values, triggers })
+    const optimisticLockHeader = buildOptimisticLockHeader(
+      typeof definition?.updatedAt === 'string' ? definition.updatedAt : null,
+    )
 
     await runMutation({
       operation: async () => {
-        const response = await apiFetch(`/api/workflows/definitions/${definitionId}`, {
+        const updateDefinition = () => apiFetch(`/api/workflows/definitions/${definitionId}`, {
           method: 'PUT',
           headers: { 'Content-Type': 'application/json' },
           body: JSON.stringify(payload),
         })
+        const response = Object.keys(optimisticLockHeader).length > 0
+          ? await withScopedApiHeaders(optimisticLockHeader, updateDefinition)
+          : await updateDefinition()
         if (!response.ok) {
-          const errorBody = await readJsonSafe<{ error?: string; details?: Array<{ path?: Array<string | number>; message?: string }> }>(response, null)
-          throw new Error(formatWorkflowValidationError(errorBody, t('workflows.errors.updateFailed')))
+          const errorBody = await readJsonSafe<{
+            error?: string
+            code?: string
+            currentUpdatedAt?: string
+            expectedUpdatedAt?: string
+            details?: Array<{ path?: Array<string | number>; message?: string }>
+          }>(response, null)
+          throw Object.assign(
+            new Error(formatWorkflowValidationError(errorBody, t('workflows.errors.updateFailed'))),
+            { status: response.status, ...(errorBody ?? {}) },
+          )
         }
         return response
       },

package/src/modules/workflows/backend/definitions/page.tsx

@@ -18,11 +18,14 @@ import {
   DialogHeader,
   DialogTitle,
 } from '@open-mercato/ui/primitives/dialog'
-import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+import { apiCall, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
+import { surfaceRecordConflict } from '@open-mercato/ui/backend/conflicts'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { useQuery, useQueryClient } from '@tanstack/react-query'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import type { FilterDef, FilterValues } from '@open-mercato/ui/backend/FilterBar'
+import { ListEmptyState } from '@open-mercato/ui/backend/filters/ListEmptyState'
 import { Trash2 } from 'lucide-react'
 
 type WorkflowDefinitionSource = 'code' | 'code_override' | 'user'
@@ -86,7 +89,7 @@ export default function WorkflowDefinitionsListPage() {
   const router = useRouter()
   const queryClient = useQueryClient()
   const [filterValues, setFilterValues] = React.useState<FilterValues>({})
-  const [deleteTarget, setDeleteTarget] = React.useState<{ id: string; name: string } | null>(null)
+  const [deleteTarget, setDeleteTarget] = React.useState<{ id: string; name: string; updatedAt: string | null } | null>(null)
 
   const { data, isLoading, error } = useQuery({
     queryKey: ['workflow-definitions', 'list', filterValues, page],
@@ -121,22 +124,31 @@ export default function WorkflowDefinitionsListPage() {
     },
   })
 
-  const handleDelete = (id: string, workflowName: string) => {
-    setDeleteTarget({ id, name: workflowName })
+  const handleDelete = (id: string, workflowName: string, updatedAt: string | null) => {
+    setDeleteTarget({ id, name: workflowName, updatedAt })
   }
 
   const confirmDelete = async () => {
     if (!deleteTarget) return
 
-    const result = await apiCall(`/api/workflows/definitions/${deleteTarget.id}`, {
-      method: 'DELETE',
-    })
+    const result = await withScopedApiRequestHeaders(
+      buildOptimisticLockHeader(deleteTarget.updatedAt),
+      () => apiCall(`/api/workflows/definitions/${deleteTarget.id}`, {
+        method: 'DELETE',
+      }),
+    )
 
     if (result.ok) {
       flash(t('workflows.messages.deleted'), 'success')
       queryClient.invalidateQueries({ queryKey: ['workflow-definitions'] })
     } else {
-      flash(t('workflows.messages.deleteFailed'), 'error')
+      const conflictError = Object.assign(new Error(t('workflows.messages.deleteFailed')), {
+        status: result.status,
+        ...(result.result && typeof result.result === 'object' ? result.result : {}),
+      })
+      if (!surfaceRecordConflict(conflictError, t)) {
+        flash(t('workflows.messages.deleteFailed'), 'error')
+      }
     }
     setDeleteTarget(null)
   }
@@ -255,12 +267,12 @@ export default function WorkflowDefinitionsListPage() {
             )}
           </div>
           {row.original.description && (
-            <div className="text-xs text-gray-500">
+            <div className="text-xs text-muted-foreground">
               {row.original.description}
             </div>
           )}
           {row.original.metadata?.category && (
-            <div className="text-xs text-gray-400 mt-0.5">
+            <div className="text-xs text-muted-foreground mt-0.5">
               {row.original.metadata.category}
             </div>
           )}
@@ -287,8 +299,8 @@ export default function WorkflowDefinitionsListPage() {
           onClick={() => handleToggleEnabled(row.original.id, row.original.enabled)}
           className={`inline-flex items-center px-2 py-1 rounded text-xs font-medium cursor-pointer ${
             row.original.enabled
-              ? 'bg-green-100 text-green-800 hover:bg-green-200'
-              : 'bg-gray-100 text-gray-600 hover:bg-gray-200'
+              ? 'bg-status-success-bg text-status-success-text hover:bg-status-success-border'
+              : 'bg-status-neutral-bg text-status-neutral-text hover:bg-status-neutral-border'
           }`}
           title={t('workflows.actions.toggleEnabled')}
         >
@@ -301,7 +313,7 @@ export default function WorkflowDefinitionsListPage() {
       header: t('workflows.fields.tags'),
       cell: ({ row }) => {
         const tags = row.original.metadata?.tags || []
-        if (tags.length === 0) return <span className="text-gray-400">-</span>
+        if (tags.length === 0) return <span className="text-muted-foreground">-</span>
         return (
           <div className="flex flex-wrap gap-1">
             {tags.slice(0, 2).map((tag, idx) => (
@@ -322,7 +334,7 @@ export default function WorkflowDefinitionsListPage() {
       accessorKey: 'createdAt',
       cell: ({ row }) => {
         const date = new Date(row.original.createdAt)
-        return <span className="text-sm text-gray-600">{date.toLocaleDateString()}</span>
+        return <span className="text-sm text-muted-foreground">{date.toLocaleDateString()}</span>
       },
     },
     {
@@ -354,7 +366,7 @@ export default function WorkflowDefinitionsListPage() {
           ...(!isCodeOnly ? [{
             id: 'delete',
             label: t('common.delete'),
-            onSelect: () => handleDelete(row.original.id, row.original.workflowName),
+            onSelect: () => handleDelete(row.original.id, row.original.workflowName, row.original.updatedAt),
             destructive: true,
           }] : []),
         ]
@@ -410,6 +422,13 @@ export default function WorkflowDefinitionsListPage() {
           perspective={{
             tableId: 'workflows.definitions.list',
           }}
+          emptyState={(
+            <ListEmptyState
+              entityName={t('workflows.list.title')}
+              createHref="/backend/definitions/create"
+              createLabel={t('workflows.actions.create')}
+            />
+          )}
           pagination={{ page, pageSize, total, totalPages, onPageChange: setPage }}
         />
         <Dialog open={!!deleteTarget} onOpenChange={(open) => !open && setDeleteTarget(null)}>

package/src/modules/workflows/backend/definitions/visual-editor/page.tsx

@@ -32,7 +32,9 @@ import { Alert, AlertTitle } from '@open-mercato/ui/primitives/alert'
 import { useConfirmDialog } from '@open-mercato/ui/backend/confirm-dialog'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import { FormHeader } from '@open-mercato/ui/backend/forms'
-import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+import { apiCall, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
+import { surfaceRecordConflict } from '@open-mercato/ui/backend/conflicts'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { CircleQuestionMark, Info, PanelTopClose, PanelTopOpen, Play, Save, Trash2 } from 'lucide-react'
 import { NODE_TYPE_ICONS, NODE_TYPE_COLORS, NODE_TYPE_LABELS } from '../../../lib/node-type-icons'
@@ -107,6 +109,7 @@ export default function VisualEditorPage() {
   const [effectiveTo, setEffectiveTo] = useState('')
   const [triggers, setTriggers] = useState<WorkflowDefinitionTrigger[]>([])
   const [source, setSource] = useState<'code' | 'code_override' | 'user' | null>(null)
+  const [updatedAt, setUpdatedAt] = useState<string | null>(null)
 
   const isCodeOnly = source === 'code'
   const isCodeOverride = source === 'code_override'
@@ -154,6 +157,7 @@ export default function VisualEditorPage() {
         // code → read-only with Customize button; code_override → editable
         // with Reset to code; user → editable, no banner.
         setSource((definition.source as 'code' | 'code_override' | 'user') ?? null)
+        setUpdatedAt(typeof definition.updatedAt === 'string' ? definition.updatedAt : null)
       } catch (error) {
         console.error('Error loading workflow definition:', error)
         flash('Failed to load workflow definition', 'error')
@@ -372,20 +376,23 @@ export default function VisualEditorPage() {
         // edits (name, description, version, category, tags, icon, effective
         // dates) actually persist. Previously only `definition` + `enabled`
         // were sent, silently dropping every other field.
-        result = await apiCall<{ data: any; error?: string }>(`/api/workflows/definitions/${definitionId}`, {
-          method: 'PUT',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({
-            workflowName,
-            description: description || null,
-            version,
-            definition: definitionData,
-            metadata: Object.keys(metadata).length > 0 ? metadata : null,
-            enabled,
-            effectiveFrom: effectiveFrom || null,
-            effectiveTo: effectiveTo || null,
+        result = await withScopedApiRequestHeaders(
+          buildOptimisticLockHeader(updatedAt),
+          () => apiCall<{ data: any; error?: string }>(`/api/workflows/definitions/${definitionId}`, {
+            method: 'PUT',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+              workflowName,
+              description: description || null,
+              version,
+              definition: definitionData,
+              metadata: Object.keys(metadata).length > 0 ? metadata : null,
+              enabled,
+              effectiveFrom: effectiveFrom || null,
+              effectiveTo: effectiveTo || null,
+            }),
           }),
-        })
+        )
       } else {
         // Create new definition
         result = await apiCall<{ data: any; error?: string }>('/api/workflows/definitions', {
@@ -406,7 +413,13 @@ export default function VisualEditorPage() {
       }
 
       if (!result.ok) {
-        flash(`Failed to save: ${result.result?.error || 'Unknown error'}`, 'error')
+        const conflictError = Object.assign(new Error(t('workflows.messages.saveFailed', 'Failed to save')), {
+          status: result.status,
+          ...(result.result && typeof result.result === 'object' ? result.result : {}),
+        })
+        if (!surfaceRecordConflict(conflictError, t)) {
+          flash(`Failed to save: ${result.result?.error || 'Unknown error'}`, 'error')
+        }
         return
       }
 
@@ -425,7 +438,7 @@ export default function VisualEditorPage() {
     } finally {
       setIsSaving(false)
     }
-  }, [nodes, edges, workflowId, workflowName, description, version, enabled, category, tags, icon, effectiveFrom, effectiveTo, triggers, definitionId, router])
+  }, [nodes, edges, workflowId, workflowName, description, version, enabled, category, tags, icon, effectiveFrom, effectiveTo, triggers, definitionId, updatedAt, router])
 
   // Customize a code-defined workflow → creates an override and reloads the
   // editor pointed at the new UUID. Mirrors the non-visual edit page button.

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/formConfig.tsx

@@ -17,14 +17,19 @@ export type WorkflowDefinitionFormValues = {
   enabled: boolean
   effectiveFrom?: string | null
   effectiveTo?: string | null
-  metadata?: {
-    tags?: string[]
-    category?: string
-    icon?: string
-  } | null
+  // Metadata fields are declared on the form with dot-path ids
+  // (`metadata.category`, `metadata.tags`, `metadata.icon`). CrudForm only
+  // collapses dot-paths for injected/custom fields, so declared base fields are
+  // carried as flat keys end-to-end; buildWorkflowPayload reassembles them into
+  // the nested metadata object the API expects. See issue #2503.
+  'metadata.category'?: string
+  'metadata.tags'?: string[]
+  'metadata.icon'?: string
   steps: any[]
   transitions: any[]
   triggers: WorkflowDefinitionTrigger[]
+  id?: string
+  updatedAt?: string | null
 }
 
 /**
@@ -47,11 +52,11 @@ export const workflowDefinitionFormSchema = z.object({
   enabled: z.boolean(),
   effectiveFrom: z.string().optional().nullable(),
   effectiveTo: z.string().optional().nullable(),
-  metadata: z.object({
-    tags: z.array(z.string()).optional(),
-    category: z.string().max(50).optional(),
-    icon: z.string().max(50).optional(),
-  }).optional().nullable(),
+  // Flat dot-path keys mirror the field ids so CrudForm's non-strict
+  // schema.safeParse keeps them instead of stripping them before onSubmit.
+  'metadata.category': z.string().max(50).optional(),
+  'metadata.tags': z.array(z.string()).optional(),
+  'metadata.icon': z.string().max(50).optional(),
   steps: z.array(z.any()),
   transitions: z.array(z.any()),
   triggers: z.array(z.any()).default([]),
@@ -68,11 +73,9 @@ export const defaultFormValues: WorkflowDefinitionFormValues = {
   enabled: true,
   effectiveFrom: null,
   effectiveTo: null,
-  metadata: {
-    tags: [],
-    category: '',
-    icon: '',
-  },
+  'metadata.category': '',
+  'metadata.tags': [],
+  'metadata.icon': '',
   steps: [],
   transitions: [],
   triggers: [],
@@ -234,6 +237,8 @@ import { toDateInputValue } from '@open-mercato/shared/lib/date/format'
  * Parse workflow definition to form values
  */
 export function parseWorkflowToFormValues(workflow: any): WorkflowDefinitionFormValues {
+  const updatedAt = workflow.updatedAt ?? workflow.updated_at ?? null
+  const metadata = workflow.metadata || {}
   return {
     workflowId: workflow.workflowId || '',
     workflowName: workflow.workflowName || '',
@@ -242,10 +247,15 @@ export function parseWorkflowToFormValues(workflow: any): WorkflowDefinitionForm
     enabled: workflow.enabled ?? true,
     effectiveFrom: toDateInputValue(workflow.effectiveFrom),
     effectiveTo: toDateInputValue(workflow.effectiveTo),
-    metadata: workflow.metadata || { tags: [], category: '', icon: '' },
+    // Hydrate the flat dot-path keys the CrudForm inputs actually read.
+    'metadata.category': metadata.category || '',
+    'metadata.tags': Array.isArray(metadata.tags) ? metadata.tags : [],
+    'metadata.icon': metadata.icon || '',
     steps: workflow.definition?.steps || [],
     transitions: workflow.definition?.transitions || [],
     triggers: workflow.definition?.triggers || [],
+    id: workflow.id,
+    updatedAt: typeof updatedAt === 'string' ? updatedAt : updatedAt ? String(updatedAt) : null,
   }
 }
 
@@ -254,6 +264,16 @@ export function parseWorkflowToFormValues(workflow: any): WorkflowDefinitionForm
  */
 export function buildWorkflowPayload(values: WorkflowDefinitionFormValues) {
   const triggers = values.triggers ?? []
+  // Collapse the flat dot-path keys back into the nested metadata object the API
+  // expects. Empty category/icon are dropped so they don't persist as blanks.
+  const category = (values['metadata.category'] || '').trim()
+  const icon = (values['metadata.icon'] || '').trim()
+  const tags = Array.isArray(values['metadata.tags']) ? values['metadata.tags'] : []
+  const metadata = {
+    tags,
+    ...(category ? { category } : {}),
+    ...(icon ? { icon } : {}),
+  }
   return {
     workflowId: values.workflowId,
     workflowName: values.workflowName,
@@ -262,7 +282,7 @@ export function buildWorkflowPayload(values: WorkflowDefinitionFormValues) {
     enabled: values.enabled,
     effectiveFrom: values.effectiveFrom || null,
     effectiveTo: values.effectiveTo || null,
-    metadata: values.metadata || null,
+    metadata,
     definition: {
       steps: values.steps,
       transitions: values.transitions,

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>
+  )
+}