root/fusion
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

FN-5761: add workflow IR parsing and serialization contract

Browse Source 
Implement the v1 workflow IR contract in core with validation, serialization, and coverage.

- add workflow IR type definitions, parser, serializer, and structured validation errors in @fusion/core
- export workflow IR APIs from core index and add comprehensive unit tests for valid/invalid shapes and metadata parsing
- document the workflow IR contract in workflow step docs and include release tracking via changesets, including plugin-sdk DOM lib prerequisite for Windows compilation

Files changed:
 .changeset/fn-5761-workflow-ir-contract.md       |   5 +
 .changeset/windows-release-plugin-sdk-dom-lib.md |   5 +
 docs/workflow-steps.md                           |  24 +++
 packages/core/src/__tests__/workflow-ir.test.ts  |  70 +++++++
 packages/core/src/index.ts                       |  15 ++
 packages/core/src/workflow-ir-types.ts           | 103 ++++++++++
 packages/core/src/workflow-ir.ts                 | 244 +++++++++++++++++++++++
 packages/plugin-sdk/tsconfig.json                |   7 +-
 8 files changed, 472 insertions(+), 1 deletion(-)

Fusion-Task-Id: FN-5761

Fusion-Task-Lineage: 2cd5491e-89c8-418c-a913-76d0c13b466c
This commit is contained in:
gsxdsm
2026-05-31 01:18:01 -07:00
parent acad46cc10
commit 3d22a98cf2
8 changed files with 472 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
docs/workflow-steps.md
View File

@@ -4,6 +4,30 @@
Workflow steps are reusable quality gates that run around task completion.
## Workflow IR (v1)
Fusion also defines a separate **Workflow Intermediate Representation (IR)** contract in `@fusion/core` for editor↔interpreter graph exchange. This IR is distinct from the post-implementation quality gates documented on this page (`WorkflowStep` templates and execution policies).
Workflow IR v1 is a JSON-safe graph document:
- `schemaVersion`: must be exactly `"1.0.0"` for v1 (`WORKFLOW_IR_SCHEMA_VERSION`)
- `metadata`: workflow-level JSON metadata (`name` required)
- `nodes`: node array with built-in kinds (`start`, `prompt`, `script`, `gate`, `end`)
- `edges`: directed links referencing node ids
Contract behavior:
- Parsing is strict: unsupported/missing versions, invalid node kinds, invalid shapes, and dangling edges are rejected at parse time.
- Serialization is stable JSON via `serializeWorkflowIr`; round-tripping `parseWorkflowIr(serializeWorkflowIr(ir))` preserves data.
- `BUILTIN_WORKFLOW_IR_FIXTURE` provides a complete built-in reference flow for parity testing.
Out of scope for v1:
- Plugin-contributed node kinds
- Layout/position metadata for editors
- Execution history/runtime traces
- Migration tooling for future schema versions (future versions should use explicit `schemaVersion` migrations)
## What They Are
A workflow step is a reusable check (AI prompt or script) that can be enabled on tasks.