@camstack/addon-post-analysis 1.1.25 → 1.1.27

package/dist/pipeline-analytics/index.mjs

@@ -1,4 +1,4 @@
-import { C as object, S as number, c as pipelineAnalyticsCapability, d as zoneAnalyticsCapability, f as errMsg, h as EventCategory, i as cosineSimilarity, l as plateGalleryCapability, m as DeviceType, n as addonWidgetsSourceCapability, o as faceGalleryCapability, p as BaseAddon, r as audioMetricsCapability, t as EVENT_PAD_MS, u as videoclipsCapability, v as hydrateSchema, w as string, x as boolean } from "../dist-Csk_yJr_.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";
@@ -119,6 +119,138 @@ function clusterByEmbedding(items, threshold = .5) {
 	})).toSorted((a, b) => b.size - a.size || b.cohesion - a.cohesion);
 }
 //#endregion
+//#region src/pipeline-analytics/pipeline/key-event-scoring.ts
+/**
+* key-event-scoring — the SINGLE deterministic "importance" scorer for a
+* completed track. A value in [0,1] the viewer sorts events by (events page)
+* and a future reels feature pulls highlights from.
+*
+* PURE + DETERMINISTIC: no Date.now / no random. Time enters ONLY as the
+* precomputed `durationMs` (the caller already knows a track's dwell). Given
+* the same `ScoringInput`, `computeImportance` always returns the same
+* `{ importance, reason }`.
+*
+* The score is a weighted sum of seven independent, individually-saturated
+* signals. Every weight and knee is a NAMED EXPORT so the formula is auditable
+* and the tests can assert exact wiring. The weights sum to exactly 1.0, so an
+* all-signals-maxed track scores exactly 1.0 (the clamp is then a no-op) and an
+* all-zero track scores 0.
+*/
+var WEIGHT_CONFIDENCE = .3;
+var WEIGHT_CLASS = .2;
+var WEIGHT_DWELL = .2;
+var WEIGHT_PROXIMITY = .12;
+var WEIGHT_TRAVEL = .08;
+var WEIGHT_ZONE = .05;
+var WEIGHT_IDENTITY = .05;
+/** Dwell (ms) that saturates the dwell term. */
+var DWELL_FULL_MS = 6e4;
+/** Peak bbox area (as a fraction of frame area) that saturates the size term. */
+var SIZE_FULL = .15;
+var CLASS_RANK_VEHICLE = .8;
+var CLASS_RANK_ANIMAL = .5;
+var CLASS_RANK_DEFAULT = .25;
+var PERSON_CLASSES = new Set(["person", "face"]);
+var VEHICLE_CLASSES = new Set([
+	"vehicle",
+	"car",
+	"truck",
+	"bus"
+]);
+var ANIMAL_CLASSES = new Set([
+	"animal",
+	"dog",
+	"cat"
+]);
+/** Clamp to [0,1]. */
+function clamp01(x) {
+	if (Number.isNaN(x)) return 0;
+	if (x < 0) return 0;
+	if (x > 1) return 1;
+	return x;
+}
+/** Rank a class name into [0,1] by how event-worthy it is. Case-insensitive. */
+function classRank(className) {
+	const c = className.toLowerCase();
+	if (PERSON_CLASSES.has(c)) return 1;
+	if (VEHICLE_CLASSES.has(c)) return CLASS_RANK_VEHICLE;
+	if (ANIMAL_CLASSES.has(c)) return CLASS_RANK_ANIMAL;
+	return CLASS_RANK_DEFAULT;
+}
+/**
+* Compute a deterministic importance score for a completed track.
+*
+* `reason` is the tag of the single largest weighted term. Ties resolve to the
+* first term in a fixed, weight-descending order (confidence → class → dwell →
+* proximity → travel → zone → identity), so the output stays deterministic.
+*/
+function computeImportance(input) {
+	const terms = [
+		{
+			reason: "confidence",
+			value: WEIGHT_CONFIDENCE * clamp01(input.peakConfidence)
+		},
+		{
+			reason: "class",
+			value: WEIGHT_CLASS * classRank(input.className)
+		},
+		{
+			reason: "dwell",
+			value: WEIGHT_DWELL * clamp01(input.durationMs / DWELL_FULL_MS)
+		},
+		{
+			reason: "proximity",
+			value: WEIGHT_PROXIMITY * clamp01(input.peakBboxAreaFrac / SIZE_FULL)
+		},
+		{
+			reason: "travel",
+			value: WEIGHT_TRAVEL * clamp01(input.totalDistance / 2)
+		},
+		{
+			reason: "zone",
+			value: WEIGHT_ZONE * (input.zonesVisited.length > 0 ? 1 : 0)
+		},
+		{
+			reason: "identity",
+			value: WEIGHT_IDENTITY * (input.label ? 1 : 0)
+		}
+	];
+	let sum = 0;
+	let best = terms[0];
+	for (const term of terms) {
+		sum += term.value;
+		if (term.value > best.value) best = term;
+	}
+	return {
+		importance: clamp01(sum),
+		reason: best.reason
+	};
+}
+//#endregion
+//#region src/pipeline-analytics/pipeline/key-event-recompute.ts
+/**
+* Recompute + persist a persisted track's importance from its current fields
+* (including any newly-assigned label) and re-stamp its object events. No-op
+* when the track is not (yet) persisted.
+*/
+async function recomputeTrackImportance(deps, trackId) {
+	const track = await deps.trackStore.getPersistedByTrackId(trackId);
+	if (track === null) return;
+	const peak = await deps.eventStore.peakForTrack(trackId);
+	const { importance, reason } = computeImportance({
+		peakConfidence: peak.peakConfidence,
+		className: track.className,
+		durationMs: track.lastSeen - track.firstSeen,
+		peakBboxAreaFrac: peak.peakBboxAreaFrac,
+		totalDistance: track.totalDistance,
+		zonesVisited: track.zonesVisited,
+		...track.label !== void 0 ? { label: track.label } : {}
+	});
+	const bestEventId = track.bestEventId ?? peak.bestEventId;
+	await deps.trackStore.setImportance(trackId, importance, reason, bestEventId);
+	await deps.eventStore.setImportanceForTrack(trackId, importance);
+}
+//#endregion
 //#region src/pipeline-analytics/face-gallery-provider.ts
 /** Embedding model id used when enrolling face crops as identity samples. */
 var MODEL_ID = "arcface-r100";
