@foresthubai/workflow-core 0.4.4 → 0.4.5

package/src/api/engine.ts

@@ -7,31 +7,35 @@ export type paths = Record<string, never>;
 export type webhooks = Record<string, never>;
 export interface components {
     schemas: {
-        /** @description The engine's complete boot input, loaded once at startup from a single file — the engine is immutable, with no runtime hot-swap. Bundles the binding-free workflow, the deploy mapping that binds its logical resource ids to this environment, the resolved external-resource configs those bindings point at, and the device manifest (the hardware catalog the mapping resolves against). The deployment-scoped parts and the device-scoped manifest have different owners in the control plane; the renderer merges them into this one blob for the engine. A workflow is required — an engine exists only to run one. The engine still validates it at boot and fails fast if it is missing, since JSON unmarshalling does not enforce required fields. */
+        /** @description The engine's complete boot input, loaded once at startup. */
         EngineConfig: {
             workflow: components["schemas"]["Workflow"];
-            mapping?: components["schemas"]["DeploymentMapping"];
+            mapping?: components["schemas"]["ResourceMapping"];
             externalResources?: components["schemas"]["ExternalResources"];
             manifest?: components["schemas"]["DeviceManifest"];
         };
-        /** @description Binds a binding-free workflow's logical resource ids to concrete platform resources for one deploy, keyed by workflow resource id. The pool a binding's ref resolves against is determined by the workflow resource's type: hardware channels resolve against the boot DeviceManifest; MQTT channels and custom models against the deploy ExternalResources; RAG memory against the boot-configured backend (the ref is the collection id). */
-        DeploymentMapping: {
+        /** @description The engine's secret store: a flat map of secret id -> opaque secret value. */
+        EngineSecrets: {
+            [key: string]: string;
+        };
+        /** @description Binds a binding-free workflow's logical resource ids to concrete platform resources, keyed by workflow resource id. */
+        ResourceMapping: {
             [key: string]: components["schemas"]["ResourceBinding"];
         };
-        /** @description How one workflow resource binds to the environment. `ref` is the shared platform resource it points at (driver instance id, external resource id, or RAG collection id) — a sharing identity, so many workflow resources may share one ref and the engine builds it once. `index` is the optional per-channel physical sub-address within that resource: GPIO line, or ADC/PWM/DAC channel number. Absent for UART, MQTT, memory and models. */
+        /** @description How one workflow resource binds to the environment: a shared platform resource `ref` with an optional per-channel physical sub-address `index`. */
         ResourceBinding: {
             /** @description Shared platform resource id this binds to. */
             ref: string;
             /** @description Per-channel physical sub-address within the driver (GPIO line / ADC-PWM-DAC channel). Omitted when the resource has no sub-address. */
             index?: number;
         };
-        /** @description Deploy-time configs for a workflow's non-device external resources (MQTT transports, custom-model providers, ...), keyed by the platform resource id the DeploymentMapping points at. Replaces the former NetworkManifest. Device-owned configs (drivers) stay in the boot DeviceManifest; this carries only deploy-delivered, swappable configs. */
+        /** @description Deploy-time configs for a workflow's non-device external resources (MQTT transports, custom-model providers, ...), keyed by platform resource id. */
         ExternalResources: {
             [key: string]: components["schemas"]["ExternalResourceConfig"];
         };
         /** @description Tagged union of deploy-time external-resource configs, discriminated by runtime kind (not by ownership — locality like on-device vs cloud lives inside an arm). New kinds extend this oneOf. */
         ExternalResourceConfig: components["schemas"]["MQTTConnection"] | components["schemas"]["LLMProviderConfig"];
-        /** @description Resolved connection to a self-hosted/custom LLM endpoint the llmproxy doesn't ship. The engine registers it as an llmproxy provider for the workflow's custom model; the model's capabilities come from its declared workflow entry, so they are not repeated here. The bearer credential is NOT here — it is a secret, delivered out-of-band and injected at runtime (keyed by this resource's id), never stored in the deployment spec. */
+        /** @description Resolved connection to a self-hosted/custom LLM endpoint the llmproxy doesn't ship. */
         LLMProviderConfig: {
             /**
              * @description discriminator enum property added by openapi-typescript
@@ -43,7 +47,7 @@ export interface components {
             /** @description Upstream model name the endpoint serves; defaults to the workflow model id when empty. */
             model?: string;
         };
-        /** @description Resolved connection metadata for an MQTT broker. The password is NOT here — it is a secret, delivered out-of-band and injected at runtime (keyed by this resource's id), never stored in the deployment spec. username is connection metadata (an identifier), not a credential, so it stays. */
+        /** @description Resolved connection metadata for an MQTT broker. */
         MQTTConnection: {
             /**
              * @description discriminator enum property added by openapi-typescript
@@ -53,20 +57,20 @@ export interface components {
             brokerUrl: string;
             clientId?: string;
             username?: string;
-            /** @description Topic prefix the engine prepends to workflow-level publish topics ({networkId}/{agentId}/). */
+            /** @description Topic prefix for workflow-level publish topics ({networkId}/{agentId}/). */
             publishPrefix?: string;
-            /** @description Topic prefix the engine prepends to workflow-level subscribe filters ({networkId}/+/). */
+            /** @description Topic prefix for workflow-level subscribe filters ({networkId}/+/). */
             subscribePrefix?: string;
             will?: components["schemas"]["MQTTWill"];
         };
         MQTTWill: {
             topic: string;
             payload: string;
-            /** @description MQTT QoS (0,1,2). Cast to byte at the paho call site. */
+            /** @description MQTT QoS (0, 1, or 2). */
             qos: number;
             retain: boolean;
         };
-        /** @description Hardware resources available on the device, keyed by driver instance ID. Drives runtime driver instantiation on the engine. */
+        /** @description Hardware resources available on the device, keyed by driver instance ID. */
         DeviceManifest: {
             gpios?: {
                 [key: string]: components["schemas"]["GPIOConfig"];
@@ -106,10 +110,6 @@ export interface components {
             /** @description sysfs path to the pwmchip directory, e.g. "/sys/class/pwm/pwmchip0" */
             chip: string;
         };
-        /** @description Body of PUT /agents/memory/{name}. */
-        MemoryFileWrite: {
-            content: string;
-        };
         RagQueryRequest: {
             /** @description Collection to query */
             collectionId: string;
@@ -162,7 +162,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;
             };
         };
@@ -232,7 +232,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;
             };
         };
@@ -297,7 +297,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;
             };
         };
