miravo 0.6.0 → 0.6.2

package/src/lib/le/le-apply.ts

@@ -1,832 +0,0 @@
-/**
- * LE Apply reconciler.
- *
- * Builds a plan from desired state, then executes create/update
- * operations in dependency order with best-effort error handling
- * (continues on failure, collects all errors).
- */
-
-import { isRecord, type ProtocolName } from "@miravo/shared";
-import { formatThrownError, pMap } from "./le-concurrency.ts";
-import type { LEDevice, LEDeviceHub, LEItem } from "./le-devicehub.ts";
-import type { LEDigitalTwins, LEInstance, LEModel } from "./le-digital-twins.ts";
-import { getDriverName } from "./le-drivers.ts";
-import { formatEndpoint } from "./le-endpoint.ts";
-import {
-  encodeDeviceMarkers,
-  encodeDTInstanceMarkers,
-  isDeviceManaged,
-  isDTManaged,
-  parseDeviceMarkers,
-} from "./le-markers.ts";
-import type { ApplyPlan, ApplyScope, PlanEntry } from "./le-plan.ts";
-
-/** Max concurrent LE API calls per execution phase. Tuned for edge devices. */
-const LE_PHASE_CONCURRENCY = 5;
-
-/** Enforce scope dependencies: instances requires models. */
-function normalizeScopeDeps(scope: readonly ApplyScope[]): readonly ApplyScope[] {
-  const set = new Set(scope);
-  if (set.has("instances")) set.add("models");
-  return [...set];
-}
-
-// --- Desired state types ---
-
-export interface DesiredDevice {
-  readonly instanceId: string;
-  readonly modelName: string;
-  readonly protocol: ProtocolName;
-  readonly deviceName: string;
-  readonly browsePath: string;
-  readonly endpoint: { host: string; port: number };
-  readonly properties: readonly LEItem[];
-  readonly tags: readonly DesiredTag[];
-}
-
-export interface DesiredTag {
-  readonly name: string;
-  readonly tagName: string;
-  readonly valueType: string;
-  readonly properties: readonly LEItem[];
-  readonly description?: string | undefined;
-  readonly unsPath: string;
-  readonly access: string;
-  readonly unit?: string | undefined;
-  readonly euRange?: readonly [number, number] | undefined;
-}
-
-export interface DesiredModel {
-  readonly name: string;
-  readonly leDtJson: unknown;
-}
-
-export interface DesiredInstance {
-  readonly instanceId: string;
-  readonly modelName: string;
-  readonly dtInstanceName: string;
-  readonly dtModelName: string;
-  readonly boundDeviceName: string;
-  readonly browsePath: string;
-}
-
-export interface ResourceProgress {
-  readonly phase: string;
-  readonly resourceType: string;
-  readonly name: string;
-  readonly action: string;
-  readonly status: "success" | "failed";
-  readonly error?: string | undefined;
-  readonly index: number;
-  readonly of: number;
-  /** Number of sub-resources affected (e.g. tags per device). Defaults to 1. */
-  readonly count?: number | undefined;
-}
-
-export interface ApplyOptions {
-  readonly templateId: string;
-  readonly targetHost: string;
-  readonly sourceHostname: string | undefined;
-  readonly scope: readonly ApplyScope[];
-  readonly filters: {
-    readonly area?: string | undefined;
-    readonly line?: string | undefined;
-    readonly instance?: string | undefined;
-  };
-  readonly ifUnmanaged: "fail" | "skip";
-  readonly dryRun: boolean;
-  readonly onProgress?: ((msg: string) => void) | undefined;
-  readonly onResourceComplete?: ((progress: ResourceProgress) => void) | undefined;
-  readonly signal?: AbortSignal | undefined;
-}
-
-export interface ApplyDesiredState {
-  readonly devices: readonly DesiredDevice[];
-  readonly models: readonly DesiredModel[];
-  readonly instances: readonly DesiredInstance[];
-}
-
-/** Snapshot of LE state fetched during planning, reused by the executor. */
-interface LESnapshot {
-  readonly deviceByName: Map<string, LEDevice>;
-  readonly modelsByName: Map<string, LEModel[]>;
-  readonly instanceByName: Map<string, LEInstance>;
-  readonly driverIdByProtocol: Map<ProtocolName, string>;
-}
-
-interface PlanResult {
-  readonly plan: ApplyPlan;
-  readonly snapshot: LESnapshot;
-}
-
-function indexModelsByName(models: readonly LEModel[]): Map<string, LEModel[]> {
-  const byName = new Map<string, LEModel[]>();
-  for (const model of models) {
-    const existing = byName.get(model.Name);
-    if (existing) {
-      existing.push(model);
-    } else {
-      byName.set(model.Name, [model]);
-    }
-  }
-  return byName;
-}
-
-function resolveModelMarkersInImport(
-  modelJson: unknown,
-  data: { templateId: string; modelName: string },
-): unknown {
-  if (!Array.isArray(modelJson)) return modelJson;
-
-  return modelJson.map((entry) => {
-    if (!isRecord(entry)) return entry;
-    const staticAttributes = entry["staticAttributes"];
-    if (!Array.isArray(staticAttributes)) return entry;
-
-    return {
-      ...entry,
-      staticAttributes: staticAttributes.map((attr) => {
-        if (!isRecord(attr) || typeof attr["key"] !== "string") return attr;
-        switch (attr["key"]) {
-          case "miravo_managed":
-            return { ...attr, value: "true" };
-          case "miravo_template":
-            return { ...attr, value: data.templateId };
-          case "miravo_model":
-            return { ...attr, value: data.modelName };
-          default:
-            return attr;
-        }
-      }),
-    };
-  });
-}
-
-function buildTagMetaData(tag: DesiredTag, dev: DesiredDevice): LEItem[] {
-  const meta: LEItem[] = [
-    { Key: "uns_path", Value: tag.unsPath },
-    { Key: "model", Value: dev.modelName },
-    { Key: "instance", Value: dev.instanceId },
-    { Key: "access", Value: tag.access },
-  ];
-  if (tag.unit) meta.push({ Key: "unit", Value: tag.unit });
-  if (tag.euRange) {
-    meta.push(
-      { Key: "eu_range_min", Value: String(tag.euRange[0]) },
-      { Key: "eu_range_max", Value: String(tag.euRange[1]) },
-    );
-  }
-  return meta;
-}
-
-// --- Plan builder ---
-
-export async function buildApplyPlan(
-  hub: LEDeviceHub,
-  dt: LEDigitalTwins,
-  desired: ApplyDesiredState,
-  opts: ApplyOptions,
-): Promise<PlanResult> {
-  const entries: PlanEntry[] = [];
-  // Enforce scope dependencies: instances requires models
-  const scope = normalizeScopeDeps(opts.scope);
-
-  const needDevices = scope.includes("devices");
-  const needModels = scope.includes("models");
-  const needInstances = scope.includes("instances");
-
-  const [existingDevices, existingModels, existingInstances] = await Promise.all([
-    needDevices ? hub.listDevices() : ([] as readonly LEDevice[]),
-    needModels ? dt.listModels() : ([] as readonly LEModel[]),
-    needInstances
-      ? dt.listInstances().catch((): readonly LEInstance[] => {
-          opts.onProgress?.(
-            "⚠ Warning: LE ListInstances failed — treating all DT instances as new (create).",
-          );
-          return [];
-        })
-      : ([] as readonly LEInstance[]),
-  ]);
-
-  const deviceByName = new Map(existingDevices.map((d) => [d.Name, d]));
-  const modelsByName = indexModelsByName(existingModels);
-  const instanceByName = new Map(existingInstances.map((i) => [i.Name, i]));
-
-  const driverCache = new Map<ProtocolName, string>();
-
-  if (scope.includes("devices")) {
-    for (const dev of desired.devices) {
-      const prefixedName = dev.deviceName;
-      const existing = deviceByName.get(prefixedName);
-
-      if (existing) {
-        const managed = isDeviceManaged(existing.MetaData);
-        if (!managed) {
-          if (opts.ifUnmanaged === "fail") {
-            entries.push({
-              action: "blocked",
-              resourceType: "device",
-              name: prefixedName,
-              protocol: dev.protocol,
-              blockReason: `unmanaged device "${prefixedName}" already exists on LE`,
-            });
-            continue;
-          }
-          continue;
-        }
-        // DriverID is immutable on update — replace the device if the protocol changed.
-        const existingMarkers = parseDeviceMarkers(existing.MetaData);
-        const protocolChanged = !!existingMarkers && existingMarkers.protocol !== dev.protocol;
-
-        if (protocolChanged) {
-          if (!driverCache.has(dev.protocol)) {
-            try {
-              const driver = await hub.resolveDriverByName(getDriverName(dev.protocol));
-              driverCache.set(dev.protocol, driver.ID);
-            } catch {
-              entries.push({
-                action: "blocked",
-                resourceType: "device",
-                name: prefixedName,
-                protocol: dev.protocol,
-                blockReason: `LE driver "${getDriverName(dev.protocol)}" not found`,
-              });
-              continue;
-            }
-          }
-          entries.push({
-            action: "replace",
-            resourceType: "device",
-            name: prefixedName,
-            protocol: dev.protocol,
-            endpoint: formatEndpoint(dev.endpoint),
-          });
-        } else {
-          entries.push({
-            action: "update",
-            resourceType: "device",
-            name: prefixedName,
-            protocol: dev.protocol,
-            endpoint: formatEndpoint(dev.endpoint),
-          });
-        }
-      } else {
-        if (!driverCache.has(dev.protocol)) {
-          try {
-            const driver = await hub.resolveDriverByName(getDriverName(dev.protocol));
-            driverCache.set(dev.protocol, driver.ID);
-          } catch {
-            entries.push({
-              action: "blocked",
-              resourceType: "device",
-              name: prefixedName,
-              protocol: dev.protocol,
-              blockReason: `LE driver "${getDriverName(dev.protocol)}" not found`,
-            });
-            continue;
-          }
-        }
-        entries.push({
-          action: "create",
-          resourceType: "device",
-          name: prefixedName,
-          protocol: dev.protocol,
-          endpoint: formatEndpoint(dev.endpoint),
-        });
-      }
-    }
-  }
-
-  if (scope.includes("models")) {
-    for (const model of desired.models) {
-      const dtName = model.name;
-      const existing = modelsByName.get(dtName) ?? [];
-      if (existing.length > 1) {
-        const ids = existing.map((m) => m.ID).join(", ");
-        entries.push({
-          action: "blocked",
-          resourceType: "model",
-          name: dtName,
-          blockReason: `duplicate DT models "${dtName}" exist on LE (ids: ${ids}); clean duplicates before apply`,
-        });
-      } else {
-        entries.push({
-          action: existing.length === 1 ? "update" : "create",
-          resourceType: "model",
-          name: dtName,
-        });
-      }
-    }
-  }
-
-  if (scope.includes("instances")) {
-    // Pre-fetch managed status for all existing instances concurrently
-    const existingInstancePairs = desired.instances
-      .map((inst) => ({
-        inst,
-        existing: instanceByName.get(inst.dtInstanceName),
-      }))
-      .filter((p): p is typeof p & { existing: LEInstance } => p.existing !== undefined);
-
-    const managedStatusMap = new Map<string, boolean>();
-    if (existingInstancePairs.length > 0) {
-      await pMap(
-        existingInstancePairs,
-        async ({ inst, existing }) => {
-          const dtInstName = inst.dtInstanceName;
-          try {
-            const attrs = await dt.listStaticAttributes({ instanceId: existing.ID });
-            managedStatusMap.set(dtInstName, isDTManaged(attrs));
-          } catch {
-            opts.onProgress?.(
-              `⚠ Warning: could not check managed status of instance ${dtInstName} — assuming managed.`,
-            );
-            managedStatusMap.set(dtInstName, true);
-          }
-        },
-        { concurrency: LE_PHASE_CONCURRENCY },
-      );
-    }
-
-    for (const inst of desired.instances) {
-      const dtInstName = inst.dtInstanceName;
-      const existing = instanceByName.get(dtInstName);
-
-      if (existing) {
-        const managed = managedStatusMap.get(dtInstName) ?? true;
-        if (!managed) {
-          if (opts.ifUnmanaged === "fail") {
-            entries.push({
-              action: "blocked",
-              resourceType: "instance",
-              name: dtInstName,
-              blockReason: `unmanaged instance "${dtInstName}" already exists on LE`,
-            });
-            continue;
-          }
-          continue;
-        }
-        entries.push({ action: "update", resourceType: "instance", name: dtInstName });
-      } else {
-        entries.push({ action: "create", resourceType: "instance", name: dtInstName });
-      }
-
-      const instEntry = entries[entries.length - 1];
-      if (instEntry && instEntry.action !== "blocked") {
-        entries.push({
-          action: instEntry.action,
-          resourceType: "param-sync",
-          name: dtInstName,
-          detail: `device=${inst.boundDeviceName}`,
-        });
-      }
-    }
-  }
-
-  const plan: ApplyPlan = {
-    sourceMode: "static",
-    targetHost: opts.targetHost,
-    sourceHostname: opts.sourceHostname,
-    scope: [...scope],
-    filters: opts.filters,
-    entries,
-  };
-
-  return {
-    plan,
-    snapshot: { deviceByName, modelsByName, instanceByName, driverIdByProtocol: driverCache },
-  };
-}
-
-// --- Executor ---
-
-interface ApplyResult {
-  readonly plan: ApplyPlan;
-  readonly applied: number;
-  readonly failed: number;
-  readonly failedEntries: readonly { entry: PlanEntry; error: string }[];
-  readonly error?: string | undefined;
-}
-
-export async function executePlan(
-  hub: LEDeviceHub,
-  dt: LEDigitalTwins,
-  plan: ApplyPlan,
-  desired: ApplyDesiredState,
-  opts: ApplyOptions,
-  snapshot: LESnapshot,
-): Promise<ApplyResult> {
-  const log = opts.onProgress ?? (() => {});
-  const onResource = opts.onResourceComplete;
-  let applied = 0;
-  let nonFatalFailures = 0;
-
-  // Pre-compute per-phase totals for progress reporting
-  const phaseTotals = new Map<string, number>();
-  const phaseCounters = new Map<string, number>();
-  for (const entry of plan.entries) {
-    if (entry.action === "blocked") continue;
-    phaseTotals.set(entry.resourceType, (phaseTotals.get(entry.resourceType) ?? 0) + 1);
-  }
-
-  function emitProgress(
-    phase: string,
-    name: string,
-    action: string,
-    status: "success" | "failed",
-    error?: string,
-    count?: number,
-  ): void {
-    const idx = (phaseCounters.get(phase) ?? 0) + 1;
-    phaseCounters.set(phase, idx);
-    onResource?.({
-      phase,
-      resourceType: phase,
-      name,
-      action,
-      status,
-      error,
-      index: idx,
-      of: phaseTotals.get(phase) ?? 0,
-      count,
-    });
-  }
-
-  // Mutable copies — updated as we create/update resources
-  const { deviceByName, modelsByName, instanceByName, driverIdByProtocol } = snapshot;
-
-  // Pre-index desired state for O(1) lookup instead of linear scans
-  const desiredDeviceByName = new Map(desired.devices.map((d) => [d.deviceName, d]));
-  const desiredModelByName = new Map(desired.models.map((m) => [m.name, m]));
-  const desiredInstanceByName = new Map(desired.instances.map((i) => [i.dtInstanceName, i]));
-
-  function recordNonFatalFailure(msg: string): void {
-    nonFatalFailures++;
-    log(`⚠ Warning: ${msg}`);
-  }
-
-  function getSingleModelByName(name: string): LEModel | undefined {
-    const matches = modelsByName.get(name) ?? [];
-    if (matches.length === 0) return undefined;
-    if (matches.length > 1) {
-      const ids = matches.map((model) => model.ID).join(", ");
-      throw new Error(`duplicate DT models "${name}" exist on LE (ids: ${ids})`);
-    }
-    return matches[0];
-  }
-
-  // Group actionable entries by resource type (phase)
-  const PHASE_ORDER = ["device", "model", "instance", "param-sync"] as const;
-  type PhaseKey = (typeof PHASE_ORDER)[number];
-  const groups = new Map<PhaseKey, PlanEntry[]>();
-  for (const entry of plan.entries) {
-    if (entry.action === "blocked") continue;
-    const list = groups.get(entry.resourceType) ?? [];
-    list.push(entry);
-    groups.set(entry.resourceType, list);
-  }
-
-  // --- Per-entry execution by resource type ---
-
-  async function execDevice(entry: PlanEntry): Promise<void> {
-    const dev = desiredDeviceByName.get(entry.name);
-    if (!dev) throw new Error(`Desired device "${entry.name}" not found`);
-
-    const markers = encodeDeviceMarkers({
-      templateId: opts.templateId,
-      instanceId: dev.instanceId,
-      modelName: dev.modelName,
-      protocol: dev.protocol,
-      unsPath: dev.browsePath,
-    });
-
-    const existing = deviceByName.get(entry.name);
-    let deviceId: string;
-
-    if (existing && entry.action === "replace") {
-      const driverId = driverIdByProtocol.get(dev.protocol);
-      if (!driverId) throw new Error(`Driver for protocol "${dev.protocol}" not resolved`);
-
-      // Protocol changed — DriverID is immutable; delete the old device and recreate
-      // (LE cascade-deletes registers with the device)
-      await hub.deleteDevices([existing.ID]);
-      deviceByName.delete(entry.name);
-      let replaced: Awaited<ReturnType<typeof hub.createDevice>>;
-      try {
-        replaced = await hub.createDevice({
-          DriverID: driverId,
-          Name: entry.name,
-          Properties: dev.properties as LEItem[],
-          MetaData: markers,
-          Description: `Miravo managed: ${dev.instanceId}`,
-        });
-      } catch (err) {
-        const msg = formatThrownError(err);
-        throw new Error(
-          `Device "${entry.name}" was deleted for protocol change but recreation failed: ${msg}`,
-        );
-      }
-      deviceByName.set(entry.name, replaced);
-      deviceId = replaced.ID;
-    } else if (existing) {
-      const result = await hub.updateDevice({
-        ID: existing.ID,
-        Name: entry.name,
-        Properties: dev.properties as LEItem[],
-        MetaData: markers,
-        Description: `Miravo managed: ${dev.instanceId}`,
-      });
-      deviceByName.set(entry.name, result);
-      // Clear existing registers before writing new ones (LE does not cascade-update them)
-      await hub.deleteDeviceRegisters(existing.ID);
-      deviceId = existing.ID;
-    } else {
-      const driverId = driverIdByProtocol.get(dev.protocol);
-      if (!driverId) throw new Error(`Driver for protocol "${dev.protocol}" not resolved`);
-
-      const result = await hub.createDevice({
-        DriverID: driverId,
-        Name: entry.name,
-        Properties: dev.properties as LEItem[],
-        MetaData: markers,
-        Description: `Miravo managed: ${dev.instanceId}`,
-      });
-      deviceByName.set(entry.name, result);
-      deviceId = result.ID;
-    }
-
-    if (dev.tags.length > 0) {
-      await hub.createRegisters(
-        dev.tags.map((tag) => ({
-          DeviceID: deviceId,
-          Name: tag.name,
-          TagName: tag.tagName,
-          ValueType: tag.valueType,
-          Properties: tag.properties as LEItem[],
-          Description: tag.description ?? "",
-          MetaData: buildTagMetaData(tag, dev),
-        })),
-      );
-    }
-    log(
-      `✓ ${entry.action.toUpperCase()} device ${entry.name} [${dev.protocol}] (${dev.tags.length} tags)`,
-    );
-    applied++;
-    emitProgress("device", entry.name, entry.action, "success", undefined, dev.tags.length);
-  }
-
-  async function execModelImport(entry: PlanEntry): Promise<void> {
-    const model = desiredModelByName.get(entry.name);
-    if (!model) throw new Error(`Desired model "${entry.name}" not found`);
-
-    // LE ImportModel always creates a new model entity — it does not upsert.
-    // Skip import for existing models to prevent duplicates.
-    // Model definition changes require cleanup → re-apply.
-    if (entry.action === "update") {
-      log(`✓ UPDATE DT model ${entry.name} (exists)`);
-      applied++;
-      emitProgress("model", entry.name, entry.action, "success");
-      return;
-    }
-
-    await dt.importModel(
-      resolveModelMarkersInImport(model.leDtJson, {
-        templateId: opts.templateId,
-        modelName: model.name,
-      }),
-    );
-    log(`✓ CREATE DT model ${entry.name}`);
-    applied++;
-    emitProgress("model", entry.name, entry.action, "success");
-  }
-
-  async function execInstance(entry: PlanEntry): Promise<void> {
-    const inst = desiredInstanceByName.get(entry.name);
-    if (!inst) throw new Error(`Desired instance "${entry.name}" not found`);
-
-    const dtModelName = inst.dtModelName;
-    const leModel = getSingleModelByName(dtModelName);
-    if (!leModel) {
-      throw new Error(`DT model "${dtModelName}" not found on LE. Ensure models are in scope.`);
-    }
-
-    const dtTopic = `digitaltwins.${leModel.Name}.${entry.name}`;
-    const existing = instanceByName.get(entry.name);
-    if (existing) {
-      const result = await dt.updateInstance({
-        ID: existing.ID,
-        ModelID: leModel.ID,
-        Name: entry.name,
-        Topic: dtTopic,
-        Interval: 1,
-      });
-      instanceByName.set(entry.name, result);
-    } else {
-      const result = await dt.createInstance({
-        ModelID: leModel.ID,
-        Name: entry.name,
-        Topic: dtTopic,
-        Interval: 1,
-      });
-      instanceByName.set(entry.name, result);
-    }
-
-    const leInst = instanceByName.get(entry.name);
-    if (leInst) {
-      try {
-        const existingAttrs = await dt.listStaticAttributes({ instanceId: leInst.ID });
-        const attrByKey = new Map(existingAttrs.map((attr) => [attr.Key, attr]));
-        const instanceMarkers = encodeDTInstanceMarkers({
-          templateId: opts.templateId,
-          modelName: inst.modelName,
-          instanceId: inst.instanceId,
-          unsPath: inst.browsePath,
-        });
-        const updates = instanceMarkers
-          .map((marker) => {
-            const attr = attrByKey.get(marker.Key);
-            if (!attr) return undefined;
-            return {
-              ID: attr.ID,
-              ModelID: attr.ModelID,
-              InstanceID: attr.InstanceID,
-              Key: marker.Key,
-              Value: marker.Value,
-            };
-          })
-          .filter((item): item is NonNullable<typeof item> => item !== undefined);
-
-        if (updates.length !== instanceMarkers.length) {
-          const missing = instanceMarkers
-            .map((marker) => marker.Key)
-            .filter((key) => !attrByKey.has(key));
-          recordNonFatalFailure(
-            `could not set markers on instance ${entry.name}: missing placeholder attrs (${missing.join(", ")})`,
-          );
-        } else {
-          await dt.updateInstanceStaticAttributes(leInst.ID, updates);
-        }
-      } catch (err) {
-        const msg = formatThrownError(err);
-        recordNonFatalFailure(`could not set markers on instance ${entry.name}: ${msg}`);
-      }
-    }
-
-    log(`✓ ${entry.action.toUpperCase()} DT instance ${entry.name}`);
-    applied++;
-    emitProgress("instance", entry.name, entry.action, "success");
-  }
-
-  async function execParamSync(entry: PlanEntry): Promise<void> {
-    const inst = desiredInstanceByName.get(entry.name);
-    if (!inst) throw new Error(`Desired instance "${entry.name}" not found for param sync`);
-
-    const leInst = instanceByName.get(entry.name);
-    if (!leInst) throw new Error(`LE instance "${entry.name}" not found for param sync`);
-
-    const deviceAlias = inst.boundDeviceName;
-    await dt.setInstanceParameters(leInst.ID, [{ Name: "device", Value: deviceAlias }]);
-    log(`✓ SYNC DT parameter device=${deviceAlias} on ${entry.name}`);
-    applied++;
-    emitProgress("param-sync", entry.name, entry.action, "success");
-  }
-
-  const execByPhase: Record<PhaseKey, (entry: PlanEntry) => Promise<void>> = {
-    device: execDevice,
-    model: execModelImport, // model phase uses special two-step flow below
-    instance: execInstance,
-    "param-sync": execParamSync,
-  };
-
-  /** Run a pMap over entries with best-effort semantics — collect all failures. */
-  async function runPhase(
-    phase: PhaseKey,
-    entries: readonly PlanEntry[],
-    fn: (entry: PlanEntry) => Promise<void>,
-  ): Promise<{ entry: PlanEntry; error: string }[]> {
-    const phaseFailures: { entry: PlanEntry; error: string }[] = [];
-
-    await pMap(
-      entries,
-      async (entry) => {
-        try {
-          await fn(entry);
-        } catch (err) {
-          const msg = formatThrownError(err);
-          log(`✗ ${entry.action.toUpperCase()} ${phase} ${entry.name} — ${msg}`);
-          emitProgress(phase, entry.name, entry.action, "failed", msg);
-          phaseFailures.push({ entry, error: msg });
-        }
-      },
-      { concurrency: LE_PHASE_CONCURRENCY, ...(opts.signal ? { signal: opts.signal } : {}) },
-    );
-
-    return phaseFailures;
-  }
-
-  // --- Phase-ordered execution with bounded concurrency ---
-
-  const allFailedEntries: { entry: PlanEntry; error: string }[] = [];
-
-  const refreshModelCache = async () => {
-    const models = await dt.listModels();
-    modelsByName.clear();
-    for (const [name, list] of indexModelsByName(models)) {
-      modelsByName.set(name, list);
-    }
-  };
-
-  function failAllEntries(phase: string, entries: readonly PlanEntry[], msg: string): void {
-    log(`✗ ${phase} pre-phase setup failed — ${msg}`);
-    for (const entry of entries) {
-      emitProgress(phase, entry.name, entry.action, "failed", msg);
-      allFailedEntries.push({ entry, error: msg });
-    }
-  }
-
-  // --- Parallel: device + model (target independent LE services) ---
-
-  async function executeDevicePhase(): Promise<void> {
-    const entries = groups.get("device");
-    if (!entries?.length) return;
-
-    try {
-      const neededProtocols = new Set(
-        entries
-          .filter((e) => e.action === "create" || e.action === "replace")
-          .map((e) => desiredDeviceByName.get(e.name)?.protocol)
-          .filter((p): p is ProtocolName => p !== undefined),
-      );
-      for (const proto of neededProtocols) {
-        if (!driverIdByProtocol.has(proto)) {
-          const driver = await hub.resolveDriverByName(getDriverName(proto));
-          driverIdByProtocol.set(proto, driver.ID);
-        }
-      }
-    } catch (err) {
-      failAllEntries("device", entries, formatThrownError(err));
-      return;
-    }
-
-    allFailedEntries.push(...(await runPhase("device", entries, execDevice)));
-  }
-
-  async function executeModelPhase(): Promise<void> {
-    const entries = groups.get("model");
-    if (!entries?.length) return;
-
-    allFailedEntries.push(...(await runPhase("model", entries, execModelImport)));
-
-    // Refresh model cache only after actual imports so the instance phase can
-    // resolve new model IDs. Skip when all models are updates (no-ops) — the
-    // planning-time cache is already accurate.
-    if (entries.some((e) => e.action === "create")) {
-      try {
-        await refreshModelCache();
-      } catch {
-        try {
-          await refreshModelCache();
-        } catch {
-          log("⚠ Warning: model cache refresh failed — markers may be incomplete");
-        }
-      }
-    }
-  }
-
-  await Promise.all([executeDevicePhase(), executeModelPhase()]);
-
-  // --- Sequential: instance → param-sync (depend on model cache + instance IDs) ---
-
-  let skipInstancePhases = false;
-
-  if (groups.has("instance") && !groups.has("model")) {
-    // Model phase didn't run — refresh cache before instance creation
-    try {
-      await refreshModelCache();
-    } catch (err) {
-      const msg = formatThrownError(err);
-      // biome-ignore lint/style/noNonNullAssertion: group guaranteed to exist by scope dependency check
-      failAllEntries("instance", groups.get("instance")!, msg);
-      const ps = groups.get("param-sync");
-      if (ps?.length) failAllEntries("param-sync", ps, msg);
-      skipInstancePhases = true;
-    }
-  }
-
-  if (!skipInstancePhases) {
-    for (const phase of ["instance", "param-sync"] as const) {
-      const entries = groups.get(phase);
-      if (!entries?.length) continue;
-      allFailedEntries.push(...(await runPhase(phase, entries, execByPhase[phase])));
-    }
-  }
-
-  const totalFailed = allFailedEntries.length + nonFatalFailures;
-  return {
-    plan,
-    applied,
-    failed: totalFailed,
-    failedEntries: allFailedEntries,
-    error: allFailedEntries[0]?.error,
-  };
-}