@camstack/addon-pipeline 1.2.31 → 1.2.37

package/dist/detection-pipeline/index.js

@@ -4,7 +4,7 @@ Object.defineProperties(exports, {
 });
 const require_chunk = require("../chunk-emK7D4bc.js");
 const require_dist = require("../dist-BvFLZyhW.js");
-const require_step_definitions = require("../step-definitions-gC-Ovglc.js");
+const require_step_definitions = require("../step-definitions-i8O-hxyI.js");
 const require_node_topology_platform = require("../node-topology-platform-CFZ7F4xW.js");
 const require_model_download_service_Cp9f4dk6 = require("../model-download-service-Cp9f4dk6-fsdDExML.js");
 let node_os = require("node:os");
@@ -16,6 +16,7 @@ let node_fs = require("node:fs");
 node_fs = require_chunk.__toESM(node_fs);
 let node_path = require("node:path");
 node_path = require_chunk.__toESM(node_path);
+let node_perf_hooks = require("node:perf_hooks");
 //#region src/detection-pipeline/runtimes.ts
 var KNOWN_PLATFORMS = [
 	"darwin",
@@ -251,43 +252,6 @@ function normalizeEngineNodeId(rawNodeId) {
 	return raw.includes("/") ? raw.split("/")[0] ?? "hub" : raw;
 }
 //#endregion
-//#region src/detection-pipeline/pipeline/native-crop-compose.ts
-/** Clamp `v` into `[lo, hi]`. */
-function clamp(v, lo, hi) {
-	if (v < lo) return lo;
-	if (v > hi) return hi;
-	return v;
-}
-/**
-* Compose a child `roi` given in the parent CROP's normalized space into the
-* FRAME's normalized space, given the crop's frame-space pixel rectangle and the
-* frame dimensions. The result is clamped to the unit square (origin in
-* `[0,1]`, extent bounded so `x + w ≤ 1` and `y + h ≤ 1`). Returns `null` for
-* degenerate inputs (non-finite frame dims, empty crop rect, or an ROI that
-* clamps to zero area) so the caller falls back to the downscaled tile crop.
-*
-* Pure — never mutates its arguments.
-*/
-function composeCropRoiToFrameNorm(roi, cropFrameSpace, frameWidth, frameHeight) {
-	if (!(frameWidth > 0) || !(frameHeight > 0)) return null;
-	if (!(cropFrameSpace.w > 0) || !(cropFrameSpace.h > 0)) return null;
-	const fx = (cropFrameSpace.x + roi.x * cropFrameSpace.w) / frameWidth;
-	const fy = (cropFrameSpace.y + roi.y * cropFrameSpace.h) / frameHeight;
-	const fw = roi.w * cropFrameSpace.w / frameWidth;
-	const fh = roi.h * cropFrameSpace.h / frameHeight;
-	const x = clamp(fx, 0, 1);
-	const y = clamp(fy, 0, 1);
-	const w = clamp(fw, 0, 1 - x);
-	const h = clamp(fh, 0, 1 - y);
-	if (!(w > 0) || !(h > 0)) return null;
-	return {
-		x,
-		y,
-		w,
-		h
-	};
-}
-//#endregion
 //#region src/detection-pipeline/default-detection-model.ts
 /** The object-detection step id — the only slot this resolver applies to. */
 var OBJECT_DETECTION_STEP_ID$1 = "object-detection";
@@ -338,10 +302,12 @@ function classifyAccelerator(backend, device) {
 *
 * Guarantees:
 *   - never throws (hot default-tree path);
-*   - never returns a model id that is not in the object-detection catalog
-*     with a build for `format` — an unmapped backend, a `'cpu'` class, a
-*     mapped id missing from the catalog, or a mapped id without a `format`
-*     build all fall back to the step's own `defaultModelId` (`yolo26n`).
+*   - never returns a model id without a build for `format` (unless the step
+*     has ZERO builds for `format`, which is unloadable regardless of pick and
+*     flagged by `collectZeroBuildIssues`) — an unmapped backend, a `'cpu'`
+*     class, a mapped id missing from the catalog, or a mapped id without a
+*     `format` build all fall back to the step's PER-FORMAT default
+*     (`getDefaultModelForFormatFromDef`), NOT the bare `defaultModelId`.
 *
 * `getStepDef` is injectable (defaults to the real catalog lookup) so the
 * missing-build fallback branch is unit-testable without a live catalog —
@@ -354,12 +320,12 @@ function resolveDefaultDetectionModel(backend, device, format, getStepDef = requ
 	} catch {
 		return "yolo26n";
 	}
-	const fallback = def.defaultModelId;
 	const candidate = MODEL_BY_CLASS[classifyAccelerator(backend, device)];
-	if (candidate === null) return fallback;
-	const entry = def.models.find((m) => m.id === candidate);
-	if (!entry || entry.formats[format] === void 0) return fallback;
-	return candidate;
+	if (candidate !== null) {
+		const entry = def.models.find((m) => m.id === candidate);
+		if (entry && entry.formats[format] !== void 0) return candidate;
+	}
+	return require_step_definitions.getDefaultModelForFormatFromDef(def, format);
 }
 //#endregion
 //#region src/detection-pipeline/engine/shared-inference-pool.ts
@@ -476,10 +442,7 @@ var PoolHandle = class {
 	}
 	async infer(input) {
 		const start = performance.now();
-		return {
-			structured: input.kind === "raw" ? await this.pool.inferRaw(this.modelIndex, input.data, input.width, input.height, input.format) : await this.pool.infer(this.modelIndex, input.data),
-			inferenceMs: performance.now() - start
-		};
+		return poolResultToEngineOutput(input.kind === "raw" ? await this.pool.inferRaw(this.modelIndex, input.data, input.width, input.height, input.format) : await this.pool.infer(this.modelIndex, input.data), performance.now() - start);
 	}
 	/**
 	* Inference on a frame previously cached in the Python pool via
@@ -488,20 +451,50 @@ var PoolHandle = class {
 	*/
 	async inferFromCache(frameId) {
 		const start = performance.now();
-		return {
-			structured: await this.pool.inferCached(this.modelIndex, frameId),
-			inferenceMs: performance.now() - start
-		};
+		return poolResultToEngineOutput(await this.pool.inferCached(this.modelIndex, frameId), performance.now() - start);
 	}
 	async dispose() {}
 };
 /**
+* Map a raw pool response record to an {@link EngineOutput}.
+*
+* An overload shed (`{dropped: true}` — from the Python pool's per-model bound
+* OR the TS worker in-flight cap, which deliberately mirrors it) becomes a
+* first-class `EngineOutput.dropped` with NO `structured` payload. Before this
+* mapping the shed record rode through as `structured`, failed the StepOutput
+* kind guard in the postprocess funnel, and every deliberate shed was logged
+* as `runInference failed … unexpected kind: undefined` at error level on
+* every node (~4/s cluster-wide, 2026-08-01). A shed is flow control, not a
+* fault — it must never reach a postprocessor. Exported for tests.
+*/
+function poolResultToEngineOutput(result, inferenceMs) {
+	if (result["dropped"] === true) {
+		const shedReason = result["shedReason"];
+		return {
+			dropped: true,
+			...typeof shedReason === "string" ? { shedReason } : {},
+			inferenceMs
+		};
+	}
+	return {
+		structured: result,
+		inferenceMs
+	};
+}
+/**
 * How long to wait for a worker to exit on SIGTERM before escalating to
 * SIGKILL. A worker idle between frames exits well under this; only a worker
 * stuck in a native inference call (openvino/onnx C++) needs the escalation.
 */
 var POOL_WORKER_TERM_GRACE_MS = 2e3;
 /**
+* Sampling stride for the "Python pool shed frame under overload" debug
+* line — see `trackDroppedResponse`. At the observed chronic-overload rate
+* (~13 shed/s, 2026-08-01) a stride of 500 yields roughly one line every
+* 40 s while `droppedTotal` in the line keeps the exact count.
+*/
+var SHED_LOG_SAMPLE_EVERY = 500;
+/**
 * Terminate a spawned child GRACEFULLY THEN FORCEFULLY: end stdin, send
 * SIGTERM, and if the process hasn't exited within `graceMs`, send SIGKILL.
 * Resolves once the process has exited (or was already dead).
@@ -605,8 +598,12 @@ var PoolWorker = class {
 			this.ready = false;
 		});
 		this.process.stdout.on("data", (chunk) => {
+			const t0 = Date.now();
 			this.receiveBuffer = Buffer.concat([this.receiveBuffer, chunk]);
+			this.recvConcatMs += Date.now() - t0;
+			if (this.receiveBuffer.length > this.recvPeakBytes) this.recvPeakBytes = this.receiveBuffer.length;
 			this.drainResponses();
+			this.reportRecvCostIfDue();
 		});
 		const config = {
 			runtime: this.opts.poolRuntime,
@@ -793,7 +790,7 @@ var PoolWorker = class {
 					device: this.opts.device ?? "default",
 					inFlight: this.pending.size,
 					reqId,
-					timeoutMs: POOL_INFER_TIMEOUT_MS
+					timeoutMs
 				} });
 				reject(/* @__PURE__ */ new Error(`PoolWorker[${this.opts.workerLabel}]: inference request ${reqId} timed out after ${timeoutMs}ms (worker alive, no reply)`));
 			}
