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

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

@@ -0,0 +1,236 @@
+/**
+ * Workflows Module - Error Routing (pure)
+ *
+ * Resolves what happens when a step fails, from the definition alone:
+ *
+ *   1. an outgoing transition marked `kind: 'error'` wins — the engine follows it
+ *      instead of failing the instance (spec 5.9 "error output handle");
+ *   2. otherwise the failed step's `errorDirective` applies
+ *      (`fail` | `continueWithFallback` | `failureQueue`);
+ *   3. otherwise the instance fails exactly as it does today.
+ *
+ * Definitions carrying neither an error transition nor a directive resolve to
+ * `fail`, which is the untouched legacy path — this module is the single place
+ * that decides, so the "no error config ⇒ identical trace" guarantee is testable.
+ *
+ * PURE: no ORM, DI, React or registry imports. Engine call sites pass the plain
+ * definition JSON.
+ */
+
+export const ERROR_TRANSITION_KIND = 'error'
+
+/**
+ * Canvas handle id every activity-bearing node exposes for its error output. A
+ * connection drawn from it compiles to a transition with `kind: 'error'`. Lives
+ * in this pure module so `graph-utils` can read it without pulling the React
+ * component chain (enforced by the xyflow import-boundary test).
+ */
+export const ERROR_SOURCE_HANDLE_ID = 'error'
+
+/**
+ * Run-context key carrying the failure that caused an error route to be taken,
+ * so the handling branch can render/forward it. Engine-owned and reserved
+ * against user context writes.
+ */
+export const WORKFLOW_ERROR_CONTEXT_KEY = '__error'
+
+export interface WorkflowErrorContextEntry {
+  stepId: string
+  message: string
+  occurredAt: string
+}
+
+export function buildErrorContextEntry(stepId: string, message: string): WorkflowErrorContextEntry {
+  return { stepId, message, occurredAt: new Date().toISOString() }
+}
+
+export type WorkflowErrorDirectiveMode = 'fail' | 'continueWithFallback' | 'failureQueue'
+
+export interface ErrorRoutingTransitionLike {
+  transitionId?: string
+  fromStepId?: string
+  toStepId?: string
+  kind?: string
+  priority?: number
+}
+
+export interface ErrorRoutingStepLike {
+  stepId?: string
+  errorDirective?: {
+    mode?: string
+    fallbackValue?: unknown
+  } | null
+}
+
+export interface ErrorRoutingErrorHandlerLike {
+  workflowId?: string
+  version?: number
+  stepId?: string
+}
+
+export interface ErrorRoutingDefinitionLike {
+  steps?: ErrorRoutingStepLike[]
+  transitions?: ErrorRoutingTransitionLike[]
+  errorHandler?: ErrorRoutingErrorHandlerLike | null
+}
+
+export type StepFailureHandling =
+  | { kind: 'route'; transition: ErrorRoutingTransitionLike }
+  | { kind: 'continue'; fallbackValue?: unknown }
+  | { kind: 'park' }
+  | { kind: 'handlerStep'; stepId: string }
+  | { kind: 'fail' }
+
+export interface ErrorRouteIssue {
+  code: 'ERROR_ROUTE_DUPLICATE_TARGET' | 'ERROR_ROUTE_UNKNOWN_TARGET' | 'ERROR_ROUTE_UNKNOWN_SOURCE'
+  message: string
+  transitionId?: string
+  stepId?: string
+}
+
+/**
+ * A transition authored as an error route. The discriminator is the additive
+ * optional `kind` field: absent (or any other value) means a normal route, so
+ * every stored definition keeps its current meaning.
+ */
+export function isErrorTransition(transition: ErrorRoutingTransitionLike | null | undefined): boolean {
+  return transition?.kind === ERROR_TRANSITION_KIND
+}
+
+/**
+ * Error routes must never be taken by normal routing — they are only reachable
+ * from a failure. Every routing lookup filters through this helper.
+ */
+export function excludeErrorTransitions<T extends ErrorRoutingTransitionLike>(transitions: T[]): T[] {
+  return transitions.filter((transition) => !isErrorTransition(transition))
+}
+
+/**
+ * Highest-priority outgoing error route of a step. Ties keep definition order,
+ * mirroring how `findValidTransitions` orders normal routes.
+ */
+export function findErrorTransition(
+  definition: ErrorRoutingDefinitionLike | null | undefined,
+  stepId: string
+): ErrorRoutingTransitionLike | null {
+  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
+}
+
+export function readStepErrorDirective(
+  definition: ErrorRoutingDefinitionLike | null | undefined,
+  stepId: string
+): { mode: WorkflowErrorDirectiveMode; fallbackValue?: unknown } | null {
+  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 }
+}
+
+/**
+ * Definition-level catch-all handler (spec 5.9). Returns null unless exactly one
+ * form is declared, so a malformed handler degrades to today's behavior instead
+ * of guessing.
+ */
+export function readWorkflowErrorHandler(
+  definition: ErrorRoutingDefinitionLike | null | undefined
+): { workflowId: string; version?: number } | { stepId: string } | null {
+  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 as string, version: handler.version }
+  }
+  return { stepId: handler.stepId as string }
+}
+
+/**
+ * The single decision point for a failed step, in precedence order:
+ * wired error route → step directive → definition-level handler step → fail.
+ * The handler step comes last because it is a catch-all, and a step never jumps
+ * to itself, which is the recursion guard for the in-instance handler form.
+ * `fail` is both the explicit directive and the absent-config default, so legacy
+ * definitions never diverge.
+ */
+export function resolveStepFailureHandling(
+  definition: ErrorRoutingDefinitionLike | null | undefined,
+  stepId: string
+): StepFailureHandling {
+  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' }
+}
+
+/**
+ * Author-time checks surfaced by the Problems panel. An error route sharing its
+ * source AND target with a normal route is rejected because the engine resolves
+ * a followed route by its `(fromStepId, toStepId)` pair — the pair would be
+ * ambiguous and the wrong activities could run.
+ */
+export function validateErrorRoutes(
+  definition: ErrorRoutingDefinitionLike | null | undefined
+): ErrorRouteIssue[] {
+  const issues: ErrorRouteIssue[] = []
+  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
+}

