@camstack/addon-post-analysis 1.2.2 → 1.2.4

package/dist/pipeline-analytics/index.js

@@ -2,7 +2,7 @@ Object.defineProperties(exports, {
 	__esModule: { value: true },
 	[Symbol.toStringTag]: { value: "Module" }
 });
-const require_dist = require("../dist-DSP-cVM0.js");
+const require_dist = require("../dist-Ck79MtSp.js");
 let node_crypto = require("node:crypto");
 let sharp = require("sharp");
 sharp = require_dist.__toESM(sharp);
@@ -3360,6 +3360,24 @@ async function cascadeDeleteTracks(registry, trackStore, trackIds) {
 	for (const trackId of trackIds) await trackStore.deletePersisted(trackId);
 }
 /**
+* Full whole-track cascade for ONE track: events → their media + track media →
+* track row. Delegates to the generalized `cascadeDeleteTracks` so the shipped
+* `deleteTracks` provider path flows through the same engine while preserving
+* the exact legacy call order (event ids stay local to the delete). Adapts the
+* narrow legacy store shapes onto `TrackScopedStore` — a superset store (faces /
+* embeddings) is opted in by the CALLER's registry, not by this legacy shim.
+*/
+async function cascadeDeleteTrack(stores, trackId) {
+	await cascadeDeleteTracks([{ deleteByTracks: async (ids) => {
+		for (const id of ids) {
+			const eventIds = await stores.eventStore.deleteByTrack(id);
+			if (eventIds.length > 0) await stores.mediaStore.deleteForEvents([...eventIds]);
+		}
+	} }, { deleteByTracks: async (ids) => {
+		await stores.mediaStore.deleteForTracks([...ids]);
+	} }], stores.trackStore, [trackId]);
+}
+/**
 * Widened batch whole-track deletion — the ONE engine behind the three §5 entry
 * points. Runs the FULL registry cascade per track (via `cascadeDeleteTracks`
 * with a single-id list so the track root is deleted last), fires cleanup on
@@ -4497,6 +4515,7 @@ var SINGLE_INSTANCE_KINDS = new Set([
 	"keyFrame",
 	"keyFrameSmall",
 	"thumbnail",
+	"thumbnailSmall",
 	"firstFrame",
 	"lastFrame"
 ]);
@@ -6477,6 +6496,106 @@ function squareSafeCropRegionNormalized(bbox, frame, padding) {
 	};
 }
 //#endregion
+//#region src/shared/frame/crop-extractor.ts
+/**
+* Extracts a JPEG-encoded crop from a raw frame buffer using a normalized bounding box.
+* Coordinates are clamped to frame bounds to avoid out-of-range errors.
+*/
+async function extractCrop(frameData, frameWidth, frameHeight, bbox) {
+	const rawLeft = Math.round(bbox.x * frameWidth);
+	const rawTop = Math.round(bbox.y * frameHeight);
+	const rawWidth = Math.round(bbox.w * frameWidth);
+	const rawHeight = Math.round(bbox.h * frameHeight);
+	const left = Math.max(0, Math.min(rawLeft, frameWidth - 1));
+	const top = Math.max(0, Math.min(rawTop, frameHeight - 1));
+	const width = Math.max(1, Math.min(rawWidth, frameWidth - left));
+	const height = Math.max(1, Math.min(rawHeight, frameHeight - top));
+	return {
+		crop: await (0, sharp.default)(frameData, { raw: {
+			width: frameWidth,
+			height: frameHeight,
+			channels: 3
+		} }).extract({
+			left,
+			top,
+			width,
+			height
+		}).jpeg({ quality: 90 }).toBuffer(),
+		width,
+		height
+	};
+}
+//#endregion
+//#region src/shared/frame/square-subject-crop.ts
+/** Expansion factor applied to the bbox long side to frame the subject with a
+*  little breathing room (operator choice: ×1.2). */
+var SQUARE_SUBJECT_CROP_EXPANSION = 1.2;
+/**
+* Compute a SQUARE crop region in PIXEL space around the subject bbox.
+*
+* Algorithm:
+*   1. center: cx = x + w/2, cy = y + h/2
+*   2. side = max(w, h) × SQUARE_SUBJECT_CROP_EXPANSION
+*   3. clamp side to fit the frame: side = min(side, W, H) — a square can never
+*      exceed the frame's SHORT edge (this is the "subject bigger than the
+*      frame's short side" case)
+*   4. center-and-clamp the origin so the square stays fully inside the frame
+*   5. round to integer pixels
+*
+* The returned region fully contains the bbox whenever the bbox itself fits in a
+* square of the frame's short side (always true for real detections).
+*/
+function squareSubjectCropRegion(bbox, frame) {
+	const { W, H } = frame;
+	const cx = bbox.x + bbox.w / 2;
+	const cy = bbox.y + bbox.h / 2;
+	const longerSide = Math.max(bbox.w, bbox.h);
+	const side = Math.min(longerSide * SQUARE_SUBJECT_CROP_EXPANSION, W, H);
+	const rawX0 = cx - side / 2;
+	const rawY0 = cy - side / 2;
+	const x0 = Math.max(0, Math.min(rawX0, W - side));
+	const y0 = Math.max(0, Math.min(rawY0, H - side));
+	return {
+		x: Math.round(x0),
+		y: Math.round(y0),
+		w: Math.round(side),
+		h: Math.round(side)
+	};
+}
+/**
+* The same SQUARE region as {@link squareSubjectCropRegion}, expressed in
+* NORMALIZED [0,1]×[0,1] coordinates. A normalized box maps DIRECTLY onto a
+* native-resolution surface of the SAME aspect ratio, so the region computed
+* from the detection-frame dimensions addresses the exact same ROI on the
+* runner's retained native frame. Reuses the pixel geometry verbatim (single
+* source of truth) and divides by the frame dimensions.
+*/
+function squareSubjectCropRegionNormalized(bbox, frame) {
+	const region = squareSubjectCropRegion(bbox, frame);
+	return {
+		x: region.x / frame.W,
+		y: region.y / frame.H,
+		w: region.w / frame.W,
+		h: region.h / frame.H
+	};
+}
+/**
+* Derive the `thumbnailSmall` JPEG from an already-encoded native subject-crop
+* JPEG. Downscales to at most {@link THUMBNAIL_SMALL_MAX_WIDTH} on the long side
+* (aspect preserved). If the native crop's long side is already ≤ the cap, the
+* ORIGINAL buffer is returned unchanged (store as-is, never upscale, no wasted
+* re-encode).
+*/
+async function deriveThumbnailSmall(nativeJpeg) {
+	const meta = await (0, sharp.default)(nativeJpeg).metadata();
+	const longSide = Math.max(meta.width ?? 0, meta.height ?? 0);
+	if (longSide > 0 && longSide <= 480) return nativeJpeg;
+	return (0, sharp.default)(nativeJpeg).resize(480, 480, {
+		fit: "inside",
+		withoutEnlargement: true
+	}).jpeg({ quality: 88 }).toBuffer();
+}
+//#endregion
 //#region src/shared/frame/box-drawer.ts
 var DEFAULT_COLOR = require_dist.DEFAULT_EVENT_COLOR;
 var DEFAULT_QUALITY = 80;
