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

package/src/modules/workflows/lib/route-chip-events.ts

@@ -0,0 +1,45 @@
+/**
+ * Workflows Module - Route Chip Events
+ *
+ * Chips live inside React Flow's `EdgeLabelRenderer` portal, so a chip click
+ * never reaches the canvas' `onEdgeClick`. The chip therefore announces itself
+ * on `window` and the visual editor listens — the same decoupling the inline
+ * node-delete button uses (`WORKFLOW_NODE_DELETE_EVENT`), so no callback has to
+ * be threaded through the edge-data transform.
+ */
+
+import type { RouteChipSection } from './route-chips'
+
+export const WORKFLOW_ROUTE_CHIP_EVENT = 'workflow-route-chip:open'
+
+export interface RouteChipEventDetail {
+  edgeId: string
+  section: RouteChipSection
+}
+
+export function requestRouteChipSection(edgeId: string, section: RouteChipSection): void {
+  if (typeof window === 'undefined') return
+  window.dispatchEvent(
+    new CustomEvent<RouteChipEventDetail>(WORKFLOW_ROUTE_CHIP_EVENT, { detail: { edgeId, section } }),
+  )
+}
+
+/**
+ * A single activity chip announces which activity it is, so the editor can open
+ * a focused single-activity modal instead of the whole transition inspector.
+ */
+export const WORKFLOW_ROUTE_ACTIVITY_EVENT = 'workflow-route-activity:open'
+
+export interface RouteActivityEventDetail {
+  edgeId: string
+  activityId: string
+}
+
+export function requestRouteActivityEdit(edgeId: string, activityId: string): void {
+  if (typeof window === 'undefined') return
+  window.dispatchEvent(
+    new CustomEvent<RouteActivityEventDetail>(WORKFLOW_ROUTE_ACTIVITY_EVENT, {
+      detail: { edgeId, activityId },
+    }),
+  )
+}

package/src/modules/workflows/lib/route-chips.ts