@@ -336,7 +336,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;
             };
         };
@@ -650,7 +650,7 @@ 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: {
@@ -662,11 +662,11 @@ export interface components {
             id: string;
             label: string;
             /**
-             * @description Severity the engine records messages written to this channel at.
+             * @description Severity for messages written to this channel.
              * @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. */
+            /** @description Optional category label stamped on each line written to this channel. */
             tag?: string;
         };
         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"];
@@ -679,7 +679,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;
@@ -713,11 +713,11 @@ 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"][];
         };
         Model: components["schemas"]["LLMModel"];
-        /** @description Workflow represents the deployment format of a project, passed to agents. */
+        /** @description The deployment format of a workflow project. */
         Workflow: {
             /**
              * Format: int32

package/src/api/index.ts

@@ -1,3 +1,6 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 ForestHub.
+
 export type { components } from "./workflow";
 
 import type { components } from "./workflow";

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;
             };
         };
@@ -591,7 +591,7 @@ 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: {
@@ -603,11 +603,11 @@ export interface components {
             id: string;
             label: string;
             /**
-             * @description Severity the engine records messages written to this channel at.
+             * @description Severity for messages written to this channel.
              * @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. */
+            /** @description Optional category label stamped on each line written to this channel. */
             tag?: string;
         };
         /** @enum {string} */

