@camstack/addon-pipeline 1.2.296 → 1.2.297

package/dist/detection-pipeline/index.mjs

@@ -1,9 +1,9 @@
 import { n as __require } from "../chunk-DnnnRqeS.mjs";
-import { At as pickClusterStepSettings, Cn as parseJsonUnknown, Dt as overlayClusterStepSettings, En as sleep, Gt as resolvePoolMemoryPolicy, H as YAMNET_TO_MACRO, Ln as string, Mt as pickInvalidClusterStepModels, On as array, Pn as object, Pt as pipelineExecutorCapability, Qt as supportedRuntimes$1, Rn as union, Sn as nodePin, Vt as resolveClusterStepModelId, cn as BaseAddon, et as defaultDeviceFor$1, gt as inferModelProvider, it as detectionPipelineCapability, j as PoolMemoryWatchdog, kt as pickClusterStepModels, lt as evaluateZoneRules, m as DEFAULT_CLUSTER_STEP_SETTINGS, mn as createEvent, p as DEFAULT_CLUSTER_STEP_MODELS, qt as runtimeDevices$1, st as enumerateInferenceDevices, t as APPLE_SA_TO_MACRO, tn as errMsg, vn as hydrateSchema, vt as loadContributionCapability, y as DEVICE_BACKEND_TO_FORMAT, zn as EventCategory } from "../dist-CCd0Q3nr.mjs";
-import { s as readProcessCost } from "../node-DgMSXSWP.mjs";
-import { a as localFrameRegistry, c as ALL_STEPS, d as getStepDefinition, f as resolveModelForFormat, l as getDefaultModelForFormat, m as landmarkPrecisionVerdict, n as resolveDefaultDetectionModel, r as macroGateVerdict, s as ALL_PIPELINE_STEPS, u as getStep } from "../default-detection-model-Co578D8C.mjs";
+import { Dn as array, Dt as overlayClusterStepSettings, Gt as runtimeDevices$1, H as YAMNET_TO_MACRO, In as string, Kt as stepModelRunsOnFormat, Ln as union, Mt as pipelineExecutorCapability, Nn as object, Rn as EventCategory, Sn as parseJsonUnknown, Tn as sleep, Ut as resolvePoolMemoryPolicy, Zt as supportedRuntimes$1, _n as hydrateSchema, en as errMsg, et as defaultDeviceFor$1, it as detectionPipelineCapability, j as PoolMemoryWatchdog, kt as pickClusterStepSettings, lt as evaluateZoneRules, m as DEFAULT_CLUSTER_STEP_SETTINGS, pn as createEvent, sn as BaseAddon, st as enumerateInferenceDevices, t as APPLE_SA_TO_MACRO, u as CLUSTER_MODEL_SCOPED_STEPS, vt as loadContributionCapability, xn as nodePin, y as DEVICE_BACKEND_TO_FORMAT, zt as resolveClusterStepModelId } from "../dist-CxHIpsQs.mjs";
+import { s as readProcessCost } from "../node-DyeWu78a.mjs";
+import { _ as resolveModelForFormat, a as buildSubtreeCanRun, c as macroGateVerdict, f as ALL_PIPELINE_STEPS, g as getStepDefinition, h as getStep, i as mergeCustomModels, m as getDefaultModelForFormat, n as resolveDefaultDetectionModel, p as ALL_STEPS, r as CustomModelCatalog, u as localFrameRegistry, y as landmarkPrecisionVerdict } from "../default-detection-model-D6DypCkI.mjs";
 import { t as getSharp } from "../lazy-sharp-DXsqwpph.mjs";
-import { n as pickNodePlatformArch, t as readProcessMemory } from "../process-memory-DFC_O5zE.mjs";
+import { n as pickNodePlatformArch, t as readProcessMemory } from "../process-memory-BVR4592X.mjs";
 import * as os from "node:os";
 import * as fs from "node:fs";
 import * as path$1 from "node:path";
