@camstack/addon-pipeline 1.1.54 → 1.1.55

package/dist/pipeline-runner/index.mjs

@@ -1,7 +1,8 @@
-import { $ as boolean, D as nodePin, H as createEvent, I as errMsg, K as makeSourceBrokerId, L as BaseAddon, Q as array, V as EventCategory, Z as _enum, _ as customAction, it as object, k as pipelineRunnerCapability, ot as string, rt as number, tt as lazy, y as defineCustomActions } from "../dist-CEcTeu1h.mjs";
-import { n as isRemoteRestream, r as profileForStreamId, t as RemoteSourcePlane } from "../remote-source-plane-CNCqC_XG.mjs";
+import { $ as boolean, D as nodePin, H as createEvent, I as errMsg, K as makeSourceBrokerId, L as BaseAddon, Q as array, V as EventCategory, Z as _enum, _ as customAction, it as object, k as pipelineRunnerCapability, ot as string, rt as number, tt as lazy, y as defineCustomActions } from "../dist-RWGGPwVx.mjs";
+import { n as isRemoteRestream, r as profileForStreamId, t as RemoteSourcePlane } from "../remote-source-plane-DU0aRSPv.mjs";
 import { t as resolveHubHostname } from "../hub-hostname-cCknRYKj.mjs";
-import { t as isWorkerReply } from "../worker-protocol-DGIt_waM.mjs";
+import { t as isWorkerReply } from "../worker-protocol-CyVJTZEO.mjs";
+import { a as getStepDefinition } from "../step-definitions-CP9kVSml.mjs";
 import { DecoderFrameRingSink, FrameRingReaderCache, unlinkSegment } from "@camstack/shm-ring";
 import { fork } from "node:child_process";
 import { fileURLToPath } from "node:url";
@@ -423,6 +424,36 @@ function startPolling(options, source, subscriptionId, resolvedMaxFps, lifecycle
 	};
 }
 //#endregion
