@foresthubai/workflow-core 0.4.3 → 0.4.4

package/src/api/index.ts

@@ -1,11 +1,26 @@
-export type { components } from "./workflow";
-
-import type { components } from "./workflow";
-export type Schemas = components["schemas"];
-
-// Api-layer type aliases used across the domain. They live here (not in any
-// single domain module) so modules don't cross-import them; consumers pull
-// them from the package root (`@foresthubai/workflow-core`).
-export type DataType = Schemas["DataType"];
-export type Reference = Schemas["Reference"];
-export type Expression = Schemas["Expression"];
+export type { components } from "./workflow";
+
+import type { components } from "./workflow";
+export type Schemas = components["schemas"];
+
+// Deployment-spec api layer, generated from contract/deployment.yaml. Its
+// DeployComponent.config is an opaque object — the spec transports rendered config
+// as bytes and no longer $refs engine.yaml — so the engine's own config types live
+// in EngineSchemas below, not here. Kept under a distinct name so it never collides
+// with the workflow Schemas above.
+import type { components as deploymentComponents } from "./deployment";
+export type DeploymentSchemas = deploymentComponents["schemas"];
+
+// Engine wire/config api layer, generated from contract/engine.yaml. The deploy
+// resolver (src/deploy/) PRODUCES an EngineConfig (workflow + mapping + external
+// resources + device manifest) and freezes it into a DeployComponent's opaque
+// config, so it types that construction against these.
+import type { components as engineComponents } from "./engine";
+export type EngineSchemas = engineComponents["schemas"];
+
+// Api-layer type aliases used across the domain. They live here (not in any
+// single domain module) so modules don't cross-import them; consumers pull
+// them from the package root (`@foresthubai/workflow-core`).
+export type DataType = Schemas["DataType"];
+export type Reference = Schemas["Reference"];
+export type Expression = Schemas["Expression"];

package/src/api/workflow.ts

@@ -519,7 +519,7 @@ export interface components {
                 output: components["schemas"]["OutputBinding"];
             };
         };
-        Channel: components["schemas"]["GPIOINChannel"] | components["schemas"]["GPIOOUTChannel"] | components["schemas"]["ADCChannel"] | components["schemas"]["PWMChannel"] | components["schemas"]["DACChannel"] | components["schemas"]["UARTChannel"] | components["schemas"]["MQTTChannel"];
+        Channel: components["schemas"]["GPIOINChannel"] | components["schemas"]["GPIOOUTChannel"] | components["schemas"]["ADCChannel"] | components["schemas"]["PWMChannel"] | components["schemas"]["DACChannel"] | components["schemas"]["UARTChannel"] | components["schemas"]["MQTTChannel"] | components["schemas"]["LOGChannel"];
         GPIOINChannel: {
             /**
              * @description discriminator enum property added by openapi-typescript
@@ -594,6 +594,22 @@ export interface components {
             /** @description Topic this channel publishes to / subscribes on. The engine wraps it with the bound broker's prefix at runtime. */
             topic: string;
         };
+        LOGChannel: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "LOG";
+            id: string;
+            label: string;
+            /**
+             * @description Severity the engine records messages written to this channel at.
+             * @enum {string}
+             */
+            level: "debug" | "info" | "warn" | "error";
+            /** @description Optional category stamped on each line so the backend can group workflow-emitted logs apart from engine diagnostics. */
+            tag?: string;
+        };
         /** @enum {string} */
         ModelCapability: "chat" | "embedding" | "function_call" | "vision" | "fine_tuning" | "reasoning" | "classification" | "code";
     };

package/src/channel/Channel.ts

