@camstack/addon-post-analysis 1.1.42 → 1.2.1

package/dist/pipeline-analytics/index.mjs

@@ -1,4 +1,4 @@
-import { C as hydrateSchema, D as object, E as number, O as string, S as createEvent, T as boolean, _ as videoclipsCapability, a as OpsLogEntrySchema, b as BaseAddon, c as buildEventKindDescriptor, d as faceGalleryCapability, g as subKindsOf, h as plateGalleryCapability, i as MACRO_LABELS, k as EventCategory, l as cosineSimilarity, m as pipelineAnalyticsCapability, n as EVENT_KIND_BY_CAP, o as addonWidgetsSourceCapability, p as nodePin, r as EVENT_PAD_MS, s as audioMetricsCapability, t as DEFAULT_EVENT_COLOR, v as zoneAnalyticsCapability, w as array, x as DeviceType, y as errMsg } from "../dist-Cgv25jQz.mjs";
+import { C as hydrateSchema, D as object, E as number, O as string, S as createEvent, T as boolean, _ as videoclipsCapability, a as OpsLogEntrySchema, b as BaseAddon, c as buildEventKindDescriptor, d as faceGalleryCapability, g as subKindsOf, h as plateGalleryCapability, i as MACRO_LABELS, k as EventCategory, l as cosineSimilarity, m as pipelineAnalyticsCapability, n as EVENT_KIND_BY_CAP, o as addonWidgetsSourceCapability, p as nodePin, r as EVENT_PAD_MS, s as audioMetricsCapability, t as DEFAULT_EVENT_COLOR, v as zoneAnalyticsCapability, w as array, x as DeviceType, y as errMsg } from "../dist-D4KAS857.mjs";
 import { randomUUID } from "node:crypto";
 import sharp from "sharp";
 //#region src/pipeline-analytics/videoclips-provider.ts
@@ -3650,6 +3650,10 @@ var TRACKS_COLUMNS = [
 		name: "source",
 		type: "TEXT"
 	},
