Enforce document.dsl Version Validation #491

Summary

The document.dsl field currently exists in workflow definitions but is largely ignored by the compiler/runtime.

This issue proposes making document.dsl a required and validated field that represents the Zigflow DSL version used by the workflow definition.

Motivation

Although Zigflow currently supports a single DSL version, validating document.dsl provides several benefits:

• Prevents the field becoming decorative metadata
• Establishes a clear contract between workflow definitions and the Zigflow parser/compiler
• Creates a foundation for future DSL evolution
• Allows users to explicitly declare which Zigflow DSL version a workflow was authored against
• Enables clearer error messages when incompatible workflow definitions are encountered

Proposed Behaviour

A workflow definition must specify a DSL version:

document:
  dsl: 0.13.0

The compiler validates that the declared DSL version matches the supported DSL version.

For example:

Workflow DSL version: 0.13.0
Supported DSL version: 0.13.0

✓ Validation succeeds

Workflow DSL version: 0.12.0
Supported DSL version: 0.13.0

✗ Unsupported DSL version

Scope

In Scope

• Make document.dsl mandatory
• Validate document.dsl during workflow loading/compilation
• Return clear validation errors for unsupported versions
• Document the purpose and behaviour of the field

Out of Scope

• Supporting multiple DSL versions simultaneously
• Version negotiation
• Compatibility modes
• Automatic migrations
• Semver range support (1, 1.0, ^1.0.0, etc.)

Design Notes

For pre-1.0 Zigflow releases, only a single DSL version will be supported at any given time.

The declared version must match the supported version exactly.

Future versions of Zigflow may choose to support multiple DSL versions, but this proposal intentionally does not introduce any compatibility matrix or migration logic.

Acceptance Criteria

• document.dsl is required
• Workflow validation fails when document.dsl is missing
• Workflow validation fails when document.dsl does not match the supported DSL version
• Validation errors clearly indicate the expected and received versions
• Documentation explains the purpose of the field