@camstack/addon-pipeline 1.2.103 → 1.2.105

package/dist/detection-pipeline/index.mjs

@@ -1,8 +1,8 @@
 import { n as __require } from "../chunk-DnnnRqeS.mjs";
-import { At as array, Bt as EventCategory, H as enumerateInferenceDevices, It as object, Ot as sleep, P as defaultDeviceFor$1, Rt as string, T as YAMNET_TO_MACRO, Tt as parseJsonUnknown, U as evaluateZoneRules, Z as pipelineExecutorCapability, bt as hydrateSchema, d as DEVICE_BACKEND_TO_FORMAT, ht as BaseAddon, it as runtimeDevices$1, lt as errMsg, nt as resolvePoolMemoryPolicy, st as supportedRuntimes$1, t as APPLE_SA_TO_MACRO, wt as nodePin, y as PoolMemoryWatchdog, yt as createEvent, z as detectionPipelineCapability, zt as union } from "../dist-Ccmt3fGJ.mjs";
-import { a as getDefaultModelForFormat, c as getStepDefinition, i as ALL_STEPS, l as resolveModelForFormat, n as startEventLoopStallMonitor, o as getDefaultModelForFormatFromDef, r as ALL_PIPELINE_STEPS, s as getStep, u as landmarkPrecisionVerdict } from "../event-loop-stall-monitor-OJrOMeuu.mjs";
+import { $ as pipelineExecutorCapability, B as detectionPipelineCapability, Ct as hydrateSchema, Dt as nodePin, E as YAMNET_TO_MACRO, F as defaultDeviceFor$1, Ht as union, Nt as array, Ot as parseJsonUnknown, St as createEvent, U as enumerateInferenceDevices, Ut as EventCategory, Vt as string, W as evaluateZoneRules, X as pickClusterStepModels, at as resolvePoolMemoryPolicy, b as PoolMemoryWatchdog, c as DEFAULT_CLUSTER_STEP_MODELS, f as DEVICE_BACKEND_TO_FORMAT, ft as errMsg, jt as sleep, rt as resolveClusterStepModelId, st as runtimeDevices$1, t as APPLE_SA_TO_MACRO, ut as supportedRuntimes$1, vt as BaseAddon, zt as object } from "../dist-BSWr9Qg8.mjs";
+import { a as getDefaultModelForFormat, c as getStepDefinition, i as ALL_STEPS, l as resolveModelForFormat, n as startEventLoopStallMonitor, o as getDefaultModelForFormatFromDef, r as ALL_PIPELINE_STEPS, s as getStep, u as landmarkPrecisionVerdict } from "../event-loop-stall-monitor-BeQHivuY.mjs";
 import { t as getSharp } from "../lazy-sharp-6oymT_yf.mjs";
-import { n as pickNodePlatformArch, t as readProcessMemory } from "../process-memory-D0zDmXLI.mjs";
+import { n as pickNodePlatformArch, t as readProcessMemory } from "../process-memory-DFL51gCx.mjs";
 import { a as ensureModel, o as isModelDownloaded, r as deleteModelFromDisk } from "../addon-utils-A2S9D7pu.mjs";
 import sharp from "sharp";
 import { spawn } from "node:child_process";
@@ -84,6 +84,11 @@ function probedToHardwareInfo(hw) {
 * `numStreams` / `intraOpThreads` are inert at 0 (the runtime picks) — they are
 * still spelled out per row so a reader never has to guess which default a
 * missing key would have hit.
+*
+* `batchMode` / `maxBatchSize` are REQUEST GROUPING, not shape. Whether a graph
+* may keep a dynamic batch axis is a hardware fact derived at load from the
+* (engine, device) pair — `_static_batch_required` in `inference_pool.py`, D202 —
+* and appears nowhere in this registry, in the catalog, or in any operator knob.
 */
 var RUNTIME_DETAIL = {
 	onnx: {
@@ -1064,6 +1069,25 @@ var SharedInferencePool = class {
 		})));
 		for (const resp of responses) if (resp.status !== "ok") throw new Error(`Failed to unload model at index ${index}: ${resp.error ?? "unknown"}`);
 	}
