experiment: pydantic-graph prototype for workflow engine replacement

[lambdabaa]

Summary

Standalone prototype validating whether pydantic-graph can replace the factory's custom workflow execution engine (primitives.py + executor.py). Lives in experiments/pydantic-graph-prototype/ as a side-by-side comparison — does not modify any existing factory code.

• Ports 3 progressively harder patterns: sequential chains, gate/verdict routing with typed return unions, and parallel fork/join via asyncio.gather
• 52 tests, 95% coverage, QA pipeline passed
• Full dual-engine comparison harness diffs event traces between both approaches
• Detailed migration verdict answering 5 prototype questions

Key Findings

Question	Verdict
Can BaseNode model factory node types?	YES — clean 1:1 mapping
Does return-type routing work for gates?	YES — biggest architectural gain
Does FactoryState + FactoryDeps carry context?	YES — cleaner than executor vars
Mermaid + Graph.iter() as bonus wins?	YES — significant observability gains
Can definitions.py patterns adapt?	YES — structural change, not syntactic

Infrastructure reduction: 74% (1,457 → 73 lines). The entire executor.py is replaced by Graph.run().

Recommendation: Proceed with thin-adapter migration starting with improve_workflow. See docs/migration-verdict.md for the full analysis.

How to review

cd experiments/pydantic-graph-prototype
pip install -e ".[dev]"
pytest          # 52 tests
pyright         # type checking

Key files:

• docs/migration-verdict.md — answers all 5 prototype questions with evidence
• docs/comparison-report.md — side-by-side event traces, LOC comparison, feature matrix
• src/pg_factory/nodes/ — BaseNode implementations (study chain, gates, parallel)
• src/pg_factory/compare.py — dual-engine comparison harness

Test plan

• All 52 tests pass (pytest)
• pyright strict mode clean
• Health check: PASS (95% coverage)
• Code review: no critical issues
• Adversarial testing: PASS (19 edge-case tests)
• Comparison harness: both engines produce equivalent event traces

🤖 Generated with Claude Code