package/src/channel/Channel.ts

@@ -1,3 +1,6 @@
+// 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"];

package/src/channel/ChannelDefinition.ts

@@ -1,3 +1,6 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 ForestHub.
+
 import type { Parameter } from "../parameter";
 import { ALL_CHANNEL_TYPES } from "./Channel";
 

package/src/channel/index.ts

@@ -1,3 +1,6 @@
+// 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";

package/src/channel/serialization.ts

@@ -1,3 +1,6 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 ForestHub.
+
 import type { Schemas } from "../api";
 import { pruneArguments } from "../parameter";
 import { CHANNEL_DEFINITION } from "./ChannelDefinition";

package/src/deploy/index.ts

@@ -1,3 +1,6 @@
+// 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";
@@ -11,4 +14,4 @@ export {
   ggufNameError,
   sidecarServiceName,
 } from "./spec";
-export type { DeploymentSpecMeta, DeploymentSpecResult, ResourceSecret, ResourceSecrets } from "./spec";
+export type { DeploymentSpecMeta, DeploymentSpecResult, EngineSecrets } from "./spec";

package/src/deploy/inputs.ts

@@ -1,3 +1,6 @@
+// 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

package/src/deploy/requirements.test.ts

@@ -1,3 +1,6 @@
+// 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";

package/src/deploy/requirements.ts

@@ -1,3 +1,6 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 ForestHub.
+
 import type { Workflow } from "../workflow";
 import { NodeRegistry, isNodeUsedAsTool } from "../node";
 import { isParameterActive } from "../parameter";

package/src/deploy/spec.test.ts

@@ -1,3 +1,6 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 ForestHub.
+
 import { describe, it, expect } from "vitest";
 import { buildDeploymentSpec, assertDeployable, sidecarServiceName } from "./spec";
 import { deriveRequirements } from "./requirements";
