@camstack/addon-pipeline 1.1.42 → 1.1.44

package/dist/detection-pipeline/index.mjs

@@ -1,5 +1,5 @@
 import { t as __require } from "../chunk-BdkLduGY.mjs";
-import { H as createEvent, I as errMsg, K as parseJsonUnknown, L as BaseAddon, O as pipelineExecutorCapability, P as supportedRuntimes$1, S as hfModelUrl, U as hydrateSchema, V as EventCategory, Y as sleep, a as COCO_TO_MACRO, b as detectionPipelineCapability, f as YAMNET_TO_MACRO, i as COCO_80_LABELS, j as runtimeDevices$1, r as AUDIO_MACRO_LABELS, t as APPLE_SA_TO_MACRO, v as defaultDeviceFor$1, x as evaluateZoneRules } from "../dist-GFd8M6KO.mjs";
+import { H as createEvent, I as errMsg, L as BaseAddon, O as pipelineExecutorCapability, P as supportedRuntimes$1, S as hfModelUrl, U as hydrateSchema, V as EventCategory, X as sleep, a as COCO_TO_MACRO, b as detectionPipelineCapability, f as YAMNET_TO_MACRO, i as COCO_80_LABELS, j as runtimeDevices$1, q as parseJsonUnknown, r as AUDIO_MACRO_LABELS, t as APPLE_SA_TO_MACRO, v as defaultDeviceFor$1, x as evaluateZoneRules } from "../dist-CgBGV988.mjs";
 import { t as pickNodePlatformArch } from "../node-topology-platform-BkR_k6WT.mjs";
 import { a as isModelDownloaded, i as ensureModel, n as deleteModelFromDisk } from "../model-download-service-C-IHWnXx-BPy6aoAx.mjs";
 import { FrameRingReaderCache } from "@camstack/shm-ring";
