@open-mercato/core 0.7.1-develop.7193.1.910a5b0a1e → 0.7.1-develop.7194.1.ab4fc81f82

package/src/modules/workflows/lib/endpoint-catalog.ts

@@ -0,0 +1,283 @@
+/**
+ * Workflows Module - in-process endpoint catalog (issue #4235, spec
+ * 2026-07-26-workflows-ux-redesign.md section 5.3).
+ *
+ * Builds a trimmed index of the platform's API surface from the SAME inputs
+ * the docs route uses — the registered module list plus the API route
+ * manifests — via `attachOpenApiDocsToModules` + `buildOpenApiDocument`. The
+ * projection keeps only what the endpoint picker and the CALL_API output
+ * contract need: path, method, summary, tag, parameter descriptors, and the
+ * declared request/response JSON schemas. Undeclared responses (the
+ * generator's advisory `Schema not declared` fallback) are omitted so
+ * consumers degrade honestly to `unknown` instead of trusting a placeholder.
+ *
+ * Server-only: assembling the catalog loads every route module through the
+ * manifests (exactly what the docs route pays), so the result is cached per
+ * process. Paths are exposed with the `/api` prefix to match what CALL_API
+ * `endpoint` config values look like (`buildApiUrl` only accepts `/api/*`).
+ */
+
+import { ZodType } from 'zod'
+import type { ZodTypeAny } from 'zod'
+import type { Module } from '@open-mercato/shared/modules/registry'
+import { getApiRouteManifests } from '@open-mercato/shared/modules/registry'
+import { getModules } from '@open-mercato/shared/lib/modules/registry'
+import { attachOpenApiDocsToModules, buildOpenApiDocument } from '@open-mercato/shared/lib/openapi'
+import type { OpenApiMethodDoc, OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { findMatchingEndpoint } from './endpoint-path'
+
+export type WorkflowEndpointParamLocation = 'path' | 'query' | 'header'
+
+export interface WorkflowEndpointParam {
+  name: string
+  in: WorkflowEndpointParamLocation
+  required: boolean
+  type: string
+}
+
+export interface WorkflowEndpointDescriptor {
+  path: string
+  method: string
+  summary: string
+  tag: string
+  params: WorkflowEndpointParam[]
+  hasRequestSchema: boolean
+  requestSchema?: Record<string, unknown>
+  responseSchema?: Record<string, unknown>
+}
+
+export interface WorkflowEndpointCatalog {
+  items: WorkflowEndpointDescriptor[]
+}
+
+const METHOD_ORDER = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'] as const
+
+const PARAM_LOCATIONS = new Set<WorkflowEndpointParamLocation>(['path', 'query', 'header'])
+
+const UNDECLARED_RESPONSE_DESCRIPTION = 'Schema not declared'
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function methodRank(method: string): number {
+  const index = METHOD_ORDER.indexOf(method as (typeof METHOD_ORDER)[number])
+  return index === -1 ? METHOD_ORDER.length : index
+}
+
+function compareEndpoints(left: WorkflowEndpointDescriptor, right: WorkflowEndpointDescriptor): number {
+  const byPath = left.path.localeCompare(right.path)
+  if (byPath !== 0) return byPath
+  return methodRank(left.method) - methodRank(right.method)
+}
+
+function schemaTypeOf(schema: unknown): string {
+  if (!isRecord(schema)) return 'unknown'
+  if (typeof schema.type === 'string' && schema.type.length > 0) return schema.type
+  return 'unknown'
+}
+
+function projectParams(parameters: unknown): WorkflowEndpointParam[] {
+  if (!Array.isArray(parameters)) return []
+  const params: WorkflowEndpointParam[] = []
+  for (const parameter of parameters) {
+    if (!isRecord(parameter)) continue
+    const name = parameter.name
+    const location = parameter.in
+    if (typeof name !== 'string' || name.length === 0) continue
+    if (typeof location !== 'string' || !PARAM_LOCATIONS.has(location as WorkflowEndpointParamLocation)) continue
+    params.push({
+      name,
+      in: location as WorkflowEndpointParamLocation,
+      required: parameter.required === true,
+      type: schemaTypeOf(parameter.schema),
+    })
+  }
+  return params
+}
+
+function jsonContentSchema(container: unknown): Record<string, unknown> | undefined {
+  if (!isRecord(container)) return undefined
+  const content = container.content
+  if (!isRecord(content)) return undefined
+  const jsonEntry = content['application/json']
+  if (!isRecord(jsonEntry)) return undefined
+  const schema = jsonEntry.schema
+  if (!isRecord(schema) || Object.keys(schema).length === 0) return undefined
+  return schema
+}
+
+function isDeclaredResponseSchema(schema: Record<string, unknown>): boolean {
+  if (schema.description !== UNDECLARED_RESPONSE_DESCRIPTION) return true
+  if (isRecord(schema.properties) && Object.keys(schema.properties).length > 0) return true
+  return schema.type !== 'object'
+}
+
+function projectSuccessResponseSchema(responses: unknown): Record<string, unknown> | undefined {
+  if (!isRecord(responses)) return undefined
+  const successStatuses = Object.keys(responses)
+    .map((status) => Number.parseInt(status, 10))
+    .filter((status) => Number.isInteger(status) && status >= 200 && status < 300)
+    .sort((left, right) => left - right)
+  for (const status of successStatuses) {
+    const schema = jsonContentSchema(responses[String(status)])
+    if (schema && isDeclaredResponseSchema(schema)) return schema
+  }
+  return undefined
+}
+
+export function buildEndpointCatalog(modules: Module[]): WorkflowEndpointCatalog {
+  const doc = buildOpenApiDocument(modules)
+  const items: WorkflowEndpointDescriptor[] = []
+  for (const [docPath, operations] of Object.entries(doc.paths)) {
+    if (!isRecord(operations)) continue
+    for (const [methodLower, operation] of Object.entries(operations)) {
+      const method = methodLower.toUpperCase()
+      if (methodRank(method) === METHOD_ORDER.length) continue
+      if (!isRecord(operation)) continue
+      const requestSchema = jsonContentSchema(operation.requestBody)
+      const responseSchema = projectSuccessResponseSchema(operation.responses)
+      const tags = operation.tags
+      items.push({
+        path: `/api${docPath}`,
+        method,
+        summary:
+          typeof operation.summary === 'string' && operation.summary.length > 0
+            ? operation.summary
+            : `${method} /api${docPath}`,
+        tag: Array.isArray(tags) && typeof tags[0] === 'string' ? tags[0] : '',
+        params: projectParams(operation.parameters),
+        hasRequestSchema: requestSchema !== undefined,
+        ...(requestSchema !== undefined ? { requestSchema } : {}),
+        ...(responseSchema !== undefined ? { responseSchema } : {}),
+      })
+    }
+  }
+  items.sort(compareEndpoints)
+  return { items }
+}
+
+interface EndpointResponseSchemaEntry {
+  path: string
+  method: string
+  schema: ZodTypeAny | null
+}
+
+function normalizeDocPath(path: string): string {
+  const segments = path
+    .split('/')
+    .filter((segment) => segment.length > 0)
+    .map((segment) => {
+      const optionalCatchAll = segment.match(/^\[\[\.\.\.(.+)\]\]$/)
+      if (optionalCatchAll) return `{${optionalCatchAll[1]}}`
+      const catchAll = segment.match(/^\[\.\.\.(.+)\]$/)
+      if (catchAll) return `{${catchAll[1]}}`
+      const dynamic = segment.match(/^\[(.+)\]$/)
+      if (dynamic) return `{${dynamic[1]}}`
+      return segment
+    })
+  return `/${segments.join('/')}`
+}
+
+function successResponseZodSchema(methodDoc: OpenApiMethodDoc | undefined): ZodTypeAny | null {
+  if (!methodDoc || !Array.isArray(methodDoc.responses)) return null
+  const declaredSuccesses = methodDoc.responses
+    .filter(
+      (response) =>
+        typeof response?.status === 'number' &&
+        response.status >= 200 &&
+        response.status < 300 &&
+        response.schema instanceof ZodType,
+    )
+    .sort((left, right) => left.status - right.status)
+  const schema = declaredSuccesses[0]?.schema
+  return schema instanceof ZodType ? schema : null
+}
+
+/**
+ * Index of the endpoint surface with each endpoint's declared zod success
+ * response schema (or null when none is declared), built from the SAME
+ * attached route docs the catalog projection reads. Every endpoint is
+ * indexed — not only those with schemas — so a literal route always wins the
+ * match over a sibling `{param}` template instead of borrowing its schema.
+ * Schemas stay zod (not JSON schema) so the CALL_API output contract can
+ * feed `flattenSchemaToContract` through the existing `resolveOutputContract`
+ * seam.
+ */
+function buildResponseSchemaIndex(modules: Module[]): EndpointResponseSchemaEntry[] {
+  const entries: EndpointResponseSchemaEntry[] = []
+  for (const moduleEntry of modules) {
+    for (const api of moduleEntry.apis ?? []) {
+      const rawPath = (api as { path?: unknown }).path
+      if (typeof rawPath !== 'string' || rawPath.length === 0) continue
+      const path = `/api${normalizeDocPath(rawPath)}`
+      if ('handlers' in api) {
+        const handlers = (api as { handlers?: Record<string, unknown> }).handlers ?? {}
+        const docs = (api as { docs?: OpenApiRouteDoc }).docs
+        for (const method of METHOD_ORDER) {
+          if (typeof handlers[method] !== 'function') continue
+          entries.push({ path, method, schema: successResponseZodSchema(docs?.methods?.[method]) })
+        }
+        continue
+      }
+      const legacyMethod = (api as { method?: unknown }).method
+      if (typeof legacyMethod !== 'string' || legacyMethod.length === 0) continue
+      entries.push({
+        path,
+        method: legacyMethod.toUpperCase(),
+        schema: successResponseZodSchema((api as { docs?: OpenApiMethodDoc }).docs),
+      })
+    }
+  }
+  return entries
+}
+
+let catalogPromise: Promise<WorkflowEndpointCatalog> | null = null
+let responseSchemaIndex: EndpointResponseSchemaEntry[] | null = null
+
+async function assembleCatalog(): Promise<WorkflowEndpointCatalog> {
+  const docModules = await attachOpenApiDocsToModules(getModules(), getApiRouteManifests())
+  responseSchemaIndex = buildResponseSchemaIndex(docModules)
+  return buildEndpointCatalog(docModules)
+}
+
+export async function getWorkflowEndpointCatalog(): Promise<WorkflowEndpointCatalog> {
+  if (!catalogPromise) {
+    catalogPromise = assembleCatalog().catch((error: unknown) => {
+      catalogPromise = null
+      throw error
+    })
+  }
+  return catalogPromise
+}
+
+/**
+ * Warms the per-process catalog cache, swallowing failures: callers that only
+ * need the sync `findEndpointResponseSchema` lookup (the context-schema
+ * route) degrade to 'unknown' contracts when assembly is impossible, e.g.
+ * when the module registry is not bootstrapped.
+ */
+export async function ensureWorkflowEndpointCatalog(): Promise<void> {
+  try {
+    await getWorkflowEndpointCatalog()
+  } catch {
+    return
+  }
+}
+
+/**
+ * Sync lookup over the warmed response-schema index. Returns null until
+ * `getWorkflowEndpointCatalog`/`ensureWorkflowEndpointCatalog` has resolved
+ * at least once in this process, and for endpoints without a declared zod
+ * success response.
+ */
+export function findEndpointResponseSchema(endpoint: string, method: string): ZodTypeAny | null {
+  if (!responseSchemaIndex) return null
+  const matched = findMatchingEndpoint(endpoint, method, responseSchemaIndex)
+  return matched ? matched.item.schema : null
+}
+
+export function clearWorkflowEndpointCatalogForTests(): void {
+  catalogPromise = null
+  responseSchemaIndex = null
+}

package/src/modules/workflows/lib/endpoint-path.ts

@@ -0,0 +1,134 @@
+/**
+ * Workflows Module - pure endpoint-path helpers (issue #4235).
+ *
+ * Shared between the EndpointPicker component (browser) and the server-side
+ * CALL_API output-contract lookup: matching a CALL_API `endpoint` config
+ * value against catalog template paths (`/api/customers/people/{id}`) and
+ * composing an endpoint string from typed parameter values. PURE — no React,
+ * no ORM, no DI, no registry imports.
+ *
+ * Values are treated as opaque text: `{{...}}` interpolation pills and
+ * unfilled `{param}` placeholders both match a template's parameter segments,
+ * and query values are never URL-encoded so pills survive round-trips.
+ */
+
+export interface EndpointValueParts {
+  path: string
+  query: Record<string, string>
+}
+
+export interface EndpointTemplateMatch {
+  pathParams: Record<string, string>
+}
+
+function stripTrailingSlash(path: string): string {
+  if (path.length > 1 && path.endsWith('/')) return path.slice(0, -1)
+  return path
+}
+
+export function splitEndpointValue(value: string): EndpointValueParts {
+  const trimmed = value.trim()
+  const queryIndex = trimmed.indexOf('?')
+  const path = stripTrailingSlash(queryIndex === -1 ? trimmed : trimmed.slice(0, queryIndex))
+  const query: Record<string, string> = {}
+  if (queryIndex !== -1) {
+    const rawQuery = trimmed.slice(queryIndex + 1)
+    for (const pair of rawQuery.split('&')) {
+      if (pair.length === 0) continue
+      const equalsIndex = pair.indexOf('=')
+      const key = equalsIndex === -1 ? pair : pair.slice(0, equalsIndex)
+      if (key.length === 0) continue
+      query[key] = equalsIndex === -1 ? '' : pair.slice(equalsIndex + 1)
+    }
+  }
+  return { path, query }
+}
+
+function templateParamName(segment: string): string | null {
+  if (segment.length > 2 && segment.startsWith('{') && segment.endsWith('}')) {
+    return segment.slice(1, -1)
+  }
+  return null
+}
+
+export function matchEndpointTemplate(endpointPath: string, templatePath: string): EndpointTemplateMatch | null {
+  const valueSegments = stripTrailingSlash(endpointPath.trim()).split('/')
+  const templateSegments = stripTrailingSlash(templatePath.trim()).split('/')
+  if (valueSegments.length !== templateSegments.length) return null
+  const pathParams: Record<string, string> = {}
+  for (let index = 0; index < templateSegments.length; index += 1) {
+    const templateSegment = templateSegments[index]
+    const valueSegment = valueSegments[index]
+    const paramName = templateParamName(templateSegment)
+    if (paramName !== null) {
+      if (valueSegment.length === 0) return null
+      pathParams[paramName] = valueSegment === `{${paramName}}` ? '' : valueSegment
+      continue
+    }
+    if (templateSegment !== valueSegment) return null
+  }
+  return { pathParams }
+}
+
+export interface MatchableEndpoint {
+  path: string
+  method: string
+}
+
+function templateParamCount(templatePath: string): number {
+  let count = 0
+  for (const segment of templatePath.split('/')) {
+    if (templateParamName(segment) !== null) count += 1
+  }
+  return count
+}
+
+/**
+ * Finds the catalog endpoint a CALL_API endpoint value points at. Exact
+ * literal matches win; otherwise the template with the fewest parameter
+ * segments wins, ties broken by path order, so `/api/a/{id}` beats
+ * `/api/{x}/{y}` deterministically.
+ */
+export function findMatchingEndpoint<T extends MatchableEndpoint>(
+  endpointValue: string,
+  method: string,
+  items: T[],
+): { item: T; match: EndpointTemplateMatch } | null {
+  const { path } = splitEndpointValue(endpointValue)
+  if (path.length === 0) return null
+  const normalizedMethod = method.trim().toUpperCase()
+  const candidates: Array<{ item: T; match: EndpointTemplateMatch; paramCount: number }> = []
+  for (const item of items) {
+    if (item.method.toUpperCase() !== normalizedMethod) continue
+    const match = matchEndpointTemplate(path, item.path)
+    if (!match) continue
+    candidates.push({ item, match, paramCount: templateParamCount(item.path) })
+  }
+  if (candidates.length === 0) return null
+  candidates.sort((left, right) => {
+    if (left.paramCount !== right.paramCount) return left.paramCount - right.paramCount
+    return left.item.path.localeCompare(right.item.path)
+  })
+  const best = candidates[0]
+  return { item: best.item, match: best.match }
+}
+
+export function composeEndpointValue(
+  templatePath: string,
+  pathParams: Record<string, string>,
+  queryParams: Record<string, string>,
+): string {
+  const path = stripTrailingSlash(templatePath.trim())
+    .split('/')
+    .map((segment) => {
+      const paramName = templateParamName(segment)
+      if (paramName === null) return segment
+      const value = pathParams[paramName]
+      return typeof value === 'string' && value.length > 0 ? value : segment
+    })
+    .join('/')
+  const queryEntries = Object.entries(queryParams).filter(([key, value]) => key.length > 0 && value.length > 0)
+  if (queryEntries.length === 0) return path
+  const query = queryEntries.map(([key, value]) => `${key}=${value}`).join('&')
+  return `${path}?${query}`
+}

package/src/modules/workflows/lib/engine-version.ts

@@ -0,0 +1,67 @@
+/**
+ * Workflow engine version — the forward-compatibility guard for additive
+ * definition capabilities (spec 2026-07-26-workflows-ux-redesign.md section
+ * 5.8).
+ *
+ * A definition may declare `metadata.minEngineVersion`. An engine whose
+ * `WORKFLOW_ENGINE_VERSION` is lower refuses to instantiate that definition
+ * rather than silently misexecuting a capability it does not know. Bump the
+ * constant whenever a release teaches the engine a new definition capability,
+ * and have the editor stamp the matching `minEngineVersion` on definitions
+ * that use it.
+ *
+ * Version log:
+ * - 1: baseline (all step types up to and including WAIT_FOR_TIMER)
+ * - 2: IF_ELSE and SWITCH branching steps
+ * - 3: WAIT_FOR_CONDITION predicate wait step
+ * - 4: outcome transitions for agent disposition routing
+ */
+export const WORKFLOW_ENGINE_VERSION = 4
+
+/**
+ * Engine versions required by definition capabilities. Kept pure and data-only
+ * so both the editor (stamping metadata on save) and the engine can share them.
+ */
+export const STEP_TYPE_MIN_ENGINE_VERSIONS: Record<string, number> = {
+  IF_ELSE: 2,
+  SWITCH: 2,
+  WAIT_FOR_CONDITION: 3,
+}
+
+export const TRANSITION_KIND_MIN_ENGINE_VERSIONS: Record<string, number> = {
+  outcome: 4,
+}
+
+export type EngineVersionedDefinition = {
+  steps?: unknown
+  transitions?: unknown
+}
+
+export function resolveRequiredEngineVersion(definition: EngineVersionedDefinition | null | undefined): number {
+  if (!definition || typeof definition !== 'object') return 1
+  let required = 1
+  if (Array.isArray(definition.steps)) {
+    for (const step of definition.steps) {
+      const stepType = step && typeof step === 'object' ? (step as { stepType?: unknown }).stepType : undefined
+      if (typeof stepType !== 'string') continue
+      const version = STEP_TYPE_MIN_ENGINE_VERSIONS[stepType]
+      if (version && version > required) required = version
+    }
+  }
+  if (Array.isArray(definition.transitions)) {
+    for (const transition of definition.transitions) {
+      const transitionKind = transition && typeof transition === 'object'
+        ? (transition as { kind?: unknown }).kind
+        : undefined
+      if (typeof transitionKind !== 'string') continue
+      const version = TRANSITION_KIND_MIN_ENGINE_VERSIONS[transitionKind]
+      if (version && version > required) required = version
+    }
+  }
+  return required
+}
+
+export function isEngineVersionSupported(minEngineVersion: unknown): boolean {
+  if (typeof minEngineVersion !== 'number' || !Number.isFinite(minEngineVersion)) return true
+  return minEngineVersion <= WORKFLOW_ENGINE_VERSION
+}

package/src/modules/workflows/lib/error-handler.ts

@@ -0,0 +1,192 @@
+/**
+ * Workflows Module - Workflow-level Error Handler
+ *
+ * The definition-level catch-all of spec 5.9, implemented as an ENGINE
+ * CONSTRUCT: `completeWorkflow`'s FAILED branch schedules the designated handler
+ * before compensation runs, and a queue worker starts it as a sub-workflow with
+ * `{ failedStepId, error, contextSnapshot }` as its initial context. It is
+ * deliberately NOT an event trigger — the trigger subscriber excludes
+ * `workflows.*` events.
+ *
+ * Durability: `ERROR_HANDLER_SCHEDULED` is written inside the failing
+ * transaction, so the intent survives even if the enqueue is lost; the queue
+ * carries the execution. Running the handler out of band keeps a handler failure
+ * from poisoning the transaction that is recording the original failure, and
+ * releases the instance row lock first.
+ *
+ * Recursion guard: handler instances carry `metadata.errorHandler.depth`, which
+ * is engine-owned (unlike context, which the context PATCH API exposes). A
+ * handler that fails cannot schedule another handler.
+ */
+
+import type { EntityManager } from '@mikro-orm/core'
+import type { AwilixContainer } from 'awilix'
+import { WorkflowInstance } from '../data/entities'
+import { logWorkflowEvent } from './event-logger'
+import { readWorkflowErrorHandler } from './error-routing'
+import { findDefinitionForInstance } from './find-definition'
+import type { WorkflowActivityJob, WorkflowActivityJobErrorHandler } from './activity-queue-types'
+import { WORKFLOW_ACTIVITIES_QUEUE_NAME } from './activity-queue-types'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+
+const logger = createLogger('workflows').child({ component: 'error-handler' })
+
+/** One level of handling: a handler that fails is never handled by a handler. */
+export const WORKFLOW_MAX_ERROR_HANDLER_DEPTH = 1
+
+export interface WorkflowErrorHandlerFailure {
+  failedStepId?: string | null
+  error?: string | null
+  details?: unknown
+}
+
+export function readErrorHandlerDepth(instance: WorkflowInstance): number {
+  const depth = instance.metadata?.errorHandler?.depth
+  return typeof depth === 'number' && Number.isFinite(depth) ? depth : 0
+}
+
+/**
+ * Schedule the definition-level handler sub-workflow for a failing instance.
+ * Best-effort like `enqueueSubWorkflowParentResume`: a queue hiccup must never
+ * undo the failure that is being recorded. Called BEFORE compensation so the
+ * snapshot describes the state that actually failed.
+ */
+export async function scheduleWorkflowErrorHandler(
+  em: EntityManager,
+  instance: WorkflowInstance,
+  failure: WorkflowErrorHandlerFailure
+): Promise<boolean> {
+  const definition = await findDefinitionForInstance(em, instance)
+  const handler = readWorkflowErrorHandler(definition?.definition)
+  if (!handler || !('workflowId' in handler)) return false
+
+  const failedStepId = failure.failedStepId || instance.currentStepId || null
+  const depth = readErrorHandlerDepth(instance)
+
+  if (depth >= WORKFLOW_MAX_ERROR_HANDLER_DEPTH) {
+    await logWorkflowEvent(em, {
+      workflowInstanceId: instance.id,
+      eventType: 'ERROR_HANDLER_SKIPPED',
+      eventData: {
+        reason: 'MAX_DEPTH',
+        depth,
+        maxDepth: WORKFLOW_MAX_ERROR_HANDLER_DEPTH,
+        handlerWorkflowId: handler.workflowId,
+        failedStepId,
+      },
+      tenantId: instance.tenantId,
+      organizationId: instance.organizationId,
+    })
+    return false
+  }
+
+  const contextSnapshot = { ...(instance.context || {}) }
+
+  await logWorkflowEvent(em, {
+    workflowInstanceId: instance.id,
+    eventType: 'ERROR_HANDLER_SCHEDULED',
+    eventData: {
+      handlerWorkflowId: handler.workflowId,
+      handlerVersion: handler.version,
+      failedStepId,
+      error: failure.error ?? null,
+      depth: depth + 1,
+    },
+    tenantId: instance.tenantId,
+    organizationId: instance.organizationId,
+  })
+
+  const job: WorkflowActivityJobErrorHandler = {
+    kind: 'workflow_error_handler',
+    workflowInstanceId: instance.id,
+    handlerWorkflowId: handler.workflowId,
+    handlerVersion: handler.version,
+    failedStepId,
+    error: failure.error ?? null,
+    contextSnapshot,
+    depth: depth + 1,
+    tenantId: instance.tenantId,
+    organizationId: instance.organizationId,
+  }
+
+  try {
+    const { createModuleQueue } = await import('@open-mercato/queue')
+    const queue = createModuleQueue<WorkflowActivityJob>(WORKFLOW_ACTIVITIES_QUEUE_NAME, {
+      concurrency: parseInt(process.env.WORKFLOW_WORKER_CONCURRENCY || '5'),
+    })
+    await queue.enqueue(job)
+  } catch (error) {
+    logger.error('Failed to enqueue workflow error handler', {
+      instanceId: instance.id,
+      handlerWorkflowId: handler.workflowId,
+      err: error,
+    })
+    return false
+  }
+
+  return true
+}
+
+/**
+ * Worker side: start the handler workflow with the failure triple as its input
+ * context, on the worker's own EntityManager. The depth marker rides the child's
+ * metadata so a failing handler cannot schedule another one.
+ */
+export async function runWorkflowErrorHandler(
+  em: EntityManager,
+  container: AwilixContainer,
+  payload: WorkflowActivityJobErrorHandler
+): Promise<string | null> {
+  const failedInstance = await em.findOne(WorkflowInstance, {
+    id: payload.workflowInstanceId,
+    tenantId: payload.tenantId,
+    organizationId: payload.organizationId,
+  })
+  if (!failedInstance) {
+    logger.warn('Error handler job references an unknown instance', {
+      instanceId: payload.workflowInstanceId,
+    })
+    return null
+  }
+
+  const { startWorkflow, executeWorkflow } = await import('./workflow-executor')
+
+  const handlerInstance = await startWorkflow(em, {
+    workflowId: payload.handlerWorkflowId,
+    version: payload.handlerVersion,
+    initialContext: {
+      failedStepId: payload.failedStepId,
+      error: payload.error,
+      contextSnapshot: payload.contextSnapshot,
+    },
+    metadata: {
+      labels: {
+        errorHandlerForInstanceId: payload.workflowInstanceId,
+      },
+      errorHandler: {
+        depth: payload.depth,
+        forInstanceId: payload.workflowInstanceId,
+        forStepId: payload.failedStepId ?? undefined,
+      },
+    },
+    tenantId: payload.tenantId,
+    organizationId: payload.organizationId,
+  })
+
+  await logWorkflowEvent(em, {
+    workflowInstanceId: payload.workflowInstanceId,
+    eventType: 'ERROR_HANDLER_STARTED',
+    eventData: {
+      handlerInstanceId: handlerInstance.id,
+      handlerWorkflowId: payload.handlerWorkflowId,
+      failedStepId: payload.failedStepId,
+      depth: payload.depth,
+    },
+    tenantId: payload.tenantId,
+    organizationId: payload.organizationId,
+  })
+
+  await executeWorkflow(em, container, handlerInstance.id)
+
+  return handlerInstance.id
+}