@@ -57,7 +60,6 @@ const fullInputs: DeploymentInputs = {
 
 const meta = {
   id: "dep-1",
-  status: "active" as const,
   engineImage: "fh-engine:0.4.2",
   llamaServerImage: "ghcr.io/ggml-org/llama.cpp:server-b8589",
 };
@@ -68,7 +70,6 @@ describe("buildDeploymentSpec", () => {
 
     expect(spec.schemaVersion).toBe(1);
     expect(spec.id).toBe("dep-1");
-    expect(spec.status).toBe("active");
 
     const engine = engineOf(spec);
     expect(engine.image).toBe("fh-engine:0.4.2");
@@ -102,8 +103,8 @@ describe("buildDeploymentSpec", () => {
     expect(llamaOf(spec, "local-llm")).toMatchObject({
       name: sidecarServiceName("local-llm"),
       image: "ghcr.io/ggml-org/llama.cpp:server-b8589",
-      command: ["--model", "/models/model.gguf", "--host", "0.0.0.0", "--port", "8080", "--ctx-size", "4096"],
-      volumes: ["./models:/models:ro"],
+      command: ["--model", "/var/lib/foresthub/workspace/model.gguf", "--host", "0.0.0.0", "--port", "8080", "--ctx-size", "4096"],
+      volumes: ["./workspaces/llama-local-llm:/var/lib/foresthub/workspace:ro"],
     });
     // The external-resource provider URL must point at the sidecar service name.
     const ext = engineConfigOf(spec).externalResources!;
@@ -145,7 +146,7 @@ describe("buildDeploymentSpec", () => {
     const ext = engineConfigOf(spec).externalResources!;
     const [ref, provider] = Object.entries(ext).find(([, r]) => r.type === "selfhosted")!;
     expect(provider).toEqual({ type: "selfhosted", url: "https://infer.example/v1" });
-    expect(resourceSecrets[ref]).toEqual({ apiKey: "k" });
+    expect(resourceSecrets[ref]).toEqual("k");
   });
 
   it("pulls MQTT/endpoint secrets out of the spec, keyed by resource ref", () => {
@@ -155,7 +156,7 @@ describe("buildDeploymentSpec", () => {
     const [mqttRef, mqttConn] = Object.entries(ext).find(([, r]) => r.type === "mqtt")!;
     expect(mqttConn).not.toHaveProperty("password");
     expect(mqttConn).toMatchObject({ username: "u" });
-    expect(resourceSecrets[mqttRef]).toEqual({ password: "p" });
+    expect(resourceSecrets[mqttRef]).toEqual("p");
     // Whole spec serialized carries no secret value.
     expect(JSON.stringify(spec)).not.toContain('"p"');
   });

package/src/deploy/spec.ts

@@ -1,3 +1,6 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 ForestHub.
+
 // The spec resolver: (workflow + bindings) -> DeploymentSpec. The shared
 // "packaging library" the migration doc calls for — component-set derivation
 // and device-grant resolution computed once here, frozen into the contract spec,
@@ -19,9 +22,22 @@ type DeployComponent = DeploymentSchemas["DeployComponent"];
 // the spec carries it as an opaque blob in DeployComponent.config.
 type EngineConfig = EngineSchemas["EngineConfig"];
 
-// Mount path for the engine's memory volume — matches the image's ENGINE_MEMORY_DIR
-// default, so the renderer mounts here without wiring an env var.
-const ENGINE_MEMORY_PATH = "/var/lib/foresthub/memory";
+// In-container mount path for a component's durable workspace. MUST equal the Go
+// component.Workspace contract constant (go/component/paths.go) — the component
+// reads/writes there, so we mount the host workspace dir there and wire no env var.
+// A cross-repo contract: changing it requires changing the Go constant in lockstep.
+const COMPONENT_WORKSPACE_PATH = "/var/lib/foresthub/workspace";
+
+// The OSS renderer's state root (docs/device-filesystem.md §2). Bind-mount sources
+// hang off it as `<root>/workspaces/<container>/`. "." makes Docker resolve them
+// relative to the compose file, so the bundle stays drop-anywhere; Ranger is a
+// separate renderer that sets root to the absolute `/var/lib/foresthub`.
+const STATE_ROOT = ".";
+
+// Host bind-mount source for a container's workspace under the state root.
+function workspaceDir(container: string): string {
+  return `${STATE_ROOT}/workspaces/${container}`;
+}
 
 // Deploy-time metadata the resolver cannot derive from the workflow: identity,
 // lifecycle, and the full image reference each component runs (frozen here so the
@@ -29,26 +45,24 @@ const ENGINE_MEMORY_PATH = "/var/lib/foresthub/memory";
 // used only when the workflow has an on-device model.
 export interface DeploymentSpecMeta {
   id: string;
-  status: DeploymentSpec["status"];
   createdAt?: string;
   engineImage: string;
   llamaServerImage: string;
 }
 
-// One external resource's credentials. Secrets are NEVER part of the spec (not
-// rotation-safe, breach-exposed if stored): the resolver returns them separately,
-// keyed by the same resource ref the spec's externalResources use, for the
-// renderer to deliver out-of-band (engine env FH_RESOURCE_SECRETS).
-export interface ResourceSecret {
-  password?: string; // MQTT broker password
-  apiKey?: string; // self-hosted LLM endpoint bearer
-}
-export type ResourceSecrets = Record<string, ResourceSecret>;
+// The engine's secret store: a flat map of secret id -> opaque secret value,
+// keyed by the same resource ref the spec's externalResources use. Each value is
+// the single credential that resource needs (MQTT password, self-hosted-LLM
+// bearer token). Secrets are NEVER part of the spec (not rotation-safe, breach-
+// exposed if stored): the resolver returns them separately, for the renderer to
+// deliver out-of-band as a mounted secret document (secrets.json). Mirrors the
+// wire EngineSecrets.
+export type EngineSecrets = Record<string, string>;
 
 // buildDeploymentSpec's output: the secret-free spec plus the pulled-out secrets.
 export interface DeploymentSpecResult {
   spec: DeploymentSpec;
-  resourceSecrets: ResourceSecrets;
+  resourceSecrets: EngineSecrets;
 }
 
 // Hands out stable, collision-free ref names. Same dedup key -> same ref (the
@@ -104,7 +118,7 @@ export function ggufNameError(name: string | undefined): string | null {
   const t = (name ?? "").trim();
   if (!t) return "a model filename is required";
   if (!t.toLowerCase().endsWith(".gguf")) return "must be a .gguf file (llama-server only loads GGUF)";
-  if (t.includes("/")) return "just the filename, not a path — the file goes in ./models/";
+  if (t.includes("/")) return "just the filename, not a path — the file goes in the model's workspace dir (./workspaces/llama-…/)";
   return null;
 }
 
@@ -223,7 +237,7 @@ export function buildDeploymentSpec(
   assertDeployable(req, inputs);
 
   const refs = new RefAllocator();
-  const resourceSecrets: ResourceSecrets = {};
+  const resourceSecrets: EngineSecrets = {};
 
   // DeviceManifest is split per family; accumulate each separately, attach only
   // the non-empty ones (all slots optional).
@@ -234,7 +248,7 @@ export function buildDeploymentSpec(
   const serials: Record<string, EngineSchemas["SerialConfig"]> = {};
 
   const externalResources: EngineSchemas["ExternalResources"] = {};
-  const mapping: EngineSchemas["DeploymentMapping"] = {};
+  const mapping: EngineSchemas["ResourceMapping"] = {};
 
   // Container-level hardware access, resolved once: cdev nodes (GPIO, UART) map
   // one-to-one into the engine component's devices; sysfs families (ADC/DAC/PWM)
@@ -292,7 +306,7 @@ export function buildDeploymentSpec(
     const ref = refs.alloc(`mqtt:${JSON.stringify(conn)}:${b.password ?? ""}`, `mqtt-${brokerHost(b.brokerUrl)}`);
     externalResources[ref] = conn;
     mapping[ch.id] = { ref };
-    if (b.password) resourceSecrets[ref] = { ...resourceSecrets[ref], password: b.password };
+    if (b.password) resourceSecrets[ref] = b.password;
   }
 
   // Custom models: one self-hosted provider per model id. A device model points
@@ -318,7 +332,7 @@ export function buildDeploymentSpec(
         image: meta.llamaServerImage,
         command: [
           "--model",
-          `/models/${b.modelFile}`,
+          `${COMPONENT_WORKSPACE_PATH}/${b.modelFile}`,
           "--host",
           "0.0.0.0",
           "--port",
@@ -326,12 +340,14 @@ export function buildDeploymentSpec(
           "--ctx-size",
           String(b.ctxSize ?? 4096),
         ],
-        volumes: ["./models:/models:ro"],
+        // The model lives in this sidecar's own workspace; read-only, so no chown
+        // is needed (docs §5). The operator drops the GGUF in workspaceDir(service).
+        volumes: [`${workspaceDir(service)}:${COMPONENT_WORKSPACE_PATH}:ro`],
       });
     } else {
       externalResources[ref] = { type: "selfhosted", url: b.url };
       // The endpoint bearer is a secret — out of the spec, returned separately.
-      if (b.apiKey) resourceSecrets[ref] = { apiKey: b.apiKey };
+      if (b.apiKey) resourceSecrets[ref] = b.apiKey;
     }
   }
 
@@ -350,20 +366,23 @@ export function buildDeploymentSpec(
   if (Object.keys(externalResources).length) config.externalResources = externalResources;
   if (Object.keys(manifest).length) config.manifest = manifest;
 
-  // The engine component. configPath is omitted (the image reads the convention
-  // path it defaults to); the config blob is mounted there by the renderer. cdev
-  // nodes pass through as devices; sysfs families force privileged; either case
-  // needs root to open the root-owned nodes the nonroot image otherwise can't.
+  // The engine component. The config blob is mounted at the fixed convention path
+  // (component.ConfigFile) the engine image reads.
   const engine: DeployComponent = {
     name: "engine",
     image: meta.engineImage,
     pull: "never", // built locally before deploy, in no registry
     config,
-    volumes: [`engine-memory:${ENGINE_MEMORY_PATH}`],
+    // Durable memory: a host bind mount under the state root, read-write, at the
+    // in-container workspace path (docs/device-filesystem.md §10).
+    volumes: [`${workspaceDir("engine")}:${COMPONENT_WORKSPACE_PATH}`],
+    // Run as root: writes the rw workspace bind mount without a host chown step
+    // (the OSS default, §5), and also opens root-owned device nodes when hardware
+    // (cdev passthrough / sysfs-privileged) is mapped in below.
+    user: "0:0",
   };
   if (cdev.size > 0) engine.devices = [...cdev];
   if (privileged) engine.privileged = true;
-  if (cdev.size > 0 || privileged) engine.user = "0:0";
 
   const components = [engine, ...llamaComponents, ...customComponents];
   assertNoNameCollisions(components);
@@ -371,7 +390,6 @@ export function buildDeploymentSpec(
   const spec: DeploymentSpec = {
     schemaVersion: 1,
     id: meta.id,
-    status: meta.status,
     components,
   };
   if (meta.createdAt) spec.createdAt = meta.createdAt;

package/src/diagnostics/__fixtures__/diagnosticFixtures.ts

@@ -1,3 +1,6 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 ForestHub.
+
 import type { Edge } from "../../edge";
 import type { NodeDefinition, NodeData } from "../../node";
 import type { DataType, Expression, Reference } from "../../api";

package/src/diagnostics/diagnostics.test.ts

@@ -1,3 +1,6 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 ForestHub.
+
 import { describe, it, expect } from "vitest";
 import { computeNodeDiagnostics, validateFunction, type Diagnostic } from "./diagnostics";
 import type { Expression } from "../api";

package/src/diagnostics/diagnostics.ts

@@ -1,3 +1,6 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 ForestHub.
+
 import type { NodeDefinition, NodeData } from "../node";
 import type { Expression } from "../api";
 import { NodeCategory, NodeRegistry } from "../node";

package/src/diagnostics/index.ts

@@ -1,3 +1,6 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 ForestHub.
+
 export type { DiagnosticSeverity, DiagnosticCategory, Diagnostic, CanvasValidationResult, ValidationResult } from "./diagnostics";
 export {
   computeNodeDiagnostics,

package/src/edge/Edge.ts

@@ -1,3 +1,6 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 ForestHub.
+
 import type { Expression } from "../api";
 
 export interface EdgeData extends Record<string, unknown> {

package/src/edge/EdgeDefinition.ts

@@ -1,3 +1,6 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 ForestHub.
+
 import { Parameter } from "../parameter";
 import type { EdgeType } from "./EdgeType";
 

package/src/edge/EdgeType.ts

@@ -1,3 +1,6 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 ForestHub.
+
 // Edge taxonomy: a plain control/tool edge, or one of the three agent-specific
 // control-flow refinements resolved at connection time from source/target context.
 // Node port handles themselves only carry `control` or `tool`. Tool edges have no

package/src/edge/index.ts

@@ -1,3 +1,6 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 ForestHub.
+
 // Public surface of the edge module. The base type (EdgeData) lives in
 // ./Edge; this file is a barrel only. Mirrors channel/memory/model.
 

package/src/edge/serialization.ts

@@ -1,3 +1,6 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 ForestHub.
+
 import type { Schemas } from "../api";
 import type { Edge, EdgeData } from "./Edge";
 import type { EdgeType } from "./EdgeType";

package/src/expression/index.ts

@@ -1,3 +1,6 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 ForestHub.
+
 export type { ParseResult } from "./parser";
 export { parseExpression } from "./parser";
 export type { ResolvedExpr } from "./types";