@camstack/addon-pipeline 1.2.18 → 1.2.27

package/dist/{model-download-service-Cp9f4dk6-WO-foD7W.mjs → model-download-service-Cp9f4dk6-CwUb5v3Y.mjs}

@@ -1,33 +1,8 @@
-import { createRequire } from "node:module";
 import * as fs from "node:fs";
 import { createReadStream, promises } from "node:fs";
 import * as path$1 from "node:path";
 import path from "node:path";
 import "node:crypto";
-//#region \0rolldown/runtime.js
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
-var __copyProps = (to, from, except, desc) => {
-	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
-		key = keys[i];
-		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
-			get: ((k) => from[k]).bind(null, key),
-			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-		});
-	}
-	return to;
-};
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
-	value: mod,
-	enumerable: true
-}) : target, mod));
-var __require = /* @__PURE__ */ createRequire(import.meta.url);
-//#endregion
 //#region ../system/dist/model-download-service-Cp9f4dk6.mjs
 /**
 * Map a rel path to one candidate absolute path PER root, keeping only roots the
@@ -353,4 +328,4 @@ function deleteModelFromDisk(modelsDir, entry, format) {
 	return true;
 }
 //#endregion
-export { ensureModel as a, __commonJSMin as c, downloadFile as i, __require as l, createFileDataPlaneHandler as n, isModelDownloaded as o, deleteModelFromDisk as r, parseRangeHeader as s, contentTypeFor as t, __toESM as u };
+export { ensureModel as a, downloadFile as i, createFileDataPlaneHandler as n, isModelDownloaded as o, deleteModelFromDisk as r, parseRangeHeader as s, contentTypeFor as t };

package/dist/motion-wasm/index.js

@@ -2,7 +2,7 @@ Object.defineProperties(exports, {
 	__esModule: { value: true },
 	[Symbol.toStringTag]: { value: "Module" }
 });
-const require_dist = require("../dist-DDTAur0R.js");
+const require_dist = require("../dist-DUHlZcWd.js");
 let node_fs = require("node:fs");
 let node_path = require("node:path");
 //#region src/motion-wasm/wasm-motion-detector.ts

package/dist/motion-wasm/index.mjs

@@ -1,4 +1,4 @@
-import { A as motionDetectionCapability, K as hydrateSchema, T as evaluateZoneRules, V as BaseAddon, W as DeviceType } from "../dist-OjOsoSZG.mjs";
+import { A as motionDetectionCapability, E as evaluateZoneRules, K as hydrateSchema, V as BaseAddon, W as DeviceType } from "../dist-CsKaXmP8.mjs";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 //#region src/motion-wasm/wasm-motion-detector.ts

package/dist/pipeline-runner/index.js

@@ -3,11 +3,11 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../chunk-emK7D4bc.js");
-const require_dist = require("../dist-DDTAur0R.js");
+const require_dist = require("../dist-DUHlZcWd.js");
 const require_remote_restream = require("../remote-restream-CO36Sr30.js");
 const require_hub_hostname = require("../hub-hostname-DAJXlOgV.js");
 const require_worker_protocol = require("../worker-protocol-DextwlTX.js");
-const require_step_definitions = require("../step-definitions-DGCuoeCj.js");
+const require_step_definitions = require("../step-definitions-Bo1hJQQw.js");
 let node_child_process = require("node:child_process");
 let node_url = require("node:url");
 let sharp = require("sharp");
@@ -575,6 +575,22 @@ var PipelineTimingSampler = class {
 //#endregion
 //#region src/pipeline-runner/runner.ts
 /**
+* Bound on one `processFrame` call. Chosen well above the slowest legitimate
+* inference seen in production (8 617 ms, GPU contention on the hub) so the
+* timeout only ever fires on a call that is genuinely never coming back.
+*/
+var DEFAULT_INFERENCE_TIMEOUT_MS = 2e4;
+/** Grace period before a permit-starved scheduler with queued work warns. */
+var DEFAULT_INFERENCE_STALL_WARN_MS = 6e4;
+/** Re-warn cadence while a stall persists, so a wedge stays visible. */
+var INFERENCE_STALL_REWARN_MS = 6e4;
+/**
+* Sentinel distinguishing "the bound expired" from a legitimate `null`
+* (`processFrame` returning no result). A unique symbol, so it can never
+* collide with a value the executor produces.
+*/
+var TIMED_OUT = Symbol("inference-timed-out");
+/**
 * Clone a {@link DetectionQueueEntry} for the queue's copy-on-retain
 * boundary: the inner frame's pixel buffer is detached via
 * {@link ownFrame}, the `FrameHandle` is carried through unchanged (it's
@@ -657,6 +673,10 @@ var PipelineRunner = class {
 	arrivalCounts = /* @__PURE__ */ new Map();
 	lastGovernorRecomputeAt = Date.now();
 	governorIntervalHandle = null;
