@open-mercato/core 0.7.1-develop.7193.1.910a5b0a1e → 0.7.1-develop.7195.1.b5efd1d51a

package/src/modules/workflows/lib/branching-routes.ts

@@ -0,0 +1,280 @@
+import type { Edge } from '@xyflow/react'
+import type { ConditionExpression, GroupCondition } from '@open-mercato/core/modules/business_rules/components/utils/conditionValidation'
+
+/**
+ * If/Else + Switch route compilation (spec
+ * 2026-07-26-workflows-ux-redesign.md section 5.8).
+ *
+ * Branching nodes are pure transition sugar: the inspectors in this module's
+ * editor never invent a storage shape. Everything an author configures becomes
+ * an ordinary outgoing transition — an inline `condition` in the business_rules
+ * expression language (or a business-rule reference through `preConditions`),
+ * plus a `priority` that makes the engine's existing highest-priority-first
+ * evaluation pick cases before the unconditioned "otherwise" route.
+ *
+ * Pure module: no React, no ORM, no DI. The only xyflow dependency is the
+ * `Edge` type.
+ */
+
+export const OTHERWISE_ROUTE_PRIORITY = 0
+export const FIRST_CASE_ROUTE_PRIORITY = 100
+export const CASE_ROUTE_PRIORITY_STEP = 10
+
+export type BranchingConditionMode = 'inline' | 'rule'
+
+export interface BranchingRouteDraft {
+  transitionId: string
+  toStepId: string
+  kind: 'case' | 'otherwise'
+  caseLabel?: string
+  caseValue?: string
+  mode: BranchingConditionMode
+  condition?: GroupCondition | null
+  ruleId?: string | null
+}
+
+export interface SwitchRoutesValue {
+  field: string
+  routes: BranchingRouteDraft[]
+}
+
+interface EdgeDataLike {
+  condition?: unknown
+  preConditions?: unknown
+  transitionName?: string
+  label?: string
+  caseLabel?: string
+  caseValue?: string
+}
+
+function edgeData(edge: Edge): EdgeDataLike {
+  return (edge.data ?? {}) as EdgeDataLike
+}
+
+function firstRuleId(preConditions: unknown): string | null {
+  if (!Array.isArray(preConditions) || preConditions.length === 0) return null
+  const [first] = preConditions
+  if (typeof first === 'string') return first
+  if (first && typeof first === 'object' && typeof (first as { ruleId?: unknown }).ruleId === 'string') {
+    return (first as { ruleId: string }).ruleId
+  }
+  return null
+}
+
+function asGroupCondition(value: unknown): GroupCondition | null {
+  if (!value || typeof value !== 'object') return null
+  const candidate = value as { operator?: unknown; rules?: unknown }
+  if (typeof candidate.operator !== 'string' || !Array.isArray(candidate.rules)) return null
+  return value as GroupCondition
+}
+
+function readCaseValue(condition: unknown): string | undefined {
+  const group = asGroupCondition(condition)
+  const rules = group ? (group.rules as ConditionExpression[]) : []
+  const [firstRule] = rules
+  if (!firstRule || typeof firstRule !== 'object') return undefined
+  const simple = firstRule as { value?: unknown }
+  if (simple.value === undefined || simple.value === null) return undefined
+  return String(simple.value)
+}
+
+function readCaseField(condition: unknown): string | undefined {
+  const group = asGroupCondition(condition)
+  const rules = group ? (group.rules as ConditionExpression[]) : []
+  const [firstRule] = rules
+  if (!firstRule || typeof firstRule !== 'object') return undefined
+  const simple = firstRule as { field?: unknown }
+  return typeof simple.field === 'string' && simple.field.length > 0 ? simple.field : undefined
+}
+
+export const BRANCHING_NODE_TYPES = ['ifElse', 'switch'] as const
+
+export type BranchingNodeType = (typeof BRANCHING_NODE_TYPES)[number]
+
+export function isBranchingNodeType(nodeType: string | undefined | null): nodeType is BranchingNodeType {
+  return typeof nodeType === 'string' && (BRANCHING_NODE_TYPES as readonly string[]).includes(nodeType)
+}
+
+export function outgoingRouteEdges(edges: Edge[], nodeId: string): Edge[] {
+  return edges.filter((edge) => edge.source === nodeId && edge.type !== 'workflowDataMapping')
+}
+
+/**
+ * Build the case condition for a Switch route: `field == value`, wrapped in the
+ * single-rule AND group the ConditionBuilder and the rule evaluator both speak.
+ */
+export function buildCaseCondition(field: string, caseValue: string): GroupCondition {
+  return {
+    operator: 'AND',
+    rules: [{ field, operator: '==', value: caseValue }],
+  }
+}
+
+/**
+ * Derive the inspector's view of a branching node's outgoing routes. A route
+ * with neither an inline condition nor a business-rule reference IS the
+ * otherwise route.
+ */
+export function readBranchingRoutes(edges: Edge[], nodeId: string): BranchingRouteDraft[] {
+  return outgoingRouteEdges(edges, nodeId).map((edge) => {
+    const data = edgeData(edge)
+    const condition = asGroupCondition(data.condition)
+    const ruleId = firstRuleId(data.preConditions)
+    const kind: BranchingRouteDraft['kind'] = condition || ruleId ? 'case' : 'otherwise'
+    return {
+      transitionId: edge.id,
+      toStepId: edge.target,
+      kind,
+      caseLabel: data.caseLabel ?? data.transitionName ?? data.label ?? undefined,
+      caseValue: data.caseValue ?? readCaseValue(data.condition),
+      mode: ruleId ? 'rule' : 'inline',
+      condition,
+      ruleId,
+    }
+  })
+}
+
+/**
+ * Infer the switched field from the first case route that carries one, so the
+ * inspector reopens on the field the author already picked.
+ */
+export function readSwitchField(edges: Edge[], nodeId: string): string {
+  for (const edge of outgoingRouteEdges(edges, nodeId)) {
+    const field = readCaseField(edgeData(edge).condition)
+    if (field) return field
+  }
+  return ''
+}
+
+/**
+ * Guarantee exactly one unconditioned otherwise route. The last route is
+ * promoted when the author has not designated one, which is what makes the
+ * otherwise route "auto-created" as soon as a branching node has routes.
+ */
+export function ensureOtherwiseRoute(routes: BranchingRouteDraft[]): BranchingRouteDraft[] {
+  if (routes.length === 0) return routes
+  // Scan from the end so a freshly connected branching node — where every
+  // route still reads as unconditioned — keeps its FIRST connection as the
+  // case route and its last as the otherwise.
+  let otherwiseIndex = -1
+  for (let index = routes.length - 1; index >= 0; index -= 1) {
+    if (routes[index].kind === 'otherwise') {
+      otherwiseIndex = index
+      break
+    }
+  }
+  const designatedIndex = otherwiseIndex >= 0 ? otherwiseIndex : routes.length - 1
+  return routes.map((route, index) =>
+    index === designatedIndex
+      ? { ...route, kind: 'otherwise', condition: null, ruleId: null, caseValue: undefined }
+      : { ...route, kind: 'case' },
+  )
+}
+
+function casePriority(caseIndex: number): number {
+  return FIRST_CASE_ROUTE_PRIORITY - caseIndex * CASE_ROUTE_PRIORITY_STEP
+}
+
+interface ApplyRoutesOptions {
+  resolveCondition: (route: BranchingRouteDraft) => GroupCondition | null
+}
+
+function applyRoutes(
+  edges: Edge[],
+  nodeId: string,
+  routes: BranchingRouteDraft[],
+  options: ApplyRoutesOptions,
+): Edge[] {
+  const normalized = ensureOtherwiseRoute(routes)
+  const byTransitionId = new Map(normalized.map((route) => [route.transitionId, route]))
+  let caseIndex = 0
+  const priorityByTransitionId = new Map<string, number>()
+  for (const route of normalized) {
+    if (route.kind === 'otherwise') {
+      priorityByTransitionId.set(route.transitionId, OTHERWISE_ROUTE_PRIORITY)
+      continue
+    }
+    priorityByTransitionId.set(route.transitionId, casePriority(caseIndex))
+    caseIndex += 1
+  }
+
+  return edges.map((edge) => {
+    if (edge.source !== nodeId) return edge
+    const route = byTransitionId.get(edge.id)
+    if (!route) return edge
+
+    const data = { ...(edge.data ?? {}) } as Record<string, unknown>
+    data.priority = priorityByTransitionId.get(route.transitionId) ?? OTHERWISE_ROUTE_PRIORITY
+
+    if (route.kind === 'otherwise') {
+      delete data.condition
+      delete data.caseValue
+      data.preConditions = []
+    } else if (route.mode === 'rule') {
+      delete data.condition
+      data.preConditions = route.ruleId ? [{ ruleId: route.ruleId, required: true }] : []
+      if (route.caseValue !== undefined) data.caseValue = route.caseValue
+    } else {
+      const condition = options.resolveCondition(route)
+      if (condition) data.condition = condition
+      else delete data.condition
+      data.preConditions = []
+      if (route.caseValue !== undefined) data.caseValue = route.caseValue
+    }
+
+    if (route.caseLabel !== undefined) {
+      data.caseLabel = route.caseLabel
+      data.transitionName = route.caseLabel
+      data.label = route.caseLabel
+    }
+
+    return { ...edge, data }
+  })
+}
+
+/**
+ * Compile If/Else inspector state onto the node's outgoing edges. Case routes
+ * keep whatever inline condition (or business-rule reference) the author chose;
+ * the otherwise route is stripped of both.
+ */
+export function applyIfElseRoutes(edges: Edge[], nodeId: string, routes: BranchingRouteDraft[]): Edge[] {
+  return applyRoutes(edges, nodeId, routes, {
+    resolveCondition: (route) => route.condition ?? null,
+  })
+}
+
+/**
+ * Compile Switch inspector state onto the node's outgoing edges: every case
+ * value becomes a generated `field == value` condition.
+ */
+export function applySwitchRoutes(edges: Edge[], nodeId: string, value: SwitchRoutesValue): Edge[] {
+  const field = value.field.trim()
+  return applyRoutes(edges, nodeId, value.routes, {
+    resolveCondition: (route) => {
+      const caseValue = (route.caseValue ?? '').trim()
+      if (!field || !caseValue) return null
+      return buildCaseCondition(field, caseValue)
+    },
+  })
+}
+
+/**
+ * Case values that appear on more than one route. Duplicates make the second
+ * route unreachable, because the engine stops at the first matching priority.
+ */
+export function collectDuplicateCaseValues(routes: BranchingRouteDraft[]): string[] {
+  const seen = new Set<string>()
+  const duplicates = new Set<string>()
+  for (const route of routes) {
+    if (route.kind !== 'case') continue
+    const caseValue = (route.caseValue ?? '').trim()
+    if (!caseValue) continue
+    if (seen.has(caseValue)) duplicates.add(caseValue)
+    else seen.add(caseValue)
+  }
+  return [...duplicates]
+}
+
+export function hasOtherwiseRoute(routes: BranchingRouteDraft[]): boolean {
+  return routes.some((route) => route.kind === 'otherwise')
+}

