FN-5761: add workflow IR parsing and serialization contract

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
2026-05-31 01:18:01 -07:00
parent acad46cc10
commit 3d22a98cf2
8 changed files with 472 additions and 1 deletions
--- a/packages/core/src/tests/workflow-ir.test.ts
+++ b/packages/core/src/tests/workflow-ir.test.ts
@@ -0,0 +1,70 @@
+import { describe, expect, it } from "vitest";
+import {
+  BUILTIN_WORKFLOW_IR_FIXTURE,
+  WORKFLOW_IR_SCHEMA_VERSION,
+  parseWorkflowIr,
+  serializeWorkflowIr,
+  WorkflowIrError,
+} from "../index.js";
+
+describe("workflow ir", () => {
+  it("round-trips fixture with no data loss", () => {
+    const serialized = serializeWorkflowIr(BUILTIN_WORKFLOW_IR_FIXTURE);
+    const parsed = parseWorkflowIr(serialized);
+    expect(parsed).toEqual(BUILTIN_WORKFLOW_IR_FIXTURE);
+  });
+
+  it("rejects missing or mismatched schemaVersion", () => {
+    expect(() =>
+      parseWorkflowIr({
+        metadata: { name: "missing-version" },
+        nodes: [],
+        edges: [],
+      }),
+    ).toThrowError(expect.objectContaining({ code: "unsupported_version" }));
+
+    expect(() =>
+      parseWorkflowIr({
+        schemaVersion: "2.0.0",
+        metadata: { name: "wrong-version" },
+        nodes: [],
+        edges: [],
+      }),
+    ).toThrowError(expect.objectContaining({ code: "unsupported_version" }));
+  });
+
+  it("rejects unknown node kinds and dangling edges", () => {
+    expect(() =>
+      parseWorkflowIr({
+        schemaVersion: WORKFLOW_IR_SCHEMA_VERSION,
+        metadata: { name: "unknown-kind" },
+        nodes: [{ id: "n1", kind: "custom" }],
+        edges: [],
+      }),
+    ).toThrowError(WorkflowIrError);
+
+    expect(() =>
+      parseWorkflowIr({
+        schemaVersion: WORKFLOW_IR_SCHEMA_VERSION,
+        metadata: { name: "dangling-edge" },
+        nodes: [{ id: "start", kind: "start" }],
+        edges: [{ id: "e1", from: "start", to: "missing" }],
+      }),
+    ).toThrowError(expect.objectContaining({ code: "dangling_edge" }));
+  });
+
+  it("parses fixture JSON string for interpreter parity", () => {
+    const json = JSON.stringify(BUILTIN_WORKFLOW_IR_FIXTURE);
+    const parsed = parseWorkflowIr(json);
+
+    expect(parsed.schemaVersion).toBe(WORKFLOW_IR_SCHEMA_VERSION);
+    expect(parsed.nodes.length).toBeGreaterThanOrEqual(1);
+    expect(parsed.edges.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it("exposes workflow ir surface from package entry", () => {
+    expect(typeof parseWorkflowIr).toBe("function");
+    expect(typeof serializeWorkflowIr).toBe("function");
+    expect(BUILTIN_WORKFLOW_IR_FIXTURE.schemaVersion).toBe(WORKFLOW_IR_SCHEMA_VERSION);
+  });
+});