@@ -0,0 +1,177 @@
+/**
+ * Workflows Module - Route Chips (pure)
+ *
+ * Derives what a transition renders ALONG its edge (spec
+ * 2026-07-26-workflows-ux-redesign.md section 4.4, issue #4244): a compact
+ * condition summary, the activities that run on the route as icon chips, and
+ * the `otherwise` marker for the one unconditioned route of a branching node.
+ *
+ * The model is DERIVED, never stored: nothing here writes back into edge data
+ * or the definition, so chips can never change the saved shape of a workflow.
+ * PURE — no React, no xyflow, no registry: the caller supplies already-read
+ * edge data and the activity icon lookup.
+ */
+
+/** Activity chips beyond this cap collapse into a single `+N` badge. */
+export const ROUTE_CHIP_LIMIT = 3
+
+/**
+ * Below this canvas zoom the chip row collapses to dots (semantic zoom). Picked
+ * so a 60-node flow zoomed out to fit stays readable as structure rather than
+ * as a wall of text.
+ */
+export const ROUTE_CHIP_ZOOM_THRESHOLD = 0.6
+
+/** Longest condition summary rendered before it is elided. */
+export const CONDITION_SUMMARY_MAX_LENGTH = 28
+
+export type RouteChipSection = 'condition' | 'activities'
+
+export interface RouteActivityChip {
+  activityId: string
+  activityType: string
+}
+
+export interface RouteChipModel {
+  conditionSummary: string | null
+  activities: RouteActivityChip[]
+  overflowCount: number
+  isOtherwise: boolean
+  isEmpty: boolean
+}
+
+export interface RouteChipInput {
+  condition?: unknown
+  preConditions?: unknown
+  activities?: unknown
+  /** True when a sibling route leaving the same step carries a condition. */
+  hasConditionedSibling?: boolean
+}
+
+interface SimpleConditionLike {
+  field: string
+  operator: string
+  value?: unknown
+  valueField?: string
+}
+
+interface GroupConditionLike {
+  operator: string
+  rules: unknown[]
+}
+
+/** Operators that read as a complete predicate on their own. */
+const VALUELESS_OPERATORS = new Set(['IS_EMPTY', 'IS_NOT_EMPTY'])
+
+function isGroupLike(value: unknown): value is GroupConditionLike {
+  return Boolean(
+    value &&
+      typeof value === 'object' &&
+      typeof (value as GroupConditionLike).operator === 'string' &&
+      Array.isArray((value as GroupConditionLike).rules),
+  )
+}
+
+function isSimpleLike(value: unknown): value is SimpleConditionLike {
+  return Boolean(
+    value &&
+      typeof value === 'object' &&
+      typeof (value as SimpleConditionLike).field === 'string' &&
+      typeof (value as SimpleConditionLike).operator === 'string',
+  )
+}
+
+function formatValue(value: unknown): string {
+  if (value === null || value === undefined) return ''
+  if (Array.isArray(value)) return value.map((entry) => formatValue(entry)).join(',')
+  if (typeof value === 'object') return '{…}'
+  return String(value)
+}
+
+function truncate(text: string, max: number): string {
+  if (text.length <= max) return text
+  return `${text.slice(0, Math.max(0, max - 1)).trimEnd()}…`
+}
+
+function summarizeSimple(condition: SimpleConditionLike): string {
+  const operator = condition.operator === '==' ? '=' : condition.operator
+  if (VALUELESS_OPERATORS.has(condition.operator)) {
+    return `${condition.field} ${operator}`
+  }
+  const right = condition.valueField ? condition.valueField : formatValue(condition.value)
+  return right ? `${condition.field} ${operator} ${right}` : `${condition.field} ${operator}`
+}
+
+/**
+ * Compact `field op value` rendering of a business_rules `ConditionExpression`.
+ * A group summarises to its first rule plus a `+N` suffix for the rest, which is
+ * what makes the chip readable at a glance; the full expression stays one click
+ * away in the condition editor. Returns null when there is nothing to show.
+ */
+export function summarizeConditionExpression(
+  condition: unknown,
+  maxLength: number = CONDITION_SUMMARY_MAX_LENGTH,
+): string | null {
+  if (isSimpleLike(condition)) return truncate(summarizeSimple(condition), maxLength)
+
+  if (isGroupLike(condition)) {
+    const rules = condition.rules
+    const first = rules.find((rule) => isSimpleLike(rule) || isGroupLike(rule))
+    if (!first) return null
+    const head = summarizeConditionExpression(first, maxLength)
+    if (!head) return null
+    const remaining = rules.length - 1
+    if (remaining <= 0) return head
+    return truncate(`${head} +${remaining}`, maxLength + 4)
+  }
+
+  return null
+}
+
+function readActivities(raw: unknown): RouteActivityChip[] {
+  if (!Array.isArray(raw)) return []
+  const chips: RouteActivityChip[] = []
+  raw.forEach((entry, index) => {
+    if (!entry || typeof entry !== 'object') return
+    const activityType = (entry as { activityType?: unknown }).activityType
+    if (typeof activityType !== 'string' || activityType.length === 0) return
+    const activityId = (entry as { activityId?: unknown }).activityId
+    chips.push({
+      activityId: typeof activityId === 'string' && activityId ? activityId : `${activityType}-${index}`,
+      activityType,
+    })
+  })
+  return chips
+}
+
+function hasRuleReference(raw: unknown): boolean {
+  return Array.isArray(raw) && raw.length > 0
+}
+
+/**
+ * The chip row for one transition. `isOtherwise` marks the default route: it
+ * carries no condition of its own while a sibling leaving the same step does —
+ * exactly the `ensureOtherwiseRoute` reading used by branching nodes, computed
+ * here from the live graph so it stays true for hand-wired routes too.
+ */
+export function buildRouteChipModel(input: RouteChipInput): RouteChipModel {
+  const conditionSummary = summarizeConditionExpression(input.condition)
+  const allActivities = readActivities(input.activities)
+  const activities = allActivities.slice(0, ROUTE_CHIP_LIMIT)
+  const overflowCount = Math.max(0, allActivities.length - activities.length)
+  const carriesCondition = conditionSummary !== null || hasRuleReference(input.preConditions)
+  const isOtherwise = !carriesCondition && Boolean(input.hasConditionedSibling)
+
+  return {
+    conditionSummary,
+    activities,
+    overflowCount,
+    isOtherwise,
+    isEmpty: conditionSummary === null && allActivities.length === 0 && !isOtherwise,
+  }
+}
+
+/** Route data carries a condition (inline expression or business-rule reference). */
+export function routeCarriesCondition(input: { condition?: unknown; preConditions?: unknown }): boolean {
+  return summarizeConditionExpression(input.condition) !== null || hasRuleReference(input.preConditions)
+}