@@ -239,7 +371,9 @@ var FaceGalleryProvider = class {
 				...face.recognizedIdentityId != null ? { recognizedIdentityId: face.recognizedIdentityId } : {},
 				...identityName !== void 0 ? { identityName } : {},
 				assigned: face.assigned,
-				...base64 !== void 0 ? { base64 } : {}
+				...base64 !== void 0 ? { base64 } : {},
+				...face.faceBbox !== void 0 ? { faceBbox: face.faceBbox } : {},
+				...face.keyFrameMediaKey !== void 0 ? { keyFrameMediaKey: face.keyFrameMediaKey } : {}
 			});
 		}
 		return result;
@@ -267,7 +401,9 @@ var FaceGalleryProvider = class {
 			...face.recognizedIdentityId != null ? { recognizedIdentityId: face.recognizedIdentityId } : {},
 			...identityName !== void 0 ? { identityName } : {},
 			assigned: face.assigned,
-			...base64 !== void 0 ? { base64 } : {}
+			...base64 !== void 0 ? { base64 } : {},
+			...face.faceBbox !== void 0 ? { faceBbox: face.faceBbox } : {},
+			...face.keyFrameMediaKey !== void 0 ? { keyFrameMediaKey: face.keyFrameMediaKey } : {}
 		};
 	}
 	/**
@@ -344,6 +480,10 @@ var FaceGalleryProvider = class {
 		if (identityName !== void 0) {
 			await this.trackStore.setLabel(currentFace.trackId, identityName);
 			await this.eventStore.setLabelForTrack(currentFace.trackId, identityName);
+			await recomputeTrackImportance({
+				trackStore: this.trackStore,
+				eventStore: this.eventStore
+			}, currentFace.trackId);
 		}
 		this.refreshGallery();
 	}
@@ -1382,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) => {
@@ -1424,6 +1565,11 @@ 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 } : {}
+			});
 		}
 		for (const det of frame.detections) {
 			if (det.kind !== "detail" || det.macroClass !== "plate" || !det.parentId) continue;
@@ -1462,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,
@@ -1476,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,
@@ -1564,6 +1712,115 @@ var BestDetectionTracker = class {
 	}
 };
 //#endregion
+//#region src/pipeline-analytics/pipeline/track-best-detection.ts
+/**
+* `TrackBestSelector` — the ONE unified "best detection per track" primitive.
+*
+* Post-analysis derives several per-track "best" artefacts (best FRAME thumbnail,
+* best OBJECT/CLIP embedding + its crop, best FACE crop). They all rank the same
+* way: highest detector confidence per `trackId`. This selector composes the
+* canonical {@link BestDetectionTracker} ranking with the RESOLVED payload the
+* consumers need at the peak (bbox / className / embedding / faceBbox), so a
+* single "new best" DECISION can drive one capture whose output is shared:
+*  - the boxed best-frame `thumbnail`,
+*  - the tight object crop written onto the CLIP embedding row's `mediaKey`
+*    (so a search hit's thumbnail IS the embedded crop).
+*
+* It is deliberately in-memory (the peak is per live track, dropped at track
+* end). The CLIP embedding's cross-restart persistence stays a SEPARATE store-
+* side gate (`ObjectEmbeddingStore.upsertIfBetter`): this selector unifies the
+* DECISION, not the durable store (see best-detection-tracker.ts docstring).
+*
+* The face path keeps its own hold buffer because a face crop can only come
+* from a face-bearing frame (the documented FRAME↔FACE seam) — but it shares
+* this ranking so best-frame and best-face agree on which frame is "best".
+*/
+var TrackBestSelector = class {
+	tracker;
+	payloads = /* @__PURE__ */ new Map();
+	constructor(options = {}) {
+		this.tracker = new BestDetectionTracker(options);
+	}
+	/**
+	* Record an observation for its track. Returns true when it becomes the
+	* track's new best (first sighting, or a confidence that beats the held peak
+	* per the tracker's hysteresis / minGap rules). On acceptance the held payload
+	* advances to this observation so `peak(trackId)` returns the winning frame's
+	* bbox / embedding / faceBbox.
+	*/
+	observe(obs) {
+		const isNewBest = this.tracker.observe(obs.trackId, obs.confidence, obs.atMs);
+		if (isNewBest) {
+			const { trackId, ...payload } = obs;
+			this.payloads.set(trackId, payload);
+		}
+		return isNewBest;
+	}
+	/** The held best payload for a track (undefined if never observed). */
+	peak(trackId) {
+		return this.payloads.get(trackId);
+	}
+	/** The held peak confidence for a track (undefined if never observed). */
+	peakConfidence(trackId) {
+		return this.tracker.peak(trackId)?.confidence;
+	}
+	/** Drop a track's peak + payload (call at track end). */
+	delete(trackId) {
+		this.tracker.delete(trackId);
+		this.payloads.delete(trackId);
+	}
+	clear() {
+		this.tracker.clear();
+		this.payloads.clear();
+	}
+};
+//#endregion
+//#region src/pipeline-analytics/pipeline/object-embedding-selection.ts
+function isClipObjectEmbedding(t) {
+	return Array.isArray(t.embedding) && t.embedding.length > 0 && typeof t.embeddingModelId === "string" && t.embeddingModelId.startsWith("mobileclip-");
+}
+function resolveSearchThumbnailUrl(input) {
+	if (input.baseUrl === null) return void 0;
+	const id = input.embeddingMediaKey ?? input.eventId;
+	return `${input.baseUrl}/${encodeURIComponent(id)}`;
+}
+//#endregion
+//#region src/pipeline-analytics/pipeline/key-event-query.ts
+async function rankKeyEvents(candidates, options, peakLookup) {
+	const scored = [];
+	for (const t of candidates) {
+		if (options.classFilter !== void 0 && t.className !== options.classFilter) continue;
+		let importance = t.importance;
+		let bestEventId = t.bestEventId;
+		if (importance === void 0) {
+			const peak = await peakLookup(t.trackId);
+			importance = computeImportance({
+				peakConfidence: peak.peakConfidence,
+				className: t.className,
+				durationMs: t.lastSeen - t.firstSeen,
+				peakBboxAreaFrac: peak.peakBboxAreaFrac,
+				totalDistance: t.totalDistance,
+				zonesVisited: t.zonesVisited,
+				...t.label !== void 0 ? { label: t.label } : {}
+			}).importance;
+			bestEventId = bestEventId ?? peak.bestEventId;
+		}
+		if (options.minImportance !== void 0 && importance < options.minImportance) continue;
+		scored.push({
+			id: bestEventId ?? t.trackId,
+			trackId: t.trackId,
+			timestamp: t.firstSeen,
+			className: t.className,
+			...t.label !== void 0 ? { label: t.label } : {},
+			importance,
+			bestEventId: bestEventId ?? "",
+			windowMs: t.lastSeen - t.firstSeen
+		});
+	}
+	scored.sort((a, b) => b.importance - a.importance);
+	return scored.slice(0, options.limit);
+}
+//#endregion
 //#region src/pipeline-analytics/pipeline/native-detection.ts
 /**
 * Nominal frame size used to denormalize native `[0,1]` boxes when a
@@ -1733,6 +1990,18 @@ var TRACKS_COLUMNS = [
 	{
 		name: "state",
 		type: "TEXT"
+	},
+	{
+		name: "importance",
+		type: "REAL"
+	},
+	{
+		name: "bestEventId",
+		type: "TEXT"
+	},
+	{
+		name: "importanceReason",
+		type: "TEXT"
 	}
 ];
 var TRACKS_INDEXES = [{
@@ -1764,7 +2033,10 @@ function cloneTrack(t) {
 		zonesVisited: [...t.zonesVisited],
 		totalDistance: t.totalDistance,
 		state: t.state,
-		active: t.active
+		active: t.active,
+		...t.importance !== void 0 ? { importance: t.importance } : {},
+		...t.bestEventId !== void 0 ? { bestEventId: t.bestEventId } : {},
+		...t.importanceReason !== void 0 ? { importanceReason: t.importanceReason } : {}
 	};
 }
 var TrackStore = class {
@@ -1898,6 +2170,37 @@ var TrackStore = class {
 		}
 	}
 	/**
+	* Stamp a track's importance score (+ dominant reason and best-event pointer).
+	* Updates the in-memory active entry (so the value is carried into an eventual
+	* (re)persist) AND patches the already-persisted row. Mirrors `setLabel`.
+	* Forward-only — never rewrites history beyond these fields.
+	*/
+	async setImportance(trackId, importance, reason, bestEventId) {
+		const active = this.active.get(trackId);
+		if (active) {
+			active.importance = importance;
+			active.importanceReason = reason;
+			if (bestEventId !== void 0) active.bestEventId = bestEventId;
+		}
+		const data = {
+			importance,
+			importanceReason: reason
+		};
+		if (bestEventId !== void 0) data["bestEventId"] = bestEventId;
+		try {
+			await this.store.update.mutate({
+				collection: TRACKS_COLLECTION,
+				id: trackId,
+				data
+			});
+		} catch (err) {
+			this.logger.warn("setImportance persist failed", { meta: {
+				trackId,
+				error: String(err)
+			} });
+		}
+	}
+	/**
 	* Clear a track's label. Sets label to null in the persisted row (so
 	* rowToTrack's `typeof label === 'string'` guard omits it on read → label
 	* is absent/undefined). Also clears the in-memory active entry if present.
@@ -1968,7 +2271,10 @@ var TrackStore = class {
 				snapshots: [...t.snapshots],
 				zonesVisited: [...t.zonesVisited],
 				totalDistance: t.totalDistance,
-				state: t.state
+				state: t.state,
+				...t.importance !== void 0 ? { importance: t.importance } : {},
+				...t.bestEventId !== void 0 ? { bestEventId: t.bestEventId } : {},
+				...t.importanceReason !== void 0 ? { importanceReason: t.importanceReason } : {}
 			}
 		});
 	}
@@ -1977,6 +2283,9 @@ var TrackStore = class {
 		const snapshots = data["snapshots"] ?? [];
 		const zones = data["zonesVisited"] ?? [];
 		const label = data["label"];
+		const importance = data["importance"];
+		const bestEventId = data["bestEventId"];
+		const importanceReason = data["importanceReason"];
 		return {
 			trackId: id,
 			deviceId: Number(data["deviceId"]),
@@ -1989,7 +2298,10 @@ var TrackStore = class {
 			zonesVisited: zones,
 			totalDistance: Number(data["totalDistance"] ?? 0),
 			state: data["state"] ?? "idle",
-			active: false
+			active: false,
+			...typeof importance === "number" ? { importance } : {},
+			...typeof bestEventId === "string" ? { bestEventId } : {},
+			...typeof importanceReason === "string" ? { importanceReason } : {}
 		};
 	}
 };
@@ -2492,6 +2804,10 @@ var OBJECT_COLUMNS = [
 	{
 		name: "mediaKey",
 		type: "TEXT"
+	},
+	{
+		name: "importance",
+		type: "REAL"
 	}
 ];
 var AUDIO_COLUMNS = [
@@ -2689,6 +3005,63 @@ var EventStore = class {
 		return updated;
 	}
 	/**
+	* Forward-only: stamp `importance` on every already-emitted object event of a
+	* track. Returns the number of events updated. Best-effort per row. Mirrors
+	* `setLabelForTrack`. Called when a track's key-event score is computed (at
+	* expiry) or recomputed (late label) so an event row carries the parent
+	* track's importance without a join.
+	*/
+	async setImportanceForTrack(trackId, importance) {
+		const rows = await this.store.query.query({
+			collection: OBJECT_EVENTS_COLLECTION,
+			filter: { where: { trackId } }
+		});
+		let updated = 0;
+		for (const row of rows) try {
+			await this.store.update.mutate({
+				collection: OBJECT_EVENTS_COLLECTION,
+				id: row.id,
+				data: { importance }
+			});
+			updated++;
+		} catch (err) {
+			this.logger.warn("setImportanceForTrack update failed", { meta: {
+				trackId,
+				eventId: row.id,
+				error: String(err)
+			} });
+		}
+		return updated;
+	}
+	/**
+	* The track's highest-confidence object event, its bbox area (as a fraction of
+	* frame area), and that event's id — the SHARED per-track ranking already used
+	* for the best frame, read back from the persisted object events (index
+	* `idx_object_track`). Returns zeros + undefined id when the track has none.
+	* Used by the importance scorer at expiry and by `getKeyEvents` compute-on-read.
+	*/
+	async peakForTrack(trackId) {
+		const rows = await this.store.query.query({
+			collection: OBJECT_EVENTS_COLLECTION,
+			filter: { where: { trackId } }
+		});
+		let bestConf = -1;
+		let bestEventId;
+		let peakBboxAreaFrac = 0;
+		for (const row of rows) {
+			const conf = typeof row.data["confidence"] === "number" ? row.data["confidence"] : 0;
+			if (conf <= bestConf) continue;
+			bestConf = conf;
+			bestEventId = row.id;
+			peakBboxAreaFrac = bboxAreaFrac(row.data);
+		}
+		return {
+			peakConfidence: bestConf < 0 ? 0 : bestConf,
+			peakBboxAreaFrac,
+			bestEventId
+		};
+	}
+	/**
 	* Clear `label` on every already-emitted object event of a track (sets label
 	* to null so stripNulls/slimObject omit it on read → label is absent/undefined).
 	* Returns the number of events updated. Best-effort per row. Mirrors
@@ -2883,7 +3256,8 @@ function slimObject(id, data) {
 		timestamp: data["timestamp"],
 		className: data["className"],
 		...typeof data["frameId"] === "string" ? { frameId: data["frameId"] } : {},
-		...typeof data["trackId"] === "string" ? { trackId: data["trackId"] } : {}
+		...typeof data["trackId"] === "string" ? { trackId: data["trackId"] } : {},
+		...typeof data["importance"] === "number" ? { importance: data["importance"] } : {}
 	};
 	if (typeof data["label"] === "string") return {
 		...base,
@@ -2913,6 +3287,17 @@ function slimAudio(id, data) {
 	}
 	return base;
 }
+function bboxAreaFrac(data) {
+	const bbox = data["bbox"];
+	const fw = data["frameWidth"];
+	const fh = data["frameHeight"];
+	if (bbox === null || typeof bbox !== "object") return 0;
+	if (typeof fw !== "number" || typeof fh !== "number" || fw <= 0 || fh <= 0) return 0;
+	const w = "w" in bbox && typeof bbox.w === "number" ? bbox.w : 0;
+	const h = "h" in bbox && typeof bbox.h === "number" ? bbox.h : 0;
+	if (w <= 0 || h <= 0) return 0;
+	return w * h / (fw * fh);
+}
 function stripNulls(data) {
 	const out = {};
 	for (const [k, v] of Object.entries(data)) if (v !== null) out[k] = v;
@@ -4532,6 +4917,14 @@ var FACE_COLUMNS = [
 	{
 		name: "assignedSampleId",
 		type: "TEXT"
+	},
+	{
+		name: "keyFrameMediaKey",
+		type: "TEXT"
+	},
+	{
+		name: "faceBbox",
+		type: "JSON"
 	}
 ];
 var FACE_INDEXES = [{
@@ -4604,7 +4997,9 @@ var FaceStore = class {
 				assigned: Boolean(r.data.assigned),
 				mediaKey: data.mediaKey ?? void 0,
 				recognizedIdentityId: data.recognizedIdentityId ?? void 0,
-				assignedSampleId: data.assignedSampleId ?? void 0
+				assignedSampleId: data.assignedSampleId ?? void 0,
+				keyFrameMediaKey: data.keyFrameMediaKey ?? void 0,
+				faceBbox: data.faceBbox ?? void 0
 			};
 		}).filter((f) => !f.assigned);
 	}
@@ -4768,8 +5163,11 @@ var FaceStore = class {
 			id: faceId,
 			...data,
 			assigned: Boolean(raw.assigned),
+			mediaKey: data.mediaKey ?? void 0,
 			recognizedIdentityId: data.recognizedIdentityId ?? void 0,
-			assignedSampleId: data.assignedSampleId ?? void 0
+			assignedSampleId: data.assignedSampleId ?? void 0,
+			keyFrameMediaKey: data.keyFrameMediaKey ?? void 0,
+			faceBbox: data.faceBbox ?? void 0
 		};
 	}
 	/**
@@ -4813,7 +5211,9 @@ var FaceStore = class {
 				assigned: Boolean(r.data.assigned),
 				mediaKey: data.mediaKey ?? void 0,
 				recognizedIdentityId: data.recognizedIdentityId ?? void 0,
-				assignedSampleId: data.assignedSampleId ?? void 0
+				assignedSampleId: data.assignedSampleId ?? void 0,
+				keyFrameMediaKey: data.keyFrameMediaKey ?? void 0,
+				faceBbox: data.faceBbox ?? void 0
 			};
 		});
 		const filterMode = input.filter ?? "all";
@@ -4878,6 +5278,10 @@ var OBJECT_EMBEDDING_COLUMNS = [
 	{
 		name: "mediaKey",
 		type: "TEXT"
+	},
+	{
+		name: "keyFrameMediaKey",
+		type: "TEXT"
 	}
 ];
 var ObjectEmbeddingStore = class {
@@ -4924,7 +5328,8 @@ var ObjectEmbeddingStore = class {
 			modelId: input.modelId,
 			dim: input.embedding.length,
 			confidence: input.confidence,
-			...input.mediaKey !== void 0 ? { mediaKey: input.mediaKey } : {}
+			...input.mediaKey !== void 0 ? { mediaKey: input.mediaKey } : {},
+			...input.keyFrameMediaKey !== void 0 ? { keyFrameMediaKey: input.keyFrameMediaKey } : {}
 		};
 		try {
 			await this.store.set.mutate({
@@ -4962,7 +5367,8 @@ var ObjectEmbeddingStore = class {
 			return {
 				id: r.id,
 				...data,
-				mediaKey: data.mediaKey ?? void 0
+				mediaKey: data.mediaKey ?? void 0,
+				keyFrameMediaKey: data.keyFrameMediaKey ?? void 0
 			};
 		});
 	}
@@ -5091,6 +5497,16 @@ function updateTrackAggregate(prev, match, opts) {
 }
 //#endregion
 //#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 = [];
@@ -5102,6 +5518,9 @@ var FaceRecognizer = class {
 	*  true highest-confidence face (holding a buffer in memory is cheap, and a
 	*  track may last well under the best-frame rate-limit window). */
 	bestTracker = new BestDetectionTracker();
