@camstack/addon-pipeline 1.2.192 → 1.2.194

package/dist/pipeline-runner/index.js

@@ -2,67 +2,22 @@ Object.defineProperties(exports, {
 	__esModule: { value: true },
 	[Symbol.toStringTag]: { value: "Module" }
 });
-const require_dist = require("../dist-CXO_Fmx6.js");
-const require_node = require("../node-DF98pVP7.js");
-const require_local_frame_registry = require("../local-frame-registry-P7tSfvaY.js");
-const require_worker_protocol = require("../worker-protocol-BJzhw3t0.js");
+const require_dist = require("../dist-HG5geL9t.js");
+const require_node = require("../node--my8JTOW.js");
+const require_default_detection_model = require("../default-detection-model-CJdc8j83.js");
+const require_worker_protocol = require("../worker-protocol-DCsi4YS1.js");
 const require_hub_hostname = require("../hub-hostname-DAJXlOgV.js");
-const require_lazy_sharp = require("../lazy-sharp-o-aNNXuz.js");
+const require_lazy_sharp = require("../lazy-sharp-DmAwZ0s9.js");
 const require_restream_intent = require("../restream-intent-Cv9x3jmu.js");
 const require_event_loop_stall_monitor = require("../event-loop-stall-monitor-DaUBcb13.js");
 const require_remote_restream = require("../remote-restream-CO36Sr30.js");
+let node_os = require("node:os");
+node_os = require_dist.__toESM(node_os);
 let node_child_process = require("node:child_process");
 let sharp = require("sharp");
 sharp = require_dist.__toESM(sharp);
 let node_url = require("node:url");
 let node_perf_hooks = require("node:perf_hooks");
-let node_os = require("node:os");
-node_os = require_dist.__toESM(node_os);
-//#region src/pipeline-runner/first-detection-frame.ts
-/**
-* How long a camera waits, after `attachCamera`, before a decoded frame
-* actually reaches the detection queue.
-*
-* The orchestrator already measures `session motion → attach latency` and it
-* is small — 11, 13 and 18 ms across three consecutive sessions on the same
-* camera. What nothing measured is the NEXT leg: from the attach to the first
-* frame the detector is given. An operator reporting "detection starts late"
-* is describing that leg, and answering them required reading the timestamps
-* of unrelated INFO lines and inferring — which produced a wrong first answer
-* (the absence of a `frame processed` line means the frame produced nothing
-* notable, not that no frame arrived).
-*
-* One number, once per attach, so a slow start is a value rather than an
-* inference.
-*/
-/** Pending attach marks, keyed by device. */
-var FirstDetectionFrameTimer = class {
-	attachedAt = /* @__PURE__ */ new Map();
-	/** A camera attached. Replaces any pending mark: the newest attach is the
-	*  one the next frame belongs to. */
-	markAttached(deviceId, nowMs) {
-		this.attachedAt.set(deviceId, nowMs);
-	}
-	/**
-	* A decoded frame was admitted to the detection queue. Returns the elapsed
-	* ms since the attach the FIRST time it is called after one, and `null`
-	* every time after — so the caller logs once per attach, not once per frame.
-	*/
-	takeLatency(deviceId, nowMs) {
-		const at = this.attachedAt.get(deviceId);
-		if (at === void 0) return null;
-		this.attachedAt.delete(deviceId);
-		return Math.max(0, nowMs - at);
-	}
-	/** A camera detached with no frame ever admitted — drop the mark so the
-	*  NEXT attach is not measured from this one. Returns whether one was
-	*  pending, which is itself the interesting fact: a session that ran and
-	*  fed the detector nothing. */
-	forget(deviceId) {
-		return this.attachedAt.delete(deviceId);
-	}
-};
-//#endregion
 //#region src/session-decode/fork-decode-worker.ts
 /** Absolute path to the built decode-worker child entry (a vite build entry). */
 var CHILD_ENTRY_PATH = (0, node_url.fileURLToPath)(new URL("../session-decode/decode-worker-child.js", require("url").pathToFileURL(__filename).href));
@@ -527,6 +482,57 @@ var NativeCropRegistry = class {
 	}
 };
 //#endregion
