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

package/dist/modules/workflows/lib/endpoint-catalog.js.map

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

package/dist/modules/workflows/lib/endpoint-path.js

@@ -0,0 +1,90 @@
+function stripTrailingSlash(path) {
+  if (path.length > 1 && path.endsWith("/")) return path.slice(0, -1);
+  return path;
+}
+function splitEndpointValue(value) {
+  const trimmed = value.trim();
+  const queryIndex = trimmed.indexOf("?");
+  const path = stripTrailingSlash(queryIndex === -1 ? trimmed : trimmed.slice(0, queryIndex));
+  const query = {};
+  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) {
+  if (segment.length > 2 && segment.startsWith("{") && segment.endsWith("}")) {
+    return segment.slice(1, -1);
+  }
+  return null;
+}
+function matchEndpointTemplate(endpointPath, templatePath) {
+  const valueSegments = stripTrailingSlash(endpointPath.trim()).split("/");
+  const templateSegments = stripTrailingSlash(templatePath.trim()).split("/");
+  if (valueSegments.length !== templateSegments.length) return null;
+  const pathParams = {};
+  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 };
+}
+function templateParamCount(templatePath) {
+  let count = 0;
+  for (const segment of templatePath.split("/")) {
+    if (templateParamName(segment) !== null) count += 1;
+  }
+  return count;
+}
+function findMatchingEndpoint(endpointValue, method, items) {
+  const { path } = splitEndpointValue(endpointValue);
+  if (path.length === 0) return null;
+  const normalizedMethod = method.trim().toUpperCase();
+  const candidates = [];
+  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 };
+}
+function composeEndpointValue(templatePath, pathParams, queryParams) {
+  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}`;
+}
+export {
+  composeEndpointValue,
+  findMatchingEndpoint,
+  matchEndpointTemplate,
+  splitEndpointValue
+};
+//# sourceMappingURL=endpoint-path.js.map

package/dist/modules/workflows/lib/endpoint-path.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/workflows/lib/endpoint-path.ts"],
+  "sourcesContent": ["/**\n * Workflows Module - pure endpoint-path helpers (issue #4235).\n *\n * Shared between the EndpointPicker component (browser) and the server-side\n * CALL_API output-contract lookup: matching a CALL_API `endpoint` config\n * value against catalog template paths (`/api/customers/people/{id}`) and\n * composing an endpoint string from typed parameter values. PURE \u2014 no React,\n * no ORM, no DI, no registry imports.\n *\n * Values are treated as opaque text: `{{...}}` interpolation pills and\n * unfilled `{param}` placeholders both match a template's parameter segments,\n * and query values are never URL-encoded so pills survive round-trips.\n */\n\nexport interface EndpointValueParts {\n  path: string\n  query: Record<string, string>\n}\n\nexport interface EndpointTemplateMatch {\n  pathParams: Record<string, string>\n}\n\nfunction stripTrailingSlash(path: string): string {\n  if (path.length > 1 && path.endsWith('/')) return path.slice(0, -1)\n  return path\n}\n\nexport function splitEndpointValue(value: string): EndpointValueParts {\n  const trimmed = value.trim()\n  const queryIndex = trimmed.indexOf('?')\n  const path = stripTrailingSlash(queryIndex === -1 ? trimmed : trimmed.slice(0, queryIndex))\n  const query: Record<string, string> = {}\n  if (queryIndex !== -1) {\n    const rawQuery = trimmed.slice(queryIndex + 1)\n    for (const pair of rawQuery.split('&')) {\n      if (pair.length === 0) continue\n      const equalsIndex = pair.indexOf('=')\n      const key = equalsIndex === -1 ? pair : pair.slice(0, equalsIndex)\n      if (key.length === 0) continue\n      query[key] = equalsIndex === -1 ? '' : pair.slice(equalsIndex + 1)\n    }\n  }\n  return { path, query }\n}\n\nfunction templateParamName(segment: string): string | null {\n  if (segment.length > 2 && segment.startsWith('{') && segment.endsWith('}')) {\n    return segment.slice(1, -1)\n  }\n  return null\n}\n\nexport function matchEndpointTemplate(endpointPath: string, templatePath: string): EndpointTemplateMatch | null {\n  const valueSegments = stripTrailingSlash(endpointPath.trim()).split('/')\n  const templateSegments = stripTrailingSlash(templatePath.trim()).split('/')\n  if (valueSegments.length !== templateSegments.length) return null\n  const pathParams: Record<string, string> = {}\n  for (let index = 0; index < templateSegments.length; index += 1) {\n    const templateSegment = templateSegments[index]\n    const valueSegment = valueSegments[index]\n    const paramName = templateParamName(templateSegment)\n    if (paramName !== null) {\n      if (valueSegment.length === 0) return null\n      pathParams[paramName] = valueSegment === `{${paramName}}` ? '' : valueSegment\n      continue\n    }\n    if (templateSegment !== valueSegment) return null\n  }\n  return { pathParams }\n}\n\nexport interface MatchableEndpoint {\n  path: string\n  method: string\n}\n\nfunction templateParamCount(templatePath: string): number {\n  let count = 0\n  for (const segment of templatePath.split('/')) {\n    if (templateParamName(segment) !== null) count += 1\n  }\n  return count\n}\n\n/**\n * Finds the catalog endpoint a CALL_API endpoint value points at. Exact\n * literal matches win; otherwise the template with the fewest parameter\n * segments wins, ties broken by path order, so `/api/a/{id}` beats\n * `/api/{x}/{y}` deterministically.\n */\nexport function findMatchingEndpoint<T extends MatchableEndpoint>(\n  endpointValue: string,\n  method: string,\n  items: T[],\n): { item: T; match: EndpointTemplateMatch } | null {\n  const { path } = splitEndpointValue(endpointValue)\n  if (path.length === 0) return null\n  const normalizedMethod = method.trim().toUpperCase()\n  const candidates: Array<{ item: T; match: EndpointTemplateMatch; paramCount: number }> = []\n  for (const item of items) {\n    if (item.method.toUpperCase() !== normalizedMethod) continue\n    const match = matchEndpointTemplate(path, item.path)\n    if (!match) continue\n    candidates.push({ item, match, paramCount: templateParamCount(item.path) })\n  }\n  if (candidates.length === 0) return null\n  candidates.sort((left, right) => {\n    if (left.paramCount !== right.paramCount) return left.paramCount - right.paramCount\n    return left.item.path.localeCompare(right.item.path)\n  })\n  const best = candidates[0]\n  return { item: best.item, match: best.match }\n}\n\nexport function composeEndpointValue(\n  templatePath: string,\n  pathParams: Record<string, string>,\n  queryParams: Record<string, string>,\n): string {\n  const path = stripTrailingSlash(templatePath.trim())\n    .split('/')\n    .map((segment) => {\n      const paramName = templateParamName(segment)\n      if (paramName === null) return segment\n      const value = pathParams[paramName]\n      return typeof value === 'string' && value.length > 0 ? value : segment\n    })\n    .join('/')\n  const queryEntries = Object.entries(queryParams).filter(([key, value]) => key.length > 0 && value.length > 0)\n  if (queryEntries.length === 0) return path\n  const query = queryEntries.map(([key, value]) => `${key}=${value}`).join('&')\n  return `${path}?${query}`\n}\n"],
+  "mappings": "AAuBA,SAAS,mBAAmB,MAAsB;AAChD,MAAI,KAAK,SAAS,KAAK,KAAK,SAAS,GAAG,EAAG,QAAO,KAAK,MAAM,GAAG,EAAE;AAClE,SAAO;AACT;AAEO,SAAS,mBAAmB,OAAmC;AACpE,QAAM,UAAU,MAAM,KAAK;AAC3B,QAAM,aAAa,QAAQ,QAAQ,GAAG;AACtC,QAAM,OAAO,mBAAmB,eAAe,KAAK,UAAU,QAAQ,MAAM,GAAG,UAAU,CAAC;AAC1F,QAAM,QAAgC,CAAC;AACvC,MAAI,eAAe,IAAI;AACrB,UAAM,WAAW,QAAQ,MAAM,aAAa,CAAC;AAC7C,eAAW,QAAQ,SAAS,MAAM,GAAG,GAAG;AACtC,UAAI,KAAK,WAAW,EAAG;AACvB,YAAM,cAAc,KAAK,QAAQ,GAAG;AACpC,YAAM,MAAM,gBAAgB,KAAK,OAAO,KAAK,MAAM,GAAG,WAAW;AACjE,UAAI,IAAI,WAAW,EAAG;AACtB,YAAM,GAAG,IAAI,gBAAgB,KAAK,KAAK,KAAK,MAAM,cAAc,CAAC;AAAA,IACnE;AAAA,EACF;AACA,SAAO,EAAE,MAAM,MAAM;AACvB;AAEA,SAAS,kBAAkB,SAAgC;AACzD,MAAI,QAAQ,SAAS,KAAK,QAAQ,WAAW,GAAG,KAAK,QAAQ,SAAS,GAAG,GAAG;AAC1E,WAAO,QAAQ,MAAM,GAAG,EAAE;AAAA,EAC5B;AACA,SAAO;AACT;AAEO,SAAS,sBAAsB,cAAsB,cAAoD;AAC9G,QAAM,gBAAgB,mBAAmB,aAAa,KAAK,CAAC,EAAE,MAAM,GAAG;AACvE,QAAM,mBAAmB,mBAAmB,aAAa,KAAK,CAAC,EAAE,MAAM,GAAG;AAC1E,MAAI,cAAc,WAAW,iBAAiB,OAAQ,QAAO;AAC7D,QAAM,aAAqC,CAAC;AAC5C,WAAS,QAAQ,GAAG,QAAQ,iBAAiB,QAAQ,SAAS,GAAG;AAC/D,UAAM,kBAAkB,iBAAiB,KAAK;AAC9C,UAAM,eAAe,cAAc,KAAK;AACxC,UAAM,YAAY,kBAAkB,eAAe;AACnD,QAAI,cAAc,MAAM;AACtB,UAAI,aAAa,WAAW,EAAG,QAAO;AACtC,iBAAW,SAAS,IAAI,iBAAiB,IAAI,SAAS,MAAM,KAAK;AACjE;AAAA,IACF;AACA,QAAI,oBAAoB,aAAc,QAAO;AAAA,EAC/C;AACA,SAAO,EAAE,WAAW;AACtB;AAOA,SAAS,mBAAmB,cAA8B;AACxD,MAAI,QAAQ;AACZ,aAAW,WAAW,aAAa,MAAM,GAAG,GAAG;AAC7C,QAAI,kBAAkB,OAAO,MAAM,KAAM,UAAS;AAAA,EACpD;AACA,SAAO;AACT;AAQO,SAAS,qBACd,eACA,QACA,OACkD;AAClD,QAAM,EAAE,KAAK,IAAI,mBAAmB,aAAa;AACjD,MAAI,KAAK,WAAW,EAAG,QAAO;AAC9B,QAAM,mBAAmB,OAAO,KAAK,EAAE,YAAY;AACnD,QAAM,aAAmF,CAAC;AAC1F,aAAW,QAAQ,OAAO;AACxB,QAAI,KAAK,OAAO,YAAY,MAAM,iBAAkB;AACpD,UAAM,QAAQ,sBAAsB,MAAM,KAAK,IAAI;AACnD,QAAI,CAAC,MAAO;AACZ,eAAW,KAAK,EAAE,MAAM,OAAO,YAAY,mBAAmB,KAAK,IAAI,EAAE,CAAC;AAAA,EAC5E;AACA,MAAI,WAAW,WAAW,EAAG,QAAO;AACpC,aAAW,KAAK,CAAC,MAAM,UAAU;AAC/B,QAAI,KAAK,eAAe,MAAM,WAAY,QAAO,KAAK,aAAa,MAAM;AACzE,WAAO,KAAK,KAAK,KAAK,cAAc,MAAM,KAAK,IAAI;AAAA,EACrD,CAAC;AACD,QAAM,OAAO,WAAW,CAAC;AACzB,SAAO,EAAE,MAAM,KAAK,MAAM,OAAO,KAAK,MAAM;AAC9C;AAEO,SAAS,qBACd,cACA,YACA,aACQ;AACR,QAAM,OAAO,mBAAmB,aAAa,KAAK,CAAC,EAChD,MAAM,GAAG,EACT,IAAI,CAAC,YAAY;AAChB,UAAM,YAAY,kBAAkB,OAAO;AAC3C,QAAI,cAAc,KAAM,QAAO;AAC/B,UAAM,QAAQ,WAAW,SAAS;AAClC,WAAO,OAAO,UAAU,YAAY,MAAM,SAAS,IAAI,QAAQ;AAAA,EACjE,CAAC,EACA,KAAK,GAAG;AACX,QAAM,eAAe,OAAO,QAAQ,WAAW,EAAE,OAAO,CAAC,CAAC,KAAK,KAAK,MAAM,IAAI,SAAS,KAAK,MAAM,SAAS,CAAC;AAC5G,MAAI,aAAa,WAAW,EAAG,QAAO;AACtC,QAAM,QAAQ,aAAa,IAAI,CAAC,CAAC,KAAK,KAAK,MAAM,GAAG,GAAG,IAAI,KAAK,EAAE,EAAE,KAAK,GAAG;AAC5E,SAAO,GAAG,IAAI,IAAI,KAAK;AACzB;",
+  "names": []
+}

package/dist/modules/workflows/lib/engine-version.js

@@ -0,0 +1,42 @@
+const WORKFLOW_ENGINE_VERSION = 4;
+const STEP_TYPE_MIN_ENGINE_VERSIONS = {
+  IF_ELSE: 2,
+  SWITCH: 2,
+  WAIT_FOR_CONDITION: 3
+};
+const TRANSITION_KIND_MIN_ENGINE_VERSIONS = {
+  outcome: 4
+};
+function resolveRequiredEngineVersion(definition) {
+  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.stepType : void 0;
+      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.kind : void 0;
+      if (typeof transitionKind !== "string") continue;
+      const version = TRANSITION_KIND_MIN_ENGINE_VERSIONS[transitionKind];
+      if (version && version > required) required = version;
+    }
+  }
+  return required;
+}
+function isEngineVersionSupported(minEngineVersion) {
+  if (typeof minEngineVersion !== "number" || !Number.isFinite(minEngineVersion)) return true;
+  return minEngineVersion <= WORKFLOW_ENGINE_VERSION;
+}
+export {
+  STEP_TYPE_MIN_ENGINE_VERSIONS,
+  TRANSITION_KIND_MIN_ENGINE_VERSIONS,
+  WORKFLOW_ENGINE_VERSION,
+  isEngineVersionSupported,
+  resolveRequiredEngineVersion
+};
+//# sourceMappingURL=engine-version.js.map

package/dist/modules/workflows/lib/engine-version.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/workflows/lib/engine-version.ts"],
+  "sourcesContent": ["/**\n * Workflow engine version \u2014 the forward-compatibility guard for additive\n * definition capabilities (spec 2026-07-26-workflows-ux-redesign.md section\n * 5.8).\n *\n * A definition may declare `metadata.minEngineVersion`. An engine whose\n * `WORKFLOW_ENGINE_VERSION` is lower refuses to instantiate that definition\n * rather than silently misexecuting a capability it does not know. Bump the\n * constant whenever a release teaches the engine a new definition capability,\n * and have the editor stamp the matching `minEngineVersion` on definitions\n * that use it.\n *\n * Version log:\n * - 1: baseline (all step types up to and including WAIT_FOR_TIMER)\n * - 2: IF_ELSE and SWITCH branching steps\n * - 3: WAIT_FOR_CONDITION predicate wait step\n * - 4: outcome transitions for agent disposition routing\n */\nexport const WORKFLOW_ENGINE_VERSION = 4\n\n/**\n * Engine versions required by definition capabilities. Kept pure and data-only\n * so both the editor (stamping metadata on save) and the engine can share them.\n */\nexport const STEP_TYPE_MIN_ENGINE_VERSIONS: Record<string, number> = {\n  IF_ELSE: 2,\n  SWITCH: 2,\n  WAIT_FOR_CONDITION: 3,\n}\n\nexport const TRANSITION_KIND_MIN_ENGINE_VERSIONS: Record<string, number> = {\n  outcome: 4,\n}\n\nexport type EngineVersionedDefinition = {\n  steps?: unknown\n  transitions?: unknown\n}\n\nexport function resolveRequiredEngineVersion(definition: EngineVersionedDefinition | null | undefined): number {\n  if (!definition || typeof definition !== 'object') return 1\n  let required = 1\n  if (Array.isArray(definition.steps)) {\n    for (const step of definition.steps) {\n      const stepType = step && typeof step === 'object' ? (step as { stepType?: unknown }).stepType : undefined\n      if (typeof stepType !== 'string') continue\n      const version = STEP_TYPE_MIN_ENGINE_VERSIONS[stepType]\n      if (version && version > required) required = version\n    }\n  }\n  if (Array.isArray(definition.transitions)) {\n    for (const transition of definition.transitions) {\n      const transitionKind = transition && typeof transition === 'object'\n        ? (transition as { kind?: unknown }).kind\n        : undefined\n      if (typeof transitionKind !== 'string') continue\n      const version = TRANSITION_KIND_MIN_ENGINE_VERSIONS[transitionKind]\n      if (version && version > required) required = version\n    }\n  }\n  return required\n}\n\nexport function isEngineVersionSupported(minEngineVersion: unknown): boolean {\n  if (typeof minEngineVersion !== 'number' || !Number.isFinite(minEngineVersion)) return true\n  return minEngineVersion <= WORKFLOW_ENGINE_VERSION\n}\n"],
+  "mappings": "AAkBO,MAAM,0BAA0B;AAMhC,MAAM,gCAAwD;AAAA,EACnE,SAAS;AAAA,EACT,QAAQ;AAAA,EACR,oBAAoB;AACtB;AAEO,MAAM,sCAA8D;AAAA,EACzE,SAAS;AACX;AAOO,SAAS,6BAA6B,YAAkE;AAC7G,MAAI,CAAC,cAAc,OAAO,eAAe,SAAU,QAAO;AAC1D,MAAI,WAAW;AACf,MAAI,MAAM,QAAQ,WAAW,KAAK,GAAG;AACnC,eAAW,QAAQ,WAAW,OAAO;AACnC,YAAM,WAAW,QAAQ,OAAO,SAAS,WAAY,KAAgC,WAAW;AAChG,UAAI,OAAO,aAAa,SAAU;AAClC,YAAM,UAAU,8BAA8B,QAAQ;AACtD,UAAI,WAAW,UAAU,SAAU,YAAW;AAAA,IAChD;AAAA,EACF;AACA,MAAI,MAAM,QAAQ,WAAW,WAAW,GAAG;AACzC,eAAW,cAAc,WAAW,aAAa;AAC/C,YAAM,iBAAiB,cAAc,OAAO,eAAe,WACtD,WAAkC,OACnC;AACJ,UAAI,OAAO,mBAAmB,SAAU;AACxC,YAAM,UAAU,oCAAoC,cAAc;AAClE,UAAI,WAAW,UAAU,SAAU,YAAW;AAAA,IAChD;AAAA,EACF;AACA,SAAO;AACT;AAEO,SAAS,yBAAyB,kBAAoC;AAC3E,MAAI,OAAO,qBAAqB,YAAY,CAAC,OAAO,SAAS,gBAAgB,EAAG,QAAO;AACvF,SAAO,oBAAoB;AAC7B;",
+  "names": []
+}

package/dist/modules/workflows/lib/error-handler.js

@@ -0,0 +1,132 @@
+import { WorkflowInstance } from "../data/entities.js";
+import { logWorkflowEvent } from "./event-logger.js";
+import { readWorkflowErrorHandler } from "./error-routing.js";
+import { findDefinitionForInstance } from "./find-definition.js";
+import { WORKFLOW_ACTIVITIES_QUEUE_NAME } from "./activity-queue-types.js";
+import { createLogger } from "@open-mercato/shared/lib/logger";
+const logger = createLogger("workflows").child({ component: "error-handler" });
+const WORKFLOW_MAX_ERROR_HANDLER_DEPTH = 1;
+function readErrorHandlerDepth(instance) {
+  const depth = instance.metadata?.errorHandler?.depth;
+  return typeof depth === "number" && Number.isFinite(depth) ? depth : 0;
+}
+async function scheduleWorkflowErrorHandler(em, instance, failure) {
+  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 = {
+    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(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;
+}
+async function runWorkflowErrorHandler(em, container, payload) {
+  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.js");
+  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 ?? void 0
+      }
+    },
+    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;
+}
+export {
+  WORKFLOW_MAX_ERROR_HANDLER_DEPTH,
+  readErrorHandlerDepth,
+  runWorkflowErrorHandler,
+  scheduleWorkflowErrorHandler
+};
+//# sourceMappingURL=error-handler.js.map

package/dist/modules/workflows/lib/error-handler.js.map

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

package/dist/modules/workflows/lib/error-routing.js

@@ -0,0 +1,104 @@
+const ERROR_TRANSITION_KIND = "error";
+const ERROR_SOURCE_HANDLE_ID = "error";
+const WORKFLOW_ERROR_CONTEXT_KEY = "__error";
+function buildErrorContextEntry(stepId, message) {
+  return { stepId, message, occurredAt: (/* @__PURE__ */ new Date()).toISOString() };
+}
+function isErrorTransition(transition) {
+  return transition?.kind === ERROR_TRANSITION_KIND;
+}
+function excludeErrorTransitions(transitions) {
+  return transitions.filter((transition) => !isErrorTransition(transition));
+}
+function findErrorTransition(definition, stepId) {
+  const transitions = definition?.transitions ?? [];
+  const candidates = transitions.filter(
+    (transition) => transition.fromStepId === stepId && isErrorTransition(transition)
+  );
+  if (candidates.length === 0) return null;
+  const ordered = [...candidates].sort((a, b) => (b.priority || 0) - (a.priority || 0));
+  return ordered[0] ?? null;
+}
+function readStepErrorDirective(definition, stepId) {
+  const step = (definition?.steps ?? []).find((candidate) => candidate.stepId === stepId);
+  const directive = step?.errorDirective;
+  if (!directive) return null;
+  const mode = directive.mode;
+  if (mode !== "fail" && mode !== "continueWithFallback" && mode !== "failureQueue") return null;
+  return { mode, fallbackValue: directive.fallbackValue };
+}
+function readWorkflowErrorHandler(definition) {
+  const handler = definition?.errorHandler;
+  if (!handler) return null;
+  const hasWorkflow = typeof handler.workflowId === "string" && handler.workflowId.length > 0;
+  const hasStep = typeof handler.stepId === "string" && handler.stepId.length > 0;
+  if (hasWorkflow === hasStep) return null;
+  if (hasWorkflow) {
+    return { workflowId: handler.workflowId, version: handler.version };
+  }
+  return { stepId: handler.stepId };
+}
+function resolveStepFailureHandling(definition, stepId) {
+  const errorTransition = findErrorTransition(definition, stepId);
+  if (errorTransition) return { kind: "route", transition: errorTransition };
+  const directive = readStepErrorDirective(definition, stepId);
+  if (directive?.mode === "continueWithFallback") {
+    return { kind: "continue", fallbackValue: directive.fallbackValue };
+  }
+  if (directive?.mode === "failureQueue") return { kind: "park" };
+  const handler = readWorkflowErrorHandler(definition);
+  if (handler && "stepId" in handler && handler.stepId !== stepId) {
+    return { kind: "handlerStep", stepId: handler.stepId };
+  }
+  return { kind: "fail" };
+}
+function validateErrorRoutes(definition) {
+  const issues = [];
+  const transitions = definition?.transitions ?? [];
+  const stepIds = new Set((definition?.steps ?? []).map((step) => step.stepId).filter(Boolean));
+  for (const transition of transitions) {
+    if (!isErrorTransition(transition)) continue;
+    if (transition.fromStepId && stepIds.size > 0 && !stepIds.has(transition.fromStepId)) {
+      issues.push({
+        code: "ERROR_ROUTE_UNKNOWN_SOURCE",
+        message: `Error route ${transition.transitionId ?? ""} starts at unknown step ${transition.fromStepId}`,
+        transitionId: transition.transitionId,
+        stepId: transition.fromStepId
+      });
+    }
+    if (transition.toStepId && stepIds.size > 0 && !stepIds.has(transition.toStepId)) {
+      issues.push({
+        code: "ERROR_ROUTE_UNKNOWN_TARGET",
+        message: `Error route ${transition.transitionId ?? ""} targets unknown step ${transition.toStepId}`,
+        transitionId: transition.transitionId,
+        stepId: transition.toStepId
+      });
+    }
+    const collides = transitions.some(
+      (other) => !isErrorTransition(other) && other.fromStepId === transition.fromStepId && other.toStepId === transition.toStepId
+    );
+    if (collides) {
+      issues.push({
+        code: "ERROR_ROUTE_DUPLICATE_TARGET",
+        message: `Error route ${transition.transitionId ?? ""} shares its source and target with a normal route`,
+        transitionId: transition.transitionId,
+        stepId: transition.fromStepId
+      });
+    }
+  }
+  return issues;
+}
+export {
+  ERROR_SOURCE_HANDLE_ID,
+  ERROR_TRANSITION_KIND,
+  WORKFLOW_ERROR_CONTEXT_KEY,
+  buildErrorContextEntry,
+  excludeErrorTransitions,
+  findErrorTransition,
+  isErrorTransition,
+  readStepErrorDirective,
+  readWorkflowErrorHandler,
+  resolveStepFailureHandling,
+  validateErrorRoutes
+};
+//# sourceMappingURL=error-routing.js.map

package/dist/modules/workflows/lib/error-routing.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/workflows/lib/error-routing.ts"],
+  "sourcesContent": ["/**\n * Workflows Module - Error Routing (pure)\n *\n * Resolves what happens when a step fails, from the definition alone:\n *\n *   1. an outgoing transition marked `kind: 'error'` wins \u2014 the engine follows it\n *      instead of failing the instance (spec 5.9 \"error output handle\");\n *   2. otherwise the failed step's `errorDirective` applies\n *      (`fail` | `continueWithFallback` | `failureQueue`);\n *   3. otherwise the instance fails exactly as it does today.\n *\n * Definitions carrying neither an error transition nor a directive resolve to\n * `fail`, which is the untouched legacy path \u2014 this module is the single place\n * that decides, so the \"no error config \u21D2 identical trace\" guarantee is testable.\n *\n * PURE: no ORM, DI, React or registry imports. Engine call sites pass the plain\n * definition JSON.\n */\n\nexport const ERROR_TRANSITION_KIND = 'error'\n\n/**\n * Canvas handle id every activity-bearing node exposes for its error output. A\n * connection drawn from it compiles to a transition with `kind: 'error'`. Lives\n * in this pure module so `graph-utils` can read it without pulling the React\n * component chain (enforced by the xyflow import-boundary test).\n */\nexport const ERROR_SOURCE_HANDLE_ID = 'error'\n\n/**\n * Run-context key carrying the failure that caused an error route to be taken,\n * so the handling branch can render/forward it. Engine-owned and reserved\n * against user context writes.\n */\nexport const WORKFLOW_ERROR_CONTEXT_KEY = '__error'\n\nexport interface WorkflowErrorContextEntry {\n  stepId: string\n  message: string\n  occurredAt: string\n}\n\nexport function buildErrorContextEntry(stepId: string, message: string): WorkflowErrorContextEntry {\n  return { stepId, message, occurredAt: new Date().toISOString() }\n}\n\nexport type WorkflowErrorDirectiveMode = 'fail' | 'continueWithFallback' | 'failureQueue'\n\nexport interface ErrorRoutingTransitionLike {\n  transitionId?: string\n  fromStepId?: string\n  toStepId?: string\n  kind?: string\n  priority?: number\n}\n\nexport interface ErrorRoutingStepLike {\n  stepId?: string\n  errorDirective?: {\n    mode?: string\n    fallbackValue?: unknown\n  } | null\n}\n\nexport interface ErrorRoutingErrorHandlerLike {\n  workflowId?: string\n  version?: number\n  stepId?: string\n}\n\nexport interface ErrorRoutingDefinitionLike {\n  steps?: ErrorRoutingStepLike[]\n  transitions?: ErrorRoutingTransitionLike[]\n  errorHandler?: ErrorRoutingErrorHandlerLike | null\n}\n\nexport type StepFailureHandling =\n  | { kind: 'route'; transition: ErrorRoutingTransitionLike }\n  | { kind: 'continue'; fallbackValue?: unknown }\n  | { kind: 'park' }\n  | { kind: 'handlerStep'; stepId: string }\n  | { kind: 'fail' }\n\nexport interface ErrorRouteIssue {\n  code: 'ERROR_ROUTE_DUPLICATE_TARGET' | 'ERROR_ROUTE_UNKNOWN_TARGET' | 'ERROR_ROUTE_UNKNOWN_SOURCE'\n  message: string\n  transitionId?: string\n  stepId?: string\n}\n\n/**\n * A transition authored as an error route. The discriminator is the additive\n * optional `kind` field: absent (or any other value) means a normal route, so\n * every stored definition keeps its current meaning.\n */\nexport function isErrorTransition(transition: ErrorRoutingTransitionLike | null | undefined): boolean {\n  return transition?.kind === ERROR_TRANSITION_KIND\n}\n\n/**\n * Error routes must never be taken by normal routing \u2014 they are only reachable\n * from a failure. Every routing lookup filters through this helper.\n */\nexport function excludeErrorTransitions<T extends ErrorRoutingTransitionLike>(transitions: T[]): T[] {\n  return transitions.filter((transition) => !isErrorTransition(transition))\n}\n\n/**\n * Highest-priority outgoing error route of a step. Ties keep definition order,\n * mirroring how `findValidTransitions` orders normal routes.\n */\nexport function findErrorTransition(\n  definition: ErrorRoutingDefinitionLike | null | undefined,\n  stepId: string\n): ErrorRoutingTransitionLike | null {\n  const transitions = definition?.transitions ?? []\n  const candidates = transitions.filter(\n    (transition) => transition.fromStepId === stepId && isErrorTransition(transition)\n  )\n  if (candidates.length === 0) return null\n  const ordered = [...candidates].sort((a, b) => (b.priority || 0) - (a.priority || 0))\n  return ordered[0] ?? null\n}\n\nexport function readStepErrorDirective(\n  definition: ErrorRoutingDefinitionLike | null | undefined,\n  stepId: string\n): { mode: WorkflowErrorDirectiveMode; fallbackValue?: unknown } | null {\n  const step = (definition?.steps ?? []).find((candidate) => candidate.stepId === stepId)\n  const directive = step?.errorDirective\n  if (!directive) return null\n  const mode = directive.mode\n  if (mode !== 'fail' && mode !== 'continueWithFallback' && mode !== 'failureQueue') return null\n  return { mode, fallbackValue: directive.fallbackValue }\n}\n\n/**\n * Definition-level catch-all handler (spec 5.9). Returns null unless exactly one\n * form is declared, so a malformed handler degrades to today's behavior instead\n * of guessing.\n */\nexport function readWorkflowErrorHandler(\n  definition: ErrorRoutingDefinitionLike | null | undefined\n): { workflowId: string; version?: number } | { stepId: string } | null {\n  const handler = definition?.errorHandler\n  if (!handler) return null\n  const hasWorkflow = typeof handler.workflowId === 'string' && handler.workflowId.length > 0\n  const hasStep = typeof handler.stepId === 'string' && handler.stepId.length > 0\n  if (hasWorkflow === hasStep) return null\n  if (hasWorkflow) {\n    return { workflowId: handler.workflowId as string, version: handler.version }\n  }\n  return { stepId: handler.stepId as string }\n}\n\n/**\n * The single decision point for a failed step, in precedence order:\n * wired error route \u2192 step directive \u2192 definition-level handler step \u2192 fail.\n * The handler step comes last because it is a catch-all, and a step never jumps\n * to itself, which is the recursion guard for the in-instance handler form.\n * `fail` is both the explicit directive and the absent-config default, so legacy\n * definitions never diverge.\n */\nexport function resolveStepFailureHandling(\n  definition: ErrorRoutingDefinitionLike | null | undefined,\n  stepId: string\n): StepFailureHandling {\n  const errorTransition = findErrorTransition(definition, stepId)\n  if (errorTransition) return { kind: 'route', transition: errorTransition }\n\n  const directive = readStepErrorDirective(definition, stepId)\n  if (directive?.mode === 'continueWithFallback') {\n    return { kind: 'continue', fallbackValue: directive.fallbackValue }\n  }\n  if (directive?.mode === 'failureQueue') return { kind: 'park' }\n\n  const handler = readWorkflowErrorHandler(definition)\n  if (handler && 'stepId' in handler && handler.stepId !== stepId) {\n    return { kind: 'handlerStep', stepId: handler.stepId }\n  }\n\n  return { kind: 'fail' }\n}\n\n/**\n * Author-time checks surfaced by the Problems panel. An error route sharing its\n * source AND target with a normal route is rejected because the engine resolves\n * a followed route by its `(fromStepId, toStepId)` pair \u2014 the pair would be\n * ambiguous and the wrong activities could run.\n */\nexport function validateErrorRoutes(\n  definition: ErrorRoutingDefinitionLike | null | undefined\n): ErrorRouteIssue[] {\n  const issues: ErrorRouteIssue[] = []\n  const transitions = definition?.transitions ?? []\n  const stepIds = new Set((definition?.steps ?? []).map((step) => step.stepId).filter(Boolean))\n\n  for (const transition of transitions) {\n    if (!isErrorTransition(transition)) continue\n\n    if (transition.fromStepId && stepIds.size > 0 && !stepIds.has(transition.fromStepId)) {\n      issues.push({\n        code: 'ERROR_ROUTE_UNKNOWN_SOURCE',\n        message: `Error route ${transition.transitionId ?? ''} starts at unknown step ${transition.fromStepId}`,\n        transitionId: transition.transitionId,\n        stepId: transition.fromStepId,\n      })\n    }\n\n    if (transition.toStepId && stepIds.size > 0 && !stepIds.has(transition.toStepId)) {\n      issues.push({\n        code: 'ERROR_ROUTE_UNKNOWN_TARGET',\n        message: `Error route ${transition.transitionId ?? ''} targets unknown step ${transition.toStepId}`,\n        transitionId: transition.transitionId,\n        stepId: transition.toStepId,\n      })\n    }\n\n    const collides = transitions.some(\n      (other) =>\n        !isErrorTransition(other) &&\n        other.fromStepId === transition.fromStepId &&\n        other.toStepId === transition.toStepId\n    )\n    if (collides) {\n      issues.push({\n        code: 'ERROR_ROUTE_DUPLICATE_TARGET',\n        message: `Error route ${transition.transitionId ?? ''} shares its source and target with a normal route`,\n        transitionId: transition.transitionId,\n        stepId: transition.fromStepId,\n      })\n    }\n  }\n\n  return issues\n}\n"],
+  "mappings": "AAmBO,MAAM,wBAAwB;AAQ9B,MAAM,yBAAyB;AAO/B,MAAM,6BAA6B;AAQnC,SAAS,uBAAuB,QAAgB,SAA4C;AACjG,SAAO,EAAE,QAAQ,SAAS,aAAY,oBAAI,KAAK,GAAE,YAAY,EAAE;AACjE;AAmDO,SAAS,kBAAkB,YAAoE;AACpG,SAAO,YAAY,SAAS;AAC9B;AAMO,SAAS,wBAA8D,aAAuB;AACnG,SAAO,YAAY,OAAO,CAAC,eAAe,CAAC,kBAAkB,UAAU,CAAC;AAC1E;AAMO,SAAS,oBACd,YACA,QACmC;AACnC,QAAM,cAAc,YAAY,eAAe,CAAC;AAChD,QAAM,aAAa,YAAY;AAAA,IAC7B,CAAC,eAAe,WAAW,eAAe,UAAU,kBAAkB,UAAU;AAAA,EAClF;AACA,MAAI,WAAW,WAAW,EAAG,QAAO;AACpC,QAAM,UAAU,CAAC,GAAG,UAAU,EAAE,KAAK,CAAC,GAAG,OAAO,EAAE,YAAY,MAAM,EAAE,YAAY,EAAE;AACpF,SAAO,QAAQ,CAAC,KAAK;AACvB;AAEO,SAAS,uBACd,YACA,QACsE;AACtE,QAAM,QAAQ,YAAY,SAAS,CAAC,GAAG,KAAK,CAAC,cAAc,UAAU,WAAW,MAAM;AACtF,QAAM,YAAY,MAAM;AACxB,MAAI,CAAC,UAAW,QAAO;AACvB,QAAM,OAAO,UAAU;AACvB,MAAI,SAAS,UAAU,SAAS,0BAA0B,SAAS,eAAgB,QAAO;AAC1F,SAAO,EAAE,MAAM,eAAe,UAAU,cAAc;AACxD;AAOO,SAAS,yBACd,YACsE;AACtE,QAAM,UAAU,YAAY;AAC5B,MAAI,CAAC,QAAS,QAAO;AACrB,QAAM,cAAc,OAAO,QAAQ,eAAe,YAAY,QAAQ,WAAW,SAAS;AAC1F,QAAM,UAAU,OAAO,QAAQ,WAAW,YAAY,QAAQ,OAAO,SAAS;AAC9E,MAAI,gBAAgB,QAAS,QAAO;AACpC,MAAI,aAAa;AACf,WAAO,EAAE,YAAY,QAAQ,YAAsB,SAAS,QAAQ,QAAQ;AAAA,EAC9E;AACA,SAAO,EAAE,QAAQ,QAAQ,OAAiB;AAC5C;AAUO,SAAS,2BACd,YACA,QACqB;AACrB,QAAM,kBAAkB,oBAAoB,YAAY,MAAM;AAC9D,MAAI,gBAAiB,QAAO,EAAE,MAAM,SAAS,YAAY,gBAAgB;AAEzE,QAAM,YAAY,uBAAuB,YAAY,MAAM;AAC3D,MAAI,WAAW,SAAS,wBAAwB;AAC9C,WAAO,EAAE,MAAM,YAAY,eAAe,UAAU,cAAc;AAAA,EACpE;AACA,MAAI,WAAW,SAAS,eAAgB,QAAO,EAAE,MAAM,OAAO;AAE9D,QAAM,UAAU,yBAAyB,UAAU;AACnD,MAAI,WAAW,YAAY,WAAW,QAAQ,WAAW,QAAQ;AAC/D,WAAO,EAAE,MAAM,eAAe,QAAQ,QAAQ,OAAO;AAAA,EACvD;AAEA,SAAO,EAAE,MAAM,OAAO;AACxB;AAQO,SAAS,oBACd,YACmB;AACnB,QAAM,SAA4B,CAAC;AACnC,QAAM,cAAc,YAAY,eAAe,CAAC;AAChD,QAAM,UAAU,IAAI,KAAK,YAAY,SAAS,CAAC,GAAG,IAAI,CAAC,SAAS,KAAK,MAAM,EAAE,OAAO,OAAO,CAAC;AAE5F,aAAW,cAAc,aAAa;AACpC,QAAI,CAAC,kBAAkB,UAAU,EAAG;AAEpC,QAAI,WAAW,cAAc,QAAQ,OAAO,KAAK,CAAC,QAAQ,IAAI,WAAW,UAAU,GAAG;AACpF,aAAO,KAAK;AAAA,QACV,MAAM;AAAA,QACN,SAAS,eAAe,WAAW,gBAAgB,EAAE,2BAA2B,WAAW,UAAU;AAAA,QACrG,cAAc,WAAW;AAAA,QACzB,QAAQ,WAAW;AAAA,MACrB,CAAC;AAAA,IACH;AAEA,QAAI,WAAW,YAAY,QAAQ,OAAO,KAAK,CAAC,QAAQ,IAAI,WAAW,QAAQ,GAAG;AAChF,aAAO,KAAK;AAAA,QACV,MAAM;AAAA,QACN,SAAS,eAAe,WAAW,gBAAgB,EAAE,yBAAyB,WAAW,QAAQ;AAAA,QACjG,cAAc,WAAW;AAAA,QACzB,QAAQ,WAAW;AAAA,MACrB,CAAC;AAAA,IACH;AAEA,UAAM,WAAW,YAAY;AAAA,MAC3B,CAAC,UACC,CAAC,kBAAkB,KAAK,KACxB,MAAM,eAAe,WAAW,cAChC,MAAM,aAAa,WAAW;AAAA,IAClC;AACA,QAAI,UAAU;AACZ,aAAO,KAAK;AAAA,QACV,MAAM;AAAA,QACN,SAAS,eAAe,WAAW,gBAAgB,EAAE;AAAA,QACrD,cAAc,WAAW;AAAA,QACzB,QAAQ,WAAW;AAAA,MACrB,CAAC;AAAA,IACH;AAAA,EACF;AAEA,SAAO;AACT;",
+  "names": []
+}

package/dist/modules/workflows/lib/event-logger.js

@@ -46,6 +46,29 @@ const WorkflowEventTypes = {
   SIGNAL_AWAITING: "SIGNAL_AWAITING",
   SIGNAL_RECEIVED: "SIGNAL_RECEIVED",
   SIGNAL_TIMEOUT: "SIGNAL_TIMEOUT",
+  // Error routing (spec 5.9)
+  ERROR_ROUTED: "ERROR_ROUTED",
+  ERROR_DIRECTIVE_APPLIED: "ERROR_DIRECTIVE_APPLIED",
+  ERROR_PARKED: "ERROR_PARKED",
+  ERROR_HANDLER_SCHEDULED: "ERROR_HANDLER_SCHEDULED",
+  ERROR_HANDLER_STARTED: "ERROR_HANDLER_STARTED",
+  ERROR_HANDLER_SKIPPED: "ERROR_HANDLER_SKIPPED",
+  // Recovery (spec 8.4). `STEP_RERUN` carries `{ stepId, editedContextDiff, by }`
+  // and is the audit record of a rerun — the terminal StepInstance of the
+  // previous attempt is never touched, so the event log is where the two
+  // attempts are linked.
+  STEP_RERUN: "STEP_RERUN",
+  // Agent outcome routing (spec 7.2)
+  OUTCOME_ROUTED: "OUTCOME_ROUTED",
+  OUTCOME_UNHANDLED: "OUTCOME_UNHANDLED",
+  // Dry run (spec 8.2). Written only by an `isDryRun` instance; the pure
+  // `lib/dry-run.ts` owns the same literals as `DRY_RUN_EVENT_TYPES` and builds
+  // the "Would do" report from them. A test pins the two lists together.
+  DRY_RUN_STARTED: "DRY_RUN_STARTED",
+  ACTIVITY_SIMULATED: "ACTIVITY_SIMULATED",
+  ACTIVITY_SIMULATION_REFUSED: "ACTIVITY_SIMULATION_REFUSED",
+  USER_TASK_SIMULATED: "USER_TASK_SIMULATED",
+  BUSINESS_RULE_ACTIONS_SUPPRESSED: "BUSINESS_RULE_ACTIONS_SUPPRESSED",
   // Timer events (Phase 9)
   TIMER_AWAITING: "TIMER_AWAITING",
   TIMER_FIRED: "TIMER_FIRED",