+	/** Throttle for the "dropping imageless track" log — one line per minute at
+	*  most, so a busy scene that never produces a face crop can't flood logs. */
+	lastImagelessLogAt = 0;
 	constructor(deps) {
 		this.deps = deps;
 	}
@@ -5115,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);
@@ -5152,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", {
@@ -5231,6 +5683,17 @@ var FaceRecognizer = class {
 					}
 				});
 			}
+			try {
+				await this.deps.recomputeImportance?.(work.trackId);
+			} catch (err) {
+				this.deps.logger.warn("recomputeImportance failed", {
+					tags: { deviceId: input.deviceId },
+					meta: {
+						trackId: work.trackId,
+						error: String(err)
+					}
+				});
+			}
 		}
 	}
 	/**
@@ -5250,9 +5713,23 @@ var FaceRecognizer = class {
 			} });
 			return;
 		}
+		if (held.crop === void 0) {
+			const now = Date.now();
+			if (now - this.lastImagelessLogAt >= FACE_IMAGELESS_LOG_THROTTLE_MS) {
+				this.lastImagelessLogAt = now;
+				this.deps.logger.info("face: dropping imageless track (no crop captured)", {
+					tags: {
+						deviceId,
+						trackId
+					},
+					meta: { score: held.score }
+				});
+			}
+			return;
+		}
 		const faceId = `face-${trackId}`;
 		let mediaKey;
-		if (held.crop !== void 0) try {
+		try {
 			mediaKey = await this.deps.mediaStore.put({
 				deviceId,
 				ownerKind: "face",
@@ -5270,6 +5747,17 @@ var FaceRecognizer = class {
 				}
 			});
 		}
+		if (mediaKey === void 0) {
+			this.deps.logger.warn("face: crop store failed — dropping face row", {
+				tags: {
+					deviceId,
+					trackId
+				},
+				meta: { faceId }
+			});
+			return;
+		}
+		const keyFrameMediaKey = this.deps.getKeyFrameMediaKey?.(trackId);
 		try {
 			await this.deps.faceStore.insert({
 				id: faceId,
@@ -5277,9 +5765,11 @@ var FaceRecognizer = class {
 				trackId,
 				timestamp: held.timestamp,
 				embedding: held.embedding,
-				...mediaKey !== void 0 ? { mediaKey } : {},
+				mediaKey,
 				...held.recognizedIdentityId !== void 0 ? { recognizedIdentityId: held.recognizedIdentityId } : {},
-				assigned: false
+				assigned: false,
+				faceBbox: held.bbox,
+				...keyFrameMediaKey !== void 0 ? { keyFrameMediaKey } : {}
 			});
 			this.deps.logger.info("face: buffered to gallery", {
 				tags: {
@@ -5288,7 +5778,7 @@ var FaceRecognizer = class {
 				},
 				meta: {
 					faceId,
-					hasCrop: mediaKey !== void 0,
+					hasCrop: true,
 					recognizedIdentityId: held.recognizedIdentityId ?? null,
 					score: held.score
 				}
@@ -5305,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 = [
@@ -5620,6 +6450,38 @@ var PlateRecognizer = class {
 	}
 };
 //#endregion
+//#region src/shared/frame/shared-frame-resolver.ts
+function frameHandleKey(h) {
+	return `${h.nodeId}:${h.shmId}:${h.slot}:${h.seq}`;
+}
+function createSharedFrameResolver(resolve) {
+	let cache = null;
+	return (handle) => {
+		const key = frameHandleKey(handle);
+		if (cache === null || cache.key !== key) cache = {
+			key,
+			value: resolve(handle)
+		};
+		return cache.value;
+	};
+}
+//#endregion
+//#region src/shared/frame/encode-crop.ts
+/**
+* JPEG-encode an already-cropped raw RGB (24-bit) buffer. Used for the
+* NATIVE-resolution crop path: the decode worker returns the exact ROI pixels
+* at native res, so there is nothing left to crop — only to encode to the same
+* JPEG contract `extractCrop` produces (quality 90). Kept separate from
+* `extractCrop` (which crops a FULL frame) so the native path never re-crops.
+*/
+async function encodeRgbCropToJpeg(bytes, width, height) {
+	return sharp(Buffer.from(bytes), { raw: {
+		width,
+		height,
+		channels: 3
+	} }).jpeg({ quality: 90 }).toBuffer();
+}
+//#endregion
 //#region src/pipeline-analytics/pipeline/event-child-crops.ts
 /**
 * Compute Intersection-over-Union between two (x,y,w,h) bounding boxes.
@@ -5917,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
@@ -5924,6 +6792,18 @@ var SETTINGS_CACHE_TTL_MS = 5e3;
 var BEST_FRAME_HYSTERESIS = .05;
 /** §5 best-frame: at most one best-thumbnail capture per this interval per track. */
 var BEST_FRAME_MIN_GAP_MS = 2e3;