+//#region src/pipeline-runner/frame-governor.ts
+var FrameGovernor = class {
+	config;
+	intervals = /* @__PURE__ */ new Map();
+	throttled = 0;
+	constructor(config) {
+		this.config = config;
+	}
+	update(samples) {
+		this.intervals.clear();
+		this.throttled = 0;
+		if (samples.size === 0) return;
+		const shareMsPerSec = this.config.targetLoadPercent / 100 * this.config.maxConcurrentInferences * 1e3 / samples.size;
+		for (const [deviceId, s] of samples) {
+			const ceilingFps = s.configuredFps > 0 ? s.configuredFps : s.decodeFps;
+			const affordableFps = s.avgInferenceMs > 0 ? shareMsPerSec / s.avgInferenceMs : ceilingFps;
+			const targetFps = Math.min(ceilingFps, Math.max(this.config.minThrottledFps, affordableFps));
+			if (targetFps < ceilingFps) this.throttled++;
+			this.intervals.set(deviceId, targetFps > 0 ? 1e3 / targetFps : 0);
+		}
+	}
+	/** Minimum ms between admitted frames; 0 = no gate. */
+	minIntervalMs(deviceId) {
+		return this.intervals.get(deviceId) ?? 0;
+	}
+	throttledCount() {
+		return this.throttled;
+	}
+};
+//#endregion
 //#region src/pipeline-runner/frame-queue.ts
 /**
 * Latest-frame-only buffer. Keeps only the most recent item, dropping all
@@ -604,6 +635,24 @@ var PipelineTimingSampler = class {
 		if (!this.detSamples.has(deviceId)) this.detSamples.set(deviceId, []);
 		this.detSamples.get(deviceId).push(s);
 	}
+	/**
+	* Moving average inference time (ms) per camera over the current
+	* accumulation window — the same `inf` samples the `pipeline stats` log
+	* line aggregates (see {@link report}'s `inf` computation). Consumed by
+	* the {@link FrameGovernor} recompute tick as `CameraLoadSample.avgInferenceMs`.
+	* The window resets on every {@link report} call (every REPORT_INTERVAL_MS),
+	* so a camera with zero completed inferences since the last report is
+	* simply absent from the returned map — callers supply their own default.
+	*/
+	avgInferenceMsByCamera() {
+		const result = /* @__PURE__ */ new Map();
+		for (const [deviceId, samples] of this.detSamples) {
+			if (samples.length === 0) continue;
+			const total = samples.reduce((sum, s) => sum + s.inference, 0);
+			result.set(deviceId, total / samples.length);
+		}
+		return result;
+	}
 	addMotionSample(deviceId, ms, frameAge = -1) {
 		if (!this.motSamples.has(deviceId)) this.motSamples.set(deviceId, []);
 		this.motSamples.get(deviceId).push({
@@ -781,6 +830,8 @@ function ownMotionEntry(entry) {
 */
 var HANDLE_PASSTHROUGH_MAX_QUEUE_DEPTH = 1;
 var DEFAULT_MOTION_COOLDOWN_MS = 3e4;
+var GOVERNOR_RECOMPUTE_INTERVAL_MS = 2e3;
+var DEFAULT_DECODE_FPS = 25;
 function toFrameInput$1(frame) {
 	return {
 		data: frame.data,
@@ -816,10 +867,20 @@ var PipelineRunner = class {
 	detectionStreamHandler = null;
 	logger;
 	timingSampler = new PipelineTimingSampler();
+	governor;
+	lastAdmittedAt = /* @__PURE__ */ new Map();
+	arrivalCounts = /* @__PURE__ */ new Map();
+	lastGovernorRecomputeAt = Date.now();
+	governorIntervalHandle = null;
 	constructor(config) {
 		this.config = config;
 		this.logger = config.logger;
 		this.semaphore = new Semaphore(config.maxConcurrentInferences);
+		this.governor = new FrameGovernor({
+			targetLoadPercent: config.targetLoadPercent,
+			minThrottledFps: config.minThrottledFps,
+			maxConcurrentInferences: config.maxConcurrentInferences
+		});
 	}
 	/**
 	* Hot-reload the four tuning fields without tearing down the runner.
@@ -830,8 +891,15 @@ var PipelineRunner = class {
 	*   (the FrameQueue implementation is latest-only and ignores maxSize
 	*   anyway — see `frame-queue.ts` — so the field is effectively a
 	*   metadata hint for observability).
-	* - `targetLoadPercent` / `minThrottledFps`: stored for future
-	*   throttling logic (not yet consumed in the current runner body).
+	* - `targetLoadPercent` / `minThrottledFps`: stored on `this.config` (read
+	*   by `getLimits()`), but NOT re-fed into the live `FrameGovernor` — the
+	*   governor is built once, at construction, from the config snapshot
+	*   passed to the constructor. A hot patch to either knob changes what
+	*   `getLimits()` reports but does not change live admission pacing until
+	*   the runner is reconstructed. (Rebuilding the governor live is a
+	*   follow-up, not in scope here — `maxConcurrentInferences` has the same
+	*   gap: the semaphore resizes live but the governor's budget calc keeps
+	*   the construction-time value.)
 	*
 	* Only keys present in the patch are overwritten; unspecified keys
 	* retain their current value. Any illegal combination (e.g.
@@ -877,13 +945,16 @@ var PipelineRunner = class {
 			lastArmedSource: null,
 			lastArmedRegions: void 0,
 			occupancyTimer: null,
-			motionInFlight: false
+			motionInFlight: false,
+			lastResultDetections: 0,
+			occupancyArmed: false,
+			emptyBurstStreak: 0
 		};
 		this.cameras.set(deviceId, state);
 		this.timingSampler.setDroppedFramesSource(deviceId, () => detectionQueue.droppedFrames);
 		if (registration.detectionMode === "on-motion") this.defaultRoundRobinKeys.push(deviceId);
 		if (registration.detectionMode === "on-motion" && registration.occupancyRecheckEnabled === true && (registration.occupancyRecheckSec ?? 0) > 0) state.occupancyTimer = setInterval(() => {
-			if (state.phase === "watching") this.config.onOccupancyRecheck?.(deviceId, registration.occupancyRecheckFrames ?? 4);
+			if (state.phase === "watching" && state.occupancyArmed) this.config.onOccupancyRecheck?.(deviceId, registration.occupancyRecheckFrames ?? 4);
 		}, (registration.occupancyRecheckSec ?? 0) * 1e3);
 		if (initialPhase === "active") {
 			this.detectionStreamHandler?.(deviceId, "subscribe");
@@ -912,6 +983,8 @@ var PipelineRunner = class {
 		state.detectionQueue.clear();
 		this.timingSampler.clearDroppedFramesSource(deviceId);
 		this.cameras.delete(deviceId);
+		this.lastAdmittedAt.delete(deviceId);
+		this.arrivalCounts.delete(deviceId);
 		const idx = this.defaultRoundRobinKeys.indexOf(deviceId);
 		if (idx !== -1) {
 			this.defaultRoundRobinKeys.splice(idx, 1);
@@ -929,13 +1002,29 @@ var PipelineRunner = class {
 	enqueueDetectionFrame(deviceId, frame, handle) {
 		const state = this.cameras.get(deviceId);
 		if (!state) return;
+		this.arrivalCounts.set(deviceId, (this.arrivalCounts.get(deviceId) ?? 0) + 1);
 		if (state.phase !== "active") return;
+		const interval = this.governor.minIntervalMs(deviceId);
+		if (interval > 0) {
+			const last = this.lastAdmittedAt.get(deviceId) ?? 0;
+			const now = Date.now();
+			if (now - last < interval) return;
+			this.lastAdmittedAt.set(deviceId, now);
+		}
 		frame._enqueuedAt = Date.now();
 		state.detectionQueue.enqueue({
 			frame,
 			handle
 		});
 	}
+	/**
+	* `handle` is optional (mirrors {@link DetectionQueueEntry.handle}) — the
+	* dial path (`runOccupancyBurst`'s `startFrameHandlePoller`) always has a
+	* real shm handle, but Task 10's analyzer-tap path can feed a frame whose
+	* motion subscription never produced one (e.g. the per-session motion
+	* decode worker). `runInference` already falls back to the pixel path
+	* when the handle is absent.
+	*/
 	enqueueOccupancyFrame(deviceId, frame, handle) {
 		const state = this.cameras.get(deviceId);
 		if (!state) return;
@@ -988,6 +1077,42 @@ var PipelineRunner = class {
 	getPhase(deviceId) {
 		return this.cameras.get(deviceId)?.phase;
 	}
+	/**
+	* Record the detection count from the runner's most recent inference
+	* result for this camera. The addon wrapping the scheduler calls this
+	* from its `onResult` callback — the runner itself stays event-agnostic
+	* (it never inspects `FrameResult` shapes), it only remembers the raw
+	* count that `transitionToWatching` reads to decide whether the
+	* occupancy recheck timer arms for the upcoming `watching` phase.
+	*/
+	noteDetectionResult(deviceId, detectionCount) {
+		const state = this.cameras.get(deviceId);
+		if (!state) return;
+		state.lastResultDetections = detectionCount;
+	}
+	/**
+	* Report the outcome of a completed occupancy recheck burst (see
+	* `RunnerConfig.onOccupancyRecheck`). Called by the addon once it knows
+	* whether any burst frame's inference result had detections.
+	*
+	* - `found: true` — resets the empty-burst streak. The timer stays armed;
+	*   a genuine occupant is a separate `reportMotion` event that reopens the
+	*   session through the existing motion/dispatch path — this method does
+	*   not itself flip the phase.
+	* - `found: false` — increments the streak; after 2 consecutive empty
+	*   bursts the timer disarms (`occupancyArmed = false`) until the next
+	*   active→watching transition re-evaluates from scratch.
+	*/
+	reportOccupancyBurstOutcome(deviceId, found) {
+		const state = this.cameras.get(deviceId);
+		if (!state) return;
+		if (found) {
+			state.emptyBurstStreak = 0;
+			return;
+		}
+		state.emptyBurstStreak++;
+		if (state.emptyBurstStreak >= 2) state.occupancyArmed = false;
+	}
 	onResult(callback) {
 		this.resultCallbacks.push(callback);
 	}
@@ -995,12 +1120,19 @@ var PipelineRunner = class {
 		if (this.intervalHandle !== null) return;
 		this.intervalHandle = setInterval(() => this.tick(), 10);
 		this.timingSampler.start();
+		this.lastGovernorRecomputeAt = Date.now();
+		this.governorIntervalHandle = setInterval(() => this.recomputeGovernor(), GOVERNOR_RECOMPUTE_INTERVAL_MS);
+		this.governorIntervalHandle?.unref?.();
 	}
 	stop() {
 		if (this.intervalHandle !== null) {
 			clearInterval(this.intervalHandle);
 			this.intervalHandle = null;
 		}
+		if (this.governorIntervalHandle !== null) {
+			clearInterval(this.governorIntervalHandle);
+			this.governorIntervalHandle = null;
+		}
 		this.timingSampler.stop();
 		for (const state of this.cameras.values()) {
 			if (state.motionCooldownTimer !== null) {
@@ -1013,6 +1145,31 @@ var PipelineRunner = class {
 			}
 		}
 	}
+	/**
+	* Recompute the {@link FrameGovernor}'s per-camera admission intervals
+	* from fresh sampler + arrival data. Called on the {@link
+	* GOVERNOR_RECOMPUTE_INTERVAL_MS} tick started by `start()`; also exposed
+	* so tests can prime the governor deterministically without waiting on a
+	* timer. `now` defaults to the wall clock but is accepted explicitly so a
+	* caller can pass a fixed instant for reproducible elapsed-time math.
+	*/
+	recomputeGovernor(now = Date.now()) {
+		const elapsedSec = Math.max((now - this.lastGovernorRecomputeAt) / 1e3, .001);
+		const avgInferenceMsByCamera = this.timingSampler.avgInferenceMsByCamera();
+		const samples = /* @__PURE__ */ new Map();
+		for (const [deviceId, state] of this.cameras) {
+			if (state.phase !== "active") continue;
+			const measuredDecodeFps = (this.arrivalCounts.get(deviceId) ?? 0) / elapsedSec;
+			samples.set(deviceId, {
+				avgInferenceMs: avgInferenceMsByCamera.get(deviceId) ?? 0,
+				configuredFps: state.registration.fps,
+				decodeFps: measuredDecodeFps > 0 ? measuredDecodeFps : DEFAULT_DECODE_FPS
+			});
+		}
+		this.governor.update(samples);
+		this.arrivalCounts.clear();
+		this.lastGovernorRecomputeAt = now;
+	}
 	getMetrics() {
 		let totalQueueDepth = 0;
 		let totalInferenceTime = 0;
@@ -1026,7 +1183,7 @@ var PipelineRunner = class {
 		}
 		return {
 			activeCameras: this.cameras.size,
-			throttledCameras: 0,
+			throttledCameras: this.governor.throttledCount(),
 			avgInferenceTimeMs: totalInferenceCount > 0 ? totalInferenceTime / totalInferenceCount : 0,
 			queueDepth: totalQueueDepth
 		};
@@ -1064,6 +1221,7 @@ var PipelineRunner = class {
 	}
 	transitionToActive(deviceId, state, source, regions, cooldownMs) {
 		state.phase = "active";
+		state.lastResultDetections = 0;
 		this.logger?.info("motion gate opened — phase=active", {
 			tags: { deviceId },
 			meta: {
@@ -1082,9 +1240,14 @@ var PipelineRunner = class {
 	transitionToWatching(deviceId, state, cooldownMs) {
 		state.phase = "watching";
 		state.detectionQueue.clear();
+		state.occupancyArmed = state.lastResultDetections > 0;
+		state.emptyBurstStreak = 0;
 		this.logger?.info("motion gate closed — phase=watching", {
 			tags: { deviceId },
-			meta: { lastSource: state.lastArmedSource }
+			meta: {
+				lastSource: state.lastArmedSource,
+				occupancyArmed: state.occupancyArmed
+			}
 		});
 		this.detectionStreamHandler?.(deviceId, "unsubscribe");
 		const source = state.lastArmedSource ?? "analyzer";
@@ -1221,9 +1384,11 @@ var KILL_SIGNALS = {
 };
 /** Adapt a Node {@link ChildProcess} to the coordinator's {@link ForkedChildLike}. */
 function wrapChild(child) {
+	child.on("error", () => void 0);
 	return {
 		send: (msg) => {
-			child.send(msg);
+			if (!child.connected) return;
+			child.send(msg, () => void 0);
 		},
 		on: (ev, cb) => {
 			if (ev === "exit") child.on("exit", () => cb(void 0));
@@ -1542,6 +1707,18 @@ var SessionDecodeSession = class {
 			}
 		});
 	}
+	/**
+	* Prompt-release the worker's RAM native-frame lease for `frameId`. Fire and
+	* forget (no reply): a lease also self-expires on its TTL, so a dropped
+	* release only defers reclaim. No-op once the worker has exited.
+	*/
+	releaseLease(frameId) {
+		if (this.exited) return;
+		this.trySend({
+			kind: "releaseNativeLease",
+			frameId
+		});
+	}
 	/** Teardown: `stop`, `kill()`, arm the SIGKILL fallback unless already exited. */
 	teardown() {
 		this.clearPullTimeout();
@@ -1749,6 +1926,7 @@ function buildFrameImage(session, reply) {
 			return session.requestBuffer(reply.frameId, opts);
 		},
 		nativeCrop: (bbox, maxWidth) => session.requestNativeCrop(reply.frameId, bbox, maxWidth),
+		releaseNativeLease: () => session.releaseLease(reply.frameId),
 		close: () => {
 			closed = true;
 		}
@@ -1890,7 +2068,8 @@ function startSessionDecodePump(deps) {
 				try {
 					const decoded = await toDecodedFrame(frame, format);
 					const image = frame.image;
-					const nativeCrop = image.nativeCrop ? (bbox, maxWidth) => image.nativeCrop(bbox, maxWidth) : void 0;
+					const cropFn = image.nativeCrop;
+					const nativeCrop = cropFn ? Object.assign((bbox, maxWidth) => cropFn(bbox, maxWidth), { release: () => image.releaseNativeLease?.() }) : void 0;
 					deps.onDecodedFrame(decoded, nativeCrop);
 				} catch (err) {
 					deps.logger.debug("session-decode pump: skipped a frame (decode/consume error)", {
@@ -1924,6 +2103,12 @@ function startSessionDecodePump(deps) {
 		iterator.return().catch(() => {});
 	};
 }
+/** Invoke a requester's best-effort `release()`, swallowing any transport error. */
+function safeRelease(request) {
+	try {
+		request.release();
+	} catch {}
+}
 var NativeCropRegistry = class {
 	capacity;
 	entries = /* @__PURE__ */ new Map();
@@ -1938,7 +2123,10 @@ var NativeCropRegistry = class {
 	key(handle) {
 		return `${handle.shmId}#${handle.slot}#${handle.seq}`;
 	}
-	/** Bind `request` to `handle`; evicts the oldest entry past the cap. */
+	/**
+	* 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) {
 		const k = this.key(handle);
 		this.entries.delete(k);
@@ -1946,19 +2134,173 @@ var NativeCropRegistry = class {
 		while (this.entries.size > this.capacity) {
 			const oldest = this.entries.keys().next().value;
 			if (oldest === void 0) break;
-			this.entries.delete(oldest);
+			this.releaseEntry(oldest);
 		}
 	}
 	/** The requester for `handle`, or `null` if never registered / already evicted. */
 	get(handle) {
 		return this.entries.get(this.key(handle)) ?? null;
 	}
-	/** Drop every entry (node/addon shutdown). */
+	/**
+	* Release the worker-side RAM native lease for `handle` and drop its entry —
+	* the caller is done cutting native crops from that frame. Best-effort +
+	* idempotent (an unknown handle is a no-op; the lease also self-expires).
+	*/
+	release(handle) {
+		this.releaseEntry(this.key(handle));
+	}
+	/** Drop every entry, releasing each frame's worker-side lease (node/addon shutdown). */
 	clear() {
+		for (const request of this.entries.values()) safeRelease(request);
 		this.entries.clear();
 	}
+	/** Release + drop one entry by its map key. */
+	releaseEntry(key) {
+		const request = this.entries.get(key);
+		if (!request) return;
+		this.entries.delete(key);
+		safeRelease(request);
+	}
 };
 //#endregion
+//#region src/pipeline-runner/detail-subtree.ts
+/** Relative padding applied to the parent bbox before cutting the crop — more context for the child model. */
+var DETAIL_CROP_PADDING_RATIO = .15;
+/**
+* Pad `bbox` by {@link DETAIL_CROP_PADDING_RATIO} of its own size, then clamp
+* to `[0, frameWidth] x [0, frameHeight]`. Pure — always returns a new rect.
+*/
+function padAndClampFrameBbox(bbox, frameWidth, frameHeight) {
+	const padX = DETAIL_CROP_PADDING_RATIO * bbox.w;
+	const padY = DETAIL_CROP_PADDING_RATIO * bbox.h;
+	const x1 = Math.max(0, bbox.x - padX);
+	const y1 = Math.max(0, bbox.y - padY);
+	const x2 = Math.min(frameWidth, bbox.x + bbox.w + padX);
+	const y2 = Math.min(frameHeight, bbox.y + bbox.h + padY);
+	return {
+		x: x1,
+		y: y1,
+		w: Math.max(0, x2 - x1),
+		h: Math.max(0, y2 - y1)
+	};
+}
+/** Normalize a frame-space pixel rect to `[0,1]` by the given frame dims. */
+function normalizeRect(rect, frameWidth, frameHeight) {
+	return {
+		x: rect.x / frameWidth,
+		y: rect.y / frameHeight,
+		w: rect.w / frameWidth,
+		h: rect.h / frameHeight
+	};
+}
+/** Inverse of {@link normalizeRect} — denormalize a `[0,1]` rect back to frame-space pixels. */
+function denormalizeRect(rect, frameWidth, frameHeight) {
+	return {
+		x: rect.x * frameWidth,
+		y: rect.y * frameHeight,
+		w: rect.w * frameWidth,
+		h: rect.h * frameHeight
+	};
+}
+/**
+* Walk `steps` (the attach config's tree) collecting every ENABLED step
+* whose catalog definition's `inputClasses` includes `parentClassName` —
+* these become the subtree's roots. A matched step's own nested `children`
+* ride along UNCHANGED (transitively included: `face-detection` pulls
+* `face-embedding`, `plate-detection` pulls `plate-ocr`) — recursion stops
+* at a match rather than also searching inside it for further matches.
+* `filter`, when given, keeps only matches whose `addonId` is in the list.
+*/
+function findMatchingDetailSteps(steps, parentClassName, lookupStepDefinition, filter) {
+	const matches = [];
+	const walk = (list) => {
+		for (const step of list) {
+			if (!step.enabled) continue;
+			const definition = lookupStepDefinition(step.addonId);
+			if (definition !== null && definition.inputClasses !== null && definition.inputClasses.includes(parentClassName)) {
+				if (!filter || filter.includes(step.addonId)) matches.push(step);
+				continue;
+			}
+			if (step.children) walk(step.children);
+		}
+	};
+	walk(steps);
+	return matches;
+}
+/** Map a detection's CROP-pixel bbox back to FRAME-space pixels. */
+function mapBboxToFrameSpace(bbox, crop) {
+	const scaleX = crop.frameSpace.w / crop.width;
+	const scaleY = crop.frameSpace.h / crop.height;
+	return {
+		x: crop.frameSpace.x + bbox.x * scaleX,
+		y: crop.frameSpace.y + bbox.y * scaleY,
+		w: bbox.width * scaleX,
+		h: bbox.height * scaleY
+	};
+}
+/** Base64-encode a normalized float32 embedding vector. */
+function encodeEmbeddingBase64(embedding) {
+	return Buffer.from(Float32Array.from(embedding).buffer).toString("base64");
+}
+/** First user-visible label — skips the opaque `embedding:*` marker (see `result-assembler.ts`). */
+function pickLabel(detection) {
+	return detection.labels.find((l) => !l.label.startsWith("embedding:"))?.label;
+}
+function toDetailResult(detection, stepId, crop) {
+	const label = pickLabel(detection);
+	return {
+		stepId,
+		className: detection.macroClass,
+		score: detection.score,
+		bbox: mapBboxToFrameSpace(detection.bbox, crop),
+		...detection.embedding !== void 0 ? { embedding: encodeEmbeddingBase64(detection.embedding) } : {},
+		...label !== void 0 ? { label } : {},
+		...detection.faceAlignedCrop !== void 0 ? { alignedCropJpeg: detection.faceAlignedCrop } : {}
+	};
+}
+async function resolveCrop(deps, input) {
+	if (input.frameHandle) {
+		const normalized = normalizeRect(padAndClampFrameBbox(input.parent.bbox, input.frameHandle.width, input.frameHandle.height), input.frameHandle.width, input.frameHandle.height);
+		const native = await deps.getNativeCrop(input.deviceId, input.frameHandle, normalized);
+		if (native) return native;
+	}
+	if (input.cropJpeg) {
+		const jpeg = Buffer.from(input.cropJpeg, "base64");
+		const sharp = (await import("sharp")).default;
+		const meta = await sharp(jpeg).metadata();
+		const width = meta.width ?? 0;
+		const height = meta.height ?? 0;
+		if (width <= 0 || height <= 0) return null;
+		return {
+			jpeg,
+			width,
+			height,
+			frameSpace: input.parent.bbox
+		};
+	}
+	return null;
+}
+/**
+* Run the DETAIL subtree for a single tracked detection: resolve a crop
+* (native lease → `cropJpeg` fallback), run each matched top-level child
+* step's chain against it, and map every result bbox back to frame space.
+* Returns `null` when the camera isn't attached, no configured child
+* matches `input.parent.className`, or no crop source resolves.
+*/
+async function runDetailSubtree(deps, input) {
+	const steps = deps.resolveChildSteps(input.deviceId, input.parent.className, input.steps);
+	if (!steps || steps.length === 0) return null;
+	const crop = await resolveCrop(deps, input);
+	if (!crop) return null;
+	const details = [];
+	for (const step of steps) {
+		const result = await deps.runPipeline([step], crop.jpeg, input.deviceId);
+		if (!result) continue;
+		for (const detection of result.detections) details.push(toDetailResult(detection, step.addonId, crop));
+	}
+	return { details };
+}
+//#endregion
 //#region src/pipeline-runner/index.ts
 var DEFAULT_CONFIG = {
 	maxQueueDepth: 30,
@@ -1983,6 +2325,23 @@ var DEFAULT_CONFIG = {
 */
 var DETECTION_KEEPWARM_MS = 15e3;
 /**
+* Occupancy-burst safety timeout (both the dial path and the analyzer-tap
+* path — Task 10). Bounds worst-case burst latency when frames stop
+* arriving mid-burst — a dial that never gets a keyframe, or a tap whose
+* motion subscription closes before N frames arrive.
+*/
+var OCCUPANCY_BURST_SAFETY_TIMEOUT_MS = 8e3;
+/**
+* Freshness window for `lastMotionFrameAt` (Task 10 hardening). A non-null
+* `attachment.motionUnsubscribe` only proves a subscription handle exists —
+* NOT that frames are actually flowing (guarded-session-decode can return
+* its teardown synchronously, and a failed `acquireSessionDecodeRestreamFrom`
+* acquire never retries, leaving the handle permanently non-null with zero
+* frames arriving). `runOccupancyBurst` additionally requires a motion frame
+* to have been teed within this window before it will route to the tap path.
+*/
+var MOTION_FRESHNESS_WINDOW_MS = 5e3;
+/**
 * Pure decision helper: returns `true` when a dynamic frame-diff analyzer
 * subscription should be opened for an onboard-motion camera.
 *
@@ -1999,6 +2358,62 @@ function shouldStartOnboardAnalyzer(config) {
 	if (config.motionSources.includes("analyzer")) return false;
 	return true;
 }
+/** Recursively collects the `addonId` of every ENABLED step in the tree. */
+function collectEnabledStepIds(steps, acc) {
+	if (!steps) return;
+	for (const step of steps) {
+		if (!step.enabled) continue;
+		acc.add(step.addonId);
+		collectEnabledStepIds(step.children, acc);
+	}
+}
+/**
+* Looks up a catalog step definition, tolerating an unknown id. A stale
+* config entry (removed/custom addon) must degrade to "not announced"
+* rather than fail the attach — `getStepDefinition` throws on a miss.
+*/
+function tryGetStepDefinition(stepId) {
+	try {
+		return getStepDefinition(stepId);
+	} catch {
+		return null;
+	}
+}
+/**
+* Precomputes the `detailSteps` announce (two-plane design) for a camera's
+* configured step tree: every ENABLED step whose catalog definition is a
+* detail/child step (`inputClasses !== null` — a root step like
+* `object-detection` runs on every frame on the `'frame'` plane and has
+* nothing to announce) is surfaced as `{ stepId, inputClasses, cadence }`
+* so a track-level consumer knows what it can dispatch via
+* `pipelineRunner.runDetailSubtree` and on what cadence, without a
+* separate round-trip to the executor's schema/config caps.
+*
+* Unknown step ids (stale config referencing a removed/custom addon) are
+* skipped rather than thrown — the catalog is the single source of truth
+* for cadence and a stale entry must not fail the attach.
+*
+* Extracted as a pure function so the unit suite can exercise the
+* derivation without instantiating the full addon.
+*/
+function deriveDetailSteps(steps) {
+	const stepIds = /* @__PURE__ */ new Set();
+	collectEnabledStepIds(steps, stepIds);
+	const announces = [];
+	for (const stepId of stepIds) {
+		const def = tryGetStepDefinition(stepId);
+		if (!def || def.inputClasses === null) continue;
+		announces.push({
+			stepId: def.id,
+			inputClasses: def.inputClasses,
+			cadence: def.cadence ?? {
+				trigger: "once",
+				maxPerTrack: 3
+			}
+		});
+	}
+	return announces;
+}
 function toFrameInput(frame) {
 	return {
 		data: frame.data,
@@ -2260,6 +2675,13 @@ var PipelineRunnerAddon = class extends BaseAddon {
 	/** Per-camera single-flight: a camera never runs two occupancy bursts at once. */
 	occupancyBurstInFlight = /* @__PURE__ */ new Set();
 	/**
+	* Devices whose in-flight occupancy burst has seen at least one inference
+	* result with detections>0 (set from the `onResult` handler above, cleared
+	* per-burst in `runOccupancyBurst`). Read at burst cleanup and reported to
+	* `PipelineRunner.reportOccupancyBurstOutcome` — Task 9's arm/disarm signal.
+	*/
+	occupancyBurstFound = /* @__PURE__ */ new Set();
+	/**
 	* GLOBAL occupancy admission queue. Each occupancy burst SUBSCRIBES a detection
 	* stream (rgb) which, during the `watching` phase, has no existing consumer and
 	* therefore makes the broker DIAL a fresh decoder. Without a global cap, N
@@ -2276,6 +2698,23 @@ var PipelineRunnerAddon = class extends BaseAddon {
 	occupancyActiveCount = 0;
 	/** Max concurrent occupancy bursts (decoder dials) across all cameras. */
 	occupancyMaxConcurrent = 3;
+	/**
+	* TAP-based occupancy bursts in flight, keyed by deviceId (Task 10). See
+	* {@link OccupancyTapState}. A device has an entry here XOR is dialing via
+	* `startFrameHandlePoller` in `runOccupancyBurst` — never both; the choice
+	* is made once at burst start based on `attachment.motionUnsubscribe`.
+	*/
+	occupancyTaps = /* @__PURE__ */ new Map();
+	/**
+	* Timestamp (`Date.now()`) of the last motion frame teed for each device
+	* — set in `runMotionAnalysis` at the same call site as
+	* `teeOccupancyTapFrame` (Task 10 hardening). This is the TRUTHFUL "is
+	* the analyzer subscription actually delivering frames" signal;
+	* `attachment.motionUnsubscribe !== null` alone only proves a
+	* subscription handle was assigned, not that it's live. See
+	* {@link MOTION_FRESHNESS_WINDOW_MS}.
+	*/
+	lastMotionFrameAt = /* @__PURE__ */ new Map();
 	constructor() {
 		super({ ...DEFAULT_CONFIG });
 	}
@@ -2312,6 +2751,9 @@ var PipelineRunnerAddon = class extends BaseAddon {
 		});
 		this.runner.onResult(async (deviceId, frame, result, _streamType, handle) => {
 			this.emitInferenceResult(deviceId, frame, result, handle);
+			const detectionCount = result.detections?.length ?? 0;
+			this.runner?.noteDetectionResult(deviceId, detectionCount);
+			if (detectionCount > 0 && this.occupancyBurstInFlight.has(deviceId)) this.occupancyBurstFound.add(deviceId);
 		});
 		this.runner.start();
 		this.ctx.logger.info("Pipeline runner started", {
@@ -2377,6 +2819,7 @@ var PipelineRunnerAddon = class extends BaseAddon {
 			attachment.detectionUnsubscribe?.();
 		}
 		this.attached.clear();
+		this.lastMotionFrameAt.clear();
 	}
 	async cacheBenchFrame(input) {
 		const sharp = (await import("sharp")).default;
@@ -2722,7 +3165,8 @@ var PipelineRunnerAddon = class extends BaseAddon {
 			config,
 			motionUnsubscribe: null,
 			detectionUnsubscribe: null,
-			detectionKeepWarmTimer: null
+			detectionKeepWarmTimer: null,
+			detailSteps: deriveDetailSteps(config.steps)
 		};
 		this.attached.set(config.deviceId, attachment);
 		runner.registerCamera(config.deviceId, {
@@ -2775,6 +3219,78 @@ var PipelineRunnerAddon = class extends BaseAddon {
 			height: result.height
 		} : null;
 	}
+	/**
+	* Two-plane design: run the DETAIL subtree (crop children) for a single
+	* tracked detection. Delegates the algorithm to the deps-injected pure
+	* function in {@link runDetailSubtreeImpl} — this method only wires the
+	* real deps: the attach config's step tree (+ the catalog, for the
+	* `inputClasses` match), the SAME internal native-crop lease path
+	* `getNativeCrop` uses above (no `ctx.api` round-trip — we're already in
+	* the frame's owning process), and the node-local `pipelineExecutor`.
+	*/
+	async runDetailSubtree(input) {
+		return runDetailSubtree({
+			resolveChildSteps: (deviceId, parentClassName, filter) => this.resolveDetailChildSteps(deviceId, parentClassName, filter),
+			getNativeCrop: (deviceId, handle, paddedBbox) => this.getNativeCropForDetail(deviceId, handle, paddedBbox),
+			runPipeline: (steps, imageJpeg, deviceId) => this.runDetailPipeline(steps, imageJpeg, deviceId)
+		}, input);
+	}
+	/**
+	* Real `resolveChildSteps` dep: `null` when the camera isn't attached
+	* (matches the cap doc — "camera not attached" is a distinct case from
+	* "attached but no matching child steps", which returns an empty array
+	* and short-circuits inside {@link runDetailSubtreeImpl} the same way).
+	*/
+	resolveDetailChildSteps(deviceId, parentClassName, filter) {
+		const attachment = this.attached.get(deviceId);
+		if (!attachment) return null;
+		const steps = attachment.config.steps;
+		if (!steps) return [];
+		return findMatchingDetailSteps(steps, parentClassName, tryGetStepDefinition, filter);
+	}
+	/**
+	* Real `getNativeCrop` dep: reuses the node-local {@link nativeCropRegistry}
+	* lease (same path the `getNativeCrop` cap method above uses), encodes the
+	* raw RGB crop to JPEG, and denormalizes `paddedBbox` back to frame-space
+	* pixels for the `frameSpace` the caller maps result bboxes against.
+	*/
+	async getNativeCropForDetail(_deviceId, handle, paddedBbox) {
+		const native = await this.getNativeCrop({
+			handle,
+			bbox: paddedBbox
+		});
+		if (!native) return null;
+		const sharp = (await import("sharp")).default;
+		return {
+			jpeg: await sharp(Buffer.from(native.bytes), { raw: {
+				width: native.width,
+				height: native.height,
+				channels: 3
+			} }).jpeg({ quality: 90 }).toBuffer(),
+			width: native.width,
+			height: native.height,
+			frameSpace: denormalizeRect(paddedBbox, handle.width, handle.height)
+		};
+	}
+	/** Real `runPipeline` dep: node-local `pipelineExecutor.runPipeline` on the `'full'` plane. */
+	async runDetailPipeline(steps, imageJpeg, deviceId) {
+		const api = this.ctxIfReady?.api;
+		if (!api) return null;
+		try {
+			return await api.pipelineExecutor.runPipeline.mutate({
+				steps: [...steps],
+				image: new Uint8Array(imageJpeg),
+				deviceId,
+				plane: "full"
+			});
+		} catch (err) {
+			this.ctxIfReady?.logger.warn("runDetailSubtree: runPipeline failed", {
+				tags: { deviceId },
+				meta: { error: errMsg(err) }
+			});
+			return null;
+		}
+	}
 	detachInternal(deviceId) {
 		const attachment = this.attached.get(deviceId);
 		if (!attachment) return;
@@ -2785,6 +3301,7 @@ var PipelineRunnerAddon = class extends BaseAddon {
 		}
 		attachment.motionUnsubscribe?.();
 		attachment.detectionUnsubscribe?.();
+		this.lastMotionFrameAt.delete(deviceId);
 		const remotePlane = this.remotePlanes.get(deviceId);
 		if (remotePlane) {
 			this.remotePlanes.delete(deviceId);
@@ -3317,7 +3834,8 @@ var PipelineRunnerAddon = class extends BaseAddon {
 			return await api.pipelineExecutor.runPipeline.mutate({
 				steps: [...steps],
 				...useHandle ? { frameHandle: handle } : { frame },
-				deviceId
+				deviceId,
+				plane: "frame"
 			});
 		} catch (err) {
 			const msg = errMsg(err);
@@ -3329,6 +3847,8 @@ var PipelineRunnerAddon = class extends BaseAddon {
 		const ctx = this.ctx;
 		const runner = this.runner;
 		if (!ctx || !runner) return;
+		this.lastMotionFrameAt.set(deviceId, Date.now());
+		this.teeOccupancyTapFrame(deviceId, frame, handle);
 		const log = this.ctx.logger.withTags({ deviceId });
 		const motionStart = Date.now();
 		try {
@@ -3443,11 +3963,98 @@ var PipelineRunnerAddon = class extends BaseAddon {
 			});
 		}
 	}
+	/**
+	* Shared burst-completion path (Task 9 report + Task 10 dial/tap
+	* consolidation): clears the in-flight flag, reads the `found` flag the
+	* `onResult` handler set while the burst was live, reports it to the
+	* runner's arm/disarm state machine, and logs. Both the dial path
+	* (`runOccupancyBurst`'s `cleanup`) and the tap path
+	* (`finishOccupancyTap`) fold into this single implementation so the
+	* found/report semantics can't drift between the two admission
+	* mechanisms.
+	*/
+	finishOccupancyBurst(deviceId, log, collected) {
+		this.occupancyBurstInFlight.delete(deviceId);
+		const found = this.occupancyBurstFound.has(deviceId);
+		this.occupancyBurstFound.delete(deviceId);
+		this.runner?.reportOccupancyBurstOutcome(deviceId, found);
+		log.debug("occupancy re-check: burst complete", { meta: {
+			collected,
+			found
+		} });
+	}
+	/**
+	* Task 10: arm a TAP-based occupancy burst for a device whose analyzer
+	* motion subscription is already flowing (`attachment.motionUnsubscribe
+	* !== null` — see `runOccupancyBurst`). Frames feed in via
+	* `teeOccupancyTapFrame`, called from `runMotionAnalysis` on every
+	* arriving substream frame; NO new main-stream poller/decode session is
+	* started. A safety timer (mirrors the dial path's) completes the burst
+	* even if the motion subscription stops producing frames mid-burst.
+	*
+	* Returns a promise that resolves once the tap settles (budget drained or
+	* safety timeout) — `runOccupancyBurst` awaits it so the global
+	* `occupancyActiveCount` slot stays held for the tap's full duration, the
+	* same as the dial path.
+	*/
+	/**
+	* Returns a promise that resolves with the tap's final `collected` count
+	* once it settles (budget drained or safety timeout). The caller
+	* (`runOccupancyBurst`) decides what to do with that count — report the
+	* outcome via `finishOccupancyBurst` when frames were actually collected,
+	* or fall back to a dial burst when the tap collected zero (Task 10
+	* hardening #2). Resolving with the count rather than reporting from
+	* inside the tap itself is what makes that fallback possible without
+	* double-reporting.
+	*/
+	startOccupancyTap(deviceId, frames, log) {
+		this.occupancyBurstInFlight.add(deviceId);
+		this.occupancyBurstFound.delete(deviceId);
+		log.debug("occupancy re-check: tapping live analyzer motion frames (no dial)", { meta: { frames } });
+		return new Promise((resolve) => {
+			const safetyTimer = setTimeout(() => {
+				const collected = this.occupancyTaps.get(deviceId)?.collected ?? 0;
+				log.debug("occupancy re-check: tap safety timeout reached", { meta: { collected } });
+				this.finishOccupancyTap(deviceId);
+			}, OCCUPANCY_BURST_SAFETY_TIMEOUT_MS);
+			this.occupancyTaps.set(deviceId, {
+				remaining: frames,
+				collected: 0,
+				safetyTimer,
+				resolve
+			});
+		});
+	}
+	/** Idempotent: a no-op once the tap has already settled (timer fired, or the budget already drained). */
+	finishOccupancyTap(deviceId) {
+		const tap = this.occupancyTaps.get(deviceId);
+		if (!tap) return;
+		clearTimeout(tap.safetyTimer);
+		this.occupancyTaps.delete(deviceId);
+		tap.resolve(tap.collected);
+	}
+	/**
+	* Tee an arriving analyzer motion frame into occupancy-burst detection
+	* admission (Task 10). Called from `runMotionAnalysis` on EVERY
+	* substream frame; a no-op unless `startOccupancyTap` armed a budget for
+	* this device. The frame always feeds `enqueueOccupancyFrame` — the
+	* handle may be `undefined` (e.g. the Epic-C per-session motion decode
+	* worker never produces a shm handle) and `runInference` already falls
+	* back to the pixel path in that case, so every arriving frame counts
+	* toward the budget regardless of whether it carried a zero-copy handle.
+	*/
+	teeOccupancyTapFrame(deviceId, frame, handle) {
+		const tap = this.occupancyTaps.get(deviceId);
+		if (!tap) return;
+		this.runner?.enqueueOccupancyFrame(deviceId, frame, handle);
+		tap.collected++;
+		tap.remaining--;
+		if (tap.remaining <= 0) this.finishOccupancyTap(deviceId);
+	}
 	async runOccupancyBurst(deviceId, frames) {
 		if (this.occupancyBurstInFlight.has(deviceId)) return;
 		const attachment = this.attached.get(deviceId);
 		if (!attachment) return;
-		const config = attachment.config;
 		const runner = this.runner;
 		if (!runner) return;
 		const log = this.ctx.logger.withTags({ deviceId });
@@ -3456,8 +4063,40 @@ var PipelineRunnerAddon = class extends BaseAddon {
 			log.debug("runOccupancyBurst: ctx.api not available");
 			return;
 		}
-		this.occupancyBurstInFlight.add(deviceId);
-		log.debug("occupancy re-check: starting burst", { meta: { frames } });
+		const lastFrameAt = this.lastMotionFrameAt.get(deviceId);
+		const motionFresh = lastFrameAt !== void 0 && Date.now() - lastFrameAt < MOTION_FRESHNESS_WINDOW_MS;
+		if (attachment.motionUnsubscribe !== null && motionFresh) {
+			const collected = await this.startOccupancyTap(deviceId, frames, log);
+			if (collected > 0) {
+				this.finishOccupancyBurst(deviceId, log, collected);
+				return;
+			}
+			log.debug("occupancy re-check: tap collected 0 frames, falling back to dial", { meta: { frames } });
+			await this.runOccupancyDial(deviceId, frames, attachment, runner, api, log, true);
+			return;
+		}
+		await this.runOccupancyDial(deviceId, frames, attachment, runner, api, log, false);
+	}
+	/**
+	* Dial-path occupancy burst: subscribes a fresh main-stream decode session
+	* via `startFrameHandlePoller` and collects `frames` handles (or times out
+	* at {@link OCCUPANCY_BURST_SAFETY_TIMEOUT_MS}). Called either directly
+	* from `runOccupancyBurst` (no live/fresh motion tap available,
+	* `alreadyInFlight: false`) or as the Task 10 hardening #2 fallback after
+	* a zero-collected tap (`alreadyInFlight: true` — the tap already claimed
+	* the `occupancyBurstInFlight`/`occupancyBurstFound` slot, so this must
+	* NOT re-add it).
+	*/
+	async runOccupancyDial(deviceId, frames, attachment, runner, api, log, alreadyInFlight) {
+		const config = attachment.config;
+		if (!alreadyInFlight) {
+			this.occupancyBurstInFlight.add(deviceId);
+			this.occupancyBurstFound.delete(deviceId);
+		}
+		log.debug("occupancy re-check: starting burst", { meta: {
+			frames,
+			fallback: alreadyInFlight
+		} });
 		let count = 0;
 		let unsubscribe = null;
 		let unsubbed = false;
@@ -3472,13 +4111,12 @@ var PipelineRunnerAddon = class extends BaseAddon {
 			if (settled) return;
 			settled = true;
 			doUnsub();
-			this.occupancyBurstInFlight.delete(deviceId);
-			log.debug("occupancy re-check: burst complete", { meta: { collected: count } });
+			this.finishOccupancyBurst(deviceId, log, count);
 		};
 		const safetyTimer = setTimeout(() => {
 			log.debug("occupancy re-check: safety timeout reached", { meta: { collected: count } });
 			cleanup();
-		}, 8e3);
+		}, OCCUPANCY_BURST_SAFETY_TIMEOUT_MS);
 		try {
 			unsubscribe = await startFrameHandlePoller({
 				api,
@@ -3502,6 +4140,7 @@ var PipelineRunnerAddon = class extends BaseAddon {
 		} catch (err) {
 			clearTimeout(safetyTimer);
 			this.occupancyBurstInFlight.delete(deviceId);
+			this.occupancyBurstFound.delete(deviceId);
 			log.debug("occupancy re-check: poller start failed", { meta: { error: errMsg(err) } });
 			return;
 		}
@@ -3513,12 +4152,14 @@ var PipelineRunnerAddon = class extends BaseAddon {
 	emitInferenceResult(deviceId, frame, result, handle) {
 		if (!this.ctx?.eventBus) return;
 		const capturedAt = frame.capturedAt;
+		const detailSteps = this.attached.get(deviceId)?.detailSteps;
 		const payload = {
 			deviceId,
 			frame: result,
 			nodeId: this.nodeId,
 			frameHandle: handle,
-			...typeof capturedAt === "number" && capturedAt > 0 ? { capturedAt } : {}
+			...typeof capturedAt === "number" && capturedAt > 0 ? { capturedAt } : {},
+			...detailSteps && detailSteps.length > 0 ? { detailSteps } : {}
 		};
 		this.ctx.eventBus.emit(createEvent(EventCategory.PipelineInferenceResult, {
 			type: "device",
@@ -3675,4 +4316,4 @@ var PipelineRunnerAddon = class extends BaseAddon {
 	}
 };
 //#endregion
-export { DEFAULT_CONFIG, FrameQueue, PipelineRunner, PipelineTimingSampler, Semaphore, acquireSessionDecodeRestreamFrom, pipelineRunnerBenchActions as customActions, PipelineRunnerAddon as default, resolveMotionFrameSource, resolveSessionDecodeHostname, resolveSessionDecodeOwnerNodeId, rgbFrameToGrayFrame, shouldStartOnboardAnalyzer };
+export { DEFAULT_CONFIG, FrameQueue, PipelineRunner, PipelineTimingSampler, Semaphore, acquireSessionDecodeRestreamFrom, pipelineRunnerBenchActions as customActions, PipelineRunnerAddon as default, deriveDetailSteps, resolveMotionFrameSource, resolveSessionDecodeHostname, resolveSessionDecodeOwnerNodeId, rgbFrameToGrayFrame, shouldStartOnboardAnalyzer };