Bug: Template validator doesn't recognize batch-specific variables

[spinje]

Summary

The template validator (src/pflow/runtime/template_validator.py) does not recognize batch-specific template variables, causing valid batch workflows to fail validation even though they execute correctly at runtime.

Reproduction

cat > /tmp/batch-test.json << 'WORKFLOW'
{
  "inputs": {"items": {"type": "array", "required": true}},
  "nodes": [
    {
      "id": "process",
      "type": "llm",
      "batch": {"items": "${items}", "parallel": true},
      "params": {"prompt": "Process: ${item}"}
    },
    {
      "id": "combine",
      "type": "shell",
      "params": {"stdin": "${process.results}", "command": "cat"}
    }
  ],
  "edges": [{"from": "process", "to": "combine"}]
}
WORKFLOW

uv run pflow --validate-only /tmp/batch-test.json

Expected Behavior

Validation should pass - this is a valid batch workflow.

Actual Behavior

✗ Static validation failed:
  • Node 'process' references undefined input '${item}' in parameter 'prompt'
  • Declared input(s) never used as template variable: items
  • Template variable ${item} has no valid source
  • Node 'process' (type: llm) does not output 'results'

Tip: Try using ${process.response} instead

Note: The workflow executes correctly at runtime - this is purely a validation issue.

Root Cause Analysis

Three related issues:

1. Batch Item Alias Not Recognized

_extract_node_outputs() only queries registry metadata for node interfaces. It has no awareness of batch configuration, so ${item} (or custom alias via batch.as) is not recognized as valid.

2. Batch Output Structure Not Recognized

The validator extracts outputs from the base node type (e.g., llm → response). It doesn't know that batch wrapping changes the output structure to results, count, success_count, error_count, errors, batch_metadata.

3. batch.items Template Not Extracted

_extract_all_templates() only scans node.params, not node.batch. So templates in batch.items aren't counted as "used", leading to the "unused input" warning.

Impact

• Batch workflows cannot be saved to the workflow library
• Users see confusing validation errors for valid workflows
• The "Tip" suggestions are wrong (suggests response when results is correct)

Files Affected

• src/pflow/runtime/template_validator.py
• src/pflow/core/workflow_data_flow.py

[spinje]

Implementation Guidance

From .taskmaster/knowledge/pitfalls.md:

When fixing this, audit ALL validation systems that reason about node outputs:

1. template_validator.py - Static template extraction and output recognition
2. workflow_data_flow.py - Data flow and execution order validation
3. Any other compile-time validation

Key insight: This is fundamentally a compile-time vs runtime mismatch. The batch wrapper transforms outputs at runtime, but validation happens at compile-time with no knowledge of wrappers.

---

Context from PR #19 code review