@camstack/addon-post-analysis 1.1.26 → 1.1.27

package/dist/pipeline-analytics/index.mjs

@@ -1,4 +1,4 @@
-import { C as number, S as boolean, T as string, c as nodePin, d as videoclipsCapability, f as zoneAnalyticsCapability, g as EventCategory, h as DeviceType, i as cosineSimilarity, l as pipelineAnalyticsCapability, m as BaseAddon, n as addonWidgetsSourceCapability, o as faceGalleryCapability, p as errMsg, r as audioMetricsCapability, t as EVENT_PAD_MS, u as plateGalleryCapability, w as object, y as hydrateSchema } from "../dist-DytVmDZg.mjs";
+import { C as number, S as boolean, T as string, c as nodePin, d as videoclipsCapability, f as zoneAnalyticsCapability, g as EventCategory, h as DeviceType, i as cosineSimilarity, l as pipelineAnalyticsCapability, m as BaseAddon, n as addonWidgetsSourceCapability, o as faceGalleryCapability, p as errMsg, r as audioMetricsCapability, t as EVENT_PAD_MS, u as plateGalleryCapability, w as object, y as hydrateSchema } from "../dist-BqOBYSWs.mjs";
 import { n as extractCrop, t as resolveFrame } from "../resolve-frame-CT1T1tWy.mjs";
 import { FrameRingReaderCache } from "@camstack/shm-ring";
 import sharp from "sharp";