@@ -6645,7 +6764,8 @@ var EventMediaDispatcher = class {
 		const snapshots = input.snapshots ?? [];
 		const empty = {
 			storedSnapshots: [],
-			thumbnailTrackIds: []
+			thumbnailTrackIds: [],
+			rasterFallbacks: []
 		};
 		if (events.length === 0 && trackFrames.length === 0 && snapshots.length === 0) return empty;
 		let decoded;
@@ -6697,21 +6817,67 @@ var EventMediaDispatcher = class {
 			});
 			return empty;
 		}
+		const rasterFallbacks = await this.collectRasterFallbacks(frameData, fw, fh, trackFrames, snapshots, input.cropPadding, input.rasterFallbackWantedTrackIds);
 		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) {
-			const res = await this.writeTrackSnapshot(deviceId, frameHandle, frameData, fw, fh, sn, input.cropPadding);
+			const res = await this.writeTrackSnapshot(deviceId, frameHandle, frameData, fw, fh, sn);
 			if (res.storedSnapshot) storedSnapshots.push(res.storedSnapshot);
 			if (res.thumbnailWritten) thumbnailTrackIds.push(sn.trackId);
 		}
 		return {
 			storedSnapshots,
-			thumbnailTrackIds
+			thumbnailTrackIds,
+			rasterFallbacks
 		};
 	}
 	/**
+	* Cut ONE clean detection-raster subject crop per WANTED track that has a
+	* target (firstFrame or snapshot) in this frame — the "first available
+	* detection-raster frame" of the zero-media fallback. Cropped from the
+	* already-resolved `frameData` at its REAL resolution via {@link extractCrop}
+	* (extract-only — NEVER upscaled). Deduped per trackId (first target wins).
+	* A per-track encode failure is skipped (logged) — a missing fallback simply
+	* leaves the track with no last-resort preview, never an error.
+	*/
+	async collectRasterFallbacks(frameData, fw, fh, trackFrames, snapshots, cropPadding, wanted) {
+		if (!wanted || wanted.size === 0) return [];
+		const seen = /* @__PURE__ */ new Set();
+		const out = [];
+		const candidates = [...trackFrames.map((t) => ({
+			trackId: t.trackId,
+			timestamp: t.timestamp,
+			bbox: t.bbox
+		})), ...snapshots.map((s) => ({
+			trackId: s.trackId,
+			timestamp: s.timestamp,
+			bbox: s.bbox
+		}))];
+		for (const c of candidates) {
+			if (!wanted.has(c.trackId) || seen.has(c.trackId)) continue;
+			seen.add(c.trackId);
+			try {
+				const { crop } = await extractCrop(frameData, fw, fh, squareSafeCropRegionNormalized(c.bbox, {
+					W: fw,
+					H: fh
+				}, cropPadding));
+				out.push({
+					trackId: c.trackId,
+					timestamp: c.timestamp,
+					jpeg: crop
+				});
+			} catch (err) {
+				this.deps.logger.debug("event media: raster fallback crop failed", { meta: {
+					trackId: c.trackId,
+					error: err instanceof Error ? err.message : String(err)
+				} });
+			}
+		}
+		return out;
+	}
+	/**
 	* Periodic per-track media (§5). The boxed FULL frame is encoded once and
 	* shared by the appended `snapshot` (timeline filmstrip) and the rolling
 	* `lastFrame` (overwrite). The best `thumbnail` is DIFFERENT: a clean
@@ -6723,7 +6889,7 @@ var EventMediaDispatcher = class {
 	* failed). `thumbnailWritten` reports whether a best `thumbnail` actually
 	* landed this frame (#27-A) so the caller can stop forcing retries.
 	*/
