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

package/src/modules/workflows/lib/business-rule-usage.ts

@@ -0,0 +1,154 @@
+/**
+ * Workflows Module - Business Rule Usage Lookup
+ *
+ * Answers "which workflows reference this business rule?" for the dependency
+ * visibility panel that ships with the inline BR editor (spec
+ * 2026-07-26-workflows-ux-redesign.md team decision #5, issue #4236).
+ *
+ * The direction matters: `business_rules` owns the editor and exposes a slot,
+ * and every consuming module resolves its OWN usage. So this lookup lives here,
+ * scans workflow definitions, and never asks business_rules for anything —
+ * business_rules stays free of a workflows import (core AGENTS.md §
+ * Cross-Module Coupling).
+ *
+ * `collectBusinessRuleUsage` is PURE (plain definition JSON in, references out)
+ * so it is unit-testable without a database; `findBusinessRuleUsage` is the
+ * tenant-scoped query wrapper, modelled on `caller-graph.ts`.
+ */
+
+import type { EntityManager } from '@mikro-orm/core'
+
+export type BusinessRuleUsageKind = 'startPreCondition' | 'transitionPreCondition' | 'transitionPostCondition'
+
+export interface BusinessRuleUsageReference {
+  workflowId: string
+  version: number
+  workflowName?: string
+  kind: BusinessRuleUsageKind
+  /** Step id for START pre-conditions, transition id for transition conditions. */
+  locationId: string
+}
+
+export interface BusinessRuleUsageDefinition {
+  workflowId: string
+  version: number
+  name?: string
+  definition: unknown
+}
+
+function readConditionRuleIds(raw: unknown): string[] {
+  if (!Array.isArray(raw)) return []
+  const ids: string[] = []
+  for (const entry of raw) {
+    if (typeof entry === 'string') {
+      ids.push(entry)
+      continue
+    }
+    if (entry && typeof entry === 'object') {
+      const ruleId = (entry as { ruleId?: unknown }).ruleId
+      if (typeof ruleId === 'string' && ruleId.length > 0) ids.push(ruleId)
+    }
+  }
+  return ids
+}
+
+/**
+ * Every place a definition can name a business rule: START step pre-conditions
+ * and transition pre/post-conditions (`data/validators.ts`
+ * `startPreConditionSchema` / `transitionConditionSchema`). Inline
+ * `transition.condition` expressions are NOT rule references — they are
+ * embedded expressions with no rule identity — so they are deliberately absent.
+ */
+export function collectBusinessRuleUsage(
+  definitions: BusinessRuleUsageDefinition[],
+  ruleId: string,
+): BusinessRuleUsageReference[] {
+  if (!ruleId) return []
+  const references: BusinessRuleUsageReference[] = []
+
+  for (const candidate of definitions) {
+    const data = (candidate.definition ?? {}) as { steps?: unknown; transitions?: unknown }
+    const steps = Array.isArray(data.steps) ? data.steps : []
+    const transitions = Array.isArray(data.transitions) ? data.transitions : []
+
+    for (const step of steps) {
+      const stepId = (step as { stepId?: unknown })?.stepId
+      if (typeof stepId !== 'string') continue
+      if (readConditionRuleIds((step as { preConditions?: unknown }).preConditions).includes(ruleId)) {
+        references.push({
+          workflowId: candidate.workflowId,
+          version: candidate.version,
+          ...(candidate.name ? { workflowName: candidate.name } : {}),
+          kind: 'startPreCondition',
+          locationId: stepId,
+        })
+      }
+    }
+
+    for (const transition of transitions) {
+      const transitionId = (transition as { transitionId?: unknown })?.transitionId
+      if (typeof transitionId !== 'string') continue
+      if (readConditionRuleIds((transition as { preConditions?: unknown }).preConditions).includes(ruleId)) {
+        references.push({
+          workflowId: candidate.workflowId,
+          version: candidate.version,
+          ...(candidate.name ? { workflowName: candidate.name } : {}),
+          kind: 'transitionPreCondition',
+          locationId: transitionId,
+        })
+      }
+      if (readConditionRuleIds((transition as { postConditions?: unknown }).postConditions).includes(ruleId)) {
+        references.push({
+          workflowId: candidate.workflowId,
+          version: candidate.version,
+          ...(candidate.name ? { workflowName: candidate.name } : {}),
+          kind: 'transitionPostCondition',
+          locationId: transitionId,
+        })
+      }
+    }
+  }
+
+  return references
+}
+
+/** Distinct workflows (by `workflowId`) touched by the supplied references. */
+export function countReferencingWorkflows(references: BusinessRuleUsageReference[]): number {
+  return new Set(references.map((reference) => reference.workflowId)).size
+}
+
+/**
+ * Tenant/org-scoped scan of workflow definitions for `ruleId`. Uses jsonb `@>`
+ * containment (GIN-indexed on `workflow_definitions.definition`) so only rows
+ * that actually name the rule are materialised, then re-checks them with the
+ * pure collector to attach exact locations.
+ */
+export async function findBusinessRuleUsage(
+  em: EntityManager,
+  options: { ruleId: string; tenantId: string; organizationId: string },
+): Promise<BusinessRuleUsageReference[]> {
+  const { ruleId, tenantId, organizationId } = options
+  if (!ruleId) return []
+
+  const containments = [
+    JSON.stringify({ steps: [{ preConditions: [{ ruleId }] }] }),
+    JSON.stringify({ transitions: [{ preConditions: [{ ruleId }] }] }),
+    JSON.stringify({ transitions: [{ postConditions: [{ ruleId }] }] }),
+  ]
+
+  const rows = (await em.getConnection().execute(
+    `select workflow_id, version, workflow_name, definition from workflow_definitions
+     where tenant_id = ? and organization_id = ? and deleted_at is null
+       and (definition @> ?::jsonb or definition @> ?::jsonb or definition @> ?::jsonb)`,
+    [tenantId, organizationId, ...containments],
+  )) as Array<{ workflow_id: string; version: number; workflow_name: string | null; definition: unknown }>
+
+  const definitions: BusinessRuleUsageDefinition[] = rows.map((row) => ({
+    workflowId: row.workflow_id,
+    version: row.version,
+    ...(row.workflow_name ? { name: row.workflow_name } : {}),
+    definition: typeof row.definition === 'string' ? JSON.parse(row.definition) : row.definition,
+  }))
+
+  return collectBusinessRuleUsage(definitions, ruleId)
+}