@@ -360,12 +360,14 @@ function normalizeEngineNodeId(rawNodeId) {
 * builders eventually reaches ten of them, and the cameras attached by the
 * forgotten one quietly write a foreign feature space into the shared index.
 *
-* ## Why the failure mode keeps the last value
+* ## Why the failure mode keeps the last value — and refuses before the first
 *
 * A failed read must never revert to the registry default MID-PASS: that would
 * silently change what every remaining vector of that dispatch means, which is
 * the exact class of harm the scope exists to prevent. So a failure keeps the
-* last known row and says so, loudly, once per failure.
+* last known row and says so, once per change. Before the FIRST answer there is
+* no row to keep: the step is refused by name (D658) — a default run then made
+* the default model the pool's active variant for the process lifetime.
 */
 /**
 * The addon whose GLOBAL settings own the cluster row. Same owner as the crop
@@ -374,35 +376,58 @@ function normalizeEngineNodeId(rawNodeId) {
 * enforces it live — neither should own a value the other depends on).
 */
 var CLUSTER_MODEL_OWNER_ADDON_ID = "pipeline-orchestrator";
-/** TTL-cached read of the cluster model row. */
+/**
+* TTL-cached read of the cluster model row.
+*
+* A step's model is KNOWN only once the owner has answered for it (`stored` or
+* `absent`). Until then it is UNKNOWN, and a cluster-scoped step is refused by
+* name rather than run with the registry default (D49, D658): a default run
+* during the owner's boot window made that model the pool's active variant for
+* the whole process, and the face default was ArcFace until D651. Once known,
+* an unanswered read keeps the LAST KNOWN model — never reverts to a default.
+*/
 var ClusterModelSource = class {
-	models = DEFAULT_CLUSTER_STEP_MODELS;
+	models = {};
+	unknown = new Map(CLUSTER_MODEL_SCOPED_STEPS.map((s) => [s.stepId, "not-yet-asked"]));
 	settings = DEFAULT_CLUSTER_STEP_SETTINGS;
 	lastReadAtMs = Number.NEGATIVE_INFINITY;
 	inFlight = null;
 	logger;
 	now;
 	ttlMs;
+	unknownRetryMs;
+	/** The last "not known" state logged, so it is said once per change. */
+	lastUnknownLogKey = "";
 	constructor(options) {
 		this.logger = options.logger;
 		this.now = options.now ?? (() => Date.now());
 		this.ttlMs = options.ttlMs ?? 6e4;
+		this.unknownRetryMs = options.unknownRetryMs ?? 5e3;
 	}
-	/** The row in force right now — the registry defaults until a read lands. */
+	/**
+	* The KNOWN models, `stepId → modelId`. A step absent here is unknown (see
+	* {@link unknownSteps}) and must be refused, never defaulted.
+	*/
 	current() {
 		return this.models;
 	}
+	/** Cluster-scoped steps whose model the owner has not answered yet, with why. */
+	unknownSteps() {
+		return this.unknown;
+	}
 	/** Cluster-scoped step knobs in force right now (admission floors, …). */
 	currentSettings() {
 		return this.settings;
 	}
 	/**
-	* Re-read if the cached row has expired. Concurrent callers share one
-	* in-flight read; a failure keeps the LAST KNOWN row.
+	* Re-read if the cached row has expired (sooner while a step is unknown).
+	* Concurrent callers share one in-flight read; a failure keeps the LAST
+	* KNOWN row.
 	*/
 	async refresh(api) {
 		if (api === void 0) return this.models;
-		if (this.now() - this.lastReadAtMs < this.ttlMs) return this.models;
+		const ttl = this.unknown.size > 0 ? Math.min(this.ttlMs, this.unknownRetryMs) : this.ttlMs;
+		if (this.now() - this.lastReadAtMs < ttl) return this.models;
 		this.inFlight ??= this.read(api).finally(() => {
 			this.inFlight = null;
 		});
@@ -410,44 +435,186 @@ var ClusterModelSource = class {
 		return this.models;
 	}
 	async read(api) {
-		try {
-			const view = await api.addonSettings.getGlobalSettings.query({ addonId: CLUSTER_MODEL_OWNER_ADDON_ID });
-			const next = pickClusterStepModels(view);
-			const nextSettings = pickClusterStepSettings(view);
-			this.lastReadAtMs = this.now();
-			const invalid = pickInvalidClusterStepModels(view);
-			if (invalid.length > 0) this.logger.warn("cluster step model row holds a value that is not a model id — running the catalog default for that step; no re-embed pass will run on it", { meta: {
-				owner: CLUSTER_MODEL_OWNER_ADDON_ID,
-				invalid,
-				inUse: Object.fromEntries(invalid.map((e) => [e.stepId, next[e.stepId]]))
-			} });
-			const changed = Object.keys(next).filter((stepId) => next[stepId] !== this.models[stepId]);
-			const settingsChanged = Object.keys(nextSettings).some((stepId) => {
-				const from = this.settings[stepId] ?? {};
-				const to = nextSettings[stepId] ?? {};
-				return [...new Set([...Object.keys(from), ...Object.keys(to)])].some((key) => from[key] !== to[key]);
-			});
-			if (changed.length > 0) {
-				this.logger.info("cluster step model changed — vectors already stored by the previous model need a re-embed pass", { meta: { changed: changed.map((stepId) => ({
-					stepId,
-					from: this.models[stepId],
-					to: next[stepId]
-				})) } });
-				this.models = next;
-			}
-			if (settingsChanged) {
-				this.logger.info("cluster step settings changed", { meta: {
-					from: { ...this.settings },
-					to: { ...nextSettings }
-				} });
-				this.settings = nextSettings;
+		this.lastReadAtMs = this.now();
+		await Promise.all([this.readModels(api), this.readSettings(api)]);
+	}
+	async readModels(api) {
+		const answers = await Promise.all(CLUSTER_MODEL_SCOPED_STEPS.map(async (step) => ({
+			stepId: step.stepId,
+			answer: await askOwner(api, step.stepId)
+		})));
+		const nextModels = { ...this.models };
+		const nextUnknown = /* @__PURE__ */ new Map();
+		const unanswered = [];
+		for (const { stepId, answer } of answers) {
+			if (answer.kind === "model") {
+				nextModels[stepId] = answer.modelId;
+				continue;
 			}
+			const keeping = this.models[stepId] ?? null;
+			unanswered.push({
+				stepId,
+				reason: answer.reason,
+				keeping
+			});
+			if (keeping === null) nextUnknown.set(stepId, answer.reason);
+		}
+		const changed = Object.keys(nextModels).filter((stepId) => this.models[stepId] !== void 0 && nextModels[stepId] !== this.models[stepId]);
+		if (changed.length > 0) this.logger.info("cluster step model changed — vectors already stored by the previous model need a re-embed pass", { meta: { changed: changed.map((stepId) => ({
+			stepId,
+			from: this.models[stepId],
+			to: nextModels[stepId]
+		})) } });
+		const learned = Object.keys(nextModels).filter((stepId) => this.models[stepId] === void 0);
+		if (learned.length > 0) this.logger.info("cluster step model known — cluster-scoped steps run it", { meta: { known: Object.fromEntries(learned.map((id) => [id, nextModels[id]])) } });
+		this.models = nextModels;
+		this.unknown = nextUnknown;
+		this.reportUnanswered(unanswered);
+	}
+	/** Once per change of the unanswered set — never once per retry. */
+	reportUnanswered(unanswered) {
+		const key = JSON.stringify(unanswered);
+		if (key === this.lastUnknownLogKey) return;
+		this.lastUnknownLogKey = key;
+		if (unanswered.length === 0) return;
+		this.logger.warn("cluster step model not answered by its owner — a step never known is REFUSED, a known one keeps its last model", { meta: {
+			owner: CLUSTER_MODEL_OWNER_ADDON_ID,
+			unanswered: unanswered.map((u) => ({
+				stepId: u.stepId,
+				reason: u.reason,
+				...u.keeping !== null ? { keeping: u.keeping } : { refused: true }
+			}))
+		} });
+	}
+	async readSettings(api) {
+		let view;
+		try {
+			view = await api.addonSettings.getGlobalSettings.query({ addonId: CLUSTER_MODEL_OWNER_ADDON_ID });
 		} catch (err) {
-			this.logger.warn("cluster step model read failed — keeping the last known row", { meta: {
+			this.logger.warn("cluster step settings read failed — keeping the last known knobs", { meta: {
 				owner: CLUSTER_MODEL_OWNER_ADDON_ID,
-				inUse: { ...this.models },
 				error: err instanceof Error ? err.message : String(err)
 			} });
+			return;
+		}
+		if (view === null) return;
+		const nextSettings = pickClusterStepSettings(view);
+		if (Object.keys(nextSettings).some((stepId) => {
+			const from = this.settings[stepId] ?? {};
+			const to = nextSettings[stepId] ?? {};
+			return [...new Set([...Object.keys(from), ...Object.keys(to)])].some((key) => from[key] !== to[key]);
+		})) {
+			this.logger.info("cluster step settings changed", { meta: {
+				from: { ...this.settings },
+				to: { ...nextSettings }
+			} });
+			this.settings = nextSettings;
+		}
+	}
+};
+/** One step's model from the owner's three-way answer; a throw is no answer. */
+async function askOwner(api, stepId) {
+	try {
+		const choice = await api.pipelineOrchestrator.getClusterModelChoice.query({ stepId });
+		switch (choice.kind) {
+			case "stored": return {
+				kind: "model",
+				modelId: choice.modelId
+			};
+			case "absent": return {
+				kind: "model",
+				modelId: choice.defaultModelId
+			};
+			case "unreadable": return {
+				kind: "none",
+				reason: choice.reason
+			};
+		}
+	} catch (err) {
+		return {
+			kind: "none",
+			reason: `read-failed: ${err instanceof Error ? err.message : String(err)}`
+		};
+	}
+}
+//#endregion
+//#region src/detection-pipeline/cluster-model-switch-log.ts
+function* clusterScopedSteps(steps) {
+	for (const step of steps) {
+		if (step.definition.modelScope === "cluster") yield step;
+		yield* clusterScopedSteps(step.children);
+	}
+}
+var ClusterModelSwitchLog = class {
+	logger;
+	/** `deviceId|stepId` → the model that step last ran for that camera. */
+	lastRun = /* @__PURE__ */ new Map();
+	constructor(logger) {
+		this.logger = logger;
+	}
+	/** Record what `tree` runs for `deviceId`; say so when a cluster step changed model. */
+	note(deviceId, tree) {
+		if (deviceId <= 0) return;
+		for (const step of clusterScopedSteps(tree.roots)) {
+			const key = `${String(deviceId)}|${step.stepId}`;
+			const previous = this.lastRun.get(key);
+			if (previous === step.modelId) continue;
+			this.lastRun.set(key, step.modelId);
+			if (previous === void 0) continue;
+			this.logger.info("cluster-scoped step re-provisioned for this camera — now runs the new model", {
+				tags: { deviceId },
+				meta: {
+					stepId: step.stepId,
+					from: previous,
+					to: step.modelId
+				}
+			});
+		}
+	}
+};
+function* enabledStepIds(steps) {
+	for (const step of steps) {
+		if (!step.enabled) continue;
+		yield step.addonId;
+		if (step.children) yield* enabledStepIds(step.children);
+	}
+}
+/** The enabled steps of `steps` (any depth) whose cluster model is unknown. */
+function unknownStepsNamed(steps, unknown) {
+	if (unknown.size === 0) return [];
+	return [...enabledStepIds(steps)].filter((id) => unknown.has(id));
+}
+/**
+* One line per (camera, step) while a cluster-scoped step is REFUSED because
+* the owner has not answered which model the cluster runs (D658). Said once per
+* episode: when every step becomes known the memory is cleared, so the next
+* episode is said again.
+*/
+var ClusterUnknownRefusalLog = class {
+	logger;
+	said = /* @__PURE__ */ new Set();
+	constructor(logger) {
+		this.logger = logger;
+	}
+	note(deviceId, steps, unknown) {
+		if (unknown.size === 0) {
+			if (this.said.size > 0) this.said = /* @__PURE__ */ new Set();
+			return;
+		}
+		if (deviceId <= 0) return;
+		for (const stepId of enabledStepIds(steps)) {
+			const reason = unknown.get(stepId);
+			if (reason === void 0) continue;
+			const key = `${String(deviceId)}|${stepId}`;
+			if (this.said.has(key)) continue;
+			this.said = new Set(this.said).add(key);
+			this.logger.warn("cluster-scoped step refused for this camera — the owner has not answered which model the cluster runs", {
+				tags: { deviceId },
+				meta: {
+					stepId,
+					reason
+				}
+			});
 		}
 	}
 };
@@ -2147,7 +2314,8 @@ function collectFramePlaneSteps(steps, isDetailStep) {
 }
 /**
 * Immutably remove from a frame-plane dispatch tree every enabled DETAIL
-* subtree (at any depth below the top level) whose top step `isUnrunnable`.
+* subtree (at any depth below the top level) that `isUnrunnable` — judged
+* WHOLE at its top, because its children ride its call (D657).
 * Those steps can never load into the dispatch device's pool — leaving them
 * in the tree makes `ensureModelsForSteps` fail the whole call on a format
 * build that does not exist. They are NOT dropped work: each runs later as
@@ -2159,6 +2327,11 @@ function collectFramePlaneSteps(steps, isDetailStep) {
 */
 function pruneUnrunnableDetailSteps(steps, isDetailStep, isUnrunnable) {
 	const prunedAddonIds = [];
+	const removedAddonIds = [];
+	const collect = (step) => {
+		removedAddonIds.push(step.addonId);
+		for (const child of step.children ?? []) collect(child);
+	};
 	const walk = (nodes, topLevel) => {
 		const kept = [];
 		for (const step of nodes) {
@@ -2166,8 +2339,9 @@ function pruneUnrunnableDetailSteps(steps, isDetailStep, isUnrunnable) {
 				kept.push(step);
 				continue;
 			}
-			if (!topLevel && isDetailStep(step.addonId) && isUnrunnable(step.addonId)) {
+			if (!topLevel && isDetailStep(step.addonId) && isUnrunnable(step)) {
 				prunedAddonIds.push(step.addonId);
+				collect(step);
 				continue;
 			}
 			kept.push(step.children?.length ? {
@@ -2179,7 +2353,8 @@ function pruneUnrunnableDetailSteps(steps, isDetailStep, isUnrunnable) {
 	};
 	return {
 		steps: walk(steps, true),
-		prunedAddonIds
+		prunedAddonIds,
+		removedAddonIds
 	};
 }
 //#endregion
@@ -2452,16 +2627,26 @@ var PipelineModelManager = class {
 		for (const { entry, step } of diff.unchanged) await this.reconcileDecode(entry, step.settings);
 	}
 	/**
-	* Get an `IInferenceEngine` handle. Without `modelId`, returns the
-	* active model for the step (camera-runtime hot path). Pass
-	* `modelId` to grab a specific warm variant (benchmark path).
-	* Touches the LRU clock so the looked-up model survives eviction
-	* pressure from concurrent loads.
-	*/
-	getHandle(stepId, modelId) {
-		const entry = this.resolveOrThrow(stepId, modelId);
+	* The warm variant that runs `(stepId, modelId)` — its handle AND the model
+	* loaded at that pool index, which is the only honest answer to "which model
+	* produced this output" (D658).
+	*
+	* No active-variant fallback, deliberately. The step-only lookup this
+	* replaces (`getHandle(stepId)`, deleted) answered the step's ACTIVE
+	* variant — the first one loaded after boot — and a tree that paired that
+	* handle with the step's REQUESTED id stamped SigLIP2 on MobileCLIP vectors
+	* for twenty minutes on 2026-09-27. A pair that is not resident throws,
+	* naming both.
+	*/
+	getVariant(stepId, modelId) {
+		const entry = this.loaded.get(stepId)?.get(modelId);
+		if (entry === void 0) throw new Error(`Step "${stepId}" has no warm variant for model "${modelId}" in the inference pool — refusing rather than running another variant`);
 		this.touch(entry);
-		return this.pool.getHandle(entry.poolIndex);
+		return {
+			engine: this.pool.getHandle(entry.poolIndex),
+			modelId: entry.modelId,
+			poolIndex: entry.poolIndex
+		};
 	}
 	/** True iff the step has any model loaded. */
 	isLoaded(stepId) {
@@ -2492,13 +2677,14 @@ var PipelineModelManager = class {
 		return this.activeByStep.get(stepId);
 	}
 	/**
-	* Pool index for a given (stepId, modelId). Without `modelId`,
-	* returns the active model's index. Used by the inference fast
-	* paths that bypass `getHandle` and call `pool.inferBatch` directly.
+	* Pool index for exactly `(stepId, modelId)`, or `null` when that pair is not
+	* warm. Used by the inference fast paths that bypass `getVariant` and call
+	* `pool.inferBatch` directly. The model is REQUIRED: the active-variant
+	* fallback this had timed a benchmark on whichever variant was active (D658).
 	*/
 	getPoolIndex(stepId, modelId) {
-		const entry = this.resolve(stepId, modelId);
-		if (!entry) return null;
+		const entry = this.loaded.get(stepId)?.get(modelId);
+		if (entry === void 0) return null;
 		this.touch(entry);
 		return entry.poolIndex;
 	}
@@ -2718,18 +2904,6 @@ var PipelineModelManager = class {
 			await this.unloadEntry(evicted);
 		}
 	}
-	resolve(stepId, modelId) {
-		const perStep = this.loaded.get(stepId);
-		if (!perStep) return null;
-		const targetModelId = modelId ?? this.activeByStep.get(stepId);
-		if (!targetModelId) return null;
-		return perStep.get(targetModelId) ?? null;
-	}
-	resolveOrThrow(stepId, modelId) {
-		const entry = this.resolve(stepId, modelId);
-		if (!entry) throw new Error(`Step "${stepId}"${modelId ? ` (model "${modelId}")` : ""} is not loaded in the inference pool`);
-		return entry;
-	}
 	touch(entry) {
 		entry.lruTick = ++this.lruClock;
 	}
@@ -2925,16 +3099,15 @@ var EngineFactory = class {
 		await this.poolManager.applyConfig(steps);
 	}
 	/**
-	* Get an IInferenceEngine for a pipeline step. Without `modelId`,
-	* resolves to the active model (camera-runtime hot path); pass
-	* `modelId` to grab a specific warm variant (benchmark / override
-	* paths picking a non-runtime model).
+	* The resident variant for exactly `(stepId, modelId)`, with the model it
+	* runs — never the step's active variant in its place (D658). The executable
+	* tree is built from this, and a result's model stamp comes from it.
 	*
-	* @throws if step not loaded with the requested (or active) model.
+	* @throws if that exact pair is not warm.
 	*/
-	getEngine(stepId, modelId) {
+	getStepVariant(stepId, modelId) {
 		if (!this.poolManager) throw new Error("EngineFactory not initialized");
-		return this.poolManager.getHandle(stepId, modelId);
+		return this.poolManager.getVariant(stepId, modelId);
 	}
 	/** Check if a step is loaded (any variant). */
 	isLoaded(stepId) {
@@ -3038,7 +3211,7 @@ var EngineFactory = class {
 	async batchInferRaw(stepId, items, modelId, frameId = 0) {
 		if (!this.poolManager) throw new Error("EngineFactory.batchInferRaw: pool not initialized");
 		const idx = this.poolManager.getPoolIndex(stepId, modelId);
-		if (idx === null) throw new Error(`EngineFactory.batchInferRaw: step "${stepId}"${modelId ? ` (model "${modelId}")` : ""} is not loaded`);
+		if (idx === null) throw new Error(`EngineFactory.batchInferRaw: step "${stepId}" (model "${modelId}") is not loaded`);
 		return this.poolManager.getPool().inferBatch(idx, items, frameId);
 	}
 	async cacheFrameInPool(raw, width, height, format) {
@@ -3048,7 +3221,7 @@ var EngineFactory = class {
 	async inferCached(stepId, frameId, modelId) {
 		if (!this.poolManager) throw new Error("inferCached: pool not available");
 		const idx = this.poolManager.getPoolIndex(stepId, modelId);
-		if (idx === null) throw new Error(`inferCached: step "${stepId}"${modelId ? ` (model "${modelId}")` : ""} not loaded`);
+		if (idx === null) throw new Error(`inferCached: step "${stepId}" (model "${modelId}") not loaded`);
 		return this.poolManager.getPool().inferCached(idx, frameId);
 	}
 	async uncacheFrame(frameId) {
@@ -3943,13 +4116,16 @@ function checkReplayPin(input) {
 }
 var PRIMARY_ROOT_STEP = "object-detection";
 /**
-* The root model a frame result reports: `object-detection` when it runs (it
-* is the detector the tracks come from), else the first enabled video root.
-* `undefined` when no root runs — never a fabricated id.
+* The same rule over an EXECUTABLE tree's roots (D658): their model ids are the
+* pool variants that will run — after resolution, per-step loads and drops —
+* so this is what a live `runPipeline` stamps. The tree holds only enabled
+* video roots already.
 */
-function resolveRootModelId(roots) {
-	const enabled = roots.filter((s) => s.enabled && s.slot !== "audio-classifier");
-	return (enabled.find((s) => s.addonId === PRIMARY_ROOT_STEP) ?? enabled[0])?.modelId;
+function resolveTreeRootModelId(roots) {
+	return primaryRootModelId(roots);
+}
+function primaryRootModelId(roots) {
+	return (roots.find((s) => s.stepId === PRIMARY_ROOT_STEP) ?? roots[0])?.modelId;
 }
 //#endregion
 //#region src/detection-pipeline/engine-provisioner.ts
@@ -6742,26 +6918,47 @@ function resolveEffectiveClassMap(definition, modelId, resolveModel) {
 * Build an executable tree from user config.
 *
 * @param steps - User-configured pipeline steps (from PipelineDefaultStep[])
-* @param getEngine - Function that returns an IInferenceEngine for a step ID.
-*                    Throws if step not loaded.
+* @param getEngine - Returns the engine that runs exactly `(stepId, modelId)`
+*                    and the model it runs. Throws if that pair is not loaded.
 */
-function buildExecutableTree(steps, getEngine, resolveModel) {
-	return { roots: steps.filter((s) => s.enabled).filter((s) => s.slot !== "audio-classifier").map((s) => buildNode(s, getEngine, resolveModel)) };
+function buildExecutableTree(steps, getEngine, resolveModel, onMissingVariant) {
+	return { roots: steps.filter((s) => s.enabled).filter((s) => s.slot !== "audio-classifier").map((s) => buildNode(s, getEngine, resolveModel, onMissingVariant)) };
+}
+function subtreeIds(step) {
+	return [step.addonId, ...(step.children ?? []).filter((c) => c.enabled).flatMap((c) => subtreeIds(c))];
+}
+function buildChild(child, parentStepId, getEngine, resolveModel, onMissingVariant) {
+	if (onMissingVariant === void 0) return buildNode(child, getEngine, resolveModel, onMissingVariant);
+	let variant;
+	try {
+		variant = getEngine(child.addonId, child.modelId);
+	} catch (err) {
+		onMissingVariant({
+			step: child,
+			stepId: child.addonId,
+			modelId: child.modelId,
+			parentStepId,
+			droppedSubtree: subtreeIds(child),
+			error: err instanceof Error ? err.message : String(err)
+		});
+		return null;
+	}
+	return buildNode(child, getEngine, resolveModel, onMissingVariant, variant);
 }
-function buildNode(step, getEngine, resolveModel) {
+function buildNode(step, getEngine, resolveModel, onMissingVariant, resolved) {
 	const definition = getStepDefinition(step.addonId);
-	const engine = getEngine(step.addonId);
-	const children = (step.children ?? []).filter((c) => c.enabled).map((c) => buildNode(c, getEngine, resolveModel));
+	const variant = resolved ?? getEngine(step.addonId, step.modelId);
+	const children = (step.children ?? []).filter((c) => c.enabled).map((c) => buildChild(c, step.addonId, getEngine, resolveModel, onMissingVariant)).filter((c) => c !== null);
 	const mergedSettings = {
 		...collectSchemaDefaults(step.addonId),
 		...step.settings
 	};
-	const effectiveClassMap = resolveEffectiveClassMap(definition, step.modelId, resolveModel);
+	const effectiveClassMap = resolveEffectiveClassMap(definition, variant.modelId, resolveModel);
 	return {
 		stepId: step.addonId,
 		definition,
-		engine,
-		modelId: step.modelId,
+		engine: variant.engine,
+		modelId: variant.modelId,
 		inputClasses: definition.inputClasses ?? [],
 		enabled: step.enabled,
 		children,
@@ -6791,43 +6988,6 @@ function walkFieldsForDefaults(fields, out) {
 	}
 }
 //#endregion
-//#region src/detection-pipeline/registry/custom-models.ts
-/**
-* Group a flat list of custom-model descriptors (as returned by the
-* `custom-model-registry` collection cap) into a `stepId → entries` map for
-* the picker / resolution union. Pure; order within a step preserved.
-*/
-function groupCustomModelsByStep(descriptors) {
-	const byStep = /* @__PURE__ */ new Map();
-	for (const d of descriptors) {
-		const arr = byStep.get(d.stepId) ?? [];
-		arr.push(d.entry);
-		byStep.set(d.stepId, arr);
-	}
-	return byStep;
-}
-/**
-* Union a step's static catalog models with operator-registered custom
-* models. On an `id` collision the static catalog entry wins — a custom
-* model can never shadow a built-in one.
-*
-* Pure + side-effect-free so it can be unit-tested in isolation and called
-* from the (free) `buildSchemaSlots` builder without any addon context.
-*/
-function mergeCustomModels(staticModels, customModels) {
-	const seen = new Set(staticModels.map((m) => m.id));
-	const merged = [...staticModels];
-	for (const m of customModels) {
-		if (seen.has(m.id)) continue;
-		seen.add(m.id);
-		merged.push({
-			...m,
-			provider: inferModelProvider(m)
-		});
-	}
-	return merged;
-}
-//#endregion
 //#region src/detection-pipeline/cluster-model-resolution.ts
 /**
 * The cluster model rule, enforced on the node that has to obey it.
@@ -6932,8 +7092,10 @@ function collectSubstitutions(steps, 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
+* Return one {@link ZeroBuildIssue} per step in `steps` that a pool of `format`
+* cannot run: neither the model it names nor any NON-legacy model of its
+* catalog (via `getStepDef`) ships a build for `format`
+* (`stepModelRunsOnFormat`, D657). `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}.
@@ -6954,7 +7116,7 @@ function collectZeroBuildIssues(steps, format, getStepDef = getStepDefinition) {
 		} catch {
 			continue;
 		}
-		if (!def.models.some((m) => m.formats[format])) result.push({
+		if (!stepModelRunsOnFormat(def.models, step.modelId, format)) result.push({
 			addonId: step.addonId,
 			format
 		});
@@ -7004,11 +7166,20 @@ function collectUnknownAddonIssues(steps, getStepDef = getStepDefinition) {
 * `diagnostics.substitutions` instead of happening silently. The caller
 * (the provider) owns logging + dedup for both.
 */
-function resolveInputSteps(steps, format, engine, clusterModels, clusterSettings) {
+function resolveInputSteps(steps, format, engine, clusterModels, clusterSettings, unknownClusterSteps) {
 	const resolvedSteps = [];
 	const unknownAddonIds = [];
 	const substitutions = [];
 	const clusterRefusals = [];
+	const clusterUnknown = [];
+	const recurse = (children) => {
+		const r = resolveInputSteps(children, format, engine, clusterModels, clusterSettings, unknownClusterSteps);
+		unknownAddonIds.push(...r.diagnostics.unknownAddonIds);
+		substitutions.push(...r.diagnostics.substitutions);
+		clusterRefusals.push(...r.diagnostics.clusterRefusals);
+		clusterUnknown.push(...r.diagnostics.clusterUnknown);
+		return r;
+	};
 	for (const s of steps) {
 		let def;
 		try {
@@ -7017,6 +7188,10 @@ function resolveInputSteps(steps, format, engine, clusterModels, clusterSettings
 			unknownAddonIds.push(s.addonId);
 			continue;
 		}
+		if (def.modelScope === "cluster" && unknownClusterSteps?.has(s.addonId) === true) {
+			clusterUnknown.push(s.addonId);
+			continue;
+		}
 		if (clusterModels !== void 0) {
 			const verdict = resolveClusterStepModel(s.addonId, clusterModels, format, () => def);
 			if (verdict.kind !== "node-scoped") {
@@ -7026,12 +7201,7 @@ function resolveInputSteps(steps, format, engine, clusterModels, clusterSettings
 					format: verdict.format,
 					formatsShipped: verdict.formatsShipped
 				});
-				const childResult = s.children ? resolveInputSteps(s.children, format, engine, clusterModels, clusterSettings) : null;
-				if (childResult) {
-					unknownAddonIds.push(...childResult.diagnostics.unknownAddonIds);
-					substitutions.push(...childResult.diagnostics.substitutions);
-					clusterRefusals.push(...childResult.diagnostics.clusterRefusals);
-				}
+				const childResult = s.children ? recurse(s.children) : null;
 				const settings = overlayClusterStepSettings(s.addonId, s.settings, clusterSettings ?? {});
 				resolvedSteps.push({
 					addonId: s.addonId,
@@ -7055,12 +7225,7 @@ function resolveInputSteps(steps, format, engine, clusterModels, clusterSettings
 			running: runningModelId,
 			format
 		});
-		const childResult = s.children ? resolveInputSteps(s.children, format, engine, clusterModels, clusterSettings) : null;
-		if (childResult) {
-			unknownAddonIds.push(...childResult.diagnostics.unknownAddonIds);
-			substitutions.push(...childResult.diagnostics.substitutions);
-			clusterRefusals.push(...childResult.diagnostics.clusterRefusals);
-		}
+		const childResult = s.children ? recurse(s.children) : null;
 		const settings = overlayClusterStepSettings(s.addonId, s.settings, clusterSettings ?? {});
 		resolvedSteps.push({
 			addonId: s.addonId,
@@ -7079,7 +7244,8 @@ function resolveInputSteps(steps, format, engine, clusterModels, clusterSettings
 		diagnostics: {
 			unknownAddonIds,
 			substitutions,
-			clusterRefusals
+			clusterRefusals,
+			clusterUnknown
 		}
 	};
 }
@@ -7322,6 +7488,62 @@ function stepModelKey(step) {
 function stateOf(verdict) {
 	return verdict.kind === "refused" ? "refused" : `failed:${verdict.generation}`;
 }
+/** The load policy of a `runPipeline` call — see {@link DispatchLoadPolicy}. */
+function dispatchLoadPolicyOf(input) {
+	return input.deviceId !== void 0 && input.replay !== true ? "partial" : "all-or-nothing";
+}
+/**
+* An all-or-nothing call lost steps to failed loads (D657). Names every one,
+* so a benchmark never reports timings for a tree it did not run.
+*/
+var DispatchStepsNotLoadedError = class extends Error {
+	failedSteps;
+	constructor(failures) {
+		const named = failures.map((f) => `${f.step.addonId}/${f.step.modelId} (${f.error instanceof Error ? f.error.message : String(f.error)})`);
+		super(`pipeline steps failed to load — the call runs all of them or none: ${named.join("; ")}`, { cause: failures[0]?.error });
+		this.name = "DispatchStepsNotLoadedError";
+		this.failedSteps = failures.map((f) => `${f.step.addonId}/${f.step.modelId}`);
+	}
+};
+/**
+* A step's model artifact cannot be made present for the pool's format — no
+* build for that format, a custom model missing from this node, a download
+* that failed. Named by step and model so the failure is charged to THAT
+* model only (D657): a plain `Error` was charged to every model of the set,
+* and one face model with no tflite build backed the Coral's root detector
+* off for minutes.
+*/
+var StepModelArtifactError = class extends Error {
+	stepId;
+	modelId;
+	constructor(stepId, modelId, cause) {
+		super(cause instanceof Error ? cause.message : String(cause), { cause });
+		this.name = "StepModelArtifactError";
+		this.stepId = stepId;
+		this.modelId = modelId;
+	}
+};
+/** The one model a failed load is charged to, when the error names it. */
+function failedModelOf(err) {
+	if (err instanceof StepVariantLoadError || err instanceof StepModelArtifactError) return `${err.stepId}/${err.modelId}`;
+	return null;
+}
+/**
+* `steps` without the subtrees of the steps whose model did not load (D657).
+* A step's children consume its output, so they leave with it. Matched by
+* INSTANCE: two steps of one addon in a tree are two steps.
+*/
+function withoutFailedSteps(steps, failed) {
+	const kept = [];
+	for (const step of steps) {
+		if (failed.has(step)) continue;
+		kept.push(step.children && step.children.length > 0 ? {
+			...step,
+			children: withoutFailedSteps(step.children, failed)
+		} : step);
+	}
+	return kept;
+}
 /**
 * The reason a condemned pool is charged against its device's restart budget.
 * A pool recycled because it HUNG (D653) names the hang — `inference device
@@ -7429,18 +7651,18 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 	* paths don't issue a cap round-trip on every call. Empty map = no provider
 	* (or a query failure) → behaviour identical to the static-catalog-only path.
 	*/
-	customModelsCache = null;
+	customModels = new CustomModelCatalog({ warn: (message, extras) => this.log.warn(message, extras) });
 	/**
 	* SYNC custom-model lookup handed to every live {@link EngineFactory} so
 	* `buildPoolModelConfigForStep` can resolve an operator-registered model at
-	* pool-load time. Reads the {@link customModelsCache} snapshot — every load
+	* pool-load time. Reads the {@link customModels} snapshot — every load
 	* path (`ensureModelsForSteps`, `ensureModelsForCurrentSteps`) refreshes the
 	* cache via `resolveModelEntry` BEFORE `loadAdditional`/`applyConfig`, so
 	* the snapshot is fresh when the pool asks. Without this seam a selected
 	* custom model failed the WHOLE pool applyConfig with
 	* `Model "X" not found in step "Y" catalog`.
 	*/
-	customModelResolver = (stepId, modelId) => this.customModelsCache?.byStep.get(stepId)?.find((m) => m.id === modelId);
+	customModelResolver = (stepId, modelId) => this.customModels.current().get(stepId)?.find((m) => m.id === modelId);
 	/**
 	* Per-device {@link DeviceProxy} cache used for zone gating at the
 	* runtime path. Reads `state.zones.value` + `state.zoneRules.value`
@@ -7463,6 +7685,10 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 		info: (message, extras) => this.log.info(message, extras),
 		warn: (message, extras) => this.log.warn(message, extras)
 	} });
+	/** One line per camera when a cluster-scoped step starts running another model (D658). */
+	clusterModelSwitchLog = new ClusterModelSwitchLog({ info: (message, extras) => this.log.info(message, extras) });
+	/** One line per (camera, step) while a cluster step is refused as unknown (D658). */
+	clusterUnknownLog = new ClusterUnknownRefusalLog({ warn: (message, extras) => this.log.warn(message, extras) });
 	/**
 	* Last logged "step configured" signature — used to dedupe the
 	* per-step debug trail so it only fires on actual config CHANGE
@@ -7929,7 +8155,7 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 			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`);
+			const zeroBuildIssues = collectZeroBuildIssues(flattenSteps(steps), format, this.mergedStepDefOrThrow).map((i) => `${i.addonId}: no model has a ${i.format} build`);
 			this.configIssues = [...substitutionIssues, ...zeroBuildIssues];
 		} catch (err) {
 			this.configIssues = [];
@@ -8063,24 +8289,21 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 	* a warning — callers then behave exactly like the static-catalog path.
 	*/
 	async getCustomModels() {
-		const now = Date.now();
-		if (this.customModelsCache && now - this.customModelsCache.at < 5e3) return this.customModelsCache.byStep;
-		let byStep = /* @__PURE__ */ new Map();
-		try {
-			const api = this.addonCtx?.api;
-			if (api) {
-				if ((await api.addons.listCapabilityProviders.query({ capName: "custom-model-registry" })).some((p) => p.isActive)) byStep = groupCustomModelsByStep(await api.customModelRegistry.listModels.query());
-			}
-		} catch (err) {
-			this.log.warn("custom-model-registry query failed — using static catalog only", { meta: { error: errMsg(err) } });
-		}
-		this.customModelsCache = {
-			at: now,
-			byStep
-		};
-		return byStep;
+		return this.customModels.refresh(this.addonCtx?.api);
 	}
 	/**
+	* A step's definition MERGED with its custom models, synchronously, from
+	* the last custom-model read (D657 round 2). Every placement gate here
+	* judges this catalog — the one the orchestrator's schema carries.
+	*/
+	mergedStepDef = (addonId) => this.customModels.stepDefinition(addonId);
+	/** {@link mergedStepDef} as the throwing lookup `collectZeroBuildIssues` takes. */
+	mergedStepDefOrThrow = (addonId) => {
+		const def = this.mergedStepDef(addonId);
+		if (def === null) throw new Error(`Unknown pipeline step: "${addonId}"`);
+		return def;
+	};
+	/**
 	* Resolve a model id within a step to a catalog entry — static catalog
 	* first, then the custom registry. Returns undefined if neither has it.
 	*/
@@ -8271,7 +8494,7 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 			const enabledSteps = this.pruneToEnabledSteps(steps);
 			const substitutions = collectSubstitutions(enabledSteps, format);
 			const unknownAddonIssues = collectUnknownAddonIssues(enabledSteps);
-			const zeroBuildIssues = collectZeroBuildIssues(this.flattenEnabledVideoStepInputs(steps), format);
+			const zeroBuildIssues = collectZeroBuildIssues(this.flattenEnabledVideoStepInputs(steps), format, this.mergedStepDefOrThrow);
 			const issues = [...unknownAddonIssues.map((u) => ({
 				addonId: u.addonId,
 				kind: "unknown-addon",
@@ -8588,6 +8811,12 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 	}
 	async runPipeline(input, onProgress) {
 		await this.clusterModels.refresh(this.addonCtx?.api);
+		this.clusterUnknownLog.note(input.deviceId ?? 0, input.steps, this.clusterModels.unknownSteps());
+		if (dispatchLoadPolicyOf(input) === "all-or-nothing") {
+			const unknown = unknownStepsNamed(input.steps, this.clusterModels.unknownSteps());
+			if (unknown.length > 0) throw new Error(`cluster-model-unknown: the owner has not answered which model the cluster runs for ${unknown.join(", ")} — the call runs all of its steps or none`);
+		}
+		await this.getCustomModels();
 		const nodeId = this.addonCtx?.kernel?.localNodeId ?? "hub";
 		const sessionId = input.sessionId ?? `run-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
 		const isRuntime = Boolean(input.frame || input.frameRef);
@@ -8752,11 +8981,6 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 		}
 		const enabledSteps = flattenSteps(benchmarkSteps);
 		emit(`Pipeline: ${enabledSteps.length} step(s) — ${enabledSteps.map((s) => s.addonId).join(" → ")}`);
-		const rootModelId = resolveRootModelId(benchmarkSteps);
-		const stampRoot = (r) => rootModelId === void 0 ? r : {
-			...r,
-			rootModelId
-		};
 		if (input.replay === true) {
 			const verdict = checkReplayPin({
 				requested: input.steps,
@@ -8798,24 +9022,51 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 		const dispatchEngine = dispatchDeviceKey ? resolveDeviceEngine(dispatchDeviceKey) : runEngine;
 		const dispatchFactory = dispatchDeviceKey ? await this.resolveDeviceFactory(dispatchDeviceKey) : this.engineFactory;
 		const needed = enabledSteps.filter((s) => dispatchFactory.needsPoolUpdate(s));
+		let runSteps = benchmarkSteps;
+		const loadPolicy = dispatchLoadPolicyOf(input);
 		if (needed.length > 0) {
-			this.log.info("Benchmark: models to load", { meta: {
-				count: needed.length,
-				models: needed.map((s) => `${s.addonId}/${s.modelId}`)
+			const dispatchDeviceKeyLabel = deviceKeyOf(dispatchEngine);
+			const toIssue = needed.filter((s) => this.loadGovernor.check(dispatchFactory, dispatchDeviceKeyLabel, [stepModelKey(s)]).kind === "go");
+			if (toIssue.length > 0) this.log.info("Benchmark: models to load", { meta: {
+				count: toIssue.length,
+				models: toIssue.map((s) => `${s.addonId}/${s.modelId}`)
 			} });
-			for (const s of needed) emit(`Loading model: ${s.addonName} (${s.modelId})...`, {
+			for (const s of toIssue) emit(`Loading model: ${s.addonName} (${s.modelId})...`, {
 				step: s.addonId,
 				addonId: s.addonId,
 				modelId: s.modelId
 			});
-			await this.ensureModelsForSteps(benchmarkSteps, dispatchFactory, dispatchEngine.format, {
+			const failures = await this.loadDispatchModels(benchmarkSteps, dispatchFactory, dispatchEngine.format, {
 				...input.deviceId !== void 0 ? { deviceId: input.deviceId } : {},
-				deviceKey: deviceKeyOf(dispatchEngine)
-			});
-			emit(`All models loaded`);
+				deviceKey: dispatchDeviceKeyLabel
+			}, loadPolicy);
+			runSteps = stepsSurvivingLoad(benchmarkSteps, failures, loadPolicy);
+			emit(failures.length === 0 ? `All models loaded` : `Models loaded (${failures.length} failed)`);
 		}
 		emit("Running inference...");
-		const tree = buildExecutableTree(benchmarkSteps, (stepId) => dispatchFactory.getEngine(stepId), this.customModelResolver);
+		const notWarm = [];
+		const tree = buildExecutableTree(runSteps, (stepId, modelId) => dispatchFactory.getStepVariant(stepId, modelId), this.customModelResolver, (drop) => notWarm.push({
+			step: drop.step,
+			error: new Error(drop.error)
+		}));
+		if (notWarm.length > 0) {
+			if (loadPolicy === "all-or-nothing") throw new DispatchStepsNotLoadedError(notWarm);
+			const dispatchDeviceKeyLabel = deviceKeyOf(dispatchEngine);
+			for (const failure of notWarm) {
+				const model = stepModelKey(failure.step);
+				this.reportDispatchLoadLoss({
+					...input.deviceId !== void 0 ? { deviceId: input.deviceId } : {},
+					deviceKey: dispatchDeviceKeyLabel,
+					outcome: "step-dropped"
+				}, dispatchDeviceKeyLabel, [model], model, "not-warm", errMsg(failure.error));
+			}
+		}
+		const rootModelId = resolveTreeRootModelId(tree.roots);
+		const stampRoot = (r) => rootModelId === void 0 ? r : {
+			...r,
+			rootModelId
+		};
+		if (input.replay !== true) this.clusterModelSwitchLog.note(input.deviceId ?? 0, tree);
 		setupMs = performance.now() - wallT0 - decodeMs;
 		const effectiveDeviceId = input.deviceId ?? 0;
 		const deviceOverrides = effectiveDeviceId > 0 ? await this.deviceOverrides.resolve(effectiveDeviceId) : {};
@@ -8921,7 +9172,7 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 		backend: this.currentEngine.backend,
 		device: this.currentEngine.device ?? null
 	}, clusterRefusalsOut) {
-		const { steps: resolvedSteps, diagnostics } = resolveInputSteps(steps, format, engine, this.clusterModels.current(), this.clusterModels.currentSettings());
+		const { steps: resolvedSteps, diagnostics } = resolveInputSteps(steps, format, engine, this.clusterModels.current(), this.clusterModels.currentSettings(), this.clusterModels.unknownSteps());
 		if (clusterRefusalsOut) clusterRefusalsOut.push(...diagnostics.clusterRefusals);
 		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: {
@@ -9034,7 +9285,7 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 		const deviceRefusals = [];
 		const steps = this.inputStepsToPipelineSteps(args.steps, deviceFormat, deviceStepEngine, deviceRefusals);
 		const framePlane = args.plane === "frame";
-		const zeroBuild = collectZeroBuildIssues(framePlane ? collectFramePlaneSteps(steps, isDetailPlaneStep) : flattenSteps(steps), deviceFormat);
+		const zeroBuild = collectZeroBuildIssues(framePlane ? collectFramePlaneSteps(steps, isDetailPlaneStep) : flattenSteps(steps), deviceFormat, this.mergedStepDefOrThrow);
 		if (zeroBuild.length === 0) {
 			if (!framePlane) {
 				this.logClusterRefusals(deviceRefusals, deviceId, `${deviceKey} (${deviceFormat})`);
@@ -9043,7 +9294,7 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 					steps
 				};
 			}
-			const pruneResult = pruneUnrunnableDetailSteps(steps, isDetailPlaneStep, (addonId) => stepHasZeroBuildsFor(addonId, deviceFormat));
+			const pruneResult = pruneUnrunnableDetailSteps(steps, isDetailPlaneStep, (subtree) => !buildSubtreeCanRun(subtree, this.mergedStepDef)(deviceFormat));
 			if (pruneResult.prunedAddonIds.length > 0) {
 				const prunedList = pruneResult.prunedAddonIds.join(",");
 				this.logLiveDispatchIssueOnce(`detail-defer:${deviceKey}:${deviceFormat}:${prunedList}`, () => this.log.info("Detail steps have no model build for the dispatch device format — deferred to the detail-plane device jump", {
@@ -9055,7 +9306,7 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 					}
 				}));
 			}
-			this.logClusterRefusals(deviceRefusals.filter((r) => !pruneResult.prunedAddonIds.includes(r.stepId)), deviceId, `${deviceKey} (${deviceFormat})`);
+			this.logClusterRefusals(deviceRefusals.filter((r) => !pruneResult.removedAddonIds.includes(r.stepId)), deviceId, `${deviceKey} (${deviceFormat})`);
 			return {
 				deviceKey,
 				steps: pruneResult.steps
@@ -9089,7 +9340,7 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 	* microseconds instead of a 3-retry download backoff).
 	*/
 	assertStepsRunnable(steps, format, deviceId, enginesTried) {
-		const zeroBuild = collectZeroBuildIssues(flattenSteps(steps), format);
+		const zeroBuild = collectZeroBuildIssues(flattenSteps(steps), format, this.mergedStepDefOrThrow);
 		if (zeroBuild.length === 0) return;
 		const detail = zeroBuild.map((issue) => {
 			const step = flattenSteps(steps).find((s) => s.addonId === issue.addonId);
@@ -9123,6 +9374,40 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 	nullPoolKey = {};
 	/** Negative cache, per-model compile-timeout refusals, per-camera reporting (D653). */
 	loadGovernor = new ModelLoadGovernor();
+	/**
+	* Load a dispatch's models ONE STEP AT A TIME (D657), and answer which steps
+	* did not load. Never throws: each step is its own load, joined, backed off
+	* and charged on its own model, so a step whose model cannot load on this
+	* pool — no build for its format, a compile that failed — costs that step,
+	* never the root or a sibling. The caller decides what the dispatch runs
+	* without it ({@link stepsSurvivingLoad}).
+	*/
+	async loadDispatchModels(steps, factory, format, context, policy) {
+		const failures = [];
+		const walk = async (nodes, root) => {
+			for (const step of nodes) {
+				if (!step.enabled || step.slot === "audio-classifier") continue;
+				if (factory === null || factory.needsPoolUpdate(step)) try {
+					await this.ensureModelsForSteps([{
+						...step,
+						children: []
+					}], factory, format, {
+						...context,
+						outcome: policy === "all-or-nothing" ? "call-failed" : root ? "root-lost" : "step-dropped"
+					});
+				} catch (err) {
+					failures.push({
+						step,
+						error: err
+					});
+					continue;
+				}
+				await walk(step.children ?? [], false);
+			}
+		};
+		await walk(steps, true);
+		return failures;
+	}
 	/** Ensure all models needed by steps are downloaded and loaded in the engine pool.
 	* `factory`/`format` default to the node's engine; a per-device dispatch passes
 	* that device's factory + format (Phase 2 multi-device). `context` names the
@@ -9152,7 +9437,7 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 				this.reportDispatchLoadLoss(context, deviceKey, models, err.model, err.state, err.message);
 				throw err;
 			}
-			const failed = err instanceof StepVariantLoadError ? `${err.stepId}/${err.modelId}` : models[0] ?? "";
+			const failed = failedModelOf(err) ?? models[0] ?? "";
 			this.reportDispatchLoadLoss(context, deviceKey, models, failed, `failed:${flight.generation ?? "unknown"}`, errMsg(err));
 			throw err;
 		}
@@ -9244,7 +9529,8 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 	}
 	/** Charge a failed load to the model that failed; say so once if it is now refused. */
 	recordModelLoadFailure(pool, deviceKey, models, err) {
-		const failedModels = err instanceof StepVariantLoadError ? [`${err.stepId}/${err.modelId}`] : models;
+		const named = failedModelOf(err);
+		const failedModels = named !== null ? [named] : models;
 		const compileTimeout = err instanceof StepVariantLoadError && err.reason === "compile-timeout";
 		const poolModel = err instanceof StepVariantLoadError ? err.poolModel : null;
 		let generation = 0;
@@ -9277,24 +9563,31 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 				models,
 				model,
 				state,
-				error
+				error,
+				...context.outcome !== void 0 ? { outcome: context.outcome } : {}
 			}
 		});
 	}
 	/** Download any model of `needed` missing in `format` (the device's). */
 	async downloadNeededModels(needed, format) {
-		for (const step of needed) {
-			const modelEntry = await this.resolveModelEntry(step.addonId, step.modelId);
-			if (modelEntry && !isModelDownloaded(this.modelsDir, modelEntry, format)) {
-				if (modelEntry.formats[format] === void 0) throw new Error(`Model "${modelEntry.id}" has no ${format} format build (available: ${Object.keys(modelEntry.formats).join(", ") || "none"}) — not retrying a permanent format mismatch`);
-				if (modelEntry.formats[format]?.url.startsWith("camstack-local://") === true) throw new Error(`Custom model "${modelEntry.id}" (${format}) is not present in this node's models directory — distribute it to this node from Model Studio before selecting it here`);
-				this.log.info("Downloading model for step", { meta: {
-					modelId: step.modelId,
-					format,
-					step: step.addonId
-				} });
-				await this.downloadWithRetry(modelEntry, format, 3);
-			}
+		for (const step of needed) try {
+			await this.ensureStepModelArtifact(step, format);
+		} catch (err) {
+			throw new StepModelArtifactError(step.addonId, step.modelId, err);
+		}
+	}
+	/** Make one step's model artifact present on disk for `format`, or say why it cannot be. */
+	async ensureStepModelArtifact(step, format) {
+		const modelEntry = await this.resolveModelEntry(step.addonId, step.modelId);
+		if (modelEntry && !isModelDownloaded(this.modelsDir, modelEntry, format)) {
+			if (modelEntry.formats[format] === void 0) throw new Error(`Model "${modelEntry.id}" has no ${format} format build (available: ${Object.keys(modelEntry.formats).join(", ") || "none"}) — not retrying a permanent format mismatch`);
+			if (modelEntry.formats[format]?.url.startsWith("camstack-local://") === true) throw new Error(`Custom model "${modelEntry.id}" (${format}) is not present in this node's models directory — distribute it to this node from Model Studio before selecting it here`);
+			this.log.info("Downloading model for step", { meta: {
+				modelId: step.modelId,
+				format,
+				step: step.addonId
+			} });
+			await this.downloadWithRetry(modelEntry, format, 3);
 		}
 	}
 	/** Download a model with retry + exponential backoff */
@@ -9392,6 +9685,7 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 	}
 	async runPipelineBatchImpl(input) {
 		if (input.frames.length === 0) return { results: [] };
+		await this.getCustomModels();
 		const dispatchResolution = this.resolveStepsForDispatch({
 			steps: input.steps,
 			deviceKey: input.deviceKey,
@@ -9634,9 +9928,10 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 		return this.engineFactory.cacheFrameInPool(buf, input.width, input.height, input.format);
 	}
 	async inferCached(input) {
+		if (typeof input.modelId !== "string" || input.modelId === "") throw new Error(`inferCached: no modelId for step "${input.stepId}" — refusing rather than running the step's active variant`);
 		await this.ensureEngineFactory();
 		if (!this.engineFactory) throw new Error("inferCached: factory not initialized");
-		return this.engineFactory.inferCached(input.stepId, input.frameId);
+		return this.engineFactory.inferCached(input.stepId, input.frameId, input.modelId);
 	}
 	async uncacheFrame(input) {
 		if (!this.engineFactory) return;
@@ -10440,13 +10735,22 @@ function isDetailPlaneStep(addonId) {
 	}
 }
 /**
-* True when the step's FULL catalog ships no model with a build for
-* `format` — the single-step form of `collectZeroBuildIssues`. Unknown/custom
-* addonIds (no catalog to check) are never zero-build, mirroring the
-* collector's skip.
-*/
-function stepHasZeroBuildsFor(addonId, format) {
-	return collectZeroBuildIssues([{ addonId }], format).length > 0;
+* What a dispatch runs after its per-step loads (D657).
+*
+* An ALL-OR-NOTHING call (a benchmark, a replay — D56 — a capacity ramp) fails
+* on any failure, naming every step it lost ({@link DispatchStepsNotLoadedError}):
+* it measures or reproduces exactly what it names. A camera's LIVE dispatch
+* runs the tree without the steps whose model did not load, and fails — with
+* the first root's own named error — only when no root survives: a dispatch
+* with no root has nothing to produce.
+*/
+function stepsSurvivingLoad(steps, failures, policy) {
+	if (failures.length === 0) return steps;
+	if (policy === "all-or-nothing") throw new DispatchStepsNotLoadedError(failures);
+	const kept = withoutFailedSteps(steps, new Set(failures.map((f) => f.step)));
+	if (kept.some((s) => s.enabled)) return kept;
+	const roots = new Set(steps);
+	throw (failures.find((f) => roots.has(f.step)) ?? failures[0]).error;
 }
 /**
 * The union of model formats a step's catalog ships ANY build for — the