-	async writeTrackSnapshot(deviceId, frameHandle, frameData, fw, fh, sn, cropPadding) {
+	async writeTrackSnapshot(deviceId, frameHandle, frameData, fw, fh, sn) {
 		if (!sn.appendSnapshot && !sn.rollingLastFrame && !sn.bestThumbnail) return {
 			storedSnapshot: null,
 			thumbnailWritten: false
@@ -6750,8 +6916,11 @@ var EventMediaDispatcher = class {
 		if (sn.rollingLastFrame && boxed) await this.replaceKind(deviceId, sn.trackId, "lastFrame", sn.timestamp, boxed);
 		let thumbnailWritten = false;
 		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);
+			const variants = await this.cropSubjectVariants(frameHandle, fw, fh, sn.bbox);
+			if (variants) {
+				thumbnailWritten = await this.replaceKind(deviceId, sn.trackId, "thumbnail", sn.timestamp, variants.thumbnail);
+				await this.replaceKind(deviceId, sn.trackId, "thumbnailSmall", sn.timestamp, variants.thumbnailSmall);
+			}
 		}
 		return {
 			storedSnapshot: stored,
@@ -6801,6 +6970,54 @@ var EventMediaDispatcher = class {
 		}
 	}
 	/**
+	* The best-shot subject crop as its TWO persisted variants (best-crop
+	* fast-load, 2026-07-21). ONE native fetch: the SQUARE-framed subject ROI
+	* (side = max(w,h)×1.2, clamped to the frame — {@link squareSubjectCropRegionNormalized})
+	* is requested from the runner's retained native surface with NO `maxWidth`
+	* (uncapped TRUE native, decision #3) → the `thumbnail`. The `thumbnailSmall`
+	* is DERIVED by downscaling that SAME JPEG to the 480 long-side cap — never a
+	* second `getNativeCropJpeg`, never upscaled ({@link deriveThumbnailSmall}
+	* returns the native buffer as-is when it is already ≤ 480).
+	*
+	* NATIVE-OR-NOTHING: any miss/error (or a runner without the method) returns
+	* `null` after a loud `logger.warn`; the caller SKIPS the write and the
+	* per-frame retry lands a real native crop later. Never a local resize
+	* upscale of a ≤640 tile (a blurred lie).
+	*/
+	async cropSubjectVariants(frameHandle, fw, fh, bbox) {
+		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 = squareSubjectCropRegionNormalized(bbox, {
+				W: fw,
+				H: fh
+			});
+			const native = await this.deps.getNativeCropJpeg(frameHandle, norm);
+			if (!native) {
+				this.deps.logger.warn("native subject crop miss — will retry, no upscale", { meta: {
+					shmId: frameHandle.shmId,
+					reason: "native-miss"
+				} });
+				return null;
+			}
+			return {
+				thumbnail: native,
+				thumbnailSmall: await deriveThumbnailSmall(native)
+			};
+		} catch (err) {
+			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;
+		}
+	}
+	/**
 	* 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
@@ -6927,36 +7144,6 @@ var EventMediaDispatcher = class {
 	}
 };
 //#endregion
-//#region src/shared/frame/crop-extractor.ts
-/**
-* Extracts a JPEG-encoded crop from a raw frame buffer using a normalized bounding box.
-* Coordinates are clamped to frame bounds to avoid out-of-range errors.
-*/
-async function extractCrop(frameData, frameWidth, frameHeight, bbox) {
-	const rawLeft = Math.round(bbox.x * frameWidth);
-	const rawTop = Math.round(bbox.y * frameHeight);
-	const rawWidth = Math.round(bbox.w * frameWidth);
-	const rawHeight = Math.round(bbox.h * frameHeight);
-	const left = Math.max(0, Math.min(rawLeft, frameWidth - 1));
-	const top = Math.max(0, Math.min(rawTop, frameHeight - 1));
-	const width = Math.max(1, Math.min(rawWidth, frameWidth - left));
-	const height = Math.max(1, Math.min(rawHeight, frameHeight - top));
-	return {
-		crop: await (0, sharp.default)(frameData, { raw: {
-			width: frameWidth,
-			height: frameHeight,
-			channels: 3
-		} }).extract({
-			left,
-			top,
-			width,
-			height
-		}).jpeg({ quality: 90 }).toBuffer(),
-		width,
-		height
-	};
-}
-//#endregion
 //#region src/pipeline-analytics/embedding/embedding-dispatcher.ts
 function selectCropBbox(detection) {
 	return detection.refinedBbox ?? detection.bbox;
@@ -8745,6 +8932,16 @@ function planPeriodicMedia(input) {
 		bestThumbnail: input.isNewBest || !thumbnailLanded
 	};
 }
+var DEFAULT_ZERO_MEDIA_POLICY_CONFIG = { suppressMaxDurationMs: 1e3 };
+/**
+* Classify a closing track's persistence outcome. Pure — see the module header
+* for the full contract.
+*/
+function decideZeroMediaPolicy(input, config = DEFAULT_ZERO_MEDIA_POLICY_CONFIG) {
+	if (input.hasMedia) return "persist";
+	if (input.durationMs < config.suppressMaxDurationMs && !input.confirmed) return "suppress";
+	return input.hasRasterFallback ? "raster-fallback" : "persist";
+}
 //#endregion
 //#region src/pipeline-analytics/best-thumbnail-guard.ts
 /**
@@ -11997,10 +12194,28 @@ 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. */
+*  KeyEvent path uses: `thumbnailSmall` (480 fast-load) → 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];
+	return files.find((f) => f.kind === "thumbnailSmall") ?? 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];
+}
+/**
+* Crop-forced resolution (the `?kind=crop` reel/timeline path). Prefer a CLEAN
+* (never-boxed) frame via the injected `pickClean`; when the track owns NO clean
+* frame at all — the regression class created by retiring `crop`/`fullFrame`
+* production (2026-07-21), leaving degenerate tracks with only boxed
+* `lastFrame`/`snapshot`/`firstFrame` — degrade to ANY track media rather than
+* returning undefined. A boxed frame (with the target's box drawn) is a real
+* preview; an empty tile is not. Clean is always tried FIRST so the common case
+* still serves an unboxed tile. Undefined only when the owner has NO media.
+*
+* `pickClean` is injected because the clean-kind picker (`pickCleanMedia`) lives
+* in the addon `index.ts` over the concrete `MediaFileKind` set; this keeps the
+* composition pure + unit-testable here.
+*/
+function resolveCropForcedMedia(files, pickClean) {
+	return pickClean(files) ?? pickTrackFallbackMedia(files);
 }
 /**
 * Resolve the default-path media for an event id: the event's own media when it
@@ -12358,6 +12573,14 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 	*  area) + emit time, so a material improvement is measured against the
 	*  last emit and debounced. Seeded at `start`, dropped at `end`. */
 	trackLifecycleUpdateMem = /* @__PURE__ */ new Map();