package/src/modules/workflows/lib/route-edge.ts

@@ -0,0 +1,57 @@
+/**
+ * Workflows Module - Route edge construction (pure)
+ *
+ * The ONE place a control-flow route becomes a React Flow edge.
+ *
+ * A route the author has just drawn and the same route re-read from a saved
+ * definition are the same thing and must render identically. They did not:
+ * `definitionToGraph` typed every stored transition `workflowTransition` — the
+ * module's own bezier renderer — while the Studio's `handleConnect` and the
+ * insert-on-route splice typed a newly authored NORMAL route `smoothstep`,
+ * React Flow's built-in orthogonal renderer. ReactFlow merges
+ * `defaultEdgeOptions` UNDER each edge (`{ ...defaultEdgeOptions, ...edge }`),
+ * so the canvas default could not correct an explicit type, and a freshly drawn
+ * route rendered as a right-angled staircase that only became a curve after a
+ * save and a reload. The duplicated construction WAS the defect, so both paths
+ * build their edge here.
+ *
+ * Render-time only: nothing here reaches `graphToDefinition`, which reads
+ * endpoints, handles and `data` — an edge's `type` is how a route is drawn, not
+ * what is stored.
+ *
+ * PURE — plain graph data in, plain graph data out. The `Edge` import is
+ * type-only, so the visual-editor page keeps its lazy `@xyflow/react` boundary
+ * (#3169).
+ */
+
+import type { Edge } from '@xyflow/react'
+
+/**
+ * React Flow edge type registered for `WorkflowTransitionEdge` in
+ * `WorkflowGraphImpl`'s `edgeTypes` (and its `defaultEdgeOptions`). Every
+ * control-flow route — kinded or not, drawn or loaded — renders through it.
+ */
+export const WORKFLOW_TRANSITION_EDGE_TYPE = 'workflowTransition'
+
+export interface WorkflowRouteEdgeInput {
+  id: string
+  source: string
+  target: string
+  /** Omitted entirely when absent, so a route without one keeps today's shape. */
+  sourceHandle?: string | null
+  targetHandle?: string | null
+  data?: Record<string, unknown>
+}
+
+/** Build the React Flow edge for one control-flow route. */
+export function buildWorkflowRouteEdge(input: WorkflowRouteEdgeInput): Edge {
+  return {
+    id: input.id,
+    source: input.source,
+    target: input.target,
+    type: WORKFLOW_TRANSITION_EDGE_TYPE,
+    ...(input.sourceHandle ? { sourceHandle: input.sourceHandle } : {}),
+    ...(input.targetHandle ? { targetHandle: input.targetHandle } : {}),
+    data: input.data ?? {},
+  }
+}

package/src/modules/workflows/lib/route-kinds.ts

