@foresthubai/workflow-core 0.4.6 → 0.4.8

package/src/deploy/requirements.test.ts

@@ -1,64 +1,165 @@
-// SPDX-License-Identifier: Apache-2.0
-// Copyright (c) 2026 ForestHub.
-
-import { describe, it, expect } from "vitest";
-import { getReferencedCatalogModelIds } from "./requirements";
-import { MAIN_CANVAS_ID, type Workflow, type Canvas } from "../workflow";
-import type { Node } from "../node";
-import type { Model } from "../model";
-
-// Minimal Agent node referencing `model`. Cast through the union — only id/type/
-// arguments.model matter to the walk.
-function agent(id: string, model: string): Node {
-  return {
-    id,
-    type: "Agent",
-    position: { x: 0, y: 0 },
-    arguments: {
-      name: id,
-      model,
-      instructions: "",
-      outputDeclarations: [],
-      memoryRefs: [],
-      answer: { active: true, mode: "emit", name: "answer" },
-    },
-  } as Node;
-}
-
-function canvas(nodes: Node[]): Canvas {
-  return { nodes, edges: [], variables: {} };
-}
-
-const customModel: Model = { id: "custom-llm", label: "Custom", type: "LLMModel", arguments: {} };
-
-function workflow(canvases: Workflow["canvases"], models: Record<string, Model> = {}): Workflow {
-  return { canvases, functions: {}, channels: {}, memory: {}, models };
-}
-
-describe("getReferencedCatalogModelIds", () => {
-  it("returns catalog ids (referenced but not declared), excluding declared customs", () => {
-    const wf = workflow(
-      { [MAIN_CANVAS_ID]: canvas([agent("n1", "claude-opus-4-7"), agent("n2", "custom-llm")]) },
-      { "custom-llm": customModel },
-    );
-    expect(getReferencedCatalogModelIds(wf)).toEqual(["claude-opus-4-7"]);
-  });
-
-  it("ignores unset model references", () => {
-    const wf = workflow({ [MAIN_CANVAS_ID]: canvas([agent("n1", "")]) });
-    expect(getReferencedCatalogModelIds(wf)).toEqual([]);
-  });
-
-  it("dedupes across nodes and walks every canvas (main + function bodies)", () => {
-    const wf = workflow({
-      [MAIN_CANVAS_ID]: canvas([agent("n1", "claude-opus-4-7"), agent("n2", "claude-opus-4-7")]),
-      fnBody: canvas([agent("n3", "gemini-2")]),
-    });
-    expect(getReferencedCatalogModelIds(wf).sort()).toEqual(["claude-opus-4-7", "gemini-2"]);
-  });
-
-  it("returns nothing when every referenced model is declared", () => {
-    const wf = workflow({ [MAIN_CANVAS_ID]: canvas([agent("n1", "custom-llm")]) }, { "custom-llm": customModel });
-    expect(getReferencedCatalogModelIds(wf)).toEqual([]);
-  });
-});
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 ForestHub.
+
+import { describe, it, expect } from "vitest";
+import { workflowBindingRequirements, getReferencedCatalogModelIds, type BindingKind } from "./requirements";
+import { MAIN_CANVAS_ID, type Workflow, type Canvas } from "../workflow";
+import type { Channel, ChannelType } from "../channel";
+import type { Model } from "../model";
+import type { Node } from "../node";
+
+function channel(id: string, type: ChannelType): Channel {
+  return { id, label: id, type, arguments: {} };
+}
+
+const llm = (id: string): Model => ({ id, label: id, type: "LLMModel", arguments: {} });
+const ml = (id: string): Model => ({ id, label: id, type: "MLModel", arguments: {} });
+
+// Minimal Agent node referencing a catalog model by id — only the model ref
+// matters to the requirement walk. Cast through the union: the other Agent args
+// are irrelevant here.
+function agent(id: string, model: string): Node {
+  return {
+    id,
+    type: "Agent",
+    position: { x: 0, y: 0 },
+    arguments: {
+      name: id,
+      model,
+      instructions: "",
+      outputDeclarations: [],
+      memoryRefs: [],
+      answer: { active: true, mode: "emit", name: "answer" },
+    },
+  } as unknown as Node;
+}
+
+const canvas = (nodes: Node[]): Canvas => ({ nodes, edges: [], variables: {} });
+
+// Build a workflow from parts. `nodes` fills the main canvas; pass `canvases`
+// instead to model multiple bodies (main + function). Any other field
+// (channels, models) overrides the empty default.
+function workflow(parts: Partial<Workflow> & { nodes?: Node[] }): Workflow {
+  const { nodes = [], ...rest } = parts;
+  return {
+    canvases: { [MAIN_CANVAS_ID]: canvas(nodes) },
+    functions: {},
+    channels: {},
+    memory: {},
+    models: {},
+    ...rest,
+  };
+}
+
+const byId = (chs: Channel[]): Record<string, Channel> => Object.fromEntries(chs.map((c) => [c.id, c]));
+const modelsById = (ms: Model[]): Record<string, Model> => Object.fromEntries(ms.map((m) => [m.id, m]));
+
+// CROSS-LANGUAGE CONFORMANCE. Each case below is a golden fixture: a workflow in,
+// an exact id->kind surface out. The backend's deploy.WorkflowBindingRequirements
+// must produce the identical map for the same workflow — mirror these fixtures on
+// the Go side so the two extractors stay pinned. Divergence here is deploy drift:
+// OSS and the backend disagreeing about what a workflow needs bound.
+describe("workflowBindingRequirements", () => {
+  it("returns an empty surface for an empty workflow", () => {
+    expect(workflowBindingRequirements(workflow({}))).toEqual({});
+  });
+
+  it("maps every hardware channel family to 'hardware'", () => {
+    const chs = byId([
+      channel("in", "GPIOIN"),
+      channel("out", "GPIOOUT"),
+      channel("adc", "ADC"),
+      channel("dac", "DAC"),
+      channel("pwm", "PWM"),
+      channel("uart", "UART"),
+    ]);
+    const expected: Record<string, BindingKind> = {
+      in: "hardware",
+      out: "hardware",
+      adc: "hardware",
+      dac: "hardware",
+      pwm: "hardware",
+      uart: "hardware",
+    };
+    expect(workflowBindingRequirements(workflow({ channels: chs }))).toEqual(expected);
+  });
+
+  it("maps MQTT to 'mqtt' and CAMERA to 'camera' (OSS-ahead kind)", () => {
+    const chs = byId([channel("telemetry", "MQTT"), channel("cam0", "CAMERA")]);
+    expect(workflowBindingRequirements(workflow({ channels: chs }))).toEqual({ telemetry: "mqtt", cam0: "camera" });
+  });
+
+  it("binds nothing for a LOG channel", () => {
+    const chs = byId([channel("log", "LOG"), channel("led", "GPIOOUT")]);
+    expect(workflowBindingRequirements(workflow({ channels: chs }))).toEqual({ led: "hardware" });
+  });
+
+  it("splits declared models: LLMModel -> 'declaredModel', MLModel -> 'mlInference'", () => {
+    const models = modelsById([llm("local-llm"), ml("yolo")]);
+    expect(workflowBindingRequirements(workflow({ models }))).toEqual({ "local-llm": "declaredModel", yolo: "mlInference" });
+  });
+
+  it("maps a referenced-but-undeclared catalog model to 'catalogModel', keyed by model id", () => {
+    const wf = workflow({ nodes: [agent("a1", "gpt-4o")] });
+    expect(workflowBindingRequirements(wf)).toEqual({ "gpt-4o": "catalogModel" });
+  });
+
+  it("prefers 'declaredModel' when an id is both declared and referenced (no overwrite)", () => {
+    const wf = workflow({ models: modelsById([llm("shared")]), nodes: [agent("a1", "shared")] });
+    expect(workflowBindingRequirements(wf)).toEqual({ shared: "declaredModel" });
+  });
+
+  it("does not extract MemoryFile / VectorDatabase memory (RAG not yet in the OSS surface)", () => {
+    const wf = workflow({
+      memory: { notes: { id: "notes", label: "Notes", type: "MemoryFile", arguments: {} } as Workflow["memory"][string] },
+    });
+    expect(workflowBindingRequirements(wf)).toEqual({});
+  });
+
+  it("produces the full surface for a mixed workflow", () => {
+    const wf = workflow({
+      channels: byId([channel("led", "GPIOOUT"), channel("telemetry", "MQTT"), channel("cam0", "CAMERA"), channel("log", "LOG")]),
+      models: modelsById([llm("local-llm"), ml("yolo")]),
+      nodes: [agent("a1", "claude-sonnet")],
+    });
+    const expected: Record<string, BindingKind> = {
+      led: "hardware",
+      telemetry: "mqtt",
+      cam0: "camera",
+      "local-llm": "declaredModel",
+      yolo: "mlInference",
+      "claude-sonnet": "catalogModel",
+    };
+    expect(workflowBindingRequirements(wf)).toEqual(expected);
+  });
+});
+
+describe("getReferencedCatalogModelIds", () => {
+  it("returns catalog ids (referenced but not declared), excluding declared customs", () => {
+    const wf = workflow({
+      canvases: { [MAIN_CANVAS_ID]: canvas([agent("n1", "claude-opus-4-7"), agent("n2", "custom-llm")]) },
+      models: modelsById([llm("custom-llm")]),
+    });
+    expect(getReferencedCatalogModelIds(wf)).toEqual(["claude-opus-4-7"]);
+  });
+
+  it("ignores unset model references", () => {
+    const wf = workflow({ nodes: [agent("n1", "")] });
+    expect(getReferencedCatalogModelIds(wf)).toEqual([]);
+  });
+
+  it("dedupes across nodes and walks every canvas (main + function bodies)", () => {
+    const wf = workflow({
+      canvases: {
+        [MAIN_CANVAS_ID]: canvas([agent("n1", "claude-opus-4-7"), agent("n2", "claude-opus-4-7")]),
+        fnBody: canvas([agent("n3", "gemini-2")]),
+      },
+    });
+    expect(getReferencedCatalogModelIds(wf).sort()).toEqual(["claude-opus-4-7", "gemini-2"]);
+  });
+
+  it("returns nothing when every referenced model is declared", () => {
+    const wf = workflow({ nodes: [agent("n1", "custom-llm")], models: modelsById([llm("custom-llm")]) });
+    expect(getReferencedCatalogModelIds(wf)).toEqual([]);
+  });
+});