@@ -1522,6 +1522,7 @@ var FrameProcessor = class {
 		const embeddingByBbox = /* @__PURE__ */ new Map();
 		const firstLevelBboxById = /* @__PURE__ */ new Map();
 		const faceBboxByBbox = /* @__PURE__ */ new Map();
+		const faceAlignedCropByBbox = /* @__PURE__ */ new Map();
 		const plateByBbox = /* @__PURE__ */ new Map();
 		const maskByBbox = /* @__PURE__ */ new Map();
 		const flatDetections = frame.detections.filter((d) => d.kind === "first-level").map((det) => {
@@ -1564,6 +1565,7 @@ var FrameProcessor = class {
 				w: det.bbox.width,
 				h: det.bbox.height
 			});
+			if (det.faceAlignedCrop !== void 0) faceAlignedCropByBbox.set(parentBbox, det.faceAlignedCrop);
 			if (det.embedding !== void 0 && !embeddingByBbox.has(parentBbox)) embeddingByBbox.set(parentBbox, {
 				embedding: det.embedding,
 				...det.embeddingModelId !== void 0 ? { embeddingModelId: det.embeddingModelId } : {}
@@ -1606,6 +1608,7 @@ var FrameProcessor = class {
 			});
 			const emb = embeddingByBbox.get(td.bbox);
 			const faceBbox = faceBboxByBbox.get(td.bbox);
+			const faceAlignedCrop = faceAlignedCropByBbox.get(td.bbox);
 			const plate = plateByBbox.get(td.bbox);
 			return {
 				trackId: td.trackId,
@@ -1620,6 +1623,7 @@ var FrameProcessor = class {
 					...emb.embeddingModelId !== void 0 ? { embeddingModelId: emb.embeddingModelId } : {}
 				} : {},
 				...faceBbox !== void 0 ? { faceBbox } : {},
+				...faceAlignedCrop !== void 0 ? { faceAlignedCrop } : {},
 				...plate !== void 0 ? {
 					plateText: plate.text,
 					plateScore: plate.score,
@@ -5495,6 +5499,14 @@ function updateTrackAggregate(prev, match, opts) {
 //#region src/pipeline-analytics/face-recognizer.ts
 /** At most one "dropping imageless track" log per this interval, per recognizer. */
 var FACE_IMAGELESS_LOG_THROTTLE_MS = 6e4;
+/**
+* arcface model id stamped on a detail-plane face candidate when the gallery is
+* empty (collect-only). The detail-subtree result carries no `embeddingModelId`
+* (the two-plane `DetailResult` schema omits it), so recognition uses the
+* gallery's own model id (all enrolled samples share one) and this constant is
+* only a placeholder for the collect-only case where the id is never compared.
+*/
+var FALLBACK_FACE_MODEL_ID = "arcface";
 var FaceRecognizer = class {
 	deps;
 	gallery = [];
@@ -5522,6 +5534,38 @@ var FaceRecognizer = class {
 			this.deps.logger.warn("FaceRecognizer.refreshGallery failed", { meta: { error: String(err) } });
 		}
 	}
+	/**
+	* Two-plane detail feed: ingest ONE `runDetailSubtree` face result for a
+	* track and run it through the SAME `processFrame` logic (candidate → best
+	* face → gallery match → crop hold). The result is synthesized into a single
+	* `TrackedDetectionOut` candidate so no recognizer logic changes — only the
+	* input source moves from the per-frame plane to this per-track call.
+	*/
+	async ingestFaceDetail(input) {
+		const modelId = this.gallery[0]?.modelId ?? FALLBACK_FACE_MODEL_ID;
+		const candidate = {
+			trackId: input.trackId,
+			className: "face",
+			confidence: input.score,
+			bbox: input.parentBbox,
+			zones: [],
+			state: "moving",
+			embedding: input.embedding,
+			embeddingModelId: modelId,
+			...input.faceBbox !== void 0 ? { faceBbox: input.faceBbox } : {},
+			...input.alignedCropJpeg !== void 0 ? { faceAlignedCrop: input.alignedCropJpeg } : {}
+		};
+		await this.processFrame({
+			deviceId: input.deviceId,
+			timestamp: input.timestamp,
+			frameWidth: input.frameWidth,
+			frameHeight: input.frameHeight,
+			tracked: [candidate],
+			settings: input.settings,
+			cropPadding: input.cropPadding,
+			...input.frameHandle !== void 0 ? { frameHandle: input.frameHandle } : {}
+		});
+	}
 	async processFrame(input) {
 		const { settings } = input;
 		const candidates = input.tracked.filter((t) => Array.isArray(t.embedding) && t.embedding.length > 0 && typeof t.embeddingModelId === "string" && t.confidence >= settings.minFaceConfidence);
@@ -5559,7 +5603,8 @@ var FaceRecognizer = class {
 			if (isNewBest || needsCrop) {
 				const cropBbox = c.faceBbox ?? c.bbox;
 				let crop;
-				if (c.faceBbox !== void 0 && input.frameHandle !== void 0) try {
+				if (c.faceAlignedCrop !== void 0) crop = Buffer.from(c.faceAlignedCrop, "base64");
+				else if (c.faceBbox !== void 0 && input.frameHandle !== void 0) try {
 					crop = await this.deps.captureCrop(input.frameHandle, c.faceBbox, input.frameWidth, input.frameHeight, input.cropPadding) ?? void 0;
 				} catch (err) {
 					this.deps.logger.debug("FaceRecognizer crop capture failed", {
@@ -5750,6 +5795,346 @@ var FaceRecognizer = class {
 	}
 };
 //#endregion
+//#region src/pipeline-analytics/detail-scheduler.ts
+/** Default backoff/period when a step's cadence omits `minIntervalMs`. */
+var DEFAULT_MIN_INTERVAL_MS = 1e3;
+/** Default fire cap for a `once` step when its announce omits `maxPerTrack`. */
+var DEFAULT_ONCE_MAX_PER_TRACK = 3;
+/**
+* Pure per-(track, step) scheduling state machine for detail-subtree
+* dispatch. Given a camera's announced child steps (`DetailStepAnnounce[]`,
+* read off `PipelineInferenceResultPayload.detailSteps`), decides WHEN each
+* step should run for a given track — independent of transport, I/O, or
+* timers. The caller drives it with wall-clock `nowMs` and dispatches the
+* returned `DetailRequest[]`.
+*/
+var DetailScheduler = class {
+	tracks = /* @__PURE__ */ new Map();
+	/** Track appeared with class + announce; returns immediate requests. */
+	onTrackStarted(trackId, className, announce, nowMs) {
+		const steps = /* @__PURE__ */ new Map();
+		const requests = [];
+		for (const stepAnnounce of announce) {
+			if (!stepAnnounce.inputClasses.includes(className)) continue;
+			const state = {
+				announce: stepAnnounce,
+				firedCount: 1,
+				lastFiredAt: nowMs,
+				sticky: false,
+				retryPending: false
+			};
+			steps.set(stepAnnounce.stepId, state);
+			requests.push({
+				trackId,
+				stepId: stepAnnounce.stepId,
+				reason: "new-track"
+			});
+		}
+		this.tracks.set(trackId, steps);
+		return requests;
+	}
+	/** Better candidate crop observed for the track. */
+	onCandidateImproved(trackId, nowMs) {
+		const steps = this.tracks.get(trackId);
+		if (!steps) return [];
+		const requests = [];
+		for (const state of steps.values()) {
+			if (state.announce.cadence.trigger !== "improve") continue;
+			if (!this.canFire(state, nowMs)) continue;
+			this.markFired(state, nowMs);
+			requests.push({
+				trackId,
+				stepId: state.announce.stepId,
+				reason: "improve"
+			});
+		}
+		return requests;
+	}
+	/** Periodic tick (call ~1/s). Also carries pending retries for any trigger kind. */
+	tick(nowMs) {
+		const requests = [];
+		for (const [trackId, steps] of this.tracks) for (const state of steps.values()) {
+			if (state.sticky) continue;
+			if (state.retryPending) {
+				if (!this.intervalElapsed(state, nowMs)) continue;
+				if (!this.underMaxPerTrack(state)) {
+					state.retryPending = false;
+					continue;
+				}
+				this.markFired(state, nowMs);
+				requests.push({
+					trackId,
+					stepId: state.announce.stepId,
+					reason: "retry"
+				});
+				continue;
+			}
+			if (state.announce.cadence.trigger !== "periodic") continue;
+			if (!this.canFire(state, nowMs)) continue;
+			this.markFired(state, nowMs);
+			requests.push({
+				trackId,
+				stepId: state.announce.stepId,
+				reason: "periodic"
+			});
+		}
+		return requests;
+	}
+	/**
+	* Result arrived; confidence drives sticky/retry. null = failed (retry per
+	* policy). `_nowMs` is part of the public signature for symmetry with the
+	* other methods but isn't needed here — retry backoff is anchored to
+	* `lastFiredAt` (set when the step was actually dispatched), not to when
+	* its result came back.
+	*/
+	onResult(trackId, stepId, confidence, _nowMs) {
+		const steps = this.tracks.get(trackId);
+		if (!steps) return;
+		const state = steps.get(stepId);
+		if (!state) return;
+		if (state.sticky) return;
+		const { stickyOnConfidence } = state.announce.cadence;
+		if (confidence !== null && stickyOnConfidence !== void 0 && confidence >= stickyOnConfidence) {
+			state.sticky = true;
+			state.retryPending = false;
+			return;
+		}
+		if (confidence === null) {
+			if (this.underMaxPerTrack(state)) state.retryPending = true;
+			return;
+		}
+		if (state.announce.cadence.trigger === "once" && stickyOnConfidence !== void 0) {
+			if (this.underMaxPerTrack(state)) state.retryPending = true;
+		}
+	}
+	onTrackEnded(trackId) {
+		this.tracks.delete(trackId);
+	}
+	canFire(state, nowMs) {
+		if (state.sticky) return false;
+		if (!this.underMaxPerTrack(state)) return false;
+		return this.intervalElapsed(state, nowMs);
+	}
+	intervalElapsed(state, nowMs) {
+		if (state.lastFiredAt === null) return true;
+		const minIntervalMs = state.announce.cadence.minIntervalMs ?? DEFAULT_MIN_INTERVAL_MS;
+		return nowMs - state.lastFiredAt >= minIntervalMs;
+	}
+	underMaxPerTrack(state) {
+		const maxPerTrack = state.announce.cadence.maxPerTrack ?? (state.announce.cadence.trigger === "once" ? DEFAULT_ONCE_MAX_PER_TRACK : Infinity);
+		return state.firedCount < maxPerTrack;
+	}
+	markFired(state, nowMs) {
+		state.firedCount += 1;
+		state.lastFiredAt = nowMs;
+		state.retryPending = false;
+	}
+};
+//#endregion
+//#region src/pipeline-analytics/detail-dispatcher.ts
+/** Throttle for the per-device "detail call failed" warn — one line / minute. */
+var FAIL_WARN_THROTTLE_MS = 6e4;
+var TrackDetailDispatcher = class {
+	deps;
+	devices = /* @__PURE__ */ new Map();
+	maxInFlight;
+	tickIntervalMs;
+	disposed = false;
+	constructor(deps) {
+		this.deps = deps;
+		this.maxInFlight = deps.maxInFlightPerDevice ?? 2;
+		this.tickIntervalMs = deps.tickIntervalMs ?? 1e3;
+	}
+	/** A track appeared: record its frame, seed its best-confidence, and dispatch
+	*  the scheduler's immediate (new-track) requests. */
+	onTrackStarted(deviceId, trackId, className, announce, frame, nowMs) {
+		if (this.disposed) return;
+		const dev = this.ensureDevice(deviceId);
+		dev.tracks.set(trackId, frame);
+		dev.candidateBest.observe(trackId, frame.confidence, frame.timestamp);
+		const requests = dev.scheduler.onTrackStarted(trackId, className, announce, nowMs);
+		this.enqueue(deviceId, dev, requests);
+		this.ensureTimer(deviceId, dev);
+	}
+	/** A subsequent frame for a live track: refresh its frame + fire
+	*  `improve`-cadence steps when the detector confidence strictly improves.
+	*
+	*  `announce` is the frame's currently-announced detail chain. When a track
+	*  is alive but has NO dispatcher state yet — it existed before `detailSteps`
+	*  first appeared (a mid-track redeploy / config change) — this adopts it as a
+	*  new track so it starts getting scheduled instead of starving for its whole
+	*  life. Idempotent: guarded by the per-track state check, so a track that
+	*  already has state is never reset. */
+	onFrame(deviceId, trackId, announce, frame, nowMs) {
+		if (this.disposed) return;
+		const dev = this.devices.get(deviceId);
+		if (!dev || !dev.tracks.has(trackId)) {
+			if (announce.length > 0) this.onTrackStarted(deviceId, trackId, frame.className, announce, frame, nowMs);
+			return;
+		}
+		dev.tracks.set(trackId, frame);
+		if (!dev.candidateBest.observe(trackId, frame.confidence, frame.timestamp)) return;
+		const requests = dev.scheduler.onCandidateImproved(trackId, nowMs);
+		this.enqueue(deviceId, dev, requests);
+	}
+	/** A track ended (durable TTL expiry): drop its scheduler + frame state. Any
+	*  queued request for it is discarded at dequeue. */
+	onTrackEnded(deviceId, trackId) {
+		const dev = this.devices.get(deviceId);
+		if (!dev) return;
+		dev.scheduler.onTrackEnded(trackId);
+		dev.tracks.delete(trackId);
+		dev.candidateBest.delete(trackId);
+		if (dev.tracks.size === 0) this.clearTimer(dev);
+	}
+	dispose() {
+		this.disposed = true;
+		for (const dev of this.devices.values()) {
+			this.clearTimer(dev);
+			dev.queue.length = 0;
+			dev.tracks.clear();
+			dev.candidateBest.clear();
+		}
+		this.devices.clear();
+	}
+	ensureDevice(deviceId) {
+		let dev = this.devices.get(deviceId);
+		if (!dev) {
+			dev = {
+				scheduler: new DetailScheduler(),
+				tracks: /* @__PURE__ */ new Map(),
+				candidateBest: new BestDetectionTracker(),
+				queue: [],
+				inFlight: 0,
+				timer: null,
+				lastFailWarnAt: 0
+			};
+			this.devices.set(deviceId, dev);
+		}
+		return dev;
+	}
+	ensureTimer(deviceId, dev) {
+		if (dev.timer) return;
+		const timer = setInterval(() => this.tick(deviceId, dev), this.tickIntervalMs);
+		if (typeof timer.unref === "function") timer.unref();
+		dev.timer = timer;
+	}
+	clearTimer(dev) {
+		if (dev.timer) {
+			clearInterval(dev.timer);
+			dev.timer = null;
+		}
+	}
+	tick(deviceId, dev) {
+		if (this.disposed) return;
+		const requests = dev.scheduler.tick(Date.now());
+		this.enqueue(deviceId, dev, requests);
+	}
+	enqueue(deviceId, dev, requests) {
+		if (requests.length === 0) return;
+		for (const r of requests) dev.queue.push(r);
+		this.pump(deviceId, dev);
+	}
+	pump(deviceId, dev) {
+		while (dev.inFlight < this.maxInFlight && dev.queue.length > 0) {
+			const req = dev.queue.shift();
+			if (req === void 0) break;
+			const frame = dev.tracks.get(req.trackId);
+			if (frame === void 0) continue;
+			dev.inFlight += 1;
+			this.dispatch(deviceId, dev, req, frame).finally(() => {
+				dev.inFlight -= 1;
+				this.pump(deviceId, dev);
+			});
+		}
+	}
+	async dispatch(deviceId, dev, req, frame) {
+		const details = await this.runOnce(deviceId, dev, req, frame);
+		let topScore = null;
+		if (details !== null && details.length > 0) {
+			topScore = details.reduce((max, d) => d.score > max ? d.score : max, Number.NEGATIVE_INFINITY);
+			try {
+				await this.deps.routeResults(deviceId, req.trackId, details, frame);
+			} catch (err) {
+				this.deps.logger.warn("detail result routing failed", {
+					tags: { deviceId },
+					meta: {
+						trackId: req.trackId,
+						stepId: req.stepId,
+						error: String(err)
+					}
+				});
+			}
+		}
+		dev.scheduler.onResult(req.trackId, req.stepId, topScore, Date.now());
+	}
+	/**
+	* Run the request once via the frameHandle, and — on a miss (null OR throw)
+	* — retry ONCE with a `cropJpeg` fallback when one can be captured. Returns
+	* the detail list, or `null` when both attempts fail to produce a result.
+	*/
+	async runOnce(deviceId, dev, req, frame) {
+		const parent = {
+			bbox: { ...frame.bbox },
+			className: frame.className
+		};
+		if (frame.frameHandle !== void 0) try {
+			const primary = await this.deps.runDetailSubtree({
+				deviceId,
+				frameHandle: frame.frameHandle,
+				parent,
+				steps: [req.stepId]
+			}, frame.nodeId);
+			if (primary !== null) return primary.details;
+		} catch (err) {
+			this.deps.logger.debug("detail primary call failed — trying crop fallback", {
+				tags: { deviceId },
+				meta: {
+					trackId: req.trackId,
+					stepId: req.stepId,
+					error: String(err)
+				}
+			});
+		}
+		if (this.deps.captureCropBase64 !== void 0) try {
+			const cropJpeg = await this.deps.captureCropBase64(frame);
+			if (cropJpeg !== null) {
+				const retry = await this.deps.runDetailSubtree({
+					deviceId,
+					cropJpeg,
+					parent,
+					steps: [req.stepId]
+				}, frame.nodeId);
+				if (retry !== null) return retry.details;
+			}
+		} catch (err) {
+			this.deps.logger.debug("detail crop-fallback call failed", {
+				tags: { deviceId },
+				meta: {
+					trackId: req.trackId,
+					stepId: req.stepId,
+					error: String(err)
+				}
+			});
+		}
+		this.warnFailThrottled(deviceId, dev, req);
+		return null;
+	}
+	warnFailThrottled(deviceId, dev, req) {
+		const now = Date.now();
+		if (now - dev.lastFailWarnAt < FAIL_WARN_THROTTLE_MS) return;
+		dev.lastFailWarnAt = now;
+		this.deps.logger.warn("runDetailSubtree produced no result (frame + crop both missed)", {
+			tags: { deviceId },
+			meta: {
+				trackId: req.trackId,
+				stepId: req.stepId,
+				reason: req.reason
+			}
+		});
+	}
+};
+//#endregion
 //#region src/pipeline-analytics/store/plate-store.ts
 var PLATES_COLLECTION = "pipeline-analytics:plates";
 var PLATE_COLUMNS = [
@@ -6394,6 +6779,12 @@ function createEventMediaHandler(deps) {
 * surface to turn the refinement pipeline on/off for a camera.
 */
 var TTL_SWEEP_INTERVAL_MS = 5e3;
+/** Padding applied to the parent bbox for the `cropJpeg` retry fallback when a
+*  scheduled detail call's frameHandle lease is already gone. */
+var DETAIL_FALLBACK_CROP_PADDING = .15;
+/** How long the active CLIP model id (from the embedding-encoder) is cached
+*  before re-reading. */
+var CLIP_MODEL_ID_CACHE_TTL_MS = 6e4;
 var SETTINGS_CACHE_TTL_MS = 5e3;
 /** §5 best-frame: a track's `thumbnail` is overwritten only when the current
 *  detection confidence beats the held best by at least this margin (hysteresis
@@ -6426,6 +6817,15 @@ var RETENTION_SWEEP_INTERVAL_MS = 5 * 6e4;
 var AUDIO_EVENT_HEARTBEAT_MS = 5e3;
 var MOTION_EVENT_HEARTBEAT_MS = 5e3;
 /**
+* Decode a base64 little-endian float32 vector (the `DetailResult.embedding`
+* wire encoding produced by `runDetailSubtree`) back into a plain number[].
+*/
+function decodeEmbeddingBase64(base64) {
+	const bytes = Buffer.from(base64, "base64");
+	const view = new Float32Array(bytes.buffer, bytes.byteOffset, Math.floor(bytes.byteLength / 4));
+	return Array.from(view);
+}
+/**
 * Re-home the global analytics sections into the per-device `Analytics`
 * top-tab. Every section defaults to the `Analytics` tab (so the
 * device-manager aggregator groups them) AND is marked
@@ -6475,6 +6875,14 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 	plateStore = null;
 	plateRecognizer = null;
 	objectEmbeddingStore = null;
+	/** Two-plane detail scheduler/dispatcher: per-track on-demand face/clip/
+	*  classifier/plate enrichment via `pipelineRunner.runDetailSubtree`. Replaces
+	*  the per-frame child consumption the executor no longer emits. */
+	detailDispatcher = null;
+	/** Active CLIP image-embedding model id (== the text encoder's), TTL-cached.
+	*  Stamped on object-embedding rows from the detail plane so semantic search's
+	*  same-model gate keeps matching. */
+	clipModelIdCache = null;
 	/** Frame-based event/track media (crop + boxed full-frame) from the
 	*  detection-pipeline DECODED frame — the ONLY image source (never the
 	*  snapshot cap). Null when shm frame access is unavailable. */
@@ -6734,6 +7142,21 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 			store: api.settingsStore,
 			logger: logger.child("ObjectEmbeddingStore")
 		});
+		const runnerApi = api.pipelineRunner;
+		this.detailDispatcher = new TrackDetailDispatcher({
+			logger: logger.child("DetailDispatcher"),
+			runDetailSubtree: async (input, nodeId) => {
+				if (!runnerApi?.runDetailSubtree) return null;
+				if (nodeId !== void 0) return runnerApi.runDetailSubtree.mutate(input, nodePin(nodeId));
+				return runnerApi.runDetailSubtree.mutate(input);
+			},
+			routeResults: (deviceId, trackId, details, frame) => this.routeDetailResults(deviceId, trackId, details, frame),
+			captureCropBase64: async (frame) => {
+				if (frame.frameHandle === void 0 || !this.captureCrop) return null;
+				const buf = await this.captureCrop(frame.frameHandle, { ...frame.bbox }, frame.frameWidth, frame.frameHeight, DETAIL_FALLBACK_CROP_PADDING);
+				return buf ? buf.toString("base64") : null;
+			}
+		});
 		this.bindingCache = new BindingCache({
 			api,
 			logger: logger.child("BindingCache")
@@ -7138,6 +7561,8 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 		}
 		this.zoneAnalytics?.destroy();
 		this.audioMetrics?.destroy();
+		this.detailDispatcher?.dispose();
+		this.detailDispatcher = null;
 		this.processors.clear();
 		this.lastActiveTrackIds.clear();
 		this.dropoutSkipsByKey.clear();
@@ -7162,7 +7587,7 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 	async handleInferenceResult(data) {
 		if (this.shuttingDown) return;
 		const { deviceId, frame } = data;
-		await this.processFrame(deviceId, frame, "pipeline", data.frameHandle);
+		await this.processFrame(deviceId, frame, "pipeline", data.frameHandle, data.detailSteps);
 	}
 	/**
 	* Run one detection frame through the analysis layers for a given
@@ -7172,7 +7597,7 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 	* tracking/zone/event state never crosses between sources. Emits the
 	* SAME canonical events, distinguished only by `source`.
 	*/
-	async processFrame(deviceId, frame, source, frameHandle) {
+	async processFrame(deviceId, frame, source, frameHandle, detailSteps) {
 		if (this.shuttingDown) return;
 		if (!await this.bindingCache.isActive(deviceId)) return;
 		const key = this.procKey(deviceId, source);
@@ -7284,6 +7709,26 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 			} });
 		}
 		this.lastActiveTrackIds.set(key, currentTrackIds);
+		if (this.detailDispatcher && detailSteps && detailSteps.length > 0) {
+			const dispatcher = this.detailDispatcher;
+			const steps = detailSteps;
+			for (const t of result.tracked) {
+				const detailFrame = {
+					bbox: { ...t.bbox },
+					frameWidth: result.frameWidth,
+					frameHeight: result.frameHeight,
+					className: t.className,
+					confidence: t.confidence,
+					timestamp: result.timestamp,
+					...frameHandle !== void 0 ? {
+						frameHandle,
+						nodeId: frameHandle.nodeId
+					} : {}
+				};
+				if (prevIds.has(t.trackId)) dispatcher.onFrame(deviceId, t.trackId, steps, detailFrame, result.timestamp);
+				else dispatcher.onTrackStarted(deviceId, t.trackId, t.className, steps, detailFrame, result.timestamp);
+			}
+		}
 		if (newTrackCount > 0 || lostTrackCount > 0 || result.objectEvents.length > 0) {
 			const byState = {};
 			for (const t of result.tracked) byState[t.state] = (byState[t.state] ?? 0) + 1;
@@ -7495,6 +7940,142 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 		return settings;
 	}
 	/**
+	* Route one track's `runDetailSubtree` results (two-plane detail dispatch)
+	* into the EXISTING per-track consumers, discriminated by payload SHAPE:
+	*  • embedding + alignedCropJpeg → FACE (arcface): the FaceRecognizer's
+	*    candidate/best-face/gallery/keyFrame path (input source cut-over);
+	*  • embedding only → CLIP object embedding → the object-embedding store
+	*    (semantic search);
+	*  • label only → classifier answer / plate OCR text → the track's
+	*    enrichment label the notifier/UI already read.
+	* Best-effort (D8): a per-detail failure is logged and never propagated.
+	*/
+	async routeDetailResults(deviceId, trackId, details, frame) {
+		for (const d of details) try {
+			if (d.className === "face" && d.embedding !== void 0) await this.routeFaceDetail(deviceId, trackId, d, frame);
+			else if (d.embedding !== void 0) await this.routeClipDetail(deviceId, trackId, d, frame.timestamp);
+			else if (d.label !== void 0 && d.label.length > 0) await this.applyTrackEnrichmentLabel(deviceId, trackId, d.label);
+		} catch (err) {
+			this.ctx.logger.warn("detail result route failed", {
+				tags: { deviceId },
+				meta: {
+					trackId,
+					stepId: d.stepId,
+					error: errMsg(err)
+				}
+			});
+		}
+	}
+	/** Face-embedding detail → the FaceRecognizer (same gate + logic as the
+	*  former per-frame face path; only the input source moved). */
+	async routeFaceDetail(deviceId, trackId, detail, frame) {
+		if (!this.faceRecognizer || detail.embedding === void 0) return;
+		if (!await this.resolveGlobalFaceEnabled()) return;
+		const [settings, media] = await Promise.all([this.resolveDeviceFaceSettings(deviceId), this.resolveDeviceMediaSettings(deviceId)]);
+		await this.faceRecognizer.ingestFaceDetail({
+			deviceId,
+			trackId,
+			timestamp: frame.timestamp,
+			frameWidth: frame.frameWidth,
+			frameHeight: frame.frameHeight,
+			score: detail.score,
+			embedding: decodeEmbeddingBase64(detail.embedding),
+			parentBbox: { ...frame.bbox },
+			...detail.bbox !== void 0 ? { faceBbox: { ...detail.bbox } } : {},
+			...detail.alignedCropJpeg !== void 0 ? { alignedCropJpeg: detail.alignedCropJpeg } : {},
+			settings,
+			cropPadding: media.cropPadding,
+			...frame.frameHandle !== void 0 ? { frameHandle: frame.frameHandle } : {}
+		});
+	}
+	/** CLIP object-embedding detail → the object-embedding store (semantic
+	*  search). Stamps the active encoder's model id so the same-model search
+	*  gate keeps matching. */
+	async routeClipDetail(deviceId, trackId, detail, timestamp) {
+		const store = this.objectEmbeddingStore;
+		if (!store || detail.embedding === void 0) return;
+		const modelId = await this.resolveClipModelId();
+		if (modelId === null) {
+			this.ctx.logger.debug("clip detail dropped — no active embedding model id", {
+				tags: { deviceId },
+				meta: {
+					trackId,
+					stepId: detail.stepId
+				}
+			});
+			return;
+		}
+		await store.upsertIfBetter({
+			trackId,
+			deviceId,
+			timestamp,
+			className: detail.className,
+			embedding: decodeEmbeddingBase64(detail.embedding),
+			modelId,
+			confidence: detail.score
+		});
+	}
+	/** Classifier answer / plate OCR text → the track's enrichment label
+	*  (TrackStore + persisted events + importance), mirroring the FaceRecognizer
+	*  label-propagation path. */
+	async applyTrackEnrichmentLabel(deviceId, trackId, label) {
+		try {
+			await this.trackStore?.setLabel(trackId, label);
+		} catch (err) {
+			this.ctx.logger.warn("detail label setLabel failed", {
+				tags: { deviceId },
+				meta: {
+					trackId,
+					error: errMsg(err)
+				}
+			});
+		}
+		try {
+			await this.eventStore?.setLabelForTrack(trackId, label);
+		} catch (err) {
+			this.ctx.logger.warn("detail label setLabelForTrack failed", {
+				tags: { deviceId },
+				meta: {
+					trackId,
+					error: errMsg(err)
+				}
+			});
+		}
+		try {
+			const trackStore = this.trackStore;
+			const eventStore = this.eventStore;
+			if (trackStore && eventStore) await recomputeTrackImportance({
+				trackStore,
+				eventStore
+			}, trackId);
+		} catch (err) {
+			this.ctx.logger.debug("detail label recomputeImportance failed", {
+				tags: { deviceId },
+				meta: {
+					trackId,
+					error: errMsg(err)
+				}
+			});
+		}
+	}
+	/** Active CLIP image-embedding model id (== the text encoder's), TTL-cached.
+	*  Returns null when the embedding-encoder cap is unavailable. */
+	async resolveClipModelId() {
+		const now = Date.now();
+		if (this.clipModelIdCache && now < this.clipModelIdCache.expiresAt) return this.clipModelIdCache.value;
+		let value = null;
+		try {
+			value = (await this.ctx.api.embeddingEncoder.getInfo.query())?.modelId ?? null;
+		} catch (err) {
+			this.ctx.logger.debug("resolveClipModelId: getInfo failed", { meta: { error: errMsg(err) } });
+		}
+		this.clipModelIdCache = {
+			value,
+			expiresAt: now + CLIP_MODEL_ID_CACHE_TTL_MS
+		};
+		return value;
+	}
+	/**
 	* §5 — decide which active tracks need periodic media THIS frame. Pure over
 	* TrackStore.lastSnapshotAt + the per-track best-confidence map:
 	*  • `snapshot` (append) + `lastFrame` (rolling overwrite) fire together on
@@ -7882,6 +8463,7 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 				}
 				this.bestFrameTracker.delete(t.trackId);
 				this.objectEmbeddingBestSelector.delete(t.trackId);
+				this.detailDispatcher?.onTrackEnded(t.deviceId, t.trackId);
 				this.ctx.eventBus.emit({
 					id: `pa-end-${t.trackId}`,
 					timestamp: new Date(t.lastSeen),