+	/** When the scheduler first found itself with zero permits; null when healthy. */
+	inferenceStallSince = null;
+	/** Last stall warning, so a persistent wedge re-warns instead of going quiet. */
+	inferenceStallWarnedAt = null;
 	constructor(config) {
 		this.config = config;
 		this.logger = config.logger;
@@ -1047,7 +1067,12 @@ var PipelineRunner = class {
 	}
 	tick() {
 		this.drainMotionQueues();
-		if (this.semaphore.available <= 0) return;
+		if (this.semaphore.available <= 0) {
+			this.noteInferenceStall();
+			return;
+		}
+		this.inferenceStallSince = null;
+		this.inferenceStallWarnedAt = null;
 		const picked = this.pickNextDetectionFrame();
 		if (!picked) return;
 		const { deviceId, entry, state } = picked;
@@ -1070,11 +1095,18 @@ var PipelineRunner = class {
 		const pickedAt = Date.now();
 		const { frame, handle } = entry;
 		const enqueuedAt = frame._enqueuedAt ?? pickedAt;
-		const release = await this.semaphore.acquire();
+		const rawRelease = await this.semaphore.acquire();
+		let released = false;
+		const release = () => {
+			if (released) return;
+			released = true;
+			rawRelease();
+		};
 		const semAcquiredAt = Date.now();
 		const executorHandle = state.detectionQueue.size <= HANDLE_PASSTHROUGH_MAX_QUEUE_DEPTH && this.semaphore.available > 0 ? handle : void 0;
 		try {
-			const result = await this.config.processFrame(deviceId, frameInput, executorHandle);
+			const result = await this.awaitInferenceBounded(deviceId, frameInput, executorHandle, release);
+			if (result === TIMED_OUT) return;
 			const inferDoneAt = Date.now();
 			const inferenceMs = inferDoneAt - semAcquiredAt;
 			state.inferenceTimes.push(inferenceMs);
@@ -1098,6 +1130,73 @@ var PipelineRunner = class {
 			release();
 		}
 	}
+	/**
+	* Await `processFrame` with a hard bound. On expiry the permit is released
+	* immediately (via the caller's release-once closure) and {@link TIMED_OUT}
+	* is returned; the underlying call is left to settle into the void, since
+	* the executor contract offers no cancellation.
+	*/
+	async awaitInferenceBounded(deviceId, frameInput, executorHandle, release) {
+		const timeoutMs = this.config.inferenceTimeoutMs ?? DEFAULT_INFERENCE_TIMEOUT_MS;
+		let timer = null;
+		const expiry = new Promise((resolve) => {
+			timer = setTimeout(() => resolve(TIMED_OUT), timeoutMs);
+			timer.unref?.();
+		});
+		try {
+			const outcome = await Promise.race([this.config.processFrame(deviceId, frameInput, executorHandle), expiry]);
+			if (outcome === TIMED_OUT) {
+				release();
+				this.logger?.warn("inference timed out — permit released, result discarded", {
+					tags: { deviceId },
+					meta: {
+						timeoutMs,
+						availablePermits: this.semaphore.available
+					}
+				});
+			}
+			return outcome;
+		} finally {
+			if (timer !== null) clearTimeout(timer);
+		}
+	}
+	/**
+	* Called on every tick that finds zero available permits. Warns once the
+	* starvation outlives `inferenceStallWarnMs` WITH queued work — queued work
+	* is the discriminator: a runner with no permits and no backlog is simply
+	* busy, while one with a backlog it cannot touch is wedged.
+	*/
+	noteInferenceStall() {
+		let queuedFrames = 0;
+		for (const state of this.cameras.values()) queuedFrames += state.detectionQueue.size;
+		if (queuedFrames === 0) {
+			this.inferenceStallSince = null;
+			this.inferenceStallWarnedAt = null;
+			return;
+		}
+		const now = Date.now();
+		if (this.inferenceStallSince === null) {
+			this.inferenceStallSince = now;
+			return;
+		}
+		const stalledMs = now - this.inferenceStallSince;
+		if (stalledMs < (this.config.inferenceStallWarnMs ?? DEFAULT_INFERENCE_STALL_WARN_MS)) return;
+		if (this.inferenceStallWarnedAt !== null && now - this.inferenceStallWarnedAt < INFERENCE_STALL_REWARN_MS) return;
+		this.inferenceStallWarnedAt = now;
+		for (const [deviceId, state] of this.cameras) {
+			if (state.detectionQueue.size === 0) continue;
+			this.logger?.warn("no inference permit available while frames are queued", {
+				tags: { deviceId },
+				meta: {
+					stalledMs,
+					queuedFrames: state.detectionQueue.size,
+					droppedFrames: state.detectionQueue.droppedFrames,
+					phase: state.phase,
+					concurrency: this.semaphore.concurrency
+				}
+			});
+		}
+	}
 	async notifyCallbacks(deviceId, frame, result, streamType, handle) {
 		for (const callback of this.resultCallbacks) try {
 			await callback(deviceId, frame, result, streamType, handle);
@@ -2063,10 +2162,14 @@ var NativeCropRegistry = class {
 	* Bind `request` to `handle`; evicts the oldest entry past the cap, releasing
 	* its worker-side RAM lease so a lease never outlives its registry entry.
 	*/
-	register(handle, request) {
+	register(handle, request, deviceId) {
 		const k = this.key(handle);
 		this.entries.delete(k);
-		this.entries.set(k, request);
+		this.entries.set(k, {
+			request,
+			deviceId,
+			registeredAt: Date.now()
+		});
 		while (this.entries.size > this.capacity) {
 			const oldest = this.entries.keys().next().value;
 			if (oldest === void 0) break;
@@ -2075,7 +2178,22 @@ var NativeCropRegistry = class {
 	}
 	/** The requester for `handle`, or `null` if never registered / already evicted. */
 	get(handle) {
-		return this.entries.get(this.key(handle)) ?? null;
+		const entry = this.entries.get(this.key(handle));
+		if (entry === void 0) return null;
+		return {
+			request: entry.request,
+			deviceId: entry.deviceId,
+			ageMs: Date.now() - entry.registeredAt
+		};
+	}
+	/**
+	* The deviceId a handle was registered under, even AFTER its entry was
+	* evicted — kept in a small parallel ring so a `no-registry-entry` miss can
+	* still be attributed to a camera (a miss line without `deviceId` cannot
+	* answer "why is 617 worse than 615?").
+	*/
+	deviceIdFor(handle) {
+		return this.evictedDeviceIds.get(this.key(handle)) ?? this.entries.get(this.key(handle))?.deviceId ?? null;
 	}
 	/**
 	* Release the worker-side RAM native lease for `handle` and drop its entry —
@@ -2087,15 +2205,27 @@ var NativeCropRegistry = class {
 	}
 	/** Drop every entry, releasing each frame's worker-side lease (node/addon shutdown). */
 	clear() {
-		for (const request of this.entries.values()) safeRelease(request);
+		for (const entry of this.entries.values()) safeRelease(entry.request);
 		this.entries.clear();
+		this.evictedDeviceIds.clear();
 	}
-	/** Release + drop one entry by its map key. */
+	/** Release + drop one entry by its map key, remembering its camera. */
 	releaseEntry(key) {
-		const request = this.entries.get(key);
-		if (!request) return;
+		const entry = this.entries.get(key);
+		if (!entry) return;
 		this.entries.delete(key);
-		safeRelease(request);
+		this.rememberEvicted(key, entry.deviceId);
+		safeRelease(entry.request);
+	}
+	/** Bounded memory of evicted handles → deviceId, for miss attribution. */
+	evictedDeviceIds = /* @__PURE__ */ new Map();
+	rememberEvicted(key, deviceId) {
+		this.evictedDeviceIds.set(key, deviceId);
+		while (this.evictedDeviceIds.size > this.capacity) {
+			const oldest = this.evictedDeviceIds.keys().next().value;
+			if (oldest === void 0) break;
+			this.evictedDeviceIds.delete(oldest);
+		}
 	}
 };
 //#endregion
@@ -3301,16 +3431,29 @@ var PipelineRunnerAddon = class extends require_dist.BaseAddon {
 		const isFullFrame = b.x <= .001 && b.y <= .001 && b.w >= .999 && b.h >= .999;
 		const isUnboundedFullFrame = isFullFrame && input.maxWidth === void 0;
 		let nativeResult = null;
+		let missReason = null;
 		if (!isUnboundedFullFrame) {
-			const requester = this.nativeCropRegistry.get(input.handle);
-			if (requester) {
-				const result = await requester(input.bbox, input.maxWidth);
+			const found = this.nativeCropRegistry.get(input.handle);
+			if (found) {
+				const result = await found.request(input.bbox, input.maxWidth);
 				if (result) nativeResult = {
 					bytes: result.bytes,
 					width: result.width,
 					height: result.height
 				};
-			}
+				else missReason = "worker-lease-gone";
+			} else missReason = "no-registry-entry";
+			if (missReason !== null) this.ctx.logger.debug("native crop miss", {
+				tags: { deviceId: found?.deviceId ?? this.nativeCropRegistry.deviceIdFor(input.handle) ?? -1 },
+				meta: {
+					reason: missReason,
+					handle: `${input.handle.shmId}#${input.handle.slot}#${input.handle.seq}`,
+					handleNodeId: input.handle.nodeId,
+					handleAgeMs: found?.ageMs ?? null,
+					registrySize: this.nativeCropRegistry.size,
+					registryCap: DEFAULT_NATIVE_CROP_REGISTRY_CAP
+				}
+			});
 		}
 		const tier = resolveNativeCropSource(isFullFrame, nativeResult !== null);
 		if (tier === "native" && nativeResult) return this.encodeNativeCropResult(nativeResult, tier, input.encodeJpeg);
@@ -3791,7 +3934,7 @@ var PipelineRunnerAddon = class extends require_dist.BaseAddon {
 					onEnded: () => this.handleDetectionDecodeEnded(config.deviceId),
 					onDecodedFrame: (frame, nativeCrop) => {
 						const handle = retainedFrames?.write(config.deviceId, frame) ?? void 0;
-						if (handle && nativeCrop) this.nativeCropRegistry.register(handle, nativeCrop);
+						if (handle && nativeCrop) this.nativeCropRegistry.register(handle, nativeCrop, config.deviceId);
 						this.enqueueSharedDetectionFrame(config.deviceId, frame, handle);
 					}
 				});
@@ -4304,7 +4447,7 @@ var PipelineRunnerAddon = class extends require_dist.BaseAddon {
 				onDecodedFrame: (frame, nativeCrop) => {
 					if (settled) return;
 					const handle = retainedFrames?.write(config.deviceId, frame) ?? void 0;
-					if (handle && nativeCrop) this.nativeCropRegistry.register(handle, nativeCrop);
+					if (handle && nativeCrop) this.nativeCropRegistry.register(handle, nativeCrop, config.deviceId);
 					runner.enqueueOccupancyFrame(deviceId, frame, handle);
 					count++;
 					if (count >= frames) {

package/dist/pipeline-runner/index.mjs

@@ -1,8 +1,8 @@
-import { B as errMsg, G as createEvent, M as pipelineRunnerCapability, S as defineCustomActions, V as BaseAddon, X as nodePin, at as lazy, b as customAction, ct as object, ft as EventCategory, nt as array, rt as boolean, s as DEVICE_BACKEND_TO_FORMAT, st as number, tt as _enum, ut as string } from "../dist-OjOsoSZG.mjs";
+import { B as errMsg, G as createEvent, M as pipelineRunnerCapability, S as defineCustomActions, V as BaseAddon, X as nodePin, at as lazy, b as customAction, ct as object, ft as EventCategory, nt as array, rt as boolean, s as DEVICE_BACKEND_TO_FORMAT, st as number, tt as _enum, ut as string } from "../dist-CsKaXmP8.mjs";
 import { n as profileForStreamId, t as isRemoteRestream } from "../remote-restream-BeHi78PZ.mjs";
 import { t as resolveHubHostname } from "../hub-hostname-cCknRYKj.mjs";
 import { t as isWorkerReply } from "../worker-protocol-D7RzZIla.mjs";
-import { a as getStepDefinition } from "../step-definitions-B9vyUNYR.mjs";
+import { a as getStepDefinition } from "../step-definitions-C8A78dBi.mjs";
 import { fork } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import sharp from "sharp";
@@ -569,6 +569,22 @@ var PipelineTimingSampler = class {
 //#endregion
 //#region src/pipeline-runner/runner.ts
 /**
+* Bound on one `processFrame` call. Chosen well above the slowest legitimate
+* inference seen in production (8 617 ms, GPU contention on the hub) so the
+* timeout only ever fires on a call that is genuinely never coming back.
+*/
+var DEFAULT_INFERENCE_TIMEOUT_MS = 2e4;
+/** Grace period before a permit-starved scheduler with queued work warns. */
+var DEFAULT_INFERENCE_STALL_WARN_MS = 6e4;
+/** Re-warn cadence while a stall persists, so a wedge stays visible. */
+var INFERENCE_STALL_REWARN_MS = 6e4;
+/**
+* Sentinel distinguishing "the bound expired" from a legitimate `null`
+* (`processFrame` returning no result). A unique symbol, so it can never
+* collide with a value the executor produces.
+*/
+var TIMED_OUT = Symbol("inference-timed-out");
+/**
 * Clone a {@link DetectionQueueEntry} for the queue's copy-on-retain
 * boundary: the inner frame's pixel buffer is detached via
 * {@link ownFrame}, the `FrameHandle` is carried through unchanged (it's
@@ -651,6 +667,10 @@ var PipelineRunner = class {
 	arrivalCounts = /* @__PURE__ */ new Map();
 	lastGovernorRecomputeAt = Date.now();
 	governorIntervalHandle = null;
+	/** When the scheduler first found itself with zero permits; null when healthy. */
+	inferenceStallSince = null;
+	/** Last stall warning, so a persistent wedge re-warns instead of going quiet. */
+	inferenceStallWarnedAt = null;
 	constructor(config) {
 		this.config = config;
 		this.logger = config.logger;
@@ -1041,7 +1061,12 @@ var PipelineRunner = class {
 	}
 	tick() {
 		this.drainMotionQueues();
-		if (this.semaphore.available <= 0) return;
+		if (this.semaphore.available <= 0) {
+			this.noteInferenceStall();
+			return;
+		}
+		this.inferenceStallSince = null;
+		this.inferenceStallWarnedAt = null;
 		const picked = this.pickNextDetectionFrame();
 		if (!picked) return;
 		const { deviceId, entry, state } = picked;
@@ -1064,11 +1089,18 @@ var PipelineRunner = class {
 		const pickedAt = Date.now();
 		const { frame, handle } = entry;
 		const enqueuedAt = frame._enqueuedAt ?? pickedAt;
-		const release = await this.semaphore.acquire();
+		const rawRelease = await this.semaphore.acquire();
+		let released = false;
+		const release = () => {
+			if (released) return;
+			released = true;
+			rawRelease();
+		};
 		const semAcquiredAt = Date.now();
 		const executorHandle = state.detectionQueue.size <= HANDLE_PASSTHROUGH_MAX_QUEUE_DEPTH && this.semaphore.available > 0 ? handle : void 0;
 		try {
-			const result = await this.config.processFrame(deviceId, frameInput, executorHandle);
+			const result = await this.awaitInferenceBounded(deviceId, frameInput, executorHandle, release);
+			if (result === TIMED_OUT) return;
 			const inferDoneAt = Date.now();
 			const inferenceMs = inferDoneAt - semAcquiredAt;
 			state.inferenceTimes.push(inferenceMs);
@@ -1092,6 +1124,73 @@ var PipelineRunner = class {
 			release();
 		}
 	}
+	/**
+	* Await `processFrame` with a hard bound. On expiry the permit is released
+	* immediately (via the caller's release-once closure) and {@link TIMED_OUT}
+	* is returned; the underlying call is left to settle into the void, since
+	* the executor contract offers no cancellation.
+	*/
+	async awaitInferenceBounded(deviceId, frameInput, executorHandle, release) {
+		const timeoutMs = this.config.inferenceTimeoutMs ?? DEFAULT_INFERENCE_TIMEOUT_MS;
+		let timer = null;
+		const expiry = new Promise((resolve) => {
+			timer = setTimeout(() => resolve(TIMED_OUT), timeoutMs);
+			timer.unref?.();
+		});
+		try {
+			const outcome = await Promise.race([this.config.processFrame(deviceId, frameInput, executorHandle), expiry]);
+			if (outcome === TIMED_OUT) {
+				release();
+				this.logger?.warn("inference timed out — permit released, result discarded", {
+					tags: { deviceId },
+					meta: {
+						timeoutMs,
+						availablePermits: this.semaphore.available
+					}
+				});
+			}
+			return outcome;
+		} finally {
+			if (timer !== null) clearTimeout(timer);
+		}
+	}
+	/**
+	* Called on every tick that finds zero available permits. Warns once the
+	* starvation outlives `inferenceStallWarnMs` WITH queued work — queued work
+	* is the discriminator: a runner with no permits and no backlog is simply
+	* busy, while one with a backlog it cannot touch is wedged.
+	*/
+	noteInferenceStall() {
+		let queuedFrames = 0;
+		for (const state of this.cameras.values()) queuedFrames += state.detectionQueue.size;
+		if (queuedFrames === 0) {
+			this.inferenceStallSince = null;
+			this.inferenceStallWarnedAt = null;
+			return;
+		}
+		const now = Date.now();
+		if (this.inferenceStallSince === null) {
+			this.inferenceStallSince = now;
+			return;
+		}
+		const stalledMs = now - this.inferenceStallSince;
+		if (stalledMs < (this.config.inferenceStallWarnMs ?? DEFAULT_INFERENCE_STALL_WARN_MS)) return;
+		if (this.inferenceStallWarnedAt !== null && now - this.inferenceStallWarnedAt < INFERENCE_STALL_REWARN_MS) return;
+		this.inferenceStallWarnedAt = now;
+		for (const [deviceId, state] of this.cameras) {
+			if (state.detectionQueue.size === 0) continue;
+			this.logger?.warn("no inference permit available while frames are queued", {
+				tags: { deviceId },
+				meta: {
+					stalledMs,
+					queuedFrames: state.detectionQueue.size,
+					droppedFrames: state.detectionQueue.droppedFrames,
+					phase: state.phase,
+					concurrency: this.semaphore.concurrency
+				}
+			});
+		}
+	}
 	async notifyCallbacks(deviceId, frame, result, streamType, handle) {
 		for (const callback of this.resultCallbacks) try {
 			await callback(deviceId, frame, result, streamType, handle);
@@ -2057,10 +2156,14 @@ var NativeCropRegistry = class {
 	* Bind `request` to `handle`; evicts the oldest entry past the cap, releasing
 	* its worker-side RAM lease so a lease never outlives its registry entry.
 	*/
-	register(handle, request) {
+	register(handle, request, deviceId) {
 		const k = this.key(handle);
 		this.entries.delete(k);
-		this.entries.set(k, request);
+		this.entries.set(k, {
+			request,
+			deviceId,
+			registeredAt: Date.now()
+		});
 		while (this.entries.size > this.capacity) {
 			const oldest = this.entries.keys().next().value;
 			if (oldest === void 0) break;
@@ -2069,7 +2172,22 @@ var NativeCropRegistry = class {
 	}
 	/** The requester for `handle`, or `null` if never registered / already evicted. */
 	get(handle) {
-		return this.entries.get(this.key(handle)) ?? null;
+		const entry = this.entries.get(this.key(handle));
+		if (entry === void 0) return null;
+		return {
+			request: entry.request,
+			deviceId: entry.deviceId,
+			ageMs: Date.now() - entry.registeredAt
+		};
+	}
+	/**
+	* The deviceId a handle was registered under, even AFTER its entry was
+	* evicted — kept in a small parallel ring so a `no-registry-entry` miss can
+	* still be attributed to a camera (a miss line without `deviceId` cannot
+	* answer "why is 617 worse than 615?").
+	*/
+	deviceIdFor(handle) {
+		return this.evictedDeviceIds.get(this.key(handle)) ?? this.entries.get(this.key(handle))?.deviceId ?? null;
 	}
 	/**
 	* Release the worker-side RAM native lease for `handle` and drop its entry —
@@ -2081,15 +2199,27 @@ var NativeCropRegistry = class {
 	}
 	/** Drop every entry, releasing each frame's worker-side lease (node/addon shutdown). */
 	clear() {
-		for (const request of this.entries.values()) safeRelease(request);
+		for (const entry of this.entries.values()) safeRelease(entry.request);
 		this.entries.clear();
+		this.evictedDeviceIds.clear();
 	}
-	/** Release + drop one entry by its map key. */
+	/** Release + drop one entry by its map key, remembering its camera. */
 	releaseEntry(key) {
-		const request = this.entries.get(key);
-		if (!request) return;
+		const entry = this.entries.get(key);
+		if (!entry) return;
 		this.entries.delete(key);
-		safeRelease(request);
+		this.rememberEvicted(key, entry.deviceId);
+		safeRelease(entry.request);
+	}
+	/** Bounded memory of evicted handles → deviceId, for miss attribution. */
+	evictedDeviceIds = /* @__PURE__ */ new Map();
+	rememberEvicted(key, deviceId) {
+		this.evictedDeviceIds.set(key, deviceId);
+		while (this.evictedDeviceIds.size > this.capacity) {
+			const oldest = this.evictedDeviceIds.keys().next().value;
+			if (oldest === void 0) break;
+			this.evictedDeviceIds.delete(oldest);
+		}
 	}
 };
 //#endregion
@@ -3295,16 +3425,29 @@ var PipelineRunnerAddon = class extends BaseAddon {
 		const isFullFrame = b.x <= .001 && b.y <= .001 && b.w >= .999 && b.h >= .999;
 		const isUnboundedFullFrame = isFullFrame && input.maxWidth === void 0;
 		let nativeResult = null;
+		let missReason = null;
 		if (!isUnboundedFullFrame) {
-			const requester = this.nativeCropRegistry.get(input.handle);
-			if (requester) {
-				const result = await requester(input.bbox, input.maxWidth);
+			const found = this.nativeCropRegistry.get(input.handle);
+			if (found) {
+				const result = await found.request(input.bbox, input.maxWidth);
 				if (result) nativeResult = {
 					bytes: result.bytes,
 					width: result.width,
 					height: result.height
 				};
-			}
+				else missReason = "worker-lease-gone";
+			} else missReason = "no-registry-entry";
+			if (missReason !== null) this.ctx.logger.debug("native crop miss", {
+				tags: { deviceId: found?.deviceId ?? this.nativeCropRegistry.deviceIdFor(input.handle) ?? -1 },
+				meta: {
+					reason: missReason,
+					handle: `${input.handle.shmId}#${input.handle.slot}#${input.handle.seq}`,
+					handleNodeId: input.handle.nodeId,
+					handleAgeMs: found?.ageMs ?? null,
+					registrySize: this.nativeCropRegistry.size,
+					registryCap: DEFAULT_NATIVE_CROP_REGISTRY_CAP
+				}
+			});
 		}
 		const tier = resolveNativeCropSource(isFullFrame, nativeResult !== null);
 		if (tier === "native" && nativeResult) return this.encodeNativeCropResult(nativeResult, tier, input.encodeJpeg);
@@ -3785,7 +3928,7 @@ var PipelineRunnerAddon = class extends BaseAddon {
 					onEnded: () => this.handleDetectionDecodeEnded(config.deviceId),
 					onDecodedFrame: (frame, nativeCrop) => {
 						const handle = retainedFrames?.write(config.deviceId, frame) ?? void 0;
-						if (handle && nativeCrop) this.nativeCropRegistry.register(handle, nativeCrop);
+						if (handle && nativeCrop) this.nativeCropRegistry.register(handle, nativeCrop, config.deviceId);
 						this.enqueueSharedDetectionFrame(config.deviceId, frame, handle);
 					}
 				});
@@ -4298,7 +4441,7 @@ var PipelineRunnerAddon = class extends BaseAddon {
 				onDecodedFrame: (frame, nativeCrop) => {
 					if (settled) return;
 					const handle = retainedFrames?.write(config.deviceId, frame) ?? void 0;
-					if (handle && nativeCrop) this.nativeCropRegistry.register(handle, nativeCrop);
+					if (handle && nativeCrop) this.nativeCropRegistry.register(handle, nativeCrop, config.deviceId);
 					runner.enqueueOccupancyFrame(deviceId, frame, handle);
 					count++;
 					if (count >= frames) {