package/src/deploy/requirements.ts

@@ -1,159 +1,122 @@
-// SPDX-License-Identifier: Apache-2.0
-// Copyright (c) 2026 ForestHub.
-
-import type { Workflow } from "../workflow";
-import { NodeRegistry, isNodeUsedAsTool } from "../node";
-import { isParameterActive } from "../parameter";
-
-/**
- * Model ids that nodes reference but the workflow does not declare in `models`.
- * A `modelSelect` accepts exactly two sources — declared custom models and the
- * static catalog — so any referenced id that isn't a declared model is a catalog
- * model: it carries no declared config, yet still needs a provider/credential
- * supplied at deploy.
- *
- * This is the one deploy demand the workflow's resource arrays can't express:
- * channels/memory/declared-models are enumerable directly from
- * `workflow.{channels,memory,models}`, but catalog model ids live only on the
- * nodes that pick them — hence the walk. Spans every canvas (main + function
- * bodies) and honors parameter activation, so a model behind an inactive
- * `modelSelect` (pruned on serialize, never deployed) is not counted.
- */
-export function getReferencedCatalogModelIds(workflow: Workflow): string[] {
-  const declaredModel = new Set(Object.keys(workflow.models));
-  const catalogIds = new Set<string>();
-
-  for (const canvas of Object.values(workflow.canvases)) {
-    for (const node of canvas.nodes) {
-      const def = NodeRegistry.getByType(node.type);
-      if (!def) continue;
-      const args = node.arguments as Record<string, unknown>;
-      const isToolInput = isNodeUsedAsTool(node.id, node, canvas.edges);
-      for (const param of def.parameters) {
-        if (param.type !== "modelSelect") continue;
-        if (!isParameterActive(param, args, isToolInput)) continue;
-        const id = args[param.id];
-        if (typeof id === "string" && id !== "" && !declaredModel.has(id)) {
-          catalogIds.add(id);
-        }
-      }
-    }
-  }
-
-  return [...catalogIds];
-}
-
-// The five hardware-channel families the engine has a driver for. UART is the
-// odd one out: it carries no per-channel sub-address (see `addressable`).
-export type HardwareFamily = "gpio" | "adc" | "dac" | "pwm" | "serial";
-
-// One hardware channel the workflow declares. `family` is derived from the
-// channel type; `addressable` is false only for serial/UART (every
-// gpio/adc/dac/pwm channel needs an `index` sub-address, UART does not).
-export interface HardwareChannel {
-  id: string;
-  label: string;
-  family: HardwareFamily;
-  addressable: boolean;
-}
-
-export interface MqttChannel {
-  id: string;
-  label: string;
-}
-
-// One custom/self-hosted model declared in workflow.models — needs an
-// ExternalResources provider entry (a device sidecar or a network endpoint).
-export interface CustomModel {
-  id: string;
-  label: string;
-}
-
-// What a workflow needs from its environment, derived from its content alone —
-// no operator input. Drives both input collection (which bindings to ask for)
-// and the spec resolver's completeness check. The component-set derivation the
-// migration doc names as must-not-be-duplicated lives here, shared by every
-// producer.
-export interface DeployRequirements {
-  // At least one Agent references a catalog model (not declared in
-  // workflow.models) — that model needs a provider key as engine env.
-  hasProviderModel: boolean;
-  // The workflow has a Retriever node. A standalone engine has no retriever, so
-  // the node cannot resolve — a producer may refuse to deploy.
-  hasRetriever: boolean;
-  // The workflow has a WebSearchTool node — needs a web-search key as engine env.
-  hasWebSearch: boolean;
-  // Every hardware channel, in declaration order; drives the device manifest +
-  // mapping + container device passthrough.
-  hardwareChannels: HardwareChannel[];
-  // Every MQTT channel; each becomes an ExternalResources entry + a mapping.
-  mqttChannels: MqttChannel[];
-  // Every declared custom model; each becomes an ExternalResources provider + a
-  // mapping (and a llama-server sidecar when bound on-device).
-  customModels: CustomModel[];
-}
-
-// Drift sentinel: a new ChannelType widens the switch input and breaks
-// compilation here until the new type is classified above.
-function assertNeverChannel(t: never): never {
-  throw new Error(`unhandled channel type: ${String(t)}`);
-}
-
-// deriveRequirements reads what a workflow demands of its environment. Pure —
-// no I/O, no operator input. Sorts every declared channel into the hardware /
-// MQTT pools the deploy artifacts need and walks nodes (main + function bodies)
-// for the catalog-model / retriever / web-search signals.
-export function deriveRequirements(workflow: Workflow): DeployRequirements {
-  const hardwareChannels: HardwareChannel[] = [];
-  const mqttChannels: MqttChannel[] = [];
-
-  for (const channel of Object.values(workflow.channels)) {
-    switch (channel.type) {
-      case "GPIOIN":
-      case "GPIOOUT":
-        hardwareChannels.push({ id: channel.id, label: channel.label, family: "gpio", addressable: true });
-        break;
-      case "ADC":
-        hardwareChannels.push({ id: channel.id, label: channel.label, family: "adc", addressable: true });
-        break;
-      case "DAC":
-        hardwareChannels.push({ id: channel.id, label: channel.label, family: "dac", addressable: true });
-        break;
-      case "PWM":
-        hardwareChannels.push({ id: channel.id, label: channel.label, family: "pwm", addressable: true });
-        break;
-      case "UART":
-        hardwareChannels.push({ id: channel.id, label: channel.label, family: "serial", addressable: false });
-        break;
-      case "MQTT":
-        mqttChannels.push({ id: channel.id, label: channel.label });
-        break;
-      case "LOG":
-        // Resolves to the ambient engine logger — no platform resource to bind, so
-        // it demands nothing of the deploy environment.
-        break;
-      default:
-        return assertNeverChannel(channel.type);
-    }
-  }
-
-  let hasRetriever = false;
-  let hasWebSearch = false;
-  for (const canvas of Object.values(workflow.canvases)) {
-    for (const node of canvas.nodes) {
-      if (node.type === "Retriever") hasRetriever = true;
-      else if (node.type === "WebSearchTool") hasWebSearch = true;
-    }
-  }
-
-  const customModels: CustomModel[] = Object.values(workflow.models).map((m) => ({ id: m.id, label: m.label }));
-
-  return {
-    hasProviderModel: getReferencedCatalogModelIds(workflow).length > 0,
-    hasRetriever,
-    hasWebSearch,
-    hardwareChannels,
-    mqttChannels,
-    customModels,
-  };
-}
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 ForestHub.
+
+// Stage 0 of the deployment pipeline (docs/deployment-pipeline.md): extract the
+// binding SURFACE a workflow demands — which resource ids must be bound, and of
+// what kind — from the workflow content alone. This is the language-neutral
+// requirement analysis every deploy path (OSS CLI, backend) shares.
+
+import type { Workflow } from "../workflow";
+
+// The binding kind a workflow resource must be bound with — the discriminator of
+// the deployment api's ResourceBindingRequest.
+//
+// CROSS-LANGUAGE SEAM: these string values MUST match the backend's
+// deploy.BindingRequirement constants (fh-backend deploy.WorkflowBindingRequirements),
+// which are themselves the ResourceBindingRequest discriminators
+// ("hardware"/"mqtt"/"camera"/"declaredModel"/"mlInference"/"catalogModel"/"rag").
+// A value that drifts here silently disagrees with the backend about what a
+// workflow needs bound.
+//
+// One deliberate asymmetry with the backend today: "rag" is absent. OSS is behind
+// on retrieval — it does not yet extract a VectorDatabase memory resource as a
+// requirement (the backend emits "rag"). A standalone engine has no retriever, so
+// such a workflow is refused at deploy; add "rag" here when the OSS engine gains a
+// retrieval backing.
+export type BindingKind = "hardware" | "mqtt" | "camera" | "declaredModel" | "mlInference" | "catalogModel";
+
+// Drift sentinel: a new ChannelType breaks compilation here until it is
+// classified in workflowBindingRequirements' channel switch.
+function assertNeverChannel(t: never): never {
+  throw new Error(`unhandled channel type: ${String(t)}`);
+}
+
+// Drift sentinel: a new ModelType breaks compilation here until it is classified
+// in workflowBindingRequirements' model switch.
+function assertNeverModel(t: never): never {
+  throw new Error(`unhandled model type: ${String(t)}`);
+}
+
+// workflowBindingRequirements returns the resources a deploy must bind, keyed by
+// workflow logical id — the binding surface. The TS twin of the backend's
+// deploy.WorkflowBindingRequirements: both must derive the SAME id->kind map from
+// the same workflow, or an OSS deploy and a backend deploy disagree about what
+// needs binding.
+//
+// The surface is neither the declared set nor a subset of it:
+//  - LOG channels and MemoryFile bind nothing — declared, but out.
+//  - referenced catalog models bind a provider yet are node references, not
+//    declarations — undeclared, but in.
+//
+// Pure — reads workflow content alone: no operator input, no model catalog.
+export function workflowBindingRequirements(workflow: Workflow): Record<string, BindingKind> {
+  const reqs: Record<string, BindingKind> = {};
+
+  for (const channel of Object.values(workflow.channels)) {
+    switch (channel.type) {
+      case "GPIOIN":
+      case "GPIOOUT":
+      case "ADC":
+      case "DAC":
+      case "PWM":
+      case "UART":
+        reqs[channel.id] = "hardware";
+        break;
+      case "MQTT":
+        reqs[channel.id] = "mqtt";
+        break;
+      case "CAMERA":
+        reqs[channel.id] = "camera";
+        break;
+      case "LOG":
+        // Resolves to the ambient engine logger — no platform resource to bind.
+        break;
+      default:
+        return assertNeverChannel(channel.type);
+    }
+  }
+
+  // Every declared model needs a source binding, but of a different kind by family:
+  // an LLMModel binds a model source ("declaredModel"); an MLModel is served by an
+  // ml-inference component ("mlInference"). Mirrors the backend's workflowModelIDs
+  // split — both sides must agree on which kind each declared model gets.
+  for (const model of Object.values(workflow.models)) {
+    switch (model.type) {
+      case "LLMModel":
+        reqs[model.id] = "declaredModel";
+        break;
+      case "MLModel":
+        reqs[model.id] = "mlInference";
+        break;
+      default:
+        return assertNeverModel(model.type);
+    }
+  }
+
+  // Catalog models: referenced by an Agent node but not declared. Keyed by model
+  // id (canonical, matching the backend surface) — not collapsed to providers
+  // here. getReferencedCatalogModelIds already excludes declared ids, so this
+  // never overwrites a declaredModel entry.
+  for (const id of getReferencedCatalogModelIds(workflow)) reqs[id] = "catalogModel";
+
+  return reqs;
+}
+
+/**
+ * Model ids that Agent nodes reference but the workflow does not declare in
+ * `models` - the catalog models a deploy must bind a provider for.
+ */
+export function getReferencedCatalogModelIds(workflow: Workflow): string[] {
+  const declared = new Set(Object.keys(workflow.models));
+  const catalogIds = new Set<string>();
+
+  for (const canvas of Object.values(workflow.canvases)) {
+    for (const node of canvas.nodes) {
+      if (node.type !== "Agent") continue;
+      const id = node.arguments.model;
+      if (id !== "" && !declared.has(id)) catalogIds.add(id);
+    }
+  }
+
+  return [...catalogIds];
+}