package/src/modules/workflows/lib/caller-graph.ts

@@ -0,0 +1,104 @@
+/**
+ * Workflows Module - Sub-workflow Caller Graph
+ *
+ * Finds the parent definitions that invoke a given sub-workflow and computes
+ * which of their field mappings a port-schema change would break. Used by the
+ * publish flow and the breaking-change preview endpoint.
+ *
+ * The caller scan uses a tenant-scoped jsonb `@>` containment query (backed by
+ * the GIN index on `workflow_definitions.definition`); the impact diff is a pure
+ * function so it can be unit-tested without a database.
+ */
+
+import type { EntityManager } from '@mikro-orm/core'
+import { WorkflowDefinition } from '../data/entities'
+import type { PortField, WorkflowIoContract } from '../data/validators'
+
+export interface CallerImpact {
+  workflowId: string
+  version: number
+  stepId: string
+  brokenMappings: string[]
+}
+
+interface CallerDefinition {
+  workflowId: string
+  version: number
+  definition: any
+}
+
+/**
+ * Compute, for each caller, the mappings that reference a port no longer present
+ * in `ports`. Input mappings are keyed by child INPUT port name; output mappings
+ * are keyed by parent key with values that are dot-paths whose first segment is a
+ * child OUTPUT port name.
+ */
+export function computeCallerImpacts(
+  callers: CallerDefinition[],
+  subWorkflowId: string,
+  ports: WorkflowIoContract,
+): CallerImpact[] {
+  const inputNames = new Set((ports.inputs || []).map((port: PortField) => port.name))
+  const outputNames = new Set((ports.outputs || []).map((port: PortField) => port.name))
+  const impacts: CallerImpact[] = []
+
+  for (const caller of callers) {
+    const steps: any[] = Array.isArray(caller.definition?.steps) ? caller.definition.steps : []
+    for (const step of steps) {
+      if (step?.stepType !== 'SUB_WORKFLOW') continue
+      if (step?.config?.subWorkflowId !== subWorkflowId) continue
+
+      const broken: string[] = []
+
+      const inputMapping: Record<string, string> = step.config?.inputMapping || {}
+      for (const childPortKey of Object.keys(inputMapping)) {
+        if (!inputNames.has(childPortKey)) broken.push(`input:${childPortKey}`)
+      }
+
+      const outputMapping: Record<string, string> = step.config?.outputMapping || {}
+      for (const childPath of Object.values(outputMapping)) {
+        const portName = String(childPath).split('.')[0]
+        if (!outputNames.has(portName)) broken.push(`output:${childPath}`)
+      }
+
+      if (broken.length > 0) {
+        impacts.push({
+          workflowId: caller.workflowId,
+          version: caller.version,
+          stepId: step.stepId,
+          brokenMappings: broken,
+        })
+      }
+    }
+  }
+
+  return impacts
+}
+
+/**
+ * Find parent definitions that invoke `subWorkflowId` and compute their breaking
+ * mappings against the supplied published port contract. Tenant/org scoped.
+ */
+export async function findSubWorkflowCallers(
+  em: EntityManager,
+  options: { subWorkflowId: string; tenantId: string; organizationId: string; ports: WorkflowIoContract },
+): Promise<CallerImpact[]> {
+  const { subWorkflowId, tenantId, organizationId, ports } = options
+  const containment = JSON.stringify({
+    steps: [{ stepType: 'SUB_WORKFLOW', config: { subWorkflowId } }],
+  })
+
+  const rows = (await em.getConnection().execute(
+    `select workflow_id, version, definition from workflow_definitions
+     where tenant_id = ? and organization_id = ? and deleted_at is null and definition @> ?::jsonb`,
+    [tenantId, organizationId, containment],
+  )) as Array<{ workflow_id: string; version: number; definition: any }>
+
+  const callers: CallerDefinition[] = rows.map((row) => ({
+    workflowId: row.workflow_id,
+    version: row.version,
+    definition: typeof row.definition === 'string' ? JSON.parse(row.definition) : row.definition,
+  }))
+
+  return computeCallerImpacts(callers, subWorkflowId, ports)
+}