+/** Design B: cap (px) on the width of the native KEY FRAME (full-frame native
+*  capture). Native resolution is the point, but a full 4K RGB surface over the
+*  transport per new-best is wasteful for a web detail view — 1920px keeps a
+*  sharp native frame while bounding the copy (a miss falls back to the
+*  detection-res frame, which is already ≤640px). */
+var KEYFRAME_NATIVE_MAX_WIDTH = 1920;
+/** getKeyEvents: max completed tracks pulled from a window before importance
+*  ranking. Ordering is by importance (not firstSeen) and legacy rows score on
+*  read, so we over-fetch candidates and trim to `limit` after sorting. */
+var KEY_EVENT_CANDIDATE_CAP = 500;
+/** getKeyEvents: default page size when the caller omits `limit`. */
+var KEY_EVENT_DEFAULT_LIMIT = 50;
 /** Cluster setting key (in the centralized addon store) selecting the SINGLE
 *  node that runs post-analysis (event/media/audio/motion generation). All
 *  other nodes are fully inert. No multi-node balancing. Default: the hub. */
@@ -5937,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
@@ -5986,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. */
@@ -6043,6 +6940,23 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 		hysteresis: BEST_FRAME_HYSTERESIS,
 		minGapMs: BEST_FRAME_MIN_GAP_MS
 	});
