[Engine] Flow manifest / structural contract validation (one flow validate)

[ameet]

Problem

As flow count grows (50+), structural drift becomes inevitable. Steps get renamed, onError handlers get forgotten on new external calls, model routing gets inconsistent, step ordering breaks silently. There's no way to declare or enforce structural contracts on flows today.

What users build to compensate

Teams building complex flow systems end up creating external validation suites that check:

1. Required steps — does the flow have all expected steps?
2. Step ordering — does step A come before step B?
3. onError presence — do all external calls (bash with curl, claude, action steps) have error handlers?
4. Model routing — do LLM steps use the correct model?
5. Timeout caps — are timeouts within acceptable bounds?
6. Required inputs — are all expected inputs declared?
7. Sub-flow wiring — do flow steps call the correct child flows?

This is typically a JSON manifest file:

{
  "flows": [
    {
      "key": "my-flow",
      "requiredSteps": ["loadConfig", "buildResult"],
      "stepOrder": [["loadConfig", "processData"], ["processData", "buildResult"]],
      "onErrorPresence": ["externalApiCall", "llmStep"],
      "modelRouting": { "llmStep": "haiku" },
      "timeoutCap": { "llmStep": 90000 },
      "requiredInputs": ["company", "apiKey"],
      "subFlowWiring": { "loadConfig": "constants-load" }
    }
  ]
}

Then a separate script validates all flows against the manifest on every change.

Proposal

Add one flow validate [--manifest path/to/manifest.json] [--strict] that:

1. Without manifest (auto-discovery mode): Scans all flows for universal anti-patterns:

   • Bash steps with curl/claude missing onError
   • Code steps with optional chaining (?.) which doesn't work in the sandbox
   • Missing buildResult step (common convention)
   • Step references ($.steps.X) where X doesn't exist in the flow
   • Forward references (step A reads $.steps.B where B is declared after A)

2. With manifest (contract mode): Validates each flow against its declared structural contract (required steps, ordering, onError, model routing, timeout caps, inputs, sub-flow wiring).

Why this matters

A single one flow validate command would replace 8+ separate validation scripts that teams currently maintain. The validation logic is entirely generic — it's about flow structure, not business logic. This should be a platform feature.

Related

• [Feature Request] Validate step references at flow load time #44 (step reference validation)
• [Engine] Code steps should be syntax-checked at flow load time, not runtime #43 (syntax validation)
• [Feature Request] Step output type declarations for safer wiring #59 (step output type declarations)