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

package/src/modules/workflows/lib/execution-token.ts

@@ -0,0 +1,166 @@
+/**
+ * Workflows Module - Execution Token Abstraction
+ *
+ * An execution token is the cursor the engine advances: it holds a
+ * `currentStepId`, a read/write context scope, a status, and an optional
+ * pending async transition. Today there are two kinds:
+ *
+ *  - **root token** — backed directly by the `WorkflowInstance`. Used for all
+ *    single-token (FORK-less) execution. Every accessor maps 1:1 onto the
+ *    instance fields, so the legacy single-token path is behaviourally
+ *    unchanged.
+ *  - **branch token** — backed by a `WorkflowBranchInstance` created by a
+ *    PARALLEL_FORK. The branch shares the parent instance's identity (id,
+ *    definition, tenant/org) for step-instance/event scoping, but owns its own
+ *    `currentStepId`, private context namespace, status and pending transition.
+ *
+ * The handlers operate on tokens via these functional accessors so the same
+ * step/transition logic serves both kinds.
+ */
+
+import type {
+  WorkflowInstance,
+  WorkflowBranchInstance,
+} from '../data/entities'
+
+export interface PendingTransitionState {
+  toStepId: string
+  activityResults: any[]
+  timestamp: Date
+}
+
+export type ExecutionToken =
+  | { kind: 'root'; instance: WorkflowInstance }
+  | { kind: 'branch'; instance: WorkflowInstance; branch: WorkflowBranchInstance }
+
+/** Build a root token backed by the instance (single-token execution). */
+export function rootToken(instance: WorkflowInstance): ExecutionToken {
+  return { kind: 'root', instance }
+}
+
+/** Build a branch token backed by a branch instance of the given parent. */
+export function branchToken(
+  instance: WorkflowInstance,
+  branch: WorkflowBranchInstance,
+): ExecutionToken {
+  return { kind: 'branch', instance, branch }
+}
+
+// ---------------------------------------------------------------------------
+// Identity (shared between root and branch — step instances and events are
+// always scoped to the parent WorkflowInstance, tagged with branchInstanceId).
+// ---------------------------------------------------------------------------
+
+export function tokenInstanceId(token: ExecutionToken): string {
+  return token.instance.id
+}
+
+export function tokenDefinitionId(token: ExecutionToken): string {
+  return token.instance.definitionId
+}
+
+export function tokenTenantId(token: ExecutionToken): string {
+  return token.instance.tenantId
+}
+
+export function tokenOrganizationId(token: ExecutionToken): string {
+  return token.instance.organizationId
+}
+
+/** The branch id this token represents, or null for the root token. */
+export function tokenBranchInstanceId(token: ExecutionToken): string | null {
+  return token.kind === 'branch' ? token.branch.id : null
+}
+
+// ---------------------------------------------------------------------------
+// Cursor + context
+// ---------------------------------------------------------------------------
+
+export function tokenCurrentStepId(token: ExecutionToken): string {
+  return token.kind === 'branch' ? token.branch.currentStepId : token.instance.currentStepId
+}
+
+export function setTokenCurrentStepId(token: ExecutionToken, stepId: string): void {
+  if (token.kind === 'branch') token.branch.currentStepId = stepId
+  else token.instance.currentStepId = stepId
+}
+
+/**
+ * Effective read context: for a branch this is the instance context (snapshot)
+ * overlaid with the branch's private namespace, so a branch sees fork-time
+ * instance state plus its own writes. For the root it is the instance context.
+ */
+export function tokenReadContext(token: ExecutionToken): Record<string, any> {
+  if (token.kind === 'branch') {
+    return { ...(token.instance.context || {}), ...(token.branch.contextNamespace || {}) }
+  }
+  return token.instance.context || {}
+}
+
+/**
+ * Apply context writes after a transition. The root path is identical to the
+ * legacy behaviour: merge the passed workflowContext and activity outputs into
+ * `instance.context`. A branch writes only activity outputs (and any explicit
+ * deltas the caller already folded into its namespace) into its private
+ * namespace, never the shared instance snapshot — this prevents cross-branch
+ * key collisions.
+ */
+export function applyTokenContextWrites(
+  token: ExecutionToken,
+  workflowContext: Record<string, any>,
+  activityOutputs: Record<string, any>,
+): void {
+  if (token.kind === 'branch') {
+    token.branch.contextNamespace = {
+      ...(token.branch.contextNamespace || {}),
+      ...activityOutputs,
+    }
+    return
+  }
+  token.instance.context = {
+    ...(token.instance.context || {}),
+    ...workflowContext,
+    ...activityOutputs,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Status / pause state machine
+// ---------------------------------------------------------------------------
+
+export function setTokenWaitingForActivities(token: ExecutionToken): void {
+  if (token.kind === 'branch') token.branch.status = 'WAITING_FOR_ACTIVITIES'
+  else token.instance.status = 'WAITING_FOR_ACTIVITIES'
+}
+
+export function setTokenPaused(token: ExecutionToken, at: Date): void {
+  if (token.kind === 'branch') {
+    token.branch.status = 'PAUSED'
+  } else {
+    token.instance.status = 'PAUSED'
+    token.instance.pausedAt = at
+  }
+}
+
+export function getTokenPendingTransition(token: ExecutionToken): PendingTransitionState | null {
+  return (token.kind === 'branch' ? token.branch.pendingTransition : token.instance.pendingTransition) ?? null
+}
+
+export function setTokenPendingTransition(token: ExecutionToken, pending: PendingTransitionState | null): void {
+  if (token.kind === 'branch') token.branch.pendingTransition = pending
+  else token.instance.pendingTransition = pending
+}
+
+export function touchToken(token: ExecutionToken, now: Date): void {
+  if (token.kind === 'branch') token.branch.updatedAt = now
+  else token.instance.updatedAt = now
+}
+
+/** Merge a patch into the token's own write scope (instance.context or branch namespace). */
+export function mergeTokenContext(token: ExecutionToken, patch: Record<string, any>): void {
+  if (token.kind === 'branch') {
+    token.branch.contextNamespace = { ...(token.branch.contextNamespace || {}), ...patch }
+  } else {
+    token.instance.context = { ...(token.instance.context || {}), ...patch }
+  }
+}

package/src/modules/workflows/lib/node-type-icons.ts

@@ -1,6 +1,6 @@
-import { CircleDot, CircleStop, User, Zap, Workflow, Clock, Timer, LucideIcon } from 'lucide-react'
+import { CircleDot, CircleStop, User, Zap, Workflow, Clock, Timer, Split, Merge, LucideIcon } from 'lucide-react'
 
-export type NodeType = 'start' | 'end' | 'userTask' | 'automated' | 'subWorkflow' | 'waitForSignal' | 'waitForTimer'
+export type NodeType = 'start' | 'end' | 'userTask' | 'automated' | 'subWorkflow' | 'waitForSignal' | 'waitForTimer' | 'parallelFork' | 'parallelJoin'
 
 export const NODE_TYPE_ICONS: Record<NodeType, LucideIcon> = {
   start: CircleDot,
@@ -10,6 +10,8 @@ export const NODE_TYPE_ICONS: Record<NodeType, LucideIcon> = {
   subWorkflow: Workflow,
   waitForSignal: Clock,
   waitForTimer: Timer,
+  parallelFork: Split,
+  parallelJoin: Merge,
 }
 
 export const NODE_TYPE_COLORS: Record<NodeType, string> = {
@@ -20,6 +22,9 @@ export const NODE_TYPE_COLORS: Record<NodeType, string> = {
   subWorkflow: 'text-purple-500',
   waitForSignal: 'text-purple-500',
   waitForTimer: 'text-cyan-500',
+  // New nodes use a semantic token (DS rule: no hardcoded color shades).
+  parallelFork: 'text-primary',
+  parallelJoin: 'text-primary',
 }
 
 export const NODE_TYPE_LABELS: Record<NodeType, { title: string; description: string }> = {
@@ -30,6 +35,8 @@ export const NODE_TYPE_LABELS: Record<NodeType, { title: string; description: st
   subWorkflow: { title: 'SUB-WORKFLOW', description: 'Invoke workflow' },
   waitForSignal: { title: 'WAIT FOR SIGNAL', description: 'Pause for external event' },
   waitForTimer: { title: 'WAIT FOR TIMER', description: 'Pause for a duration' },
+  parallelFork: { title: 'PARALLEL FORK', description: 'Split into parallel branches' },
+  parallelJoin: { title: 'PARALLEL JOIN', description: 'Wait for all branches' },
 }
 
 const STEP_TYPE_TO_NODE_TYPE: Record<string, NodeType> = {
@@ -40,6 +47,8 @@ const STEP_TYPE_TO_NODE_TYPE: Record<string, NodeType> = {
   SUB_WORKFLOW: 'subWorkflow',
   WAIT_FOR_SIGNAL: 'waitForSignal',
   WAIT_FOR_TIMER: 'waitForTimer',
+  PARALLEL_FORK: 'parallelFork',
+  PARALLEL_JOIN: 'parallelJoin',
 }
 
 export function stepTypeToNodeType(stepType: string): NodeType {