+	/** Best (highest-confidence) CLIP-object detection per track — drives ONE
+	*  tight object-crop capture whose media key is written onto the embedding
+	*  row (so a semantic-search hit's thumbnail IS the embedded crop). Shares the
+	*  unified best-per-track decision (`TrackBestSelector`); the persistent
+	*  cross-restart "best" gate stays in `ObjectEmbeddingStore.upsertIfBetter`. */
+	objectEmbeddingBestSelector = new TrackBestSelector();
+	/** Design B: the track's shared native key-frame media key, captured at the
+	*  best-detection moment (object-embedding best path). Read by the face path
+	*  at track end so a face row links to the SAME single key frame. Cleared on
+	*  track end. */
+	keyFrameKeyByTrackId = /* @__PURE__ */ new Map();
+	/** The shared crop extractor (native-res first, detection-frame fallback),
+	*  captured in the constructor so `processFrame` can crop object thumbnails in
+	*  the same live-frame window as the face/plate/event-media captures. The
+	*  optional `maxWidth` caps the native crop width (used for the full-frame key
+	*  frame so a 4K native surface never floods the transport). */
+	captureCrop = null;
 	shuttingDown = false;
 	/** True only on the cluster's designated post-processing node. When false the
 	*  addon subscribes to NOTHING — fully inert (no event/media generation). */