package/src/modules/workflows/lib/breach-routing.ts

@@ -0,0 +1,142 @@
+/**
+ * Workflows Module - SLA breach routing (pure)
+ *
+ * Resolves what happens to a run when a USER_TASK's deadline passes, from the
+ * definition alone — deliberately shaped like `lib/error-routing.ts`, which
+ * answers the same kind of question for a failed step:
+ *
+ *   1. an outgoing transition marked `kind: 'slaBreach'` wins — the canvas form
+ *      of "route the breach";
+ *   2. otherwise the step's `onBreach` action applies (`route` bound to a
+ *      durable transition id, `reassign`, or `notify`);
+ *   3. otherwise nothing routes, which is exactly today's behavior.
+ *
+ * Every fall-through is FAIL-SAFE: an `onBreach: { action: 'route' }` whose
+ * transition no longer exists on this step resolves to `none`, never to
+ * "follow whichever route happens to be valid". Auto-routing a breach would
+ * advance the run past work the author never said could be skipped — the
+ * opposite of what a deadline means.
+ *
+ * PURE: no ORM, DI, React or registry imports. Engine call sites pass the plain
+ * definition JSON.
+ */
+
+import type { TaskOnBreach } from '../data/validators'
+
+export const SLA_BREACH_TRANSITION_KIND = 'slaBreach'
+
+/**
+ * Canvas handle id a USER_TASK node exposes for its SLA-breach output, mirroring
+ * `ERROR_SOURCE_HANDLE_ID`. A connection drawn from it compiles to a transition
+ * with `kind: 'slaBreach'`.
+ */
+export const SLA_BREACH_SOURCE_HANDLE_ID = 'slaBreach'
+
+export interface BreachRoutingTransitionLike {
+  transitionId?: string
+  fromStepId?: string
+  toStepId?: string
+  kind?: string
+  priority?: number
+}
+
+export interface BreachRoutingDefinitionLike {
+  transitions?: BreachRoutingTransitionLike[]
+}
+
+export type TaskBreachHandling =
+  | { kind: 'route'; transition: BreachRoutingTransitionLike }
+  | { kind: 'reassign'; assignedTo: string | null; assignedToRoles: string[] | null }
+  | { kind: 'notify' }
+  | { kind: 'none' }
+
+/**
+ * A transition authored as the SLA-breach route. The discriminator is the same
+ * additive optional `kind` field error routes use, so every stored definition
+ * keeps its current meaning.
+ */
+export function isSlaBreachTransition(
+  transition: BreachRoutingTransitionLike | null | undefined
+): boolean {
+  return transition?.kind === SLA_BREACH_TRANSITION_KIND
+}
+
+/**
+ * SLA-breach routes must never be taken by normal routing — they are reachable
+ * only from a breach, exactly like error routes. Every routing lookup filters
+ * through this helper.
+ */
+export function excludeSlaBreachTransitions<T extends BreachRoutingTransitionLike>(
+  transitions: T[]
+): T[] {
+  return transitions.filter((transition) => !isSlaBreachTransition(transition))
+}
+
+/**
+ * Highest-priority outgoing SLA-breach route of a step. Ties keep definition
+ * order, mirroring how `findValidTransitions` orders normal routes.
+ */
+export function findSlaBreachTransition(
+  definition: BreachRoutingDefinitionLike | null | undefined,
+  stepId: string
+): BreachRoutingTransitionLike | null {
+  const candidates = (definition?.transitions ?? []).filter(
+    (transition) => transition.fromStepId === stepId && isSlaBreachTransition(transition)
+  )
+  if (candidates.length === 0) return null
+  const ordered = [...candidates].sort((left, right) => (right.priority || 0) - (left.priority || 0))
+  return ordered[0] ?? null
+}
+
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+/**
+ * The inspector's "Reassign to" field accepts a user id OR a role, which is
+ * what its placeholder promises. A UUID addresses one person (`assigned_to`
+ * holds a bare user id); anything else is a role NAME, which is the vocabulary
+ * `assigned_to_roles` has always spoken.
+ */
+export function resolveBreachReassignTarget(
+  reassignTo: string | null | undefined
+): { assignedTo: string | null; assignedToRoles: string[] | null } | null {
+  const target = typeof reassignTo === 'string' ? reassignTo.trim() : ''
+  if (!target.length) return null
+  if (UUID_PATTERN.test(target)) return { assignedTo: target, assignedToRoles: null }
+  return { assignedTo: null, assignedToRoles: [target] }
+}
+
+/**
+ * The single decision point for a breached task, in precedence order:
+ * wired SLA-breach route → the step's `onBreach` action → nothing.
+ *
+ * `none` is both the "author configured nothing" case and every malformed
+ * configuration, so a definition that predates this feature — or one whose
+ * breach route was deleted — behaves precisely as it did before.
+ */
+export function resolveTaskBreachHandling(
+  definition: BreachRoutingDefinitionLike | null | undefined,
+  stepId: string,
+  onBreach: TaskOnBreach | null | undefined
+): TaskBreachHandling {
+  const wired = findSlaBreachTransition(definition, stepId)
+  if (wired) return { kind: 'route', transition: wired }
+
+  const action = onBreach?.action
+  if (action === 'route') {
+    const bound = (definition?.transitions ?? []).find(
+      (transition) =>
+        transition.transitionId === onBreach?.transitionId &&
+        transition.fromStepId === stepId
+    )
+    return bound ? { kind: 'route', transition: bound } : { kind: 'none' }
+  }
+
+  if (action === 'reassign') {
+    const target = resolveBreachReassignTarget(onBreach?.reassignTo)
+    return target ? { kind: 'reassign', ...target } : { kind: 'none' }
+  }
+
+  if (action === 'notify') return { kind: 'notify' }
+
+  return { kind: 'none' }
+}