@@ -1175,7 +1175,7 @@ var ovFormat = (url, sizeMB) => {
 * `camstack-<id>-<precision>.xml`. Lets an operator scale the model to the node
 * (e.g. yolo26x-int8 on a 265K, yolo26n-int8 on an N100).
 */
-var ovPrecisionVariant = (baseId, ovDir, baseName, precision, sizeMB) => ({
+var ovPrecisionVariant = (baseId, ovDir, baseName, precision, sizeMB, legacy = false) => ({
 	id: `${baseId}-${precision}`,
 	name: `${baseName} (${precision.toUpperCase()})`,
 	description: `${baseName} — OpenVINO ${precision.toUpperCase()} variant for Intel iGPU/NPU; scale by hardware`,
@@ -1185,7 +1185,13 @@ var ovPrecisionVariant = (baseId, ovDir, baseName, precision, sizeMB) => ({
 	},
 	labels: [],
 	preprocessMode: "letterbox",
-	formats: { openvino: ovFormat(hf(`${ovDir}/camstack-${baseId}-${precision}.xml`), sizeMB) }
+	formats: { openvino: ovFormat(hf(`${ovDir}/camstack-${baseId}-${precision}.xml`), sizeMB) },
+	...legacy ? { legacy: true } : {},
+	...precision === "int8" ? { group: {
+		family: baseId.slice(0, -1),
+		tier: baseId.slice(-1),
+		precision: "int8"
+	} } : {}
 });
 var MLPACKAGE_FILES = [
 	"Manifest.json",
@@ -1195,6 +1201,7 @@ var MLPACKAGE_FILES = [
 var OBJECT_DETECTION_MODELS = [
 	{
 		id: "yolov9t",
+		legacy: true,
 		name: "YOLOv9 Tiny",
 		description: "YOLOv9 Tiny — ultra-lightweight next-gen detector",
 		inputSize: {
@@ -1220,6 +1227,7 @@ var OBJECT_DETECTION_MODELS = [
 	},
 	{
 		id: "yolov9s",
+		legacy: true,
 		name: "YOLOv9 Small",
 		description: "YOLOv9 Small — improved efficiency over YOLOv8s",
 		inputSize: {
@@ -1245,6 +1253,7 @@ var OBJECT_DETECTION_MODELS = [
 	},
 	{
 		id: "yolov9c",
+		legacy: true,
 		name: "YOLOv9 C",
 		description: "YOLOv9 C — high-accuracy compact model",
 		inputSize: {
@@ -1270,6 +1279,10 @@ var OBJECT_DETECTION_MODELS = [
 	},
 	{
 		id: "yolo26n",
+		group: {
+			family: "yolo26",
+			tier: "n"
+		},
 		name: "YOLO26 Nano",
 		description: "YOLO26 Nano — latest generation ultra-lightweight detector with attention mechanism",
 		inputSize: {
@@ -1295,6 +1308,10 @@ var OBJECT_DETECTION_MODELS = [
 	},
 	{
 		id: "yolo26s",
+		group: {
+			family: "yolo26",
+			tier: "s"
+		},
 		name: "YOLO26 Small",
 		description: "YOLO26 Small — balanced speed/accuracy with attention-based architecture",
 		inputSize: {
@@ -1320,6 +1337,10 @@ var OBJECT_DETECTION_MODELS = [
 	},
 	{
 		id: "yolo26m",
+		group: {
+			family: "yolo26",
+			tier: "m"
+		},
 		name: "YOLO26 Medium",
 		description: "YOLO26 Medium — high accuracy general-purpose detector",
 		inputSize: {
@@ -1345,6 +1366,10 @@ var OBJECT_DETECTION_MODELS = [
 	},
 	{
 		id: "yolo26l",
+		group: {
+			family: "yolo26",
+			tier: "l"
+		},
 		name: "YOLO26 Large",
 		description: "YOLO26 Large — maximum accuracy for demanding deployments",
 		inputSize: {
@@ -1370,6 +1395,7 @@ var OBJECT_DETECTION_MODELS = [
 	},
 	{
 		id: "yolo26x",
+		legacy: true,
 		name: "YOLO26 XLarge",
 		description: "YOLO26 XLarge — highest accuracy, attention-based architecture",
 		inputSize: {
@@ -1395,6 +1421,7 @@ var OBJECT_DETECTION_MODELS = [
 	},
 	{
 		id: "scrypted-yolov9t-relu",
+		legacy: true,
 		name: "YOLOv9 Tiny ReLU",
 		description: "YOLOv9t ReLU — optimized for int8 quantization",
 		inputSize: {
@@ -1420,6 +1447,7 @@ var OBJECT_DETECTION_MODELS = [
 	},
 	{
 		id: "scrypted-yolov9s-relu",
+		legacy: true,
 		name: "YOLOv9 Small ReLU",
 		description: "YOLOv9s ReLU — improved efficiency, int8 ready",
 		inputSize: {
@@ -1445,6 +1473,7 @@ var OBJECT_DETECTION_MODELS = [
 	},
 	{
 		id: "scrypted-yolov9c-relu",
+		legacy: true,
 		name: "YOLOv9 C ReLU",
 		description: "YOLOv9c ReLU — high-accuracy, int8 ready",
 		inputSize: {
@@ -1470,6 +1499,7 @@ var OBJECT_DETECTION_MODELS = [
 	},
 	{
 		id: "scrypted-yolov9m-relu",
+		legacy: true,
 		name: "YOLOv9 M ReLU",
 		description: "YOLOv9m ReLU — medium, int8 ready",
 		inputSize: {
@@ -1493,20 +1523,20 @@ var OBJECT_DETECTION_MODELS = [
 			openvino: ovFormat(hf("objectDetection/scrypted-yolov9-relu/openvino/scrypted_yolov9m_relu.xml"), 38)
 		}
 	},
-	ovPrecisionVariant("yolov9t", "objectDetection/yolov9/openvino", "YOLOv9 Tiny", "fp16", 5),
-	ovPrecisionVariant("yolov9t", "objectDetection/yolov9/openvino", "YOLOv9 Tiny", "int8", 3),
-	ovPrecisionVariant("yolov9s", "objectDetection/yolov9/openvino", "YOLOv9 Small", "fp16", 15),
-	ovPrecisionVariant("yolov9s", "objectDetection/yolov9/openvino", "YOLOv9 Small", "int8", 8),
-	ovPrecisionVariant("yolo26n", "objectDetection/yolo26/openvino", "YOLO26 Nano", "fp16", 5),
+	ovPrecisionVariant("yolov9t", "objectDetection/yolov9/openvino", "YOLOv9 Tiny", "fp16", 5, true),
+	ovPrecisionVariant("yolov9t", "objectDetection/yolov9/openvino", "YOLOv9 Tiny", "int8", 3, true),
+	ovPrecisionVariant("yolov9s", "objectDetection/yolov9/openvino", "YOLOv9 Small", "fp16", 15, true),
+	ovPrecisionVariant("yolov9s", "objectDetection/yolov9/openvino", "YOLOv9 Small", "int8", 8, true),
+	ovPrecisionVariant("yolo26n", "objectDetection/yolo26/openvino", "YOLO26 Nano", "fp16", 5, true),
 	ovPrecisionVariant("yolo26n", "objectDetection/yolo26/openvino", "YOLO26 Nano", "int8", 3),
-	ovPrecisionVariant("yolo26s", "objectDetection/yolo26/openvino", "YOLO26 Small", "fp16", 19),
+	ovPrecisionVariant("yolo26s", "objectDetection/yolo26/openvino", "YOLO26 Small", "fp16", 19, true),
 	ovPrecisionVariant("yolo26s", "objectDetection/yolo26/openvino", "YOLO26 Small", "int8", 10),
-	ovPrecisionVariant("yolo26m", "objectDetection/yolo26/openvino", "YOLO26 Medium", "fp16", 41),
+	ovPrecisionVariant("yolo26m", "objectDetection/yolo26/openvino", "YOLO26 Medium", "fp16", 41, true),
 	ovPrecisionVariant("yolo26m", "objectDetection/yolo26/openvino", "YOLO26 Medium", "int8", 21),
-	ovPrecisionVariant("yolo26l", "objectDetection/yolo26/openvino", "YOLO26 Large", "fp16", 50),
+	ovPrecisionVariant("yolo26l", "objectDetection/yolo26/openvino", "YOLO26 Large", "fp16", 50, true),
 	ovPrecisionVariant("yolo26l", "objectDetection/yolo26/openvino", "YOLO26 Large", "int8", 25),
-	ovPrecisionVariant("yolo26x", "objectDetection/yolo26/openvino", "YOLO26 XLarge", "fp16", 112),
-	ovPrecisionVariant("yolo26x", "objectDetection/yolo26/openvino", "YOLO26 XLarge", "int8", 56)
+	ovPrecisionVariant("yolo26x", "objectDetection/yolo26/openvino", "YOLO26 XLarge", "fp16", 112, true),
+	ovPrecisionVariant("yolo26x", "objectDetection/yolo26/openvino", "YOLO26 XLarge", "int8", 56, true)
 ];
 var FACE_DETECTION_MODELS = [{
 	id: "scrfd-2.5g",
@@ -2372,17 +2402,58 @@ function getStepDefinition(stepId) {
 }
 /**
 * Get the default model ID for a step given the current model format.
-* Selects the smallest model that supports the format.
-* Falls back to StepDefinition.defaultModelId if no format-specific model found.
+*
+* Resolution order:
+*   1. `def.defaultModelIdByFormat?.[format]` — the step's declared
+*      per-format preference — if that model exists in `def.models` AND
+*      has a build for `format`.
+*   2. `def.defaultModelId` — the step's plain declared default — if it
+*      exists in `def.models` AND has a build for `format`.
+*   3. The smallest-by-size model among those with a `format` build
+*      (legacy fallback, preserved for steps/formats with no declared
+*      preference reachable).
+*   4. `def.defaultModelId` unchanged, when ZERO models have a `format`
+*      build — an unloadable case flagged elsewhere, not resolved here.
 */
 function getDefaultModelForFormat(stepId, format) {
 	const def = getStepDefinition(stepId);
-	const available = def.models.filter((m) => m.formats[format]);
+	const hasFormatBuild = (modelId) => def.models.find((m) => m.id === modelId)?.formats[format] !== void 0;
+	const declaredForFormat = def.defaultModelIdByFormat?.[format];
+	if (declaredForFormat !== void 0 && hasFormatBuild(declaredForFormat)) return declaredForFormat;
+	if (hasFormatBuild(def.defaultModelId)) return def.defaultModelId;
+	const available = def.models.filter((m) => m.formats[format] && m.legacy !== true);
 	if (available.length === 0) return def.defaultModelId;
 	return [...available].toSorted((a, b) => {
 		return (a.formats[format]?.sizeMB ?? Infinity) - (b.formats[format]?.sizeMB ?? Infinity);
 	})[0].id;
 }
+/**
+* The single node-local authority for turning a CHOSEN model (or none) into a
+* concrete model that has a build for this node's engine `format`. Fuses the
+* two previously-duplicated decisions (orchestrator `pickDefaultModelId` +
+* provider `substituteIncompatibleModels`):
+*
+*   - chosen === null            → the addon's default model for `format`.
+*   - chosen is a catalog model  → keep it if it has a `format` build; else
+*                                  the addon's default model for `format`
+*                                  (a substitution — the caller surfaces it).
+*   - chosen is NOT in the catalog (custom/unknown) → returned unchanged; the
+*                                  operator owns a custom model's format compat.
+*   - unknown stepId             → chosen returned unchanged (never throws).
+*/
+function resolveModelForFormat(stepId, chosenModelId, format) {
+	let def;
+	try {
+		def = getStepDefinition(stepId);
+	} catch {
+		return chosenModelId ?? "";
+	}
+	if (chosenModelId === null) return getDefaultModelForFormat(stepId, format);
+	const entry = def.models.find((m) => m.id === chosenModelId);
+	if (!entry) return chosenModelId;
+	if (entry.formats[format]) return chosenModelId;
+	return getDefaultModelForFormat(stepId, format);
+}
 //#endregion
 //#region src/detection-pipeline/engine/engine-factory.ts
 var BACKEND_TO_POOL_RUNTIME = {
@@ -3928,12 +3999,15 @@ var PipelineExecutor = class {
 				try {
 					await this.executeChildren(rootStep.children, mutable, fullFrameJpegProvider, imageWidth, imageHeight, traceBuilder, stepTimings, ctx, poolAgg);
 				} catch (err) {
-					this.opts.logger?.warn("Pipeline child execution failed — keeping parent detection", { meta: {
-						rootStepId: rootStep.stepId,
-						parentClass: mutable.macroClass,
-						parentScore: mutable.score,
-						error: errMsg(err)
-					} });
+					this.opts.logger?.warn("Pipeline child execution failed — keeping parent detection", {
+						tags: { deviceId },
+						meta: {
+							rootStepId: rootStep.stepId,
+							parentClass: mutable.macroClass,
+							parentScore: mutable.score,
+							error: errMsg(err)
+						}
+					});
 				}
 				firstLevel.push(mutable);
 			}
@@ -4198,6 +4272,147 @@ function mergeCustomModels(staticModels, customModels) {
 	return merged;
 }
 //#endregion
+//#region src/detection-pipeline/step-resolution.ts
+/**
+* Walk `steps` (recursing into children) and return exactly the
+* substitutions in effect for `format` — one entry per step whose chosen
+* model differs from its resolved model. Pure and deterministic: the same
+* `(steps, format)` always yields the same result, with no entries left over
+* from a prior format. Callers that cache substitutions (e.g. for a status
+* surface) should REBUILD their cache from this result on every resolve
+* pass rather than merging into it, so a step that becomes compatible again
+* (chosen === resolved) is dropped instead of going stale.
+*/
+function collectSubstitutions(steps, format) {
+	const result = [];
+	for (const step of steps) {
+		const chosen = step.modelId;
+		if (chosen != null) {
+			const running = resolveModelForFormat(step.addonId, chosen, format);
+			if (running !== chosen) result.push({
+				addonId: step.addonId,
+				chosen,
+				running,
+				format
+			});
+		}
+		if (step.children?.length) result.push(...collectSubstitutions(step.children, format));
+	}
+	return result;
+}
+/**
+* Return one {@link ZeroBuildIssue} per step in `steps` whose catalog entry
+* (via `getStepDef`) has ZERO models with a build for `format`. `steps` is
+* expected to already be flattened + filtered to the set the caller cares
+* about (e.g. enabled video steps) — this does not recurse into children or
+* filter by `enabled`, unlike {@link collectSubstitutions}.
+*
+* `getStepDef` defaults to the real catalog lookup and is injectable so
+* tests can exercise the zero-build branch with a fabricated
+* `StepDefinition` — the real catalog currently has no step whose EVERY
+* model lacks a given format, so this branch is otherwise unreachable in a
+* black-box test. Unknown/custom addonIds (no registered `StepDefinition`)
+* are skipped, never thrown.
+*/
+function collectZeroBuildIssues(steps, format, getStepDef = getStepDefinition) {
+	const result = [];
+	for (const step of steps) {
+		let def;
+		try {
+			def = getStepDef(step.addonId);
+		} catch {
+			continue;
+		}
+		if (!def.models.some((m) => m.formats[format])) result.push({
+			addonId: step.addonId,
+			format
+		});
+	}
+	return result;
+}
+/**
+* Walk `steps` (recursing into children, mirroring {@link collectSubstitutions}'
+* recursion — every step in the tree is checked regardless of `enabled`) and
+* return one {@link UnknownAddonIssue} per addonId whose `getStepDef` lookup
+* throws. Pure, deterministic, never throws itself.
+*
+* `getStepDef` defaults to the real catalog lookup and is injectable so
+* tests can exercise the unknown-addon branch with a fabricated resolver
+* without `vi.mock`.
+*/
+function collectUnknownAddonIssues(steps, getStepDef = getStepDefinition) {
+	const result = [];
+	for (const step of steps) {
+		try {
+			getStepDef(step.addonId);
+		} catch {
+			result.push({ addonId: step.addonId });
+		}
+		if (step.children?.length) result.push(...collectUnknownAddonIssues(step.children, getStepDef));
+	}
+	return result;
+}
+/**
+* Enrich `PipelineStepInput[]` (the wire shape a camera pipeline sends) into
+* `PipelineDefaultStep[]` (the catalog-enriched shape the executor consumes),
+* resolving each step's model for `format` via `resolveModelForFormat`.
+*
+* Pure and side-effect-free — never throws. This is the seam behind the
+* LIVE per-camera dispatch path (`DetectionPipelineProvider.
+* inputStepsToPipelineSteps`), which runs once per decoded frame (up to
+* detectionFps × N cameras/sec): a bad step config referencing an unknown
+* `addonId` must never become a per-frame throw. Unknown addons are
+* dropped from the returned tree and reported in
+* `diagnostics.unknownAddonIds`; model substitutions are reported in
+* `diagnostics.substitutions` instead of happening silently. The caller
+* (the provider) owns logging + dedup for both.
+*/
+function resolveInputSteps(steps, format) {
+	const resolvedSteps = [];
+	const unknownAddonIds = [];
+	const substitutions = [];
+	for (const s of steps) {
+		let def;
+		try {
+			def = getStepDefinition(s.addonId);
+		} catch {
+			unknownAddonIds.push(s.addonId);
+			continue;
+		}
+		const chosenModelId = s.modelId ?? null;
+		const runningModelId = resolveModelForFormat(s.addonId, chosenModelId, format);
+		if (chosenModelId !== null && runningModelId !== chosenModelId) substitutions.push({
+			addonId: s.addonId,
+			chosen: chosenModelId,
+			running: runningModelId,
+			format
+		});
+		const childResult = s.children ? resolveInputSteps(s.children, format) : null;
+		if (childResult) {
+			unknownAddonIds.push(...childResult.diagnostics.unknownAddonIds);
+			substitutions.push(...childResult.diagnostics.substitutions);
+		}
+		resolvedSteps.push({
+			addonId: s.addonId,
+			addonName: def.name,
+			slot: def.slot,
+			inputClasses: def.inputClasses ?? [],
+			outputClasses: def.outputClasses,
+			enabled: s.enabled,
+			modelId: runningModelId,
+			children: childResult ? childResult.steps : [],
+			...s.settings ? { settings: { ...s.settings } } : {}
+		});
+	}
+	return {
+		steps: resolvedSteps,
+		diagnostics: {
+			unknownAddonIds,
+			substitutions
+		}
+	};
+}
+//#endregion
 //#region src/detection-pipeline/provider.ts
 /**
 * DetectionPipelineProvider — implements IPipelineExecutorProvider.
@@ -4494,6 +4709,15 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 	*/
 	lastStepsSignature = null;
 	/**
+	* Dedup guard for the live per-camera dispatch path
+	* (`inputStepsToPipelineSteps`) — an unknown-addon skip or a runtime
+	* model substitution logs ONCE per distinct signature instead of once
+	* per decoded frame (that method runs up to detectionFps × N cameras
+	* times/sec). Never cleared — it's a log-noise guard, not runtime
+	* state, and the key space (addonId/model combos) is small and stable.
+	*/
+	loggedLiveDispatchIssues = /* @__PURE__ */ new Set();
+	/**
 	* CB5 shm passthrough — the process-local, LONG-LIVED reader cache for
 	* `runPipeline({ frameHandle })`. Opens each named shm segment ONCE and
 	* reuses the mapping for every later handle on the same ring (never
@@ -4522,6 +4746,17 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 	*/
 	provisioner = null;
 	/**
+	* Gate A (config-correctness gate at engine change). Human-readable config
+	* issues — model substitutions and zero-build steps — for the CURRENT
+	* node-default tree against `this.currentEngine.format`. Recomputed
+	* EAGERLY by {@link recomputeConfigIssues} whenever the engine actually
+	* changes (see `onEngineSelectionChanged`), rather than relying on a
+	* `getGlobalSteps()` call that may never happen on a camera-only node.
+	* Merged into {@link getEngineProvisioning}'s snapshot; never consulted by
+	* `assertEngineReady` — this gate SURFACES, it does not block inference.
+	*/
+	configIssues = [];
+	/**
 	* True when `init()` found no persisted engine choice (first boot).
 	* `setApi()` reads this flag and auto-picks the best supported runtime
 	* using probe data (hardware + bestScore hint), persists the selection,
@@ -4768,7 +5003,8 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 		const stored = await this.loadEngine();
 		if (stored) this.currentEngine = stored;
 		else await this.resolveAutoEngine();
-		if ((prev.runtime !== this.currentEngine.runtime || prev.backend !== this.currentEngine.backend || prev.format !== this.currentEngine.format || (prev.device ?? "") !== (this.currentEngine.device ?? "")) && this.engineFactory) {
+		const engineChanged = prev.runtime !== this.currentEngine.runtime || prev.backend !== this.currentEngine.backend || prev.format !== this.currentEngine.format || (prev.device ?? "") !== (this.currentEngine.device ?? "");
+		if (engineChanged && this.engineFactory) {
 			this.log.info("engine selection changed — rebuilding pool in place", { meta: {
 				from: `${prev.backend}/${prev.device ?? "default"}`,
 				to: `${this.currentEngine.backend}/${this.currentEngine.device ?? "default"}`
@@ -4780,18 +5016,56 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 			this.executor = null;
 		}
 		this.startProvisioningForCurrentEngine();
+		if (engineChanged) await this.recomputeConfigIssues();
+	}
+	/**
+	* Gate A (config-correctness gate at engine change) — eagerly re-resolve
+	* the node-default step tree for `this.currentEngine.format` and compute
+	* human-readable config issues from the result:
+	*   - model substitutions (`getActiveModelSubstitutions()`, populated as a
+	*     side effect of the `getGlobalSteps()` re-resolve below) — a step's
+	*     chosen model lacks a build for this format, so the format default
+	*     runs instead (degraded but loadable).
+	*   - zero-build steps (`collectZeroBuildIssues`) — a step whose FULL
+	*     catalog has no model at all with a build for this format (not even
+	*     the format default is loadable).
+	*
+	* Never throws — this is an additive diagnostic surface, not an
+	* enforcement point (`assertEngineReady` still owns readiness). Any
+	* failure clears `configIssues` and logs a warning rather than
+	* propagating out of the engine-change path.
+	*/
+	async recomputeConfigIssues() {
+		this.configIssues = [];
+		try {
+			const steps = await this.getGlobalSteps();
+			if (!steps) return;
+			const format = this.currentEngine.format;
+			const substitutionIssues = this.getActiveModelSubstitutions().map((s) => `${s.addonId}: chose ${s.chosen}, running ${s.running} (${s.format})`);
+			const zeroBuildIssues = collectZeroBuildIssues(flattenSteps(steps), format).map((i) => `${i.addonId}: no model has a ${i.format} build`);
+			this.configIssues = [...substitutionIssues, ...zeroBuildIssues];
+		} catch (err) {
+			this.configIssues = [];
+			this.log.warn("engine-change config gate failed — no config issues surfaced", { meta: { error: errMsg(err) } });
+		}
 	}
 	/**
 	* Per-node engine-provisioning snapshot. The cap routes `{ nodeId }` for
 	* provider resolution only (the router strips it); each node returns its
-	* own local machine state. Cold (pre-`setApi`) provider → `idle`.
+	* own local machine state. Cold (pre-`setApi`) provider → `idle`. Merges
+	* in Gate A's `configIssues` (see {@link recomputeConfigIssues}) when
+	* non-empty — additive, never overrides the provisioner's own fields.
 	*/
 	getEngineProvisioning() {
-		return this.provisioner?.state ?? {
+		const base = this.provisioner?.state ?? {
 			runtimeId: null,
 			device: null,
 			state: "idle"
 		};
+		return this.configIssues.length ? {
+			...base,
+			configIssues: [...this.configIssues]
+		} : base;
 	}
 	/**
 	* Inference gate. Rejects with the current phase/error unless the engine
@@ -4990,43 +5264,45 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 		return buildDefaultStepTree(engine.format);
 	}
 	/**
-	* Substitute, AT RUNTIME ONLY (never persisted), any step whose configured
-	* model lacks a build for that step's active engine format. A GLOBAL pipeline
-	* config can pin a model that's valid on the cluster's Intel nodes (e.g. the
-	* OpenVINO-only `yolov9t-int8`) but impossible on a CoreML/ONNX node — without
-	* this the node crash-loops `Model "X" has no <format> format`. The operator's
-	* choice stays in the persisted config; this node just runs the smallest
-	* catalog model that DOES have its format. Mirrors the per-node engine
-	* fallback in `loadEngine`. Catalog models only — a custom model that lacks
-	* the format is left as-is (operator's responsibility).
+	* Resolve every step's model for this node's engine format via the shared
+	* `resolveModelForFormat`, and surface any substitution. `step.engine?.format`
+	* is gone — `this.currentEngine.format` is the only format source (engine is
+	* node-local).
+	*
+	* Rebuilds `modelSubstitutions` from scratch (via {@link collectSubstitutions})
+	* on every call, from the FULL tree being resolved, so the map always
+	* reflects EXACTLY the substitutions in effect for the current tree+format —
+	* a step whose chosen model becomes compatible again (e.g. after the
+	* operator switches the engine to a format it supports) is cleared here
+	* instead of leaking a stale "chose X → running Y" entry.
 	*/
-	substituteIncompatibleModels(steps) {
-		const fix = (step) => {
-			const format = step.engine?.format ?? this.currentEngine.format;
-			let modelId = step.modelId;
-			try {
-				const entry = getStepDefinition(step.addonId).models.find((m) => m.id === step.modelId);
-				if (entry && !entry.formats[format]) {
-					const fallback = getDefaultModelForFormat(step.addonId, format);
-					if (fallback !== step.modelId) {
-						this.log.info("Step model lacks engine format — substituting format default (runtime)", { meta: {
-							step: step.addonId,
-							configured: step.modelId,
-							substitute: fallback,
-							format
-						} });
-						modelId = fallback;
-					}
-				}
-			} catch {}
-			const children = step.children?.length ? step.children.map(fix) : step.children;
-			return modelId === step.modelId && children === step.children ? step : {
+	resolveStepModels(steps) {
+		const format = this.currentEngine.format;
+		const substitutions = collectSubstitutions(steps, format);
+		this.modelSubstitutions = new Map(substitutions.map((s) => [s.addonId, s]));
+		for (const s of substitutions) this.log.info("Step model lacks engine format — running format default (node-local)", { meta: {
+			step: s.addonId,
+			chosen: s.chosen,
+			running: s.running,
+			format: s.format
+		} });
+		return this.resolveStepModelTree(steps, format);
+	}
+	/** Pure recursive resolver — builds the resolved step tree without touching `modelSubstitutions`. */
+	resolveStepModelTree(steps, format) {
+		return steps.map((step) => {
+			const resolved = resolveModelForFormat(step.addonId, step.modelId ?? null, format);
+			const children = step.children?.length ? this.resolveStepModelTree([...step.children], format) : step.children;
+			return resolved === step.modelId && children === step.children ? step : {
 				...step,
-				modelId,
+				modelId: resolved,
 				...children ? { children } : {}
 			};
-		};
-		return steps.map(fix);
+		});
+	}
+	modelSubstitutions = /* @__PURE__ */ new Map();
+	getActiveModelSubstitutions() {
+		return [...this.modelSubstitutions.values()];
 	}
 	async getGlobalSteps() {
 		if (this.currentSteps) return this.currentSteps;
@@ -5034,7 +5310,7 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 		if (!raw) {
 			const defaults = buildDefaultStepTree(this.currentEngine.format);
 			if (defaults.length === 0) return null;
-			this.currentSteps = this.substituteIncompatibleModels(defaults);
+			this.currentSteps = this.resolveStepModels(defaults);
 			this.writeStore({ [KEY_STEPS]: JSON.stringify(defaults) });
 			this.log.info("Bootstrapped default pipeline — object-detection + face + plate recognition enabled by default", { meta: { rootSteps: defaults.length } });
 			return this.currentSteps;
@@ -5047,15 +5323,6 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 				const audioDef = getStepDefinition("audio-classifier");
 				if (audioDef.models.some((m) => m.formats[format])) {
 					const modelId = getDefaultModelForFormat("audio-classifier", format);
-					const audioEngine = modelId === "apple-soundanalysis" ? {
-						runtime: "python",
-						backend: "coreml",
-						format: "coreml"
-					} : {
-						runtime: "python",
-						backend: "cpu",
-						format: "onnx"
-					};
 					const audioStep = {
 						addonId: audioDef.id,
 						addonName: audioDef.name,
@@ -5064,15 +5331,14 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 						outputClasses: audioDef.outputClasses,
 						enabled: true,
 						modelId,
-						children: [],
-						engine: audioEngine
+						children: []
 					};
 					steps = [...steps, audioStep];
 					this.writeStore({ [KEY_STEPS]: JSON.stringify(steps) });
 					this.log.info("Migration: added audio-classifier step to persisted pipeline config");
 				}
 			}
-			this.currentSteps = this.substituteIncompatibleModels(steps);
+			this.currentSteps = this.resolveStepModels(steps);
 			return this.currentSteps;
 		} catch {
 			throw new Error(`Failed to parse persisted pipeline steps: corrupt data in key "${KEY_STEPS}"`);
@@ -5082,6 +5348,128 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 		if (!this.currentSteps) return null;
 		return stepsToPipelineConfig(this.currentSteps, this.currentEngine);
 	}
+	/**
+	* Task G5 (Gate B) — pre-init config-correctness gate. PURE COMPUTE
+	* against `this.currentEngine.format`: resolves `steps` the same way the
+	* runtime dispatch path (`resolveInputSteps`) would and reports what
+	* WOULD happen, without touching `this.modelSubstitutions` (that node-
+	* global map stays the exclusive property of `resolveStepModels`, the
+	* node-default tree resolver — writing it here would race two
+	* independent callers over the same field). Called by the orchestrator
+	* at attach time, node-pinned to the target node.
+	*
+	* Composes three pure helpers from `step-resolution.ts`, ALL scoped to
+	* ENABLED steps only (a disabled step's subtree — and any unknown addonId
+	* or incompatible model inside it — contributes NO issue and NO
+	* substitution; it will never execute, so flagging it is false-positive
+	* noise):
+	*   - `collectSubstitutions`  → `substitutions` (informational, never
+	*     affects `ok`).
+	*   - `collectUnknownAddonIssues` → `unknown-addon` HARD issues.
+	*   - `collectZeroBuildIssues` (over the enabled, non-audio-classifier
+	*     subset — mirrors Gate A's `flattenSteps`/`flattenEnabledVideoSteps`
+	*     filter, since audio backends are validated by audio-analyzer, not
+	*     against this node's VIDEO engine format) → `no-format-build` HARD
+	*     issues.
+	*
+	* `collectSubstitutions` and `collectUnknownAddonIssues` recurse into
+	* `children` themselves, so the enabled-scoping is applied ONCE up front
+	* via {@link pruneToEnabledSteps} (which drops a disabled step's whole
+	* subtree) rather than re-implemented inside each collector.
+	*
+	* Never throws — any unexpected failure degrades to a clean `ok: true`
+	* result with a warning logged, same posture as `recomputeConfigIssues`.
+	*/
+	async validatePipeline(input) {
+		const format = this.currentEngine.format;
+		try {
+			const steps = input.steps;
+			const enabledSteps = this.pruneToEnabledSteps(steps);
+			const substitutions = collectSubstitutions(enabledSteps, format);
+			const unknownAddonIssues = collectUnknownAddonIssues(enabledSteps);
+			const zeroBuildIssues = collectZeroBuildIssues(this.flattenEnabledVideoStepInputs(steps), format);
+			const issues = [...unknownAddonIssues.map((u) => ({
+				addonId: u.addonId,
+				kind: "unknown-addon",
+				detail: `${u.addonId}: no registered step definition`
+			})), ...zeroBuildIssues.map((z) => ({
+				addonId: z.addonId,
+				kind: "no-format-build",
+				detail: `${z.addonId}: no model has a ${z.format} build`
+			}))];
+			return {
+				ok: issues.length === 0,
+				issues,
+				substitutions,
+				format
+			};
+		} catch (err) {
+			this.log.warn("validatePipeline failed — reporting a clean result", { meta: { error: errMsg(err) } });
+			return {
+				ok: true,
+				issues: [],
+				substitutions: [],
+				format
+			};
+		}
+	}
+	/**
+	* Prune `steps` to ENABLED steps only, recursing into ENABLED children —
+	* a disabled step's whole subtree is dropped, never partially kept. This
+	* is the enabled-only tree shape `collectSubstitutions` and
+	* `collectUnknownAddonIssues` need in {@link validatePipeline}: both
+	* recurse into `children` themselves (unlike `flattenEnabledVideoStepInputs`,
+	* which flattens AND excludes `audio-classifier`), so pruning once up
+	* front — without touching the audio/video split — is enough to make
+	* Gate B's three checks agree on scope. Pure; returns the original array
+	* reference when nothing changed.
+	*/
+	pruneToEnabledSteps(steps) {
+		const result = [];
+		let changed = false;
+		for (const step of steps) {
+			if (!step.enabled) {
+				changed = true;
+				continue;
+			}
+			const prunedChildren = step.children?.length ? this.pruneToEnabledSteps(step.children) : step.children;
+			if (prunedChildren !== step.children) {
+				changed = true;
+				result.push({
+					...step,
+					children: prunedChildren
+				});
+			} else result.push(step);
+		}
+		return changed ? result : steps;
+	}
+	/**
+	* Flatten `steps` (recursing into ENABLED children only — a disabled
+	* step's subtree is skipped entirely, mirroring
+	* `flattenEnabledVideoSteps`) into `{addonId}` entries, excluding
+	* `audio-classifier` steps: Gate B validates the VIDEO engine format
+	* (`this.currentEngine.format`) only — audio backends resolve their own
+	* format independently and are validated by the audio-analyzer addon.
+	* An addonId whose `StepDefinition` lookup throws is skipped here (it is
+	* already reported separately by `collectUnknownAddonIssues`).
+	*/
+	flattenEnabledVideoStepInputs(steps) {
+		const result = [];
+		const walk = (nodes) => {
+			for (const step of nodes) {
+				if (!step.enabled) continue;
+				try {
+					if (getStepDefinition(step.addonId).slot === "audio-classifier") continue;
+				} catch {
+					continue;
+				}
+				result.push({ addonId: step.addonId });
+				if (step.children?.length) walk(step.children);
+			}
+		};
+		walk(steps);
+		return result;
+	}
 	async getSelectedEngine() {
 		return this.currentEngine;
 	}
@@ -5094,7 +5482,7 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 		const addons = ALL_PIPELINE_STEPS.map((s) => ({
 			id: s.definition.id,
 			name: s.definition.name,
-			models: s.definition.models.map((m) => {
+			models: s.definition.models.filter((m) => m.legacy !== true).map((m) => {
 				const formats = {};
 				for (const [formatKey, entry] of Object.entries(m.formats)) {
 					if (!entry) continue;
@@ -5408,7 +5796,8 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 			emit(`Image: ${imageWidth}×${imageHeight}`);
 		}
 		decodeMs = performance.now() - decodeT0;
-		const benchmarkSteps = this.inputStepsToPipelineSteps(input.steps);
+		const resolveFormat = input.engine?.format ?? this.currentEngine.format;
+		const benchmarkSteps = this.inputStepsToPipelineSteps(input.steps, resolveFormat);
 		const stepsSignature = JSON.stringify(benchmarkSteps.map((s) => ({
 			id: s.addonId,
 			settings: s.settings ?? {}
@@ -5697,22 +6086,46 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 			this.log.warn("Override cache dispose failed", { meta: { error: err instanceof Error ? err.message : String(err) } });
 		}
 	}
-	/** Convert PipelineStepInput[] → PipelineDefaultStep[] by enriching from StepDefinitions */
-	inputStepsToPipelineSteps(steps) {
-		return steps.map((s) => {
-			const def = getStepDefinition(s.addonId);
-			return {
-				addonId: s.addonId,
-				addonName: def.name,
-				slot: def.slot,
-				inputClasses: def.inputClasses ?? [],
-				outputClasses: def.outputClasses,
-				enabled: s.enabled,
-				modelId: s.modelId,
-				children: s.children ? this.inputStepsToPipelineSteps(s.children) : [],
-				...s.settings ? { settings: { ...s.settings } } : {}
-			};
-		});
+	/**
+	* Convert PipelineStepInput[] → PipelineDefaultStep[] by enriching from
+	* StepDefinitions. This is the LIVE per-camera dispatch path — it runs
+	* once per decoded frame (up to detectionFps × N cameras/sec) — so it
+	* must NEVER throw. A thin adapter over the pure {@link resolveInputSteps}
+	* seam: an unknown `addonId` (a bad step config sent by a camera
+	* pipeline) is dropped from the tree and logged once (deduped, not
+	* per-frame) at warn level instead of propagating as a per-frame error
+	* loop. A runtime model substitution (the step's explicit model lacks a
+	* build for this node's engine format, so the format default runs
+	* instead) is logged once (deduped) at info level so an operator can see
+	* a camera×node model swap instead of it happening silently. Does NOT
+	* write `this.modelSubstitutions` — that map is owned exclusively by
+	* `resolveStepModels` (see its doc comment); a second writer here would
+	* corrupt it.
+	*
+	* `format` defaults to `this.currentEngine.format` (the LIVE per-camera
+	* dispatch path never passes it explicitly). Benchmark call sites with a
+	* per-run engine override (`input.engine`) MUST pass the override's format
+	* explicitly — `this.currentEngine` only gets swapped to the override
+	* LATER in `runPipeline`/`runPipelineBatch`, so relying on the default here
+	* would resolve models against the node's persisted format instead of the
+	* format actually being benchmarked.
+	*/
+	inputStepsToPipelineSteps(steps, format = this.currentEngine.format) {
+		const { steps: resolvedSteps, diagnostics } = resolveInputSteps(steps, format);
+		for (const addonId of diagnostics.unknownAddonIds) this.logLiveDispatchIssueOnce(`unknown:${addonId}`, () => this.log.warn("Live pipeline step references an unknown addon — dropping step", { meta: { addonId } }));
+		for (const sub of diagnostics.substitutions) this.logLiveDispatchIssueOnce(`${sub.addonId}|${sub.chosen}|${sub.running}|${sub.format}`, () => this.log.info("Live pipeline step model substituted for engine format (node-local)", { meta: {
+			step: sub.addonId,
+			chosen: sub.chosen,
+			running: sub.running,
+			format: sub.format
+		} }));
+		return resolvedSteps;
+	}
+	/** Run `fn()` at most once per `key` for the lifetime of this provider instance. */
+	logLiveDispatchIssueOnce(key, fn) {
+		if (this.loggedLiveDispatchIssues.has(key)) return;
+		this.loggedLiveDispatchIssues.add(key);
+		fn();
 	}
 	/**
 	* Single-flight gate around `ensureModelsForSteps`. Concurrent
@@ -5918,7 +6331,8 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 	}
 	async runPipelineBatchImpl(input) {
 		if (input.frames.length === 0) return { results: [] };
-		const benchmarkSteps = this.inputStepsToPipelineSteps(input.steps);
+		const resolveFormat = input.engine?.format ?? this.currentEngine.format;
+		const benchmarkSteps = this.inputStepsToPipelineSteps(input.steps, resolveFormat);
 		const enabledSteps = flattenEnabledVideoSteps(benchmarkSteps);
 		if (enabledSteps.length === 0) throw new Error("runPipelineBatch: no enabled steps");
 		const rootStep = enabledSteps[0];
@@ -6610,7 +7024,7 @@ function buildSchemaSlots(format, modelsDir, customByStep) {
 	const slotMap = /* @__PURE__ */ new Map();
 	for (const pipelineStep of ALL_PIPELINE_STEPS) {
 		const step = pipelineStep.definition;
-		const availableModels = mergeCustomModels(step.models, customByStep?.get(step.id) ?? []).filter((m) => m.formats[format]);
+		const availableModels = mergeCustomModels(step.models, customByStep?.get(step.id) ?? []).filter((m) => m.formats[format] && m.legacy !== true);
 		if (availableModels.length === 0) continue;
 		const slot = step.slot;
 		if (!slotMap.has(slot)) slotMap.set(slot, []);
@@ -6628,7 +7042,9 @@ function buildSchemaSlots(format, modelsDir, customByStep) {
 				formats: Object.fromEntries(Object.entries(m.formats).map(([f, entry]) => [f, {
 					downloaded: isModelDownloaded(modelsDir, m, f),
 					sizeMB: entry.sizeMB
-				}]))
+				}])),
+				...m.group ? { group: m.group } : {},
+				...m.legacy !== void 0 ? { legacy: m.legacy } : {}
 			})),
 			defaultModelId: step.defaultModelId,
 			...step.defaultModelIdByFormat ? { defaultModelIdByFormat: { ...step.defaultModelIdByFormat } } : {},
@@ -6717,23 +7133,10 @@ function buildDefaultStepTree(format) {
 		makeStep("vehicle-classifier", [], { enabled: false }),
 		makeStep("segmentation", [], { enabled: false })
 	].filter((s) => s !== null));
-	const audioEngine = getDefaultModelForFormat("audio-classifier", format) === "apple-soundanalysis" ? {
-		runtime: "python",
-		backend: "coreml",
-		format: "coreml"
-	} : {
-		runtime: "python",
-		backend: "cpu",
-		format: "onnx"
-	};
 	const audioStep = makeStep("audio-classifier", []);
-	const audioClassifier = audioStep ? {
-		...audioStep,
-		engine: audioEngine
-	} : null;
 	const steps = [];
 	if (root) steps.push(root);
-	if (audioClassifier) steps.push(audioClassifier);
+	if (audioStep) steps.push(audioStep);
 	return steps;
 }
 function stepsToPipelineConfig(steps, engine) {
@@ -6753,7 +7156,7 @@ function stepsToPipelineConfig(steps, engine) {
 		video: videoSteps.map(toNode),
 		...audioStep ? {
 			audio: toNode(audioStep),
-			audioEngine: audioStep.engine ?? engine
+			audioEngine: engine
 		} : {}
 	};
 }
@@ -6885,7 +7288,8 @@ var DEFAULT_CONFIG = {
 	engineBackend: "auto",
 	engineDevice: "cpu",
 	probedBestEngine: "",
-	activeEngine: ""
+	activeEngine: "",
+	activeModelSubstitutions: ""
 };
 /** Derive the model-format from a backend value. Called by the provider. */
 function backendToFormat(backend) {
@@ -7006,6 +7410,18 @@ var DetectionPipelineAddon = class DetectionPipelineAddon extends BaseAddon {
 					readonlyField: true,
 					default: ""
 				}),
+				this.field({
+					type: "text",
+					key: "activeModelSubstitutions",
+					label: "Model substitutions",
+					description: "Node-local model substitutions currently in effect: a step's chosen model has no build for this node's engine format, so a compatible default is running instead (format: \"step: chosen→running\"). Hidden when every step matches.",
+					readonlyField: true,
+					default: "",
+					showWhen: {
+						field: "activeModelSubstitutions",
+						notEquals: ""
+					}
+				}),
 				this.field({
 					type: "select",
 					key: "engineBackend",
@@ -7175,12 +7591,15 @@ var DetectionPipelineAddon = class DetectionPipelineAddon extends BaseAddon {
 		const device = deviceOptions.find((d) => d.value === storedDevice)?.value ?? defaultDeviceFor(backend);
 		const prov = targetNode === this.localNodeId() ? this.provider?.getEngineProvisioning() : void 0;
 		const activeEngine = prov && prov.runtimeId ? `${prov.runtimeId}/${prov.device ?? "default"} (${prov.state})` : "";
+		const substitutions = this.provider?.getActiveModelSubstitutions() ?? [];
+		const activeModelSubstitutions = substitutions.length === 0 ? "" : substitutions.map((s) => `${s.addonId}: ${s.chosen}→${s.running}`).join(", ");
 		const displayBackend = isAuto ? "auto" : backend;
 		const raw = {
 			...merged,
 			engineBackend: displayBackend,
 			engineDevice: device,
-			activeEngine
+			activeEngine,
+			activeModelSubstitutions
 		};
 		const schema = this.globalSettingsSchema();
 		if (!schema) return { sections: [] };
@@ -7444,7 +7863,7 @@ var DetectionPipelineAddon = class DetectionPipelineAddon extends BaseAddon {
 		}).catch(() => {});
 	}
 	getModelCatalog() {
-		return ALL_STEPS.flatMap((s) => [...s.models]);
+		return ALL_STEPS.flatMap((s) => s.models.filter((m) => m.legacy !== true));
 	}
 	/**
 	* Proactively install the OpenVINO Python package when Intel hardware