@@ -6142,23 +7056,62 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 		});
 		const ownNodeIdForFaces = ownNodeId;
 		const frameReadersForFaces = this.frameReaders;
-		const captureCrop = async (frameHandle, bbox, frameWidth, frameHeight, padding) => {
-			const decoded = await resolveFrame(frameHandle, {
-				ownNodeId: ownNodeIdForFaces,
-				readers: frameReadersForFaces,
-				getRemoteFrame
-			});
-			if (!decoded || decoded.format !== "rgb") return null;
-			const data = Buffer.isBuffer(decoded.data) ? decoded.data : Buffer.from(decoded.data);
+		const pipelineRunnerApi = api.pipelineRunner;
+		const cropMetricLogger = logger.child("NativeCrop");
+		let nativeHits = 0;
+		let nativeFallbacks = 0;
+		let lastCropMetricAt = 0;
+		const NATIVE_CROP_METRIC_INTERVAL_MS = 3e4;
+		const bumpCropMetric = (hit) => {
+			if (hit) nativeHits += 1;
+			else nativeFallbacks += 1;
+			const now = Date.now();
+			if (now - lastCropMetricAt < NATIVE_CROP_METRIC_INTERVAL_MS) return;
+			lastCropMetricAt = now;
+			cropMetricLogger.info("native-crop window", { meta: {
+				nativeHits,
+				detectionFrameFallbacks: nativeFallbacks
+			} });
+		};
+		const tryNativeCrop = async (frameHandle, paddedNorm, maxWidth) => {
+			if (!pipelineRunnerApi?.getNativeCrop) return null;
+			try {
+				const native = await pipelineRunnerApi.getNativeCrop.query({
+					handle: frameHandle,
+					bbox: paddedNorm,
+					...maxWidth !== void 0 ? { maxWidth } : {}
+				}, nodePin(frameHandle.nodeId));
+				if (!native || native.width <= 0 || native.height <= 0) return null;
+				return await encodeRgbCropToJpeg(Buffer.from(native.bytes), native.width, native.height);
+			} catch (err) {
+				cropMetricLogger.debug("native crop request failed — falling back", { meta: { error: errMsg(err) } });
+				return null;
+			}
+		};
+		const resolveFrameShared = createSharedFrameResolver((frameHandle) => resolveFrame(frameHandle, {
+			ownNodeId: ownNodeIdForFaces,
+			readers: frameReadersForFaces,
+			getRemoteFrame
+		}));
+		const captureCrop = async (frameHandle, bbox, frameWidth, frameHeight, padding, maxWidth) => {
 			const paddedNorm = padBbox({
 				x: bbox.x / frameWidth,
 				y: bbox.y / frameHeight,
 				w: bbox.w / frameWidth,
 				h: bbox.h / frameHeight
 			}, padding);
-			const { crop } = await extractCrop(data, decoded.width, decoded.height, paddedNorm);
+			const nativeCrop = await tryNativeCrop(frameHandle, paddedNorm, maxWidth);
+			if (nativeCrop) {
+				bumpCropMetric(true);
+				return nativeCrop;
+			}
+			bumpCropMetric(false);
+			const decoded = await resolveFrameShared(frameHandle);
+			if (!decoded || decoded.format !== "rgb") return null;
+			const { crop } = await extractCrop(Buffer.isBuffer(decoded.data) ? decoded.data : Buffer.from(decoded.data), decoded.width, decoded.height, paddedNorm);
 			return crop;
 		};
+		this.captureCrop = captureCrop;
 		this.faceRecognizer = new FaceRecognizer({
 			identityStore: this.identityStore,
 			faceStore: this.faceStore,
@@ -6166,6 +7119,16 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 			trackStore: this.trackStore,
 			eventStore: this.eventStore,
 			captureCrop,
+			recomputeImportance: (trackId) => {
+				const trackStore = this.trackStore;
+				const eventStore = this.eventStore;
+				if (!trackStore || !eventStore) return Promise.resolve();
+				return recomputeTrackImportance({
+					trackStore,
+					eventStore
+				}, trackId);
+			},
+			getKeyFrameMediaKey: (trackId) => this.keyFrameKeyByTrackId.get(trackId),
 			logger: logger.child("FaceRecognizer")
 		});
 		this.faceRecognizer.refreshGallery();
@@ -6179,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")
@@ -6203,7 +7181,7 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 		try {
 			const handler = createEventMediaHandler({ getMedia: async (id) => {
 				try {
-					return await this.readEventThumbnail(id);
+					return await this.readMediaByEventOrKey(id);
 				} catch (err) {
 					this.ctx.logger.warn("readEventThumbnail failed", { meta: {
 						eventId: id,
@@ -6583,10 +7561,13 @@ 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();
 		this.bestFrameTracker.clear();
+		this.objectEmbeddingBestSelector.clear();
 		this.levelStateByDevice.clear();
 		this.settingsCacheByDevice.clear();
 		this.sensitivityCacheByDevice.clear();
@@ -6606,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
@@ -6616,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);
@@ -6728,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;
@@ -6742,16 +7743,18 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 			} });
 		}
 		await Promise.all(result.objectEvents.map((e) => this.eventStore.insertObject(e)));
-		if (this.objectEmbeddingStore) {
-			for (const t of result.tracked) if (t.embedding !== void 0 && t.embeddingModelId !== void 0 && t.embeddingModelId.startsWith("mobileclip-")) this.objectEmbeddingStore.upsertIfBetter({
+		const objectEmbeddingBests = [];
+		if (this.objectEmbeddingStore) for (const t of result.tracked) {
+			if (!isClipObjectEmbedding(t)) continue;
+			if (this.objectEmbeddingBestSelector.observe({
 				trackId: t.trackId,
-				deviceId,
-				timestamp: result.timestamp,
+				confidence: t.confidence,
+				atMs: result.timestamp,
 				className: t.className,
+				bbox: t.bbox,
 				embedding: t.embedding,
-				modelId: t.embeddingModelId,
-				confidence: t.confidence
-			});
+				embeddingModelId: t.embeddingModelId
+			})) objectEmbeddingBests.push(t);
 		}
 		const faceSettings = this.faceRecognizer ? await this.resolveDeviceFaceSettings(deviceId) : null;
 		const faceGloballyEnabled = this.faceRecognizer ? await this.resolveGlobalFaceEnabled() : false;
@@ -6824,6 +7827,7 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 			cropPadding: mediaSettings.cropPadding,
 			...frameHandle !== void 0 ? { frameHandle } : {}
 		});
+		if (objectEmbeddingBests.length > 0) this.persistObjectEmbeddingBests(deviceId, result.timestamp, objectEmbeddingBests, frameHandle, result.frameWidth, result.frameHeight, mediaSettings.cropPadding);
 		for (const e of result.objectEvents) this.ctx.eventBus.emit({
 			id: `pa-${e.id}`,
 			timestamp: new Date(e.timestamp),
@@ -6936,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
@@ -6945,6 +8085,83 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 	*    NOT gated by saveThumbnails (a single best still-frame is always useful).
 	* The per-track best-confidence map is updated here as a side effect.
 	*/
+	/**
+	* Capture the tight object crop for each new-best CLIP track (native-res via
+	* the shared extractor) and upsert the embedding row with that crop's media
+	* key. The crop uses `putReplacing` so exactly ONE object crop is kept per
+	* track (the current peak). The embedding is upserted even when no crop was
+	* captured (no frame handle) so semantic search still works — the crop just
+	* enhances the search-hit thumbnail. `upsertIfBetter` remains the durable
+	* cross-restart best gate (R3). Best-effort; issued in the live-frame window.
+	*/
+	async persistObjectEmbeddingBests(deviceId, timestamp, bests, frameHandle, frameWidth, frameHeight, cropPadding) {
+		const store = this.objectEmbeddingStore;
+		if (!store) return;
+		await Promise.all(bests.map(async (t) => {
+			if (!isClipObjectEmbedding(t)) return;
+			let mediaKey;
+			let keyFrameMediaKey;
+			if (frameHandle !== void 0 && this.captureCrop && this.mediaStore) {
+				try {
+					const crop = await this.captureCrop(frameHandle, t.bbox, frameWidth, frameHeight, cropPadding);
+					if (crop) mediaKey = await this.mediaStore.putReplacing({
+						deviceId,
+						ownerKind: "track",
+						ownerId: t.trackId,
+						kind: "crop",
+						timestamp,
+						data: crop
+					});
+				} catch (err) {
+					this.ctx.logger.debug("object-embedding crop capture failed", {
+						tags: { deviceId },
+						meta: {
+							trackId: t.trackId,
+							error: errMsg(err)
+						}
+					});
+				}
+				try {
+					const keyFrame = await this.captureCrop(frameHandle, {
+						x: 0,
+						y: 0,
+						w: frameWidth,
+						h: frameHeight
+					}, frameWidth, frameHeight, 0, KEYFRAME_NATIVE_MAX_WIDTH);
+					if (keyFrame) {
+						keyFrameMediaKey = await this.mediaStore.putReplacing({
+							deviceId,
+							ownerKind: "track",
+							ownerId: t.trackId,
+							kind: "keyFrame",
+							timestamp,
+							data: keyFrame
+						});
+						this.keyFrameKeyByTrackId.set(t.trackId, keyFrameMediaKey);
+					}
+				} catch (err) {
+					this.ctx.logger.debug("key-frame capture failed", {
+						tags: { deviceId },
+						meta: {
+							trackId: t.trackId,
+							error: errMsg(err)
+						}
+					});
+				}
+			}
+			await store.upsertIfBetter({
+				trackId: t.trackId,
+				deviceId,
+				timestamp,
+				className: t.className,
+				embedding: t.embedding,
+				modelId: t.embeddingModelId,
+				confidence: t.confidence,
+				...mediaKey !== void 0 ? { mediaKey } : {},
+				...keyFrameMediaKey !== void 0 ? { keyFrameMediaKey } : {}
+			});
+		}));
+	}
 	buildSnapshotTargets(tracked, timestamp, media) {
 		const targets = [];
 		for (const t of tracked) {
@@ -7216,9 +8433,37 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 						positions: t.positions.length
 					}
 				});
-				this.faceRecognizer?.onTrackEnd(t.deviceId, t.trackId);
+				const faceEnd = this.faceRecognizer?.onTrackEnd(t.deviceId, t.trackId);
+				const dropKeyFrameKey = () => {
+					this.keyFrameKeyByTrackId.delete(t.trackId);
+				};
+				if (faceEnd) faceEnd.finally(dropKeyFrameKey);
+				else dropKeyFrameKey();
 				this.plateRecognizer?.onTrackEnd(t.deviceId, t.trackId);
+				try {
+					const peak = await this.eventStore?.peakForTrack(t.trackId);
+					if (peak) {
+						const { importance, reason } = computeImportance({
+							peakConfidence: this.bestFrameTracker.peak(t.trackId)?.confidence ?? peak.peakConfidence,
+							className: t.className,
+							durationMs: duration,
+							peakBboxAreaFrac: peak.peakBboxAreaFrac,
+							totalDistance: t.totalDistance,
+							zonesVisited: t.zonesVisited,
+							...t.label !== void 0 ? { label: t.label } : {}
+						});
+						await this.trackStore?.setImportance(t.trackId, importance, reason, peak.bestEventId);
+						if (peak.bestEventId !== void 0) await this.eventStore?.setImportanceForTrack(t.trackId, importance);
+					}
+				} catch (err) {
+					this.ctx.logger.debug("importance scoring failed", { meta: {
+						trackId: t.trackId,
+						error: String(err)
+					} });
+				}
 				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),
@@ -7441,6 +8686,32 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 		if (input.projection !== "slim" || this.eventMediaBaseUrl === null) return events;
 		return this.withMediaUrl(events);
 	}
+	async getKeyEvents(input) {
+		const trackStore = this.trackStore;
+		if (!trackStore) return [];
+		const eventStore = this.eventStore;
+		try {
+			const candidates = await trackStore.queryHistorical({
+				deviceId: input.deviceId,
+				since: input.since,
+				until: input.until,
+				limit: KEY_EVENT_CANDIDATE_CAP
+			});
+			const peakLookup = (trackId) => eventStore ? eventStore.peakForTrack(trackId) : Promise.resolve({
+				peakConfidence: 0,
+				peakBboxAreaFrac: 0,
+				bestEventId: void 0
+			});
+			return await rankKeyEvents(candidates, {
+				limit: input.limit ?? KEY_EVENT_DEFAULT_LIMIT,
+				...input.minImportance !== void 0 ? { minImportance: input.minImportance } : {},
+				...input.classFilter !== void 0 ? { classFilter: input.classFilter } : {}
+			}, peakLookup);
+		} catch (err) {
+			this.ctx.logger.debug("getKeyEvents failed", { meta: { error: String(err) } });
+			return [];
+		}
+	}
 	async getAudioEvents(input) {
 		const events = await (this.eventStore?.queryAudio(input) ?? Promise.resolve([]));
 		if (input.projection !== "slim" || this.eventMediaBaseUrl === null) return events;
@@ -7483,6 +8754,12 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 			className: input.classFilter
 		});
 		if (embeddingRows.length === 0) return [];
+		const embeddingMediaKeyByTrackId = /* @__PURE__ */ new Map();
+		const keyFrameKeyByTrackId = /* @__PURE__ */ new Map();
+		for (const row of embeddingRows) {
+			if (row.mediaKey !== void 0) embeddingMediaKeyByTrackId.set(row.trackId, row.mediaKey);
+			if (row.keyFrameMediaKey !== void 0) keyFrameKeyByTrackId.set(row.trackId, row.keyFrameMediaKey);
+		}
 		const encoderInfo = await api.embeddingEncoder.getInfo.query().catch((err) => {
 			this.ctx.logger.warn("searchObjectEvents: getInfo failed, proceeding without modelId gate", { meta: { error: String(err) } });
 			return null;
@@ -7529,10 +8806,20 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 					score
 				});
 			}