package/src/modules/workflows/lib/bulk-replay.ts

@@ -0,0 +1,185 @@
+/**
+ * Failure-queue bulk replay (spec §8.4) — "bulk retry/cancel runs through the
+ * progress module".
+ *
+ * The work runs in a queue worker rather than in the request, per
+ * `progress/AGENTS.md` MUST rules: replaying 500 parked instances re-executes
+ * 500 workflows, which cannot happen inside an HTTP handler and must survive
+ * the operator navigating away.
+ *
+ * One instance failing must NEVER abort the batch — that is the whole point of
+ * a triage surface. Every outcome is counted and the summary reports how many
+ * were replayed, skipped and errored.
+ */
+
+import type { AwilixContainer } from 'awilix'
+import type { EntityManager } from '@mikro-orm/core'
+import { createModuleQueue, type Queue } from '@open-mercato/queue'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { WorkflowInstance } from '../data/entities'
+import * as workflowExecutor from './workflow-executor'
+import { isRetryableRunOutcome, type WorkflowRunOutcome } from './run-outcome'
+import type { ProgressService, ProgressServiceContext } from '../../progress/lib/progressService'
+
+const logger = createLogger('workflows')
+
+export const WORKFLOW_INSTANCE_BULK_REPLAY_QUEUE = 'workflow-instance-bulk-replay'
+
+/** Bound on one batch. Larger sets are triaged by narrowing the error group. */
+export const BULK_REPLAY_MAX_IDS = 1000
+
+export type BulkReplayAction = 'retry' | 'cancel'
+
+export type BulkReplayScope = {
+  tenantId: string
+  organizationId: string
+  userId?: string | null
+}
+
+export type BulkReplayJobPayload = {
+  progressJobId: string
+  action: BulkReplayAction
+  ids: string[]
+  scope: BulkReplayScope
+}
+
+export type BulkReplaySummary = {
+  action: BulkReplayAction
+  requestedCount: number
+  affectedCount: number
+  skippedCount: number
+  failedCount: number
+}
+
+let queueInstance: Queue<Record<string, unknown>> | null = null
+
+export function getBulkReplayQueue(): Queue<Record<string, unknown>> {
+  if (!queueInstance) {
+    queueInstance = createModuleQueue<Record<string, unknown>>(WORKFLOW_INSTANCE_BULK_REPLAY_QUEUE, {
+      // Replay re-executes real workflows; one at a time keeps a bulk retry
+      // from becoming its own load spike.
+      concurrency: 1,
+    })
+  }
+  return queueInstance
+}
+
+/** Statuses each action is allowed to act on, mirroring the single-instance routes. */
+const RETRYABLE_STATUSES = new Set(['FAILED', 'PAUSED'])
+const CANCELLABLE_STATUSES = new Set(['RUNNING', 'PAUSED', 'WAITING_FOR_ACTIVITIES', 'FORKED'])
+
+/**
+ * `outcome` is optional so every existing caller keeps compiling; passing it is
+ * what makes the "a `partial_failure` is not retryable as a whole run" decision
+ * (maintainer, 2026-07-30) EXPLICIT here rather than incidental. A
+ * `partial_failure` is COMPLETED, so the status gate already refuses it — but a
+ * later widening of `RETRYABLE_STATUSES` must not silently start replaying a
+ * run whose successful half the replay would duplicate. Recovery is
+ * rerun-from-step on the specific failed step.
+ *
+ * A null outcome (still running, or a row written before outcomes existed) is
+ * never read as a refusal — only the status decides for those.
+ */
+export function canApplyBulkReplay(
+  action: BulkReplayAction,
+  status: string,
+  outcome?: WorkflowRunOutcome | null
+): boolean {
+  if (action === 'cancel') return CANCELLABLE_STATUSES.has(status)
+  if (!RETRYABLE_STATUSES.has(status)) return false
+  if (outcome != null && !isRetryableRunOutcome(outcome)) return false
+  return true
+}
+
+async function retryInstance(
+  em: EntityManager,
+  container: AwilixContainer,
+  instance: WorkflowInstance
+): Promise<void> {
+  // A parked instance carries an engine-owned attention marker; clearing it is
+  // what takes it out of the failure queue. It is deliberately cleared BEFORE
+  // execution so a replay that parks again re-marks it honestly.
+  if (instance.metadata?.attention) {
+    instance.metadata = { ...instance.metadata, attention: null }
+  }
+  instance.status = 'RUNNING'
+  instance.retryCount = (instance.retryCount || 0) + 1
+  instance.errorMessage = null
+  instance.errorDetails = null
+  instance.updatedAt = new Date()
+  await em.flush()
+
+  await workflowExecutor.executeWorkflow(em, container, instance.id)
+}
+
+export async function runBulkReplay(params: {
+  container: AwilixContainer
+  progressJobId: string
+  action: BulkReplayAction
+  ids: readonly string[]
+  scope: BulkReplayScope
+}): Promise<BulkReplaySummary> {
+  const { container, progressJobId, action, ids, scope } = params
+  const em = container.resolve('em') as EntityManager
+  const progressService = container.resolve('progressService') as ProgressService
+  const progressContext: ProgressServiceContext = {
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+    userId: scope.userId ?? null,
+  }
+
+  await progressService.startJob(progressJobId, progressContext)
+  await progressService.updateProgress(
+    progressJobId,
+    { totalCount: ids.length, processedCount: 0 },
+    progressContext
+  )
+
+  let affectedCount = 0
+  let skippedCount = 0
+  let failedCount = 0
+
+  for (const [index, instanceId] of ids.entries()) {
+    try {
+      // Re-read under the caller's tenant + organization on every iteration:
+      // an id that belongs to another tenant resolves to nothing and is
+      // skipped, never acted on.
+      const instance = await em.findOne(WorkflowInstance, {
+        id: instanceId,
+        tenantId: scope.tenantId,
+        organizationId: scope.organizationId,
+      })
+
+      if (!instance || !canApplyBulkReplay(action, instance.status, instance.outcome ?? null)) {
+        skippedCount += 1
+      } else if (action === 'retry') {
+        await retryInstance(em, container, instance)
+        affectedCount += 1
+      } else {
+        await workflowExecutor.completeWorkflow(em, container, instance.id, 'CANCELLED')
+        affectedCount += 1
+      }
+    } catch (error) {
+      // One bad instance must not abort a triage batch.
+      failedCount += 1
+      logger.error('Bulk replay failed for instance', { instanceId, action, err: error })
+    }
+
+    await progressService.updateProgress(
+      progressJobId,
+      { totalCount: ids.length, processedCount: index + 1 },
+      progressContext
+    )
+  }
+
+  const summary: BulkReplaySummary = {
+    action,
+    requestedCount: ids.length,
+    affectedCount,
+    skippedCount,
+    failedCount,
+  }
+
+  await progressService.completeJob(progressJobId, { resultSummary: summary }, progressContext)
+  return summary
+}