@@ -1,11 +1,11 @@
-export type ChannelType = "GPIOIN" | "GPIOOUT" | "ADC" | "PWM" | "DAC" | "UART" | "MQTT";
-
-export const ALL_CHANNEL_TYPES: ChannelType[] = ["GPIOIN", "GPIOOUT", "ADC", "PWM", "DAC", "UART", "MQTT"];
-
-/** Interface for a channel instance in the workflow */
-export interface Channel {
-  id: string;
-  label: string;
-  type: ChannelType;
-  arguments: Record<string, unknown>;
-}
+export type ChannelType = "GPIOIN" | "GPIOOUT" | "ADC" | "PWM" | "DAC" | "UART" | "MQTT" | "LOG";
+
+export const ALL_CHANNEL_TYPES: ChannelType[] = ["GPIOIN", "GPIOOUT", "ADC", "PWM", "DAC", "UART", "MQTT", "LOG"];
+
+/** Interface for a channel instance in the workflow */
+export interface Channel {
+  id: string;
+  label: string;
+  type: ChannelType;
+  arguments: Record<string, unknown>;
+}

package/src/channel/ChannelDefinition.ts

@@ -1,76 +1,98 @@
-import type { Parameter } from "../parameter";
-import { ALL_CHANNEL_TYPES } from "./Channel";
-
-/**
- * Single union definition for all Channel variants — deliberately NOT the
- * per-type registry pattern used by Node/Memory/Model (`*Definition` +
- * `*Registry`, one definition object per type).
- *
- * The reason is in-place `type` switching that preserves shared parameter state.
- * Because `type` is a parameter and all variants share one `arguments` bag,
- * changing a channel's type keeps the same instance (id, label) and retains any
- * entered values that are still valid for the new type: the parameter +
- * `activationRules` machinery just re-gates which fields show, and `serialize`
- * (via `pruneArguments`) drops the now-inactive ones. A per-type registry
- * would make each variant its own definition, so switching type would mean
- * delete-and-recreate — losing id/label and every shared value the user entered.
- * (It also lets channels add from one "Add Channel" button with type as a field,
- * rather than an add-button per type. Node/Memory/Model instead treat `type` as
- * an immutable registry key chosen at creation.)
- *
- * The same could be achieved with a UI-layer "type selector" over a
- * ChannelRegistry; this union trades cross-family consistency for that
- * shared-state-preserving switch.
- */
-export interface ChannelDefinition {
-  parameters: Parameter[];
-}
-
-export const CHANNEL_DEFINITION: ChannelDefinition = {
-  parameters: [
-    {
-      id: "type",
-      label: "Type",
-      description: "Channel type",
-      type: "selection",
-      default: "GPIOIN",
-      options: ALL_CHANNEL_TYPES.map((t) => ({ value: t, label: t })),
-    },
-    {
-      id: "bias",
-      label: "Bias",
-      description: "Pin bias configuration",
-      type: "selection",
-      default: "none",
-      options: [
-        { value: "none", label: "None" },
-        { value: "pullup", label: "Pull-up" },
-        { value: "pulldown", label: "Pull-down" },
-      ],
-      activationRules: [{ type: "parameterIn", parameterId: "type", values: ["GPIOIN"] }],
-    },
-    {
-      id: "debounceMs",
-      label: "Debounce (ms)",
-      description: "Debounce window in milliseconds",
-      type: "int",
-      default: 50,
-      activationRules: [{ type: "parameterIn", parameterId: "type", values: ["GPIOIN"] }],
-    },
-    {
-      id: "frequency",
-      label: "Frequency (Hz)",
-      description: "PWM frequency in Hz",
-      type: "int",
-      default: 1000,
-      activationRules: [{ type: "parameterIn", parameterId: "type", values: ["PWM"] }],
-    },
-    {
-      id: "topic",
-      label: "Topic",
-      description: "MQTT topic this channel publishes to / subscribes on (e.g. sensors/temperature)",
-      type: "string",
-      activationRules: [{ type: "parameterIn", parameterId: "type", values: ["MQTT"] }],
-    },
-  ],
-};
+import type { Parameter } from "../parameter";
+import { ALL_CHANNEL_TYPES } from "./Channel";
+
+/**
+ * Single union definition for all Channel variants — deliberately NOT the
+ * per-type registry pattern used by Node/Memory/Model (`*Definition` +
+ * `*Registry`, one definition object per type).
+ *
+ * The reason is in-place `type` switching that preserves shared parameter state.
+ * Because `type` is a parameter and all variants share one `arguments` bag,
+ * changing a channel's type keeps the same instance (id, label) and retains any
+ * entered values that are still valid for the new type: the parameter +
+ * `activationRules` machinery just re-gates which fields show, and `serialize`
+ * (via `pruneArguments`) drops the now-inactive ones. A per-type registry
+ * would make each variant its own definition, so switching type would mean
+ * delete-and-recreate — losing id/label and every shared value the user entered.
+ * (It also lets channels add from one "Add Channel" button with type as a field,
+ * rather than an add-button per type. Node/Memory/Model instead treat `type` as
+ * an immutable registry key chosen at creation.)
+ *
+ * The same could be achieved with a UI-layer "type selector" over a
+ * ChannelRegistry; this union trades cross-family consistency for that
+ * shared-state-preserving switch.
+ */
+export interface ChannelDefinition {
+  parameters: Parameter[];
+}
+
+export const CHANNEL_DEFINITION: ChannelDefinition = {
+  parameters: [
+    {
+      id: "type",
+      label: "Type",
+      description: "Channel type",
+      type: "selection",
+      default: "GPIOIN",
+      options: ALL_CHANNEL_TYPES.map((t) => ({ value: t, label: t })),
+    },
+    {
+      id: "bias",
+      label: "Bias",
+      description: "Pin bias configuration",
+      type: "selection",
+      default: "none",
+      options: [
+        { value: "none", label: "None" },
+        { value: "pullup", label: "Pull-up" },
+        { value: "pulldown", label: "Pull-down" },
+      ],
+      activationRules: [{ type: "parameterIn", parameterId: "type", values: ["GPIOIN"] }],
+    },
+    {
+      id: "debounceMs",
+      label: "Debounce (ms)",
+      description: "Debounce window in milliseconds",
+      type: "int",
+      default: 50,
+      activationRules: [{ type: "parameterIn", parameterId: "type", values: ["GPIOIN"] }],
+    },
+    {
+      id: "frequency",
+      label: "Frequency (Hz)",
+      description: "PWM frequency in Hz",
+      type: "int",
+      default: 1000,
+      activationRules: [{ type: "parameterIn", parameterId: "type", values: ["PWM"] }],
+    },
+    {
+      id: "topic",
+      label: "Topic",
+      description: "MQTT topic this channel publishes to / subscribes on (e.g. sensors/temperature)",
+      type: "string",
+      activationRules: [{ type: "parameterIn", parameterId: "type", values: ["MQTT"] }],
+    },
+    {
+      id: "level",
+      label: "Level",
+      description: "Severity the engine records messages written to this channel at",
+      type: "selection",
+      default: "info",
+      options: [
+        { value: "debug", label: "Debug" },
+        { value: "info", label: "Info" },
+        { value: "warn", label: "Warn" },
+        { value: "error", label: "Error" },
+      ],
+      activationRules: [{ type: "parameterIn", parameterId: "type", values: ["LOG"] }],
+    },
+    {
+      id: "tag",
+      label: "Tag",
+      description: "Optional category stamped on each line so the backend can group workflow-emitted logs",
+      type: "string",
+      optional: true,
+      activationRules: [{ type: "parameterIn", parameterId: "type", values: ["LOG"] }],
+    },
+  ],
+};