package/src/modules/workflows/lib/code-view-apply.ts

@@ -0,0 +1,178 @@
+/**
+ * Workflows Module — Code view stage 2, the apply gate (spec section 2.2)
+ *
+ * ## The safety model, and why this one
+ *
+ * Stage 2 asks for *"two-way live sync"*. Taken literally — mutate the canvas
+ * on every keystroke — it is unimplementable safely: deleting the `s` of
+ * `"steps"` momentarily produces a document with no steps, and applying it
+ * would delete every node, blow away the arrangement and push an undo entry
+ * per character. So the two directions get the treatment each can actually
+ * support:
+ *
+ * - **canvas → code is LIVE.** The panel re-renders from the canvas whenever
+ *   the author has not started editing. This is the direction with no risk:
+ *   the canvas is already the source of truth.
+ * - **code → canvas is EXPLICIT.** The textarea is a local draft; the author
+ *   presses Apply (or Cmd/Ctrl+Enter). Parsing and validation are still LIVE —
+ *   squiggles, the issue list and the Apply button's enabled state all update
+ *   as you type — so the feedback loop is immediate even though the commit is
+ *   not.
+ *
+ * `evaluateCodeViewDraft` is that gate, and it is PURE so the rule is testable
+ * without a canvas. It refuses in four escalating ways, each with a distinct
+ * reason the UI can explain:
+ *
+ * 1. `unchanged` — nothing to apply.
+ * 2. `parseError` — not JSON. Carries the line so the editor can point at it.
+ * 3. `schemaError` — parses, but is not a workflow definition.
+ * 4. `graphError` — a valid definition whose GRAPH is broken (no START, an
+ *    unreachable step, a route to nowhere). Warnings do NOT block, exactly as
+ *    they do not block a Save.
+ *
+ * Refusing on graph errors is the difference between this and a "just apply
+ * whatever parses" design. A canvas holding a graph the engine would reject is
+ * a canvas the author has to repair by hand, and they no longer have the JSON
+ * they typed — the textarea now mirrors the broken result.
+ */
+
+import type { WorkflowValidationIssueSeverity } from './collect-validation-issues'
+
+export type CodeViewApplyRefusal =
+  | { ok: false; reason: 'unchanged' }
+  | { ok: false; reason: 'parseError'; message: string; line: number | null }
+  | { ok: false; reason: 'schemaError'; messages: string[] }
+  | { ok: false; reason: 'graphError'; messages: string[] }
+
+export type CodeViewApplyDecision<TDefinition> =
+  | { ok: true; definition: TDefinition }
+  | CodeViewApplyRefusal
+
+export type CodeViewDraftInput<TDefinition> = {
+  draftText: string
+  /**
+   * The JSON the canvas currently serializes to.
+   *
+   * OMIT it when there is no such text to compare against — an AI-generated
+   * draft (spec section 9) is a document the author asked for, so "identical to
+   * the canvas" is not a refusal, it is a coincidence. Every other refusal
+   * still applies, which is the point: a generated definition passes the same
+   * gate a pasted one does.
+   */
+  canvasText?: string
+  parseDefinition: (parsed: unknown) => { ok: true; definition: TDefinition } | { ok: false; messages: string[] }
+  /**
+   * Graph-level validation of the parsed definition. Return only ERRORS —
+   * warnings never block an apply, for the same reason they never block a save.
+   */
+  validateGraph: (definition: TDefinition) => string[]
+}
+
+/**
+ * Extract the 1-based line number from a `JSON.parse` error message.
+ *
+ * Engines disagree on the wording, and some report only a character position,
+ * so this is deliberately best-effort: a missing line means "no gutter marker",
+ * never a marker on the wrong line.
+ */
+export function parseErrorLine(message: string, text: string): number | null {
+  const lineMatch = /line (\d+)/i.exec(message)
+  if (lineMatch) {
+    const parsed = Number.parseInt(lineMatch[1], 10)
+    if (Number.isFinite(parsed) && parsed > 0) return parsed
+  }
+  const positionMatch = /position (\d+)/i.exec(message)
+  if (positionMatch) {
+    const offset = Number.parseInt(positionMatch[1], 10)
+    if (!Number.isFinite(offset) || offset < 0) return null
+    let line = 1
+    for (let index = 0; index < Math.min(offset, text.length); index += 1) {
+      if (text[index] === '\n') line += 1
+    }
+    return line
+  }
+  return null
+}
+
+export function evaluateCodeViewDraft<TDefinition>(
+  input: CodeViewDraftInput<TDefinition>,
+): CodeViewApplyDecision<TDefinition> {
+  const { draftText, canvasText, parseDefinition, validateGraph } = input
+
+  if (canvasText !== undefined && draftText === canvasText) {
+    return { ok: false, reason: 'unchanged' }
+  }
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(draftText)
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    return { ok: false, reason: 'parseError', message, line: parseErrorLine(message, draftText) }
+  }
+
+  const definitionResult = parseDefinition(parsed)
+  if (!definitionResult.ok) {
+    return { ok: false, reason: 'schemaError', messages: definitionResult.messages }
+  }
+
+  const graphErrors = validateGraph(definitionResult.definition)
+  if (graphErrors.length > 0) {
+    return { ok: false, reason: 'graphError', messages: graphErrors }
+  }
+
+  return { ok: true, definition: definitionResult.definition }
+}
+
+export type CodeViewDraftStatus = {
+  dirty: boolean
+  canApply: boolean
+  /** Line the editor should mark as the parse failure, when there is one. */
+  parseErrorLine: number | null
+  parseErrorMessage: string | null
+  blockingMessages: string[]
+  blockingSeverity: WorkflowValidationIssueSeverity | null
+}
+
+export function describeCodeViewDraft<TDefinition>(
+  decision: CodeViewApplyDecision<TDefinition>,
+): CodeViewDraftStatus {
+  if (decision.ok) {
+    return {
+      dirty: true,
+      canApply: true,
+      parseErrorLine: null,
+      parseErrorMessage: null,
+      blockingMessages: [],
+      blockingSeverity: null,
+    }
+  }
+  if (decision.reason === 'unchanged') {
+    return {
+      dirty: false,
+      canApply: false,
+      parseErrorLine: null,
+      parseErrorMessage: null,
+      blockingMessages: [],
+      blockingSeverity: null,
+    }
+  }
+  if (decision.reason === 'parseError') {
+    return {
+      dirty: true,
+      canApply: false,
+      parseErrorLine: decision.line,
+      parseErrorMessage: decision.message,
+      blockingMessages: [decision.message],
+      blockingSeverity: 'error',
+    }
+  }
+  return {
+    dirty: true,
+    canApply: false,
+    parseErrorLine: null,
+    parseErrorMessage: null,
+    blockingMessages: decision.messages,
+    blockingSeverity: 'error',
+  }
+}