package/src/modules/workflows/lib/event-logger.ts

@@ -72,6 +72,33 @@ export const WorkflowEventTypes = {
   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',

package/src/modules/workflows/lib/expression-refs.ts

@@ -0,0 +1,291 @@
+/**
+ * Workflows Module - context expression reference extraction and ledger check
+ * (spec 2026-07-26-workflows-ux-redesign.md section 3.5).
+ *
+ * Pure, dependency-free (browser-safe) helpers that find every `{{context.*}}`
+ * reference a workflow definition makes and check each one against the
+ * per-step context ledger (`lib/context-ledger.ts`), so the editor can warn —
+ * never block — when an expression references context no producer provides.
+ *
+ * Grammar — mirrors `interpolateVariables` in `lib/activity-executor.ts`:
+ * `{{ path }}` tokens inside string values; `workflow.*`, `env.*`, and `now`
+ * are engine-provided and always valid, so they are skipped; every other token
+ * is a context reference, with an optional leading `context.` stripped (the
+ * interpolator defaults bare paths to context lookups). Tokens may carry a
+ * transform pipeline tail (`{{ path | fn(args) }}`) — the shared parser in
+ * `lib/interpolation-pipeline.ts` strips it so the ledger check validates the
+ * base path only; unparseable tokens are skipped (warnings-only surface, so
+ * false negatives beat false positives).
+ *
+ * Extraction surfaces, each verified against the runtime consumer:
+ * - Step and transition activity `config` values (all strings, recursively) —
+ *   interpolated by `interpolateVariables` before execution.
+ * - `subWorkflowConfig.inputMapping` values — `mapInputData` in
+ *   `lib/step-handler.ts` treats each value as a bare parent-context dot path
+ *   via `getNestedValue` (no `{{}}` interpolation), so bare values are
+ *   extracted whole; values containing `{{` fall back to template extraction.
+ *   `outputMapping` values read the CHILD workflow's context, which this
+ *   ledger cannot see — they are deliberately not extracted.
+ * - Trigger `contextMapping[].sourceExpression` — `event-trigger-service.ts`
+ *   resolves these against the EVENT PAYLOAD, not workflow context, so bare
+ *   values are payload paths and are skipped; only `{{context.*}}` templates
+ *   (which never interpolate there) are extracted, and their trigger scope is
+ *   not ledger-checkable, so `findUnresolvedRefs` skips them.
+ *
+ * Scope resolution in `findUnresolvedRefs`:
+ * - A STEP activity's refs check against that step's incoming ledger view
+ *   (`ledger.steps[stepId]`) — the context persisted before the step runs.
+ * - A TRANSITION activity's refs conceptually check against the SOURCE step's
+ *   OUTGOING view (transition activities run after the source step completes).
+ *   The ledger only publishes per-step INCOMING views, and the TARGET step's
+ *   incoming view is exactly source-outgoing plus the transition's own
+ *   contributions on the single-route case, only widening (set union) where
+ *   the target joins multiple routes — an over-approximation that can only
+ *   suppress warnings, never fabricate them. Transition refs therefore check
+ *   `ledger.steps[toStepId]`.
+ *
+ * Resolution rules (warnings-only, so false negatives beat false positives):
+ * - A `'*'` wildcard entry (unknown flat payload spread from triggers or
+ *   signals) resolves every ref — absence cannot be proven under it.
+ * - Exact path match resolves.
+ * - Prefix match resolves: ref `customer.name` resolves when entry `customer`
+ *   exists with type `object`/`unknown`; ref `customer` resolves when any
+ *   entry under `customer.` exists (the ref names a known ancestor).
+ */
+
+import type { ContextLedger, LedgerEntry } from './context-ledger'
+import { parseInterpolationToken } from './interpolation-pipeline'
+
+export interface ContextRefLocation {
+  stepIndex?: number
+  transitionIndex?: number
+  triggerIndex?: number
+  activityIndex?: number
+  field: string
+}
+
+export type ContextRefScope =
+  | { kind: 'step'; stepId: string }
+  | { kind: 'transition'; fromStepId: string; toStepId: string }
+  | { kind: 'trigger'; triggerId: string }
+
+export interface ContextRef {
+  path: string
+  location: ContextRefLocation
+  scope: ContextRefScope
+}
+
+export interface UnresolvedContextRef {
+  ref: ContextRef
+  stepId: string
+}
+
+export interface UnresolvedContextRefWarning {
+  path: Array<string | number>
+  refPath: string
+}
+
+export interface ExpressionRefDefinition {
+  steps?: unknown
+  transitions?: unknown
+  triggers?: unknown
+}
+
+const TEMPLATE_PATTERN = /\{\{([^}]+)\}\}/g
+const CONTEXT_PREFIX = 'context.'
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function normalizeContextPath(token: string): string | null {
+  const parsed = parseInterpolationToken(token)
+  if (!parsed.ok) return null
+  const basePath = parsed.path
+  if (basePath === 'now') return null
+  if (basePath.startsWith('workflow.')) return null
+  if (basePath.startsWith('env.')) return null
+  const path = basePath.startsWith(CONTEXT_PREFIX) ? basePath.slice(CONTEXT_PREFIX.length) : basePath
+  return path.length > 0 ? path : null
+}
+
+function contextPathsInTemplate(value: string): string[] {
+  const paths: string[] = []
+  for (const match of value.matchAll(TEMPLATE_PATTERN)) {
+    const path = normalizeContextPath(match[1])
+    if (path !== null) paths.push(path)
+  }
+  return paths
+}
+
+function pathsFromMappingValue(value: string): string[] {
+  if (value.includes('{{')) return contextPathsInTemplate(value)
+  const path = normalizeContextPath(value)
+  return path !== null ? [path] : []
+}
+
+function collectValueRefs(
+  value: unknown,
+  field: string,
+  push: (path: string, field: string) => void,
+): void {
+  if (typeof value === 'string') {
+    for (const path of contextPathsInTemplate(value)) push(path, field)
+    return
+  }
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => collectValueRefs(item, `${field}.${index}`, push))
+    return
+  }
+  if (isPlainObject(value)) {
+    for (const [key, child] of Object.entries(value)) {
+      collectValueRefs(child, `${field}.${key}`, push)
+    }
+  }
+}
+
+function collectActivityRefs(
+  activities: unknown,
+  baseLocation: Pick<ContextRefLocation, 'stepIndex' | 'transitionIndex'>,
+  scope: ContextRefScope,
+  refs: ContextRef[],
+): void {
+  if (!Array.isArray(activities)) return
+  activities.forEach((activity, activityIndex) => {
+    if (!isPlainObject(activity)) return
+    collectValueRefs(activity.config, 'config', (path, field) => {
+      refs.push({ path, location: { ...baseLocation, activityIndex, field }, scope })
+    })
+  })
+}
+
+function collectStepRefs(steps: unknown, refs: ContextRef[]): void {
+  if (!Array.isArray(steps)) return
+  steps.forEach((rawStep, stepIndex) => {
+    if (!isPlainObject(rawStep) || typeof rawStep.stepId !== 'string' || !rawStep.stepId) return
+    const scope: ContextRefScope = { kind: 'step', stepId: rawStep.stepId }
+    collectActivityRefs(rawStep.activities, { stepIndex }, scope, refs)
+
+    const subWorkflowConfig = rawStep.subWorkflowConfig
+    if (!isPlainObject(subWorkflowConfig) || !isPlainObject(subWorkflowConfig.inputMapping)) return
+    for (const [targetKey, sourcePath] of Object.entries(subWorkflowConfig.inputMapping)) {
+      if (typeof sourcePath !== 'string') continue
+      const field = `subWorkflowConfig.inputMapping.${targetKey}`
+      for (const path of pathsFromMappingValue(sourcePath)) {
+        refs.push({ path, location: { stepIndex, field }, scope })
+      }
+    }
+  })
+}
+
+function collectTransitionRefs(transitions: unknown, refs: ContextRef[]): void {
+  if (!Array.isArray(transitions)) return
+  transitions.forEach((rawTransition, transitionIndex) => {
+    if (!isPlainObject(rawTransition)) return
+    const fromStepId = rawTransition.fromStepId
+    const toStepId = rawTransition.toStepId
+    if (typeof fromStepId !== 'string' || !fromStepId) return
+    if (typeof toStepId !== 'string' || !toStepId) return
+    const scope: ContextRefScope = { kind: 'transition', fromStepId, toStepId }
+    collectActivityRefs(rawTransition.activities, { transitionIndex }, scope, refs)
+  })
+}
+
+function collectTriggerRefs(triggers: unknown, refs: ContextRef[]): void {
+  if (!Array.isArray(triggers)) return
+  triggers.forEach((rawTrigger, triggerIndex) => {
+    if (!isPlainObject(rawTrigger)) return
+    const triggerId = typeof rawTrigger.triggerId === 'string' && rawTrigger.triggerId
+      ? rawTrigger.triggerId
+      : String(triggerIndex)
+    const config = rawTrigger.config
+    if (!isPlainObject(config) || !Array.isArray(config.contextMapping)) return
+    config.contextMapping.forEach((mapping, mappingIndex) => {
+      if (!isPlainObject(mapping) || typeof mapping.sourceExpression !== 'string') return
+      for (const path of contextPathsInTemplate(mapping.sourceExpression)) {
+        refs.push({
+          path,
+          location: { triggerIndex, field: `config.contextMapping.${mappingIndex}.sourceExpression` },
+          scope: { kind: 'trigger', triggerId },
+        })
+      }
+    })
+  })
+}
+
+export function extractContextRefs(definition: ExpressionRefDefinition): ContextRef[] {
+  const refs: ContextRef[] = []
+  collectStepRefs(definition.steps, refs)
+  collectTransitionRefs(definition.transitions, refs)
+  collectTriggerRefs(definition.triggers, refs)
+  return refs
+}
+
+function scopeStepId(scope: ContextRefScope): string | null {
+  if (scope.kind === 'step') return scope.stepId
+  if (scope.kind === 'transition') return scope.toStepId
+  return null
+}
+
+/**
+ * The shared ledger-resolution rule. Exported so other author-time checks that
+ * validate a context path (condition `field` paths, step 2.12) apply exactly the
+ * same over-approximating semantics instead of re-deriving them.
+ */
+export function resolvesAgainstEntries(refPath: string, entries: LedgerEntry[]): boolean {
+  for (const entry of entries) {
+    if (entry.path === '*') return true
+    if (entry.path === refPath) return true
+    if (
+      refPath.startsWith(`${entry.path}.`) &&
+      (entry.type === 'object' || entry.type === 'unknown')
+    ) {
+      return true
+    }
+    if (entry.path.startsWith(`${refPath}.`)) return true
+  }
+  return false
+}
+
+export function findUnresolvedRefs(refs: ContextRef[], ledger: ContextLedger): UnresolvedContextRef[] {
+  const unresolved: UnresolvedContextRef[] = []
+  for (const ref of refs) {
+    const stepId = scopeStepId(ref.scope)
+    if (stepId === null) continue
+    const view = ledger.steps[stepId]
+    if (!view) continue
+    if (!resolvesAgainstEntries(ref.path, view.entries)) {
+      unresolved.push({ ref, stepId })
+    }
+  }
+  return unresolved
+}
+
+function locationToIssuePath(location: ContextRefLocation): Array<string | number> {
+  const path: Array<string | number> = []
+  if (location.stepIndex !== undefined) path.push('steps', location.stepIndex)
+  else if (location.transitionIndex !== undefined) path.push('transitions', location.transitionIndex)
+  else if (location.triggerIndex !== undefined) path.push('triggers', location.triggerIndex)
+  if (location.activityIndex !== undefined) path.push('activities', location.activityIndex)
+  for (const segment of location.field.split('.')) {
+    path.push(/^\d+$/.test(segment) ? Number(segment) : segment)
+  }
+  return path
+}
+
+export function collectUnresolvedContextRefWarnings(
+  definition: ExpressionRefDefinition,
+  ledger: ContextLedger,
+): UnresolvedContextRefWarning[] {
+  const unresolved = findUnresolvedRefs(extractContextRefs(definition), ledger)
+  const seen = new Set<string>()
+  const warnings: UnresolvedContextRefWarning[] = []
+  for (const { ref } of unresolved) {
+    const issuePath = locationToIssuePath(ref.location)
+    const key = `${issuePath.join('.')}|${ref.path}`
+    if (seen.has(key)) continue
+    seen.add(key)
+    warnings.push({ path: issuePath, refPath: ref.path })
+  }
+  return warnings
+}