+	{
+		name: "producingDeviceName",
+		type: "TEXT"
+	},
 	{
 		name: "firstSeen",
 		type: "INTEGER",
@@ -4357,6 +4361,7 @@ var TrackStore = class {
 				className: t.className,
 				...t.label !== void 0 ? { label: t.label } : {},
 				source: t.source ?? "sensor",
+				...t.producingDeviceName !== void 0 ? { producingDeviceName: t.producingDeviceName } : {},
 				firstSeen: t.firstSeen,
 				lastSeen: t.lastSeen,
 				positions: [...t.positions],
@@ -4418,6 +4423,7 @@ var TrackStore = class {
 		const classes = data["classes"];
 		const label = data["label"];
 		const source = data["source"];
+		const producingDeviceName = data["producingDeviceName"];
 		const importance = data["importance"];
 		const bestEventId = data["bestEventId"];
 		const importanceReason = data["importanceReason"];
@@ -4438,6 +4444,7 @@ var TrackStore = class {
 			className: String(data["className"]),
 			...typeof label === "string" ? { label } : {},
 			...source === "sensor" || source === "pipeline" ? { source } : {},
+			...typeof producingDeviceName === "string" ? { producingDeviceName } : {},
 			firstSeen: Number(data["firstSeen"]),
 			lastSeen: Number(data["lastSeen"]),
 			positions,
@@ -4483,6 +4490,7 @@ var PLATE_MEDIA_OWNER_PREFIX = "plate-";
 */
 var SINGLE_INSTANCE_KINDS = new Set([
 	"keyFrame",
+	"keyFrameSmall",
 	"thumbnail",
 	"firstFrame",
 	"lastFrame"
@@ -5239,6 +5247,32 @@ var EventStore = class {
 		});
 	}
 	/**
+	* Resolve the OWNING track id for an object event id. Powers the event-media
+	* resolver's track fallback: a new-style object event owns no crop, so its
+	* `mediaUrl` degrades to the track's cadence media, addressed by this id.
+	* Returns `null` when the id is not a persisted object event (e.g. a KeyEvent
+	* whose id is already a track id, or a motion/audio event) — best-effort.
+	*/
+	async getTrackIdForEvent(eventId) {
+		try {
+			const row = await this.store.get.query({
+				collection: OBJECT_EVENTS_COLLECTION,
+				key: eventId
+			});
+			if (row !== null && typeof row === "object" && "trackId" in row) {
+				const trackId = row["trackId"];
+				if (typeof trackId === "string" && trackId.length > 0) return trackId;
+			}
+			return null;
+		} catch (err) {
+			this.logger.debug("getTrackIdForEvent failed", { meta: {
+				eventId,
+				error: String(err)
+			} });
+			return null;
+		}
+	}
+	/**
 	* Forward-only: set `label` on every already-emitted object event of a track.
 	* Returns the number of events updated. Best-effort per row. Used when face
 	* recognition assigns a name to a track after its events were emitted.
@@ -6145,6 +6179,7 @@ var LinkedCamerasCache = class {
 			for (const cameraId of cameraIds) try {
 				const { devices } = await this.deps.linkedDevices.getLinkedDevices({ deviceId: cameraId });
 				for (const d of devices) {
+					if (d.producesTrackedEvents === false) continue;
 					const list = next.get(d.deviceId);
 					if (list === void 0) next.set(d.deviceId, [cameraId]);
 					else if (!list.includes(cameraId)) list.push(cameraId);
@@ -6211,10 +6246,13 @@ async function downscaleFullFrameJpeg(jpeg, maxWidth = 640, maxHeight = 360) {
 *
 * A linked sensor/control state change is projected into the UNIFIED track
 * store as a SYNTHETIC track: `className` = the event kind (`contact` /
-* `lock` / `switch` …), `source: 'sensor'`, media = an on-demand snapshot of
+* `lock` / `switch` …), `source: 'sensor'`, media = an on-demand best shot of
 * the linked camera in the SAME `getTrackMedia` shape the UIs consume (no
-* bbox → full frame), `positions: []`. It joins the timeline via the existing
-* time-based clustering — no new join mechanism.
+* bbox → full frame), persisted under `kind: 'keyFrameSmall'` — the kind the
+* viewer representative-image selectors (hero/clean/reel) actually consume; a
+* `'snapshot'`-kind blob is ignored by those chains, which is what stuck the
+* pa-synth reel on "loading". `positions: []`. It joins the timeline via the
+* existing time-based clustering — no new join mechanism.
 *
 * The raw `SensorEvent` remains the durable record; this track is its
 * projection. Snapshots are debounced per `(camera, kind)` so a chattery
@@ -6222,6 +6260,28 @@ async function downscaleFullFrameJpeg(jpeg, maxWidth = 640, maxHeight = 360) {
 * `source:'sensor'` tracks (they carry no trajectory).
 */
 var DEFAULT_DEBOUNCE_MS = 1e4;
+/** A hanging snapshot cap must not stall the sensor state-change path. */
+var DEFAULT_SNAPSHOT_TIMEOUT_MS = 1e4;
+/** Distinguishes a snapshot-cap timeout from a fetch failure for reporting. */
+var SnapshotTimeoutError = class extends Error {
+	constructor(ms) {
+		super(`snapshot cap timed out after ${ms}ms`);
+		this.name = "SnapshotTimeoutError";
+	}
+};
+/** Reject with `SnapshotTimeoutError` if `promise` doesn't settle within `ms`. */
+function withTimeout$1(promise, ms) {
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => reject(new SnapshotTimeoutError(ms)), ms);
+		promise.then((value) => {
+			clearTimeout(timer);
+			resolve(value);
+		}, (err) => {
+			clearTimeout(timer);
+			reject(err instanceof Error ? err : new Error(String(err)));
+		});
+	});
+}
 /** Full-frame, position-less placeholder (spatial consumers skip these). */
 function zeroPosition(timestamp) {
 	return {
@@ -6239,6 +6299,7 @@ function zeroPosition(timestamp) {
 var SyntheticSensorTrackMaterializer = class {
 	deps;
 	debounceMs;
+	snapshotTimeoutMs;
 	makeId;
 	now;
 	/** Last snapshot time per `${cameraId}:${kind}`. */
@@ -6246,10 +6307,29 @@ var SyntheticSensorTrackMaterializer = class {
 	constructor(deps) {
 		this.deps = deps;
 		this.debounceMs = deps.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+		this.snapshotTimeoutMs = deps.snapshotTimeoutMs ?? DEFAULT_SNAPSHOT_TIMEOUT_MS;
 		this.makeId = deps.makeId ?? (() => `pa-synth-${randomUUID()}`);
 		this.now = deps.now ?? Date.now;
 	}
 	/**
+	* Fetch the linked camera's snapshot under a bounded timeout. A hanging
+	* snapshot cap is skipped (returns null + warns) so the track still lands;
+	* a null / failed fetch is likewise reported and skipped.
+	*/
+	async fetchSnapshot(cameraId) {
+		try {
+			const snap = await withTimeout$1(this.deps.snapshot.getSnapshot({
+				deviceId: cameraId,
+				force: true
+			}), this.snapshotTimeoutMs);
+			if (snap === null) this.deps.onError?.("getSnapshot", /* @__PURE__ */ new Error("snapshot returned null"));
+			return snap;
+		} catch (err) {
+			this.deps.onError?.(err instanceof SnapshotTimeoutError ? "snapshotTimeout" : "snapshotMedia", err);
+			return null;
+		}
+	}
+	/**
 	* Materialize a synthetic track for a sensor/control event on `cameraId`.
 	* Returns the persisted track, or null when debounced. Snapshot failure
 	* still lands a track (with no media) — it never blocks the sensor record.
@@ -6262,28 +6342,23 @@ var SyntheticSensorTrackMaterializer = class {
 		const trackId = this.makeId();
 		const ts = input.timestamp;
 		let mediaKey = null;
-		try {
-			const snap = await this.deps.snapshot.getSnapshot({
+		const snap = await this.fetchSnapshot(input.cameraId);
+		if (snap !== null) try {
+			const raw = Buffer.from(snap.base64, "base64");
+			let data = raw;
+			try {
+				data = await downscaleFullFrameJpeg(raw, 960, 540);
+			} catch (err) {
+				this.deps.onError?.("downscaleSnapshot", err);
+			}
+			mediaKey = await this.deps.media.put({
 				deviceId: input.cameraId,
-				force: true
+				ownerKind: "track",
+				ownerId: trackId,
+				kind: "keyFrameSmall",
+				timestamp: ts,
+				data
 			});
-			if (snap !== null) {
-				const raw = Buffer.from(snap.base64, "base64");
-				let data = raw;
-				try {
-					data = await downscaleFullFrameJpeg(raw);
-				} catch (err) {
-					this.deps.onError?.("downscaleSnapshot", err);
-				}
-				mediaKey = await this.deps.media.put({
-					deviceId: input.cameraId,
-					ownerKind: "track",
-					ownerId: trackId,
-					kind: "snapshot",
-					timestamp: ts,
-					data
-				});
-			} else this.deps.onError?.("getSnapshot", /* @__PURE__ */ new Error("snapshot returned null"));
 		} catch (err) {
 			this.deps.onError?.("snapshotMedia", err);
 		}
@@ -6292,6 +6367,7 @@ var SyntheticSensorTrackMaterializer = class {
 			deviceId: input.cameraId,
 			className: input.kind,
 			source: "sensor",
+			...input.producingDeviceName !== void 0 ? { producingDeviceName: input.producingDeviceName } : {},
 			firstSeen: ts,
 			lastSeen: ts,
 			positions: [],
@@ -6324,6 +6400,22 @@ async function resolveFrame(handle, deps) {
 	return deps.getRemoteFrame(handle);
 }
 //#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/square-safe-crop.ts
 /**
 * Compute a square-safe 16:9 crop region in pixel space.
@@ -6452,27 +6544,30 @@ async function drawBoxedFrame(frameData, frameWidth, frameHeight, boxes, opts =
 }
 //#endregion
 //#region src/pipeline-analytics/services/event-media-dispatcher.ts
-/** All event media is stored at NATIVE resolution (no downscale), high quality.
-*  Small downscaled `thumbnail`s are intentionally left out for now — when we
-*  reintroduce them they'll be a separate small kind. */
-var MEDIA_QUALITY = 88;
-/** Output dimensions for the LOCAL-FALLBACK square-safe 16:9 crops
-*  (crop/faceCrop/plateCrop/thumbnail) cut from the resolved ≤640 frame. */
-var CROP_WIDTH = 640;
-var CROP_HEIGHT = 360;
-var CROP_QUALITY = 80;
 /**
-* Native-surface crop width cap for subject crops (`crop`/`thumbnail`/
-* `faceCrop`/`plateCrop`). ~960px yields a sharp gallery/reel tile AND a
-* ≥224px classifier input straight from the runner's native surface, WITHOUT
-* hauling a full 1920px frame per subject (that width is reserved for the
-* full-frame `keyFrame`). It is an UPPER bound only: a native miss falls back to
-* the ≤640 local crop, so quality never regresses below today's behaviour.
+* Long-side cap (px) for the boxed timeline tiles — `firstFrame`, `snapshot`,
+* `lastFrame`. These are the low-res "timeline filmstrip" images: a native full
+* frame downscaled to 960 with ONLY the track's own box burned in. A native miss
+* falls back to the ≤640 detection frame (an honest lower-res frame, NEVER an
+* upscale).
 */
-var NATIVE_SUBJECT_CROP_MAX_WIDTH = 960;
-function caption(className, confidence, label) {
-	const base = label && label !== className ? `${className} ${label}` : className;
-	return typeof confidence === "number" ? `${base} ${Math.round(confidence * 100)}%` : base;
+var SNAPSHOT_MAX_WIDTH = 960;
+/**
+* Map a detection-frame pixel box (`fromW`×`fromH`, the ≤640 raster the tracker
+* ran on) onto the native full frame (`toW`×`toH`, the 960-downscaled native
+* surface). Both frames show the SAME scene at the same aspect ratio, so a
+* uniform per-axis scale places the box correctly on the higher-res frame.
+*/
+function scaleBox(bbox, fromW, fromH, toW, toH, label) {
+	const sx = toW / fromW;
+	const sy = toH / fromH;
+	return {
+		x: bbox.x * sx,
+		y: bbox.y * sy,
+		w: bbox.w * sx,
+		h: bbox.h * sy,
+		...label ? { label } : {}
+	};
 }
 /**
 * True when a packed-RGB frame is (near-)uniform in every channel — the
@@ -6504,20 +6599,41 @@ function isUniformRgbFrame(data, width, height) {
 }
 /**
 * Generates object-event + track media FROM the decoded detection-pipeline
-* frame (the `frameHandle`/shm frame the detector ran on), NEVER the device
-* snapshot cap. Per object event it writes: a `crop` (square-safe 16:9
-* region, 640×360, q80), and — at ORIGINAL resolution — a clear `fullFrame`
-* (no boxes) + a `fullFrameBoxed` (this event's box drawn) for the detail
-* view. Per new track a boxed `firstFrame`. Child bboxes produce
-* `faceCrop`/`plateCrop` with the same square-safe algorithm.
-* The frame is resolved ONCE per call and reused across all
-* targets — frames recycle in milliseconds, so the caller must invoke this
-* immediately after producing the events while the handle is still live.
+* frame (the `frameHandle`/native surface the detector ran on), NEVER the device
+* snapshot cap.
+*
+* Per object event it writes ONLY the enrichment child crops
+* (`faceCrop`/`plateCrop`) — the retired `crop`/`fullFrame`/`fullFrameBoxed`
+* kinds are no longer produced (2026-07-21; old stored tracks keep reading them,
+* the enum is unchanged). The representative event image is now the track
+* `thumbnail`/`keyFrame`.
+*
+* Per track it writes the boxed timeline tiles — a `firstFrame` on track start,
+* plus periodic `snapshot`/`lastFrame` — each cut from the runner's NATIVE full
+* frame downscaled to {@link SNAPSHOT_MAX_WIDTH} (960) with ONLY the track's own
+* box burned in, falling back to the ≤640 detection frame (honest lower res,
+* never an upscale) on a native miss. The best `thumbnail` stays a clean,
+* uncapped native subject crop (native-or-nothing).
+*
+* The detection frame is resolved ONCE per call (blank-frame guard); native full
+* frames + subject crops are fetched per target by handle. Frames recycle in
+* milliseconds, so the caller must invoke this immediately after producing the
+* events while the handle is still live.
 */
 var EventMediaDispatcher = class {
 	deps;
+	/**
+	* Per-frame single-slot memo of the native 960 full frame (S3): every track
+	* tile in ONE `captureForFrame` pass shares the SAME `frameHandle`, so multiple
+	* `boxedTimelineFrame` calls would otherwise each round-trip the runner for the
+	* identical native full frame. Keyed by frame identity (`createSharedFrameResolver`)
+	* so a recycled slot (new `seq`) is a fresh fetch. `maxWidth` is always
+	* {@link SNAPSHOT_MAX_WIDTH} here (the only dispatcher use of the fetch).
+	*/
+	sharedNativeFullFrame;
 	constructor(deps) {
 		this.deps = deps;
+		this.sharedNativeFullFrame = createSharedFrameResolver((handle) => this.deps.getNativeFullFrameRgb(handle, SNAPSHOT_MAX_WIDTH));
 	}
 	async captureForFrame(input) {
 		const { deviceId, frameHandle, events, trackFrames } = input;
@@ -6576,8 +6692,8 @@ var EventMediaDispatcher = class {
 			});
 			return empty;
 		}
-		for (const ev of events) await this.writeEventMedia(deviceId, frameHandle, frameData, fw, fh, ev, input.cropPadding);
-		for (const tf of trackFrames) await this.writeTrackFrame(deviceId, frameData, fw, fh, tf);
+		for (const ev of events) await this.writeEventMedia(deviceId, frameHandle, fw, fh, ev, input.cropPadding);
+		for (const tf of trackFrames) await this.writeTrackFrame(deviceId, frameHandle, frameData, fw, fh, tf);
 		const storedSnapshots = [];
 		const thumbnailTrackIds = [];
 		for (const sn of snapshots) {
@@ -6608,21 +6724,7 @@ var EventMediaDispatcher = class {
 			thumbnailWritten: false
 		};
 		let boxed = null;
-		if (sn.appendSnapshot || sn.rollingLastFrame) try {
-			boxed = await drawBoxedFrame(frameData, fw, fh, [{
-				...sn.bbox,
-				...sn.label ? { label: sn.label } : {}
-			}], { quality: MEDIA_QUALITY });
-		} catch (err) {
-			this.deps.logger.warn("event media: track snapshot encode failed", {
-				tags: { deviceId },
-				meta: {
-					deviceId,
-					trackId: sn.trackId,
-					error: err instanceof Error ? err.message : String(err)
-				}
-			});
-		}
+		if (sn.appendSnapshot || sn.rollingLastFrame) boxed = await this.boxedTimelineFrame(deviceId, frameHandle, frameData, fw, fh, sn.trackId, sn.bbox, sn.label);
 		let stored = null;
 		if (sn.appendSnapshot && boxed) try {
 			const mediaKey = await this.deps.mediaStore.put({
@@ -6642,19 +6744,9 @@ var EventMediaDispatcher = class {
 		} catch {}
 		if (sn.rollingLastFrame && boxed) await this.replaceKind(deviceId, sn.trackId, "lastFrame", sn.timestamp, boxed);
 		let thumbnailWritten = false;
-		if (sn.bestThumbnail) try {
-			const crop = await this.cropSubjectRegion(frameHandle, frameData, fw, fh, sn.bbox, cropPadding);
-			thumbnailWritten = await this.replaceKind(deviceId, sn.trackId, "thumbnail", sn.timestamp, crop);
-		} catch (err) {
-			this.deps.logger.warn("event media: track thumbnail crop failed", {
-				tags: { deviceId },
-				meta: {
-					deviceId,
-					trackId: sn.trackId,
-					error: err instanceof Error ? err.message : String(err)
-				}
-			});
-			if (boxed) thumbnailWritten = await this.replaceKind(deviceId, sn.trackId, "thumbnail", sn.timestamp, boxed);
+		if (sn.bestThumbnail) {
+			const crop = await this.cropSubjectRegion(frameHandle, fw, fh, sn.bbox, cropPadding);
+			if (crop) thumbnailWritten = await this.replaceKind(deviceId, sn.trackId, "thumbnail", sn.timestamp, crop);
 		}
 		return {
 			storedSnapshot: stored,
@@ -6666,143 +6758,126 @@ var EventMediaDispatcher = class {
 	* object-event `crop` kind, the child `faceCrop`/`plateCrop`, and the track
 	* `thumbnail`: the square-safe 16:9 region around the bbox with NO box drawn.
 	*
-	* NATIVE-FIRST: the region is requested from the runner's retained native
-	* surface (normalized [0,1] coords map directly onto it), downscaled to
-	* {@link NATIVE_SUBJECT_CROP_MAX_WIDTH} — a sharp tile at native detail. On any
-	* miss/error (or a runner without the method) it FALLS BACK to cropping the
-	* resolved ≤640 frame locally (today's behaviour), so quality never regresses.
-	* Both paths run inside the live-handle window opened by `captureForFrame`.
+	* NATIVE-OR-NOTHING: the region is requested from the runner's retained native
+	* surface (normalized [0,1] coords map directly onto it) with NO `maxWidth` —
+	* the crop at TRUE native resolution (decision #3). On any miss/error (or a
+	* runner without the method) it returns `null` after a loud `logger.warn`; the
+	* caller SKIPS the write and the per-frame retry lands a real native crop
+	* later. It is NEVER upscaled — an upscaled ≤640 tile is a blurred lie
+	* (case-study lapVar 5–7), so no local resize fallback exists. Runs inside the
+	* live-handle window opened by `captureForFrame`.
 	*/
-	async cropSubjectRegion(frameHandle, frameData, fw, fh, bbox, cropPadding) {
-		if (this.deps.getNativeCropJpeg) try {
+	async cropSubjectRegion(frameHandle, fw, fh, bbox, cropPadding) {
+		if (!this.deps.getNativeCropJpeg) {
+			this.deps.logger.warn("native subject crop miss — will retry, no upscale", { meta: {
+				shmId: frameHandle.shmId,
+				reason: "no-native-cap"
+			} });
+			return null;
+		}
+		try {
 			const norm = squareSafeCropRegionNormalized(bbox, {
 				W: fw,
 				H: fh
 			}, cropPadding);
-			const native = await this.deps.getNativeCropJpeg(frameHandle, norm, NATIVE_SUBJECT_CROP_MAX_WIDTH);
+			const native = await this.deps.getNativeCropJpeg(frameHandle, norm);
 			if (native) return native;
+			this.deps.logger.warn("native subject crop miss — will retry, no upscale", { meta: {
+				shmId: frameHandle.shmId,
+				reason: "native-miss"
+			} });
+			return null;
 		} catch (err) {
-			this.deps.logger.debug("event media: native subject crop failed — local fallback", { meta: {
+			this.deps.logger.warn("native subject crop miss — will retry, no upscale", { meta: {
 				shmId: frameHandle.shmId,
 				error: err instanceof Error ? err.message : String(err)
 			} });
+			return null;
 		}
-		return this.cropSubjectRegionLocal(frameData, fw, fh, bbox, cropPadding);
 	}
 	/**
-	* Local-fallback square-safe 16:9 crop out of the resolved ≤640 frame, resized
-	* to 640×360, JPEG q80. Used when the native surface is unavailable/missed.
+	* The boxed timeline tile (`firstFrame`/`snapshot`/`lastFrame`): the track's
+	* OWN box burned onto the NATIVE full frame downscaled to
+	* {@link SNAPSHOT_MAX_WIDTH}. On a native miss it falls back to the ≤640
+	* detection frame (`frameData`) downscaled to the same cap with a `logger.warn`
+	* — an honest LOWER-res frame, NEVER an upscale. Returns the JPEG, or `null`
+	* only if the sharp encode itself throws.
 	*/
-	async cropSubjectRegionLocal(frameData, fw, fh, bbox, cropPadding) {
-		const region = squareSafeCropRegion(bbox, {
-			W: fw,
-			H: fh
-		}, cropPadding);
-		const left = Math.max(0, Math.min(region.x, fw - 1));
-		const top = Math.max(0, Math.min(region.y, fh - 1));
-		const width = Math.max(1, Math.min(region.w, fw - left));
-		const height = Math.max(1, Math.min(region.h, fh - top));
-		return await sharp(frameData, { raw: {
-			width: fw,
-			height: fh,
-			channels: 3
-		} }).extract({
-			left,
-			top,
-			width,
-			height
-		}).resize(CROP_WIDTH, CROP_HEIGHT).jpeg({ quality: CROP_QUALITY }).toBuffer();
-	}
-	async replaceKind(deviceId, trackId, kind, timestamp, data) {
+	async boxedTimelineFrame(deviceId, frameHandle, frameData, fw, fh, ownerId, bbox, label) {
+		let nf = null;
+		let fetchThrew = false;
 		try {
-			await this.deps.mediaStore.putReplacing({
-				deviceId,
-				ownerKind: "track",
-				ownerId: trackId,
-				kind,
-				timestamp,
-				data
-			});
-			return true;
+			nf = await this.sharedNativeFullFrame(frameHandle);
 		} catch (err) {
-			this.deps.logger.debug(`event media: ${kind} replace failed`, {
+			fetchThrew = true;
+			this.deps.logger.warn("native full frame fetch threw — 640 boxed fallback", {
 				tags: { deviceId },
 				meta: {
 					deviceId,
-					trackId,
+					ownerId,
 					error: err instanceof Error ? err.message : String(err)
 				}
 			});
-			return false;
 		}
-	}
-	async writeEventMedia(deviceId, frameHandle, frameData, fw, fh, ev, cropPadding) {
-		const box = {
-			...ev.bbox,
-			label: caption(ev.className, ev.confidence, ev.label)
-		};
 		try {
-			const crop = await this.cropSubjectRegion(frameHandle, frameData, fw, fh, ev.bbox, cropPadding);
-			await this.deps.mediaStore.put({
-				deviceId,
-				ownerKind: "event",
-				ownerId: ev.eventId,
-				kind: "crop",
-				timestamp: ev.timestamp,
-				data: crop
-			});
-		} catch (err) {
-			this.deps.logger.warn("event media: crop failed", {
+			if (nf && nf.format === "rgb" && nf.width > 0 && nf.height > 0) {
+				const box = scaleBox(bbox, fw, fh, nf.width, nf.height, label);
+				return await drawBoxedFrame(nf.data, nf.width, nf.height, [box], { quality: 88 });
+			}
+			if (!fetchThrew) this.deps.logger.warn("native full frame miss — 640 boxed fallback (no upscale)", {
 				tags: { deviceId },
 				meta: {
 					deviceId,
-					eventId: ev.eventId,
-					error: err instanceof Error ? err.message : String(err)
+					ownerId,
+					shmId: frameHandle.shmId
 				}
 			});
-		}
-		try {
-			const fullFrame = await drawBoxedFrame(frameData, fw, fh, [], { quality: MEDIA_QUALITY });
-			await this.deps.mediaStore.put({
-				deviceId,
-				ownerKind: "event",
-				ownerId: ev.eventId,
-				kind: "fullFrame",
-				timestamp: ev.timestamp,
-				data: fullFrame
+			return await drawBoxedFrame(frameData, fw, fh, [{
+				...bbox,
+				...label ? { label } : {}
+			}], {
+				quality: 88,
+				maxWidth: SNAPSHOT_MAX_WIDTH
 			});
 		} catch (err) {
-			this.deps.logger.warn("event media: clear full frame failed", {
+			this.deps.logger.warn("event media: timeline frame encode failed", {
 				tags: { deviceId },
 				meta: {
 					deviceId,
-					eventId: ev.eventId,
+					ownerId,
 					error: err instanceof Error ? err.message : String(err)
 				}
 			});
+			return null;
 		}
+	}
+	async replaceKind(deviceId, trackId, kind, timestamp, data) {
 		try {
-			const fullFrameBoxed = await drawBoxedFrame(frameData, fw, fh, [box], { quality: MEDIA_QUALITY });
-			await this.deps.mediaStore.put({
+			await this.deps.mediaStore.putReplacing({
 				deviceId,
-				ownerKind: "event",
-				ownerId: ev.eventId,
-				kind: "fullFrameBoxed",
-				timestamp: ev.timestamp,
-				data: fullFrameBoxed
+				ownerKind: "track",
+				ownerId: trackId,
+				kind,
+				timestamp,
+				data
 			});
+			return true;
 		} catch (err) {
-			this.deps.logger.warn("event media: boxed full frame failed", {
+			this.deps.logger.debug(`event media: ${kind} replace failed`, {
 				tags: { deviceId },
 				meta: {
 					deviceId,
-					eventId: ev.eventId,
+					trackId,
 					error: err instanceof Error ? err.message : String(err)
 				}
 			});
+			return false;
 		}
+	}
+	async writeEventMedia(deviceId, frameHandle, fw, fh, ev, cropPadding) {
 		if (ev.childCrops) for (const child of ev.childCrops) try {
-			const childCropData = await this.cropSubjectRegion(frameHandle, frameData, fw, fh, child.bbox, cropPadding);
+			const childCropData = await this.cropSubjectRegion(frameHandle, fw, fh, child.bbox, cropPadding);
+			if (!childCropData) continue;
 			await this.deps.mediaStore.put({
 				deviceId,
 				ownerKind: "event",
@@ -6822,13 +6897,10 @@ var EventMediaDispatcher = class {
 			});
 		}
 	}
-	async writeTrackFrame(deviceId, frameData, fw, fh, tf) {
-		const box = {
-			...tf.bbox,
-			...tf.label ? { label: tf.label } : {}
-		};
+	async writeTrackFrame(deviceId, frameHandle, frameData, fw, fh, tf) {
+		const boxed = await this.boxedTimelineFrame(deviceId, frameHandle, frameData, fw, fh, tf.trackId, tf.bbox, tf.label);
+		if (!boxed) return;
 		try {
-			const boxed = await drawBoxedFrame(frameData, fw, fh, [box], { quality: MEDIA_QUALITY });
 			await this.deps.mediaStore.put({
 				deviceId,
 				ownerKind: "track",
@@ -8704,34 +8776,13 @@ function isPlausibleThumbnailBox(bbox, frameWidth, frameHeight) {
 }
 //#endregion
 //#region src/pipeline-analytics/pipeline/key-frame-capture.ts
-/**
-* Pure helpers for the per-track NATIVE-resolution `keyFrame` capture
-* (Design B — one native full-frame per track at its best-detection moment).
-*
-* ## Why this exists (the missing native keyFrame)
-*
-* `keyFrame` was historically captured ONLY inside the CLIP object-embedding
-* best path (`persistObjectEmbeddingBests`, gated by `isClipObjectEmbedding`).
-* Under the two-plane pipeline the root frame carries NO CLIP embedding (clip is
-* a per-track DETAIL served via `runDetailSubtree`, and is disabled cluster-
-* wide), so that gate was never satisfied and the native `keyFrame` was NEVER
-* produced — every stored frame stayed at the ≤640×360 detection resolution.
-*
-* The fix decouples the `keyFrame` from the clip path: it is captured on the
-* GENERAL best-frame signal (the same `bestThumbnail` decision that drives the
-* `thumbnail`), reusing the WORKING native crop path (`captureCrop` →
-* `pipelineRunner.getNativeCrop`, which cuts the ROI from the decode worker's
-* retained NATIVE surface and only falls back to the detection frame on a miss).
-* A full-frame ROI at {@link KEYFRAME_NATIVE_MAX_WIDTH} therefore yields a frame
-* LARGER than the detection raster (up to the cap), which is the whole point of
-* the `keyFrame` kind.
-*/
 /** 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;
+*  Native resolution is the point: a 4K cam (3840) resolves TRUE native (no
+*  resize, 3840 ≤ 4096); an 8K cam is bounded to 4096 (still far past the retired
+*  1920 cap). This honours "native, no 1920 intermediate" while keeping the raw
+*  rgb transfer wire-safe. Env-overridable (`CAMSTACK_KEYFRAME_NATIVE_MAX_WIDTH`)
+*  for a homelab that wants a tighter/looser bound. */
+var KEYFRAME_NATIVE_MAX_WIDTH = Number.parseInt(process.env.CAMSTACK_KEYFRAME_NATIVE_MAX_WIDTH ?? "", 10) || 4096;
 /**
 * The tracks whose native `keyFrame` should be (re)captured THIS frame: exactly
 * the tracks that hit a GENUINE new best-frame moment (`keyFrame`), NOT the
@@ -8742,31 +8793,39 @@ function selectKeyFrameTrackIds(targets) {
 	return targets.filter((t) => t.keyFrame).map((t) => t.trackId);
 }
 /**
-* Build the `captureCrop` request for a track's native `keyFrame`: the FULL
-* frame (no padding) at the native width cap. The full-frame box is what makes
-* the capture route through the native surface at native resolution instead of
-* a tight ≤640 detection crop.
+* Gate for the clean best-shot native `keyFrame` (design 2026-07-21): the keyFrame
+* is the track's CLEAN native best frame and MUST NEVER be persisted from the
+* ≤640 RAM fallback (`tier: 'ram-fullframe'`) — that would pin the stored keyFrame
+* at detection resolution. On a `ram-fullframe` tier the caller drops the write
+* and the per-frame re-fire retries a real native surface later.
+*
+* An ABSENT tier (`undefined`, from a pre-tier runner on a mixed-version cluster)
+* is ACCEPTED exactly as before the tier field existed — back-compat, never break
+* mixed-version clusters. Only an explicit `ram-fullframe` is rejected.
+*
+* NOTE: this gates the native `keyFrame` ONLY. The 960 boxed TIMELINE tiles keep
+* accepting the ≤640 fallback (an honest low-res timeline is acceptable there).
 */
-function buildKeyFrameCaptureRequest(frameWidth, frameHeight) {
-	return {
-		bbox: {
-			x: 0,
-			y: 0,
-			w: frameWidth,
-			h: frameHeight
-		},
-		padding: 0,
-		maxWidth: KEYFRAME_NATIVE_MAX_WIDTH
-	};
+function keyFrameAcceptsTier(tier) {
+	return tier !== "ram-fullframe";
 }
 /**
-* True when a native subject crop of `width` px is a plausible native hit worth
-* keeping, rather than a sub-threshold fallback stamp. Clamps the floor to the
-* requested `maxWidth` so a caller that legitimately asked for a narrow crop
-* (`maxWidth < MIN`) is not rejected for honouring its own cap.
+* Encode BOTH key-frame variants from a single decoded native full frame. No box
+* is drawn (the `keyFrame` is the clean best full frame); `drawBoxedFrame([])`
+* is used purely as the raw-rgb → JPEG (+ optional downscale) encoder so the two
+* variants share one code path. The caller has ALREADY fetched the native frame
+* at {@link KEYFRAME_NATIVE_MAX_WIDTH}, so `keyFrame` re-encodes it verbatim
+* (no resize) and `keyFrameSmall` downscales the same buffer to ≤960 —
+* `withoutEnlargement` never upscales a sub-960 native frame.
 */
-function nativeSubjectCropMeetsFloor(width, maxWidth) {
-	return width >= Math.min(320, maxWidth);
+async function encodeKeyFrameVariants(native) {
+	return {
+		keyFrame: await drawBoxedFrame(native.data, native.width, native.height, [], { quality: 88 }),
+		keyFrameSmall: await drawBoxedFrame(native.data, native.width, native.height, [], {
+			quality: 88,
+			maxWidth: 960
+		})
+	};
 }
 //#endregion
 //#region src/pipeline-analytics/track-retention-sweep.ts
@@ -11529,22 +11588,6 @@ 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
@@ -11720,6 +11763,26 @@ function padBbox(bbox, padding) {
 	};
 }
 //#endregion
+//#region src/pipeline-analytics/pipeline/capture-crop.ts
+function createCaptureCrop(deps) {
+	return 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 nativeCrop = await deps.tryNativeCrop(frameHandle, paddedNorm, maxWidth);
+		if (nativeCrop) {
+			deps.bumpCropMetric(true);
+			return nativeCrop;
+		}
+		deps.bumpCropMetric(false);
+		deps.logger.debug("enrichment crop native miss — detail scheduler will re-run", { meta: { nodeId: frameHandle.nodeId } });
+		return null;
+	};
+}
+//#endregion
 //#region src/pipeline-analytics/pipeline/dropout-skip.ts
 function shouldSkipDropoutFrame(activeTrackCount, detectionCount, consecutiveSkips, cfg) {
 	if (!cfg.enabled) return false;
@@ -11905,6 +11968,32 @@ async function makeSquareThumb(bytes, size) {
 	}).jpeg({ quality: THUMB_QUALITY }).toBuffer();
 }
 //#endregion
+//#region src/pipeline-analytics/event-thumbnail-resolver.ts
+/** Pick an event-OWNED media blob: the tight `crop`, else the native-res boxed
+*  `fullFrameBoxed`, else any available file. Both preferred kinds are RETIRED
+*  for new tracks (served only for old stored rows). Undefined when the event
+*  owns no media. */
+function pickEventOwnedMedia(files) {
+	return files.find((f) => f.kind === "crop") ?? files.find((f) => f.kind === "fullFrameBoxed") ?? files[0];
+}
+/** Pick a track's fallback media in the shared cadence-preference order the
+*  KeyEvent path uses: best `thumbnail` → rolling `lastFrame` → `firstFrame` →
+*  newest `snapshot` → any track blob. Undefined when the track owns no media. */
+function pickTrackFallbackMedia(files) {
+	return files.find((f) => f.kind === "thumbnail") ?? files.find((f) => f.kind === "lastFrame") ?? files.find((f) => f.kind === "firstFrame") ?? [...files].reverse().find((f) => f.kind === "snapshot") ?? files[files.length - 1];
+}
+/**
+* Resolve the default-path media for an event id: the event's own media when it
+* has any, else the owning track's fallback media. Returns `null` when neither
+* yields a blob (caller 404s → the surface shows an icon).
+*/
+async function resolveDefaultEventMedia(deps) {
+	const owned = pickEventOwnedMedia(deps.eventFiles);
+	if (owned) return owned;
+	const trackId = await deps.getTrackIdForEvent(deps.eventId) ?? deps.eventId;
+	return pickTrackFallbackMedia(await deps.listTrackMedia(trackId)) ?? null;
+}
+//#endregion
 //#region src/pipeline-analytics/index.ts
 /**
 * Pipeline Analytics addon — subscribes to `PipelineInferenceResult` +
@@ -11979,12 +12068,20 @@ var MOTION_EVENT_HEARTBEAT_MS = 5e3;
 * without it a crop-forced request degraded to the `keyFrame` FULL FRAME,
 * which is how 65% of the timeline tiles rendered as whole scenes. It sits
 * right after a real `crop`, before the full-scene `fullFrame`/`keyFrame`.
+*
+* `keyFrameSmall` (the 960px no-box downscale of the best-shot `keyFrame`)
+* joined the clean set on 2026-07-21 so a crop-forced request can degrade to it
+* for tracks whose only clean media is the small key frame; it sits last
+* (fullest-scene, but subject-centered enough to serve as a reasonable fallback
+* over 404). The retired-but-still-stored kinds (`crop`) stay listed so old rows
+* keep resolving.
 */
 var CLEAN_MEDIA_KINDS = [
 	"crop",
 	"thumbnail",
 	"fullFrame",
-	"keyFrame"
+	"keyFrame",
+	"keyFrameSmall"
 ];
 /**
 * Pick a CLEAN (never boxed) media file for a crop-forced request: the exact
@@ -12247,6 +12344,12 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 	*  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;
+	/** Full NATIVE frame by handle (downscaled worker-side to `maxWidth`), routed
+	*  to the owning runner, PLUS the source `tier`. Captured in the async init
+	*  block so `persistKeyFrames` can fetch the native full frame for the
+	*  `keyFrame` + `keyFrameSmall` writes in the same live-frame window AND reject
+	*  a ≤640 RAM fallback (`tier: 'ram-fullframe'`). Null until init completes. */
+	getNativeKeyFrameRgb = 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). */
@@ -12461,6 +12564,33 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 				timestamp: 0
 			};
 		};
+		const fetchNativeFullFrameTiered = async (handle, maxWidth) => {
+			if (!pipelineRunnerApi?.getNativeCrop) return null;
+			const full = await pipelineRunnerApi.getNativeCrop.query({
+				handle,
+				bbox: {
+					x: 0,
+					y: 0,
+					w: 1,
+					h: 1
+				},
+				maxWidth
+			}, nodePin(handle.nodeId));
+			if (!full || full.width <= 0 || full.height <= 0) return null;
+			const tier = full.tier === "ram-fullframe" ? "ram-fullframe" : "native";
+			return {
+				frame: {
+					data: Buffer.from(full.bytes),
+					width: full.width,
+					height: full.height,
+					format: "rgb",
+					timestamp: 0
+				},
+				tier
+			};
+		};
+		const getNativeFullFrameRgb = async (handle, maxWidth) => (await fetchNativeFullFrameTiered(handle, maxWidth))?.frame ?? null;
+		this.getNativeKeyFrameRgb = fetchNativeFullFrameTiered;
 		const cropMetricLogger = logger.child("NativeCrop");
 		let nativeHits = 0;
 		let nativeFallbacks = 0;
@@ -12503,12 +12633,7 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 		};
 		const getNativeCropJpeg = async (frameHandle, normalizedBbox, maxWidth) => {
 			const native = await fetchNativeCropRgb(frameHandle, normalizedBbox, maxWidth);
-			if (!native || !nativeSubjectCropMeetsFloor(native.width, maxWidth)) {
-				if (native) cropMetricLogger.debug("native subject crop below floor — local fallback", { meta: {
-					width: native.width,
-					height: native.height,
-					maxWidth
-				} });
+			if (!native) {
 				bumpCropMetric(false);
 				return null;
 			}
@@ -12519,28 +12644,15 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 		this.eventMediaDispatcher = new EventMediaDispatcher({
 			getRemoteFrame,
 			getNativeCropJpeg,
+			getNativeFullFrameRgb,
 			mediaStore: this.mediaStore,
 			logger: logger.child("EventMediaDispatcher")
 		});
-		const resolveFrameShared = createSharedFrameResolver((frameHandle) => resolveFrame(frameHandle, { 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 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;
-		};
+		const captureCrop = createCaptureCrop({
+			tryNativeCrop,
+			bumpCropMetric,
+			logger: logger.child("CaptureCrop")
+		});
 		this.captureCrop = captureCrop;
 		this.faceRecognizer = new FaceRecognizer({
 			identityStore: this.identityStore,
@@ -13389,7 +13501,7 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 			else plateCrops += 1;
 			const snapshotTargets = this.buildSnapshotTargets(deviceId, result.tracked, result.timestamp, mediaSettings, result.frameWidth, result.frameHeight);
 			const keyFrameTrackIds = selectKeyFrameTrackIds(snapshotTargets);
-			if (keyFrameTrackIds.length > 0) this.persistKeyFrames(deviceId, result.timestamp, keyFrameTrackIds, frameHandle, result.frameWidth, result.frameHeight);
+			if (keyFrameTrackIds.length > 0) this.persistKeyFrames(deviceId, result.timestamp, keyFrameTrackIds, frameHandle);
 			if (eventTargets.length > 0 || firstFrameTargets.length > 0 || snapshotTargets.length > 0) {
 				const captureCounts = {
 					events: eventTargets.length,
@@ -14000,30 +14112,54 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 		}));
 	}
 	/**
-	* Capture ONE native-resolution KEY FRAME per given track at this best-
-	* detection frame and store it (`putReplacing` → one keyFrame per track).
+	* Capture the CLEAN best full frame per given track at this best-detection
+	* moment and store BOTH variants (`putReplacing` → one row per track, per
+	* kind): the native `keyFrame` (full frame fetched at `KEYFRAME_NATIVE_MAX_WIDTH`
+	* — true native on a 4K cam) plus its 960 companion `keyFrameSmall`, encoded
+	* from the SAME native surface (no second fetch). No box is drawn — these are
+	* the clean hero images (`keyFrameSmall` is the web-friendly one).
 	*
-	* The full frame is cropped NATIVE-FIRST via `captureCrop`: the request is the
-	* FULL frame (no padding) at `KEYFRAME_NATIVE_MAX_WIDTH`, which routes through
-	* `pipelineRunner.getNativeCrop` (the decode worker's retained native surface)
-	* and only falls back to the ≤640 detection frame when the native lease is
-	* gone. The stored key is recorded in `keyFrameKeyByTrackId` so the face /
-	* plate / object-embedding rows LINK the SAME native key frame (Design B).
-	* Issued in the live-frame window so the native lease is still held. Best-
-	* effort (D8) — a per-track failure is logged and never thrown.
+	* NATIVE-OR-NOTHING: a native miss logs `error` and returns (no upscale, no
+	* ≤640 stand-in) — the next genuine new-best frame retries. The `keyFrame`
+	* key is recorded in `keyFrameKeyByTrackId` so the face / plate /
+	* object-embedding rows LINK the SAME native key frame (Design B). Issued in
+	* the live-frame window so the native lease is still held. Best-effort (D8) —
+	* a per-track failure is logged and never thrown.
 	*/
-	async persistKeyFrames(deviceId, timestamp, trackIds, frameHandle, frameWidth, frameHeight) {
-		const capture = this.captureCrop;
+	async persistKeyFrames(deviceId, timestamp, trackIds, frameHandle) {
+		const getNative = this.getNativeKeyFrameRgb;
 		const mediaStore = this.mediaStore;
-		if (!capture || !mediaStore) return;
-		const req = buildKeyFrameCaptureRequest(frameWidth, frameHeight);
+		if (!getNative || !mediaStore) return;
 		const pending = trackIds.filter((id) => !this.keyFrameInFlight.has(id));
 		if (pending.length === 0) return;
 		for (const id of pending) this.keyFrameInFlight.add(id);
 		await Promise.all(pending.map(async (trackId) => {
 			try {
-				const keyFrame = await capture(frameHandle, req.bbox, frameWidth, frameHeight, req.padding, req.maxWidth);
-				if (!keyFrame) return;
+				const result = await getNative(frameHandle, KEYFRAME_NATIVE_MAX_WIDTH);
+				const native = result?.frame;
+				if (!native || native.format !== "rgb" || native.width <= 0 || native.height <= 0) {
+					this.ctx.logger.error("key-frame native miss — no upscale, will retry next best", {
+						tags: { deviceId },
+						meta: {
+							trackId,
+							shmId: frameHandle.shmId
+						}
+					});
+					return;
+				}
+				const tier = result.tier;
+				if (!keyFrameAcceptsTier(tier)) {
+					this.ctx.logger.warn("keyFrame native miss — RAM tier rejected, will retry", {
+						tags: { deviceId },
+						meta: {
+							trackId,
+							shmId: frameHandle.shmId,
+							tier
+						}
+					});
+					return;
+				}
+				const { keyFrame, keyFrameSmall } = await encodeKeyFrameVariants(native);
 				const key = await mediaStore.putReplacing({
 					deviceId,
 					ownerKind: "track",
@@ -14033,6 +14169,14 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 					data: keyFrame
 				});
 				this.keyFrameKeyByTrackId.set(trackId, key);
+				await mediaStore.putReplacing({
+					deviceId,
+					ownerKind: "track",
+					ownerId: trackId,
+					kind: "keyFrameSmall",
+					timestamp,
+					data: keyFrameSmall
+				});
 			} catch (err) {
 				this.ctx.logger.debug("key-frame capture failed", {
 					tags: { deviceId },
@@ -14980,11 +15124,14 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 		if (materializer === null || descriptor === void 0) return;
 		try {
 			const cameraIds = await cache.camerasFor(data.deviceId);
+			if (cameraIds.length === 0) return;
+			const producingDeviceName = await this.resolveProducingDeviceName(data.deviceId);
 			for (const cameraId of cameraIds) await materializer.materialize({
 				cameraId,
 				sourceDeviceId: data.deviceId,
 				kind: descriptor.kind,
-				timestamp
+				timestamp,
+				...producingDeviceName !== void 0 ? { producingDeviceName } : {}
 			});
 		} catch (err) {
 			this.ctx.logger.warn("synthetic sensor-track materialize failed", {
@@ -14996,6 +15143,25 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 			});
 		}
 	}
+	/**
+	* Resolve the NAME of a device (the linked sensor/control that produced a
+	* synthetic event) via the device-manager cap. Best-effort — returns
+	* undefined on any lookup failure or an unknown device so the synthetic
+	* track still materializes without a label.
+	*/
+	async resolveProducingDeviceName(deviceId) {
+		const api = this.ctx?.api;
+		if (!api) return void 0;
+		try {
+			return (await api.deviceManager.getDevice.query({ deviceId }))?.name;
+		} catch (err) {
+			this.ctx?.logger?.debug("resolveProducingDeviceName failed", {
+				tags: { deviceId },
+				meta: { error: errMsg(err) }
+			});
+			return;
+		}
+	}
 	async clearTracks(input) {
 		this.trackStore?.clearDevice(input.deviceId);
 		this.stationaryRegistry?.clearDevice(input.deviceId);
@@ -15511,17 +15677,16 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 				key: clean.key
 			};
 		}
-		const chosenEvent = eventFiles.find((f) => f.kind === "crop") ?? eventFiles.find((f) => f.kind === "fullFrameBoxed") ?? eventFiles[0];
-		if (chosenEvent) return {
-			bytes: Buffer.from(chosenEvent.base64, "base64"),
-			key: chosenEvent.key
-		};
-		const trackFiles = await (this.mediaStore?.listByOwner("track", id) ?? Promise.resolve([]));
-		const chosenTrack = trackFiles.find((f) => f.kind === "thumbnail") ?? trackFiles.find((f) => f.kind === "lastFrame") ?? trackFiles.find((f) => f.kind === "firstFrame") ?? [...trackFiles].reverse().find((f) => f.kind === "snapshot") ?? trackFiles[trackFiles.length - 1];
-		if (!chosenTrack) return null;
+		const chosen = await resolveDefaultEventMedia({
+			eventId: id,
+			eventFiles,
+			listTrackMedia: (trackId) => this.mediaStore?.listByOwner("track", trackId) ?? Promise.resolve([]),
+			getTrackIdForEvent: (eventId) => this.eventStore?.getTrackIdForEvent(eventId) ?? Promise.resolve(null)
+		});
+		if (!chosen) return null;
 		return {
-			bytes: Buffer.from(chosenTrack.base64, "base64"),
-			key: chosenTrack.key
+			bytes: Buffer.from(chosen.base64, "base64"),
+			key: chosen.key
 		};
 	}
 	/**