+	/**
+	* Retune a LOADED slot's decode-scoped settings without touching its
+	* inference session — the narrow counterpart of `replaceModel`.
+	*
+	* `replace` is `unload` + `load`: it re-instantiates the session (~1.4s on
+	* coreml, and an OpenVINO recompile) and stalls every live camera routed to
+	* this pool. An operator moving the NMS slider must not cost that, and must
+	* not touch any other slot: the Python side applies the patch to `index`
+	* only, and refuses any key outside its reconfigurable allow-list rather
+	* than accepting a `path` change that would silently not reload.
+	*/
+	async reconfigureModel(index, settings) {
+		const responses = await Promise.all(this.workers.map((w) => w.sendCommand({
+			cmd: "reconfigure",
+			index,
+			config: { nmsIouThreshold: settings.nmsIouThreshold }
+		})));
+		for (const resp of responses) if (resp.status !== "ok") throw new Error(`Failed to reconfigure model at index ${index}: ${resp.error ?? "unknown"}`);
+	}
 	async replaceModel(index, config) {
 		const responses = await Promise.all(this.workers.map((w) => w.sendCommand({
 			cmd: "replace",
@@ -1203,6 +1227,7 @@ function serializeModelConfig(config) {
 	if (config.plateRegion !== void 0) result["plateRegion"] = config.plateRegion;
 	if (config.minTextLength !== void 0) result["minTextLength"] = config.minTextLength;
 	if (config.minTextConfidence !== void 0) result["minTextConfidence"] = config.minTextConfidence;
+	if (config.minCharProbability !== void 0) result["minCharProbability"] = config.minCharProbability;
 	if (config.numClasses) result["numClasses"] = config.numClasses;
 	if (config.strides) result["strides"] = config.strides;
 	if (config.maskThreshold !== void 0) result["maskThreshold"] = config.maskThreshold;
@@ -1290,10 +1315,188 @@ function pruneUnrunnableDetailSteps(steps, isDetailStep, isUnrunnable) {
 	};
 }
 //#endregion
+//#region src/detection-pipeline/registry/effective-postprocessor.ts
+function resolveEffectivePostprocessor(definition, modelId) {
+	return resolveEffectivePostprocessorForEntry(definition, modelId ? definition.models.find((m) => m.id === modelId) : void 0);
+}
+/**
+* Entry-based variant for callers that already hold the `ModelCatalogEntry` —
+* required for CUSTOM (operator-registered) models, which are NOT in
+* `definition.models` and would otherwise silently fall back to the step
+* default decode (a Frigate `yolonas` model decoded as `yolo` produces no
+* error anywhere, just zero detections).
+*/
+function resolveEffectivePostprocessorForEntry(definition, entry) {
+	return entry?.postprocessor ?? definition.postprocessor;
+}
+//#endregion
+//#region src/detection-pipeline/registry/model-knob-applicability.ts
+/** Decodes that run NMS in the pipeline (and hence consult `nmsIouThreshold`).
+*  Mirrors the Python postprocessors that read the knob — yolo.py,
+*  yolo_seg.py, rfdetr.py, scrfd.py. */
+var NMS_CONSUMING_POSTPROCESSORS = new Set([
+	"yolo",
+	"yolo-seg",
+	"rfdetr",
+	"scrfd"
+]);
+/**
+* Does this decode consult `nmsIouThreshold`?
+*
+* ONE predicate for the whole system: the UI disables the slider through
+* {@link annotateConfigSchemaForModels}, and the runtime refuses to forward a
+* value through `resolvePoolDecodeSettings` — both off this set. Two copies of
+* the matrix would let the UI promise an effect the pool does not deliver,
+* which is the failure D214 exists to remove.
+*/
+function postprocessorConsumesNms(postprocessor) {
+	return NMS_CONSUMING_POSTPROCESSORS.has(postprocessor);
+}
+var MIN_CONFIDENCE_MACRO_PREFIX = "minConfidence";
+/** `minConfidencePerson` → `person`; bare `minConfidence` → null (generic). */
+function macroOfMinConfidenceKey(key) {
+	if (!key.startsWith(MIN_CONFIDENCE_MACRO_PREFIX)) return null;
+	const rest = key.slice(13);
+	if (rest.length === 0) return null;
+	return rest.charAt(0).toLowerCase() + rest.slice(1);
+}
+/**
+* The macro classes a model's OWN labelmap can reach through the step's
+* classMap. `undefined` ⇒ the model declares no labels (catalog default
+* labelmap) — every macro of the step is reachable, nothing to annotate.
+*/
+function reachableMacros(def, entry) {
+	if (entry.labels.length === 0) return void 0;
+	const map = def.classMap;
+	if (!map) return new Set(entry.labels.map((l) => l.id));
+	if (map.preserveOriginal) return void 0;
+	const macros = /* @__PURE__ */ new Set();
+	for (const label of entry.labels) {
+		const mapped = map.mapping[label.id];
+		if (mapped !== void 0) macros.add(mapped);
+	}
+	return macros;
+}
+/**
+* The labels a custom model declares that the step's dropping classMap
+* (`preserveOriginal: false`) removes UPSTREAM of every operator setting.
+* `null` when the model declares no labels, the step has no classMap, the map
+* preserves originals, or nothing is dropped. The engine factory logs this at
+* pool-config time — a dropped class must never be silent (CLAUDE.md logging
+* rule; the discard trail alone answers "what", not "why zero forever").
+*/
+function collectClassMapDropWarning(def, entry) {
+	if (entry.labels.length === 0) return null;
+	const map = def.classMap;
+	if (!map || map.preserveOriginal) return null;
+	const unmapped = entry.labels.filter((l) => map.mapping[l.id] === void 0).map((l) => l.id);
+	if (unmapped.length === 0) return null;
+	return {
+		unmappedLabels: unmapped,
+		mappedCount: entry.labels.length - unmapped.length
+	};
+}
+function toApplicability(acc) {
+	const hasInapplicable = Object.keys(acc.inapplicable).length > 0;
+	const hasOptions = Object.keys(acc.optionsByModel).length > 0;
+	if (!hasInapplicable && !hasOptions) return void 0;
+	return {
+		...hasInapplicable ? { inapplicable: acc.inapplicable } : {},
+		...hasOptions ? { optionsByModel: acc.optionsByModel } : {}
+	};
+}
+function isAnnotatable(field) {
+	return field.type === "slider" || field.type === "number" || field.type === "multiselect" || field.type === "select" || field.type === "boolean";
+}
+function annotateField(field, inputs) {
+	if (!isAnnotatable(field)) return field;
+	const { def, models, customModelIds } = inputs;
+	const acc = {
+		inapplicable: {},
+		optionsByModel: {}
+	};
+	const macroKey = macroOfMinConfidenceKey(field.key);
+	for (const entry of models) {
+		const postprocessor = resolveEffectivePostprocessorForEntry(def, entry);
+		if (field.key === "nmsIouThreshold" && !postprocessorConsumesNms(postprocessor)) {
+			acc.inapplicable[entry.id] = `NMS is fused inside this model's "${postprocessor}" export — the pipeline IoU threshold is not consulted.`;
+			continue;
+		}
+		if (field.key === "rectify" && postprocessor !== "ctc") {
+			acc.inapplicable[entry.id] = `The "${postprocessor}" reader consumes the raw plate box — its crop policy never deskews, so this switch has no effect.`;
+			continue;
+		}
+		if (macroKey !== null) {
+			const macros = reachableMacros(def, entry);
+			if (macros !== void 0 && !macros.has(macroKey)) acc.inapplicable[entry.id] = `This model's labelmap cannot produce "${macroKey}" — the slider filters a class that never arrives.`;
+			continue;
+		}
+		if (field.key === "enabledMacroClasses" && field.type === "multiselect") {
+			const macros = reachableMacros(def, entry);
+			if (macros === void 0) continue;
+			const reachable = field.options.filter((o) => macros.has(o.value));
+			if (reachable.length === 0) acc.inapplicable[entry.id] = "None of this model's labels map to a macro class the pipeline tracks — every detection it emits is dropped upstream of this filter.";
+			else if (reachable.length < field.options.length) acc.optionsByModel[entry.id] = reachable.map((o) => ({
+				value: o.value,
+				label: o.label
+			}));
+			continue;
+		}
+		if (field.key === "enabledClasses" && field.type === "multiselect" && customModelIds.has(entry.id) && entry.labels.length > 0) {
+			acc.optionsByModel[entry.id] = entry.labels.map((l) => ({
+				value: l.id,
+				label: l.name
+			}));
+			continue;
+		}
+	}
+	const applicability = toApplicability(acc);
+	if (applicability === void 0) return field;
+	return {
+		...field,
+		modelApplicability: applicability
+	};
+}
+/**
+* Decorate a step's config schema with per-model applicability, computed from
+* the same model union the picker offers. Fields with nothing to say are
+* returned untouched (identity), so a static-only step with fully-consuming
+* models produces a byte-identical schema.
+*/
+function annotateConfigSchemaForModels(inputs) {
+	return inputs.configSchema.map((field) => annotateField(field, inputs));
+}
+/**
+* A persisted settings blob is external data — it survives schema changes,
+* hand edits and migrations. Accept only a finite IoU in the open (0,1)
+* interval; anything else falls back rather than reaching the decode, where a
+* 0 would suppress every overlapping box and a 1 would suppress none.
+*/
+function readIouThreshold(value) {
+	if (typeof value !== "number" || !Number.isFinite(value)) return void 0;
+	if (value <= 0 || value >= 1) return void 0;
+	return value;
+}
+/** The effective decode-scoped values for a `(step, model)` pair. */
+function resolvePoolDecodeSettings(inputs) {
+	const fallback = readIouThreshold(inputs.fallbackNmsIouThreshold) ?? .45;
+	if (!postprocessorConsumesNms(resolveEffectivePostprocessorForEntry(inputs.def, inputs.modelEntry))) return { nmsIouThreshold: fallback };
+	return { nmsIouThreshold: readIouThreshold(inputs.settings?.["nmsIouThreshold"]) ?? fallback };
+}
+/** What a built pool config actually carries — the state the slot is IN after
+*  a `load`, so the manager's diff is anchored to the command it sent, never
+*  to a second derivation of the same inputs. */
+function poolDecodeSettingsOf(config) {
+	return { nmsIouThreshold: config.nmsIouThreshold ?? .45 };
+}
+function poolDecodeSettingsEqual(a, b) {
+	return a.nmsIouThreshold === b.nmsIouThreshold;
+}
+//#endregion
 //#region src/detection-pipeline/engine/pipeline-model-manager.ts
 var PipelineModelManager = class {
 	pool;
-	buildPoolConfig;
+	source;
 	/** stepId → modelId → loaded entry. */
 	loaded = /* @__PURE__ */ new Map();
 	/** stepId → currently-active modelId (the runtime choice). */
@@ -1302,9 +1505,9 @@ var PipelineModelManager = class {
 	lruClock = 0;
 	log;
 	maxModelsPerStep;
-	constructor(pool, buildPoolConfig, logger, options) {
+	constructor(pool, source, logger, options) {
 		this.pool = pool;
-		this.buildPoolConfig = buildPoolConfig;
+		this.source = source;
 		this.log = logger;
 		this.maxModelsPerStep = options?.maxModelsPerStep ?? 4;
 	}
@@ -1328,7 +1531,7 @@ var PipelineModelManager = class {
 			} });
 		}
 		for (const added of diff.added) {
-			await this.ensureLoaded(added.addonId, added.modelId);
+			await this.ensureLoaded(added.addonId, added.modelId, added.settings);
 			this.activeByStep.set(added.addonId, added.modelId);
 			this.log.info("Step loaded", { meta: {
 				step: added.addonId,
@@ -1337,7 +1540,7 @@ var PipelineModelManager = class {
 			} });
 		}
 		for (const { step, oldModelId } of diff.modelChanged) {
-			await this.ensureLoaded(step.addonId, step.modelId);
+			await this.ensureLoaded(step.addonId, step.modelId, step.settings);
 			this.activeByStep.set(step.addonId, step.modelId);
 			this.log.info("Active model switched", { meta: {
 				step: step.addonId,
@@ -1346,6 +1549,7 @@ var PipelineModelManager = class {
 			} });
 			await this.enforceLruCap(step.addonId);
 		}
+		for (const { entry, step } of diff.unchanged) await this.reconcileDecode(entry, step.settings);
 	}
 	/**
 	* Get an `IInferenceEngine` handle. Without `modelId`, returns the
@@ -1367,6 +1571,22 @@ var PipelineModelManager = class {
 	isLoadedWithModel(stepId, modelId) {
 		return this.loaded.get(stepId)?.has(modelId) ?? false;
 	}
+	/**
+	* Does the pool NOT yet reflect this step? True when the (step, model) pair
+	* is absent, and also when it is resident with different decode-scoped
+	* settings — the case `isLoadedWithModel` cannot see.
+	*
+	* This is the per-dispatch skip gate: callers that short-circuit on
+	* "already loaded" were the reason a saved threshold never reached a
+	* running pool. Cheap by contract — `resolveDecode` never touches the fs.
+	*/
+	needsPoolUpdate(step) {
+		const entry = this.loaded.get(step.addonId)?.get(step.modelId);
+		if (!entry) return true;
+		const desired = this.source.resolveDecode(step.addonId, step.modelId, step.settings);
+		if (desired === null) return true;
+		return !poolDecodeSettingsEqual(entry.decode, desired);
+	}
 	/** ModelId currently designated as active for the step. */
 	getLoadedModelId(stepId) {
 		return this.activeByStep.get(stepId);
@@ -1418,8 +1638,7 @@ var PipelineModelManager = class {
 	*/
 	async loadAdditional(steps) {
 		for (const step of steps) {
-			if (this.isLoadedWithModel(step.addonId, step.modelId)) continue;
-			await this.ensureLoaded(step.addonId, step.modelId);
+			await this.ensureLoaded(step.addonId, step.modelId, step.settings);
 			if (!this.activeByStep.has(step.addonId)) this.activeByStep.set(step.addonId, step.modelId);
 		}
 	}
@@ -1428,7 +1647,7 @@ var PipelineModelManager = class {
 	* Honors `maxModelsPerStep` — evicts a non-active LRU variant first
 	* when the cap would otherwise be exceeded.
 	*/
-	async ensureLoaded(stepId, modelId) {
+	async ensureLoaded(stepId, modelId, settings) {
 		let perStep = this.loaded.get(stepId);
 		if (!perStep) {
 			perStep = /* @__PURE__ */ new Map();
@@ -1437,6 +1656,7 @@ var PipelineModelManager = class {
 		const existing = perStep.get(modelId);
 		if (existing) {
 			this.touch(existing);
+			await this.reconcileDecode(existing, settings);
 			return existing;
 		}
 		while (perStep.size >= this.maxModelsPerStep) {
@@ -1451,11 +1671,13 @@ var PipelineModelManager = class {
 			} });
 		}
 		const index = this.pool.allocateIndex();
-		const config = this.buildPoolConfig(stepId, modelId);
+		const config = this.source.buildConfig(stepId, modelId, settings);
+		const decode = poolDecodeSettingsOf(config);
 		this.log.info("Loading step variant", { meta: {
 			step: stepId,
 			modelId,
-			poolIndex: index
+			poolIndex: index,
+			...decode
 		} });
 		const { loadMs } = await this.pool.loadModel(index, config);
 		this.log.info("Step variant loaded", { meta: {
@@ -1468,11 +1690,71 @@ var PipelineModelManager = class {
 			stepId,
 			modelId,
 			poolIndex: index,
-			lruTick: ++this.lruClock
+			lruTick: ++this.lruClock,
+			decode
 		};
 		perStep.set(modelId, entry);
 		return entry;
 	}
+	/**
+	* Push a retuned decode setting into ONE already-loaded slot.
+	*
+	* Scope is the point: `reconfigure` names a single pool index, so a slider
+	* moved on `object-detection/yolo26n` never disturbs the face detector, the
+	* classifiers, or the same step's warm benchmark variants — and it never
+	* costs a session reload (see `SharedInferencePool.reconfigureModel`).
+	*
+	* A no-op when nothing moved: this runs on the per-dispatch path, so the
+	* common case must send zero commands.
+	*/
+	async reconcileDecode(entry, settings) {
+		const desired = this.source.resolveDecode(entry.stepId, entry.modelId, settings);
+		if (desired === null) return;
+		if (poolDecodeSettingsEqual(entry.decode, desired)) return;
+		const previous = entry.decode;
+		await this.pool.reconfigureModel(entry.poolIndex, desired);
+		entry.decode = desired;
+		this.log.info("Decode settings retuned in place — no model reload", { meta: {
+			step: entry.stepId,
+			modelId: entry.modelId,
+			poolIndex: entry.poolIndex,
+			previousNmsIouThreshold: previous.nmsIouThreshold,
+			...desired
+		} });
+		this.reportContention(entry, previous, desired);
+	}
+	/** Decode values each (step, model) pair has already run, so a value
+	*  RETURNING can be told apart from a value being changed. */
+	decodeHistory = /* @__PURE__ */ new Map();
+	contentionReported = /* @__PURE__ */ new Set();
+	/**
+	* A pool slot is NODE-level; the settings driving it arrive per dispatch, so
+	* two cameras with different per-camera overrides for the same (step, model)
+	* pull the same slot back and forth. That is not expressible — one of them is
+	* always decoding with the other's threshold — and it is invisible from the
+	* outside, so it is reported the first time a pair flip-flops BACK to a value
+	* it already ran. One steady retune (the operator moving a slider) never
+	* trips it; alternating writers do, immediately.
+	*/
+	reportContention(entry, previous, desired) {
+		const key = `${entry.stepId}::${entry.modelId}`;
+		let seen = this.decodeHistory.get(key);
+		if (!seen) {
+			seen = new Set([previous.nmsIouThreshold]);
+			this.decodeHistory.set(key, seen);
+		}
+		const returning = seen.has(desired.nmsIouThreshold);
+		seen.add(desired.nmsIouThreshold);
+		if (!returning || this.contentionReported.has(key)) return;
+		this.contentionReported.add(key);
+		this.log.warn("Two dispatches disagree on this step’s decode settings — the pool slot is node-level, so one of them always decodes with the other’s value", { meta: {
+			step: entry.stepId,
+			modelId: entry.modelId,
+			poolIndex: entry.poolIndex,
+			valuesSeen: [...seen].sort((a, b) => a - b),
+			hint: "a per-camera override of a decode-scoped knob cannot be honoured on a shared pool — keep this knob at the node level"
+		} });
+	}
 	async unloadEntry(entry) {
 		await this.pool.unloadModel(entry.poolIndex);
 		const perStep = this.loaded.get(entry.stepId);
@@ -1538,7 +1820,10 @@ var PipelineModelManager = class {
 				step: desired,
 				oldModelId: activeModelId
 			});
-			else unchanged.push(activeEntry);
+			else unchanged.push({
+				entry: activeEntry,
+				step: desired
+			});
 		}
 		for (const [stepId, step] of desiredMap) if (!this.activeByStep.has(stepId)) added.push(step);
 		return {
@@ -1816,6 +2101,14 @@ var EngineFactory = class {
 		return this.poolManager?.isLoadedWithModel(stepId, modelId) ?? false;
 	}
 	/**
+	* Does the pool still owe this step something — a load, or a retune of its
+	* decode-scoped settings? The skip gate every dispatch path must use instead
+	* of `isLoadedWithModel`, which cannot see a changed threshold (D214).
+	*/
+	needsPoolUpdate(step) {
+		return this.poolManager?.needsPoolUpdate(step) ?? true;
+	}
+	/**
 	* List every loaded (stepId, modelId) variant — the pool surfaces each
 	* warm slot independently (including bench overrides).
 	*/
@@ -1951,54 +2244,124 @@ var EngineFactory = class {
 			numWorkers,
 			...this.opts.engine.device ? { device: this.opts.engine.device } : {}
 		});
-		this.poolManager = new PipelineModelManager(this.pool, (stepId, modelId) => this.buildPoolModelConfig(stepId, modelId, poolRuntime), this.log.child("model-mgr"));
+		this.poolManager = new PipelineModelManager(this.pool, {
+			buildConfig: (stepId, modelId, settings) => this.buildPoolModelConfig(stepId, modelId, poolRuntime, settings),
+			resolveDecode: (stepId, modelId, settings) => this.resolveDecode(stepId, modelId, settings)
+		}, this.log.child("model-mgr"));
 		await this.pool.initialize([]);
 		await this.poolManager.applyConfig(steps);
 	}
-	buildPoolModelConfig(stepId, modelId, poolRuntime) {
+	/** (step, model) pairs whose classMap-drop warning already logged — the
+	*  pool reloads models on every applyConfig; the fact doesn't change. */
+	classMapDropLogged = /* @__PURE__ */ new Set();
+	/**
+	* The fs-free half of {@link PoolModelSource} — the effective decode-scoped
+	* settings for a `(step, model, settings)` triple. Runs on the per-dispatch
+	* path, so it must resolve the catalog entry and nothing more; the label
+	* file, the format build and the model path are load-time concerns.
+	*
+	* `null` when the pair resolves to no model at all — the caller routes that
+	* to `buildConfig`, which throws the message naming the step and the model.
+	*/
+	resolveDecode(stepId, modelId, settings) {
 		const def = getStepDefinition(stepId);
-		const modelEntry = def.models.find((m) => m.id === modelId);
-		if (!modelEntry) throw new Error(`Model "${modelId}" not found in step "${stepId}" catalog`);
-		const format = RUNTIME_TO_FORMAT[poolRuntime];
-		if (!format) throw new Error(`No format mapping for pool runtime "${poolRuntime}"`);
-		const formatEntry = modelEntry.formats[format];
-		if (!formatEntry) throw new Error(`Model "${modelId}" has no ${format} format. Available: ${Object.keys(modelEntry.formats).join(", ")}`);
-		const urlParts = formatEntry.url.split("/");
-		const filename = urlParts[urlParts.length - 1] ?? `${modelId}.${format}`;
-		const modelPath = `${this.opts.modelsDir}/${filename}`;
-		const inputWidth = modelEntry.inputSize.width;
-		const inputHeight = modelEntry.inputSize.height;
-		const inputSize = Math.max(inputWidth, inputHeight);
-		const inputChannels = modelEntry.inputChannels ?? 3;
-		const labels = readModelLabels(this.opts.modelsDir, modelEntry) ?? def.labels;
-		return {
-			path: modelPath,
-			inputSize,
-			inputWidth,
-			inputHeight,
-			inputChannels,
-			preprocessMode: modelEntry.preprocessMode ?? "letterbox",
-			inputNormalization: modelEntry.inputNormalization,
-			outputProbabilities: modelEntry.outputProbabilities,
-			postprocessor: modelEntry.postprocessor ?? def.postprocessor,
-			confidence: resolvePoolConfidenceFloor(stepId, def.defaultConfidence),
-			nmsIouThreshold: this.opts.nmsIouThreshold ?? .45,
-			labels,
-			charset: def.charset,
-			plateRegion: def.plateRegion,
-			minTextLength: def.minTextLength,
-			minTextConfidence: def.minTextConfidence,
-			numClasses: labels?.length,
-			strides: def.postprocessor === "scrfd" ? [
-				8,
-				16,
-				32
-			] : void 0,
-			maskThreshold: def.postprocessor === "saliency" ? .5 : void 0,
-			device: this.opts.engine.device ?? (poolRuntime === "coreml" ? "all" : void 0)
-		};
+		const modelEntry = def.models.find((m) => m.id === modelId) ?? this.opts.resolveCustomModel?.(stepId, modelId);
+		if (!modelEntry) return null;
+		return resolvePoolDecodeSettings({
+			def,
+			modelEntry,
+			settings,
+			fallbackNmsIouThreshold: this.opts.nmsIouThreshold
+		});
+	}
+	buildPoolModelConfig(stepId, modelId, poolRuntime, stepSettings) {
+		return buildPoolModelConfigForStep({
+			stepId,
+			modelId,
+			poolRuntime,
+			modelsDir: this.opts.modelsDir,
+			nmsIouThreshold: this.opts.nmsIouThreshold,
+			stepSettings,
+			device: this.opts.engine.device,
+			resolveCustomModel: this.opts.resolveCustomModel,
+			onClassMapDrop: ({ stepId: sid, modelId: mid, unmappedLabels }) => {
+				const key = `${sid}::${mid}`;
+				if (this.classMapDropLogged.has(key)) return;
+				this.classMapDropLogged.add(key);
+				this.log.warn("Model labels dropped by step classMap — unreachable by any setting", { meta: {
+					step: sid,
+					modelId: mid,
+					unmappedLabels: [...unmappedLabels],
+					hint: "these classes are removed before enabledMacroClasses / minConfidence* run; only labels in the step classMap are tracked"
+				} });
+			}
+		});
 	}
 };
+/**
+* Build the Python-pool model config for `(stepId, modelId)`.
+*
+* Resolution order: static step catalog first, then the injected
+* custom-model resolver (operator-registered models from the
+* `custom-model-registry` cap). A model found in NEITHER throws — that step
+* cannot load.
+*/
+function buildPoolModelConfigForStep(inputs) {
+	const { stepId, modelId, poolRuntime, modelsDir } = inputs;
+	const def = getStepDefinition(stepId);
+	const modelEntry = def.models.find((m) => m.id === modelId) ?? inputs.resolveCustomModel?.(stepId, modelId);
+	if (!modelEntry) throw new Error(`Model "${modelId}" not found in step "${stepId}" catalog (static or custom registry)`);
+	const format = RUNTIME_TO_FORMAT[poolRuntime];
+	if (!format) throw new Error(`No format mapping for pool runtime "${poolRuntime}"`);
+	const dropWarning = collectClassMapDropWarning(def, modelEntry);
+	if (dropWarning !== null) inputs.onClassMapDrop?.({
+		stepId,
+		modelId,
+		unmappedLabels: dropWarning.unmappedLabels
+	});
+	const formatEntry = modelEntry.formats[format];
+	if (!formatEntry) throw new Error(`Model "${modelId}" has no ${format} format. Available: ${Object.keys(modelEntry.formats).join(", ")}`);
+	const urlParts = formatEntry.url.split("/");
+	const modelPath = `${modelsDir}/${urlParts[urlParts.length - 1] ?? `${modelId}.${format}`}`;
+	const inputWidth = modelEntry.inputSize.width;
+	const inputHeight = modelEntry.inputSize.height;
+	const inputSize = Math.max(inputWidth, inputHeight);
+	const inputChannels = modelEntry.inputChannels ?? 3;
+	const entryLabels = modelEntry.labels.length > 0 ? modelEntry.labels.map((l) => l.id) : void 0;
+	const labels = readModelLabels(modelsDir, modelEntry) ?? entryLabels ?? def.labels;
+	return {
+		path: modelPath,
+		inputSize,
+		inputWidth,
+		inputHeight,
+		inputChannels,
+		preprocessMode: modelEntry.preprocessMode ?? "letterbox",
+		inputNormalization: modelEntry.inputNormalization,
+		outputProbabilities: modelEntry.outputProbabilities,
+		postprocessor: resolveEffectivePostprocessorForEntry(def, modelEntry),
+		confidence: resolvePoolConfidenceFloor(stepId, def.defaultConfidence),
+		nmsIouThreshold: resolvePoolDecodeSettings({
+			def,
+			modelEntry,
+			settings: inputs.stepSettings,
+			fallbackNmsIouThreshold: inputs.nmsIouThreshold
+		}).nmsIouThreshold,
+		labels,
+		charset: def.charset,
+		plateRegion: def.plateRegion,
+		minTextLength: def.minTextLength,
+		minTextConfidence: def.minTextConfidence,
+		minCharProbability: def.minCharProbability,
+		numClasses: labels?.length,
+		strides: def.postprocessor === "scrfd" ? [
+			8,
+			16,
+			32
+		] : void 0,
+		maskThreshold: def.postprocessor === "saliency" ? .5 : void 0,
+		device: inputs.device ?? (poolRuntime === "coreml" ? "all" : void 0)
+	};
+}
 //#endregion
 //#region src/detection-pipeline/engine/idle-pool-reaper.ts
 var IdlePoolReaper = class {
@@ -3263,7 +3626,7 @@ function estimateSkewAngle(gray, opts = {}) {
 		score: bestScore
 	};
 }
-function toSharpChannels(channels) {
+function toSharpChannels$1(channels) {
 	switch (channels) {
 		case 1: return 1;
 		case 2: return 2;
@@ -3344,7 +3707,7 @@ async function rectifyPlateJpeg(jpeg, opts = {}) {
 			jpeg: await sharp(Buffer.from(band.data), { raw: {
 				width: band.width,
 				height: band.height,
-				channels: toSharpChannels(band.channels)
+				channels: toSharpChannels$1(band.channels)
 			} }).jpeg({ quality: opts.quality ?? 90 }).toBuffer(),
 			width: band.width,
 			height: band.height,
@@ -3355,6 +3718,413 @@ async function rectifyPlateJpeg(jpeg, opts = {}) {
 	}
 }
 //#endregion
+//#region src/detection-pipeline/pipeline/plate-ocr-crop-policy.ts
+/**
+* Keyed by POSTPROCESSOR, not by model id: the postprocessor is what identifies
+* the reader family, it is already what the executor branches on, and a new
+* model of an existing family inherits the right pixels without touching this
+* table. A new reader family with a new postprocessor has to add a row — which
+* is the point, since it cannot be given the wrong one by default.
+*/
+var PLATE_OCR_CROP_POLICIES = {
+	ctc: {
+		marginFraction: 0,
+		rectify: true,
+		minLongSidePx: 85
+	},
+	"plate-slots": {
+		marginFraction: .15,
+		rectify: false,
+		minLongSidePx: 70
+	}
+};
+/**
+* The crop policy for a step child, or `null` when the child is not a plate
+* reader at all (a face embedder, a classifier — nothing here applies to them).
+*/
+function resolvePlateOcrCropPolicy(postprocessor) {
+	return PLATE_OCR_CROP_POLICIES[postprocessor] ?? null;
+}
+/**
+* Grow a bbox by `marginFraction` of its own size on each side, clamped to the
+* frame. Returns the input unchanged at margin 0 or on a degenerate box, so the
+* un-margined readers keep the exact pixels they had.
+*/
+function expandBbox(bbox, marginFraction, imageWidth, imageHeight) {
+	const [x1, y1, x2, y2] = bbox;
+	const width = x2 - x1;
+	const height = y2 - y1;
+	if (!(marginFraction > 0) || !(width > 0) || !(height > 0)) return [
+		x1,
+		y1,
+		x2,
+		y2
+	];
+	return [
+		Math.max(0, x1 - width * marginFraction),
+		Math.max(0, y1 - height * marginFraction),
+		Math.min(imageWidth, x2 + width * marginFraction),
+		Math.min(imageHeight, y2 + height * marginFraction)
+	];
+}
+//#endregion
+//#region src/detection-pipeline/pipeline/plate-warp.ts
+/**
+* Plate-crop WARP — perspective rectification of a licence-plate ROI to a
+* canonical, aspect-locked text strip, run immediately before the CTC reader.
+*
+* WHY this exists on top of {@link ./plate-deskew.rectifyPlateJpeg}
+* ----------------------------------------------------------------
+* The detector hands OCR an AXIS-ALIGNED box around a plate that, on an oblique
+* camera, is a rotated trapezoid inside it. Two things then destroy the read,
+* and neither is a resolution problem:
+*
+*  1. **Aspect.** A German plate is 4.7 : 1. The boxes cam 617 produces measure
+*     1.3 – 2.0 : 1 — the box is 2-3× too tall because it circumscribes a
+*     tilted rectangle. The recognizer resizes its input to a fixed 64px height
+*     preserving aspect, so a 1.5 : 1 tile becomes ~96px wide: seven glyphs get
+*     ~13px each. The same plate rectified to 4.7 : 1 arrives ~300px wide.
+*  2. **Tilt.** The 2026-08 deskew estimator searches ±16° and REJECTS an
+*     unbracketed optimum (D186) — correct, and it means it returns 0° on this
+*     camera, whose plates sit at 24-31°. The rotation is real; the projection
+*     profile just cannot measure it from a box that is mostly car.
+*
+* The plate itself is the one thing in the ROI that is reliably a large, bright,
+* convex blob. So: Otsu-threshold the tile, keep the largest bright connected
+* component, take its four extreme corners, and sample that quadrilateral onto
+* a fixed 4.7 : 1 × 64px canvas with bilinear interpolation. One pass, no
+* OpenCV, no new dependency — sharp only decodes and re-encodes, exactly as
+* `plate-deskew.ts` and `native-child-crop.ts` do.
+*
+* MEASURED on 21 ground-truthed cam-617 plate crops (9 distinct vehicles,
+* 2026-08-20 offline replay against the production `vgg_english_g2` weights and
+* the production CTC postprocessor):
+*
+*   | chain                                  | exact | char acc | false on 18 junk ROIs |
+*   | deskew only + 100px gate (live today)  |  0/21 |   4.8 %  | 0 |
+*   | deskew + text-band + 3× upscale        |  0/21 |  16.3 %  | 0 |
+*   | THIS warp + seal-tolerant gate, 85px   |  4/21 |  42.9 %  | 0 |
+*
+* The four exact reads are four DIFFERENT vehicles at 91-98px native plate
+* width — every one of them SKIPPED entirely by the old 100px floor. Upscaling
+* and contrast work (CLAHE, autocontrast, unsharp, 2/3/4× lanczos) moved char
+* accuracy by ≤2 points on their own and are NOT included: the geometry was the
+* whole story.
+*/
+/**
+* Canonical strip geometry. 4.7 : 1 is the German plate ratio (520 × 110 mm);
+* 64px is the recognizer's own input height, so the warp writes exactly the
+* pixels the model reads and no resampling is wasted.
+*/
+var PLATE_STRIP_ASPECT = 4.7;
+/**
+* Longest side the blob search runs at. The connected-component pass is O(px)
+* with an explicit stack; capping it keeps a 600px plate ROI at ~1ms.
+*/
+var BLOB_SEARCH_MAX_DIM = 200;
+/**
+* The blob must be a plausible plate: neither a speck nor the whole tile, and
+* within a wide-but-finite aspect band. Outside these the caller keeps its
+* un-warped tile — a bad quad is far worse than no quad.
+*/
+var MIN_BLOB_AREA_FRAC = .04;
+var MAX_BLOB_AREA_FRAC = .96;
+var MIN_QUAD_ASPECT = 1.5;
+var MAX_QUAD_ASPECT = 9;
+var MIN_QUAD_WIDTH_PX = 12;
+var MIN_QUAD_HEIGHT_PX = 5;
+/**
+* Fraction of the plate width dropped from the LEFT edge before sampling.
+* The bright blob's left boundary sits on the plate's black frame / the blue EU
+* band shoulder, and that edge column decodes as a spurious leading glyph
+* ("IDND7578" for DN-D 7578). Swept end to end over the ground-truth set at
+* 0 / 2 / 3.5 / 4 / 5 / 6 / 7 %: 4 % is the peak (4/21 exact, 42.9 % char), the
+* neighbours give 3/21, and 7 % starts eating the first character (0/21).
+*/
+var LEFT_INSET_FRAC = .04;
+/** Otsu's between-class-variance threshold of a grayscale image. */
+function otsuThreshold(gray) {
+	const hist = new Float64Array(256);
+	for (let i = 0; i < gray.data.length; i++) {
+		const v = gray.data[i];
+		hist[v] = (hist[v] ?? 0) + 1;
+	}
+	const total = gray.data.length;
+	if (total === 0) return 128;
+	let sum = 0;
+	for (let v = 0; v < 256; v++) sum += v * hist[v];
+	let wB = 0;
+	let sumB = 0;
+	let best = 0;
+	let bestVar = -1;
+	for (let v = 0; v < 256; v++) {
+		wB += hist[v];
+		if (wB === 0) continue;
+		const wF = total - wB;
+		if (wF === 0) break;
+		sumB += v * hist[v];
+		const mB = sumB / wB;
+		const mF = (sum - sumB) / wF;
+		const between = wB * wF * (mB - mF) * (mB - mF);
+		if (between > bestVar) {
+			bestVar = between;
+			best = v;
+		}
+	}
+	return best;
+}
+/** `p`-th percentile (0-100) of a grayscale image, via its 256-bin histogram. */
+function percentile(gray, p) {
+	const hist = new Int32Array(256);
+	for (let i = 0; i < gray.data.length; i++) hist[gray.data[i]] = (hist[gray.data[i]] ?? 0) + 1;
+	const target = gray.data.length * p / 100;
+	let seen = 0;
+	for (let v = 0; v < 256; v++) {
+		seen += hist[v] ?? 0;
+		if (seen >= target) return v;
+	}
+	return 255;
+}
+/**
+* Mask (1/0, same dimensions) of the LARGEST 4-connected component of pixels
+* strictly above `threshold`. `null` when nothing clears the threshold.
+* Iterative flood fill — a plate ROI is small and recursion depth is not.
+*/
+function largestBrightComponent(gray, threshold) {
+	const { data, width, height } = gray;
+	const n = width * height;
+	const label = new Int32Array(n);
+	const stack = [];
+	let current = 0;
+	let bestLabel = 0;
+	let bestSize = 0;
+	for (let seed = 0; seed < n; seed++) {
+		if (label[seed] !== 0 || data[seed] <= threshold) continue;
+		current += 1;
+		label[seed] = current;
+		stack.length = 0;
+		stack.push(seed);
+		let size = 0;
+		while (stack.length > 0) {
+			const i = stack.pop();
+			size += 1;
+			const x = i % width;
+			const y = (i - x) / width;
+			if (x > 0 && label[i - 1] === 0 && data[i - 1] > threshold) {
+				label[i - 1] = current;
+				stack.push(i - 1);
+			}
+			if (x < width - 1 && label[i + 1] === 0 && data[i + 1] > threshold) {
+				label[i + 1] = current;
+				stack.push(i + 1);
+			}
+			if (y > 0 && label[i - width] === 0 && data[i - width] > threshold) {
+				label[i - width] = current;
+				stack.push(i - width);
+			}
+			if (y < height - 1 && label[i + width] === 0 && data[i + width] > threshold) {
+				label[i + width] = current;
+				stack.push(i + width);
+			}
+		}
+		if (size > bestSize) {
+			bestSize = size;
+			bestLabel = current;
+		}
+	}
+	if (bestLabel === 0) return null;
+	const out = new Uint8Array(n);
+	for (let i = 0; i < n; i++) out[i] = label[i] === bestLabel ? 1 : 0;
+	return out;
+}
+/**
+* Four corners of a mask, taken as the extreme points of `x+y` (top-left /
+* bottom-right) and `x−y` (top-right / bottom-left). Exact for a rotated
+* rectangle and stable under the blob noise of a real plate. `null` when the
+* mask is degenerate.
+*/
+function quadFromMask(mask, width, height) {
+	let minSum = Number.POSITIVE_INFINITY;
+	let maxSum = Number.NEGATIVE_INFINITY;
+	let minDif = Number.POSITIVE_INFINITY;
+	let maxDif = Number.NEGATIVE_INFINITY;
+	let tl = null;
+	let br = null;
+	let bl = null;
+	let tr = null;
+	for (let y = 0; y < height; y++) for (let x = 0; x < width; x++) {
+		if (mask[y * width + x] !== 1) continue;
+		const s = x + y;
+		const d = x - y;
+		if (s < minSum) {
+			minSum = s;
+			tl = {
+				x,
+				y
+			};
+		}
+		if (s > maxSum) {
+			maxSum = s;
+			br = {
+				x,
+				y
+			};
+		}
+		if (d < minDif) {
+			minDif = d;
+			bl = {
+				x,
+				y
+			};
+		}
+		if (d > maxDif) {
+			maxDif = d;
+			tr = {
+				x,
+				y
+			};
+		}
+	}
+	if (!tl || !tr || !br || !bl) return null;
+	const w = Math.max(dist(tl, tr), dist(bl, br));
+	const h = Math.max(dist(tl, bl), dist(tr, br));
+	if (w < MIN_QUAD_WIDTH_PX || h < MIN_QUAD_HEIGHT_PX) return null;
+	return {
+		tl,
+		tr,
+		br,
+		bl
+	};
+}
+function dist(a, b) {
+	return Math.hypot(a.x - b.x, a.y - b.y);
+}
+/**
+* Bilinear sample of the source quadrilateral onto an `outW × outH` canvas.
+* The mapping is the standard bilinear-in-(u,v) interpolation of the four
+* corners — the same family as the rotation warp in `plate-deskew.ts`, and
+* exact for the affine case. Out-of-bounds samples clamp to the edge pixel.
+*/
+function samplePerspective(src, quad, outW, outH) {
+	const { data, width: sw, height: sh, channels: ch } = src;
+	const out = new Uint8Array(outW * outH * ch);
+	const maxX = sw - 1;
+	const maxY = sh - 1;
+	for (let oy = 0; oy < outH; oy++) {
+		const v = (oy + .5) / outH;
+		for (let ox = 0; ox < outW; ox++) {
+			const u = (ox + .5) / outW;
+			const topX = quad.tl.x + (quad.tr.x - quad.tl.x) * u;
+			const topY = quad.tl.y + (quad.tr.y - quad.tl.y) * u;
+			const botX = quad.bl.x + (quad.br.x - quad.bl.x) * u;
+			const botY = quad.bl.y + (quad.br.y - quad.bl.y) * u;
+			const sx = Math.min(maxX, Math.max(0, topX + (botX - topX) * v));
+			const sy = Math.min(maxY, Math.max(0, topY + (botY - topY) * v));
+			const x0 = Math.floor(sx);
+			const y0 = Math.floor(sy);
+			const x1 = x0 < maxX ? x0 + 1 : x0;
+			const y1 = y0 < maxY ? y0 + 1 : y0;
+			const fx = sx - x0;
+			const fy = sy - y0;
+			const w00 = (1 - fx) * (1 - fy);
+			const w10 = fx * (1 - fy);
+			const w01 = (1 - fx) * fy;
+			const w11 = fx * fy;
+			const i00 = (y0 * sw + x0) * ch;
+			const i10 = (y0 * sw + x1) * ch;
+			const i01 = (y1 * sw + x0) * ch;
+			const i11 = (y1 * sw + x1) * ch;
+			const o = (oy * outW + ox) * ch;
+			for (let k = 0; k < ch; k++) out[o + k] = data[i00 + k] * w00 + data[i10 + k] * w10 + data[i01 + k] * w01 + data[i11 + k] * w11 + .5 | 0;
+		}
+	}
+	return {
+		data: out,
+		width: outW,
+		height: outH,
+		channels: ch
+	};
+}
+function toSharpChannels(channels) {
+	switch (channels) {
+		case 1: return 1;
+		case 2: return 2;
+		case 4: return 4;
+		default: return 3;
+	}
+}
+/**
+* Locate the plate blob inside `jpeg` and return it rectified to the canonical
+* {@link PLATE_STRIP_ASPECT} × {@link PLATE_STRIP_HEIGHT} strip.
+*
+* `null` — meaning "caller keeps its own tile" — on: a decode failure, a tile
+* under 16 × 8, no bright component, a component that is a speck or the whole
+* tile, or a quad outside the plate aspect band. Never throws, never returns a
+* strip it is not confident about: the un-warped tile is the floor, not a
+* guess.
+*/
+async function warpPlateJpeg(jpeg, opts = {}) {
+	const raw = await sharp(jpeg).removeAlpha().raw().toBuffer({ resolveWithObject: true }).catch(() => null);
+	if (!raw) return null;
+	const { data, info } = raw;
+	if (info.width < 16 || info.height < 8) return null;
+	const rgb = {
+		data: new Uint8Array(data.buffer, data.byteOffset, data.byteLength),
+		width: info.width,
+		height: info.height,
+		channels: info.channels
+	};
+	const gray = toGrayscale(rgb);
+	const small = downscaleGray(gray, BLOB_SEARCH_MAX_DIM);
+	const scale = small.width / gray.width;
+	const mask = largestBrightComponent(small, Math.max(otsuThreshold(small), percentile(small, 55)));
+	if (!mask) return null;
+	let area = 0;
+	for (let i = 0; i < mask.length; i++) area += mask[i];
+	const frac = area / (small.width * small.height);
+	if (frac < MIN_BLOB_AREA_FRAC || frac > MAX_BLOB_AREA_FRAC) return null;
+	const q = quadFromMask(mask, small.width, small.height);
+	if (!q) return null;
+	const up = (p) => ({
+		x: p.x / scale,
+		y: p.y / scale
+	});
+	const tl = up(q.tl);
+	const tr = up(q.tr);
+	const br = up(q.br);
+	const bl = up(q.bl);
+	const quadW = Math.max(dist(tl, tr), dist(bl, br));
+	const quadH = Math.max(dist(tl, bl), dist(tr, br));
+	if (quadW < MIN_QUAD_WIDTH_PX || quadH < MIN_QUAD_HEIGHT_PX) return null;
+	const ratio = quadW / quadH;
+	if (ratio < MIN_QUAD_ASPECT || ratio > MAX_QUAD_ASPECT) return null;
+	const inset = (a, b) => ({
+		x: a.x + (b.x - a.x) * LEFT_INSET_FRAC,
+		y: a.y + (b.y - a.y) * LEFT_INSET_FRAC
+	});
+	const warped = {
+		tl: inset(tl, tr),
+		tr,
+		br,
+		bl: inset(bl, br)
+	};
+	const outH = 64;
+	const strip = samplePerspective(rgb, warped, Math.round(outH * PLATE_STRIP_ASPECT), outH);
+	try {
+		return {
+			jpeg: await sharp(Buffer.from(strip.data), { raw: {
+				width: strip.width,
+				height: strip.height,
+				channels: toSharpChannels(strip.channels)
+			} }).jpeg({ quality: opts.quality ?? 92 }).toBuffer(),
+			width: strip.width,
+			height: strip.height
+		};
+	} catch {
+		return null;
+	}
+}
+//#endregion
 //#region src/detection-pipeline/pipeline/result-assembler.ts
 /** L2 norm of a raw embedding vector. */
 function vectorMagnitude(v) {
@@ -3438,6 +4208,13 @@ function applyChildOutput(parent, childStep, output, stepLatencyMs, ctx) {
 			const passesClass = (c) => (enabledSet === null || enabledSet.has(c.class)) && !rejectSet.has(c.class.toLowerCase());
 			const minConfidence = typeof childStep.settings?.["minConfidence"] === "number" ? childStep.settings["minConfidence"] : 0;
 			const winner = output.classifications[0];
+			if (winner && !passesClass(winner) && winner.score >= minConfidence) ctx.onClassifierClassDropped?.({
+				stepId: childStep.stepId,
+				modelId: childStep.modelId,
+				droppedClass: winner.class,
+				score: winner.score,
+				reason: enabledSet !== null && !enabledSet.has(winner.class) ? "class-not-enabled" : "reject-class"
+			});
 			if (winner && passesClass(winner) && winner.score >= minConfidence) parent.ownLabels.push({
 				label: winner.class,
 				score: winner.score,
@@ -3677,36 +4454,6 @@ var MIN_FACE_DETECTION_FLOOR_PX = 6;
 * above the downscaled detection resolution while bounding the crop payload.
 */
 var NATIVE_FACE_CROP_MAX_WIDTH = 320;
-/**
-* Minimum LONG side (px) of the ACTUAL crop fed to the plate-OCR (`ctc`) leaf —
-* the plate analogue of the face path's min-face-size gate.
-*
-* The long side, not the short one. A plate's information lives along its text
-* run: the recognizer resizes the tile to a fixed 64px height and reads left to
-* right, so what decides whether a glyph survives is how many horizontal pixels
-* each character got. The previous 20px SHORT-side floor measured the wrong
-* axis and passed essentially everything.
-*
-* The number comes from the 2026-08 audit of 11 cam-617 plate tracks with
-* ground truth. Native long side vs read:
-*
-*   117px → "DNRO3O9"  (truth DNRO309 — one glyph out, the only near-miss)
-*    82px → "VONND9592" (truth DNDS597)
-*    77px → "DEPNOQ1"   (truth DNP1091)
-*    76px → "VDHPXOE8"  (truth DNPK838)
-*    73px → "DAEOR2D8"  (truth DNDR298)
-*    ≤62px → "I0IAZ", "EUSM9", "0IA3", "DYAGI2", "I0AA", "IC1E"
-*
-* Not one read under 100px resembled its plate, and the gap between 82 and 117
-* is empty — 100 sits in it. Below this floor the OCR call is pure cost: it
-* produces a label that is wrong, and a wrong plate label is worse than none.
-*
-* Measured on the NATIVE crop when the native ROI fetch succeeded (its
-* dimensions ARE the plate's real native size — `nativeChildCrop`'s 1920 cap
-* never binds for a plate), else on the fallback detection-space tile — which
-* IS the input OCR would read, so the same floor applies honestly in both cases.
-*/
-var MIN_PLATE_OCR_LONG_SIDE_PX = 100;
 function isEnrichmentOutput(output) {
 	return output.kind === "classifications" || output.kind === "embedding" || output.kind === "text";
 }
@@ -3761,6 +4508,10 @@ var PipelineExecutor = class {
 	/** Bounds the full-frame-guard drop log: first example per (device,
 	*  class), then a counted summary per minute. See `drop-sampler.ts`. */
 	dropSampler = new DropSampler();
+	/** Bounds the classifier class-filter drop log the same way, keyed per
+	*  (device, `step:class`) — an excluded species firing on every frame of a
+	*  track must be a line and a counter, not wallpaper. */
+	classFilterDropSampler = new DropSampler();
 	constructor(opts) {
 		this.opts = opts;
 	}
@@ -3829,7 +4580,30 @@ var PipelineExecutor = class {
 		const idGen = new FrameIdGenerator();
 		const ctx = {
 			idGen,
-			details
+			details,
+			onClassifierClassDropped: (drop) => {
+				const sample = this.classFilterDropSampler.record(deviceId, `${drop.stepId}:${drop.droppedClass}`);
+				if (sample.logExample) this.opts.logger?.info("classifier winner excluded by class filter — label dropped", {
+					tags: { deviceId },
+					meta: {
+						step: drop.stepId,
+						model: drop.modelId,
+						droppedClass: drop.droppedClass,
+						score: Number(drop.score.toFixed(3)),
+						reason: drop.reason,
+						hint: "detection keeps its macro class; adjust the step enabledClasses to change this"
+					}
+				});
+				if (sample.summaryCount !== null) this.opts.logger?.info("classifier class filter: still dropping", {
+					tags: { deviceId },
+					meta: {
+						step: drop.stepId,
+						droppedClass: drop.droppedClass,
+						suppressed: sample.summaryCount,
+						windowMs: DROP_SUMMARY_INTERVAL_MS
+					}
+				});
+			}
 		};
 		let discarded;
 		const rootShed = {
@@ -4234,20 +5008,22 @@ var PipelineExecutor = class {
 						cropH = crop.height;
 					}
 				} else {
-					const nativeChild = nativeCropProvider && child.children.length === 0 ? await nativeChildCrop(nativeCropProvider, parentDetection.bbox, imageWidth, imageHeight, NATIVE_CHILD_CROP_MAX_WIDTH) : null;
+					const cropPolicy = resolvePlateOcrCropPolicy(resolveEffectivePostprocessor(child.definition, child.modelId));
+					const cropBbox = cropPolicy ? expandBbox(parentDetection.bbox, cropPolicy.marginFraction, imageWidth, imageHeight) : parentDetection.bbox;
+					const nativeChild = nativeCropProvider && child.children.length === 0 ? await nativeChildCrop(nativeCropProvider, cropBbox, imageWidth, imageHeight, NATIVE_CHILD_CROP_MAX_WIDTH) : null;
 					if (nativeChild) {
 						cropJpegBuf = nativeChild.jpeg;
 						cropW = nativeChild.width;
 						cropH = nativeChild.height;
 					} else {
-						const crop = await cropJpeg(fullFrameJpeg, parentDetection.bbox, imageWidth, imageHeight);
+						const crop = await cropJpeg(fullFrameJpeg, cropBbox, imageWidth, imageHeight);
 						cropJpegBuf = crop.jpeg;
 						cropW = crop.width;
 						cropH = crop.height;
 					}
-					if (child.definition.postprocessor === "ctc") {
+					if (cropPolicy) {
 						const plateLongSidePx = Math.max(cropW, cropH);
-						if (plateLongSidePx < MIN_PLATE_OCR_LONG_SIDE_PX) {
+						if (plateLongSidePx < cropPolicy.minLongSidePx) {
 							this.opts.logger?.info("plate ROI too small for OCR — skipping", {
 								tags: { deviceId },
 								meta: {
@@ -4255,28 +5031,44 @@ var PipelineExecutor = class {
 									model: child.modelId,
 									plateLongSidePx: Math.round(plateLongSidePx),
 									plateShortSidePx: Math.round(Math.min(cropW, cropH)),
-									minPlateLongSidePx: MIN_PLATE_OCR_LONG_SIDE_PX,
+									minPlateLongSidePx: cropPolicy.minLongSidePx,
+									marginFraction: cropPolicy.marginFraction,
 									source: nativeChild ? "native" : "detection-tile"
 								}
 							});
 							continue;
 						}
 					}
-					if (child.definition.postprocessor === "ctc" && child.settings?.["rectify"] !== false) try {
-						const rectified = await rectifyPlateJpeg(cropJpegBuf);
-						if (rectified) {
-							cropJpegBuf = rectified.jpeg;
-							cropW = rectified.width;
-							cropH = rectified.height;
-							this.opts.logger?.info("plate crop deskewed before OCR", {
+					if (cropPolicy?.rectify && child.settings?.["rectify"] !== false) try {
+						const warped = await warpPlateJpeg(cropJpegBuf);
+						if (warped) {
+							cropJpegBuf = warped.jpeg;
+							cropW = warped.width;
+							cropH = warped.height;
+							this.opts.logger?.info("plate crop warped before OCR", {
 								tags: { deviceId },
 								meta: {
 									step: child.stepId,
-									angleDeg: Number(rectified.angleDeg.toFixed(2)),
 									width: cropW,
 									height: cropH
 								}
 							});
+						} else {
+							const rectified = await rectifyPlateJpeg(cropJpegBuf);
+							if (rectified) {
+								cropJpegBuf = rectified.jpeg;
+								cropW = rectified.width;
+								cropH = rectified.height;
+								this.opts.logger?.info("plate crop deskewed before OCR", {
+									tags: { deviceId },
+									meta: {
+										step: child.stepId,
+										angleDeg: Number(rectified.angleDeg.toFixed(2)),
+										width: cropW,
+										height: cropH
+									}
+								});
+							}
 						}
 					} catch {}
 				}
@@ -4479,6 +5271,81 @@ function mergeCustomModels(staticModels, customModels) {
 	return merged;
 }
 //#endregion
+//#region src/detection-pipeline/cluster-model-resolution.ts
+/**
+* The cluster model rule, enforced on the node that has to obey it.
+*
+* ## What is different about a cluster-scoped step
+*
+* For every other step, `resolveModelForFormat` is a kindness: a chosen model
+* with no build for this node's format is quietly swapped for the format's
+* default, one info line, and the camera keeps detecting. That is the right
+* trade when the output is a box, because two nodes producing boxes with two
+* detectors are not producing anything that gets compared.
+*
+* `face-embedding` and `clip-embedding` produce vectors that land in ONE shared
+* index and are ranked against each other by cosine. There the same kindness is
+* corruption: the substituted node writes a second feature space into the index
+* and nothing in the data says so. So for a step whose definition declares
+* `modelScope: 'cluster'` this module replaces the substitution with a
+* **refusal** — the rule `runStatelessStep` already applies to a pinned model
+* ([D54](../../../../docs/decisions/adr-0056.md)), extended to the live detail
+* plane, which is the other writer into the same indexes.
+*
+* ## What "refused" means here, exactly
+*
+* It means **refused to substitute**, not "dropped". The step keeps the pinned
+* model id, and the placement machinery that already exists —
+* `resolveStepsForDispatch`'s node-local engine fallback and the detail plane's
+* `resolveDetailStepDevice` jump — keeps doing its job, both of which key off a
+* step whose model has no build for the candidate format. That is how a
+* `face-embedding` dispatched at a Coral gets rescued onto the node's onnx
+* engine today, and taking that rescue away in the name of safety would stop
+* producing faces on every mixed-accelerator node.
+*
+* What the refusal removes is the LAST resort: after the fallback and the jump,
+* a step whose model this node truly cannot serve fails loudly
+* (`assertStepsRunnable`, D39) instead of quietly running a different encoder.
+*
+* A refusal is COUNTED and logged by the caller, with `tags: { deviceId }`.
+* Silence would read as "never happened" (CLAUDE.md: a branch that drops work
+* logs it).
+*/
+var defaultLookup = (stepId) => {
+	try {
+		return getStepDefinition(stepId);
+	} catch {
+		return null;
+	}
+};
+/**
+* Decide what `stepId` runs on a node dispatching in `format`.
+*
+* An unknown step is `node-scoped`: a custom addon owns its own format
+* compatibility and this module has no catalog entry to reason about.
+*/
+function resolveClusterStepModel(stepId, clusterModels, format, lookup = defaultLookup) {
+	const def = lookup(stepId);
+	if (def === null || def.modelScope !== "cluster") return { kind: "node-scoped" };
+	const modelId = resolveClusterStepModelId(stepId, clusterModels);
+	if (modelId === null) return { kind: "node-scoped" };
+	const entry = def.models.find((m) => m.id === modelId);
+	if (entry === void 0) return {
+		kind: "pinned",
+		modelId
+	};
+	if (entry.formats[format] !== void 0) return {
+		kind: "pinned",
+		modelId
+	};
+	return {
+		kind: "refused",
+		modelId,
+		format,
+		formatsShipped: Object.keys(entry.formats)
+	};
+}
+//#endregion
 //#region src/detection-pipeline/step-resolution.ts
 /**
 * Walk `steps` (recursing into children) and return exactly the
@@ -4580,10 +5447,11 @@ 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) {
+function resolveInputSteps(steps, format, engine, clusterModels) {
 	const resolvedSteps = [];
 	const unknownAddonIds = [];
 	const substitutions = [];
+	const clusterRefusals = [];
 	for (const s of steps) {
 		let def;
 		try {
@@ -4592,6 +5460,35 @@ function resolveInputSteps(steps, format, engine) {
 			unknownAddonIds.push(s.addonId);
 			continue;
 		}
+		if (clusterModels !== void 0) {
+			const verdict = resolveClusterStepModel(s.addonId, clusterModels, format, () => def);
+			if (verdict.kind !== "node-scoped") {
+				if (verdict.kind === "refused") clusterRefusals.push({
+					stepId: s.addonId,
+					modelId: verdict.modelId,
+					format: verdict.format,
+					formatsShipped: verdict.formatsShipped
+				});
+				const childResult = s.children ? resolveInputSteps(s.children, format, engine, clusterModels) : null;
+				if (childResult) {
+					unknownAddonIds.push(...childResult.diagnostics.unknownAddonIds);
+					substitutions.push(...childResult.diagnostics.substitutions);
+					clusterRefusals.push(...childResult.diagnostics.clusterRefusals);
+				}
+				resolvedSteps.push({
+					addonId: s.addonId,
+					addonName: def.name,
+					slot: def.slot,
+					inputClasses: def.inputClasses ?? [],
+					outputClasses: def.outputClasses,
+					enabled: s.enabled,
+					modelId: verdict.modelId,
+					children: childResult ? childResult.steps : [],
+					...s.settings ? { settings: { ...s.settings } } : {}
+				});
+				continue;
+			}
+		}
 		const chosenModelId = s.modelId ?? null;
 		const runningModelId = chosenModelId === null && engine !== void 0 && s.addonId === "object-detection" ? resolveDefaultDetectionModel(engine.backend, engine.device, format) : resolveModelForFormat(s.addonId, chosenModelId, format);
 		if (chosenModelId !== null && runningModelId !== chosenModelId) substitutions.push({
@@ -4600,10 +5497,11 @@ function resolveInputSteps(steps, format, engine) {
 			running: runningModelId,
 			format
 		});
-		const childResult = s.children ? resolveInputSteps(s.children, format, engine) : null;
+		const childResult = s.children ? resolveInputSteps(s.children, format, engine, clusterModels) : null;
 		if (childResult) {
 			unknownAddonIds.push(...childResult.diagnostics.unknownAddonIds);
 			substitutions.push(...childResult.diagnostics.substitutions);
+			clusterRefusals.push(...childResult.diagnostics.clusterRefusals);
 		}
 		resolvedSteps.push({
 			addonId: s.addonId,
@@ -4621,7 +5519,8 @@ function resolveInputSteps(steps, format, engine) {
 		steps: resolvedSteps,
 		diagnostics: {
 			unknownAddonIds,
-			substitutions
+			substitutions,
+			clusterRefusals
 		}
 	};
 }
@@ -4664,6 +5563,94 @@ function applyZoneRuleGate(result, zones, rules) {
 	};
 }
 //#endregion
+//#region src/shared/cluster-model-source.ts
+/**
+* Where the runner gets the ONE cluster model choice per cluster-scoped step.
+*
+* The sibling of `crop-convention-source.ts`, and deliberately built the same
+* way, because it answers the neighbouring half of the same question: the crop
+* convention decides WHAT pixels the encoder sees, this decides WHICH encoder
+* sees them. Both are cluster-wide, both are read by the runner from the
+* `pipeline-orchestrator` global settings over the hub-routed `addon-settings`
+* cap, both pass NO `nodeId`.
+*
+* ## Deliberately NOT node-scoped, and not on the attach config
+*
+* With a `nodeId` the settings cap would project that node's scoped value and
+* two nodes could embed into one index with two encoders — the original defect,
+* relocated to the transport. And the attach config is the wrong carrier for
+* the same reason it was wrong for the crop: eleven builders construct a
+* `RunnerCameraConfig`, a cluster-wide constant threaded through eleven
+* 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
+*
+* 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.
+*/
+/**
+* The addon whose GLOBAL settings own the cluster row. Same owner as the crop
+* convention and the native-frame lease: hub-resident and neutral between the
+* addons that read it (post-analysis pins it for a re-embed pass, the runner
+* 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. */
+var ClusterModelSource = class {
+	models = DEFAULT_CLUSTER_STEP_MODELS;
+	lastReadAtMs = Number.NEGATIVE_INFINITY;
+	inFlight = null;
+	logger;
+	now;
+	ttlMs;
+	constructor(options) {
+		this.logger = options.logger;
+		this.now = options.now ?? (() => Date.now());
+		this.ttlMs = options.ttlMs ?? 6e4;
+	}
+	/** The row in force right now — the registry defaults until a read lands. */
+	current() {
+		return this.models;
+	}
+	/**
+	* Re-read if the cached row has expired. 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;
+		this.inFlight ??= this.read(api).finally(() => {
+			this.inFlight = null;
+		});
+		await this.inFlight;
+		return this.models;
+	}
+	async read(api) {
+		try {
+			const next = pickClusterStepModels(await api.addonSettings.getGlobalSettings.query({ addonId: CLUSTER_MODEL_OWNER_ADDON_ID }));
+			this.lastReadAtMs = this.now();
+			const changed = Object.keys(next).filter((stepId) => next[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: next[stepId]
+				})) } });
+				this.models = next;
+			}
+		} catch (err) {
+			this.logger.warn("cluster step model read failed — keeping the last known row", { meta: {
+				owner: CLUSTER_MODEL_OWNER_ADDON_ID,
+				inUse: { ...this.models },
+				error: err instanceof Error ? err.message : String(err)
+			} });
+		}
+	}
+};
+//#endregion
 //#region src/detection-pipeline/provider.ts
 /**
 * DetectionPipelineProvider — implements IPipelineExecutorProvider.
@@ -4929,6 +5916,17 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 	*/
 	customModelsCache = null;
 	/**
+	* 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
+	* 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);
+	/**
 	* Per-device {@link DeviceProxy} cache used for zone gating at the
 	* runtime path. Reads `state.zones.value` + `state.zoneRules.value`
 	* synchronously per frame so detections inside an `exclude` zone
@@ -4938,6 +5936,19 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 	deviceProxies = /* @__PURE__ */ new Map();
 	proxyUnsubs = /* @__PURE__ */ new Map();
 	/**
+	* The cluster-wide model row for `modelScope: 'cluster'` steps
+	* (`face-embedding`, `clip-embedding`) — read from the orchestrator's global
+	* settings, cluster-scoped, TTL-cached. See `shared/cluster-model-source.ts`
+	* for why it is not carried on the attach config and never node-scoped.
+	*
+	* Refreshed on the ASYNC boundary (`runPipeline`) and read SYNCHRONOUSLY by
+	* `inputStepsToPipelineSteps`, which runs per dispatch and must not await.
+	*/
+	clusterModels = new ClusterModelSource({ logger: {
+		info: (message, extras) => this.log.info(message, extras),
+		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
 	* (not on every frame). `runPipeline` is called once per decoded
@@ -6024,6 +7035,7 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 		};
 	}
 	async runPipeline(input, onProgress) {
+		await this.clusterModels.refresh(this.addonCtx?.api);
 		const nodeId = this.addonCtx?.kernel?.localNodeId ?? "hub";
 		const sessionId = input.sessionId ?? `run-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
 		const emit = (message, extra) => {
@@ -6208,7 +7220,8 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 				modelsDir: this.modelsDir,
 				logger: this.log.child("engine-override"),
 				pythonPath: this.executorOptions.pythonPath ?? "",
-				provisioning: this.executorOptions.provisioning
+				provisioning: this.executorOptions.provisioning,
+				resolveCustomModel: this.customModelResolver
 			});
 			const initPromise = newFactory.initialize([]);
 			this.overrideCache = {
@@ -6252,7 +7265,7 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 			this.executor = executor;
 			const dispatchEngine = dispatchDeviceKey ? resolveDeviceEngine(dispatchDeviceKey) : runEngine;
 			const dispatchFactory = dispatchDeviceKey ? await this.resolveDeviceFactory(dispatchDeviceKey) : this.engineFactory;
-			const needed = enabledSteps.filter((s) => !dispatchFactory.isLoadedWithModel(s.addonId, s.modelId));
+			const needed = enabledSteps.filter((s) => dispatchFactory.needsPoolUpdate(s));
 			if (needed.length > 0) {
 				this.log.info("Benchmark: models to load", { meta: {
 					count: needed.length,
@@ -6388,7 +7401,8 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 				modelsDir: this.modelsDir,
 				logger: this.log.child("engine-override"),
 				pythonPath: this.executorOptions.pythonPath ?? "",
-				provisioning: this.executorOptions.provisioning
+				provisioning: this.executorOptions.provisioning,
+				resolveCustomModel: this.customModelResolver
 			});
 			const initPromise = newFactory.initialize([]);
 			this.overrideCache = {
@@ -6482,8 +7496,9 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 	inputStepsToPipelineSteps(steps, format = this.currentEngine.format, engine = {
 		backend: this.currentEngine.backend,
 		device: this.currentEngine.device ?? null
-	}) {
-		const { steps: resolvedSteps, diagnostics } = resolveInputSteps(steps, format, engine);
+	}, clusterRefusalsOut) {
+		const { steps: resolvedSteps, diagnostics } = resolveInputSteps(steps, format, engine, this.clusterModels.current());
+		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: {
 			step: sub.addonId,
@@ -6493,6 +7508,34 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 		} }));
 		return resolvedSteps;
 	}
+	/**
+	* Announce the cluster-scope refusals of the resolution that is actually
+	* being RETURNED — never of a speculative one.
+	*
+	* A refusal here means: this dispatch will run `stepId` with the cluster's
+	* chosen model on an engine that ships no build of it, and NOTHING was
+	* substituted in its place. `assertStepsRunnable` has already had its say
+	* (it throws when the catalog ships nothing at all for the format); what
+	* this line adds is the case the throw cannot see — the catalog has a build,
+	* just not of the model the cluster chose — which without this line is the
+	* quietest possible way to stop producing vectors.
+	*
+	* Deduped per (step, model, engine): a fleet of cameras on one incompatible
+	* node produces one line, not one per track.
+	*/
+	logClusterRefusals(refusals, deviceId, engineLabel) {
+		for (const refusal of refusals) this.logLiveDispatchIssueOnce(`cluster-refused:${refusal.stepId}|${refusal.modelId}|${engineLabel}`, () => this.log.warn("cluster-scoped step: this engine ships no build of the CLUSTER model and nothing was substituted — a substitute encoder would put a second feature space in a shared vector index", {
+			...deviceId !== void 0 ? { tags: { deviceId } } : {},
+			meta: {
+				step: refusal.stepId,
+				clusterModelId: refusal.modelId,
+				format: refusal.format,
+				formatsShipped: [...refusal.formatsShipped],
+				engine: engineLabel,
+				remedy: `choose a cluster model with a ${refusal.format} build, or take this engine out of the rotation for ${refusal.stepId}`
+			}
+		}));
+	}
 	/** Run `fn()` at most once per `key` for the lifetime of this provider instance. */
 	logLiveDispatchIssueOnce(key, fn) {
 		if (this.loggedLiveDispatchIssues.has(key)) return;
@@ -6554,8 +7597,10 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 		const nodeEngineLabel = `${nodeEngine.backend}/${nodeEngine.device ?? "default"} (${nodeFormat})`;
 		const deviceEngine = deviceKey ? resolveDeviceEngine(deviceKey) : void 0;
 		if (deviceKey === void 0 || deviceEngine === void 0) {
-			const steps = this.inputStepsToPipelineSteps(args.steps, nodeFormat, nodeEngine);
+			const refusals = [];
+			const steps = this.inputStepsToPipelineSteps(args.steps, nodeFormat, nodeEngine, refusals);
 			this.assertStepsRunnable(steps, nodeFormat, deviceId, [nodeEngineLabel]);
+			this.logClusterRefusals(refusals, deviceId, nodeEngineLabel);
 			return {
 				deviceKey: void 0,
 				steps
@@ -6566,14 +7611,18 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 			backend: deviceEngine.backend,
 			device: deviceEngine.device ?? null
 		};
-		const steps = this.inputStepsToPipelineSteps(args.steps, deviceFormat, deviceStepEngine);
+		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);
 		if (zeroBuild.length === 0) {
-			if (!framePlane) return {
-				deviceKey,
-				steps
-			};
+			if (!framePlane) {
+				this.logClusterRefusals(deviceRefusals, deviceId, `${deviceKey} (${deviceFormat})`);
+				return {
+					deviceKey,
+					steps
+				};
+			}
 			const pruneResult = pruneUnrunnableDetailSteps(steps, isDetailPlaneStep, (addonId) => stepHasZeroBuildsFor(addonId, deviceFormat));
 			if (pruneResult.prunedAddonIds.length > 0) {
 				const prunedList = pruneResult.prunedAddonIds.join(",");
@@ -6586,6 +7635,7 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 					}
 				}));
 			}
+			this.logClusterRefusals(deviceRefusals.filter((r) => !pruneResult.prunedAddonIds.includes(r.stepId)), deviceId, `${deviceKey} (${deviceFormat})`);
 			return {
 				deviceKey,
 				steps: pruneResult.steps
@@ -6601,8 +7651,10 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 				fallbackEngine: nodeEngineLabel
 			}
 		}));
-		const fallbackSteps = this.inputStepsToPipelineSteps(args.steps, nodeFormat, nodeEngine);
+		const fallbackRefusals = [];
+		const fallbackSteps = this.inputStepsToPipelineSteps(args.steps, nodeFormat, nodeEngine, fallbackRefusals);
 		this.assertStepsRunnable(fallbackSteps, nodeFormat, deviceId, [`${deviceKey} (${deviceFormat})`, nodeEngineLabel]);
+		this.logClusterRefusals(fallbackRefusals, deviceId, nodeEngineLabel);
 		return {
 			deviceKey: void 0,
 			steps: fallbackSteps
@@ -6654,7 +7706,7 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 		const needed = [];
 		for (const step of allEnabled) {
 			if (!step.enabled) continue;
-			if (factory?.isLoadedWithModel(step.addonId, step.modelId)) continue;
+			if (factory !== null && !factory.needsPoolUpdate(step)) continue;
 			needed.push(step);
 		}
 		if (needed.length === 0) return;
@@ -6663,6 +7715,7 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 				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,
@@ -6812,7 +7865,7 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 		try {
 			const factory = dispatchDeviceKey ? await this.resolveDeviceFactory(dispatchDeviceKey) : this.engineFactory;
 			if (!factory) throw new Error("runPipelineBatch: factory not initialised");
-			if (enabledSteps.filter((s) => !factory.isLoadedWithModel(s.addonId, s.modelId)).length > 0) await this.ensureModelsForSteps(benchmarkSteps, factory, resolveFormat);
+			if (enabledSteps.filter((s) => factory.needsPoolUpdate(s)).length > 0) await this.ensureModelsForSteps(benchmarkSteps, factory, resolveFormat);
 			const canFastPath = singleRoot && allRaw && uniformDims && factory.supportsBatch();
 			this.log.info("runPipelineBatch path decision", { meta: {
 				phase: "batch",
@@ -7068,7 +8121,8 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 				modelsDir: this.modelsDir,
 				logger: this.log.child("engine"),
 				pythonPath: this.executorOptions.pythonPath ?? "",
-				provisioning: this.executorOptions.provisioning
+				provisioning: this.executorOptions.provisioning,
+				resolveCustomModel: this.customModelResolver
 			});
 			try {
 				await factory.initialize([]);
@@ -7148,7 +8202,8 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 				modelsDir: this.modelsDir,
 				logger: this.log.child(`engine:${deviceKey}`),
 				pythonPath: this.executorOptions.pythonPath ?? "",
-				provisioning: this.executorOptions.provisioning
+				provisioning: this.executorOptions.provisioning,
+				resolveCustomModel: this.customModelResolver
 			});
 			try {
 				await factory.initialize([]);
@@ -7519,7 +8574,13 @@ function buildSchemaSlots(formats, modelsDir, customByStep) {
 		if (availableModels.length === 0) continue;
 		const slot = step.slot;
 		if (!slotMap.has(slot)) slotMap.set(slot, []);
-		const configSchema = pipelineStep.getConfigSchema();
+		const customIds = new Set((customByStep?.get(step.id) ?? []).map((m) => m.id));
+		const configSchema = annotateConfigSchemaForModels({
+			def: step,
+			configSchema: pipelineStep.getConfigSchema(),
+			models: availableModels,
+			customModelIds: customIds
+		});
 		slotMap.get(slot).push({
 			id: step.id,
 			name: step.name,
@@ -7896,7 +8957,7 @@ var DetectionPipelineAddon = class extends BaseAddon {
 					type: "select",
 					key: "batchMode",
 					label: "Batch dispatch mode",
-					description: "How the Python pool dispatches predicts. `none` = one call per frame. `window` = per-model accumulator coalesces concurrent calls within Window (ms). Auto uses the matrix-sweep default for the current backend. Applies to THIS node only.",
+					description: "How the Python pool GROUPS predict requests — it never changes a model's compiled batch SHAPE, which is derived from (engine, device) at load and is not configurable (D202). `none` = one call per frame. `window` = per-model accumulator coalesces concurrent calls within Window (ms). Auto uses the matrix-sweep default for the current backend. Applies to THIS node only.",
 					options: [
 						{
 							value: "",
@@ -7940,7 +9001,7 @@ var DetectionPipelineAddon = class extends BaseAddon {
 					type: "slider",
 					key: "maxBatchSize",
 					label: "Max batch size",
-					description: "Cap on items per batched predict call. Auto = backend default. Applies to THIS node only.",
+					description: "Cap on how many requests are GROUPED into one batched predict call. Not the model's compiled batch shape — that is derived from (engine, device) at load and is not configurable (D202); a stacked tensor is only ever built for an export that declares a flexible batch axis itself. Auto = backend default. Applies to THIS node only.",
 					min: 1,
 					max: 16,
 					step: 1,