package/src/channel/index.ts

@@ -1,6 +1,6 @@
-export type { ChannelType, Channel } from "./Channel";
-export { ALL_CHANNEL_TYPES } from "./Channel";
-export type { ChannelDefinition } from "./ChannelDefinition";
-export { CHANNEL_DEFINITION } from "./ChannelDefinition";
-export { serialize, deserialize } from "./serialization";
-export type { ApiChannel } from "./serialization";
+export type { ChannelType, Channel } from "./Channel";
+export { ALL_CHANNEL_TYPES } from "./Channel";
+export type { ChannelDefinition } from "./ChannelDefinition";
+export { CHANNEL_DEFINITION } from "./ChannelDefinition";
+export { serialize, deserialize } from "./serialization";
+export type { ApiChannel } from "./serialization";

package/src/channel/serialization.ts

@@ -1,68 +1,74 @@
-import type { Schemas } from "../api";
-import { pruneArguments } from "../parameter";
-import { CHANNEL_DEFINITION } from "./ChannelDefinition";
-import type { Channel } from "./Channel";
-
-export type ApiChannel = Schemas["Channel"];
-
-/**
- * Serialize a domain Channel to the API discriminated-union shape.
- *
- * The domain store retains inactive parameters (non-destructive type switching),
- * so this is the boundary that drops them. The `type` discriminator must be in
- * the args record so `parameterIn` rules can evaluate — otherwise every gated
- * field (bias/debounceMs/frequency) is stripped as "inactive". Physical
- * addressing (GPIO line, ADC/PWM/DAC channel) is not here — it's a deploy
- * binding, not workflow state.
- */
-export function serialize(ch: Channel): ApiChannel {
-  const { id, label, type } = ch;
-  const args: Record<string, unknown> = { ...ch.arguments, type };
-  pruneArguments(args, CHANNEL_DEFINITION.parameters);
-  switch (type) {
-    case "GPIOIN":
-      return {
-        type,
-        id,
-        label,
-        bias: args.bias as Schemas["GPIOINChannel"]["bias"],
-        debounceMs: args.debounceMs as number,
-      };
-    case "GPIOOUT":
-      return { type, id, label };
-    case "ADC":
-      return { type, id, label };
-    case "PWM":
-      return { type, id, label, frequency: args.frequency as number };
-    case "DAC":
-      return { type, id, label };
-    case "UART":
-      return { type, id, label };
-    case "MQTT":
-      return { type, id, label, topic: args.topic as string };
-  }
-}
-
-/** Convert an API Channel into a domain Channel. */
-export function deserialize(api: ApiChannel): Channel {
-  const { id, label, type } = api;
-  const args: Record<string, unknown> = {};
-  switch (type) {
-    case "GPIOIN":
-      args.bias = api.bias;
-      args.debounceMs = api.debounceMs;
-      break;
-    case "PWM":
-      args.frequency = api.frequency;
-      break;
-    case "MQTT":
-      args.topic = api.topic;
-      break;
-    case "GPIOOUT":
-    case "ADC":
-    case "DAC":
-    case "UART":
-      break;
-  }
-  return { id, label, type, arguments: args };
-}
+import type { Schemas } from "../api";
+import { pruneArguments } from "../parameter";
+import { CHANNEL_DEFINITION } from "./ChannelDefinition";
+import type { Channel } from "./Channel";
+
+export type ApiChannel = Schemas["Channel"];
+
+/**
+ * Serialize a domain Channel to the API discriminated-union shape.
+ *
+ * The domain store retains inactive parameters (non-destructive type switching),
+ * so this is the boundary that drops them. The `type` discriminator must be in
+ * the args record so `parameterIn` rules can evaluate — otherwise every gated
+ * field (bias/debounceMs/frequency) is stripped as "inactive". Physical
+ * addressing (GPIO line, ADC/PWM/DAC channel) is not here — it's a deploy
+ * binding, not workflow state.
+ */
+export function serialize(ch: Channel): ApiChannel {
+  const { id, label, type } = ch;
+  const args: Record<string, unknown> = { ...ch.arguments, type };
+  pruneArguments(args, CHANNEL_DEFINITION.parameters);
+  switch (type) {
+    case "GPIOIN":
+      return {
+        type,
+        id,
+        label,
+        bias: args.bias as Schemas["GPIOINChannel"]["bias"],
+        debounceMs: args.debounceMs as number,
+      };
+    case "GPIOOUT":
+      return { type, id, label };
+    case "ADC":
+      return { type, id, label };
+    case "PWM":
+      return { type, id, label, frequency: args.frequency as number };
+    case "DAC":
+      return { type, id, label };
+    case "UART":
+      return { type, id, label };
+    case "MQTT":
+      return { type, id, label, topic: args.topic as string };
+    case "LOG":
+      return { type, id, label, level: args.level as Schemas["LOGChannel"]["level"], tag: args.tag as string | undefined };
+  }
+}
+
+/** Convert an API Channel into a domain Channel. */
+export function deserialize(api: ApiChannel): Channel {
+  const { id, label, type } = api;
+  const args: Record<string, unknown> = {};
+  switch (type) {
+    case "GPIOIN":
+      args.bias = api.bias;
+      args.debounceMs = api.debounceMs;
+      break;
+    case "PWM":
+      args.frequency = api.frequency;
+      break;
+    case "MQTT":
+      args.topic = api.topic;
+      break;
+    case "LOG":
+      args.level = api.level;
+      args.tag = api.tag;
+      break;
+    case "GPIOOUT":
+    case "ADC":
+    case "DAC":
+    case "UART":
+      break;
+  }
+  return { id, label, type, arguments: args };
+}