+//#region src/session-decode/node-decode-budget.ts
+/**
+* The decode RAM budget and worker cap THIS node runs under.
+*
+* `nodeDecodeBudgetMb` and `maxLiveDecodeWorkers` are cluster settings — one
+* number for a 64 GB hub and a 16 GB Mac alike. Until 2026-09-05 the shipped
+* 8192 MB was the hub's number applied everywhere; with the footprint fixed
+* (D361) that admits 8 workers on the Mac, whose workers measure RSS p90
+* 952 MB on a machine already at 80% — 7.6 GB of decode on 16 GB is a swap
+* away from a stall — while the hub leaves 56 GB idle.
+*
+* Three sources, in order, and the winner is NAMED so a log line can say why:
+*  1. the node's own agent setting (`decodeBudgetMb` / `maxLiveDecodeWorkers`
+*     in `AgentPipelineSettings`) — the operator sized this node;
+*  2. the cluster setting when the operator MOVED it off the shipped default
+*     (a value equal to the default reads as "nobody chose", the same rule the
+*     native-lease knobs use, `readKnob`);
+*  3. otherwise a share of the node's RAM, clamped — the shipped default
+*     becomes a per-node derivation instead of the hub's number.
+*/
+var DECODE_BUDGET_RAM_SHARE = .5;
+var DECODE_BUDGET_MIN_MB = 2048;
+var DECODE_BUDGET_MAX_MB = 16384;
+function derivedDecodeBudgetMb(totalMemMb) {
+	const share = Math.round(totalMemMb * DECODE_BUDGET_RAM_SHARE);
+	return Math.max(DECODE_BUDGET_MIN_MB, Math.min(DECODE_BUDGET_MAX_MB, share));
+}
+function resolveNodeDecodeLimits(input) {
+	const budget = input.node.decodeBudgetMb !== void 0 ? {
+		budgetMb: input.node.decodeBudgetMb,
+		budgetSource: "node"
+	} : input.clusterBudgetMb !== input.defaultBudgetMb ? {
+		budgetMb: input.clusterBudgetMb,
+		budgetSource: "cluster"
+	} : {
+		budgetMb: derivedDecodeBudgetMb(input.totalMemMb),
+		budgetSource: "derived"
+	};
+	const workers = input.node.maxLiveDecodeWorkers !== void 0 ? {
+		maxWorkers: input.node.maxLiveDecodeWorkers,
+		maxWorkersSource: "node"
+	} : {
+		maxWorkers: input.clusterMaxWorkers,
+		maxWorkersSource: "cluster"
+	};
+	return {
+		...budget,
+		...workers
+	};
+}
+//#endregion
 //#region src/session-decode/retained-content-fallback.ts
 /**
 * Honest ≤640 RAM fallback for `getNativeCrop` full-frame misses.
@@ -928,55 +934,6 @@ function cropRgb(frame, bbox, maxWidth) {
 	};
 }
 //#endregion
-//#region src/pipeline-runner/frame-cutter-binding.ts
-/** The per-frame binding key — the same identity the retention handle carries. */
-function frameCutterKey(handle) {
-	return `${handle.shmId}#${handle.slot}#${handle.seq}`;
-}
-var FrameCutterBinding = class {
-	max;
-	map = /* @__PURE__ */ new Map();
-	constructor(max) {
-		this.max = max;
-	}
-	/** Bind at delivery. Re-binding the same handle replaces without stranding the first. */
-	bind(handle, cutter) {
-		const key = frameCutterKey(handle);
-		this.map.delete(key);
-		this.map.set(key, cutter);
-		while (this.map.size > this.max) {
-			const oldest = this.map.keys().next().value;
-			if (oldest === void 0) break;
-			const stale = this.map.get(oldest);
-			this.map.delete(oldest);
-			release(stale);
-		}
-	}
-	/** Consume the binding for a frame whose result arrived. `undefined` when already ended. */
-	take(handle) {
-		const key = frameCutterKey(handle);
-		const cutter = this.map.get(key);
-		this.map.delete(key);
-		return cutter;
-	}
-	/**
-	* End the hold of a frame the runner let go without a result. A no-op for a
-	* frame whose result already consumed the binding, so the two paths cannot
-	* double-release.
-	*/
-	drop(handle) {
-		release(this.take(handle));
-	}
-	get size() {
-		return this.map.size;
-	}
-};
-function release(cutter) {
-	try {
-		cutter?.release();
-	} catch {}
-}
-//#endregion
 //#region src/session-decode/session-decode-coordinator.ts
 /** How long to wait after `kill()` before escalating to `kill('SIGKILL')`. */
 var SIGKILL_FALLBACK_MS = 1e3;
