@open-mercato/core 0.7.1-develop.7193.1.910a5b0a1e → 0.7.1-develop.7195.1.b5efd1d51a

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

@@ -23,6 +23,14 @@ import * as activityExecutor from './activity-executor'
 import type { ActivityDefinition } from './activity-executor'
 import * as stepHandler from './step-handler'
 import { findDefinitionForInstance } from './find-definition'
+import { resolveDefinitionInterpolationMode } from './interpolation-pipeline'
+import { buildSetVariableContextPatch, isSetVariableOutput } from './set-variable'
+import {
+  resolveStepFailureHandling,
+  type StepFailureHandling,
+} from './error-routing'
+import { DRY_RUN_EVENT_TYPES, isDryRunInstance } from './dry-run'
+import { excludeNonNormalTransitions } from './route-kinds'
 import {
   type ExecutionToken,
   rootToken,
@@ -39,6 +47,56 @@ import { createLogger } from '@open-mercato/shared/lib/logger'
 
 const logger = createLogger('workflows')
 
+/**
+ * Translate a resolved failure handling into the fields the executor acts on.
+ * `fail` (the absent-config default) adds nothing, so untouched definitions
+ * return the exact failure shape they returned before error routing existed.
+ */
+function buildFailureRouting(
+  handling: StepFailureHandling,
+  failedStepId: string
+): Pick<
+  TransitionExecutionResult,
+  'failedStepId' | 'errorRoute' | 'parkForAttention' | 'errorHandlerStepId'
+> {
+  if (handling.kind === 'route' && typeof handling.transition.toStepId === 'string') {
+    return {
+      failedStepId,
+      errorRoute: {
+        transitionId: handling.transition.transitionId,
+        toStepId: handling.transition.toStepId,
+      },
+    }
+  }
+  if (handling.kind === 'park') {
+    return { failedStepId, parkForAttention: true }
+  }
+  if (handling.kind === 'handlerStep') {
+    return { failedStepId, errorHandlerStepId: handling.stepId }
+  }
+  return {}
+}
+
+/**
+ * Record that a dry run evaluated a transition's business rule but withheld its
+ * ACTION arm, so the "Would do" report can say which side effect was skipped
+ * rather than leaving the author to assume the rule did nothing.
+ */
+async function logSuppressedRuleActions(
+  em: EntityManager,
+  instance: WorkflowInstance,
+  ruleId: string,
+  phase: 'pre_transition' | 'post_transition'
+): Promise<void> {
+  await logTransitionEvent(em, {
+    workflowInstanceId: instance.id,
+    eventType: DRY_RUN_EVENT_TYPES.businessRuleActionsSuppressed,
+    eventData: { ruleId, phase },
+    tenantId: instance.tenantId,
+    organizationId: instance.organizationId,
+  })
+}
+
 // ============================================================================
 // Types and Interfaces
 // ============================================================================
@@ -47,6 +105,7 @@ export interface TransitionEvaluationContext {
   workflowContext: Record<string, any>
   userId?: string
   triggerData?: any
+  transitionId?: string
 }
 
 export interface TransitionEvaluationResult {
@@ -61,18 +120,33 @@ export interface TransitionExecutionContext {
   workflowContext: Record<string, any>
   userId?: string
   triggerData?: any
+  transitionId?: string
 }
 
 export interface TransitionExecutionResult {
   success: boolean
   nextStepId?: string
   pausedForActivities?: boolean
+  // The destination step entered a wait state (PAUSED / WAITING_FOR_ACTIVITIES)
+  // after the transition into it executed — e.g. an INVOKE_AGENT AUTOMATED step
+  // parked the instance on its agent signal. Distinct from `pausedForActivities`
+  // (async activities ON THE TRANSITION, resumed via resumeWorkflowAfterActivities).
+  paused?: boolean
   conditionsEvaluated?: {
     preConditions: boolean
     postConditions: boolean
   }
   activitiesExecuted?: activityExecutor.ActivityExecutionResult[]
   error?: string
+  // Error routing (spec 5.9). Set only when the failure carries error handling
+  // the executor must apply: `errorRoute` names the wired error transition to
+  // follow, `parkForAttention` asks for a failure-queue park instead of a fail.
+  // Absent on every legacy failure, which therefore keeps failing identically.
+  failedStepId?: string
+  errorRoute?: { transitionId?: string; toStepId: string }
+  parkForAttention?: boolean
+  // Definition-level handler step to jump to before failing (spec 5.9).
+  errorHandlerStepId?: string
 }
 
 export class TransitionError extends Error {
@@ -133,7 +207,10 @@ export async function evaluateTransition(
     if (toStepId) {
       // Find specific transition
       transition = transitions.find(
-        (t: any) => t.fromStepId === fromStepId && t.toStepId === toStepId
+        (candidate: { fromStepId?: unknown; toStepId?: unknown; transitionId?: unknown }) =>
+          candidate.fromStepId === fromStepId
+          && candidate.toStepId === toStepId
+          && (context.transitionId === undefined || candidate.transitionId === context.transitionId)
       )
 
       if (!transition) {
@@ -144,8 +221,9 @@ export async function evaluateTransition(
         }
       }
     } else {
-      // Auto-select first valid transition
-      const availableTransitions = transitions.filter(
+      // Auto-select first valid transition (never a kinded route: error,
+      // SLA-breach or agent-outcome)
+      const availableTransitions = excludeNonNormalTransitions(transitions).filter(
         (t: any) => t.fromStepId === fromStepId
       )
 
@@ -231,8 +309,11 @@ export async function findValidTransitions(
       return []
     }
 
-    // Find all transitions from current step, sorted by priority (highest first)
-    const transitions = (definition.definition.transitions || [])
+    // Find all transitions from current step, sorted by priority (highest first).
+    // Every kinded route is excluded — each is reachable only from its own
+    // trigger (a step failure, a task's deadline passing, a resolved agent
+    // disposition), never from normal routing.
+    const transitions = excludeNonNormalTransitions(definition.definition.transitions || [])
       .filter((t: any) => t.fromStepId === fromStepId)
       .sort((a: any, b: any) => (b.priority || 0) - (a.priority || 0))
 
@@ -246,7 +327,7 @@ export async function findValidTransitions(
         instance,
         fromStepId,
         transition.toStepId,
-        context
+        { ...context, transitionId: transition.transitionId },
       )
 
       if (!conditionResult.isValid) {
@@ -424,6 +505,7 @@ export async function executeTransitionForToken(
     const activityResults: activityExecutor.ActivityExecutionResult[] = []
 
     if (transition.activities && transition.activities.length > 0) {
+      const definitionForInterpolation = await findDefinitionForInstance(em, instance)
       const activityContext: activityExecutor.ActivityContext = {
         workflowInstance: instance,
         workflowContext: {
@@ -432,6 +514,7 @@ export async function executeTransitionForToken(
         },
         branchInstanceId,
         userId: context.userId,
+        interpolationMode: resolveDefinitionInterpolationMode(definitionForInterpolation?.definition),
       }
 
       // Execute all activities
@@ -448,6 +531,20 @@ export async function executeTransitionForToken(
       const failedActivities = results.filter(r => !r.success)
 
       if (failedActivities.length > 0) {
+        // A dry-run refusal stops the run AT that node (spec section 8.2). It is
+        // not an activity failure — nothing was attempted — so neither
+        // `continueOnActivityFailure` nor the step's error route/directive may
+        // absorb it. Answering it before either is consulted is what keeps the
+        // marker explicit instead of silently routed.
+        const refusal = failedActivities.find((result) => result.dryRunRefused)
+        if (refusal) {
+          return {
+            success: false,
+            error: refusal.error ?? 'Dry run stopped',
+            conditionsEvaluated: { preConditions: true, postConditions: false },
+          }
+        }
+
         const continueOnFailure = transition.continueOnActivityFailure ?? false
 
         // Log activity failures
@@ -472,22 +569,68 @@ export async function executeTransitionForToken(
         })
 
         if (!continueOnFailure) {
-          return {
-            success: false,
-            error: `Activities failed: ${failedActivities.map(f => f.error).join(', ')}`,
-            conditionsEvaluated: {
-              preConditions: true,
-              postConditions: false,
-            },
+          // Error routing (spec 5.9). The failing node here is the step the
+          // route leaves, because the token cursor has not advanced yet.
+          const failureHandling = resolveStepFailureHandling(
+            definitionForInterpolation?.definition,
+            fromStepId
+          )
+
+          if (failureHandling.kind === 'continue') {
+            // `continueWithFallback` is the directive form of the legacy
+            // `continueOnActivityFailure` flag: identical continue semantics,
+            // plus the authored fallback value landing under the step id.
+            await logTransitionEvent(em, {
+              workflowInstanceId: instance.id,
+              branchInstanceId,
+              eventType: 'ERROR_DIRECTIVE_APPLIED',
+              eventData: {
+                stepId: fromStepId,
+                directive: 'continueWithFallback',
+                transitionId: transition.transitionId || `${fromStepId}->${toStepId}`,
+                hasFallbackValue: failureHandling.fallbackValue !== undefined,
+              },
+              userId: context.userId,
+              tenantId: instance.tenantId,
+              organizationId: instance.organizationId,
+            })
+            if (failureHandling.fallbackValue !== undefined) {
+              activityOutputs[fromStepId] = failureHandling.fallbackValue
+            }
+          } else {
+            return {
+              success: false,
+              error: `Activities failed: ${failedActivities.map(f => f.error).join(', ')}`,
+              conditionsEvaluated: {
+                preConditions: true,
+                postConditions: false,
+              },
+              ...buildFailureRouting(failureHandling, fromStepId),
+            }
           }
         }
       }
 
-      // Collect activity outputs for context update
+      // Collect activity outputs for context update. SET_VARIABLE outputs are
+      // applied at their assignment paths in top-level context (preserving
+      // sibling keys of any nested target); other outputs merge under the
+      // activity name/type key.
       results.forEach(result => {
         if (result.success && result.output) {
-          const key = result.activityName || result.activityType
-          activityOutputs[key] = result.output
+          if (result.activityType === 'SET_VARIABLE' && isSetVariableOutput(result.output)) {
+            const assignmentBase = {
+              ...tokenReadContext(token),
+              ...context.workflowContext,
+              ...activityOutputs,
+            }
+            Object.assign(
+              activityOutputs,
+              buildSetVariableContextPatch(assignmentBase, result.output.assignments)
+            )
+          } else {
+            const key = result.activityName || result.activityType
+            activityOutputs[key] = result.output
+          }
         }
       })
     }
@@ -571,14 +714,58 @@ export async function executeTransitionForToken(
     // Flush to database after step execution completes to make state visible to UI
     await em.flush()
 
-    // Handle step execution failure
+    // Handle step execution failure. Error routing (spec 5.9) keys on the step
+    // that failed — the cursor already advanced, so that is `toStepId`.
     if (stepExecutionResult.status === 'FAILED') {
-      return {
-        success: false,
-        error: stepExecutionResult.error || 'Step execution failed',
+      const definitionForFailure = await findDefinitionForInstance(em, instance)
+      const failureHandling = resolveStepFailureHandling(definitionForFailure?.definition, toStepId)
+
+      if (failureHandling.kind === 'continue') {
+        // The step instance stays FAILED — its state machine is untouched. The
+        // instance advances with the authored fallback value in context, and
+        // the executor re-evaluates the failed step's outgoing routes.
+        await logTransitionEvent(em, {
+          workflowInstanceId: instance.id,
+          branchInstanceId,
+          eventType: 'ERROR_DIRECTIVE_APPLIED',
+          eventData: {
+            stepId: toStepId,
+            directive: 'continueWithFallback',
+            transitionId: transition.transitionId || `${fromStepId}->${toStepId}`,
+            error: stepExecutionResult.error,
+            hasFallbackValue: failureHandling.fallbackValue !== undefined,
+          },
+          userId: context.userId,
+          tenantId: instance.tenantId,
+          organizationId: instance.organizationId,
+        })
+        if (failureHandling.fallbackValue !== undefined) {
+          mergeTokenContext(token, { [toStepId]: failureHandling.fallbackValue })
+          await em.flush()
+        }
+      } else {
+        return {
+          success: false,
+          error: stepExecutionResult.error || 'Step execution failed',
+          ...buildFailureRouting(failureHandling, toStepId),
+        }
       }
     }
 
+    // The transition INTO the step genuinely happened, but the step then parked
+    // the instance (e.g. an INVOKE_AGENT AUTOMATED step enqueued an async agent
+    // job and set status PAUSED). Surface that via `paused` so the executor loop
+    // stops advancing instead of taking the next auto-transition.
+    //
+    // `FORK` is the ONE wait reason that is not an external park: `openFork`
+    // leaves the instance FORKED with its branch rows already written, and the
+    // branches are driven by `advanceBranches` on the executor loop's NEXT
+    // iteration. Reporting it as paused makes the executor return before it
+    // re-reads the instance, so the branches never advance and the instance
+    // stays FORKED at the fork step forever.
+    const stepPaused =
+      stepExecutionResult.status === 'WAITING' && stepExecutionResult.waitReason !== 'FORK'
+
     // Evaluate post-conditions (business rules)
     const postConditionsResult = await evaluatePostConditions(
       em,
@@ -633,6 +820,7 @@ export async function executeTransitionForToken(
     return {
       success: true,
       nextStepId: toStepId,
+      paused: stepPaused,
       conditionsEvaluated: {
         preConditions: true,
         postConditions: postConditionsResult.allowed,
@@ -771,6 +959,7 @@ async function evaluatePreConditions(
     }
 
     // Execute each pre-condition rule directly by ruleId
+    const dryRun = isDryRunInstance(instance)
     const startTime = Date.now()
     const executedRules: ruleEngine.RuleExecutionResult[] = []
     const errors: string[] = []
@@ -797,7 +986,16 @@ async function evaluatePreConditions(
         entityType: `workflow:${definition.workflowId}:transition`,
         entityId: transition.transitionId || `${transition.fromStepId}->${transition.toStepId}`,
         eventType: 'pre_transition',
+        // Dry run (spec section 8.2): the rule engine's own `dryRun` only
+        // suppresses its execution LOG — a rule's success/failure ACTIONS run
+        // regardless — so a side-effect-free run has to ask for `skipActions`.
+        // The conditions still evaluate, so the run takes the routes it really
+        // would; only the ACTION arm is withheld, and it is reported.
+        skipActions: dryRun,
       })
+      if (dryRun && result.actionsExecuted === null) {
+        await logSuppressedRuleActions(em, instance, condition.ruleId, 'pre_transition')
+      }
 
       // Create a compatible RuleExecutionResult for tracking
       // We don't have the full BusinessRule entity, but we can create a partial result
@@ -898,6 +1096,7 @@ async function evaluatePostConditions(
     }
 
     // Execute each post-condition rule directly by ruleId
+    const dryRun = isDryRunInstance(instance)
     const startTime = Date.now()
     const executedRules: ruleEngine.RuleExecutionResult[] = []
     const errors: string[] = []
@@ -924,7 +1123,16 @@ async function evaluatePostConditions(
         entityType: `workflow:${definition.workflowId}:transition`,
         entityId: transition.transitionId || `${transition.fromStepId}->${transition.toStepId}`,
         eventType: 'post_transition',
+        // Dry run (spec section 8.2): the rule engine's own `dryRun` only
+        // suppresses its execution LOG — a rule's success/failure ACTIONS run
+        // regardless — so a side-effect-free run has to ask for `skipActions`.
+        // The conditions still evaluate, so the run takes the routes it really
+        // would; only the ACTION arm is withheld, and it is reported.
+        skipActions: dryRun,
       })
+      if (dryRun && result.actionsExecuted === null) {
+        await logSuppressedRuleActions(em, instance, condition.ruleId, 'post_transition')
+      }
 
       // Create a compatible RuleExecutionResult for tracking
       const ruleResult: ruleEngine.RuleExecutionResult = {

package/src/modules/workflows/lib/trigger-node.ts

@@ -0,0 +1,272 @@
+/**
+ * Workflows Module — the canvas trigger node (pure; fidelity gap #5).
+ *
+ * Until now nothing on the canvas answered "where does this start". A
+ * definition's triggers lived only in the details drawer, so a flow opened onto
+ * a generic START card indistinguishable from a step. These helpers derive the
+ * pill that states the answer — and nothing else: there is NO engine change
+ * here, the triggers are already on the definition.
+ *
+ * The node is a RENDER-TIME overlay, exactly like the compensation ghosts
+ * (`lib/compensation-ghosts.ts`) and the "show last run" decoration. It is
+ * minted inside `WorkflowGraphImpl` from a prop and never enters the editor's
+ * node state, so it is absent from `graphToDefinition`, from the undo stack,
+ * from the drag autosave, from the per-user draft and from the subgraph
+ * clipboard by construction. `graphToDefinition` and `validateWorkflowGraph`
+ * filter it anyway, so the guarantee is testable rather than merely true.
+ *
+ * What it says has to be TRUE, which drives three decisions the mockup does not
+ * make for us:
+ *
+ *  - **Manual and API starts are always a way in.** `POST /api/workflows/instances`
+ *    → `workflowExecutor.startWorkflow` needs no trigger at all; it only needs
+ *    the definition to be enabled. So the node always carries a manual/API line,
+ *    and a definition with zero triggers still renders — it just does not claim
+ *    an event starts it.
+ *  - **A DISABLED definition starts from nothing.** `startWorkflow` throws
+ *    `DEFINITION_DISABLED` before it looks at anything else, so the node says so
+ *    instead of listing entry points that cannot fire.
+ *  - **A disabled trigger does not start the workflow.** It is still shown (the
+ *    canvas would otherwise disagree with the drawer the author just used) but
+ *    it is marked, and it never displaces a live trigger into the overflow.
+ *
+ * PURE: no React, no ORM, no registry. `@xyflow/react` is imported for types
+ * only, the same boundary `lib/compensation-ghosts.ts` keeps.
+ */
+
+import type { Edge, Node } from '@xyflow/react'
+import { EDGE_COLORS } from './status-colors'
+import {
+  TERMINAL_NODE_HEIGHT,
+  TERMINAL_NODE_MIN_WIDTH,
+  TRIGGER_NODE_GAP,
+  TRIGGER_NODE_HEADER_HEIGHT,
+  TRIGGER_NODE_ROW_HEIGHT,
+  TRIGGER_NODE_WIDTH,
+} from './node-geometry'
+
+/** Node type registered on the canvas for the trigger pill. Never a step type. */
+export const WORKFLOW_TRIGGER_NODE_TYPE = 'workflowTrigger'
+
+/**
+ * The synthetic node's id. Reserved and recognisable without consulting the
+ * type, which is what lets `graphToDefinition` refuse to serialize it even if
+ * the node ever reached it.
+ */
+export const WORKFLOW_TRIGGER_NODE_ID = '__workflow_trigger__'
+
+/** Id of the connector drawn from the pill into START. */
+export const WORKFLOW_TRIGGER_EDGE_ID = '__workflow_trigger_edge__'
+
+/**
+ * Event tags rendered before the rest collapse into a `+N` line, matching
+ * `ROUTE_CHIP_LIMIT`. A definition may declare many triggers, and the 60-node
+ * density criterion is what settles the question: an uncapped list turns one
+ * node into a scrolling legend at exactly the zoom where the canvas is supposed
+ * to read as structure.
+ */
+export const TRIGGER_NODE_EVENT_LIMIT = 3
+
+/**
+ * The connector's own dash pattern. `pending` routes are SOLID since fidelity
+ * gap #2, so a dash again means something — here, "this is not a transition".
+ * Distinct from error (`8,4`), data-mapping (`2,3`) and compensation ghosts
+ * (`10,4,2,4`).
+ */
+export const TRIGGER_EDGE_DASH_ARRAY = '4,4'
+
+export interface TriggerLike {
+  triggerId?: unknown
+  name?: unknown
+  eventPattern?: unknown
+  enabled?: unknown
+}
+
+export interface TriggerNodeEventRow {
+  /** Stable React key — the trigger id when it has one. */
+  key: string
+  name: string
+  eventPattern: string
+  enabled: boolean
+}
+
+export interface TriggerNodeModel {
+  /** Event tags actually rendered, capped at {@link TRIGGER_NODE_EVENT_LIMIT}. */
+  rows: TriggerNodeEventRow[]
+  /** Declared triggers the cap left out. */
+  hiddenCount: number
+  /** Every declared trigger, enabled or not. */
+  triggerCount: number
+  /** Triggers that can actually fire. */
+  enabledCount: number
+  /** The definition itself is enabled — i.e. anything can start it at all. */
+  definitionEnabled: boolean
+}
+
+function readString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : ''
+}
+
+/**
+ * What the pill says, from the definition's triggers.
+ *
+ * Enabled triggers sort first so a disabled one can never push a live entry
+ * point past the cap — the overflow line has to hide the least load-bearing
+ * rows, not an arbitrary tail of the authoring order. Order is otherwise
+ * preserved, so the canvas lists triggers in the order the drawer does.
+ */
+export function buildTriggerNodeModel(
+  triggers: TriggerLike[] | null | undefined,
+  options: { definitionEnabled?: boolean } = {},
+): TriggerNodeModel {
+  const declared = (triggers ?? []).filter((trigger) => !!trigger && readString(trigger.eventPattern).length > 0)
+  const enabled = declared.filter((trigger) => trigger.enabled !== false)
+  const disabled = declared.filter((trigger) => trigger.enabled === false)
+  const ordered = [...enabled, ...disabled]
+
+  const rows: TriggerNodeEventRow[] = ordered.slice(0, TRIGGER_NODE_EVENT_LIMIT).map((trigger, index) => {
+    const eventPattern = readString(trigger.eventPattern)
+    return {
+      key: readString(trigger.triggerId) || `${eventPattern}:${index}`,
+      name: readString(trigger.name) || eventPattern,
+      eventPattern,
+      enabled: trigger.enabled !== false,
+    }
+  })
+
+  return {
+    rows,
+    hiddenCount: Math.max(0, ordered.length - rows.length),
+    triggerCount: ordered.length,
+    enabledCount: enabled.length,
+    definitionEnabled: options.definitionEnabled !== false,
+  }
+}
+
+/**
+ * Lines the pill renders below its header: one per shown event tag, one for the
+ * overflow when there is one, and the manual/API line — which is unconditional
+ * because that entry point always exists — or the disabled note, which replaces
+ * it because a disabled definition cannot be started by any means.
+ */
+export function triggerNodeRowCount(model: TriggerNodeModel): number {
+  if (!model.definitionEnabled) return 1
+  return model.rows.length + (model.hiddenCount > 0 ? 1 : 0) + 1
+}
+
+/**
+ * The pill's footprint. Derived, not measured — the node is placed relative to
+ * START before React Flow has measured anything.
+ */
+export function triggerNodeFootprint(model: TriggerNodeModel): { width: number; height: number } {
+  return {
+    width: TRIGGER_NODE_WIDTH,
+    height: TRIGGER_NODE_HEADER_HEIGHT + triggerNodeRowCount(model) * TRIGGER_NODE_ROW_HEIGHT,
+  }
+}
+
+export interface TriggerAnchorNode {
+  id: string
+  position: { x: number; y: number }
+  measured?: { width?: number; height?: number }
+}
+
+/**
+ * The pill, anchored to the START terminal.
+ *
+ * It sits one rank-gap to the LEFT of START and is centred on it. It is never
+ * given to dagre — a synthetic node has no rank, and ranking it would make it
+ * participate in the fork/join walks and in `validateWorkflowGraph`'s
+ * exactly-one-START count. Because dagre's LR layout puts START in the first
+ * rank, the gutter it is placed in is empty by construction, so not ranking it
+ * costs nothing.
+ *
+ * Non-interactive in every way that could corrupt the graph: not draggable, not
+ * selectable, not deletable, and not connectable, so no gesture can make it the
+ * source or target of a real transition. Clicking it is still useful — the pill
+ * renders its own button, which opens the definition drawer's triggers section.
+ */
+export function buildTriggerNode(
+  model: TriggerNodeModel,
+  startNode: TriggerAnchorNode,
+  data: Record<string, unknown> = {},
+): Node {
+  const { width, height } = triggerNodeFootprint(model)
+  const startHeight = startNode.measured?.height ?? TERMINAL_NODE_HEIGHT
+
+  return {
+    id: WORKFLOW_TRIGGER_NODE_ID,
+    type: WORKFLOW_TRIGGER_NODE_TYPE,
+    position: {
+      x: startNode.position.x - width - TRIGGER_NODE_GAP,
+      y: startNode.position.y + startHeight / 2 - height / 2,
+    },
+    data: { ...data, model },
+    draggable: false,
+    selectable: false,
+    focusable: false,
+    deletable: false,
+    connectable: false,
+  }
+}
+
+/**
+ * Where the pill lands and how big it is, without a DOM. The canvas places the
+ * node from exactly these numbers, so a layout assertion can check the box
+ * clears START rather than eyeballing a screenshot.
+ */
+export function triggerNodeBox(
+  model: TriggerNodeModel,
+  startNode: TriggerAnchorNode,
+): { x: number; y: number; width: number; height: number } {
+  const node = buildTriggerNode(model, startNode)
+  const { width, height } = triggerNodeFootprint(model)
+  return { x: node.position.x, y: node.position.y, width, height }
+}
+
+/** The START terminal's own box, in the same terms. */
+export function startNodeBox(
+  startNode: TriggerAnchorNode,
+): { x: number; y: number; width: number; height: number } {
+  return {
+    x: startNode.position.x,
+    y: startNode.position.y,
+    width: startNode.measured?.width ?? TERMINAL_NODE_MIN_WIDTH,
+    height: startNode.measured?.height ?? TERMINAL_NODE_HEIGHT,
+  }
+}
+
+/**
+ * The connector from the pill into START. Deliberately NOT a
+ * `workflowTransition`: it carries no condition, no activities and no id the
+ * engine resolves, so rendering it in the routes' own channel would be a lie an
+ * author could try to click. It uses React Flow's built-in bezier edge with the
+ * trigger dash pattern and is inert — unselectable, unfocusable, undeletable
+ * and unreconnectable, so no editing gesture can reach it.
+ */
+export function buildTriggerEdge(startNodeId: string, markerEnd?: Edge['markerEnd']): Edge {
+  return {
+    id: WORKFLOW_TRIGGER_EDGE_ID,
+    source: WORKFLOW_TRIGGER_NODE_ID,
+    target: startNodeId,
+    type: 'default',
+    selectable: false,
+    focusable: false,
+    deletable: false,
+    reconnectable: false,
+    ...(markerEnd ? { markerEnd } : {}),
+    style: {
+      stroke: EDGE_COLORS.pending.stroke,
+      strokeWidth: EDGE_COLORS.pending.strokeWidth,
+      strokeDasharray: TRIGGER_EDGE_DASH_ARRAY,
+    },
+  }
+}
+
+export function isTriggerNode(node: { id?: string; type?: string }): boolean {
+  return node?.type === WORKFLOW_TRIGGER_NODE_TYPE || node?.id === WORKFLOW_TRIGGER_NODE_ID
+}
+
+export function isTriggerEdge(edge: { id?: string; source?: string; target?: string }): boolean {
+  return edge?.id === WORKFLOW_TRIGGER_EDGE_ID || edge?.source === WORKFLOW_TRIGGER_NODE_ID
+}