+	/** Per-active-track close-policy state (spec §"Zero-media track policy"):
+	*  whether the track ever reached the tracker's hit-confirmation
+	*  (`trackAge >= minHits`) and the FIRST retained detection-raster subject
+	*  crop. Both are read ONLY at close (`sweepExpiredTracks`) to decide
+	*  suppress / raster-fallback / persist for a track that ends with no media.
+	*  `deviceId` lets `clearDevice` prune without an active-track lookup. Dropped
+	*  on every teardown path. */
+	trackClosureState = /* @__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
@@ -12416,7 +12639,7 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 		let storage = this.ctx.kernel.storage;
 		const mediaRoot = process.env.CAMSTACK_MEDIA_ROOT?.trim();
 		if (mediaRoot) {
-			const { FilesystemStorageProvider } = await Promise.resolve().then(() => require("../node-DtSEvIXU.js"));
+			const { FilesystemStorageProvider } = await Promise.resolve().then(() => require("../node-C4bKtLou.js"));
 			storage = new FilesystemStorageProvider(mediaRoot);
 			logger.info("pipeline-analytics: event media rooted at CAMSTACK_MEDIA_ROOT", { meta: { mediaRoot } });
 		}
@@ -12849,6 +13072,7 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 			this.bindingCache?.onBindingsChanged(data);
 			if (data.capName === "pipeline-analytics" && data.reason === "wrapper-deactivated") {
 				this.trackStore?.clearDevice(data.deviceId);
+				this.clearClosureStateForDevice(data.deviceId);
 				this.stationaryRegistry?.forgetDevice(data.deviceId);
 				this.overlayState.clearDevice(data.deviceId);
 				this.overlaySynthesisWarnAt.delete(data.deviceId);
@@ -12867,6 +13091,7 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 		this.unsubDeviceUnreg = this.ctx.eventBus.subscribe({ category: require_dist.EventCategory.DeviceUnregistered }, (ev) => {
 			const { deviceId } = ev.data;
 			this.trackStore?.clearDevice(deviceId);
+			this.clearClosureStateForDevice(deviceId);
 			this.stationaryRegistry?.forgetDevice(deviceId);
 			this.overlayState.clearDevice(deviceId);
 			this.overlaySynthesisWarnAt.delete(deviceId);
@@ -13222,6 +13447,7 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 		this.thumbnailInFlight.clear();
 		this.keyFrameInFlight.clear();
 		this.trackLifecycleUpdateMem.clear();
+		this.trackClosureState.clear();
 		this.objectEmbeddingBestSelector.clear();
 		this.levelStateByDevice.clear();
 		this.settingsCacheByDevice.clear();
@@ -13340,6 +13566,10 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 			});
 			positionsCountById.set(t.trackId, upserted.positions.length);
 		}
+		if (result.rawTrackedDetections.length > 0) {
+			const { minHits } = await this.resolveDeviceDetectionSensitivitySettings(deviceId);
+			for (const rt of result.rawTrackedDetections) if (rt.trackAge >= minHits) this.markTrackConfirmed(deviceId, rt.trackId);
+		}
 		const log = this.ctx.logger.withTags({ deviceId });
 		const prevIds = this.lastActiveTrackIds.get(key) ?? /* @__PURE__ */ new Set();
 		const firstFrameTargets = [];
