@foresthubai/workflow-core 0.3.0

package/src/workflow/serialization.test.ts

@@ -0,0 +1,240 @@
+import { describe, it, expect } from "vitest";
+import { serialize, deserialize, computeVariablesFromNodes, buildCanvasVariables } from "./serialization";
+import { MAIN_CANVAS_ID, type Workflow, type Canvas } from "./Workflow";
+import type { Schemas } from "../api";
+import type { NodeData } from "../node";
+
+// ============================================================================
+// Reverse roundtrip: api JSON → deserialize → serialize → deep-equal JSON
+//
+// This direction is the strongest invariant — deserialize is the function
+// that reconstructs derivable state (variable records); if it gets the rest
+// right, re-serialize must produce the same JSON back. Tests every code path
+// in deserialize + serialize without separately constructing WorkflowState.
+// ============================================================================
+
+const empty: Schemas["Workflow"] = {
+  schemaVersion: 1,
+  nodes: [],
+  edges: [],
+  functions: [],
+  declaredVariables: [],
+  channels: [],
+  memory: [],
+  models: [],
+};
+
+const mainOnly: Schemas["Workflow"] = {
+  schemaVersion: 1,
+  nodes: [
+    {
+      id: "n1",
+      type: "Agent",
+      position: { x: 100, y: 200 },
+      label: "My Agent",
+      arguments: {
+        name: "agent-1",
+        model: "claude-opus-4-7",
+        instructions: "be helpful",
+        outputDeclarations: [],
+        memoryRefs: [],
+        answer: { active: true, mode: "emit", name: "answer" },
+      },
+    },
+  ],
+  edges: [],
+  functions: [],
+  declaredVariables: [
+    { uid: "d1", name: "counter", dataType: "int", initialValue: 0 },
+  ],
+  channels: [],
+  memory: [],
+  models: [],
+};
+
+const allEdgeTypes: Schemas["Workflow"] = {
+  schemaVersion: 1,
+  nodes: [],
+  edges: [
+    { id: "edge-control", type: "control", from: { nodeId: "a", port: "out" }, to: { nodeId: "b", port: "in" } },
+    { id: "edge-tool", type: "tool", from: { nodeId: "a", port: "tool-out" }, to: { nodeId: "b", port: "tool-in" } },
+    {
+      id: "edge-task",
+      type: "agentTask",
+      from: { nodeId: "agent", port: "tool" },
+      to: { nodeId: "task", port: "trigger" },
+      prompt: { expression: '"summarize"', references: [], dataType: "string" },
+    },
+    {
+      id: "edge-choice",
+      type: "agentChoice",
+      from: { nodeId: "agent", port: "choice" },
+      to: { nodeId: "branchA", port: "in" },
+      description: "when the user asks about weather",
+    },
+    {
+      id: "edge-delegate",
+      type: "agentDelegate",
+      from: { nodeId: "agent", port: "delegate" },
+      to: { nodeId: "sub", port: "in" },
+      prompt: { expression: '"continue"', references: [], dataType: "string" },
+      description: "delegate everything else",
+    },
+  ],
+  functions: [],
+  declaredVariables: [],
+  channels: [],
+  memory: [],
+  models: [],
+};
+
+const withFunctionCanvas: Schemas["Workflow"] = {
+  schemaVersion: 1,
+  nodes: [
+    {
+      id: "fcall",
+      type: "FunctionCall",
+      position: { x: 0, y: 0 },
+      // The wire stores only the reference; the signature is resolved from
+      // `functions[]` and the snapshot rebuilt on deserialize.
+      functionId: "fn-uuid",
+      arguments: {
+        inputBindings: {
+          "arg-x": { expression: "1", references: [], dataType: "int" },
+          "arg-y": { expression: "2", references: [], dataType: "int" },
+        },
+        outputBindings: {
+          "ret-sum": { active: true, mode: "emit", name: "result" },
+        },
+      },
+    },
+  ],
+  edges: [],
+  functions: [
+    {
+      functionInfo: {
+        id: "fn-uuid",
+        version: 1,
+        name: "add",
+        arguments: [
+          { uid: "arg-x", name: "x", dataType: "int" },
+          { uid: "arg-y", name: "y", dataType: "int" },
+        ],
+        returns: [{ uid: "ret-sum", name: "sum", dataType: "int" }],
+      },
+      outputAssignments: {
+        "ret-sum": { expression: "x + y", references: [
+          { srcId: "fnarg", varId: "arg-x" },
+          { srcId: "fnarg", varId: "arg-y" },
+        ], dataType: "int" },
+      },
+      nodes: [],
+      edges: [],
+      declaredVariables: [],
+    },
+  ],
+  declaredVariables: [],
+  channels: [],
+  memory: [],
+  models: [],
+};
+
+describe("workflowSerialization — reverse roundtrip (JSON → deserialize → serialize)", () => {
+  it("empty workflow", () => {
+    expect(serialize(deserialize(empty))).toEqual(empty);
+  });
+
+  it("main canvas with declared variables and one node", () => {
+    expect(serialize(deserialize(mainOnly))).toEqual(mainOnly);
+  });
+
+  it("preserves all edge type variants verbatim, including ids", () => {
+    const out = serialize(deserialize(allEdgeTypes));
+    expect(out).toEqual(allEdgeTypes);
+    // Specific guardrail: each edge id is preserved (the bug we fixed).
+    const ids = out.edges.map((e) => e.id).sort();
+    expect(ids).toEqual(["edge-choice", "edge-control", "edge-delegate", "edge-task", "edge-tool"]);
+  });
+
+  it("function canvas with fnargs, output assignments, and a FunctionCall on main", () => {
+    const out = serialize(deserialize(withFunctionCanvas));
+    expect(out).toEqual(withFunctionCanvas);
+  });
+});
+
+// ============================================================================
+// Forward roundtrip: WorkflowState → serialize → deserialize → equality
+//
+// Variables are reconstructed from nodes + functionInfo + declared on every
+// deserialize. To get exact equality, build fixtures whose `variables` field
+// matches what reconstruction would produce (i.e., let buildCanvasVariables
+// produce the expected value for us).
+// ============================================================================
+
+function makeMainCanvas(nodes: Canvas["nodes"] = [], edges: Canvas["edges"] = [], declared: Schemas["Variable"][] = []): Canvas {
+  return {
+    nodes,
+    edges,
+    variables: buildCanvasVariables(nodes, [], declared),
+  };
+}
+
+describe("workflowSerialization — forward roundtrip (state → serialize → deserialize)", () => {
+  it("empty state roundtrips to a state with an empty main canvas", () => {
+    const state: Workflow = { canvases: { [MAIN_CANVAS_ID]: makeMainCanvas() }, functions: {}, channels: {}, memory: {}, models: {} };
+    expect(deserialize(serialize(state))).toEqual(state);
+  });
+
+  it("preserves edge ids across serialize/deserialize", () => {
+    const edges: Canvas["edges"] = [
+      { id: "stable-id-A", type: "control", source: "n1", sourceHandle: "out", target: "n2", targetHandle: "in" },
+      { id: "stable-id-B", type: "tool", source: "n1", sourceHandle: "tool", target: "n3", targetHandle: "in" },
+    ];
+    const state: Workflow = { canvases: { [MAIN_CANVAS_ID]: makeMainCanvas([], edges) }, functions: {}, channels: {}, memory: {}, models: {} };
+    const roundTripped = deserialize(serialize(state));
+    expect(roundTripped.canvases[MAIN_CANVAS_ID]!.edges.map((e) => e.id)).toEqual(["stable-id-A", "stable-id-B"]);
+  });
+});
+
+// ============================================================================
+// Variable reconstruction guardrails
+// ============================================================================
+
+describe("buildCanvasVariables", () => {
+  it("reconstructs node-output variables from nodes via getNodeOutput", () => {
+    const nodes: NodeData[] = [
+      {
+        id: "agent1",
+        type: "Agent",
+        arguments: {
+          name: "a",
+          model: "claude-opus-4-7",
+          instructions: "",
+          maxTurns: undefined,
+          outputDeclarations: [],
+          memoryRefs: [],
+          answer: { active: true, mode: "emit", name: "answer" },
+        },
+      } as NodeData,
+    ];
+    const vars = computeVariablesFromNodes(nodes);
+    // Agent emits at least one output (the answer); key is "<nodeId>:<outputId>".
+    const keys = Object.keys(vars);
+    expect(keys.length).toBeGreaterThan(0);
+    expect(keys.every((k) => k.startsWith("agent1:"))).toBe(true);
+  });
+
+  it("merges declared + fnarg + node-output into disjoint key namespaces", () => {
+    const declared: Schemas["Variable"][] = [{ uid: "d1", name: "x", dataType: "int" }];
+    const fnInfo = {
+      id: "fn",
+      version: 1,
+      name: "f",
+      arguments: [{ uid: "a1", name: "arg1", dataType: "int" as const }],
+      returns: [],
+    };
+    const merged = buildCanvasVariables([], fnInfo.arguments, declared);
+    expect(merged["declared:d1"]).toMatchObject({ kind: "declared", uid: "d1" });
+    expect(merged["fnarg:a1"]).toMatchObject({ kind: "fnarg", uid: "a1" });
+  });
+});

