@camstack/addon-post-analysis 1.2.3 → 1.2.4

package/dist/pipeline-analytics/{_virtual_mf-localSharedImportMap___mfe_internal__addon_pipeline_analytics_widgets-C4dWm6ZL.mjs → _virtual_mf-localSharedImportMap___mfe_internal__addon_pipeline_analytics_widgets-ChHurWQz.mjs}

@@ -3,7 +3,7 @@ import "./dist-CYZr2fwk.mjs";
 var e = {
 	"@camstack/sdk": {
 		name: "@camstack/sdk",
-		version: "1.2.3",
+		version: "1.2.4",
 		scope: ["default"],
 		loaded: !1,
 		from: "addon_pipeline_analytics_widgets",
@@ -18,7 +18,7 @@ var e = {
 	},
 	"@camstack/types": {
 		name: "@camstack/types",
-		version: "1.2.3",
+		version: "1.2.4",
 		scope: ["default"],
 		loaded: !1,
 		from: "addon_pipeline_analytics_widgets",
@@ -33,7 +33,7 @@ var e = {
 	},
 	"@camstack/ui-library": {
 		name: "@camstack/ui-library",
-		version: "1.2.3",
+		version: "1.2.4",
 		scope: ["default"],
 		loaded: !1,
 		from: "addon_pipeline_analytics_widgets",

package/dist/pipeline-analytics/{hostInit-3T15bdHA.mjs → hostInit-DQbbiJYs.mjs}

@@ -36,7 +36,7 @@ async function r() {
 				}
 			},
 			"@camstack/types": {
-				version: "1.2.3",
+				version: "1.2.4",
 				scope: "default",
 				shareConfig: {
 					singleton: !0,
@@ -45,7 +45,7 @@ async function r() {
 				}
 			},
 			"@camstack/sdk": {
-				version: "1.2.3",
+				version: "1.2.4",
 				scope: "default",
 				shareConfig: {
 					singleton: !0,
@@ -81,7 +81,7 @@ async function r() {
 				}
 			},
 			"@camstack/ui-library": {
-				version: "1.2.3",
+				version: "1.2.4",
 				scope: "default",
 				shareConfig: {
 					singleton: !0,

package/dist/pipeline-analytics/index.js

@@ -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
@@ -6478,6 +6496,36 @@ 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). */
@@ -6716,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;
@@ -6768,6 +6817,7 @@ 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 = [];
@@ -6779,10 +6829,55 @@ var EventMediaDispatcher = class {
 		}
 		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
@@ -7049,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;
@@ -8867,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
 /**
@@ -12126,6 +12201,23 @@ function pickTrackFallbackMedia(files) {
 	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
 * has any, else the owning track's fallback media. Returns `null` when neither
 * yields a blob (caller 404s → the surface shows an icon).
@@ -12481,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
@@ -12972,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);
@@ -12990,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);
@@ -13345,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();
@@ -13463,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 = [];
@@ -13515,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)()}`,
@@ -13686,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: {
@@ -14704,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: {
@@ -14814,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();
@@ -15029,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);
@@ -15327,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);
@@ -15539,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();
@@ -15833,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({

package/dist/pipeline-analytics/index.mjs

@@ -3355,6 +3355,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
@@ -6473,6 +6491,36 @@ 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 sharp(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). */
@@ -6711,7 +6759,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;
@@ -6763,6 +6812,7 @@ 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 = [];
@@ -6774,10 +6824,55 @@ var EventMediaDispatcher = class {
 		}
 		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
@@ -7044,36 +7139,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 sharp(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;
@@ -8862,6 +8927,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
 /**
@@ -12121,6 +12196,23 @@ function pickTrackFallbackMedia(files) {
 	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
 * has any, else the owning track's fallback media. Returns `null` when neither
 * yields a blob (caller 404s → the surface shows an icon).
@@ -12476,6 +12568,14 @@ var PipelineAnalyticsAddon = class extends 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
@@ -12967,6 +13067,7 @@ var PipelineAnalyticsAddon = class extends 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);
@@ -12985,6 +13086,7 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 		this.unsubDeviceUnreg = this.ctx.eventBus.subscribe({ category: 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);
@@ -13340,6 +13442,7 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 		this.thumbnailInFlight.clear();
 		this.keyFrameInFlight.clear();
 		this.trackLifecycleUpdateMem.clear();
+		this.trackClosureState.clear();
 		this.objectEmbeddingBestSelector.clear();
 		this.levelStateByDevice.clear();
 		this.settingsCacheByDevice.clear();
@@ -13458,6 +13561,10 @@ var PipelineAnalyticsAddon = class extends 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 = [];
@@ -13510,6 +13617,7 @@ var PipelineAnalyticsAddon = class extends 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-${randomUUID()}`,
@@ -13681,14 +13789,25 @@ var PipelineAnalyticsAddon = class extends 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: {
@@ -14699,6 +14818,44 @@ var PipelineAnalyticsAddon = class extends 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: {
@@ -14809,12 +14966,53 @@ var PipelineAnalyticsAddon = class extends 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();
@@ -15024,6 +15222,7 @@ var PipelineAnalyticsAddon = class extends 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);
@@ -15322,6 +15521,7 @@ var PipelineAnalyticsAddon = class extends 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);
@@ -15534,6 +15734,27 @@ var PipelineAnalyticsAddon = class extends 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();
@@ -15828,11 +16049,11 @@ var PipelineAnalyticsAddon = class extends 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({

package/dist/pipeline-analytics/remoteEntry.js

@@ -30,7 +30,7 @@ async function d(e) {
 	}
 }
 async function f() {
-	return l ||= d(() => import("./_virtual_mf-localSharedImportMap___mfe_internal__addon_pipeline_analytics_widgets-C4dWm6ZL.mjs")).catch((e) => {
+	return l ||= d(() => import("./_virtual_mf-localSharedImportMap___mfe_internal__addon_pipeline_analytics_widgets-ChHurWQz.mjs")).catch((e) => {
 		throw l = void 0, e;
 	}), l;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/addon-post-analysis",
-  "version": "1.2.3",
+  "version": "1.2.4",
   "description": "CamStack Post-Analysis bundle — enrichment, embedding-encoder, pipeline-analytics. Multi-entry npm package shipping addons that consume pipeline output.",
   "keywords": [
     "camstack",