@foresthubai/workflow-core 0.4.6 → 0.4.7

package/src/deploy/inputs.ts

@@ -1,44 +0,0 @@
-// 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>;
-}

package/src/deploy/spec.test.ts

@@ -1,227 +0,0 @@
-// 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";
-import type { DeploymentInputs } from "./inputs";
-import { MAIN_CANVAS_ID, type Workflow } from "../workflow";
-import type { Channel } from "../channel";
-import type { Model } from "../model";
-import type { DeploymentSchemas, EngineSchemas } from "../api";
-
-type Spec = DeploymentSchemas["DeploymentSpec"];
-
-// The engine is the component named "engine"; its config is transported as an
-// opaque blob, so cast it back to EngineConfig to inspect manifest/mapping/etc.
-function engineOf(spec: Spec): DeploymentSchemas["DeployComponent"] {
-  const e = spec.components.find((c) => c.name === "engine");
-  if (!e) throw new Error("expected engine component");
-  return e;
-}
-function engineConfigOf(spec: Spec): EngineSchemas["EngineConfig"] {
-  return engineOf(spec).config as EngineSchemas["EngineConfig"];
-}
-const llamaOf = (spec: Spec, modelId: string) => spec.components.find((c) => c.name === sidecarServiceName(modelId));
-
-function channel(id: string, type: Channel["type"], args: Record<string, unknown> = {}): Channel {
-  return { id, label: id, type, arguments: args };
-}
-
-const customModel: Model = { id: "local-llm", label: "Local", type: "LLMModel", arguments: {} };
-
-// One workflow exercising every resource kind: a cdev output (GPIO), a serial
-// device (cdev), a sysfs ADC (privileged), an MQTT channel, and an on-device
-// custom model. Empty main canvas — the resolver reads channels/models, not nodes.
-function fullWorkflow(): Workflow {
-  return {
-    canvases: { [MAIN_CANVAS_ID]: { nodes: [], edges: [], variables: {} } },
-    functions: {},
-    channels: {
-      led: channel("led", "GPIOOUT"),
-      serial0: channel("serial0", "UART"),
-      sensor: channel("sensor", "ADC"),
-      telemetry: channel("telemetry", "MQTT", { topic: "t/x" }),
-    },
-    memory: {},
-    models: { "local-llm": customModel },
-  };
-}
-
-const fullInputs: DeploymentInputs = {
-  hardware: {
-    led: { chipOrDevice: "/dev/gpiochip0", index: 17 },
-    serial0: { chipOrDevice: "/dev/ttyUSB0", baud: 9600 },
-    sensor: { chipOrDevice: "/sys/bus/iio/devices/iio:device0", index: 0 },
-  },
-  mqtt: { telemetry: { brokerUrl: "mqtt://broker.local:1883", username: "u", password: "p" } },
-  models: { "local-llm": { location: "device", modelFile: "model.gguf" } },
-};
-
-const meta = {
-  id: "dep-1",
-  engineImage: "fh-engine:0.4.2",
-  llamaServerImage: "ghcr.io/ggml-org/llama.cpp:server-b8589",
-};
-
-describe("buildDeploymentSpec", () => {
-  it("resolves a full workflow into a contract-shaped spec", () => {
-    const { spec } = buildDeploymentSpec(fullWorkflow(), fullInputs, meta);
-
-    expect(spec.schemaVersion).toBe(1);
-    expect(spec.id).toBe("dep-1");
-
-    const engine = engineOf(spec);
-    expect(engine.image).toBe("fh-engine:0.4.2");
-    expect(engine.pull).toBe("never"); // built locally, in no registry
-    expect(engineConfigOf(spec).workflow.schemaVersion).toBeGreaterThanOrEqual(1);
-  });
-
-  it("splits the device manifest by family and maps every resource", () => {
-    const config = engineConfigOf(buildDeploymentSpec(fullWorkflow(), fullInputs, meta).spec);
-    const m = config.manifest!;
-    expect(Object.keys(m.gpios ?? {})).toHaveLength(1);
-    expect(Object.keys(m.serials ?? {})).toHaveLength(1);
-    expect(Object.keys(m.adcs ?? {})).toHaveLength(1);
-
-    // Mapping keyed by every workflow logical id; each ref resolves to a built resource.
-    expect(Object.keys(config.mapping ?? {}).sort()).toEqual(["led", "local-llm", "sensor", "serial0", "telemetry"]);
-    expect(config.mapping!.sensor).toEqual({ ref: expect.any(String), index: 0 });
-  });
-
-  it("resolves cdev nodes into devices and forces privileged for sysfs families", () => {
-    const engine = engineOf(buildDeploymentSpec(fullWorkflow(), fullInputs, meta).spec);
-    // GPIO + serial are cdev → granted; ADC (sysfs) is not a node → privileged instead.
-    expect(engine.devices?.sort()).toEqual(["/dev/gpiochip0", "/dev/ttyUSB0"]);
-    expect(engine.privileged).toBe(true);
-    // A nonroot image reaching root-owned nodes/sysfs runs as root.
-    expect(engine.user).toBe("0:0");
-  });
-
-  it("emits a llama-server component and points the engine's provider at the sidecar", () => {
-    const { spec } = buildDeploymentSpec(fullWorkflow(), fullInputs, meta);
-    expect(llamaOf(spec, "local-llm")).toMatchObject({
-      name: sidecarServiceName("local-llm"),
-      image: "ghcr.io/ggml-org/llama.cpp:server-b8589",
-      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!;
-    const provider = Object.values(ext).find((r) => r.type === "selfhosted");
-    expect(provider).toMatchObject({ url: `http://${sidecarServiceName("local-llm")}:8080` });
-  });
-
-  it("omits privileged and the llama sidecar when neither applies", () => {
-    const wf: Workflow = {
-      canvases: { [MAIN_CANVAS_ID]: { nodes: [], edges: [], variables: {} } },
-      functions: {},
-      channels: { led: channel("led", "GPIOOUT") },
-      memory: {},
-      models: {},
-    };
-    const { spec } = buildDeploymentSpec(wf, { hardware: { led: { chipOrDevice: "/dev/gpiochip0", index: 1 } }, mqtt: {}, models: {} }, meta);
-    const engine = engineOf(spec);
-    expect(engine.privileged).toBeUndefined();
-    expect(spec.components).toHaveLength(1); // engine only, no sidecar
-    expect(engine.devices).toEqual(["/dev/gpiochip0"]);
-  });
-
-  it("uses a network model's own endpoint and runs no sidecar", () => {
-    const wf: Workflow = {
-      canvases: { [MAIN_CANVAS_ID]: { nodes: [], edges: [], variables: {} } },
-      functions: {},
-      channels: {},
-      memory: {},
-      models: { "local-llm": customModel },
-    };
-    const inputs: DeploymentInputs = {
-      hardware: {},
-      mqtt: {},
-      models: { "local-llm": { location: "network", url: "https://infer.example/v1", apiKey: "k" } },
-    };
-    const { spec, resourceSecrets } = buildDeploymentSpec(wf, inputs, meta);
-    expect(spec.components).toHaveLength(1); // engine only, no sidecar
-    // The provider config in the spec is secret-free; the apiKey is pulled out.
-    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("k");
-  });
-
-  it("pulls MQTT/endpoint secrets out of the spec, keyed by resource ref", () => {
-    const { spec, resourceSecrets } = buildDeploymentSpec(fullWorkflow(), fullInputs, meta);
-    const ext = engineConfigOf(spec).externalResources!;
-    // The stored connection carries metadata but never the password.
-    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("p");
-    // Whole spec serialized carries no secret value.
-    expect(JSON.stringify(spec)).not.toContain('"p"');
-  });
-});
-
-describe("buildDeploymentSpec custom components", () => {
-  const bareWf: Workflow = {
-    canvases: { [MAIN_CANVAS_ID]: { nodes: [], edges: [], variables: {} } },
-    functions: {},
-    channels: {},
-    memory: {},
-    models: {},
-  };
-  const bareInputs: DeploymentInputs = { hardware: {}, mqtt: {}, models: {} };
-
-  it("merges custom components after engine (and llama)", () => {
-    const grafana = { name: "grafana", image: "grafana/grafana:11.3.0", ports: ["3000:3000"] };
-    const { spec } = buildDeploymentSpec(bareWf, bareInputs, meta, [grafana]);
-    expect(spec.components.map((c) => c.name)).toEqual(["engine", "grafana"]);
-  });
-
-  it("rejects a custom name colliding with the engine", () => {
-    expect(() => buildDeploymentSpec(bareWf, bareInputs, meta, [{ name: "engine", image: "x" }])).toThrow(
-      /duplicate component name "engine"/,
-    );
-  });
-
-  it("rejects a custom name colliding with a generated llama sidecar", () => {
-    const dup = { name: sidecarServiceName("local-llm"), image: "x" };
-    expect(() => buildDeploymentSpec(fullWorkflow(), fullInputs, meta, [dup])).toThrow(/duplicate component name/);
-  });
-
-  it("allows the same image under different names", () => {
-    const a = { name: "graf-a", image: "grafana/grafana:11.3.0" };
-    const b = { name: "graf-b", image: "grafana/grafana:11.3.0" };
-    const { spec } = buildDeploymentSpec(bareWf, bareInputs, meta, [a, b]);
-    expect(spec.components.map((c) => c.name)).toEqual(["engine", "graf-a", "graf-b"]);
-  });
-
-  it("rejects two customs sharing a name", () => {
-    const a = { name: "dash", image: "x" };
-    const b = { name: "dash", image: "y" };
-    expect(() => buildDeploymentSpec(bareWf, bareInputs, meta, [a, b])).toThrow(/duplicate component name "dash"/);
-  });
-});
-
-describe("assertDeployable", () => {
-  it("throws listing every unbound resource", () => {
-    const req = deriveRequirements(fullWorkflow());
-    expect(() => assertDeployable(req, { hardware: {}, mqtt: {}, models: {} })).toThrow(/device path[\s\S]*broker URL[\s\S]*model/);
-  });
-
-  it("rejects a non-GGUF on-device model file", () => {
-    const req = deriveRequirements(fullWorkflow());
-    const inputs = { ...fullInputs, models: { "local-llm": { location: "device" as const, modelFile: "model.bin" } } };
-    expect(() => assertDeployable(req, inputs)).toThrow(/\.gguf/);
-  });
-});
-
-describe("deriveRequirements", () => {
-  it("classifies channels into hardware families and mqtt", () => {
-    const req = deriveRequirements(fullWorkflow());
-    expect(req.hardwareChannels.map((c) => c.family).sort()).toEqual(["adc", "gpio", "serial"]);
-    expect(req.mqttChannels.map((c) => c.id)).toEqual(["telemetry"]);
-    expect(req.customModels.map((c) => c.id)).toEqual(["local-llm"]);
-    expect(req.hardwareChannels.find((c) => c.family === "serial")?.addressable).toBe(false);
-  });
-});

package/src/deploy/spec.ts

@@ -1,397 +0,0 @@
-// 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,
-// so neither renderer (OSS one-shot CLI, paid ranger) re-derives them.
-//
-// Every produced field is typed against the generated deployment contract, so a
-// contract change stops this compiling — the drift guard for the spec.
-
-import type { Workflow } from "../workflow";
-import { serialize } from "../workflow";
-import type { DeploymentSchemas, EngineSchemas } from "../api";
-import { deriveRequirements } from "./requirements";
-import type { DeployRequirements, HardwareChannel, HardwareFamily } from "./requirements";
-import type { DeploymentInputs, HardwareBinding } from "./inputs";
-
-type DeploymentSpec = DeploymentSchemas["DeploymentSpec"];
-type DeployComponent = DeploymentSchemas["DeployComponent"];
-// Typed against the engine's own contract (engine.yaml), not the deployment one:
-// the spec carries it as an opaque blob in DeployComponent.config.
-type EngineConfig = EngineSchemas["EngineConfig"];
-
-// 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
-// renderer emits a coordinate rather than assembling one). llamaServerImage is
-// used only when the workflow has an on-device model.
-export interface DeploymentSpecMeta {
-  id: string;
-  createdAt?: string;
-  engineImage: string;
-  llamaServerImage: string;
-}
-
-// 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: EngineSecrets;
-}
-
-// Hands out stable, collision-free ref names. Same dedup key -> same ref (the
-// engine builds that resource once); distinct keys preferring the same name get
-// suffixed (-2, -3, ...) so the flat ref namespace stays unambiguous.
-class RefAllocator {
-  private readonly byKey = new Map<string, string>();
-  private readonly used = new Set<string>();
-
-  alloc(key: string, hint: string): string {
-    const existing = this.byKey.get(key);
-    if (existing) return existing;
-    let ref = hint;
-    for (let n = 2; this.used.has(ref); n++) ref = `${hint}-${n}`;
-    this.used.add(ref);
-    this.byKey.set(key, ref);
-    return ref;
-  }
-}
-
-// Last path/URL segment, reduced to a safe ref token.
-// "/dev/gpiochip0" -> "gpiochip0", ".../iio:device0" -> "iio:device0".
-function basename(p: string): string {
-  const tail = p.replace(/\/+$/, "").split("/").pop() ?? p;
-  return tail.replace(/[^A-Za-z0-9._:-]/g, "-") || "res";
-}
-
-// Host of a broker URL, for a readable ref. "mqtt" when unparseable.
-function brokerHost(url: string): string {
-  try {
-    return new URL(url).hostname || "mqtt";
-  } catch {
-    return "mqtt";
-  }
-}
-
-// Compose/container service name for an on-device model's llama-server sidecar.
-// Single source of truth: the resolver derives the provider URL from it and the
-// renderer emits a service with the same name — they must agree or the URL
-// points at a service that doesn't exist.
-export function sidecarServiceName(modelId: string): string {
-  const slug = modelId
-    .toLowerCase()
-    .replace(/[^a-z0-9._-]+/g, "-")
-    .replace(/^-+|-+$/g, "");
-  return `llama-${slug || "model"}`;
-}
-
-// Why an on-device model filename is unacceptable, or null when fine. A name
-// check only — the file doesn't exist yet at spec time. Shared with the prompts
-// so input collection and the resolver reject the same input.
-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 the model's workspace dir (./workspaces/llama-…/)";
-  return null;
-}
-
-// A physical address belongs to exactly one channel — the engine doesn't police
-// this and would silently let the last claimer win. Same key = collision;
-// sharing just a chip path is fine (one chip, many lines), except serial where
-// the path IS the device. Exported so input collection (prompts) can reject a
-// duplicate at entry with the same identity the resolver validates against.
-export function hardwareAddressKey(family: HardwareFamily, chipOrDevice: string, index?: number): string {
-  const dev = chipOrDevice.trim();
-  return family === "serial" ? `serial:${dev}` : `${family}:${dev}:${index}`;
-}
-
-// The same address phrased for an error message: "/dev/gpiochip0 line 17".
-export function hardwareAddressLabel(family: HardwareFamily, chipOrDevice: string, index?: number): string {
-  const dev = chipOrDevice.trim();
-  if (family === "serial") return dev;
-  return `${dev} ${family === "gpio" ? "line" : "channel"} ${index}`;
-}
-
-// One message per channel whose address an earlier channel already claimed.
-// Incomplete bindings are skipped (completeness is checked separately).
-export function hardwareConflicts(channels: HardwareChannel[], bindings: Record<string, HardwareBinding>): string[] {
-  const conflicts: string[] = [];
-  const claimed = new Map<string, string>(); // address key -> channel id holding it
-  for (const ch of channels) {
-    const b = bindings[ch.id];
-    if (!b?.chipOrDevice || (ch.addressable && b.index === undefined)) continue;
-    const key = hardwareAddressKey(ch.family, b.chipOrDevice, b.index);
-    const holder = claimed.get(key);
-    if (holder) {
-      conflicts.push(`hardware "${ch.id}": ${hardwareAddressLabel(ch.family, b.chipOrDevice, b.index)} is already used by "${holder}"`);
-    } else {
-      claimed.set(key, ch.id);
-    }
-  }
-  return conflicts;
-}
-
-// One message per binding carrying a field its family doesn't have (`baud` is
-// serial-only, `index` is everything-but-serial). Usually a mixed-up channel id
-// in a machine-written binding set — reject loudly instead of ignoring.
-export function familyMismatches(channels: HardwareChannel[], bindings: Record<string, HardwareBinding>): string[] {
-  const mismatches: string[] = [];
-  for (const ch of channels) {
-    const b = bindings[ch.id];
-    if (!b) continue;
-    if (ch.family !== "serial" && b.baud !== undefined) {
-      mismatches.push(`hardware "${ch.id}": "baud" only applies to serial channels (this is a ${ch.family} channel)`);
-    }
-    if (ch.family === "serial" && b.index !== undefined) {
-      mismatches.push(`hardware "${ch.id}": "index" does not apply to serial channels (the device path is the full address)`);
-    }
-  }
-  return mismatches;
-}
-
-// Exhaustiveness guard over HardwareFamily — a new family breaks compilation
-// here until handled.
-function assertNeverFamily(f: never): never {
-  throw new Error(`unhandled hardware family: ${String(f)}`);
-}
-
-// Mirror of the engine's deploy-layer validation: every declared resource must
-// carry a binding or the engine fatals at boot. Collects ALL gaps so a caller
-// sees them at once. Throws on any gap — the last guard before a dead spec.
-export function assertDeployable(req: DeployRequirements, inputs: DeploymentInputs): void {
-  const missing: string[] = [];
-  for (const ch of req.hardwareChannels) {
-    const b = inputs.hardware[ch.id];
-    if (!b?.chipOrDevice) missing.push(`hardware "${ch.id}": device path`);
-    else if (ch.addressable && b.index === undefined) missing.push(`hardware "${ch.id}": index`);
-  }
-  for (const ch of req.mqttChannels) {
-    if (!inputs.mqtt[ch.id]?.brokerUrl) missing.push(`mqtt "${ch.id}": broker URL`);
-  }
-  for (const m of req.customModels) {
-    const b = inputs.models[m.id];
-    if (b?.location === "device") {
-      const err = ggufNameError(b.modelFile);
-      if (err) missing.push(`model "${m.id}": ${err}`);
-    } else if (!b?.url) {
-      missing.push(`model "${m.id}": endpoint URL`);
-    }
-  }
-  missing.push(...hardwareConflicts(req.hardwareChannels, inputs.hardware));
-  missing.push(...familyMismatches(req.hardwareChannels, inputs.hardware));
-  if (missing.length > 0) {
-    throw new Error(`invalid deploy config:\n  - ${missing.join("\n  - ")}`);
-  }
-}
-
-// One compose service per name: a duplicate name would collapse two components
-// onto one service and silently drop the loser. Names only — same image under
-// different names is legitimate (e.g. two grafanas).
-function assertNoNameCollisions(components: DeployComponent[]): void {
-  const seen = new Set<string>();
-  for (const c of components) {
-    if (seen.has(c.name)) throw new Error(`duplicate component name "${c.name}"`);
-    seen.add(c.name);
-  }
-}
-
-// buildDeploymentSpec resolves a workflow plus its bindings into a complete,
-// contract-defined DeploymentSpec. Throws (via assertDeployable) if any declared
-// resource is unbound. The embedded engine config carries the serialized (and
-// thereby pruned) workflow; device grants and privileged are resolved here.
-// customComponents are operator-authored containers, merged in verbatim.
-export function buildDeploymentSpec(
-  workflow: Workflow,
-  inputs: DeploymentInputs,
-  meta: DeploymentSpecMeta,
-  customComponents: DeployComponent[] = [],
-): DeploymentSpecResult {
-  const req = deriveRequirements(workflow);
-  assertDeployable(req, inputs);
-
-  const refs = new RefAllocator();
-  const resourceSecrets: EngineSecrets = {};
-
-  // DeviceManifest is split per family; accumulate each separately, attach only
-  // the non-empty ones (all slots optional).
-  const gpios: Record<string, EngineSchemas["GPIOConfig"]> = {};
-  const adcs: Record<string, EngineSchemas["ADCConfig"]> = {};
-  const dacs: Record<string, EngineSchemas["DACConfig"]> = {};
-  const pwms: Record<string, EngineSchemas["PWMConfig"]> = {};
-  const serials: Record<string, EngineSchemas["SerialConfig"]> = {};
-
-  const externalResources: EngineSchemas["ExternalResources"] = {};
-  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)
-  // have no single node, so the engine container runs privileged.
-  const cdev = new Set<string>();
-  let privileged = false;
-
-  // Hardware: one driver instance per distinct device path (dedup by
-  // family+path); one mapping per channel carrying its per-channel index.
-  for (const ch of req.hardwareChannels) {
-    const b = inputs.hardware[ch.id];
-    if (!b) throw new Error(`unbound hardware channel ${ch.id}`); // unreachable after assertDeployable
-    const dev = b.chipOrDevice;
-    const ref = refs.alloc(`hw:${ch.family}:${dev}`, basename(dev));
-
-    switch (ch.family) {
-      case "gpio":
-        gpios[ref] = { chip: dev };
-        cdev.add(dev);
-        break;
-      case "serial":
-        serials[ref] = b.baud ? { device: dev, baud: b.baud } : { device: dev };
-        cdev.add(dev);
-        break;
-      case "pwm":
-        pwms[ref] = { chip: dev };
-        privileged = true;
-        break;
-      case "adc":
-        adcs[ref] = { device: dev };
-        privileged = true;
-        break;
-      case "dac":
-        dacs[ref] = { device: dev };
-        privileged = true;
-        break;
-      default:
-        return assertNeverFamily(ch.family);
-    }
-
-    if (ch.addressable && b.index !== undefined) mapping[ch.id] = { ref, index: b.index };
-    else mapping[ch.id] = { ref };
-  }
-
-  // MQTT: one connection per distinct config (dedup by full content — same
-  // broker, different creds is a different resource). No index.
-  for (const ch of req.mqttChannels) {
-    const b = inputs.mqtt[ch.id];
-    if (!b) throw new Error(`unbound mqtt channel ${ch.id}`); // unreachable
-    const conn: EngineSchemas["MQTTConnection"] = { type: "mqtt", brokerUrl: b.brokerUrl };
-    if (b.username) conn.username = b.username;
-    // The password is a secret — kept out of conn (and thus the spec). It still
-    // participates in the dedup key, so two channels differing only by password
-    // don't collapse onto one ref (and one shared secret).
-    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] = b.password;
-  }
-
-  // Custom models: one self-hosted provider per model id. A device model points
-  // at the sidecar we run (over the container network, no key) and gets its own
-  // llama-server component; a network model points at the operator's endpoint and
-  // runs no component here. `model` is left off — the endpoint serves under the
-  // workflow id (no upstream-name aliasing yet).
-  const llamaComponents: DeployComponent[] = [];
-  for (const m of req.customModels) {
-    const b = inputs.models[m.id];
-    if (!b) throw new Error(`unbound model ${m.id}`); // unreachable after assertDeployable
-    const ref = refs.alloc(`model:${m.id}`, basename(m.id));
-    mapping[m.id] = { ref };
-
-    if (b.location === "device") {
-      const port = b.port ?? 8080;
-      const service = sidecarServiceName(m.id);
-      externalResources[ref] = { type: "selfhosted", url: `http://${service}:${port}` };
-      // The whole config is CLI flags, so it rides in `command` (no config blob).
-      // ctx-size is frozen here — retuning it is a re-deploy, not an env edit.
-      llamaComponents.push({
-        name: service,
-        image: meta.llamaServerImage,
-        command: [
-          "--model",
-          `${COMPONENT_WORKSPACE_PATH}/${b.modelFile}`,
-          "--host",
-          "0.0.0.0",
-          "--port",
-          String(port),
-          "--ctx-size",
-          String(b.ctxSize ?? 4096),
-        ],
-        // 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] = b.apiKey;
-    }
-  }
-
-  const manifest: EngineSchemas["DeviceManifest"] = {};
-  if (Object.keys(gpios).length) manifest.gpios = gpios;
-  if (Object.keys(adcs).length) manifest.adcs = adcs;
-  if (Object.keys(dacs).length) manifest.dacs = dacs;
-  if (Object.keys(pwms).length) manifest.pwms = pwms;
-  if (Object.keys(serials).length) manifest.serials = serials;
-
-  // The engine's boot input. workflow is serialized (and thereby pruned) from
-  // the domain. The optional sections attach only when non-empty — an absent
-  // section is correct, not a gap, and matches what the engine skips.
-  const config: EngineConfig = { workflow: serialize(workflow) };
-  if (Object.keys(mapping).length) config.mapping = mapping;
-  if (Object.keys(externalResources).length) config.externalResources = externalResources;
-  if (Object.keys(manifest).length) config.manifest = manifest;
-
-  // 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,
-    // 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;
-
-  const components = [engine, ...llamaComponents, ...customComponents];
-  assertNoNameCollisions(components);
-
-  const spec: DeploymentSpec = {
-    schemaVersion: 1,
-    id: meta.id,
-    components,
-  };
-  if (meta.createdAt) spec.createdAt = meta.createdAt;
-  return { spec, resourceSecrets };
-}