package/src/workflow/serialization.ts

@@ -0,0 +1,242 @@
+// Pure conversion between the api format (Schemas["Workflow"])
+// and the domain shape (Workflow).
+// Two producers feed serialize: the editor reads its live stores into
+// a Workflow literal; the CLI calls deserialize on parsed JSON.
+
+import type { Schemas } from "../api";
+import type { NodeData } from "../node";
+import type { FunctionDeclaration, FunctionInfo } from "../function";
+import { serialize as serializeFunction, deserialize as deserializeFunction } from "../function";
+import { getNodeOutput, isNodeUsedAsTool } from "../node/methods";
+import { ALL_CHANNEL_TYPES, type ApiChannel, type Channel, type ChannelType } from "../channel";
+import { serialize as serializeChannel, deserialize as deserializeChannel } from "../channel";
+import type { Memory } from "../memory";
+import { serialize as serializeMemory, deserialize as deserializeMemory } from "../memory";
+import type { Model } from "../model";
+import { serialize as serializeModel, deserialize as deserializeModel } from "../model";
+import { serialize as serializeNode, deserialize as deserializeNode } from "../node";
+import { serialize as serializeEdge, deserialize as deserializeEdge } from "../edge";
+import type { Variable, NodeOutputVariable } from "../variable";
+import { declaredVarKey, fnargKey, nodeOutputVarKey, ensureUids } from "../variable";
+import { MAIN_CANVAS_ID, type Workflow, type Canvas } from "./Workflow";
+import { CURRENT_SCHEMA_VERSION } from "../migration";
+
+const KNOWN_CHANNEL_TYPES = new Set<ChannelType>(ALL_CHANNEL_TYPES);
+
+/**
+ * Serialize domain → api Workflow. Multi-canvas
+ * mapping: the `main` canvas's nodes/edges/declaredVariables land at the
+ * root of `Workflow`; every other canvas becomes a `Function` entry in
+ * `Workflow.functions[]`, carrying its own functionInfo + outputAssignments.
+ */
+export function serialize(state: Workflow): Schemas["Workflow"] {
+  const mainCanvas = state.canvases[MAIN_CANVAS_ID];
+  if (!mainCanvas) {
+    throw new Error("Main canvas missing");
+  }
+  const mainNodes = mainCanvas.nodes.map((n) => serializeNode(n, isNodeUsedAsTool(n.id, n, mainCanvas.edges)));
+  const mainEdges = mainCanvas.edges.map(serializeEdge);
+  const mainDeclared = extractDeclaredVariables(mainCanvas.variables);
+
+  // Each declaration + its body canvas (joined by id) becomes one wire Function.
+  // The declaration splits into functionInfo + outputAssignments via serializeFunction.
+  const functions: Schemas["Function"][] = [];
+  for (const [id, decl] of Object.entries(state.functions)) {
+    const body = state.canvases[id];
+    if (!body) {
+      throw new Error(`[workflow-core] function ${id} has no body canvas — cannot serialize`);
+    }
+    const { functionInfo, outputAssignments } = serializeFunction(decl);
+    functions.push({
+      functionInfo,
+      outputAssignments,
+      nodes: body.nodes.map((n) => serializeNode(n, isNodeUsedAsTool(n.id, n, body.edges))),
+      edges: body.edges.map(serializeEdge),
+      declaredVariables: extractDeclaredVariables(body.variables),
+    });
+  }
+
+  const channels = Object.values(state.channels).map(serializeChannel);
+  const memory = Object.values(state.memory).map(serializeMemory);
+  const models = Object.values(state.models).map(serializeModel);
+  return {
+    schemaVersion: CURRENT_SCHEMA_VERSION,
+    nodes: mainNodes,
+    edges: mainEdges,
+    functions,
+    declaredVariables: mainDeclared,
+    channels,
+    memory,
+    models,
+  };
+}
+
+/**
+ * Deserialize api → domain Workflow. Variable
+ * records are reconstructed per canvas (declared from the api; fnarg
+ * from `functionInfo.arguments`; node-output via {@link computeVariablesFromNodes})
+ * since the api intentionally carries only `declaredVariables` to avoid
+ * redundancy.
+ *
+ * Each node is a flat {@link Node} (domain `NodeData` + `position`);
+ * its `type` is the domain node type (e.g. "Agent"). Workflow-builder projects
+ * that into a React Flow display type during store hydration — editor-only.
+ */
+export function deserialize(workflow: Schemas["Workflow"]): Workflow {
+  const canvases: Record<string, Canvas> = {};
+  const functions: Record<string, FunctionDeclaration> = {};
+
+  // Pre-build the function-info table so FunctionCall nodes — on the main canvas or
+  // in any function body — can rebuild their signature snapshot from the wire's
+  // `functionId`. (The wire stores only the reference; the engine likewise resolves
+  // by id, so the snapshot is editor-side state reconstructed here.)
+  const functionInfos: Record<string, FunctionInfo> = {};
+  for (const fn of workflow.functions ?? []) {
+    functionInfos[fn.functionInfo.id] = {
+      ...fn.functionInfo,
+      arguments: ensureUids(fn.functionInfo.arguments),
+      returns: ensureUids(fn.functionInfo.returns),
+    };
+  }
+  const resolveFunctionInfo = (id: string): FunctionInfo | undefined => functionInfos[id];
+
+  // Main canvas: data at the api root. No function declaration.
+  const mainNodes = workflow.nodes.map((n) => deserializeNode(n, resolveFunctionInfo));
+  const mainEdges = workflow.edges.map(deserializeEdge);
+  const mainDeclared = workflow.declaredVariables ?? [];
+  canvases[MAIN_CANVAS_ID] = {
+    nodes: mainNodes,
+    edges: mainEdges,
+    variables: buildCanvasVariables(mainNodes, [], mainDeclared),
+  };
+
+  // Each wire Function splits into a project-scoped declaration (functions[id]) and
+  // its body canvas (canvases[id]), joined by the function id.
+  for (const fn of workflow.functions ?? []) {
+    const functionInfo = functionInfos[fn.functionInfo.id]!;
+    const decl = deserializeFunction(functionInfo, fn.outputAssignments ?? {});
+    functions[decl.id] = decl;
+    const fnNodes = fn.nodes.map((n) => deserializeNode(n, resolveFunctionInfo));
+    const fnEdges = fn.edges.map(deserializeEdge);
+    canvases[decl.id] = {
+      nodes: fnNodes,
+      edges: fnEdges,
+      variables: buildCanvasVariables(fnNodes, decl.arguments, fn.declaredVariables ?? []),
+    };
+  }
+
+  const channels: Record<string, Channel> = {};
+  for (const c of workflow.channels ?? []) {
+    if (!KNOWN_CHANNEL_TYPES.has(c.type as ChannelType)) continue;
+    const instance = deserializeChannel(c as ApiChannel);
+    channels[instance.id] = instance;
+  }
+
+  const memory: Record<string, Memory> = {};
+  for (const m of workflow.memory ?? []) {
+    const instance = deserializeMemory(m);
+    memory[instance.id] = instance;
+  }
+
+  const models: Record<string, Model> = {};
+  for (const m of workflow.models ?? []) {
+    const instance = deserializeModel(m);
+    models[instance.id] = instance;
+  }
+
+  return {
+    canvases,
+    functions,
+    channels,
+    memory,
+    models,
+  };
+}
+
+// ============================================================================
+// Variable reconstruction
+// ============================================================================
+
+/**
+ * Derive node-output variables (`{kind: "node", nodeId, outputId, ...}`)
+ * from an array of node instances. Calls {@link getNodeOutput} to inspect
+ * each node's declared outputs.
+ *
+ * Ported from workflow-builder's canvasStore to take NodeData[] directly
+ * (NodeData carries id at the top level — no React Flow wrapper needed).
+ */
+export function computeVariablesFromNodes(nodes: NodeData[]): Record<string, NodeOutputVariable> {
+  const out: Record<string, NodeOutputVariable> = {};
+  for (const node of nodes) {
+    for (const [outputId, variable] of Object.entries(getNodeOutput(node))) {
+      out[nodeOutputVarKey(node.id, outputId)] = {
+        kind: "node",
+        nodeId: node.id,
+        outputId,
+        name: variable.name,
+        dataType: variable.dataType,
+      };
+    }
+  }
+  return out;
+}
+
+/**
+ * Merge the three variable sources into a single per-canvas record:
+ *   declared (from api)
+ * + fnarg    (derived from the function's `arguments` — empty for the main canvas)
+ * + nodeOutput (derived from nodes via {@link computeVariablesFromNodes})
+ *
+ * Disjoint key namespaces (`declared:`, `fnarg:`, `<nodeId>:<outputId>`) so
+ * merge order is irrelevant.
+ */
+export function buildCanvasVariables(
+  nodes: NodeData[],
+  fnArgs: readonly Schemas["Variable"][],
+  declaredVariables: readonly Schemas["Variable"][],
+): Record<string, Variable> {
+  const variables: Record<string, Variable> = computeVariablesFromNodes(nodes);
+  for (const arg of fnArgs) {
+    variables[fnargKey(arg.uid)] = {
+      kind: "fnarg",
+      uid: arg.uid,
+      name: arg.name,
+      dataType: arg.dataType,
+    };
+  }
+  for (const dv of declaredVariables) {
+    variables[declaredVarKey(dv.uid)] = {
+      kind: "declared",
+      uid: dv.uid,
+      name: dv.name,
+      dataType: dv.dataType,
+      ...(dv.initialValue !== undefined ? { initialValue: dv.initialValue } : {}),
+    };
+  }
+  return variables;
+}
+
+// ============================================================================
+// Helpers — declared variables
+// ============================================================================
+
+/**
+ * Filter a canvas's variables down to the declared-kind entries (the only
+ * variety the api persists). Node-output and fnarg variables are
+ * reconstructed on deserialize from nodes + functionInfo.
+ */
+function extractDeclaredVariables(variables: Record<string, Variable>): Schemas["Variable"][] {
+  const result: Schemas["Variable"][] = [];
+  for (const v of Object.values(variables)) {
+    if (v.kind === "declared") {
+      result.push({
+        uid: v.uid,
+        name: v.name,
+        dataType: v.dataType,
+        ...(v.initialValue !== undefined ? { initialValue: v.initialValue } : {}),
+      });
+    }
+  }
+  return result;
+}
+