@@ -1511,7 +1468,7 @@ function createSessionDecodeCoordinator(deps) {
 * shm-ring cameras.
 */
 async function toDecodedFrame(frame, format, viewSpec) {
-	const geometry = viewSpec ? require_local_frame_registry.resolveFrameViewGeometry(frame.image.width, frame.image.height, viewSpec) : void 0;
+	const geometry = viewSpec ? require_default_detection_model.resolveFrameViewGeometry(frame.image.width, frame.image.height, viewSpec) : void 0;
 	const bytes = await frame.image.toBuffer(geometry ? {
 		crop: geometry.sourceCrop,
 		resize: geometry.output,
@@ -2919,12 +2876,174 @@ function summarizeDeviceLoad(attachedDeviceKeys) {
 		if (!key) continue;
 		counts.set(key, (counts.get(key) ?? 0) + 1);
 	}
-	return Array.from(counts.entries()).map(([deviceKey, attachedCameras]) => ({
-		deviceKey,
-		backend: backendOf(deviceKey),
-		attachedCameras,
-		queueDepthTotal: 0
-	})).toSorted((a, b) => a.deviceKey.localeCompare(b.deviceKey));
+	return Array.from(counts.entries()).map(([deviceKey, attachedCameras]) => ({
+		deviceKey,
+		backend: backendOf(deviceKey),
+		attachedCameras,
+		queueDepthTotal: 0
+	})).toSorted((a, b) => a.deviceKey.localeCompare(b.deviceKey));
+}
+//#endregion
+//#region src/pipeline-runner/failure-report.ts
+/**
+* What `pipeline-runner` reports through `failure-contribution` — the inference
+* deadline, per camera, with the frames that made it as the denominator.
+*
+* ## The number that was never divided
+*
+* ~120 `inference timed out — permit released, result discarded` lines in six
+* hours across seven cameras, on 2026-08-28, never investigated. The line has
+* carried `tags: { deviceId }` for a while, so the count per camera was always
+* available; what was not available was the number to divide it by. 120
+* timeouts out of 120 000 admitted frames and 120 out of 1 200 are opposite
+* findings and produce identical log volume.
+*
+* So the counter takes BOTH outcomes of the same await, from the same place in
+* `awaitInferenceBounded`. A success counted anywhere else would eventually
+* drift from the failure and turn the ratio into fiction.
+*
+* ## Why there is no `variant` yet
+*
+* `failure-contribution` has a `variant` slot exactly so "which camera AND
+* which model" is one read, and the operator asked for it. The runner cannot
+* fill it honestly: `awaitInferenceBounded` wraps
+* `config.processFrame(deviceId, frameInput, executorHandle)`, which runs the
+* camera's WHOLE pipeline graph behind one deadline. Nothing at this seam knows
+* which step was still running when the 20 s expired — `CameraRegistration`
+* carries fps and mode, not models.
+*
+* Naming the step means the executor attributing the deadline to the step that
+* held it, and reporting THAT. Emitting a `variant` the runner guessed (the
+* camera's configured graph id, say) would be worse than leaving it absent: it
+* would look like an attribution and be a label. Absent, never invented — the
+* same rule `load-contribution` states for a measurement nobody made.
+*/
+/** One bounded inference deadline per admitted detection frame. */
+var FAMILY_INFERENCE = "inference";
+/** The call did not return inside `inferenceTimeoutMs`. */
+var REASON_INFERENCE_TIMEOUT = "timeout";
+/**
+* The runner's `failure-contribution` counters.
+*
+* One instance per runner process, read (never drained) by the provider.
+*/
+var RunnerFailureReport = class {
+	now;
+	counters;
+	constructor(now = Date.now, counters = new require_dist.FailureCounters()) {
+		this.now = now;
+		this.counters = counters;
+	}
+	/** One bounded inference call. `reason` absent = it returned in time. */
+	noteInference(deviceId, reason) {
+		this.counters.note({
+			deviceId,
+			family: FAMILY_INFERENCE,
+			...reason !== void 0 ? { reason } : {}
+		}, this.now());
+	}
+	/** The `failure-contribution` provider's payload. Reads, never resets. */
+	list() {
+		return this.counters.snapshot(this.now());
+	}
+	/** Addon disposal. */
+	clear() {
+		this.counters.clear();
+	}
+};
+//#endregion
+//#region src/pipeline-runner/first-detection-frame.ts
+/**
+* How long a camera waits, after `attachCamera`, before a decoded frame
+* actually reaches the detection queue.
+*
+* The orchestrator already measures `session motion → attach latency` and it
+* is small — 11, 13 and 18 ms across three consecutive sessions on the same
+* camera. What nothing measured is the NEXT leg: from the attach to the first
+* frame the detector is given. An operator reporting "detection starts late"
+* is describing that leg, and answering them required reading the timestamps
+* of unrelated INFO lines and inferring — which produced a wrong first answer
+* (the absence of a `frame processed` line means the frame produced nothing
+* notable, not that no frame arrived).
+*
+* One number, once per attach, so a slow start is a value rather than an
+* inference.
+*/
+/** Pending attach marks, keyed by device. */
+var FirstDetectionFrameTimer = class {
+	attachedAt = /* @__PURE__ */ new Map();
+	/** A camera attached. Replaces any pending mark: the newest attach is the
+	*  one the next frame belongs to. */
+	markAttached(deviceId, nowMs) {
+		this.attachedAt.set(deviceId, nowMs);
+	}
+	/**
+	* A decoded frame was admitted to the detection queue. Returns the elapsed
+	* ms since the attach the FIRST time it is called after one, and `null`
+	* every time after — so the caller logs once per attach, not once per frame.
+	*/
+	takeLatency(deviceId, nowMs) {
+		const at = this.attachedAt.get(deviceId);
+		if (at === void 0) return null;
+		this.attachedAt.delete(deviceId);
+		return Math.max(0, nowMs - at);
+	}
+	/** A camera detached with no frame ever admitted — drop the mark so the
+	*  NEXT attach is not measured from this one. Returns whether one was
+	*  pending, which is itself the interesting fact: a session that ran and
+	*  fed the detector nothing. */
+	forget(deviceId) {
+		return this.attachedAt.delete(deviceId);
+	}
+};
+//#endregion
+//#region src/pipeline-runner/frame-cutter-binding.ts
+/** The per-frame binding key — the same identity the retention handle carries. */
+function frameCutterKey(handle) {
+	return `${handle.shmId}#${handle.slot}#${handle.seq}`;
+}
+var FrameCutterBinding = class {
+	max;
+	map = /* @__PURE__ */ new Map();
+	constructor(max) {
+		this.max = max;
+	}
+	/** Bind at delivery. Re-binding the same handle replaces without stranding the first. */
+	bind(handle, cutter) {
+		const key = frameCutterKey(handle);
+		this.map.delete(key);
+		this.map.set(key, cutter);
+		while (this.map.size > this.max) {
+			const oldest = this.map.keys().next().value;
+			if (oldest === void 0) break;
+			const stale = this.map.get(oldest);
+			this.map.delete(oldest);
+			release(stale);
+		}
+	}
+	/** Consume the binding for a frame whose result arrived. `undefined` when already ended. */
+	take(handle) {
+		const key = frameCutterKey(handle);
+		const cutter = this.map.get(key);
+		this.map.delete(key);
+		return cutter;
+	}
+	/**
+	* End the hold of a frame the runner let go without a result. A no-op for a
+	* frame whose result already consumed the binding, so the two paths cannot
+	* double-release.
+	*/
+	drop(handle) {
+		release(this.take(handle));
+	}
+	get size() {
+		return this.map.size;
+	}
+};
+function release(cutter) {
+	try {
+		cutter?.release();
+	} catch {}
 }
 //#endregion
 //#region src/pipeline-runner/frame-lazy-metrics.ts
@@ -3499,57 +3618,6 @@ var NodeDecodeLimitsSource = class {
 	}
 };
 //#endregion
-//#region src/session-decode/node-decode-budget.ts
-/**
-* The decode RAM budget and worker cap THIS node runs under.
-*
-* `nodeDecodeBudgetMb` and `maxLiveDecodeWorkers` are cluster settings — one
-* number for a 64 GB hub and a 16 GB Mac alike. Until 2026-09-05 the shipped
-* 8192 MB was the hub's number applied everywhere; with the footprint fixed
-* (D361) that admits 8 workers on the Mac, whose workers measure RSS p90
-* 952 MB on a machine already at 80% — 7.6 GB of decode on 16 GB is a swap
-* away from a stall — while the hub leaves 56 GB idle.
-*
-* Three sources, in order, and the winner is NAMED so a log line can say why:
-*  1. the node's own agent setting (`decodeBudgetMb` / `maxLiveDecodeWorkers`
-*     in `AgentPipelineSettings`) — the operator sized this node;
-*  2. the cluster setting when the operator MOVED it off the shipped default
-*     (a value equal to the default reads as "nobody chose", the same rule the
-*     native-lease knobs use, `readKnob`);
-*  3. otherwise a share of the node's RAM, clamped — the shipped default
-*     becomes a per-node derivation instead of the hub's number.
-*/
-var DECODE_BUDGET_RAM_SHARE = .5;
-var DECODE_BUDGET_MIN_MB = 2048;
-var DECODE_BUDGET_MAX_MB = 16384;
-function derivedDecodeBudgetMb(totalMemMb) {
-	const share = Math.round(totalMemMb * DECODE_BUDGET_RAM_SHARE);
-	return Math.max(DECODE_BUDGET_MIN_MB, Math.min(DECODE_BUDGET_MAX_MB, share));
-}
-function resolveNodeDecodeLimits(input) {
-	const budget = input.node.decodeBudgetMb !== void 0 ? {
-		budgetMb: input.node.decodeBudgetMb,
-		budgetSource: "node"
-	} : input.clusterBudgetMb !== input.defaultBudgetMb ? {
-		budgetMb: input.clusterBudgetMb,
-		budgetSource: "cluster"
-	} : {
-		budgetMb: derivedDecodeBudgetMb(input.totalMemMb),
-		budgetSource: "derived"
-	};
-	const workers = input.node.maxLiveDecodeWorkers !== void 0 ? {
-		maxWorkers: input.node.maxLiveDecodeWorkers,
-		maxWorkersSource: "node"
-	} : {
-		maxWorkers: input.clusterMaxWorkers,
-		maxWorkersSource: "cluster"
-	};
-	return {
-		...budget,
-		...workers
-	};
-}
-//#endregion
 //#region src/session-decode/on-demand-jpeg-fallback.ts
 /** Single content-sized JPEG requested after a detection, never a continuous raw. */
 var ON_DEMAND_JPEG_VIEW = {
@@ -3895,74 +3963,6 @@ function packageZoneUnion(polygons) {
 	};
 }
 //#endregion
-//#region src/pipeline-runner/failure-report.ts
-/**
-* What `pipeline-runner` reports through `failure-contribution` — the inference
-* deadline, per camera, with the frames that made it as the denominator.
-*
-* ## The number that was never divided
-*
-* ~120 `inference timed out — permit released, result discarded` lines in six
-* hours across seven cameras, on 2026-08-28, never investigated. The line has
-* carried `tags: { deviceId }` for a while, so the count per camera was always
-* available; what was not available was the number to divide it by. 120
-* timeouts out of 120 000 admitted frames and 120 out of 1 200 are opposite
-* findings and produce identical log volume.
-*
-* So the counter takes BOTH outcomes of the same await, from the same place in
-* `awaitInferenceBounded`. A success counted anywhere else would eventually
-* drift from the failure and turn the ratio into fiction.
-*
-* ## Why there is no `variant` yet
-*
-* `failure-contribution` has a `variant` slot exactly so "which camera AND
-* which model" is one read, and the operator asked for it. The runner cannot
-* fill it honestly: `awaitInferenceBounded` wraps
-* `config.processFrame(deviceId, frameInput, executorHandle)`, which runs the
-* camera's WHOLE pipeline graph behind one deadline. Nothing at this seam knows
-* which step was still running when the 20 s expired — `CameraRegistration`
-* carries fps and mode, not models.
-*
-* Naming the step means the executor attributing the deadline to the step that
-* held it, and reporting THAT. Emitting a `variant` the runner guessed (the
-* camera's configured graph id, say) would be worse than leaving it absent: it
-* would look like an attribution and be a label. Absent, never invented — the
-* same rule `load-contribution` states for a measurement nobody made.
-*/
-/** One bounded inference deadline per admitted detection frame. */
-var FAMILY_INFERENCE = "inference";
-/** The call did not return inside `inferenceTimeoutMs`. */
-var REASON_INFERENCE_TIMEOUT = "timeout";
-/**
-* The runner's `failure-contribution` counters.
-*
-* One instance per runner process, read (never drained) by the provider.
-*/
-var RunnerFailureReport = class {
-	now;
-	counters;
-	constructor(now = Date.now, counters = new require_dist.FailureCounters()) {
-		this.now = now;
-		this.counters = counters;
-	}
-	/** One bounded inference call. `reason` absent = it returned in time. */
-	noteInference(deviceId, reason) {
-		this.counters.note({
-			deviceId,
-			family: FAMILY_INFERENCE,
-			...reason !== void 0 ? { reason } : {}
-		}, this.now());
-	}
-	/** The `failure-contribution` provider's payload. Reads, never resets. */
-	list() {
-		return this.counters.snapshot(this.now());
-	}
-	/** Addon disposal. */
-	clear() {
-		this.counters.clear();
-	}
-};
-//#endregion
 //#region src/pipeline-runner/frame-governor.ts
 var FrameGovernor = class {
 	config;
@@ -5156,6 +5156,191 @@ var PipelineRunner = class {
 		return null;
 	}
 };
+/**
+* How much of a region must lie OUTSIDE every full-frame detection for the
+* pass to run on it. A person's own blob (dilated, with shadow) is covered
+* 70–90% by the person box; a person-and-dog blob is covered ~55% by it.
+*/
+var RECOVERY_MIN_UNCOVERED_FRACTION = .35;
+function area(r) {
+	return Math.max(0, r.w) * Math.max(0, r.h);
+}
+function intersection(a, b) {
+	return Math.max(0, Math.min(a.x + a.w, b.x + b.w) - Math.max(a.x, b.x)) * Math.max(0, Math.min(a.y + a.h, b.y + b.h) - Math.max(a.y, b.y));
+}
+/**
+* Share of `region` not covered by any detection box. The sum of pairwise
+* intersections over-counts where detections overlap each other, which only
+* makes the pass MORE conservative; clipped at 1.
+*/
+function uncoveredFraction(region, detections) {
+	const regionArea = area(region);
+	if (regionArea <= 0) return 0;
+	let covered = 0;
+	for (const detection of detections) covered += intersection(region, detection);
+	return 1 - Math.min(1, covered / regionArea);
+}
+function squareAround(centreX, centreY, side, native) {
+	return {
+		left: Math.round(Math.max(0, Math.min(native.width - side, centreX - side / 2))),
+		top: Math.round(Math.max(0, Math.min(native.height - side, centreY - side / 2))),
+		side
+	};
+}
+function contains(crop, x, y) {
+	return x >= crop.left && x <= crop.left + crop.side && y >= crop.top && y <= crop.top + crop.side;
+}
+/**
+* Squares for one region: one when it fits the largest side, otherwise up to
+* two tiles along its longer axis (a person-sized blob with something small
+* at either end). The padded region decides the side, never the frame.
+*/
+function cropsForRegion(region, native) {
+	const widthPx = region.w * native.width;
+	const heightPx = region.h * native.height;
+	const longest = Math.max(widthPx, heightPx);
+	const padded = longest * 1.5;
+	const side = Math.round(Math.min(Math.max(padded, 640), 800));
+	const centreX = (region.x + region.w / 2) * native.width;
+	const centreY = (region.y + region.h / 2) * native.height;
+	if (padded <= 800) return [squareAround(centreX, centreY, side, native)];
+	const alongX = widthPx >= heightPx;
+	const quarter = longest / 4;
+	return [squareAround(alongX ? centreX - quarter : centreX, alongX ? centreY : centreY - quarter, side, native), squareAround(alongX ? centreX + quarter : centreX, alongX ? centreY : centreY + quarter, side, native)];
+}
+/**
+* The crops the second pass runs on this frame — possibly none.
+*
+* A region qualifies when it is small (`RECOVERY_MAX_REGION_FRAME_FRACTION`)
+* and mostly uncovered by the full-frame boxes
+* (`RECOVERY_MIN_UNCOVERED_FRACTION`). Qualifying regions are served largest
+* uncovered area first under `RECOVERY_MAX_CROPS_PER_FRAME`; a crop whose
+* centre already lies inside a planned crop is folded into it. A frame that
+* cannot hold the smallest crop yields nothing: it is already seen at scale.
+*/
+function planRecoveryCrops(input) {
+	const { native } = input;
+	if (Math.min(native.width, native.height) < 640) return [];
+	const ranked = input.regions.map((region) => ({
+		region,
+		uncovered: uncoveredFraction(region, input.detections)
+	})).filter(({ region, uncovered }) => {
+		if (area(region) > .25) return false;
+		return uncovered >= RECOVERY_MIN_UNCOVERED_FRACTION;
+	}).toSorted((a, b) => area(b.region) * b.uncovered - area(a.region) * a.uncovered);
+	const planned = [];
+	for (const { region } of ranked) for (const crop of cropsForRegion(region, native)) {
+		if (planned.length >= 2) return planned;
+		const centreX = crop.left + crop.side / 2;
+		const centreY = crop.top + crop.side / 2;
+		if (planned.some((existing) => contains(existing, centreX, centreY))) continue;
+		planned.push(crop);
+	}
+	return planned;
+}
+/**
+* Boxes the executor produced on the crop VIEW → the result's own space.
+*
+* Three spaces meet here: the view the model saw (`view`, ≤640 px), the native
+* square it was cut from (`crop`, native px) and the space the full-frame
+* result reports in (`result`, native px on the `frameRef` path, the inline
+* ≤640 view otherwise). A box touching the view edge was clipped by the crop
+* and is dropped: half a person is not a person, and the tracker would take
+* the half as the whole.
+*/
+function remapCropDetections(detections, crop, view, result, native) {
+	const viewToNative = crop.side / Math.max(1, view.width);
+	const nativeToResultX = result.width / Math.max(1, native.width);
+	const nativeToResultY = result.height / Math.max(1, native.height);
+	const out = [];
+	for (const detection of detections) {
+		const { x, y, width, height } = detection.bbox;
+		if (x <= 2 || y <= 2 || x + width >= view.width - 2 || y + height >= view.height - 2) continue;
+		out.push({
+			...detection,
+			bbox: {
+				x: (crop.left + x * viewToNative) * nativeToResultX,
+				y: (crop.top + y * viewToNative) * nativeToResultY,
+				width: width * viewToNative * nativeToResultX,
+				height: height * viewToNative * nativeToResultY
+			}
+		});
+	}
+	return out;
+}
+function boxIntersection(a, b) {
+	return Math.max(0, Math.min(a.x + a.width, b.x + b.width) - Math.max(a.x, b.x)) * Math.max(0, Math.min(a.y + a.height, b.y + b.height) - Math.max(a.y, b.y));
+}
+function sameSubject(recovered, existing) {
+	const inter = boxIntersection(recovered, existing);
+	if (inter <= 0) return false;
+	const areaR = recovered.width * recovered.height;
+	const union = areaR + existing.width * existing.height - inter;
+	if (union > 0 && inter / union >= .5) return true;
+	return areaR > 0 && inter / areaR >= .7;
+}
+/**
+* Class-aware NMS of the recovered boxes against the full-frame ones. Every
+* full-frame box is kept as it is — the second pass only ADDS. A recovered box
+* is added when no full-frame box of the same macro class is the same subject
+* (`RECOVERY_FUSE_IOU`) or contains it (`RECOVERY_FUSE_CONTAINMENT`). Ids are
+* re-minted so a crop's `d0` cannot collide with the frame's.
+*/
+function fuseRecoveredDetections(full, recovered) {
+	const accepted = [];
+	for (const [index, candidate] of recovered.entries()) {
+		if ([...full, ...accepted].some((existing) => existing.macroClass === candidate.macroClass && sameSubject(candidate.bbox, existing.bbox))) continue;
+		accepted.push({
+			...candidate,
+			id: `recovered-${index}-${candidate.id}`
+		});
+	}
+	return [...full, ...accepted];
+}
+/**
+* The step the second pass runs: the enabled first-level object detector of
+* the camera's own tree, with its own model and no children. Same model as
+* the full pass so a recovered box is comparable to a full-frame one.
+*/
+function selectRecoveryStep(steps) {
+	const detector = steps.find((step) => step.addonId === "object-detection" && step.enabled !== false);
+	if (!detector) return null;
+	return {
+		addonId: detector.addonId,
+		...detector.modelId !== void 0 ? { modelId: detector.modelId } : {},
+		enabled: true
+	};
+}
+/**
+* The analyzer's last regions per camera, normalised, with the instant they
+* were measured. Refreshed off the motion path; read on the detection path.
+* A stale entry answers nothing — the regions of two seconds ago are not this
+* frame's. An EMPTY analyzer result replaces the previous regions: motion that
+* stopped is not motion.
+*/
+var MotionRegionMirror = class {
+	byDevice = /* @__PURE__ */ new Map();
+	note(deviceId, regions, frameWidth, frameHeight, now) {
+		if (frameWidth <= 0 || frameHeight <= 0) return;
+		this.byDevice.set(deviceId, {
+			at: now,
+			regions: regions.map((region) => ({
+				x: region.bbox.x / frameWidth,
+				y: region.bbox.y / frameHeight,
+				w: region.bbox.w / frameWidth,
+				h: region.bbox.h / frameHeight
+			}))
+		});
+	}
+	fresh(deviceId, now) {
+		const entry = this.byDevice.get(deviceId);
+		if (!entry || now - entry.at > 2e3) return [];
+		return entry.regions;
+	}
+	forget(deviceId) {
+		this.byDevice.delete(deviceId);
+	}
+};
 //#endregion
 //#region src/pipeline-runner/stateless-step.ts
 function modelServability(step, modelId, format) {
@@ -5272,6 +5457,47 @@ function isUsable(bbox) {
 //#endregion
 //#region src/pipeline-runner/index.ts
 /**
+* addon-pipeline-runner — per-node detection scheduler.
+*
+* Lives on every "vision node" (hub if hub is one, every agent that runs
+* decoders/cameras). Receives camera assignments from the hub-side
+* `addon-pipeline-orchestrator` via cap calls, owns the per-camera frame
+* queues + semaphore + motion → detection phase machine, calls the local
+* `motion-detection` and `pipeline-executor` capabilities for the actual
+* work, and emits typed events on the bus
+* (`detection.motion-analysis`, `pipeline.inference-result`, `pipeline.trace`).
+*
+* Design notes:
+*
+*  - All cap inputs/outputs are serializable so the runner is transparently
+*    routable across the cluster: when the runner is co-located with the
+*    broker/decoder/motion/detection (the default and recommended deploy),
+*    capability lookups return live singletons and frame data never crosses
+*    a process boundary. When a deploy splits the runner from the executor
+*    (rare), the lookup returns null and the runner falls back to
+*    `this.ctx.api` (broker proxy) at the cost of serialization.
+*
+*  - The scheduler core (`PipelineRunner`) is callback-driven and framework
+*    agnostic. The addon class injects the inference + motion callbacks at
+*    construction time, capturing references to the relevant providers
+*    lazily on each invocation.
+*
+*  - Result post-processing (analysis pipeline, class filters, notifications)
+*    is intentionally NOT done by the runner. The runner emits the raw
+*    inference output as a `pipeline.inference-result` event on the bus;
+*    a hub-side subscriber consumes the event and runs the post-processing
+*    pipeline. This keeps the runner stateless w.r.t. detection-side
+*    business logic and makes it possible to deploy the post-processor
+*    independently from the inference workers.
+*/
+/**
+* How often the small-subject recovery pass reports per camera. The pass runs
+* up to twice a second; one aggregated line every ten seconds says how often
+* it ran, what it cost and what it found — the numbers a "did the second
+* pass help on 615?" question is answered from.
+*/
+var RECOVERY_LOG_INTERVAL_MS = 1e4;
+/**
 * How often a device's package zone-union geometry is re-read. An operator
 * redrawing a package zone takes effect within one interval; the read is a
 * cross-addon cap call reached from the per-frame package gate, so it must be
@@ -5325,7 +5551,7 @@ function writeRetainedDetectionFrame(store, deviceId, frame, retention) {
 	if (retention) return retention.admitFrame(deviceId, frame);
 	if (!store) return void 0;
 	if (!isContinuousRetainEnabled()) return store.allocateHandle(deviceId, frame) ?? void 0;
-	return store.write(deviceId, frame, frame.frameRef ? createRetainedContentFallback(require_local_frame_registry.localFrameRegistry, frame.frameRef) : void 0) ?? void 0;
+	return store.write(deviceId, frame, frame.frameRef ? createRetainedContentFallback(require_default_detection_model.localFrameRegistry, frame.frameRef) : void 0) ?? void 0;
 }
 var DETECTION_KEEPWARM_MS = 15e3;
 /**
@@ -5386,7 +5612,7 @@ function collectEnabledStepIds(steps, acc) {
 */
 function tryGetStepDefinition(stepId) {
 	try {
-		return require_local_frame_registry.getStepDefinition(stepId);
+		return require_default_detection_model.getStepDefinition(stepId);
 	} catch {
 		return null;
 	}
@@ -5686,6 +5912,16 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 	*  only (otherwise we'd emit on every analyzer frame). */
 	lastAnalyzerDetected = /* @__PURE__ */ new Map();
 	/**
+	* The analyzer's last motion regions per camera — what the small-subject
+	* recovery pass judges a full-frame result against. Written on the motion
+	* path, read on the detection path (`small-subject-recovery.ts`).
+	*/
+	motionRegions = new MotionRegionMirror();
+	/** Wall clock of the last recovery pass per camera (`RECOVERY_MIN_INTERVAL_MS`). */
+	lastRecoveryAt = /* @__PURE__ */ new Map();
+	/** Per-camera counters since the last recovery report line. */
+	recoveryStats = /* @__PURE__ */ new Map();
+	/**
 	* Gates the root-plane `package-detection` step to motion-settle edges +
 	* a low-cadence safety poll instead of every frame (packages are
 	* stationary — per-frame parcel inference is wasted cost). Consulted in
@@ -5855,7 +6091,7 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 		});
 		this.retention = new OnDemandRetentionSession({
 			store: this.retainedFrames,
-			registry: require_local_frame_registry.localFrameRegistry,
+			registry: require_default_detection_model.localFrameRegistry,
 			telemetry: this.frameLazy,
 			nodeId: this.nodeId,
 			continuousRetain: isContinuousRetainEnabled()
@@ -5868,7 +6104,7 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 			minThrottledFps: this.config.minThrottledFps,
 			processFrame: (deviceId, frame, handle) => this.runInference(deviceId, frame, handle),
 			analyzeMotion: (deviceId, frame, handle) => this.runMotionAnalysis(deviceId, frame, handle),
-			releaseFrameRef: (ref, reason) => require_local_frame_registry.localFrameRegistry.release(ref, reason),
+			releaseFrameRef: (ref, reason) => require_default_detection_model.localFrameRegistry.release(ref, reason),
 			releaseRetention: (handle, reason) => {
 				this.retention?.release(handle, reason);
 				this.frameCutters.drop(handle);
@@ -7406,6 +7642,9 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 		this.packageZoneUnionByDevice.delete(deviceId);
 		this.packageZoneUnionAt.delete(deviceId);
 		this.lastMotionNearPackageZone.delete(deviceId);
+		this.motionRegions.forget(deviceId);
+		this.lastRecoveryAt.delete(deviceId);
+		this.recoveryStats.delete(deviceId);
 		const warnPrefix = `${deviceId}:`;
 		for (const key of this.warnedNoJumpDevice) if (key.startsWith(warnPrefix)) this.warnedNoJumpDevice.delete(key);
 		this.attached.delete(deviceId);
@@ -7812,7 +8051,7 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 						return materialize;
 					},
 					...useLocalFrameRef ? {
-						frameRegistry: require_local_frame_registry.localFrameRegistry,
+						frameRegistry: require_default_detection_model.localFrameRegistry,
 						inlineWhen: () => runner.detectionBackpressure(config.deviceId),
 						inlineViewSpec: SPLIT_DETECTION_VIEW,
 						onFrameRef: async (frame, nativeCrop) => {
@@ -7830,8 +8069,9 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 								workerToRunnerBytes: 0
 							});
 							const admitted = current.detection && runner.enqueueReservedDetectionFrame(config.deviceId, frame, handle);
+							if (admitted) nativeCrop?.markInferred();
 							if (current.motion) {
-								const motion = await resolveMotionFrameView(require_local_frame_registry.localFrameRegistry, frame.frameRef);
+								const motion = await resolveMotionFrameView(require_default_detection_model.localFrameRegistry, frame.frameRef);
 								if (motion.kind === "view") runner.enqueueMotionFrame(config.deviceId, {
 									data: Buffer.from(motion.data),
 									width: motion.width,
@@ -7841,7 +8081,6 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 									capturedAt: frame.capturedAt
 								}, void 0);
 							}
-							if (admitted) nativeCrop?.markInferred();
 							return admitted;
 						}
 					} : { inlineViewSpec: SPLIT_DETECTION_VIEW },
@@ -8126,8 +8365,9 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 			raw: frame.data.byteLength,
 			jpeg: 0
 		});
+		let result;
 		try {
-			return await api.pipelineExecutor.runPipeline.mutate({
+			result = await api.pipelineExecutor.runPipeline.mutate({
 				steps: [...dispatchSteps],
 				...image !== void 0 ? { image } : selectExecutorFrameSource(executorCoLocated, frame.frameRef, frame),
 				deviceId,
@@ -8144,6 +8384,190 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 			} });
 			return null;
 		}
+		if (result === null) return null;
+		return this.recoverSmallSubjects(deviceId, frame, result, dispatchSteps, camConfig?.deviceKey);
+	}
+	/**
+	* The second detector pass at native resolution — `small-subject-recovery.ts`
+	* for the why and the geometry. This method owns only what is not pure: the
+	* per-camera rate limit, the `frameRef` lease that yields the crop view, the
+	* executor call and the report line.
+	*
+	* Runs on the frame the full pass just ran on, in this process, through the
+	* same process-local lease. Anything that makes the pass impossible (no
+	* local frame, no detector in the tree, a stale or empty motion mirror, a
+	* lease miss, an executor error) leaves the full-frame result EXACTLY as it
+	* was: the pass only ever adds.
+	*
+	* The crop is dispatched WITHOUT `deviceId` on purpose. The executor's
+	* provider applies the detection-stage zone gate to whatever result it
+	* builds, in that result's own coordinates — for a crop those are crop
+	* coordinates, and a zone polygon evaluated against them gates the wrong
+	* pixels. The recovered boxes are re-projected into frame space here, and
+	* the tracker on the analytics side applies the same detection rules in
+	* frame space (`frame-processor.ts`, zone filter), so nothing is gated
+	* twice and nothing is gated wrong. The cost is that the crop pass runs on
+	* the node's default thresholds rather than a per-device override.
+	*/
+	async recoverSmallSubjects(deviceId, frame, result, steps, deviceKey) {
+		const api = this.ctx?.api;
+		if (!api || !frame.frameRef) return result;
+		const now = Date.now();
+		if (now - (this.lastRecoveryAt.get(deviceId) ?? 0) < 500) return result;
+		const regions = this.motionRegions.fresh(deviceId, now);
+		if (regions.length === 0) return result;
+		const step = selectRecoveryStep(steps);
+		if (step === null) return result;
+		if (result.width <= 0 || result.height <= 0) return result;
+		const native = {
+			width: frame.frameRef.width,
+			height: frame.frameRef.height
+		};
+		const crops = planRecoveryCrops({
+			regions,
+			detections: result.detections.filter((d) => d.kind === "first-level").map((d) => ({
+				x: d.bbox.x / result.width,
+				y: d.bbox.y / result.height,
+				w: d.bbox.width / result.width,
+				h: d.bbox.height / result.height
+			})),
+			native
+		});
+		if (crops.length === 0) return result;
+		this.lastRecoveryAt.set(deviceId, now);
+		const log = this.ctx.logger.withTags({ deviceId });
+		const started = Date.now();
+		const recovered = [];
+		let cropsRun = 0;
+		for (const crop of crops) {
+			const view = await this.resolveRecoveryCropView(frame.frameRef, crop);
+			if (view === null) continue;
+			cropsRun += 1;
+			try {
+				const cropResult = await api.pipelineExecutor.runPipeline.mutate({
+					steps: [step],
+					image: view.jpeg,
+					plane: "frame",
+					...deviceKey ? { deviceKey } : {}
+				});
+				if (!cropResult) continue;
+				recovered.push(...remapCropDetections(cropResult.detections, crop, {
+					width: view.width,
+					height: view.height
+				}, {
+					width: result.width,
+					height: result.height
+				}, native));
+			} catch (err) {
+				log.warn("small-subject recovery: crop pass failed — full-frame result kept", { meta: {
+					error: require_dist.errMsg(err),
+					crop,
+					nodeId: this.nodeId
+				} });
+			}
+		}
+		const fused = fuseRecoveredDetections(result.detections, recovered);
+		const added = fused.length - result.detections.length;
+		this.reportRecovery(deviceId, {
+			crops: cropsRun,
+			recovered: added,
+			ms: Date.now() - started,
+			now,
+			classes: fused.slice(result.detections.length).map((d) => d.macroClass)
+		});
+		return added > 0 ? {
+			...result,
+			detections: fused
+		} : result;
+	}
+	/**
+	* One compressed ≤{@link RECOVERY_VIEW_PX} px view of a native square, from
+	* the same process-local lease the full pass resolved its view from. `null`
+	* on a miss — the frame is gone, and the full-frame result stands.
+	*/
+	async resolveRecoveryCropView(ref, crop) {
+		const lease = require_default_detection_model.localFrameRegistry.acquire(ref);
+		if (!lease) return null;
+		let reason = "error";
+		try {
+			const view = await lease.resolve({
+				crop: {
+					left: crop.left,
+					top: crop.top,
+					width: crop.side,
+					height: crop.side
+				},
+				content: {
+					width: 640,
+					height: 640
+				},
+				fit: "contain",
+				format: "jpeg"
+			});
+			if (view.kind !== "view") {
+				reason = "drop";
+				return null;
+			}
+			reason = "success";
+			const jpeg = new Uint8Array(new ArrayBuffer(view.data.byteLength));
+			jpeg.set(view.data);
+			return {
+				jpeg,
+				width: view.width,
+				height: view.height
+			};
+		} catch {
+			return null;
+		} finally {
+			lease.release(reason);
+		}
+	}
+	/** Aggregate the pass per camera and report once per {@link RECOVERY_LOG_INTERVAL_MS}. */
+	reportRecovery(deviceId, sample) {
+		const stats = this.recoveryStats.get(deviceId) ?? {
+			passes: 0,
+			crops: 0,
+			recovered: 0,
+			ms: 0,
+			reportedAt: sample.now
+		};
+		const next = {
+			passes: stats.passes + 1,
+			crops: stats.crops + sample.crops,
+			recovered: stats.recovered + sample.recovered,
+			ms: stats.ms + sample.ms,
+			reportedAt: stats.reportedAt
+		};
+		if (sample.recovered > 0) this.ctx.logger.info("small-subject recovery: the native crop pass found what the full frame missed", {
+			tags: { deviceId },
+			meta: {
+				crops: sample.crops,
+				recovered: sample.recovered,
+				classes: sample.classes,
+				ms: sample.ms
+			}
+		});
+		if (sample.now - stats.reportedAt >= RECOVERY_LOG_INTERVAL_MS) {
+			this.ctx.logger.info("small-subject recovery: pass report", {
+				tags: { deviceId },
+				meta: {
+					passes: next.passes,
+					crops: next.crops,
+					recovered: next.recovered,
+					avgMsPerPass: next.passes > 0 ? Math.round(next.ms / next.passes) : 0,
+					windowMs: sample.now - stats.reportedAt
+				}
+			});
+			this.recoveryStats.set(deviceId, {
+				passes: 0,
+				crops: 0,
+				recovered: 0,
+				ms: 0,
+				reportedAt: sample.now
+			});
+			return;
+		}
+		this.recoveryStats.set(deviceId, next);
 	}
 	/** Sticky true once the executor's provider shows up in THIS process' local
 	*  registry (the `detection` execution.group) — from then on the per-frame
@@ -8224,6 +8648,7 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 			});
 			if (!result) return;
 			const detected = result.regions.length > 0;
+			this.motionRegions.note(deviceId, result.regions, result.frameWidth, result.frameHeight, Date.now());
 			this.lastMotionNearPackageZone.set(deviceId, motionNearPackageZone({
 				regions: result.regions,
 				frameWidth: result.frameWidth,
@@ -8496,7 +8921,7 @@ var PipelineRunnerAddon = class PipelineRunnerAddon extends require_dist.BaseAdd
 						format: "rgb"
 					},
 					...useLocalFrameRef ? {
-						frameRegistry: require_local_frame_registry.localFrameRegistry,
+						frameRegistry: require_default_detection_model.localFrameRegistry,
 						inlineWhen: () => runner.detectionBackpressure(config.deviceId),
 						inlineViewSpec: SPLIT_DETECTION_VIEW,
 						onFrameRef: (frame, nativeCrop) => {