@camstack/addon-pipeline 1.2.104 → 1.2.105

package/dist/detection-pipeline/index.mjs

@@ -1,8 +1,8 @@
 import { n as __require } from "../chunk-DnnnRqeS.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-D9sltFoR.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-BS_lPX6H.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-Dw7-9jCI.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";
@@ -1069,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",
@@ -1296,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). */
@@ -1308,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;
 	}
@@ -1334,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,
@@ -1343,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,
@@ -1352,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
@@ -1373,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);
@@ -1424,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);
 		}
 	}
@@ -1434,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();
@@ -1443,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) {
@@ -1457,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: {
@@ -1474,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);
@@ -1544,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 {
@@ -1556,21 +1835,6 @@ var PipelineModelManager = class {
 	}
 };
 //#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/engine/resolve-device-engine.ts
 /**
 * Resolve a Phase-1 device key (`<backend>:<device>`, or bare `cpu`) into the
@@ -1837,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).
 	*/
@@ -1972,19 +2244,57 @@ 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) ?? 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
+			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"
+				} });
+			}
 		});
 	}
 };
@@ -2003,6 +2313,12 @@ function buildPoolModelConfigForStep(inputs) {
 	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("/");
@@ -2024,7 +2340,12 @@ function buildPoolModelConfigForStep(inputs) {
 		outputProbabilities: modelEntry.outputProbabilities,
 		postprocessor: resolveEffectivePostprocessorForEntry(def, modelEntry),
 		confidence: resolvePoolConfidenceFloor(stepId, def.defaultConfidence),
-		nmsIouThreshold: inputs.nmsIouThreshold ?? .45,
+		nmsIouThreshold: resolvePoolDecodeSettings({
+			def,
+			modelEntry,
+			settings: inputs.stepSettings,
+			fallbackNmsIouThreshold: inputs.nmsIouThreshold
+		}).nmsIouThreshold,
 		labels,
 		charset: def.charset,
 		plateRegion: def.plateRegion,
@@ -6944,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,
@@ -7385,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;
@@ -7544,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",
@@ -8253,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,

package/dist/{dist-D9sltFoR.mjs → dist-BSWr9Qg8.mjs}

@@ -20764,6 +20764,12 @@ var CameraStatusSchema = object({
 	/** Unix timestamp (ms) when this snapshot was composed server-side. */
 	fetchedAt: number()
 });
+var InferenceDeviceExclusionReasonSchema = _enum([
+	"disabled",
+	"unavailable",
+	"cannot-host-camera-root",
+	"accelerator-preferred"
+]);
 var NodeInferenceDeviceSchema = object({
 	/** Stable per-node device key, e.g. `openvino:npu`, `edgetpu:usb`, `cpu`. */
 	key: string(),
@@ -20794,7 +20800,17 @@ var NodeInferenceDeviceSchema = object({
 	* available per format; this is the stored selection that becomes the
 	* default for EVERY camera landing on this accelerator.
 	*/
-	steps: record(string(), DeviceStepConfigSchema).optional()
+	steps: record(string(), DeviceStepConfigSchema).optional(),
+	/**
+	* `null` when the device IS a camera-root candidate on this node; otherwise
+	* the reason the dispatcher drops it. Computed by the SAME
+	* `resolveInferenceDeviceEligibility` the dispatcher runs, so this view can
+	* never disagree with the election — deriving it in the UI from
+	* `enabled`/`available` would silently miss `cannot-host-camera-root` (needs
+	* the node's model catalog) and `accelerator-preferred` (needs the node-wide
+	* "an accelerator is serving" predicate).
+	*/
+	exclusion: InferenceDeviceExclusionReasonSchema.nullable()
 });
 var NodeInferenceDevicesSchema = object({
 	nodeId: string(),
@@ -24714,7 +24730,12 @@ var ListResultSchema = object({
 	probedAt: number()
 });
 var PreferredSchema = LocalInterfaceSchema.nullable();
-var GetConnectionEndpointsResultSchema = object({ endpoints: array(object({
+/**
+* Candidate base URL for the SDK to race on connect. Order matters —
+* the SDK should attempt these top-to-bottom with a short per-candidate
+* timeout (e.g. 1500ms) and cache the winner for the session.
+*/
+var ConnectionEndpointSchema = object({
 	/** Operator-facing label (e.g. "LAN — en0", "Public tunnel"). */
 	label: string(),
 	/** Fully-formed base URL with scheme + host + port. */
@@ -24757,7 +24778,42 @@ var GetConnectionEndpointsResultSchema = object({ endpoints: array(object({
 	* ordering between polls.
 	*/
 	priority: number()
-})).readonly() });
+});
+/**
+* Where the advertised local port came from. Ordered most → least
+* authoritative, and the whole point of returning it: a client must be able to
+* tell a FACT about the hub's socket from an echo of its own guess.
+*/
+var LocalPortSourceEnum = _enum([
+	"server-config",
+	"server-env",
+	"caller-hint",
+	"default"
+]);
+/** The port every LAN/loopback `baseUrl` in the same result was built with. */
+var AdvertisedLocalPortSchema = object({
+	port: number().int().min(1).max(65535),
+	source: LocalPortSourceEnum
+});
+var GetConnectionEndpointsResultSchema = object({
+	endpoints: array(ConnectionEndpointSchema).readonly(),
+	/**
+	* The port the hub built the LAN/loopback URLs with, and where that number
+	* came from.
+	*
+	* Returned rather than merely applied, because "the URL is right" and "the
+	* client can KNOW the URL is right" are different properties. A client that
+	* only sees a corrected URL cannot distinguish a hub that fixed the port from
+	* a hub that echoed the port the client sent, so it cannot decide whether to
+	* race the candidate or discard it. With `source` it can: anything but
+	* `caller-hint` is the hub's own socket.
+	*
+	* Absent on hubs predating this field — a client that finds it missing is
+	* talking to an echoing hub and must degrade exactly as it does for
+	* `caller-hint`.
+	*/
+	localPort: AdvertisedLocalPortSchema
+});
 /**
 * The chosen outbound endpoint for notification artifacts. `baseUrl: null` =
 * AUTO (resolved from the candidate ranking at send time); `resolved` reports
@@ -24778,8 +24834,13 @@ var AllowedAddressesSchema = object({
 */
 addresses: array(string()).readonly() });
 method(_void(), ListResultSchema), method(_void(), PreferredSchema), method(object({
-	/** Local hub HTTP port to use in base URLs. */
-	port: number().int().min(1).max(65535),
+	/**
+	* LEGACY HINT — do not send from new code. Kept optional so clients
+	* written against the echoing contract keep working; the hub uses it
+	* only when it cannot read its own port, and says so via
+	* `localPort.source === 'caller-hint'`.
+	*/
+	port: number().int().min(1).max(65535).optional(),
 	/** Include `http(s)://127.0.0.1:<port>` as the lowest-priority
 	*  candidate. Default `true`. */
 	includeLoopback: boolean().optional(),