package/src/modules/workflows/lib/collect-validation-issues.ts

@@ -0,0 +1,239 @@
+import type { Node, Edge } from '@xyflow/react'
+import type { ValidationError } from './graph-utils'
+import type { ContextLedger } from './context-ledger'
+import {
+  collectFlowLogicWarnings,
+  type FlowLogicDefinition,
+  type FlowLogicWarningCode,
+  type TaskAssigneeEntityAccess,
+} from './flow-logic-warnings'
+
+export type WorkflowValidationIssueSeverity = 'error' | 'warning'
+
+export interface WorkflowValidationIssue {
+  id: string
+  severity: WorkflowValidationIssueSeverity
+  message: string
+  nodeId?: string
+  edgeId?: string
+  nodeLabel?: string
+}
+
+export interface ZodIssueLike {
+  path: Array<string | number | symbol>
+  message: string
+}
+
+/**
+ * Message keys for the Phase 3a flow-logic warnings. English fallbacks live with
+ * the translator so a caller without an i18n dictionary still gets readable
+ * text.
+ */
+export const FLOW_LOGIC_MESSAGE_KEYS: Record<FlowLogicWarningCode, { key: string; fallback: string }> = {
+  errorRouteUnknownSource: {
+    key: 'workflows.visualEditor.problems.errorRouteUnknownSource',
+    fallback: 'Error route "{transitionId}" starts at unknown step "{stepId}"',
+  },
+  errorRouteUnknownTarget: {
+    key: 'workflows.visualEditor.problems.errorRouteUnknownTarget',
+    fallback: 'Error route "{transitionId}" targets unknown step "{stepId}"',
+  },
+  errorRouteDuplicateTarget: {
+    key: 'workflows.visualEditor.problems.errorRouteDuplicateTarget',
+    fallback: 'Error route "{transitionId}" shares its source and target with a normal route; the engine cannot tell them apart',
+  },
+  branchingWithoutOtherwise: {
+    key: 'workflows.visualEditor.problems.branchingWithoutOtherwise',
+    fallback: 'Branching step "{stepId}" has no unconditioned route; add an otherwise route so the workflow cannot stall when no condition matches',
+  },
+  duplicateBranchingCase: {
+    key: 'workflows.visualEditor.problems.duplicateBranchingCase',
+    fallback: 'Branching step "{stepId}" has more than one route for {caseValue}; only the highest-priority one can ever match',
+  },
+  conditionUnknownPath: {
+    key: 'workflows.visualEditor.problems.conditionUnknownPath',
+    fallback: 'Condition path "{path}" is not provided by any earlier step, trigger, or input',
+  },
+  unmappedStepConfig: {
+    key: 'workflows.visualEditor.problems.unmappedStepConfig',
+    fallback: 'Step "{stepId}" keeps unmapped configuration from an earlier type change ({keys}); it is stored but no longer executed',
+  },
+  taskDecisionUnknownRoute: {
+    key: 'workflows.visualEditor.problems.taskDecisionUnknownRoute',
+    fallback: 'Decision "{decisionId}" on task "{stepId}" points at route "{transitionId}", which no longer leaves this step',
+  },
+  taskDecisionDuplicateId: {
+    key: 'workflows.visualEditor.problems.taskDecisionDuplicateId',
+    fallback: 'Task "{stepId}" has more than one decision with the id "{decisionId}"; only one of them can ever be recorded',
+  },
+  taskWithoutOwner: {
+    key: 'workflows.visualEditor.problems.taskWithoutOwner',
+    fallback: 'Task "{stepId}" names neither an assignee nor a role queue, so nobody can complete it and the workflow will stall there',
+  },
+  taskPortalWithoutBinding: {
+    key: 'workflows.visualEditor.problems.taskPortalWithoutBinding',
+    fallback: 'Task "{stepId}" is addressed to a customer but is about no record; a portal task is only visible to the customer whose record it is linked to, so nobody in the portal would see it',
+  },
+  taskBindingUnknownEntityType: {
+    key: 'workflows.visualEditor.problems.taskBindingUnknownEntityType',
+    fallback: 'Task "{stepId}" is about "{entityType}", which is not a known record type; the task would be hidden from its own assignee',
+  },
+  outcomeRouteUnknownKind: {
+    key: 'workflows.visualEditor.problems.outcomeRouteUnknownKind',
+    fallback: 'Outcome route "{transitionId}" claims outcome "{outcomeKind}", which the platform does not define; it can never be selected',
+  },
+  outcomeRouteDuplicateKind: {
+    key: 'workflows.visualEditor.problems.outcomeRouteDuplicateKind',
+    fallback: 'Agent step "{stepId}" has more than one route for the "{outcomeKind}" outcome; only the highest-priority one can ever be taken',
+  },
+  taskBindingAssigneeCannotView: {
+    key: 'workflows.visualEditor.problems.taskBindingAssigneeCannotView',
+    fallback: 'Task "{stepId}" is about "{entityType}", which {roles} may not view; assignees holding only those roles would not see the task',
+  },
+}
+
+export type WorkflowIssueTranslator = (
+  key: string,
+  fallback: string,
+  params: Record<string, string>,
+) => string
+
+function interpolateFallback(template: string, params: Record<string, string>): string {
+  return template.replace(/\{(\w+)\}/g, (match, name: string) => params[name] ?? match)
+}
+
+const defaultTranslator: WorkflowIssueTranslator = (_key, fallback, params) =>
+  interpolateFallback(fallback, params)
+
+export interface CollectValidationIssuesInput {
+  graphErrors: ValidationError[]
+  zodIssues?: ZodIssueLike[]
+  configWarnings?: ZodIssueLike[]
+  nodes: Node[]
+  edges: Edge[]
+  /**
+   * Definition JSON for the Phase 3a checks (error routes, branching routes,
+   * condition paths). Omit it and only the legacy channels run.
+   */
+  definition?: FlowLogicDefinition | null
+  /** Context ledger enabling the condition-path resolution check. */
+  ledger?: ContextLedger
+  /**
+   * Generated entity ids that exist. Without it the unknown-binding check falls
+   * back to a shape test rather than flagging every id it cannot enumerate.
+   */
+  knownEntityIds?: ReadonlySet<string> | null
+  /** Tenant role features + entity view requirements, when the caller has them. */
+  assigneeEntityAccess?: TaskAssigneeEntityAccess | null
+  translate?: WorkflowIssueTranslator
+}
+
+function resolveNodeLabel(node: Node | undefined): string | undefined {
+  if (!node) return undefined
+  const label = node.data?.label
+  return typeof label === 'string' && label.length > 0 ? label : node.id
+}
+
+function mapZodPathToGraph(
+  path: Array<string | number | symbol>,
+  nodes: Node[],
+  edges: Edge[],
+): { nodeId?: string; edgeId?: string; nodeLabel?: string } {
+  const [collection, index] = path
+  if (typeof index !== 'number') return {}
+  if (collection === 'steps') {
+    const node = nodes[index]
+    if (!node) return {}
+    return { nodeId: node.id, nodeLabel: resolveNodeLabel(node) }
+  }
+  if (collection === 'transitions') {
+    const edge = edges[index]
+    if (!edge) return {}
+    return { edgeId: edge.id }
+  }
+  return {}
+}
+
+function formatZodPath(path: Array<string | number | symbol>): string {
+  return path.map((segment) => String(segment)).join('.')
+}
+
+export function collectValidationIssues(input: CollectValidationIssuesInput): WorkflowValidationIssue[] {
+  const {
+    graphErrors,
+    zodIssues = [],
+    configWarnings = [],
+    nodes,
+    edges,
+    definition,
+    ledger,
+    knownEntityIds = null,
+    assigneeEntityAccess = null,
+    translate = defaultTranslator,
+  } = input
+
+  const graphIssues: WorkflowValidationIssue[] = graphErrors.map((error, index) => ({
+    id: `graph-${index}`,
+    severity: error.type,
+    message: error.message,
+    ...(error.nodeId ? { nodeId: error.nodeId } : {}),
+    ...(error.edgeId ? { edgeId: error.edgeId } : {}),
+    ...(error.nodeId
+      ? { nodeLabel: resolveNodeLabel(nodes.find((node) => node.id === error.nodeId)) }
+      : {}),
+  }))
+
+  const schemaIssues: WorkflowValidationIssue[] = zodIssues.map((issue, index) => {
+    const pathText = formatZodPath(issue.path)
+    return {
+      id: `schema-${index}`,
+      severity: 'error',
+      message: pathText ? `${pathText} - ${issue.message}` : issue.message,
+      ...mapZodPathToGraph(issue.path, nodes, edges),
+    }
+  })
+
+  const configWarningIssues: WorkflowValidationIssue[] = configWarnings.map((issue, index) => {
+    const pathText = formatZodPath(issue.path)
+    return {
+      id: `config-${index}`,
+      severity: 'warning',
+      message: pathText ? `${pathText} - ${issue.message}` : issue.message,
+      ...mapZodPathToGraph(issue.path, nodes, edges),
+    }
+  })
+
+  // Phase 3a flow-logic + ledger checks default to WARNINGS: flow logic is
+  // transition sugar and a path a later edit will provide must never make the
+  // definition unsaveable. The §6.4 task checks opt into `error` because they
+  // describe a step the engine can never advance past — the same class as the
+  // structural problems `graphErrors` carries.
+  const flowLogicIssues: WorkflowValidationIssue[] = collectFlowLogicWarnings(definition, {
+    ledger,
+    knownEntityIds,
+    assigneeEntityAccess,
+  }).map((warning, index) => {
+    const message = FLOW_LOGIC_MESSAGE_KEYS[warning.code]
+    return {
+      id: `flow-${warning.code}-${index}`,
+      severity: warning.severity ?? 'warning',
+      message: translate(message.key, message.fallback, warning.params),
+      ...mapZodPathToGraph(warning.path, nodes, edges),
+    }
+  })
+
+  const all = [...graphIssues, ...schemaIssues, ...configWarningIssues, ...flowLogicIssues]
+  const errors = all.filter((issue) => issue.severity === 'error')
+  const warnings = all.filter((issue) => issue.severity === 'warning')
+  return [...errors, ...warnings]
+}
+
+export function countIssuesBySeverity(issues: WorkflowValidationIssue[]): { errors: number; warnings: number } {
+  let errors = 0
+  let warnings = 0
+  for (const issue of issues) {
+    if (issue.severity === 'error') errors += 1
+    else warnings += 1
+  }
+  return { errors, warnings }
+}