@@ -13392,6 +13622,7 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 					...t.label ? { label: t.label } : {}
 				});
 				this.trackStore.seedSnapshotClock(id, result.timestamp, t.bbox);
+				this.lastFrameAtByTrack.set(id, result.timestamp);
 			}
 			this.ctx.eventBus.emit({
 				id: `pa-${(0, node_crypto.randomUUID)()}`,
@@ -13563,14 +13794,25 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 				} });
 				const thumbInFlightTrackIds = snapshotTargets.filter((t) => t.bestThumbnail).map((t) => t.trackId);
 				for (const trackId of thumbInFlightTrackIds) this.thumbnailInFlight.add(trackId);
+				const rasterFallbackWantedTrackIds = /* @__PURE__ */ new Set();
+				for (const t of firstFrameTargets) if (!this.trackClosureState.get(t.trackId)?.rasterFallback) rasterFallbackWantedTrackIds.add(t.trackId);
+				for (const s of snapshotTargets) if (!this.trackClosureState.get(s.trackId)?.rasterFallback) rasterFallbackWantedTrackIds.add(s.trackId);
 				this.eventMediaDispatcher.captureForFrame({
 					deviceId,
 					frameHandle,
 					events: eventTargets,
 					trackFrames: firstFrameTargets,
 					snapshots: snapshotTargets,
-					cropPadding: mediaSettings.cropPadding
+					cropPadding: mediaSettings.cropPadding,
+					rasterFallbackWantedTrackIds
 				}).then((res) => {
+					for (const rf of res.rasterFallbacks) {
+						const st = this.ensureTrackClosureState(deviceId, rf.trackId);
+						if (!st.rasterFallback) st.rasterFallback = {
+							jpeg: rf.jpeg,
+							timestamp: rf.timestamp
+						};
+					}
 					for (const s of res.storedSnapshots) this.trackStore?.addSnapshot(s.trackId, {
 						timestamp: s.timestamp,
 						position: {
@@ -14581,6 +14823,44 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 			const expired = await this.trackStore.expireStale(Date.now());
 			for (const t of expired) {
 				const duration = t.lastSeen - t.firstSeen;
+				const closure = this.trackClosureState.get(t.trackId);
+				const outcome = decideZeroMediaPolicy({
+					durationMs: duration,
+					hasMedia: (await this.mediaStore?.listByOwner("track", t.trackId) ?? []).length > 0,
+					confirmed: closure?.confirmed ?? false,
+					hasRasterFallback: closure?.rasterFallback !== void 0
+				});
+				if (outcome === "suppress") {
+					this.ctx.logger.info("track suppressed (zero-media false birth)", {
+						tags: { deviceId: t.deviceId },
+						meta: {
+							trackId: t.trackId,
+							className: t.className,
+							durationMs: duration,
+							positions: t.positions.length
+						}
+					});
+					await this.suppressZeroMediaTrack(t.deviceId, t.trackId);
+					continue;
+				}
+				if (outcome === "raster-fallback" && closure?.rasterFallback) try {
+					await this.mediaStore?.put({
+						deviceId: t.deviceId,
+						ownerKind: "track",
+						ownerId: t.trackId,
+						kind: "thumbnail",
+						timestamp: closure.rasterFallback.timestamp,
+						data: closure.rasterFallback.jpeg
+					});
+				} catch (err) {
+					this.ctx.logger.debug("zero-media raster fallback put failed", {
+						tags: { deviceId: t.deviceId },
+						meta: {
+							trackId: t.trackId,
+							error: String(err)
+						}
+					});
+				}
 				this.ctx.logger.info("track ended", {
 					tags: { deviceId: t.deviceId },
 					meta: {
@@ -14691,12 +14971,53 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 				});
 				this.emitTrackLifecycle(endPayload, t.lastSeen);
 				this.trackLifecycleUpdateMem.delete(t.trackId);
+				this.trackClosureState.delete(t.trackId);
 			}
 		} catch (err) {
 			if (this.shuttingDown) return;
 			this.ctx.logger.debug("sweepExpiredTracks failed", { meta: { error: String(err) } });
 		}
 	}
+	/**
+	* Undo a zero-media false-birth track (spec §"Zero-media track policy"): tear
+	* down its live per-track state (mirroring the natural end MINUS importance
+	* scoring + the lifecycle `end`/`TrackEnded` events) and cascade-delete the
+	* just-persisted row + any events/media so nothing dangles. Best-effort.
+	*/
+	async suppressZeroMediaTrack(deviceId, trackId) {
+		const faceEnd = this.faceRecognizer?.onTrackEnd(deviceId, trackId);
+		const dropKeyFrame = () => {
+			this.keyFrameKeyByTrackId.delete(trackId);
+		};
+		if (faceEnd) faceEnd.finally(dropKeyFrame);
+		else dropKeyFrame();
+		this.plateRecognizer?.onTrackEnd(deviceId, trackId);
+		this.bestFrameTracker.delete(trackId);
+		this.objectEmbeddingBestSelector.delete(trackId);
+		this.lastFrameAtByTrack.delete(trackId);
+		this.thumbnailLandedTracks.delete(trackId);
+		this.thumbnailInFlight.delete(trackId);
+		this.keyFrameInFlight.delete(trackId);
+		this.detailDispatcher?.onTrackEnded(deviceId, trackId);
+		this.overlayState.onTrackEnded(deviceId, trackId);
+		this.trackLifecycleUpdateMem.delete(trackId);
+		this.trackClosureState.delete(trackId);
+		if (this.eventStore && this.mediaStore && this.trackStore) try {
+			await cascadeDeleteTrack({
+				eventStore: this.eventStore,
+				mediaStore: this.mediaStore,
+				trackStore: this.trackStore
+			}, trackId);
+		} catch (err) {
+			this.ctx.logger.debug("zero-media suppression cascade failed", {
+				tags: { deviceId },
+				meta: {
+					trackId,
+					error: String(err)
+				}
+			});
+		}
+	}
 	async sweepRetention() {
 		if (this.shuttingDown || !this.eventStore || !this.mediaStore) return;
 		const now = Date.now();
@@ -14906,6 +15227,7 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 		this.thumbnailInFlight.delete(track.trackId);
 		this.keyFrameInFlight.delete(track.trackId);
 		this.trackLifecycleUpdateMem.delete(track.trackId);
+		this.trackClosureState.delete(track.trackId);
 		this.detailDispatcher?.onTrackEnded(deviceId, track.trackId);
 		this.overlayState.onTrackEnded(deviceId, track.trackId);
 		this.lastActiveTrackIds.get(key)?.delete(track.trackId);
@@ -15204,6 +15526,7 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 	}
 	async clearTracks(input) {
 		this.trackStore?.clearDevice(input.deviceId);
+		this.clearClosureStateForDevice(input.deviceId);
 		this.stationaryRegistry?.clearDevice(input.deviceId);
 		this.overlayState.clearDevice(input.deviceId);
 		this.overlaySynthesisWarnAt.delete(input.deviceId);
@@ -15416,6 +15739,27 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 	clearLiveTrackState(deviceId, trackId) {
 		this.detailDispatcher?.onTrackEnded(deviceId, trackId);
 		this.overlayState.onTrackEnded(deviceId, trackId);
+		this.trackClosureState.delete(trackId);
+	}
+	/** Lazily create + return a track's close-policy state (zero-media policy). */
+	ensureTrackClosureState(deviceId, trackId) {
+		let st = this.trackClosureState.get(trackId);
+		if (!st) {
+			st = {
+				deviceId,
+				confirmed: false
+			};
+			this.trackClosureState.set(trackId, st);
+		}
+		return st;
+	}
+	/** Sticky-mark a track as confirmed once it reaches the tracker's hit gate. */
+	markTrackConfirmed(deviceId, trackId) {
+		this.ensureTrackClosureState(deviceId, trackId).confirmed = true;
+	}
+	/** Drop every close-policy entry for a device (mirrors `trackStore.clearDevice`). */
+	clearClosureStateForDevice(deviceId) {
+		for (const [trackId, st] of this.trackClosureState) if (st.deviceId === deviceId) this.trackClosureState.delete(trackId);
 	}
 	async deleteTracks(input) {
 		const cascade = this.buildTrackCascadeRegistry();
@@ -15710,11 +16054,11 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 		const eventFiles = await (this.mediaStore?.listByOwner("event", id) ?? Promise.resolve([]));
 		if (preferKind !== void 0 && preferKind.length > 0) {
 			const trackFiles = await (this.mediaStore?.listByOwner("track", id) ?? Promise.resolve([]));
-			const clean = pickCleanMedia([...eventFiles, ...trackFiles], preferKind);
-			if (!clean) return null;
+			const chosen = resolveCropForcedMedia([...eventFiles, ...trackFiles], (files) => pickCleanMedia(files, preferKind));
+			if (!chosen) return null;
 			return {
-				bytes: Buffer.from(clean.base64, "base64"),
-				key: clean.key
+				bytes: Buffer.from(chosen.base64, "base64"),
+				key: chosen.key
 			};
 		}
 		const chosen = await resolveDefaultEventMedia({