package/src/deploy/index.ts

@@ -1 +1,14 @@
-export { getReferencedCatalogModelIds } from "./requirements";
+export { getReferencedCatalogModelIds, deriveRequirements } from "./requirements";
+export type { DeployRequirements, HardwareChannel, MqttChannel, CustomModel, HardwareFamily } from "./requirements";
+export type { DeploymentInputs, HardwareBinding, MqttBinding, ModelBinding } from "./inputs";
+export {
+  buildDeploymentSpec,
+  assertDeployable,
+  hardwareConflicts,
+  familyMismatches,
+  hardwareAddressKey,
+  hardwareAddressLabel,
+  ggufNameError,
+  sidecarServiceName,
+} from "./spec";
+export type { DeploymentSpecMeta, DeploymentSpecResult, ResourceSecret, ResourceSecrets } from "./spec";

package/src/deploy/inputs.ts

@@ -0,0 +1,41 @@
+// Operator-supplied bindings: the per-deploy values that bind a workflow's
+// logical resource ids to a concrete environment. Shared by every spec
+// producer (the CLI prompts/--values, the FE deploy forms) — how the values are
+// collected differs per renderer, but the shape they resolve to is one thing.
+//
+// Secrets policy: provider API keys and the web-search key are NOT here — they
+// are device/operator-scoped engine env, injected at render time, never frozen
+// into a versioned spec. Only deployment-scoped resource creds (broker, custom
+// endpoint) live in these bindings, because EngineConfig.externalResources needs
+// them resolved inline.
+
+// One hardware channel's physical address. `index` = sub-address (addressable
+// families: GPIO line, ADC/DAC/PWM channel); `baud` = serial only.
+export interface HardwareBinding {
+  chipOrDevice: string;
+  index?: number;
+  baud?: number;
+}
+
+// One MQTT channel's broker connection.
+export interface MqttBinding {
+  brokerUrl: string;
+  username?: string;
+  password?: string;
+}
+
+// One custom model's runtime location. `device` = a llama-server sidecar on this
+// controller (the engine reaches it over the container network by service name);
+// `network` = an inference endpoint the operator runs elsewhere. The endpoint
+// serves the model under its workflow id — no upstream-name aliasing yet.
+export type ModelBinding =
+  | { location: "device"; modelFile: string; port?: number; ctxSize?: number }
+  | { location: "network"; url: string; apiKey?: string };
+
+// The complete set of bindings a deploy supplies, keyed by workflow logical id
+// (channel id / model id). Empty for any resource kind the workflow doesn't use.
+export interface DeploymentInputs {
+  hardware: Record<string, HardwareBinding>;
+  mqtt: Record<string, MqttBinding>;
+  models: Record<string, ModelBinding>;
+}

package/src/deploy/requirements.test.ts

@@ -1,61 +1,61 @@
-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([]);
-  });
-});
+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([]);
+  });
+});