package/src/modules/workflows/lib/failure-grouping.ts

@@ -0,0 +1,134 @@
+/**
+ * Failure-queue error grouping (spec §8.4) — PURE.
+ *
+ * > "Failure queue + bulk replay: `Send to failure queue` directive parks
+ * > instances as ATTENTION; with FAILED instances they form a triage list with
+ * > error grouping; bulk retry/cancel runs through the progress module."
+ *
+ * A triage list is only useful if 400 failures collapse into the four things
+ * that actually broke. Grouping on the raw message never does that: every row
+ * carries its own order id, its own timestamp, its own retry count. So each
+ * message is normalized into a SHAPE — identifiers, numbers, quoted values and
+ * timestamps replaced by placeholders — and rows are grouped on the shape while
+ * the first raw message is kept as the human label.
+ *
+ * The normalization is deliberately conservative. Over-normalizing merges two
+ * genuinely different failures, which is worse than showing them apart: an
+ * operator who sees two groups can still bulk-replay both, but one who sees a
+ * merged group cannot tell that half of it will fail again.
+ */
+
+/** Longest label kept for a group; the full message stays on each instance. */
+export const FAILURE_GROUP_LABEL_MAX = 160
+
+const UUID = /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/gi
+const ISO_TIMESTAMP = /\b\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:\.\d+)?Z?\b/g
+const QUOTED = /(["'`])(?:(?!\1)[^\\]|\\.)*\1/g
+const HEX_BLOB = /\b[0-9a-f]{12,}\b/gi
+const NUMBER = /\b\d+(?:\.\d+)?\b/g
+const WHITESPACE = /\s+/g
+
+export type TriageInstanceInput = {
+  id: string
+  workflowId: string
+  status: string
+  errorMessage?: string | null
+  /** `metadata.attention.reason` when the instance was parked by a directive. */
+  attentionReason?: string | null
+  /** The run's verdict; a `partial_failure` carries no `errorMessage` of its own. */
+  outcome?: string | null
+}
+
+export type FailureGroup = {
+  /** Stable key for the normalized shape — safe to use as a filter value. */
+  key: string
+  /** First raw message seen for this shape, truncated for display. */
+  label: string
+  count: number
+  /** Distinct workflow ids in the group, so a cross-workflow failure is visible. */
+  workflowIds: string[]
+  /** Instance ids in the group, in the order they were scanned. */
+  instanceIds: string[]
+}
+
+/**
+ * Reduce an error message to its shape. Two messages that differ only in the
+ * ids/numbers/quoted values they mention normalize to the same string.
+ */
+export function normalizeFailureMessage(message: string): string {
+  return message
+    .replace(UUID, '{id}')
+    .replace(ISO_TIMESTAMP, '{time}')
+    .replace(QUOTED, '{value}')
+    .replace(HEX_BLOB, '{hex}')
+    .replace(NUMBER, '{n}')
+    .replace(WHITESPACE, ' ')
+    .trim()
+}
+
+const UNCLASSIFIED_KEY = 'unclassified'
+const UNCLASSIFIED_LABEL = 'No error message recorded'
+
+/**
+ * Fallback shape for a run that reached END while tolerating a failure. It has
+ * no `errorMessage` — the run did not fail — and no attention marker, so
+ * without this every partial failure in the tenant would collapse into the one
+ * meaningless `unclassified` bucket next to genuinely unlabelled rows.
+ */
+const PARTIAL_FAILURE_LABEL = 'Completed with tolerated failures'
+
+function truncate(value: string): string {
+  return value.length <= FAILURE_GROUP_LABEL_MAX ? value : `${value.slice(0, FAILURE_GROUP_LABEL_MAX - 1)}…`
+}
+
+/**
+ * The message a group is derived from. A parked instance often has no
+ * `errorMessage` of its own — the directive recorded WHY it parked in
+ * `metadata.attention.reason` — so that is the fallback rather than dumping
+ * every parked run into one meaningless bucket.
+ */
+export function resolveFailureMessage(instance: TriageInstanceInput): string | null {
+  if (instance.errorMessage && instance.errorMessage.trim().length > 0) return instance.errorMessage.trim()
+  if (instance.attentionReason && instance.attentionReason.trim().length > 0) {
+    return instance.attentionReason.trim()
+  }
+  if (instance.outcome === 'partial_failure') return PARTIAL_FAILURE_LABEL
+  return null
+}
+
+export function groupFailures(instances: readonly TriageInstanceInput[]): FailureGroup[] {
+  const groups = new Map<string, FailureGroup>()
+
+  for (const instance of instances) {
+    const message = resolveFailureMessage(instance)
+    const key = message ? normalizeFailureMessage(message) : UNCLASSIFIED_KEY
+    const existing = groups.get(key)
+    if (existing) {
+      existing.count += 1
+      existing.instanceIds.push(instance.id)
+      if (!existing.workflowIds.includes(instance.workflowId)) {
+        existing.workflowIds.push(instance.workflowId)
+      }
+      continue
+    }
+    groups.set(key, {
+      key,
+      label: truncate(message ?? UNCLASSIFIED_LABEL),
+      count: 1,
+      workflowIds: [instance.workflowId],
+      instanceIds: [instance.id],
+    })
+  }
+
+  // Biggest group first — that is the one worth fixing. Ties break on the key
+  // so the ordering is stable across requests rather than hash-order.
+  return [...groups.values()].sort(
+    (left, right) => right.count - left.count || left.key.localeCompare(right.key)
+  )
+}
+
+/** Does this instance belong to the given group? Used to narrow the triage list. */
+export function matchesFailureGroup(instance: TriageInstanceInput, groupKey: string): boolean {
+  const message = resolveFailureMessage(instance)
+  return (message ? normalizeFailureMessage(message) : UNCLASSIFIED_KEY) === groupKey
+}