@@ -0,0 +1,166 @@
+/**
+ * Workflows Module - Route kind round-trip (pure)
+ *
+ * A transition's `kind` is what keeps a route off the happy path: `error` is
+ * reachable only from a failure, `slaBreach` only from a deadline passing. Each
+ * kind is drawn from its own canvas source handle, so persisting a route means
+ * answering two questions in both directions:
+ *
+ *   canvas edge  → which `kind` does this connection compile to?
+ *   stored route → which source handle does it re-attach to?
+ *
+ * Both answers used to be inlined per kind, which is why `slaBreach` — added
+ * after `error` — was silently downgraded to a normal transition the moment a
+ * definition carrying one was opened in the Studio and saved: `graphToDefinition`
+ * only ever special-cased `'error'`. Registering a kind here is now the single
+ * step that makes it survive the round trip, so the next kind cannot repeat it.
+ *
+ * PURE: no ORM, DI, React or registry imports, so `graph-utils` can consume it
+ * without pulling the editor's render chain (enforced by the xyflow
+ * import-boundary test).
+ */
+
+import { ERROR_SOURCE_HANDLE_ID, ERROR_TRANSITION_KIND } from './error-routing'
+import { SLA_BREACH_SOURCE_HANDLE_ID, SLA_BREACH_TRANSITION_KIND } from './breach-routing'
+import {
+  OUTCOME_TRANSITION_KIND,
+  isAgentOutcomeKind,
+  outcomeSourceHandleId,
+  parseOutcomeSourceHandleId,
+} from './outcome-routing'
+
+/**
+ * The absent form. A transition with no `kind` and a transition with
+ * `kind: 'normal'` mean the same thing to every routing lookup, so the canvas
+ * serializes both as absent — which is what keeps a definition declaring no
+ * kinds byte-identical through a save.
+ */
+export const NORMAL_TRANSITION_KIND = 'normal'
+
+/**
+ * The canvas source handle a normal route leaves from — every node's ordinary
+ * output, and the one handle no `RouteKindDescriptor` claims.
+ *
+ * FROZEN: stored transitions re-attach to it by id (`definitionToGraph` emits
+ * no `sourceHandle` for a normal route, which React Flow resolves to the node's
+ * only unnamed source), and moving where it RENDERS must never change what it
+ * is called. It moved into the outcome-row footer so every outgoing connection
+ * leaves from a row; the id did not move with it.
+ */
+export const DEFAULT_SOURCE_HANDLE_ID = 'source'
+
+export interface RouteKindTransitionLike {
+  kind?: string
+  outcomeKind?: string
+}
+
+export interface RouteKindDescriptor {
+  /** Value persisted as `transition.kind`. */
+  kind: string
+  /** True when a connection drawn from this handle compiles to this kind. */
+  matchesSourceHandle(sourceHandleId: string): boolean
+  /** Canvas source handle a stored transition of this kind re-attaches to. */
+  resolveSourceHandle(transition: RouteKindTransitionLike): string
+  /**
+   * Fields beyond `kind` this route persists, derived from what the canvas
+   * carries. A kind whose handles fan out (outcome routes) stores WHICH handle
+   * it was drawn from; a fixed-handle kind stores nothing extra.
+   */
+  discriminatorFields(edge: RouteKindEdgeLike): Record<string, unknown>
+}
+
+export interface RouteKindEdgeLike {
+  data?: RouteKindTransitionLike | null
+  sourceHandle?: string | null
+}
+
+function fixedHandleDescriptor(kind: string, sourceHandleId: string): RouteKindDescriptor {
+  return {
+    kind,
+    matchesSourceHandle: (candidate) => candidate === sourceHandleId,
+    resolveSourceHandle: () => sourceHandleId,
+    discriminatorFields: () => ({}),
+  }
+}
+
+/**
+ * Outcome routes are the one kind that fans out: an agent node exposes a handle
+ * per §7.2 disposition kind, so the handle carries the outcome and the stored
+ * route carries it back as `outcomeKind`. `approved` is the fallback because it
+ * is the outcome §7.2 renders unconditionally.
+ */
+const outcomeDescriptor: RouteKindDescriptor = {
+  kind: OUTCOME_TRANSITION_KIND,
+  matchesSourceHandle: (candidate) => parseOutcomeSourceHandleId(candidate) !== null,
+  resolveSourceHandle: (transition) =>
+    outcomeSourceHandleId(
+      isAgentOutcomeKind(transition.outcomeKind) ? transition.outcomeKind : 'approved',
+    ),
+  discriminatorFields: (edge) => {
+    const carried = edge.data?.outcomeKind
+    const fromHandle = parseOutcomeSourceHandleId(edge.sourceHandle)
+    const outcome = isAgentOutcomeKind(carried) ? carried : fromHandle
+    return { outcomeKind: outcome ?? 'approved' }
+  },
+}
+
+/**
+ * Every non-normal kind the canvas can author. Order is only the lookup order:
+ * handle ids are disjoint, so at most one descriptor ever matches.
+ */
+const ROUTE_KIND_DESCRIPTORS: RouteKindDescriptor[] = [
+  fixedHandleDescriptor(ERROR_TRANSITION_KIND, ERROR_SOURCE_HANDLE_ID),
+  fixedHandleDescriptor(SLA_BREACH_TRANSITION_KIND, SLA_BREACH_SOURCE_HANDLE_ID),
+  outcomeDescriptor,
+]
+
+export function listRouteKindDescriptors(): RouteKindDescriptor[] {
+  return [...ROUTE_KIND_DESCRIPTORS]
+}
+
+/** Descriptor for a stored `transition.kind`, or null for normal / unknown kinds. */
+export function findRouteKindDescriptor(kind: unknown): RouteKindDescriptor | null {
+  if (typeof kind !== 'string' || kind.length === 0) return null
+  return ROUTE_KIND_DESCRIPTORS.find((descriptor) => descriptor.kind === kind) ?? null
+}
+
+/** Descriptor for a canvas source handle, or null when the handle is the default one. */
+export function findRouteKindDescriptorForHandle(sourceHandleId: unknown): RouteKindDescriptor | null {
+  if (typeof sourceHandleId !== 'string' || sourceHandleId.length === 0) return null
+  return ROUTE_KIND_DESCRIPTORS.find((descriptor) => descriptor.matchesSourceHandle(sourceHandleId)) ?? null
+}
+
+/**
+ * The kind a canvas edge compiles to, from its carried `data.kind` and the
+ * handle it leaves from. Returns null for a normal route, which is what makes
+ * "no kind config ⇒ identical serialization" the default rather than a case.
+ *
+ * The carried kind wins over the handle so a route authored before its handle
+ * existed still serializes as its kind.
+ */
+export function resolveEdgeRouteKind(
+  edgeKind: unknown,
+  sourceHandleId: unknown,
+): RouteKindDescriptor | null {
+  return findRouteKindDescriptor(edgeKind) ?? findRouteKindDescriptorForHandle(sourceHandleId)
+}
+
+/** True for any route the engine reaches only through its own dedicated path. */
+export function isNonNormalRouteKind(kind: unknown): boolean {
+  return findRouteKindDescriptor(kind) !== null
+}
+
+/**
+ * Strip every kinded route from a normal-routing lookup.
+ *
+ * Each kind is reachable ONLY from its own trigger — a failure, a passed
+ * deadline, a resolved disposition — so a routing lookup that forgot one would
+ * auto-select it as a happy path. That is the bug shape `route-priority.ts`
+ * already had for `slaBreach`, so the filter lives here once and every lookup
+ * calls it instead of composing per-kind excludes and eventually missing one.
+ */
+export function excludeNonNormalTransitions<T extends { kind?: string }>(
+  transitions: T[],
+): T[] {
+  return transitions.filter((transition) => !isNonNormalRouteKind(transition?.kind))
+}

