Workflowzustände modellieren

Workflow Semantics & State Modeling

Use this skill when designing or implementing workflow data models, step contracts, execution state machines, and the boundary between visual graph editors and execution engines.

The Three-Layer Separation Principle

Never conflate a workflow's executable logic, its visual diagram layout, and its live runs:

1. Workflow Definition (WorkflowDefinition & WorkflowVersion):
   • The immutable, versioned directed graph of nodes (nodeId, stepType, typeVersion, config, credentialRefIds), typed ports, control-flow edges, and data-mapping expressions.
2. Visual Canvas Layout (WorkflowLayout / Viewport Metadata):
   • Node coordinates (x, y), dimensions, collapsed groups, zoom/pan camera state, and visual annotations. Moving a node by 50 pixels on the canvas must never alter execution semantics or force a breaking runtime change.
3. Execution Instance (WorkflowRun, StepExecution, StepAttempt):
   • A specific runtime invocation pinned to an immutable workflowVersionId with its own runId, tenant/actor context, input payload, current node token states, step outputs, wait timers, and attempt history.
   • Editing or saving a draft on the canvas must never mutate the definition or behavior of an already started WorkflowRun.

Versioned Step Registry & Explicit Contracts

• Maintain a versioned Step Type Catalog where every step type declares:
  • Input Schema: Required/optional typed parameters and allowed upstream expression bindings.
  • Config Schema: Static configuration fields and secret reference slots (never raw plaintext secrets in the definition JSON).
  • Output Schema: Deterministic output structure per outcome port (success, branch_true, branch_false, timeout, error).
  • Execution Semantics: Sync vs. async/waiting, idempotency behavior, timeout defaults, retry eligibility, and side-effect classification (pure transform vs. external mutation).
• Separate Control-Flow Edges (determining when a downstream node is activated) from Data-Flow Bindings (determining where a step reads its inputs from upstream outputs or run context).

Explicit Run and Step State Machines (Lamport)

Model distinct lifecycle states for both runs and steps:

• Run States: pending $\to$ running $\leftrightarrow$ waiting (timer / external event / human approval) $\to$ completed | failed | cancelling $\to$ cancelled.
• Step Execution States: pending, ready, running, waiting, succeeded, failed, skipped (dead-path eliminated on unchosen branch), cancelled, compensated.

Checklist

• Are the executable workflow definition, visual canvas coordinates, and runtime execution state stored as distinct structures?
• Is every WorkflowRun pinned to an immutable workflowVersionId so live edits never corrupt in-flight runs?
• Does every step type declare explicit input, configuration, and output schemas plus secret reference IDs?
• Do step states clearly distinguish skipped (unchosen branch), waiting, running, succeeded, failed, and cancelled?