@@ -849,6 +846,36 @@ var PoolWorker = class {
 	ensureReady() {
 		if (!this.ready || !this.process?.stdin) throw new Error(`PoolWorker[${this.opts.workerLabel}]: not initialized`);
 	}
+	/** Time spent in `Buffer.concat` since the last report. */
+	recvConcatMs = 0;
+	/** Largest the receive buffer has grown since the last report. */
+	recvPeakBytes = 0;
+	/** When the last receive-cost report was emitted. */
+	recvReportedAt = 0;
+	/**
+	* Emit the receive-path cost at most once every 10s, and only when it is
+	* actually interesting — silence when the reader costs nothing is the whole
+	* point, otherwise this becomes another line nobody reads.
+	*/
+	reportRecvCostIfDue() {
+		const now = Date.now();
+		if (this.recvReportedAt === 0) this.recvReportedAt = now;
+		if (now - this.recvReportedAt < 1e4) return;
+		const concatMs = this.recvConcatMs;
+		const peak = this.recvPeakBytes;
+		this.recvConcatMs = 0;
+		this.recvPeakBytes = 0;
+		this.recvReportedAt = now;
+		if (concatMs < 250) return;
+		this.log.warn("pool receive path is copying", { meta: {
+			worker: this.opts.workerLabel,
+			runtime: this.opts.poolRuntime,
+			device: this.opts.device ?? "default",
+			concatMs,
+			peakBufferKb: Math.round(peak / 1024),
+			windowMs: 1e4
+		} });
+	}
 	drainResponses() {
 		while (this.receiveBuffer.length >= 8) {
 			const totalLen = this.receiveBuffer.readUInt32LE(0);
@@ -1063,13 +1090,23 @@ var SharedInferencePool = class {
 	* single-frame inference paths. Previously indistinguishable from a
 	* genuine empty detection result — now counted + debug-logged so
 	* overload is measurable. The response passes through unchanged.
+	*
+	* SAMPLED log: one line per shed frame turned into 45 741 rows/hour on
+	* the hub during the 2026-08-01 chronic overload (~13 shed/s) — 2/3 of
+	* the hub's entire log volume, burying every other signal. The counter
+	* keeps exact totals (`droppedTotal` is authoritative, surfaced in
+	* `getStatus` consumers via `getDroppedResponseCount`); the log line
+	* now fires on the FIRST shed and every `SHED_LOG_SAMPLE_EVERY`th,
+	* carrying the running total so nothing is lost — only repeated.
 	*/
 	trackDroppedResponse(result, modelIndex) {
 		if (result["dropped"] === true) {
 			this.droppedResponseCount++;
-			this.log.debug("Python pool shed frame under overload", { meta: {
+			const total = this.droppedResponseCount;
+			if (total === 1 || total % SHED_LOG_SAMPLE_EVERY === 0) this.log.debug("Python pool shed frame under overload", { meta: {
 				modelIndex,
-				droppedTotal: this.droppedResponseCount,
+				droppedTotal: total,
+				sampledEvery: SHED_LOG_SAMPLE_EVERY,
 				runtime: this.poolRuntime,
 				device: this.device ?? "default"
 			} });
@@ -1146,6 +1183,66 @@ function flattenEnabledVideoSteps(steps) {
 	walk(steps);
 	return result;
 }
+/**
+* The steps that EXECUTE in a `plane: 'frame'` dispatch (two-plane design),
+* mirroring the executor's frame-plane skip in `executeChildren`: every
+* enabled top-level step runs at the root; a CHILD runs only when its catalog
+* definition is itself root-plane (`isDetailStep(addonId)` false). The walk
+* continues only through steps that execute — a skipped detail child's
+* descendants ride ITS per-track detail-subtree call, never this one.
+* Disabled and audio-classifier steps execute on neither plane.
+*/
+function collectFramePlaneSteps(steps, isDetailStep) {
+	const result = [];
+	const walk = (nodes, topLevel) => {
+		for (const step of nodes) {
+			if (!step.enabled) continue;
+			if (step.slot === "audio-classifier") continue;
+			if (!topLevel && isDetailStep(step.addonId)) continue;
+			result.push(step);
+			if (step.children?.length) walk(step.children, false);
+		}
+	};
+	walk(steps, true);
+	return result;
+}
+/**
+* Immutably remove from a frame-plane dispatch tree every enabled DETAIL
+* subtree (at any depth below the top level) whose top step `isUnrunnable`.
+* Those steps can never load into the dispatch device's pool — leaving them
+* in the tree makes `ensureModelsForSteps` fail the whole call on a format
+* build that does not exist. They are NOT dropped work: each runs later as
+* its own detail-subtree dispatch, where the device-jump resolver
+* (`resolveStepDevice`) places it on a same-node device that can run it, or
+* warns no-candidate loudly. Runnable detail children are kept so their
+* models pre-warm the device pool as before. Disabled subtrees are kept
+* verbatim (never walked — `ensureModelsForSteps` skips them anyway).
+*/
+function pruneUnrunnableDetailSteps(steps, isDetailStep, isUnrunnable) {
+	const prunedAddonIds = [];
+	const walk = (nodes, topLevel) => {
+		const kept = [];
+		for (const step of nodes) {
+			if (!step.enabled) {
+				kept.push(step);
+				continue;
+			}
+			if (!topLevel && isDetailStep(step.addonId) && isUnrunnable(step.addonId)) {
+				prunedAddonIds.push(step.addonId);
+				continue;
+			}
+			kept.push(step.children?.length ? {
+				...step,
+				children: walk(step.children, false)
+			} : step);
+		}
+		return kept;
+	};
+	return {
+		steps: walk(steps, true),
+		prunedAddonIds
+	};
+}
 //#endregion
 //#region src/detection-pipeline/engine/pipeline-model-manager.ts
 var PipelineModelManager = class {
@@ -1543,7 +1640,7 @@ var RUNTIME_TO_FORMAT = {
 	edgetpu: "tflite"
 };
 /** The step whose detections are re-filtered downstream by the executor's
-*  per-macro `minConfidence*` sliders (`matchesMacroFilter`). Its pool-side
+*  per-macro `minConfidence*` sliders (`macroFilterVerdict`). Its pool-side
 *  floor must stay BELOW those sliders or it silently pre-empts them. */
 var OBJECT_DETECTION_STEP_ID = "object-detection";
 /**
@@ -1988,601 +2085,6 @@ var EngineProvisioner = class {
 	}
 };
 //#endregion
-//#region src/detection-pipeline/postprocess/dispatch.ts
-/** Detector NMS IoU fallback — the historical hardcoded literal, used when the
-*  step carries no `nmsIouThreshold` setting (unset == today). */
-var DEFAULT_NMS_IOU = .45;
-/**
-* Region plate grammars for the TS fallback CTC decoder (nodejs+onnx path).
-* VALIDATION-ONLY: this mirror annotates `formatValid` but does NOT rescore
-* confusables — the confusable repair needs the aligned per-timestep softmax
-* that only the Python path retains (see `python/postprocessors/ctc.py`). Keep
-* the pattern set in sync with `PLATE_GRAMMARS` there. `'off'`/unset disables it.
-*/
-var TS_PLATE_GRAMMARS = { DE: /^[A-ZÄÖÜ]{1,3}[- ]?[A-Z]{1,2}[- ]?[0-9]{1,4}[EH]?$/ };
-var VALID_KINDS = new Set([
-	"detections",
-	"classifications",
-	"embedding",
-	"text",
-	"mask"
-]);
-/**
-* Type guard: validates that a structured payload from the Python pool is a
-* well-formed StepOutput discriminated union.
-*
-* The Python inference_pool.py always sets `output.structured` with a `kind`
-* field. This guard narrows `Record<string, unknown>` to `StepOutput` without
-* resorting to double-cast.
-*/
-function isStepOutput(value) {
-	return typeof value === "object" && value !== null && typeof value["kind"] === "string" && VALID_KINDS.has(value["kind"]);
-}
-/**
-* Return the structured payload as `StepOutput`, or null if it fails validation.
-* Callers must handle null by proceeding to raw-tensor postprocessing.
-*/
-function tryStructured(output) {
-	if (!output.structured) return null;
-	if (!isStepOutput(output.structured)) throw new Error(`Python pool returned structured output with unexpected kind: ${JSON.stringify(output.structured["kind"])}`);
-	return output.structured;
-}
-function postprocessYolo(output, stepDef, nmsIouThreshold) {
-	const structured = tryStructured(output);
-	if (structured) return structured;
-	const tensor = output.tensor;
-	if (!tensor) throw new Error("YOLO postprocessor: no tensor in engine output");
-	const labels = stepDef.labels ?? [];
-	const numClasses = labels.length || 80;
-	const numBoxes = tensor.length / (4 + numClasses);
-	const letterbox = output.letterbox;
-	const dets = [];
-	for (let i = 0; i < numBoxes; i++) {
-		const cx = tensor[i];
-		const cy = tensor[1 * numBoxes + i];
-		const w = tensor[2 * numBoxes + i];
-		const h = tensor[3 * numBoxes + i];
-		let bestScore = -Infinity;
-		let bestClass = 0;
-		for (let j = 0; j < numClasses; j++) {
-			const score = tensor[(4 + j) * numBoxes + i];
-			if (score > bestScore) {
-				bestScore = score;
-				bestClass = j;
-			}
-		}
-		if (bestScore <= 0) continue;
-		let x1 = cx - w / 2;
-		let y1 = cy - h / 2;
-		let x2 = cx + w / 2;
-		let y2 = cy + h / 2;
-		if (letterbox) {
-			x1 = (x1 - letterbox.padX) / letterbox.scale;
-			y1 = (y1 - letterbox.padY) / letterbox.scale;
-			x2 = (x2 - letterbox.padX) / letterbox.scale;
-			y2 = (y2 - letterbox.padY) / letterbox.scale;
-		}
-		const label = labels[bestClass] ?? String(bestClass);
-		dets.push({
-			class: label,
-			score: bestScore,
-			bbox: [
-				x1,
-				y1,
-				x2,
-				y2
-			]
-		});
-	}
-	return {
-		kind: "detections",
-		detections: simpleNms(dets, nmsIouThreshold)
-	};
-}
-function postprocessSsd(output, _stepDef) {
-	const structured = tryStructured(output);
-	if (structured) return structured;
-	throw new Error("SSD postprocessing runs in the Python inference pool (ssd.py); no TypeScript raw-tensor path.");
-}
-function postprocessScrfd(output, stepDef, nmsIouThreshold) {
-	const structured = tryStructured(output);
-	if (structured) return structured;
-	if (!output.tensors) throw new Error("SCRFD postprocessor: no tensors in engine output");
-	const strides = [
-		8,
-		16,
-		32
-	];
-	const anchorsPerStride = 2;
-	const inputSize = Math.max(stepDef.models[0]?.inputSize.width ?? 640, stepDef.models[0]?.inputSize.height ?? 640);
-	const strideData = matchTensorsToStrides(output.tensors, strides, inputSize, anchorsPerStride);
-	const letterbox = output.letterbox;
-	const scale = letterbox?.scale ?? 1;
-	const padX = letterbox?.padX ?? 0;
-	const padY = letterbox?.padY ?? 0;
-	const origW = letterbox?.originalWidth ?? inputSize;
-	const origH = letterbox?.originalHeight ?? inputSize;
-	const candidates = [];
-	for (const stride of strides) {
-		const data = strideData.get(stride);
-		if (!data) continue;
-		const { scores, bboxes, landmarks } = data;
-		const featSize = Math.ceil(inputSize / stride);
-		const numAnchors = featSize * featSize * anchorsPerStride;
-		for (let i = 0; i < numAnchors; i++) {
-			if (i >= scores.length) break;
-			const score = scores[i];
-			if (score <= 0) continue;
-			const gridIdx = Math.floor(i / anchorsPerStride);
-			const cx = (gridIdx % featSize + .5) * stride;
-			const cy = (Math.floor(gridIdx / featSize) + .5) * stride;
-			const x1 = cx - bboxes[i * 4] * stride;
-			const y1 = cy - bboxes[i * 4 + 1] * stride;
-			const x2 = cx + bboxes[i * 4 + 2] * stride;
-			const y2 = cy + bboxes[i * 4 + 3] * stride;
-			const ox1 = Math.max(0, Math.min(origW, (x1 - padX) / scale));
-			const oy1 = Math.max(0, Math.min(origH, (y1 - padY) / scale));
-			const ox2 = Math.max(0, Math.min(origW, (x2 - padX) / scale));
-			const oy2 = Math.max(0, Math.min(origH, (y2 - padY) / scale));
-			if (ox2 - ox1 < 1 || oy2 - oy1 < 1) continue;
-			const det = {
-				class: "face",
-				score: Math.round(score * 1e4) / 1e4,
-				bbox: [
-					Math.round(ox1 * 10) / 10,
-					Math.round(oy1 * 10) / 10,
-					Math.round(ox2 * 10) / 10,
-					Math.round(oy2 * 10) / 10
-				],
-				_xyxy: [
-					ox1,
-					oy1,
-					ox2,
-					oy2
-				]
-			};
-			if (landmarks && i * 10 + 9 < landmarks.length) {
-				det.landmarks = [];
-				for (let p = 0; p < 5; p++) {
-					const lx = (cx + landmarks[i * 10 + p * 2] * stride - padX) / scale;
-					const ly = (cy + landmarks[i * 10 + p * 2 + 1] * stride - padY) / scale;
-					det.landmarks.push({
-						x: Math.round(lx * 10) / 10,
-						y: Math.round(ly * 10) / 10
-					});
-				}
-			}
-			candidates.push(det);
-		}
-	}
-	return {
-		kind: "detections",
-		detections: simpleNms(candidates.map((c) => ({
-			class: c.class,
-			score: c.score,
-			bbox: c.bbox,
-			...c.landmarks ? { landmarks: c.landmarks } : {}
-		})), nmsIouThreshold)
-	};
-}
-/** Match ONNX output tensors to SCRFD strides by expected anchor count. */
-function matchTensorsToStrides(tensors, strides, inputSize, anchorsPerStride) {
-	const scoresByN = /* @__PURE__ */ new Map();
-	const bboxesByN = /* @__PURE__ */ new Map();
-	const landmarksByN = /* @__PURE__ */ new Map();
-	for (const [, tensor] of Object.entries(tensors)) for (const stride of strides) {
-		const featSize = Math.ceil(inputSize / stride);
-		const expectedN = featSize * featSize * anchorsPerStride;
-		if (tensor.length === expectedN) scoresByN.set(expectedN, tensor);
-		else if (tensor.length === expectedN * 4) bboxesByN.set(expectedN, tensor);
-		else if (tensor.length === expectedN * 10) landmarksByN.set(expectedN, tensor);
-	}
-	const result = /* @__PURE__ */ new Map();
-	for (const stride of strides) {
-		const featSize = Math.ceil(inputSize / stride);
-		const n = featSize * featSize * anchorsPerStride;
-		const scores = scoresByN.get(n);
-		const bboxes = bboxesByN.get(n);
-		if (scores && bboxes) result.set(stride, {
-			scores,
-			bboxes,
-			landmarks: landmarksByN.get(n)
-		});
-	}
-	return result;
-}
-function postprocessArcface(output, _stepDef) {
-	const structured = tryStructured(output);
-	if (structured) return structured;
-	const tensor = output.tensor;
-	if (!tensor) throw new Error("ArcFace postprocessor: no tensor in engine output");
-	let sumSq = 0;
-	for (let i = 0; i < tensor.length; i++) sumSq += tensor[i] * tensor[i];
-	const norm = Math.sqrt(sumSq);
-	const normalized = Array.from({ length: tensor.length });
-	for (let i = 0; i < tensor.length; i++) normalized[i] = norm === 0 ? 0 : tensor[i] / norm;
-	return {
-		kind: "embedding",
-		embedding: Array.from(tensor),
-		embeddingNorm: normalized
-	};
-}
-function postprocessClip(output, _stepDef) {
-	const structured = tryStructured(output);
-	if (structured) return structured;
-	const tensor = output.tensor;
-	if (!tensor) throw new Error("CLIP postprocessor: no tensor in engine output");
-	let sumSq = 0;
-	for (let i = 0; i < tensor.length; i++) sumSq += tensor[i] * tensor[i];
-	const norm = Math.sqrt(sumSq);
-	const normalized = Array.from({ length: tensor.length });
-	for (let i = 0; i < tensor.length; i++) normalized[i] = norm === 0 ? 0 : tensor[i] / norm;
-	return {
-		kind: "embedding",
-		embedding: Array.from(tensor),
-		embeddingNorm: normalized
-	};
-}
-function postprocessSoftmax(output, stepDef) {
-	const structured = tryStructured(output);
-	if (structured) return structured;
-	const tensor = output.tensor;
-	if (!tensor) throw new Error("Softmax postprocessor: no tensor in engine output");
-	const labels = stepDef.labels ?? [];
-	let max = -Infinity;
-	for (let i = 0; i < tensor.length; i++) if (tensor[i] > max) max = tensor[i];
-	const exps = new Float32Array(tensor.length);
-	let sum = 0;
-	for (let i = 0; i < tensor.length; i++) {
-		exps[i] = Math.exp(tensor[i] - max);
-		sum += exps[i];
-	}
-	const classifications = [];
-	for (let i = 0; i < exps.length; i++) {
-		const score = exps[i] / sum;
-		if (score >= .01) classifications.push({
-			class: labels[i] ?? String(i),
-			score
-		});
-	}
-	classifications.sort((a, b) => b.score - a.score);
-	return {
-		kind: "classifications",
-		classifications: classifications.slice(0, 5)
-	};
-}
-function postprocessCtc(output, stepDef) {
-	const structured = tryStructured(output);
-	if (structured) return structured;
-	const tensor = output.tensor;
-	if (!tensor) throw new Error("CTC postprocessor: no tensor in engine output");
-	const charset = stepDef.charset ?? [];
-	const numChars = charset.length || 97;
-	const seqLen = Math.floor(tensor.length / numChars);
-	const chars = [];
-	let totalScore = 0;
-	let prev = -1;
-	for (let t = 0; t < seqLen; t++) {
-		let bestIdx = 0;
-		let bestVal = tensor[t * numChars];
-		for (let c = 1; c < numChars; c++) {
-			const val = tensor[t * numChars + c];
-			if (val > bestVal) {
-				bestVal = val;
-				bestIdx = c;
-			}
-		}
-		totalScore += bestVal;
-		if (bestIdx !== 0 && bestIdx !== prev) chars.push(charset[bestIdx] ?? "");
-		prev = bestIdx;
-	}
-	const text = chars.join("");
-	const region = stepDef.plateRegion;
-	if (region !== void 0 && region !== "off") {
-		const grammar = TS_PLATE_GRAMMARS[region];
-		if (grammar) return {
-			kind: "text",
-			text,
-			confidence: seqLen > 0 ? totalScore / seqLen : 0,
-			formatValid: grammar.test(text)
-		};
-	}
-	return {
-		kind: "text",
-		text,
-		confidence: seqLen > 0 ? totalScore / seqLen : 0
-	};
-}
-/**
-* Bounding box [x, y, w, h] (mask-pixel space) of the largest 4-connected
-* foreground component. Port of `_largest_component_bbox` from
-* `python/postprocessors/saliency.py`.
-*
-* Returns null when there are no foreground pixels.
-*/
-function largestComponentBbox(binary, w, h) {
-	const seeds = [];
-	for (let row = 0; row < h; row++) for (let col = 0; col < w; col++) if ((binary[row * w + col] ?? 0) > 0) seeds.push([row, col]);
-	if (seeds.length === 0) return null;
-	const visited = new Uint8Array(w * h);
-	let best = null;
-	for (const [sy, sx] of seeds) {
-		const seedIdx = sy * w + sx;
-		if (visited[seedIdx] === 1) continue;
-		const stack = [[sy, sx]];
-		visited[seedIdx] = 1;
-		let minX = sx;
-		let maxX = sx;
-		let minY = sy;
-		let maxY = sy;
-		let area = 0;
-		while (stack.length > 0) {
-			const [cy, cx] = stack.pop();
-			area += 1;
-			if (cx < minX) minX = cx;
-			if (cx > maxX) maxX = cx;
-			if (cy < minY) minY = cy;
-			if (cy > maxY) maxY = cy;
-			const neighbours = [
-				[cy - 1, cx],
-				[cy + 1, cx],
-				[cy, cx - 1],
-				[cy, cx + 1]
-			];
-			for (const [ny, nx] of neighbours) {
-				if (ny < 0 || ny >= h || nx < 0 || nx >= w) continue;
-				const nIdx = ny * w + nx;
-				if ((binary[nIdx] ?? 0) > 0 && visited[nIdx] !== 1) {
-					visited[nIdx] = 1;
-					stack.push([ny, nx]);
-				}
-			}
-		}
-		if (best === null || area > best.area) best = {
-			area,
-			minX,
-			minY,
-			maxX,
-			maxY
-		};
-	}
-	if (best === null) return null;
-	return [
-		best.minX,
-		best.minY,
-		best.maxX - best.minX + 1,
-		best.maxY - best.minY + 1
-	];
-}
-function postprocessSaliency(output, _stepDef) {
-	const structured = tryStructured(output);
-	if (structured) return structured;
-	const tensor = output.tensor;
-	if (!tensor) throw new Error("Saliency postprocessor: no tensor in engine output");
-	const binary = new Uint8Array(tensor.length);
-	for (let i = 0; i < tensor.length; i++) binary[i] = 1 / (1 + Math.exp(-tensor[i])) > .5 ? 255 : 0;
-	const side = Math.round(Math.sqrt(tensor.length));
-	const mask = Buffer.from(binary).toString("base64");
-	const maskBbox = largestComponentBbox(binary, side, side);
-	if (maskBbox !== null) return {
-		kind: "mask",
-		mask,
-		maskWidth: side,
-		maskHeight: side,
-		maskBbox
-	};
-	return {
-		kind: "mask",
-		mask,
-		maskWidth: side,
-		maskHeight: side
-	};
-}
-function postprocessYoloSeg(output, stepDef, nmsIouThreshold) {
-	const structured = tryStructured(output);
-	if (structured) return structured;
-	const tensors = output.tensors;
-	if (!tensors) throw new Error("YOLO-seg postprocessor: no tensors in engine output");
-	const labels = stepDef.labels ?? [];
-	const numClasses = labels.length || 80;
-	const numMaskCoeffs = 32;
-	const protoSize = 160;
-	const letterbox = output.letterbox;
-	let detTensor;
-	let protoTensor;
-	let detRows = 300;
-	let detCols = 0;
-	for (const [, tensor] of Object.entries(tensors)) {
-		if (tensor.length === numMaskCoeffs * protoSize * protoSize) {
-			protoTensor = tensor;
-			continue;
-		}
-		const cols = 38;
-		if (tensor.length % cols === 0) {
-			detTensor = tensor;
-			detRows = tensor.length / cols;
-			detCols = cols;
-			continue;
-		}
-		const rawCols = 4 + numClasses + numMaskCoeffs;
-		if (tensor.length % rawCols === 0 && !detTensor) {
-			detTensor = tensor;
-			detRows = tensor.length / rawCols;
-			detCols = rawCols;
-		}
-	}
-	if (!detTensor) throw new Error("YOLO-seg postprocessor: could not find detection tensor");
-	if (!protoTensor) throw new Error("YOLO-seg postprocessor: could not find prototype tensor");
-	const isNmsFormat = detCols === 38;
-	const dets = [];
-	for (let i = 0; i < detRows; i++) {
-		const offset = i * detCols;
-		let x1, y1, x2, y2;
-		let bestScore;
-		let bestClass;
-		let coeffStart;
-		if (isNmsFormat) {
-			x1 = detTensor[offset];
-			y1 = detTensor[offset + 1];
-			x2 = detTensor[offset + 2];
-			y2 = detTensor[offset + 3];
-			bestScore = detTensor[offset + 4];
-			bestClass = detTensor[offset + 5];
-			coeffStart = offset + 6;
-			if (bestScore <= 0) continue;
-			if (bestClass < 0) continue;
-		} else {
-			const cx = detTensor[offset];
-			const cy = detTensor[offset + 1];
-			const w = detTensor[offset + 2];
-			const h = detTensor[offset + 3];
-			bestScore = -Infinity;
-			bestClass = 0;
-			for (let j = 0; j < numClasses; j++) {
-				const score = detTensor[offset + 4 + j];
-				if (score > bestScore) {
-					bestScore = score;
-					bestClass = j;
-				}
-			}
-			if (bestScore <= 0) continue;
-			x1 = cx - w / 2;
-			y1 = cy - h / 2;
-			x2 = cx + w / 2;
-			y2 = cy + h / 2;
-			coeffStart = offset + 4 + numClasses;
-		}
-		const coeffs = new Float32Array(numMaskCoeffs);
-		for (let j = 0; j < numMaskCoeffs; j++) coeffs[j] = detTensor[coeffStart + j];
-		const maskPixels = protoSize * protoSize;
-		const maskRaw = new Float32Array(maskPixels);
-		for (let p = 0; p < maskPixels; p++) {
-			let sum = 0;
-			for (let c = 0; c < numMaskCoeffs; c++) sum += coeffs[c] * protoTensor[c * maskPixels + p];
-			maskRaw[p] = 1 / (1 + Math.exp(-sum));
-		}
-		const protoScale = protoSize / (stepDef.models[0]?.inputSize.width ?? 640);
-		const px1 = Math.max(0, Math.floor(x1 * protoScale));
-		const py1 = Math.max(0, Math.floor(y1 * protoScale));
-		const px2 = Math.min(protoSize, Math.ceil(x2 * protoScale));
-		const py2 = Math.min(protoSize, Math.ceil(y2 * protoScale));
-		const cropW = Math.max(1, px2 - px1);
-		const cropH = Math.max(1, py2 - py1);
-		const cropped = new Uint8Array(cropW * cropH);
-		for (let row = 0; row < cropH; row++) for (let col = 0; col < cropW; col++) {
-			const srcIdx = (py1 + row) * protoSize + (px1 + col);
-			cropped[row * cropW + col] = maskRaw[srcIdx] > .5 ? 255 : 0;
-		}
-		let ox1 = x1;
-		let oy1 = y1;
-		let ox2 = x2;
-		let oy2 = y2;
-		if (letterbox) {
-			ox1 = (x1 - letterbox.padX) / letterbox.scale;
-			oy1 = (y1 - letterbox.padY) / letterbox.scale;
-			ox2 = (x2 - letterbox.padX) / letterbox.scale;
-			oy2 = (y2 - letterbox.padY) / letterbox.scale;
-		}
-		const label = labels[bestClass] ?? String(bestClass);
-		const maskB64 = Buffer.from(cropped).toString("base64");
-		dets.push({
-			class: label,
-			score: Math.round(bestScore * 1e4) / 1e4,
-			bbox: [
-				Math.round(ox1 * 10) / 10,
-				Math.round(oy1 * 10) / 10,
-				Math.round(ox2 * 10) / 10,
-				Math.round(oy2 * 10) / 10
-			],
-			mask: maskB64,
-			maskWidth: cropW,
-			maskHeight: cropH
-		});
-	}
-	const keptBoxes = simpleNms(dets.map((d) => ({
-		class: d.class,
-		score: d.score,
-		bbox: d.bbox
-	})), nmsIouThreshold);
-	const keptSet = new Set(keptBoxes.map((d) => `${d.bbox[0]}_${d.bbox[1]}_${d.bbox[2]}_${d.bbox[3]}_${d.score}`));
-	return {
-		kind: "detections",
-		detections: dets.filter((d) => keptSet.has(`${d.bbox[0]}_${d.bbox[1]}_${d.bbox[2]}_${d.bbox[3]}_${d.score}`))
-	};
-}
-function postprocessYamnet(output, _stepDef) {
-	const structured = tryStructured(output);
-	if (structured) return structured;
-	throw new Error("YAMNet TypeScript postprocessing not implemented. Use Python backend or Apple SoundAnalysis.");
-}
-var DISPATCH = {
-	yolo: postprocessYolo,
-	ssd: postprocessSsd,
-	"yolo-seg": postprocessYoloSeg,
-	scrfd: postprocessScrfd,
-	arcface: postprocessArcface,
-	clip: postprocessClip,
-	softmax: postprocessSoftmax,
-	ctc: postprocessCtc,
-	saliency: postprocessSaliency,
-	yamnet: postprocessYamnet
-};
-/**
-* Dispatch postprocessing based on step definition's postprocessor type.
-*
-* For Python backends: output.structured is already populated → passthrough.
-* For Node.js ONNX: raw tensors → postprocess in TypeScript.
-*
-* Both paths pass through normalizeOutput() to ensure consistent format
-* (e.g., classification top-K, alternates).
-*/
-function dispatchPostprocess(output, stepDef, settings) {
-	const fn = DISPATCH[stepDef.postprocessor];
-	if (!fn) throw new Error(`Unknown postprocessor type: "${stepDef.postprocessor}"`);
-	const raw = settings?.["nmsIouThreshold"];
-	return normalizeOutput(fn(output, stepDef, typeof raw === "number" && raw > 0 ? raw : DEFAULT_NMS_IOU));
-}
-/**
-* Normalize any StepOutput to a consistent format.
-* Single funnel for both Python and TypeScript postprocessor paths.
-*
-* Classifications: keep only top-1 in classifications, move full list to alternates.
-*/
-function normalizeOutput(output) {
-	if (output.kind !== "classifications") return output;
-	const all = output.classifications;
-	if (all.length <= 1) return output;
-	return {
-		kind: "classifications",
-		classifications: all.slice(0, 1),
-		alternates: all
-	};
-}
-function simpleNms(dets, iouThreshold) {
-	if (dets.length === 0) return [];
-	const sorted = [...dets].toSorted((a, b) => b.score - a.score);
-	const kept = [];
-	const suppressed = /* @__PURE__ */ new Set();
-	for (let i = 0; i < sorted.length; i++) {
-		if (suppressed.has(i)) continue;
-		kept.push(sorted[i]);
-		for (let j = i + 1; j < sorted.length; j++) {
-			if (suppressed.has(j)) continue;
-			if (iou(sorted[i].bbox, sorted[j].bbox) > iouThreshold) suppressed.add(j);
-		}
-	}
-	return kept;
-}
-function iou(a, b) {
-	const ix1 = Math.max(a[0], b[0]);
-	const iy1 = Math.max(a[1], b[1]);
-	const ix2 = Math.min(a[2], b[2]);
-	const iy2 = Math.min(a[3], b[3]);
-	const inter = Math.max(0, ix2 - ix1) * Math.max(0, iy2 - iy1);
-	if (inter === 0) return 0;
-	return inter / ((a[2] - a[0]) * (a[3] - a[1]) + (b[2] - b[0]) * (b[3] - b[1]) - inter);
-}
-//#endregion
 //#region src/detection-pipeline/pipeline/crop-utils.ts
 /**
 * Crop utilities — ROI extraction and bbox coordinate transforms.
@@ -2632,34 +2134,244 @@ function isBboxDegenerate(bbox) {
 	return bbox[2] - bbox[0] < 1 || bbox[3] - bbox[1] < 1;
 }
 //#endregion
-//#region src/detection-pipeline/pipeline/face-align.ts
+//#region src/detection-pipeline/pipeline/crop-zone.ts
 /**
-* Face alignment — landmark-based similarity warp to the ArcFace template.
-*
-* ArcFace (and most face-recognition embedders) are only discriminative when
-* the input is a *landmark-aligned* 112x112 crop: eyes, nose and mouth corners
-* must land on fixed canonical positions. Feeding a raw axis-aligned bbox crop
-* stretched to 112x112 (the previous behaviour) collapses embeddings toward a
-* common direction — different people end up with ~0.99 cosine similarity.
-*
-* This module computes the least-squares similarity transform (rotation +
-* uniform scale + translation, the cv2.estimateAffinePartial2D recipe) that
-* maps SCRFD's 5 facial landmarks onto the canonical template, then resamples
-* the source pixels into a fixed-size aligned crop with bilinear interpolation.
+* Resolve the absolute-pixel crop bbox for a `crop-zone` root detector: the
+* bounding box of the UNION of every polygon referenced by the device's
+* ENABLED `package`-stage zone rules. Zone polygons are normalized (0..1); the
+* union is clamped to [0,1] then scaled to the frame's pixel dimensions.
 *
-* The warp is done in pure JS on a raw RGB buffer (a few thousand samples per
-* face — negligible cost) so it is fully deterministic and unit-testable, and
-* needs no native affine primitive nor any change to the Python inference pool.
-*/
-/**
-* Canonical ArcFace 5-point template for a 112x112 aligned crop
-* (insightface reference points). Order matches SCRFD landmark output:
-* left-eye, right-eye, nose, left-mouth-corner, right-mouth-corner.
+* Returns `null` when there is nothing usable to crop to — no enabled rules, no
+* referenced geometry, or a degenerate result — in which case the caller falls
+* back to full-frame inference (behaviour identical to before the crop-zone
+* plumbing).
 */
-var ARCFACE_TEMPLATE_112 = [
-	{
-		x: 38.2946,
-		y: 51.6963
+function resolvePackageCropBbox(zones, packageRules, frameWidth, frameHeight) {
+	if (frameWidth <= 0 || frameHeight <= 0) return null;
+	const enabledRules = packageRules.filter((r) => r.enabled !== false);
+	if (enabledRules.length === 0) return null;
+	const zoneIds = /* @__PURE__ */ new Set();
+	for (const rule of enabledRules) for (const id of rule.zoneIds) zoneIds.add(id);
+	if (zoneIds.size === 0) return null;
+	const zoneById = new Map(zones.map((z) => [z.id, z]));
+	let minX = Number.POSITIVE_INFINITY;
+	let minY = Number.POSITIVE_INFINITY;
+	let maxX = Number.NEGATIVE_INFINITY;
+	let maxY = Number.NEGATIVE_INFINITY;
+	let sawPoint = false;
+	for (const id of zoneIds) {
+		const zone = zoneById.get(id);
+		if (!zone || zone.polygon.length === 0) continue;
+		for (const point of zone.polygon) {
+			sawPoint = true;
+			if (point.x < minX) minX = point.x;
+			if (point.y < minY) minY = point.y;
+			if (point.x > maxX) maxX = point.x;
+			if (point.y > maxY) maxY = point.y;
+		}
+	}
+	if (!sawPoint) return null;
+	const clamp01 = (v) => Math.max(0, Math.min(1, v));
+	const bbox = [
+		clamp01(minX) * frameWidth,
+		clamp01(minY) * frameHeight,
+		clamp01(maxX) * frameWidth,
+		clamp01(maxY) * frameHeight
+	];
+	if (isBboxDegenerate(bbox)) return null;
+	return bbox;
+}
+//#endregion
+//#region src/detection-pipeline/postprocess/dispatch.ts
+var VALID_KINDS = new Set([
+	"detections",
+	"classifications",
+	"embedding",
+	"text",
+	"mask"
+]);
+/** Every postprocessor the Python pool implements — the dispatch table's keys
+*  survived the raw-tensor removal as a config-drift guard: an unknown
+*  postprocessor in a step definition still fails fast here. */
+var KNOWN_POSTPROCESSORS = new Set([
+	"yolo",
+	"ssd",
+	"yolo-seg",
+	"scrfd",
+	"arcface",
+	"clip",
+	"softmax",
+	"ctc",
+	"saliency",
+	"yamnet"
+]);
+/**
+* Type guard: validates that a structured payload from the Python pool is a
+* well-formed StepOutput discriminated union.
+*
+* The Python inference_pool.py always sets `output.structured` with a `kind`
+* field. This guard narrows `Record<string, unknown>` to `StepOutput` without
+* resorting to double-cast.
+*/
+function isStepOutput(value) {
+	return typeof value === "object" && value !== null && typeof value["kind"] === "string" && VALID_KINDS.has(value["kind"]);
+}
+/**
+* Validate + normalize a Python-pool engine output into a StepOutput.
+*/
+function dispatchPostprocess(output, stepDef) {
+	if (output.dropped === true) return {
+		kind: "detections",
+		detections: []
+	};
+	if (!KNOWN_POSTPROCESSORS.has(stepDef.postprocessor)) throw new Error(`Unknown postprocessor type: "${stepDef.postprocessor}"`);
+	if (!output.structured) throw new Error(`Postprocessing for step "${stepDef.id}" (${stepDef.postprocessor}) runs in the Python inference pool — the engine output carried no structured payload. The Node.js raw-tensor path was removed; there is nothing to fall back to.`);
+	if (!isStepOutput(output.structured)) throw new Error(`Python pool returned structured output with unexpected kind: ${JSON.stringify(output.structured["kind"])}`);
+	return normalizeOutput(output.structured);
+}
+/**
+* Normalize any StepOutput to a consistent format — the single funnel every
+* pool payload passes through.
+*
+* Classifications: keep only top-1 in classifications, move full list to alternates.
+*/
+function normalizeOutput(output) {
+	if (output.kind !== "classifications") return output;
+	const all = output.classifications;
+	if (all.length <= 1) return output;
+	return {
+		kind: "classifications",
+		classifications: all.slice(0, 1),
+		alternates: all
+	};
+}
+//#endregion
+//#region src/detection-pipeline/pipeline/execution-trace.ts
+var traceCounter = 0;
+var ExecutionTraceBuilder = class {
+	verbosity;
+	deviceId;
+	frameWidth;
+	frameHeight;
+	engineRuntime;
+	steps = [];
+	startTime;
+	constructor(verbosity, deviceId, frameWidth, frameHeight, engineRuntime) {
+		this.verbosity = verbosity;
+		this.deviceId = deviceId;
+		this.frameWidth = frameWidth;
+		this.frameHeight = frameHeight;
+		this.engineRuntime = engineRuntime;
+		this.startTime = Date.now();
+	}
+	/** Whether trace collection is active. */
+	get isActive() {
+		return this.verbosity !== "off";
+	}
+	/**
+	* Record a completed step execution.
+	* No-op if verbosity is 'off'.
+	*/
+	addStep(params) {
+		if (this.verbosity === "off") return;
+		const totalMs = params.preprocessMs + params.inferenceMs + params.postprocessMs;
+		const trace = {
+			stepId: params.stepId,
+			modelId: params.modelId,
+			slot: params.slot,
+			postprocessor: params.postprocessor,
+			preprocessMs: Math.round(params.preprocessMs * 100) / 100,
+			inferenceMs: Math.round(params.inferenceMs * 100) / 100,
+			postprocessMs: Math.round(params.postprocessMs * 100) / 100,
+			totalMs: Math.round(totalMs * 100) / 100,
+			inputType: params.inputType,
+			inputSize: {
+				width: params.inputWidth,
+				height: params.inputHeight
+			},
+			parentDetection: this.verbosity === "full" ? params.parentDetection : void 0,
+			outputKind: params.output.kind,
+			outputCount: countOutput(params.output),
+			topResult: this.verbosity === "full" ? formatTopResult(params.output) : void 0,
+			error: params.error
+		};
+		this.steps.push(trace);
+	}
+	/**
+	* Finalize and return the complete execution trace.
+	* Returns null if verbosity is 'off'.
+	*/
+	build(detectionCount) {
+		if (this.verbosity === "off") return null;
+		const totalMs = Date.now() - this.startTime;
+		return {
+			traceId: `trace-${Date.now()}-${++traceCounter}`,
+			deviceId: this.deviceId,
+			timestamp: this.startTime,
+			frameSize: {
+				width: this.frameWidth,
+				height: this.frameHeight
+			},
+			engineRuntime: this.engineRuntime,
+			steps: this.steps,
+			totalMs,
+			detectionCount
+		};
+	}
+};
+function countOutput(output) {
+	switch (output.kind) {
+		case "detections": return output.detections.length;
+		case "classifications": return output.classifications.length;
+		case "embedding": return 1;
+		case "text": return output.text.length > 0 ? 1 : 0;
+		case "mask": return 1;
+	}
+}
+function formatTopResult(output) {
+	switch (output.kind) {
+		case "detections": {
+			const top = output.detections[0];
+			return top ? `${top.class} ${top.score.toFixed(2)}` : void 0;
+		}
+		case "classifications": {
+			const top = output.classifications[0];
+			return top ? `${top.class} ${top.score.toFixed(2)}` : void 0;
+		}
+		case "embedding": return `embedding[${output.embedding.length}]`;
+		case "text": return output.text || void 0;
+		case "mask": return `mask ${output.maskWidth}×${output.maskHeight}`;
+	}
+}
+//#endregion
+//#region src/detection-pipeline/pipeline/face-align.ts
+/**
+* Face alignment — landmark-based similarity warp to the ArcFace template.
+*
+* ArcFace (and most face-recognition embedders) are only discriminative when
+* the input is a *landmark-aligned* 112x112 crop: eyes, nose and mouth corners
+* must land on fixed canonical positions. Feeding a raw axis-aligned bbox crop
+* stretched to 112x112 (the previous behaviour) collapses embeddings toward a
+* common direction — different people end up with ~0.99 cosine similarity.
+*
+* This module computes the least-squares similarity transform (rotation +
+* uniform scale + translation, the cv2.estimateAffinePartial2D recipe) that
+* maps SCRFD's 5 facial landmarks onto the canonical template, then resamples
+* the source pixels into a fixed-size aligned crop with bilinear interpolation.
+*
+* The warp is done in pure JS on a raw RGB buffer (a few thousand samples per
+* face — negligible cost) so it is fully deterministic and unit-testable, and
+* needs no native affine primitive nor any change to the Python inference pool.
+*/
+/**
+* Canonical ArcFace 5-point template for a 112x112 aligned crop
+* (insightface reference points). Order matches SCRFD landmark output:
+* left-eye, right-eye, nose, left-mouth-corner, right-mouth-corner.
+*/
+var ARCFACE_TEMPLATE_112 = [
+	{
+		x: 38.2946,
+		y: 51.6963
 	},
 	{
 		x: 73.5318,
@@ -2937,63 +2649,6 @@ async function alignFaceCrop(fullFrameJpeg, faceBbox, landmarksImageSpace, image
 		height: aligned.height
 	};
 }
-//#endregion
-//#region src/detection-pipeline/pipeline/native-child-crop.ts
-/**
-* NATIVE-resolution crop of a LEAF crop-child ROI (plate-ocr, leaf classifiers)
-* — the plate-side mirror of the face path's {@link ./face-align.buildAlignedFaceCrop}.
-*
-* On the detail plane the executor runs a child model against a parent crop
-* (e.g. the native vehicle crop). A leaf child's ROI (`parentDetection.bbox`,
-* in the parent crop's PIXEL space) is what the child model reads. Cutting it
-* from the parent tile with {@link ./crop-utils.cropJpeg} bounds the child input
-* to the tile's resolution — fatal for OCR on a small, distant plate. When a
-* native-crop provider is bound to the frame, we instead resolve the SAME ROI
-* straight from the frame's retained NATIVE surface (the provider re-composes
-* the crop-normalized ROI into frame space — see {@link ./native-crop-compose}),
-* giving the model native pixels. A miss/degenerate returns `null` so the caller
-* falls back to the existing tile crop (never an upscale — native or the tile).
-*/
-/**
-* Generous native-width cap for a leaf child crop. A plate ROI is a few hundred
-* native pixels wide, so this never binds for plates (effectively uncapped —
-* the quality path the task requires); it only bounds a pathologically large
-* whole-object classifier ROI so the in-process native fetch/encode stays cheap.
-*/
-var NATIVE_CHILD_CROP_MAX_WIDTH = 1920;
-/**
-* Resolve `bbox` (a parent-crop PIXEL rectangle `[x1,y1,x2,y2]`) at native
-* resolution via `provider`, returning a JPEG crop + its native dimensions.
-* Returns `null` on a degenerate ROI or any provider miss (so the caller uses
-* the downscaled tile crop instead). Pure w.r.t. its inputs; the only effect is
-* the sharp encode of the returned pixels.
-*/
-async function nativeChildCrop(provider, bbox, imageWidth, imageHeight, maxWidth) {
-	if (!(imageWidth > 0) || !(imageHeight > 0)) return null;
-	const x1 = Math.max(0, bbox[0]);
-	const y1 = Math.max(0, bbox[1]);
-	const x2 = Math.min(imageWidth, bbox[2]);
-	const y2 = Math.min(imageHeight, bbox[3]);
-	const w = x2 - x1;
-	const h = y2 - y1;
-	if (w < 1 || h < 1) return null;
-	const native = await provider({
-		x: x1 / imageWidth,
-		y: y1 / imageHeight,
-		w: w / imageWidth,
-		h: h / imageHeight
-	}, maxWidth);
-	if (!native || native.width < 2 || native.height < 2 || native.bytes.length < native.width * native.height * 3) return null;
-	return {
-		jpeg: await (0, sharp.default)(Buffer.from(native.bytes), { raw: {
-			width: native.width,
-			height: native.height,
-			channels: 3
-		} }).jpeg({ quality: 90 }).toBuffer(),
-		width: native.width,
-		height: native.height
-	};
-}
 /**
 * Detection score at/above which a near-full-frame box is trusted as a REAL
 * close subject rather than a phantom. Below this bar a full-frame box is
@@ -3075,6 +2730,63 @@ function isFullFramePhantomDetection(bbox, frameWidth, frameHeight, score, maxCo
 	return false;
 }
 //#endregion
+//#region src/detection-pipeline/pipeline/native-child-crop.ts
+/**
+* NATIVE-resolution crop of a LEAF crop-child ROI (plate-ocr, leaf classifiers)
+* — the plate-side mirror of the face path's {@link ./face-align.buildAlignedFaceCrop}.
+*
+* On the detail plane the executor runs a child model against a parent crop
+* (e.g. the native vehicle crop). A leaf child's ROI (`parentDetection.bbox`,
+* in the parent crop's PIXEL space) is what the child model reads. Cutting it
+* from the parent tile with {@link ./crop-utils.cropJpeg} bounds the child input
+* to the tile's resolution — fatal for OCR on a small, distant plate. When a
+* native-crop provider is bound to the frame, we instead resolve the SAME ROI
+* straight from the frame's retained NATIVE surface (the provider re-composes
+* the crop-normalized ROI into frame space — see {@link ./native-crop-compose}),
+* giving the model native pixels. A miss/degenerate returns `null` so the caller
+* falls back to the existing tile crop (never an upscale — native or the tile).
+*/
+/**
+* Generous native-width cap for a leaf child crop. A plate ROI is a few hundred
+* native pixels wide, so this never binds for plates (effectively uncapped —
+* the quality path the task requires); it only bounds a pathologically large
+* whole-object classifier ROI so the in-process native fetch/encode stays cheap.
+*/
+var NATIVE_CHILD_CROP_MAX_WIDTH = 1920;
+/**
+* Resolve `bbox` (a parent-crop PIXEL rectangle `[x1,y1,x2,y2]`) at native
+* resolution via `provider`, returning a JPEG crop + its native dimensions.
+* Returns `null` on a degenerate ROI or any provider miss (so the caller uses
+* the downscaled tile crop instead). Pure w.r.t. its inputs; the only effect is
+* the sharp encode of the returned pixels.
+*/
+async function nativeChildCrop(provider, bbox, imageWidth, imageHeight, maxWidth) {
+	if (!(imageWidth > 0) || !(imageHeight > 0)) return null;
+	const x1 = Math.max(0, bbox[0]);
+	const y1 = Math.max(0, bbox[1]);
+	const x2 = Math.min(imageWidth, bbox[2]);
+	const y2 = Math.min(imageHeight, bbox[3]);
+	const w = x2 - x1;
+	const h = y2 - y1;
+	if (w < 1 || h < 1) return null;
+	const native = await provider({
+		x: x1 / imageWidth,
+		y: y1 / imageHeight,
+		w: w / imageWidth,
+		h: h / imageHeight
+	}, maxWidth);
+	if (!native || native.width < 2 || native.height < 2 || native.bytes.length < native.width * native.height * 3) return null;
+	return {
+		jpeg: await (0, sharp.default)(Buffer.from(native.bytes), { raw: {
+			width: native.width,
+			height: native.height,
+			channels: 3
+		} }).jpeg({ quality: 90 }).toBuffer(),
+		width: native.width,
+		height: native.height
+	};
+}
+//#endregion
 //#region src/detection-pipeline/pipeline/plate-deskew.ts
 /**
 * Plate-crop DESKEW — rotation rectification for oblique licence-plate crops.
@@ -3589,6 +3301,7 @@ function buildFrameResult(input) {
 		width: input.width,
 		height: input.height,
 		detections,
+		...input.discarded !== void 0 && input.discarded.length > 0 ? { discarded: input.discarded } : {},
 		debug: frameDebug
 	};
 }
@@ -3597,137 +3310,39 @@ function bboxTupleToRect(bbox) {
 	return {
 		x: x1,
 		y: y1,
-		width: x2 - x1,
-		height: y2 - y1
-	};
-}
-function pruneUndefined(obj) {
-	const out = {};
-	for (const [k, v] of Object.entries(obj)) if (v !== void 0) out[k] = v;
-	return out;
-}
-function generateFrameId() {
-	return `frame-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-}
-/** Seed a MutableObjectDetection from a root-level detector output. */
-function toMutableRootDetection(det, rootStep, idGen, rootStepLatencyMs) {
-	return {
-		id: idGen.next(),
-		kind: "first-level",
-		macroClass: det.class,
-		originalClass: det.class,
-		score: det.score,
-		bbox: [...det.bbox],
-		ownLabels: [],
-		alternateLabels: {},
-		stepLatencyMs: { [rootStep.stepId]: rootStepLatencyMs },
-		modelIds: { [rootStep.stepId]: rootStep.modelId },
-		extractMode: "full-frame",
-		...det.mask !== void 0 ? {
-			mask: det.mask,
-			maskWidth: det.maskWidth,
-			maskHeight: det.maskHeight
-		} : {},
-		...det.landmarks !== void 0 ? { landmarks: det.landmarks } : {}
-	};
-}
-//#endregion
-//#region src/detection-pipeline/pipeline/execution-trace.ts
-var traceCounter = 0;
-var ExecutionTraceBuilder = class {
-	verbosity;
-	deviceId;
-	frameWidth;
-	frameHeight;
-	engineRuntime;
-	steps = [];
-	startTime;
-	constructor(verbosity, deviceId, frameWidth, frameHeight, engineRuntime) {
-		this.verbosity = verbosity;
-		this.deviceId = deviceId;
-		this.frameWidth = frameWidth;
-		this.frameHeight = frameHeight;
-		this.engineRuntime = engineRuntime;
-		this.startTime = Date.now();
-	}
-	/** Whether trace collection is active. */
-	get isActive() {
-		return this.verbosity !== "off";
-	}
-	/**
-	* Record a completed step execution.
-	* No-op if verbosity is 'off'.
-	*/
-	addStep(params) {
-		if (this.verbosity === "off") return;
-		const totalMs = params.preprocessMs + params.inferenceMs + params.postprocessMs;
-		const trace = {
-			stepId: params.stepId,
-			modelId: params.modelId,
-			slot: params.slot,
-			postprocessor: params.postprocessor,
-			preprocessMs: Math.round(params.preprocessMs * 100) / 100,
-			inferenceMs: Math.round(params.inferenceMs * 100) / 100,
-			postprocessMs: Math.round(params.postprocessMs * 100) / 100,
-			totalMs: Math.round(totalMs * 100) / 100,
-			inputType: params.inputType,
-			inputSize: {
-				width: params.inputWidth,
-				height: params.inputHeight
-			},
-			parentDetection: this.verbosity === "full" ? params.parentDetection : void 0,
-			outputKind: params.output.kind,
-			outputCount: countOutput(params.output),
-			topResult: this.verbosity === "full" ? formatTopResult(params.output) : void 0,
-			error: params.error
-		};
-		this.steps.push(trace);
-	}
-	/**
-	* Finalize and return the complete execution trace.
-	* Returns null if verbosity is 'off'.
-	*/
-	build(detectionCount) {
-		if (this.verbosity === "off") return null;
-		const totalMs = Date.now() - this.startTime;
-		return {
-			traceId: `trace-${Date.now()}-${++traceCounter}`,
-			deviceId: this.deviceId,
-			timestamp: this.startTime,
-			frameSize: {
-				width: this.frameWidth,
-				height: this.frameHeight
-			},
-			engineRuntime: this.engineRuntime,
-			steps: this.steps,
-			totalMs,
-			detectionCount
-		};
-	}
-};
-function countOutput(output) {
-	switch (output.kind) {
-		case "detections": return output.detections.length;
-		case "classifications": return output.classifications.length;
-		case "embedding": return 1;
-		case "text": return output.text.length > 0 ? 1 : 0;
-		case "mask": return 1;
-	}
-}
-function formatTopResult(output) {
-	switch (output.kind) {
-		case "detections": {
-			const top = output.detections[0];
-			return top ? `${top.class} ${top.score.toFixed(2)}` : void 0;
-		}
-		case "classifications": {
-			const top = output.classifications[0];
-			return top ? `${top.class} ${top.score.toFixed(2)}` : void 0;
-		}
-		case "embedding": return `embedding[${output.embedding.length}]`;
-		case "text": return output.text || void 0;
-		case "mask": return `mask ${output.maskWidth}×${output.maskHeight}`;
-	}
+		width: x2 - x1,
+		height: y2 - y1
+	};
+}
+function pruneUndefined(obj) {
+	const out = {};
+	for (const [k, v] of Object.entries(obj)) if (v !== void 0) out[k] = v;
+	return out;
+}
+function generateFrameId() {
+	return `frame-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+/** Seed a MutableObjectDetection from a root-level detector output. */
+function toMutableRootDetection(det, rootStep, idGen, rootStepLatencyMs) {
+	return {
+		id: idGen.next(),
+		kind: "first-level",
+		macroClass: det.class,
+		originalClass: det.class,
+		score: det.score,
+		bbox: [...det.bbox],
+		ownLabels: [],
+		alternateLabels: {},
+		stepLatencyMs: { [rootStep.stepId]: rootStepLatencyMs },
+		modelIds: { [rootStep.stepId]: rootStep.modelId },
+		extractMode: "full-frame",
+		...det.mask !== void 0 ? {
+			mask: det.mask,
+			maskWidth: det.maskWidth,
+			maskHeight: det.maskHeight
+		} : {},
+		...det.landmarks !== void 0 ? { landmarks: det.landmarks } : {}
+	};
 }
 //#endregion
 //#region src/detection-pipeline/pipeline/executor.ts
@@ -3879,12 +3494,14 @@ var PipelineExecutor = class {
 			idGen,
 			details
 		};
+		let discarded;
 		for (const rootStep of tree.roots) {
 			if (debug) console.log(`[executor] rootStep=${rootStep.stepId} settings=${JSON.stringify(rootStep.settings ?? {})}`);
 			const cropPrep = rootStep.definition.extractMode === "crop-zone" && cropZoneBbox !== void 0 ? await this.prepareCropZoneInput(cropZoneBbox, fullFrameJpegProvider, imageWidth, imageHeight, deviceId) : null;
 			const rootStart = Date.now();
 			const rawRootOutput = await this.executeStep(rootStep, cropPrep?.input ?? rootInput, cropPrep?.width ?? imageWidth, cropPrep?.height ?? imageHeight, "full-frame", void 0, void 0, traceBuilder, stepTimings, poolAgg);
 			const rootMs = Date.now() - rootStart;
+			if (rawRootOutput === null) continue;
 			const rootOutput = cropPrep && rawRootOutput.kind === "detections" ? reprojectCropZoneDetections(rawRootOutput, cropPrep.origin) : rawRootOutput;
 			if (rootOutput.kind !== "detections") {
 				if (isEnrichmentOutput(rootOutput)) {
@@ -3914,10 +3531,35 @@ var PipelineExecutor = class {
 					if (mapped) {
 						mutable.originalClass = det.class;
 						mutable.macroClass = mapped;
-					} else if (!rootStep.definition.classMap.preserveOriginal) continue;
+					} else if (!rootStep.definition.classMap.preserveOriginal) {
+						(discarded ??= []).push({
+							bbox: [
+								mutable.bbox[0],
+								mutable.bbox[1],
+								mutable.bbox[2],
+								mutable.bbox[3]
+							],
+							macroClass: mutable.macroClass,
+							score: mutable.score,
+							reason: "class-filter"
+						});
+						continue;
+					}
 				}
-				if (!this.matchesMacroFilter(mutable.macroClass, mutable.score, rootStep.settings)) {
-					if (debug) console.log(`[executor] drop det macro=${mutable.macroClass} score=${mutable.score} (class or confidence filter)`);
+				const filterVerdict = this.macroFilterVerdict(mutable.macroClass, mutable.score, rootStep.settings);
+				if (filterVerdict !== "pass") {
+					(discarded ??= []).push({
+						bbox: [
+							mutable.bbox[0],
+							mutable.bbox[1],
+							mutable.bbox[2],
+							mutable.bbox[3]
+						],
+						macroClass: mutable.macroClass,
+						score: mutable.score,
+						reason: filterVerdict
+					});
+					if (debug) console.log(`[executor] drop det macro=${mutable.macroClass} score=${mutable.score} (${filterVerdict})`);
 					continue;
 				}
 				const fullFrameBar = rootStep.settings?.["fullFrameGuardMaxConfidence"];
@@ -3936,9 +3578,20 @@ var PipelineExecutor = class {
 							hardAreaRatio: typeof fullFrameHardArea === "number" ? fullFrameHardArea : void 0
 						}
 					});
+					(discarded ??= []).push({
+						bbox: [
+							mutable.bbox[0],
+							mutable.bbox[1],
+							mutable.bbox[2],
+							mutable.bbox[3]
+						],
+						macroClass: mutable.macroClass,
+						score: mutable.score,
+						reason: "full-frame-guard"
+					});
 					continue;
 				}
-				if (isFullFrameSurvivor(mutable.bbox, imageWidth, imageHeight, mutable.score, typeof fullFrameBar === "number" ? fullFrameBar : void 0)) this.opts.logger?.warn("full-frame box SURVIVED the guard on score", {
+				if (isFullFrameSurvivor(mutable.bbox, imageWidth, imageHeight, mutable.score, typeof fullFrameBar === "number" ? fullFrameBar : void 0)) this.opts.logger?.info("full-frame box SURVIVED the guard on score", {
 					tags: { deviceId },
 					meta: {
 						macroClass: mutable.macroClass,
@@ -3965,6 +3618,7 @@ var PipelineExecutor = class {
 				firstLevel.push(mutable);
 			}
 		}
+		const totalMs = Date.now() - startMs;
 		return {
 			result: buildFrameResult({
 				deviceId,
@@ -3972,8 +3626,9 @@ var PipelineExecutor = class {
 				height: imageHeight,
 				firstLevel,
 				details,
+				discarded,
 				stepTimings,
-				totalMs: Date.now() - startMs,
+				totalMs,
 				engine: this.opts.engineRuntime,
 				debug,
 				timestamp: Date.now(),
@@ -4078,13 +3733,40 @@ var PipelineExecutor = class {
 			});
 			throw new Error(`Inference failed for step "${step.stepId}": ${errorMsg}`, { cause: err });
 		}
+		if (engineOutput.dropped === true) {
+			stepTimings.push({
+				source: step.stepId,
+				modelId: step.modelId,
+				ms: Date.now() - preprocessStart,
+				detectionCount: 0
+			});
+			if (traceBuilder.isActive) traceBuilder.addStep({
+				stepId: step.stepId,
+				modelId: step.modelId,
+				slot: step.definition.slot,
+				postprocessor: step.definition.postprocessor,
+				preprocessMs,
+				inferenceMs: Date.now() - inferenceStart,
+				postprocessMs: 0,
+				inputType,
+				inputWidth,
+				inputHeight,
+				parentDetection: parentClass,
+				output: {
+					kind: "detections",
+					detections: []
+				},
+				error: `shed:${engineOutput.shedReason ?? "pool-overload"}`
+			});
+			return null;
+		}
 		const structured = engineOutput.structured ?? {};
 		const inferenceMs = typeof structured.inferenceMs === "number" ? structured.inferenceMs : Date.now() - inferenceStart;
 		if (typeof structured.preprocessMs === "number") poolAgg.preprocessMs += structured.preprocessMs;
 		if (typeof structured.predictMs === "number") poolAgg.predictMs += structured.predictMs;
 		if (typeof structured.batchSize === "number" && structured.batchSize > poolAgg.batchSize) poolAgg.batchSize = structured.batchSize;
 		const postprocessStart = Date.now();
-		const output = dispatchPostprocess(engineOutput, step.definition, step.settings);
+		const output = dispatchPostprocess(engineOutput, step.definition);
 		const postprocessMs = Date.now() - postprocessStart;
 		stepTimings.push({
 			source: step.stepId,
@@ -4227,6 +3909,7 @@ var PipelineExecutor = class {
 					data: cropJpegBuf
 				}, cropW, cropH, "crop-roi", parentDetection.bbox, parentDetection.macroClass, traceBuilder, stepTimings, poolAgg);
 				const childMs = Date.now() - childStart;
+				if (childOutput === null) continue;
 				const detailsBefore = ctx.details.length;
 				applyChildOutput(parentDetection, child, childOutput, childMs, ctx);
 				if (childOutput.kind === "detections" && child.children.length > 0) {
@@ -4260,20 +3943,25 @@ var PipelineExecutor = class {
 	* Apply the object-detection step's macro filter + per-macro
 	* minConfidence sliders introduced in the Phase 6 step rework.
 	*
+	* Returns WHICH gate failed rather than a bare boolean so the
+	* discard trail can label the dropped box with the honest reason
+	* (`class-filter` vs `below-threshold`) — the two are remediated
+	* differently (enable the class vs lower a slider).
+	*
 	* Expected `settings` shape:
 	*   - `enabledMacroClasses`: readonly string[] (e.g. ['person','vehicle','animal']).
 	*     Empty array = all allowed (legacy behaviour).
 	*   - `minConfidence<Macro>`: number (e.g. `minConfidencePerson: 0.5`)
 	*/
-	matchesMacroFilter(macroClass, score, settings) {
-		if (!settings) return true;
+	macroFilterVerdict(macroClass, score, settings) {
+		if (!settings) return "pass";
 		const enabled = settings["enabledMacroClasses"];
 		if (Array.isArray(enabled) && enabled.length > 0) {
-			if (!enabled.includes(macroClass)) return false;
+			if (!enabled.includes(macroClass)) return "class-filter";
 		}
 		const perMacroThreshold = settings[`minConfidence${capitalize(macroClass)}`];
-		if (typeof perMacroThreshold === "number" && score < perMacroThreshold) return false;
-		return true;
+		if (typeof perMacroThreshold === "number" && score < perMacroThreshold) return "below-threshold";
+		return "pass";
 	}
 };
 function capitalize(s) {
@@ -4281,52 +3969,41 @@ function capitalize(s) {
 	return s.charAt(0).toUpperCase() + s.slice(1);
 }
 //#endregion
-//#region src/detection-pipeline/pipeline/crop-zone.ts
+//#region src/detection-pipeline/pipeline/native-crop-compose.ts
+/** Clamp `v` into `[lo, hi]`. */
+function clamp(v, lo, hi) {
+	if (v < lo) return lo;
+	if (v > hi) return hi;
+	return v;
+}
 /**
-* Resolve the absolute-pixel crop bbox for a `crop-zone` root detector: the
-* bounding box of the UNION of every polygon referenced by the device's
-* ENABLED `package`-stage zone rules. Zone polygons are normalized (0..1); the
-* union is clamped to [0,1] then scaled to the frame's pixel dimensions.
+* Compose a child `roi` given in the parent CROP's normalized space into the
+* FRAME's normalized space, given the crop's frame-space pixel rectangle and the
+* frame dimensions. The result is clamped to the unit square (origin in
+* `[0,1]`, extent bounded so `x + w ≤ 1` and `y + h ≤ 1`). Returns `null` for
+* degenerate inputs (non-finite frame dims, empty crop rect, or an ROI that
+* clamps to zero area) so the caller falls back to the downscaled tile crop.
 *
-* Returns `null` when there is nothing usable to crop to — no enabled rules, no
-* referenced geometry, or a degenerate result — in which case the caller falls
-* back to full-frame inference (behaviour identical to before the crop-zone
-* plumbing).
+* Pure — never mutates its arguments.
 */
-function resolvePackageCropBbox(zones, packageRules, frameWidth, frameHeight) {
-	if (frameWidth <= 0 || frameHeight <= 0) return null;
-	const enabledRules = packageRules.filter((r) => r.enabled !== false);
-	if (enabledRules.length === 0) return null;
-	const zoneIds = /* @__PURE__ */ new Set();
-	for (const rule of enabledRules) for (const id of rule.zoneIds) zoneIds.add(id);
-	if (zoneIds.size === 0) return null;
-	const zoneById = new Map(zones.map((z) => [z.id, z]));
-	let minX = Number.POSITIVE_INFINITY;
-	let minY = Number.POSITIVE_INFINITY;
-	let maxX = Number.NEGATIVE_INFINITY;
-	let maxY = Number.NEGATIVE_INFINITY;
-	let sawPoint = false;
-	for (const id of zoneIds) {
-		const zone = zoneById.get(id);
-		if (!zone || zone.polygon.length === 0) continue;
-		for (const point of zone.polygon) {
-			sawPoint = true;
-			if (point.x < minX) minX = point.x;
-			if (point.y < minY) minY = point.y;
-			if (point.x > maxX) maxX = point.x;
-			if (point.y > maxY) maxY = point.y;
-		}
-	}
-	if (!sawPoint) return null;
-	const clamp01 = (v) => Math.max(0, Math.min(1, v));
-	const bbox = [
-		clamp01(minX) * frameWidth,
-		clamp01(minY) * frameHeight,
-		clamp01(maxX) * frameWidth,
-		clamp01(maxY) * frameHeight
-	];
-	if (isBboxDegenerate(bbox)) return null;
-	return bbox;
+function composeCropRoiToFrameNorm(roi, cropFrameSpace, frameWidth, frameHeight) {
+	if (!(frameWidth > 0) || !(frameHeight > 0)) return null;
+	if (!(cropFrameSpace.w > 0) || !(cropFrameSpace.h > 0)) return null;
+	const fx = (cropFrameSpace.x + roi.x * cropFrameSpace.w) / frameWidth;
+	const fy = (cropFrameSpace.y + roi.y * cropFrameSpace.h) / frameHeight;
+	const fw = roi.w * cropFrameSpace.w / frameWidth;
+	const fh = roi.h * cropFrameSpace.h / frameHeight;
+	const x = clamp(fx, 0, 1);
+	const y = clamp(fy, 0, 1);
+	const w = clamp(fw, 0, 1 - x);
+	const h = clamp(fh, 0, 1 - y);
+	if (!(w > 0) || !(h > 0)) return null;
+	return {
+		x,
+		y,
+		w,
+		h
+	};
 }
 //#endregion
 //#region src/detection-pipeline/pipeline/tree-builder.ts
@@ -4562,6 +4239,44 @@ function resolveInputSteps(steps, format, engine) {
 	};
 }
 //#endregion
+//#region src/detection-pipeline/zone-gate.ts
+function applyZoneRuleGate(result, zones, rules) {
+	if (result.detections.length === 0) return result;
+	if (zones.length === 0 || rules.length === 0) return result;
+	const frameW = result.width;
+	const frameH = result.height;
+	if (frameW === 0 || frameH === 0) return result;
+	const firstLevel = result.detections.filter((d) => d.kind === "first-level");
+	const details = result.detections.filter((d) => d.kind === "detail");
+	const { passed, excluded } = require_dist.evaluateZoneRules(firstLevel, zones, rules, (det) => ({
+		x: (det.bbox.x + det.bbox.width / 2) / frameW,
+		y: (det.bbox.y + det.bbox.height / 2) / frameH
+	}), (det) => det.macroClass);
+	if (passed.length === firstLevel.length) return result;
+	const passedIds = new Set(passed.map((d) => d.id));
+	const filteredDetails = details.filter((d) => {
+		const parentId = d.parentId;
+		return parentId === void 0 || passedIds.has(parentId);
+	});
+	const zoneDiscards = excluded.map((d) => ({
+		bbox: [
+			d.bbox.x,
+			d.bbox.y,
+			d.bbox.x + d.bbox.width,
+			d.bbox.y + d.bbox.height
+		],
+		macroClass: d.macroClass,
+		score: d.score,
+		reason: "zone-gate"
+	}));
+	const mergedDiscarded = [...result.discarded ?? [], ...zoneDiscards];
+	return {
+		...result,
+		detections: [...passed, ...filteredDetails],
+		...mergedDiscarded.length > 0 ? { discarded: mergedDiscarded } : {}
+	};
+}
+//#endregion
 //#region src/detection-pipeline/provider.ts
 /**
 * DetectionPipelineProvider — implements IPipelineExecutorProvider.
@@ -4904,10 +4619,27 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 	* Idle-TTL for a per-device inference pool (multi-device C3). A device pool
 	* with no dispatch for this long is disposed and recreated on next use — the
 	* memory guardrail that keeps `factoriesByDevice` from accumulating warm pools
-	* forever. Longer than the override cache (60s) since a device pool is heavier
-	* to respin; still well above any real inter-session gap for an active camera.
+	* forever as an operator toggles device sets over a long run.
+	*
+	* It was 120s, on the stated assumption that this was "well above any real
+	* inter-session gap for an active camera". Measured 2026-08-02, that is
+	* false: detection is dispatched ON MOTION, so at night the gap between
+	* events routinely exceeds two minutes, and the eviction fires constantly.
+	* The rebuild is not cheap — `ensureModelsForSteps` loads EVERY enabled step
+	* into the fresh factory, which on the hub is seven models
+	* (yolov9m-320-int8, scrfd-2.5g, arcface-r100, yolov8n-plate,
+	* vgg_english_g2, mobileclip-s1-vision, yolov8n-package). The hub log shows
+	* the cycle plainly: `COMPILE ×7` → shed within 7-15s → `EVICT` ~2.5 min
+	* later → repeat. So the first seconds of a motion event — precisely when
+	* detection matters — were spent recompiling models that had just been
+	* thrown away.
+	*
+	* Hours, not minutes. At this TTL only a pool that is genuinely unused
+	* (device disabled, routing changed) is reclaimed, which is what the
+	* guardrail was for; a nightly lull no longer costs a recompile. Override
+	* via env for a memory-constrained node.
 	*/
-	static DEVICE_POOL_IDLE_TTL_MS = 12e4;
+	static DEVICE_POOL_IDLE_TTL_MS = Math.max(6e4, Number(process.env["CAMSTACK_DEVICE_POOL_IDLE_TTL_MS"]) || 360 * 60 * 1e3);
 	deviceReaper = new IdlePoolReaper({
 		ttlMs: DetectionPipelineProvider.DEVICE_POOL_IDLE_TTL_MS,
 		dispose: (deviceKey) => this.disposeDevicePool(deviceKey),
@@ -5960,19 +5692,15 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 			emit(`Image: ${imageWidth}×${imageHeight}`);
 		}
 		decodeMs = performance.now() - decodeT0;
-		const deviceEngine = input.deviceKey ? resolveDeviceEngine(input.deviceKey) : void 0;
-		const resolveFormat = deviceEngine?.format ?? input.engine?.format ?? this.currentEngine.format;
-		const resolveEngine = deviceEngine ? {
-			backend: deviceEngine.backend,
-			device: deviceEngine.device ?? null
-		} : input.engine ? {
-			backend: input.engine.backend,
-			device: input.engine.device ?? null
-		} : {
-			backend: this.currentEngine.backend,
-			device: this.currentEngine.device ?? null
-		};
-		const benchmarkSteps = this.inputStepsToPipelineSteps(input.steps, resolveFormat, resolveEngine);
+		const dispatchResolution = this.resolveStepsForDispatch({
+			steps: input.steps,
+			deviceKey: input.deviceKey,
+			engineOverride: input.engine,
+			deviceId: input.deviceId,
+			plane: input.plane
+		});
+		const dispatchDeviceKey = dispatchResolution.deviceKey;
+		const benchmarkSteps = dispatchResolution.steps;
 		const stepsSignature = JSON.stringify(benchmarkSteps.map((s) => ({
 			id: s.addonId,
 			settings: s.settings ?? {}
@@ -6064,8 +5792,8 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 				logger: this.log
 			});
 			this.executor = executor;
-			const dispatchEngine = input.deviceKey ? resolveDeviceEngine(input.deviceKey) : runEngine;
-			const dispatchFactory = input.deviceKey ? await this.resolveDeviceFactory(input.deviceKey) : this.engineFactory;
+			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));
 			if (needed.length > 0) {
 				this.log.info("Benchmark: models to load", { meta: {
@@ -6314,6 +6042,142 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 		fn();
 	}
 	/**
+	* Resolve a dispatch's step tree against its target engine, with the
+	* CAPABILITY GATE + node-local engine fallback (cam-615, 2026-08-01;
+	* per-step split 2026-08-01 evening).
+	*
+	* A per-call `deviceKey` (orchestrator device routing / detail-plane step
+	* jump) selects an engine whose format every step EXECUTING IN THIS CALL
+	* must actually ship a model build for. When such a step's catalog has
+	* ZERO builds for that format (so not even `resolveModelForFormat`'s
+	* substitution can rescue it), dispatching anyway means every frame
+	* fails — before this gate it failed as a doomed 3-retry model download,
+	* ~5.5s per frame, forever.
+	*
+	* The gated set is per-plane — the ROOT decides the dispatch device, a
+	* child never bounces it (operator requirement: devices compensate for
+	* each other's missing steps; the original whole-tree gate let ONE
+	* tflite-less child knock the root off an otherwise-capable Coral):
+	*
+	*  - `'frame'` (the live per-frame path) executes only root-plane steps,
+	*    so only those gate the device. Detail children that can NEVER run on
+	*    this device are pruned from THIS dispatch (so `ensureModelsForSteps`
+	*    doesn't fail the call on a format build that does not exist) and
+	*    logged once — NOT dropped work: each runs later as its own per-track
+	*    detail dispatch, where the runner's device-jump resolver
+	*    (`resolveStepDevice`) places it on a same-node device that can run
+	*    it, or warns no-candidate loudly.
+	*  - any other plane (detail subtrees, benchmark, batch) executes the
+	*    whole passed tree inline on ONE pool — a single call cannot split
+	*    devices — so the whole-tree gate stays.
+	*
+	* Fallback is strictly NODE-LOCAL and ordered: the node's own selected
+	* engine (or the benchmark's explicit `engineOverride`) is the one and only
+	* fallback — frames never migrate to another node from here (that is the
+	* orchestrator's tier). The fallback is logged ONCE per distinct
+	* (deviceKey, steps, format) signature, with `tags: { deviceId }` when the
+	* dispatch is camera-scoped.
+	*
+	* When the node's own engine ALSO cannot run a step, this throws — fast,
+	* before any download attempt — and logs the full picture once (model,
+	* its available formats, both engines tried). A genuinely impossible
+	* configuration must stay loud, not vanish into a silent fallback chain.
+	*/
+	resolveStepsForDispatch(args) {
+		const { deviceKey, engineOverride, deviceId } = args;
+		const nodeFormat = engineOverride?.format ?? this.currentEngine.format;
+		const nodeEngine = engineOverride ? {
+			backend: engineOverride.backend,
+			device: engineOverride.device ?? null
+		} : {
+			backend: this.currentEngine.backend,
+			device: this.currentEngine.device ?? null
+		};
+		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);
+			this.assertStepsRunnable(steps, nodeFormat, deviceId, [nodeEngineLabel]);
+			return {
+				deviceKey: void 0,
+				steps
+			};
+		}
+		const deviceFormat = deviceEngine.format;
+		const deviceStepEngine = {
+			backend: deviceEngine.backend,
+			device: deviceEngine.device ?? null
+		};
+		const steps = this.inputStepsToPipelineSteps(args.steps, deviceFormat, deviceStepEngine);
+		const framePlane = args.plane === "frame";
+		const zeroBuild = collectZeroBuildIssues(framePlane ? collectFramePlaneSteps(steps, isDetailPlaneStep) : flattenSteps(steps), deviceFormat);
+		if (zeroBuild.length === 0) {
+			if (!framePlane) return {
+				deviceKey,
+				steps
+			};
+			const pruneResult = pruneUnrunnableDetailSteps(steps, isDetailPlaneStep, (addonId) => stepHasZeroBuildsFor(addonId, deviceFormat));
+			if (pruneResult.prunedAddonIds.length > 0) {
+				const prunedList = pruneResult.prunedAddonIds.join(",");
+				this.logLiveDispatchIssueOnce(`detail-defer:${deviceKey}:${deviceFormat}:${prunedList}`, () => this.log.info("Detail steps have no model build for the dispatch device format — deferred to the detail-plane device jump", {
+					...deviceId !== void 0 ? { tags: { deviceId } } : {},
+					meta: {
+						deviceKey,
+						deviceFormat,
+						steps: [...pruneResult.prunedAddonIds]
+					}
+				}));
+			}
+			return {
+				deviceKey,
+				steps: pruneResult.steps
+			};
+		}
+		const blockedSteps = zeroBuild.map((issue) => issue.addonId);
+		this.logLiveDispatchIssueOnce(`capability-fallback:${deviceKey}:${deviceFormat}:${blockedSteps.join(",")}`, () => this.log.warn("Device pool cannot run step (no model build for its format) — falling back to the node-local default engine", {
+			...deviceId !== void 0 ? { tags: { deviceId } } : {},
+			meta: {
+				deviceKey,
+				deviceFormat,
+				steps: blockedSteps,
+				fallbackEngine: nodeEngineLabel
+			}
+		}));
+		const fallbackSteps = this.inputStepsToPipelineSteps(args.steps, nodeFormat, nodeEngine);
+		this.assertStepsRunnable(fallbackSteps, nodeFormat, deviceId, [`${deviceKey} (${deviceFormat})`, nodeEngineLabel]);
+		return {
+			deviceKey: void 0,
+			steps: fallbackSteps
+		};
+	}
+	/**
+	* The loud, fast half of the capability gate: throw when any ENABLED step
+	* has ZERO model builds for `format` — BEFORE any model download runs. The
+	* error names the step, its chosen model, the formats the catalog actually
+	* ships, and every engine that was tried, and is logged ONCE per distinct
+	* signature (the throw itself still surfaces per dispatch, but costs
+	* microseconds instead of a 3-retry download backoff).
+	*/
+	assertStepsRunnable(steps, format, deviceId, enginesTried) {
+		const zeroBuild = collectZeroBuildIssues(flattenSteps(steps), format);
+		if (zeroBuild.length === 0) return;
+		const detail = zeroBuild.map((issue) => {
+			const step = flattenSteps(steps).find((s) => s.addonId === issue.addonId);
+			const formats = availableFormatsForStep(issue.addonId);
+			return `step "${issue.addonId}" (model "${step?.modelId ?? "unknown"}") has no ${format} build (available: ${formats.join(", ") || "none"})`;
+		}).join("; ");
+		const message = `Pipeline dispatch impossible on this node: ${detail}. Engines tried: ${enginesTried.join(" → ")}.`;
+		this.logLiveDispatchIssueOnce(`unrunnable:${format}:${zeroBuild.map((i) => i.addonId).join(",")}`, () => this.log.error("Pipeline step cannot run on any node-local engine", {
+			...deviceId !== void 0 ? { tags: { deviceId } } : {},
+			meta: {
+				format,
+				enginesTried: [...enginesTried],
+				detail
+			}
+		}));
+		throw new Error(message);
+	}
+	/**
 	* Single-flight gate around `ensureModelsForSteps`. Concurrent
 	* callers (every camera that fires motion in the same window calls
 	* `runPipeline` → `ensureModelsForSteps`) share the same in-flight
@@ -6340,6 +6204,7 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 			for (const step of needed) {
 				const modelEntry = await this.resolveModelEntry(step.addonId, step.modelId);
 				if (modelEntry && !require_model_download_service_Cp9f4dk6.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`);
 					this.log.info("Downloading model for step", { meta: {
 						modelId: step.modelId,
 						format,
@@ -6457,19 +6322,16 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 	}
 	async runPipelineBatchImpl(input) {
 		if (input.frames.length === 0) return { results: [] };
-		const deviceEngine = input.deviceKey ? resolveDeviceEngine(input.deviceKey) : void 0;
-		const resolveFormat = deviceEngine?.format ?? input.engine?.format ?? this.currentEngine.format;
-		const resolveEngine = deviceEngine ? {
-			backend: deviceEngine.backend,
-			device: deviceEngine.device ?? null
-		} : input.engine ? {
-			backend: input.engine.backend,
-			device: input.engine.device ?? null
-		} : {
-			backend: this.currentEngine.backend,
-			device: this.currentEngine.device ?? null
-		};
-		const benchmarkSteps = this.inputStepsToPipelineSteps(input.steps, resolveFormat, resolveEngine);
+		const dispatchResolution = this.resolveStepsForDispatch({
+			steps: input.steps,
+			deviceKey: input.deviceKey,
+			engineOverride: input.engine,
+			deviceId: input.deviceId,
+			plane: void 0
+		});
+		const dispatchDeviceKey = dispatchResolution.deviceKey;
+		const resolveFormat = dispatchDeviceKey ? resolveDeviceEngine(dispatchDeviceKey).format : input.engine?.format ?? this.currentEngine.format;
+		const benchmarkSteps = dispatchResolution.steps;
 		const enabledSteps = flattenEnabledVideoSteps(benchmarkSteps);
 		if (enabledSteps.length === 0) throw new Error("runPipelineBatch: no enabled steps");
 		const rootStep = enabledSteps[0];
@@ -6491,7 +6353,7 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 		await this.ensureEngineFactory();
 		const restoreEngine = await this.applyEngineOverride(input.engine);
 		try {
-			const factory = input.deviceKey ? await this.resolveDeviceFactory(input.deviceKey) : this.engineFactory;
+			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);
 			const canFastPath = singleRoot && allRaw && uniformDims && factory.supportsBatch();
@@ -6508,7 +6370,7 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 				frame,
 				deviceId: input.deviceId,
 				sessionId: input.sessionId,
-				deviceKey: input.deviceKey
+				deviceKey: dispatchDeviceKey
 			}))) };
 			const items = input.frames.map((frame) => ({
 				raw: Buffer.from(frame.data),
@@ -6693,31 +6555,10 @@ var DetectionPipelineProvider = class DetectionPipelineProvider {
 	* detections).
 	*/
 	gateDetectionsByZoneRules(deviceId, result) {
-		if (deviceId <= 0 || result.detections.length === 0) return result;
+		if (deviceId <= 0) return result;
 		const proxy = this.deviceProxies.get(deviceId);
 		if (!proxy) return result;
-		const zones = proxy.state.zones.value?.zones ?? [];
-		const rules = proxy.state.zoneRules.value?.detection ?? [];
-		if (zones.length === 0 || rules.length === 0) return result;
-		const frameW = result.width;
-		const frameH = result.height;
-		if (frameW === 0 || frameH === 0) return result;
-		const firstLevel = result.detections.filter((d) => d.kind === "first-level");
-		const details = result.detections.filter((d) => d.kind === "detail");
-		const { passed } = require_dist.evaluateZoneRules(firstLevel, zones, rules, (det) => ({
-			x: (det.bbox.x + det.bbox.width / 2) / frameW,
-			y: (det.bbox.y + det.bbox.height / 2) / frameH
-		}), (det) => det.macroClass);
-		if (passed.length === firstLevel.length) return result;
-		const passedIds = new Set(passed.map((d) => d.id));
-		const filteredDetails = details.filter((d) => {
-			const parentId = d.parentId;
-			return parentId === void 0 || passedIds.has(parentId);
-		});
-		return {
-			...result,
-			detections: [...passed, ...filteredDetails]
-		};
+		return applyZoneRuleGate(result, proxy.state.zones.value?.zones ?? [], proxy.state.zoneRules.value?.detection ?? []);
 	}
 	async cacheFrameInPool(input) {
 		await this.ensureEngineFactory();
@@ -7307,12 +7148,49 @@ function stepsToPipelineConfig(steps, engine) {
 		} : {}
 	};
 }
-/** Flatten a step tree into a flat list (DFS). */
 /** Flatten a step tree into a flat list (DFS) — delegates to shared utility. */
 function flattenSteps(steps) {
 	return flattenEnabledVideoSteps(steps);
 }
 /**
+* Catalog root-vs-detail plane of a step: a non-null `inputClasses` on the
+* DEFINITION marks a crop child served per-track on the detail plane —
+* mirrors the executor's frame-plane skip (`executeChildren`) and the
+* runner's `deriveDetailSteps`. Unknown addonIds (already dropped from
+* resolved trees) default to root-plane.
+*/
+function isDetailPlaneStep(addonId) {
+	try {
+		return require_step_definitions.getStepDefinition(addonId).inputClasses !== null;
+	} catch {
+		return false;
+	}
+}
+/**
+* True when the step's FULL catalog ships no model with a build for
+* `format` — the single-step form of `collectZeroBuildIssues`. Unknown/custom
+* addonIds (no catalog to check) are never zero-build, mirroring the
+* collector's skip.
+*/
+function stepHasZeroBuildsFor(addonId, format) {
+	return collectZeroBuildIssues([{ addonId }], format).length > 0;
+}
+/**
+* The union of model formats a step's catalog ships ANY build for — the
+* "Available: …" half of the capability-gate error. Unknown/custom addonIds
+* yield an empty list (no catalog to enumerate), never a throw.
+*/
+function availableFormatsForStep(addonId) {
+	try {
+		const def = require_step_definitions.getStepDefinition(addonId);
+		const formats = /* @__PURE__ */ new Set();
+		for (const model of def.models) for (const format of Object.keys(model.formats)) formats.add(format);
+		return Array.from(formats).toSorted();
+	} catch {
+		return [];
+	}
+}
+/**
 * Return a shallow-cloned executable tree with `rootStepId`'s `settings`
 * merged with `overrides` (per-device values win). Non-matching root steps
 * pass through unchanged. Used by `runFrame` to apply per-device detection
@@ -7328,6 +7206,142 @@ function applyDeviceOverridesToTree(tree, rootStepId, overrides) {
 	} : root) };
 }
 //#endregion
+//#region src/detection-pipeline/diagnostics/event-loop-stall-monitor.ts
+/**
+* event-loop-stall-monitor — names the thing that freezes the detection process.
+*
+* ## What this exists to settle
+*
+* On 2026-08-01/02 inference across the whole fleet stalled in bursts: 759
+* calls in 90 minutes crossed the runner's 20s deadline, p50 41s and max 80s,
+* and EVERY one of them eventually resolved. Six explanations were killed with
+* telemetry alone:
+*
+*  - not a slow GPU or a wedged pool — the work completes, just enormously late;
+*  - not CPU starvation — hosts sat at 8-48% during the freezes;
+*  - not swap — `pswpin/pswpout` are flat zero on every host;
+*  - not a logging artifact — Loki's timestamp trails the in-process one by
+*    0.1-1.0s at p95, so the gaps are real, not buffered delivery;
+*  - not the v1.2.30 release — the stalls predate it by a day;
+*  - not only the idle-pool recompile — that is real and hub-side, but the
+*    agent stalls with no eviction and no compile at all.
+*
+* What IS established: the 10s stats timer — which touches no inference code —
+* stops firing for 22-88s and resumes at the same instant the abandoned calls
+* settle. The event loop itself freezes. From outside the process, GC and a
+* synchronous block are indistinguishable, and guessing between them is how
+* this investigation would go wrong. So measure it.
+*
+* ## How
+*
+* A 1s interval whose LATENESS is the freeze: a tick that arrives 40s late means
+* the loop was blocked ~39s, whatever blocked it. In the same window the GC
+* observer accumulates pause time. The two numbers together answer the question
+* outright:
+*
+*  - `gcMs` ≈ `stallMs` → garbage collection. Look at heap growth.
+*  - `gcMs` ≈ 0 → something SYNCHRONOUS blocked the loop, and GC is innocent.
+*
+* Heap and RSS ride along because if it is GC, the next question is always
+* "growing since when?".
+*
+* Deliberately not a histogram (`monitorEventLoopDelay`): that reports a
+* distribution, and the question here is about ONE outlier and what coincided
+* with it.
+*/
+/** Tick period. Small enough to bound attribution error, large enough to cost
+*  nothing on a process already doing frame work. */
+var STALL_TICK_MS = 1e3;
+/**
+* Report a freeze only past this. The runner's own inference deadline is 20s
+* and the observed freezes run 22-88s, so this is far below the signal while
+* staying clear of ordinary scheduling jitter (a busy frame path routinely
+* overruns a 1s timer by tens of ms).
+*/
+var STALL_REPORT_MS = 2e3;
+/**
+* Attribute a freeze. Pure, because this is the ONE judgement the whole module
+* exists to make and it must be testable without freezing a real event loop.
+*
+* `gc` when garbage collection accounts for most of the stall; a
+* `synchronous-block` when it accounts for almost none — that verdict points
+* away from the heap entirely and at whatever ran without yielding.
+*/
+function attributeStall(stallMs, gcMs, gcCount, longestGcMs) {
+	const share = stallMs > 0 ? gcMs / stallMs : 0;
+	return {
+		stallMs,
+		gcMs,
+		gcCount,
+		longestGcMs,
+		cause: share >= .7 ? "gc" : share <= .2 ? "synchronous-block" : "mixed"
+	};
+}
+/**
+* Start watching. Returns a stop function; safe to call twice.
+*
+* Never throws into the caller: a diagnostic that can take the detection
+* process down is worse than no diagnostic. `PerformanceObserver` for `gc` is
+* unavailable in some embedded runtimes, and that must degrade to
+* stall-detection-without-attribution rather than a boot failure.
+*/
+function startEventLoopStallMonitor(logger, reportThresholdMs = STALL_REPORT_MS) {
+	let gc = {
+		totalMs: 0,
+		count: 0,
+		longestMs: 0
+	};
+	let observer = null;
+	try {
+		observer = new node_perf_hooks.PerformanceObserver((list) => {
+			for (const entry of list.getEntries()) {
+				gc.totalMs += entry.duration;
+				gc.count += 1;
+				if (entry.duration > gc.longestMs) gc.longestMs = entry.duration;
+			}
+		});
+		observer.observe({ entryTypes: ["gc"] });
+	} catch {
+		observer = null;
+	}
+	let expected = Date.now() + STALL_TICK_MS;
+	const timer = setInterval(() => {
+		const now = Date.now();
+		const lateBy = now - expected;
+		const window = gc;
+		gc = {
+			totalMs: 0,
+			count: 0,
+			longestMs: 0
+		};
+		expected = now + STALL_TICK_MS;
+		if (lateBy < reportThresholdMs) return;
+		const verdict = attributeStall(lateBy, Math.round(window.totalMs), window.count, Math.round(window.longestMs));
+		const mem = process.memoryUsage();
+		logger.warn("event loop stalled", { meta: {
+			stallMs: verdict.stallMs,
+			cause: verdict.cause,
+			gcMs: verdict.gcMs,
+			gcCount: verdict.gcCount,
+			longestGcMs: verdict.longestGcMs,
+			gcObserved: observer !== null,
+			heapUsedMb: Math.round(mem.heapUsed / 1e6),
+			heapTotalMb: Math.round(mem.heapTotal / 1e6),
+			rssMb: Math.round(mem.rss / 1e6),
+			externalMb: Math.round(mem.external / 1e6),
+			arrayBuffersMb: Math.round(mem.arrayBuffers / 1e6)
+		} });
+	}, STALL_TICK_MS);
+	timer.unref?.();
+	let stopped = false;
+	return () => {
+		if (stopped) return;
+		stopped = true;
+		clearInterval(timer);
+		observer?.disconnect();
+	};
+}
+//#endregion
 //#region src/detection-pipeline/python-readiness.ts
 /**
 * Resolve the embedded Python once, turning the null/throw failure modes into
@@ -7448,6 +7462,8 @@ var DetectionPipelineAddon = class extends require_dist.BaseAddon {
 	*  doesn't flip a remote node's env back to the serving hub's platform. */
 	lastGoodHardwareByNode = /* @__PURE__ */ new Map();
 	engineMetricsTimer = null;
+	/** Stops the event-loop stall monitor on shutdown. */
+	stopStallMonitor = null;
 	/** Snapshot-equality cache for engine-metrics emit. Most ticks
 	*  the engine inventory is unchanged (no model load/unload), so
 	*  we skip the bus emit and let the heartbeat re-emit at
@@ -7786,6 +7802,7 @@ var DetectionPipelineAddon = class extends require_dist.BaseAddon {
 	async onInitialize() {
 		const modelsDir = await this.resolveModelsDir();
 		if (!this.ctx.settings) throw new Error("DetectionPipelineAddon: ctx.settings not available");
+		this.stopStallMonitor = startEventLoopStallMonitor(this.ctx.logger);
 		this.pythonAddonDir = resolveAddonPythonDir();
 		const py = await ensurePythonReady(this.ctx.deps, this.ctx.logger);
 		if (py.ok && py.pythonPath) this.pythonPath = py.pythonPath;
@@ -7872,6 +7889,10 @@ var DetectionPipelineAddon = class extends require_dist.BaseAddon {
 		}
 	}
 	async onShutdown() {
+		if (this.stopStallMonitor) {
+			this.stopStallMonitor();
+			this.stopStallMonitor = null;
+		}
 		if (this.engineMetricsTimer) {
 			clearInterval(this.engineMetricsTimer);
 			this.engineMetricsTimer = null;