@foresthubai/workflow-core 0.4.3 → 0.4.5

package/src/api/index.ts

@@ -1,11 +1,29 @@
-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"];
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 ForestHub.
+
+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

@@ -17,7 +17,7 @@ export interface components {
             x: number;
             y: number;
         };
-        /** @description Workflow represents the deployment format of a project, passed to agents. */
+        /** @description The deployment format of a workflow project. */
         Workflow: {
             /**
              * Format: int32
@@ -115,7 +115,7 @@ export interface components {
             type: "MemoryFile";
             /** @description Stable identifier that survives renames; referenced from MemoryRef. */
             id: string;
-            /** @description Display name. Unique per agent (LLM tool enums use it). */
+            /** @description Display name. Unique per agent. */
             label: string;
             description: string;
             content: string;
@@ -157,7 +157,7 @@ export interface components {
             id: string;
             /** @description Display name. */
             label: string;
-            /** @description Capabilities this model supports (used to filter model pickers). */
+            /** @description Capabilities this model supports. */
             capabilities: components["schemas"]["ModelCapability"][];
         };
         Node: components["schemas"]["ReadPinNode"] | components["schemas"]["WritePinNode"] | components["schemas"]["AgentNode"] | components["schemas"]["IfNode"] | components["schemas"]["SerialReadNode"] | components["schemas"]["SerialWriteNode"] | components["schemas"]["RetrieverNode"] | components["schemas"]["WebFetchNode"] | components["schemas"]["FunctionCallNode"] | components["schemas"]["OnFunctionCallNode"] | components["schemas"]["DelayNode"] | components["schemas"]["TickerNode"] | components["schemas"]["AlarmNode"] | components["schemas"]["WebSearchToolNode"] | components["schemas"]["OnStartupNode"] | components["schemas"]["OnPinEdgeNode"] | components["schemas"]["OnSerialReceiveNode"] | components["schemas"]["OnThresholdNode"] | components["schemas"]["SetVariableNode"] | components["schemas"]["MqttPublishNode"] | components["schemas"]["OnMqttMessageNode"];
@@ -242,7 +242,7 @@ export interface components {
                 outputBindings?: {
                     [key: string]: components["schemas"]["OutputBinding"];
                 };
-                /** @description Description exposed to the LLM when this function is wired as a tool. Ignored in exec mode. */
+                /** @description Description used when this function is exposed as a tool; ignored in exec mode. */
                 toolDescription?: string;
             };
         };
@@ -342,7 +342,7 @@ export interface components {
                 /** @description Search query expression */
                 query: components["schemas"]["Expression"];
                 output: components["schemas"]["OutputBinding"];
-                /** @description Description exposed to the LLM when this node is wired as a tool. Ignored in exec mode. */
+                /** @description Description used when this node is exposed as a tool; ignored in exec mode. */
                 toolDescription?: string;
             };
         };
@@ -377,7 +377,7 @@ export interface components {
                 pinReference?: string;
                 signalType: components["schemas"]["SignalType"];
                 output: components["schemas"]["OutputBinding"];
-                /** @description Description exposed to the LLM when this node is wired as a tool. Ignored in exec mode. */
+                /** @description Description used when this node is exposed as a tool; ignored in exec mode. */
                 toolDescription?: string;
             };
         };
@@ -418,7 +418,7 @@ export interface components {
                 outputDeclarations: components["schemas"]["OutputDeclaration"][];
                 /** @description Memory files this agent can access, each with an access mode. */
                 memoryRefs: components["schemas"]["MemoryRef"][];
-                /** @description Description exposed to the LLM when this node is wired as a tool. Ignored in exec mode. */
+                /** @description Description used when this node is exposed as a tool; ignored in exec mode. */
                 toolDescription?: string;
             };
         };
@@ -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
@@ -591,9 +591,25 @@ export interface components {
             type: "MQTT";
             id: string;
             label: string;
-            /** @description Topic this channel publishes to / subscribes on. The engine wraps it with the bound broker's prefix at runtime. */
+            /** @description Topic this channel publishes to / subscribes on. */
             topic: string;
         };
+        LOGChannel: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            type: "LOG";
+            id: string;
+            label: string;
+            /**
+             * @description Severity for messages written to this channel.
+             * @enum {string}
+             */
+            level: "debug" | "info" | "warn" | "error";
+            /** @description Optional category label stamped on each line written to this channel. */
+            tag?: string;
+        };
         /** @enum {string} */
         ModelCapability: "chat" | "embedding" | "function_call" | "vision" | "fine_tuning" | "reasoning" | "classification" | "code";
     };

package/src/channel/Channel.ts

@@ -1,11 +1,14 @@
-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>;
-}
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 ForestHub.
+
+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,101 @@
-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"] }],
-    },
-  ],
-};
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 ForestHub.
+
+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,9 @@
-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";
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 ForestHub.
+
+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,77 @@
-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 };
-}
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 ForestHub.
+
+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,17 @@
-export { getReferencedCatalogModelIds } from "./requirements";
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 ForestHub.
+
+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, EngineSecrets } from "./spec";

package/src/deploy/inputs.ts

@@ -0,0 +1,44 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 ForestHub.
+
+// 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>;
+}