package/src/modules/workflows/lib/route-priority.ts

@@ -0,0 +1,197 @@
+/**
+ * Workflows Module - Route Priority (pure)
+ *
+ * Spec 2026-07-26-workflows-ux-redesign.md section 4.4: "Priority becomes
+ * drag-to-reorder of a node's outgoing routes; the number is derived and
+ * demoted to advanced. First edit of a node's routes runs a priority
+ * normalization pass (existing definitions mix dialog-default 100 with
+ * schema-default 0)."
+ *
+ * The engine is untouched: `findValidTransitions` still evaluates outgoing
+ * transitions highest-priority-first with ties keeping definition order. This
+ * module only decides which NUMBERS express a given author-visible ORDER, and
+ * the normalization pass rewrites messy legacy numbers into clean ones WITHOUT
+ * changing that evaluation order.
+ *
+ * Error routes (`kind: 'error'`) are never part of normal-route ordering — they
+ * are only reachable from a failure, so their priority means something else
+ * entirely (`findErrorTransition`). They pass through untouched.
+ *
+ * PURE: no React, no ORM, no DI. The only xyflow dependency is the `Edge` type.
+ */
+
+import type { Edge } from '@xyflow/react'
+import { isNonNormalRouteKind } from './route-kinds'
+import { routeCarriesCondition } from './route-chips'
+
+/** Priority of the highest route when a node has at most 10 normal routes. */
+export const ROUTE_PRIORITY_TOP = 100
+
+/** Gap between consecutive routes, matching the Switch compiler (step 2.2). */
+export const ROUTE_PRIORITY_STEP = 10
+
+/** The trailing unconditioned route always evaluates last. */
+export const ROUTE_PRIORITY_OTHERWISE = 0
+
+export interface RouteOrderEntry {
+  transitionId: string
+  toStepId: string
+  label?: string
+  priority: number
+  hasCondition: boolean
+  isOtherwise: boolean
+}
+
+interface EdgeDataLike {
+  priority?: number
+  condition?: unknown
+  preConditions?: unknown
+  transitionName?: string
+  label?: string
+  kind?: string
+}
+
+function edgeData(edge: Edge): EdgeDataLike {
+  return (edge.data ?? {}) as EdgeDataLike
+}
+
+function readPriority(edge: Edge): number {
+  const raw = edgeData(edge).priority
+  return typeof raw === 'number' && Number.isFinite(raw) ? raw : 0
+}
+
+/**
+ * A node's outgoing NORMAL routes — every kinded route (error, SLA-breach,
+ * agent outcome) and data-mapping edge excluded. Filtering only error routes
+ * here used to let a breach or outcome route into the priority ladder, where it
+ * would read as a happy path the author never wired.
+ */
+export function outgoingNormalRoutes(edges: Edge[], nodeId: string): Edge[] {
+  return edges.filter(
+    (edge) =>
+      edge.source === nodeId &&
+      edge.type !== 'workflowDataMapping' &&
+      !isNonNormalRouteKind(edgeData(edge).kind),
+  )
+}
+
+/**
+ * The order the engine evaluates a node's routes in today: priority descending,
+ * ties keeping definition order. Implemented as an index-decorated comparison so
+ * it stays stable on every runtime, with an explicit comparator (#3620).
+ */
+export function orderRoutesByPriority(routes: Edge[]): Edge[] {
+  return routes
+    .map((edge, index) => ({ edge, index, priority: readPriority(edge) }))
+    .sort((a, b) => (b.priority - a.priority) || (a.index - b.index))
+    .map((entry) => entry.edge)
+}
+
+/**
+ * Derived priorities for an ordered route list. The last route is the
+ * "otherwise" — and gets priority 0 — only when it carries no condition while an
+ * earlier one does; otherwise every route keeps a positive, evenly spaced slot.
+ * The top value grows with the route count so a node with more than ten routes
+ * still gets unique, non-negative numbers.
+ */
+export function derivePriorities(entries: Array<{ hasCondition: boolean }>): number[] {
+  const count = entries.length
+  if (count === 0) return []
+
+  const lastIndex = count - 1
+  const hasConditionedRoute = entries.some((entry) => entry.hasCondition)
+  const trailingOtherwise = count > 1 && hasConditionedRoute && !entries[lastIndex].hasCondition
+  const caseCount = trailingOtherwise ? lastIndex : count
+  const top = Math.max(ROUTE_PRIORITY_TOP, caseCount * ROUTE_PRIORITY_STEP)
+
+  return entries.map((_entry, index) => {
+    if (trailingOtherwise && index === lastIndex) return ROUTE_PRIORITY_OTHERWISE
+    return top - index * ROUTE_PRIORITY_STEP
+  })
+}
+
+/** The inspector's view of a node's outgoing routes, in evaluation order. */
+export function readRouteOrder(edges: Edge[], nodeId: string): RouteOrderEntry[] {
+  const ordered = orderRoutesByPriority(outgoingNormalRoutes(edges, nodeId))
+  const hasConditionedRoute = ordered.some((edge) => routeCarriesCondition(edgeData(edge)))
+  const lastIndex = ordered.length - 1
+
+  return ordered.map((edge, index) => {
+    const data = edgeData(edge)
+    const hasCondition = routeCarriesCondition(data)
+    return {
+      transitionId: edge.id,
+      toStepId: edge.target,
+      label: data.transitionName || data.label || undefined,
+      priority: readPriority(edge),
+      hasCondition,
+      isOtherwise: !hasCondition && hasConditionedRoute && index === lastIndex && ordered.length > 1,
+    }
+  })
+}
+
+/** Move one route within the list, returning a new array (drag-to-reorder). */
+export function moveRoute(entries: RouteOrderEntry[], fromIndex: number, toIndex: number): RouteOrderEntry[] {
+  if (fromIndex === toIndex) return entries
+  if (fromIndex < 0 || fromIndex >= entries.length) return entries
+  const clampedTo = Math.min(Math.max(toIndex, 0), entries.length - 1)
+  const next = [...entries]
+  const [moved] = next.splice(fromIndex, 1)
+  next.splice(clampedTo, 0, moved)
+  return next
+}
+
+/** Re-derive priorities so the entries read top-to-bottom in evaluation order. */
+export function applyDerivedPriorities(entries: RouteOrderEntry[]): RouteOrderEntry[] {
+  const priorities = derivePriorities(entries)
+  return entries.map((entry, index) => ({
+    ...entry,
+    priority: priorities[index],
+    isOtherwise: priorities[index] === ROUTE_PRIORITY_OTHERWISE && !entry.hasCondition && entries.length > 1,
+  }))
+}
+
+/** Write an inspector route list back onto the node's outgoing edges. */
+export function applyRouteOrder(edges: Edge[], nodeId: string, entries: RouteOrderEntry[]): Edge[] {
+  const priorityByTransitionId = new Map(entries.map((entry) => [entry.transitionId, entry.priority]))
+  return edges.map((edge) => {
+    if (edge.source !== nodeId) return edge
+    if (!priorityByTransitionId.has(edge.id)) return edge
+    return { ...edge, data: { ...(edge.data ?? {}), priority: priorityByTransitionId.get(edge.id) } }
+  })
+}
+
+/**
+ * True when a node's outgoing routes still carry legacy numbering — duplicated
+ * priorities (the dialog default of 100 on every route) or values off the
+ * derived scale. A single route never needs normalizing.
+ */
+export function needsPriorityNormalization(edges: Edge[], nodeId: string): boolean {
+  const entries = readRouteOrder(edges, nodeId)
+  if (entries.length < 2) return false
+  const derived = derivePriorities(entries)
+  return entries.some((entry, index) => entry.priority !== derived[index])
+}
+
+/**
+ * Whether the normalization pass may run for a definition of this `source`.
+ *
+ * A `code` definition is authored in TypeScript and is read-only in the editor —
+ * rewriting its priorities would silently diverge the canvas from the code. It
+ * becomes normalizable only after Customize, which mints an editable override
+ * (`code_override`), which is exactly the spec's "for `source: 'code'`
+ * definitions this happens only on Customize".
+ */
+export function canNormalizeRoutePriorities(source: string | null | undefined): boolean {
+  return source !== 'code'
+}
+
+/**
+ * The normalization pass: rewrite a node's outgoing normal-route priorities to
+ * clean descending values while PRESERVING the order the engine evaluates them
+ * in today. Idempotent, and a no-op for a node whose routes are already clean.
+ */
+export function normalizeRoutePriorities(edges: Edge[], nodeId: string): Edge[] {
+  if (!needsPriorityNormalization(edges, nodeId)) return edges
+  return applyRouteOrder(edges, nodeId, applyDerivedPriorities(readRouteOrder(edges, nodeId)))
+}