Workflow validation and versions

Workflow Validation & Versioning

Use this skill when implementing structural graph validation, expression safety checks, save-vs-publish lifecycles, and immutable workflow versioning.

Shared Client & Server Graph Soundness Validation (Van der Aalst)

A visually connected graph is not automatically executable. Enforce the exact same structural and semantic validation rules in the editor UI and on the server before publishing or starting a run:

1. Entry, Exit & Reachability (Workflow Net Soundness):
   • Verify at least one valid trigger/start node exists and has no required incoming control edges.
   • Traverse forward from start nodes to detect unreachable/isolated islands and verify that every active path can reach a valid terminal node without dead-ending on an unconfigured port.
2. Cycle Detection & Bounded Loops:
   • Run topological sort / DFS cycle detection (Kahn's or Tarjan's algorithm).
   • Reject arbitrary directed cycles in DAG workflows; if structured looping (ForEach / RepeatUntil) is supported, require an explicit maxIterations cap and timeout ceiling.
3. Complete Step Configuration & Upstream Scope:
   • Validate every node's configuration against its StepType schema.
   • Verify that every variable reference ({{steps.stepA.output.id}}) points to a node that is guaranteed to execute upstream on all paths leading to the referencing node (not a sibling parallel branch or an unmerged conditional branch).
4. Safe, Sandboxed Condition & Expression Evaluation:
   • Never evaluate user-authored conditions or mappings with eval(), new Function(), or unrestricted server code execution.
   • Parse and validate expressions using a restricted, deterministic AST evaluator (e.g., JSONLogic, CEL, JMESPath, or a typed AST whitelist) with strict time and memory bounds.

Drafts vs. Immutable Published Versions

• Separate Editable Drafts from Published Versions:
  • Users may save an incomplete draft while editing, but publishing/activating a workflow requires passing full structural and schema validation and creates an immutable WorkflowVersion (versionNumber, content hash, publishedAt, publishedBy).
• Pin Triggers and Runs to Explicit Versions:
  • Subsequent edits create a new draft without mutating the published WorkflowVersion. Active runs always finish against the version they started on (unless an explicit, audited version-migration operation is invoked).

Checklist

• Does server-side validation enforce reachability, cycle detection, port wiring, and step config schemas before publish/run?
• Are variable references checked to ensure the referenced node is strictly upstream on all incoming paths?
• Are user conditions and data mappings evaluated in a safe, deterministic sandbox rather than eval?
• Does publishing create an immutable WorkflowVersion while preserving in-flight runs on their original version?