-			for (const { event, score } of bestEventByTrackId.values()) scored.push({
-				...event,
-				score
-			});
+			for (const { event, score } of bestEventByTrackId.values()) {
+				const mediaUrl = resolveSearchThumbnailUrl({
+					baseUrl: this.eventMediaBaseUrl,
+					eventId: event.id,
+					...event.trackId !== void 0 && embeddingMediaKeyByTrackId.has(event.trackId) ? { embeddingMediaKey: embeddingMediaKeyByTrackId.get(event.trackId) } : {}
+				});
+				const keyFrameMediaKey = event.trackId !== void 0 ? keyFrameKeyByTrackId.get(event.trackId) : void 0;
+				scored.push({
+					...event,
+					score,
+					...mediaUrl !== void 0 ? { mediaUrl } : {},
+					...keyFrameMediaKey !== void 0 ? { keyFrameMediaKey } : {}
+				});
+			}
 		}
 		scored.sort((a, b) => b.score - a.score);
 		return scored.slice(0, input.limit);
@@ -7564,6 +8851,24 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 	* (native-res boxed frame) → any available file. Returns `null` if the
 	* event has no media at all.
 	*/
+	/**
+	* Data-plane resolver: an id is EITHER a bare event id (a UUID → the event's
+	* crop, today's behaviour) OR a MediaStore key (`ownerKind:ownerId:kind:ts`,
+	* contains ':' → served directly by key). The object-embedding search hit
+	* points its thumbnail at the embedding row's crop key (a `track:…:crop:…`
+	* key), so this resolves that crop; event ids stay on the event-crop path.
+	*/
+	async readMediaByEventOrKey(id) {
+		if (id.includes(":")) {
+			const file = await (this.mediaStore?.getByKey(id) ?? Promise.resolve(null));
+			if (!file) return null;
+			return {
+				bytes: Buffer.from(file.base64, "base64"),
+				key: file.key
+			};
+		}
+		return this.readEventThumbnail(id);
+	}
 	async readEventThumbnail(eventId) {
 		const files = await (this.mediaStore?.listByOwner("event", eventId) ?? Promise.resolve([]));
 		const chosen = files.find((f) => f.kind === "crop") ?? files.find((f) => f.kind === "fullFrameBoxed") ?? files[0];