@camstack/addon-post-analysis 1.2.3 → 1.2.5

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-Ck79MtSp.js");
+const require_dist = require("../dist-Dlb4YrCt.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
@@ -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,9 +6764,13 @@ var EventMediaDispatcher = class {
 		const snapshots = input.snapshots ?? [];
 		const empty = {
 			storedSnapshots: [],
-			thumbnailTrackIds: []
+			thumbnailTrackIds: [],
+			firstFrameTrackIds: [],
+			lastFrameTrackIds: [],
+			rasterFallbacks: []
 		};
-		if (events.length === 0 && trackFrames.length === 0 && snapshots.length === 0) return empty;
+		const extraCandidateCount = input.rasterFallbackCandidates?.length ?? 0;
+		if (events.length === 0 && trackFrames.length === 0 && snapshots.length === 0 && extraCandidateCount === 0) return empty;
 		let decoded;
 		try {
 			decoded = await resolveFrame(frameHandle, { getRemoteFrame: this.deps.getRemoteFrame });
@@ -6768,21 +6820,82 @@ var EventMediaDispatcher = class {
 			});
 			return empty;
 		}
+		const rasterFallbacks = await this.collectRasterFallbacks(frameData, fw, fh, trackFrames, snapshots, input.cropPadding, input.rasterFallbackWantedTrackIds, input.rasterFallbackCandidates);
 		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 firstFrameTrackIds = [];
+		for (const tf of trackFrames) if (await this.writeTrackFrame(deviceId, frameHandle, frameData, fw, fh, tf)) firstFrameTrackIds.push(tf.trackId);
 		const storedSnapshots = [];
 		const thumbnailTrackIds = [];
+		const lastFrameTrackIds = [];
 		for (const sn of snapshots) {
 			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);
+			if (res.lastFrameWritten) lastFrameTrackIds.push(sn.trackId);
 		}
 		return {
 			storedSnapshots,
-			thumbnailTrackIds
+			thumbnailTrackIds,
+			firstFrameTrackIds,
+			lastFrameTrackIds,
+			rasterFallbacks
 		};
 	}
 	/**
+	* Cut ONE clean detection-raster subject crop per WANTED track observed this
+	* frame — the "first available detection-raster frame" of the zero-media
+	* fallback. Candidate bboxes come from this frame's firstFrame/snapshot targets
+	* AND (widened) the explicit `extraCandidates` (confirmed tracks with no such
+	* target). Cropped from the already-resolved `frameData` at its REAL resolution
+	* via {@link extractCrop} (extract-only — NEVER upscaled). Deduped per trackId
+	* (first candidate wins; target-derived candidates precede the extras). 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, extraCandidates) {
+		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
+			})),
+			...(extraCandidates ?? []).map((c) => ({
+				trackId: c.trackId,
+				timestamp: c.timestamp,
+				bbox: c.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
@@ -6793,11 +6906,15 @@ var EventMediaDispatcher = class {
 	* TrackStore wiring (null when `appendSnapshot` is false or the encode
 	* failed). `thumbnailWritten` reports whether a best `thumbnail` actually
 	* landed this frame (#27-A) so the caller can stop forcing retries.
+	* `lastFrameWritten` reports whether the rolling `lastFrame` actually landed
+	* (DEFECT B) so the caller advances its `lastFrameAt` clock ONLY on a real
+	* write — a dropped roll leaves the clock put and retries next frame.
 	*/
 	async writeTrackSnapshot(deviceId, frameHandle, frameData, fw, fh, sn) {
 		if (!sn.appendSnapshot && !sn.rollingLastFrame && !sn.bestThumbnail) return {
 			storedSnapshot: null,
-			thumbnailWritten: false
+			thumbnailWritten: false,
+			lastFrameWritten: false
 		};
 		let boxed = null;
 		if (sn.appendSnapshot || sn.rollingLastFrame) boxed = await this.boxedTimelineFrame(deviceId, frameHandle, frameData, fw, fh, sn.trackId, sn.bbox, sn.label);
@@ -6818,7 +6935,8 @@ var EventMediaDispatcher = class {
 				bbox: sn.bbox
 			};
 		} catch {}
-		if (sn.rollingLastFrame && boxed) await this.replaceKind(deviceId, sn.trackId, "lastFrame", sn.timestamp, boxed);
+		let lastFrameWritten = false;
+		if (sn.rollingLastFrame && boxed) lastFrameWritten = await this.replaceKind(deviceId, sn.trackId, "lastFrame", sn.timestamp, boxed);
 		let thumbnailWritten = false;
 		if (sn.bestThumbnail) {
 			const variants = await this.cropSubjectVariants(frameHandle, fw, fh, sn.bbox);
@@ -6829,7 +6947,8 @@ var EventMediaDispatcher = class {
 		}
 		return {
 			storedSnapshot: stored,
-			thumbnailWritten
+			thumbnailWritten,
+			lastFrameWritten
 		};
 	}
 	/**
@@ -7026,7 +7145,7 @@ var EventMediaDispatcher = class {
 	}
 	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;
+		if (!boxed) return false;
 		try {
 			await this.deps.mediaStore.put({
 				deviceId,
@@ -7036,6 +7155,7 @@ var EventMediaDispatcher = class {
 				timestamp: tf.timestamp,
 				data: boxed
 			});
+			return true;
 		} catch (err) {
 			this.deps.logger.warn("event media: track frame failed", {
 				tags: { deviceId },
@@ -7045,40 +7165,11 @@ var EventMediaDispatcher = class {
 					error: err instanceof Error ? err.message : String(err)
 				}
 			});
+			return false;
 		}
 	}
 };
 //#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 +8958,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 +12227,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).
@@ -12457,6 +12575,32 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 	*  where no `snapshot` is appended, so it is never byte-identical to a stored
 	*  `snapshot` (kills the end-of-track duplicate). Cleared on track end. */
 	lastFrameAtByTrack = /* @__PURE__ */ new Map();
+	/** Tracks with a rolling-`lastFrame` capture CURRENTLY in flight (RC-1,
+	*  DEFECT B). The `lastFrameAt` clock now advances ONLY when the write lands
+	*  (dispatcher completion), not synchronously at plan time — so a dropped roll
+	*  (recycled/blank frame) leaves the clock put and re-rolls next frame. Without
+	*  an in-flight guard that re-roll would fire EVERY frame while the first
+	*  capture is still resolving (0.1–3s under the native path), stacking N
+	*  overlapping captures. While a track sits here `buildSnapshotTargets`
+	*  suppresses a new rolling-`lastFrame` request; the pending dispatch clears it
+	*  (and, if it landed, advances `lastFrameAtByTrack`). Cleared on track end +
+	*  reset. */
+	lastFrameInFlight = /* @__PURE__ */ new Set();
+	/** Confirmed-birth tracks whose `firstFrame` has NOT yet actually persisted
+	*  (DEFECT A). Seeded on a confirmed birth (alongside the birth firstFrame
+	*  target) and removed the moment the write lands. While a track sits here and
+	*  is matched this frame, `collectFirstFrameRetries` re-schedules a firstFrame
+	*  target so a birth capture dropped by a recycled/blank live frame is retried
+	*  on a later frame (earliest available view still beats none). Scoped to
+	*  confirmed births ONLY — a suppressed false-positive birth or resurrection
+	*  never enters, so it never gets a retro firstFrame. Cleared on track end +
+	*  reset. */
+	firstFramePendingTracks = /* @__PURE__ */ new Set();
+	/** Tracks with a `firstFrame` capture CURRENTLY in flight (RC-1, DEFECT A).
+	*  Mirrors `thumbnailInFlight`: while a firstFrame capture is resolving the
+	*  per-frame retry is suppressed so at most one capture is outstanding per
+	*  track. Cleared on dispatch settle (+ track end / reset). */
+	firstFrameInFlight = /* @__PURE__ */ new Set();
 	/** Track ids whose best `thumbnail` has ACTUALLY been persisted (#27-A). A
 	*  track absent here keeps forcing a best-thumbnail capture every frame until
 	*  one lands, so a short / high-churn track whose first capture was dropped
@@ -12481,6 +12625,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
@@ -12539,7 +12691,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-C4bKtLou.js"));
+			const { FilesystemStorageProvider } = await Promise.resolve().then(() => require("../node-DWX3J7jh.js"));
 			storage = new FilesystemStorageProvider(mediaRoot);
 			logger.info("pipeline-analytics: event media rooted at CAMSTACK_MEDIA_ROOT", { meta: { mediaRoot } });
 		}
@@ -12972,6 +13124,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 +13143,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);
@@ -13341,10 +13495,14 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 		this.dropoutSkipsByKey.clear();
 		this.bestFrameTracker.clear();
 		this.lastFrameAtByTrack.clear();
+		this.lastFrameInFlight.clear();
+		this.firstFramePendingTracks.clear();
+		this.firstFrameInFlight.clear();
 		this.thumbnailLandedTracks.clear();
 		this.thumbnailInFlight.clear();
 		this.keyFrameInFlight.clear();
 		this.trackLifecycleUpdateMem.clear();
+		this.trackClosureState.clear();
 		this.objectEmbeddingBestSelector.clear();
 		this.levelStateByDevice.clear();
 		this.settingsCacheByDevice.clear();
@@ -13463,6 +13621,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 = [];
@@ -13507,14 +13669,16 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 				className: t.className,
 				source
 			} });
-			if (this.eventMediaDispatcher && frameHandle) {
-				firstFrameTargets.push({
+			if (this.eventMediaDispatcher) {
+				this.firstFramePendingTracks.add(id);
+				this.trackStore.seedSnapshotClock(id, result.timestamp, t.bbox);
+				this.lastFrameAtByTrack.set(id, result.timestamp);
+				if (frameHandle) firstFrameTargets.push({
 					trackId: id,
 					timestamp: result.timestamp,
 					bbox: { ...t.bbox },
 					...t.label ? { label: t.label } : {}
 				});
-				this.trackStore.seedSnapshotClock(id, result.timestamp, t.bbox);
 			}
 			this.ctx.eventBus.emit({
 				id: `pa-${(0, node_crypto.randomUUID)()}`,
@@ -13663,6 +13827,7 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 			for (const crops of childCropsByEvent.values()) for (const c of crops) if (c.kind === "faceCrop") faceCrops += 1;
 			else plateCrops += 1;
 			const snapshotTargets = this.buildSnapshotTargets(deviceId, result.tracked, result.timestamp, mediaSettings, result.frameWidth, result.frameHeight);
+			for (const retry of this.collectFirstFrameRetries(result.tracked, result.timestamp, firstFrameTargets)) firstFrameTargets.push(retry);
 			const keyFrameTrackIds = selectKeyFrameTrackIds(snapshotTargets);
 			if (keyFrameTrackIds.length > 0) this.persistKeyFrames(deviceId, result.timestamp, keyFrameTrackIds, frameHandle);
 			if (eventTargets.length > 0 || firstFrameTargets.length > 0 || snapshotTargets.length > 0) {
@@ -13686,14 +13851,46 @@ 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 firstFrameInFlightTrackIds = firstFrameTargets.map((t) => t.trackId);
+				for (const trackId of firstFrameInFlightTrackIds) this.firstFrameInFlight.add(trackId);
+				const lastFrameInFlightTrackIds = snapshotTargets.filter((t) => t.rollingLastFrame).map((t) => t.trackId);
+				for (const trackId of lastFrameInFlightTrackIds) this.lastFrameInFlight.add(trackId);
+				const dispatchTimestamp = result.timestamp;
+				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);
+				const targetedThisFrame = new Set([...firstFrameTargets.map((t) => t.trackId), ...snapshotTargets.map((s) => s.trackId)]);
+				const rasterFallbackCandidates = [];
+				for (const t of result.tracked) {
+					if (t.matchedThisFrame === false) continue;
+					const closure = this.trackClosureState.get(t.trackId);
+					if (!closure?.confirmed) continue;
+					if (closure.rasterFallback) continue;
+					if (targetedThisFrame.has(t.trackId)) continue;
+					rasterFallbackWantedTrackIds.add(t.trackId);
+					rasterFallbackCandidates.push({
+						trackId: t.trackId,
+						timestamp: result.timestamp,
+						bbox: { ...t.bbox }
+					});
+				}
 				this.eventMediaDispatcher.captureForFrame({
 					deviceId,
 					frameHandle,
 					events: eventTargets,
 					trackFrames: firstFrameTargets,
 					snapshots: snapshotTargets,
-					cropPadding: mediaSettings.cropPadding
+					cropPadding: mediaSettings.cropPadding,
+					rasterFallbackWantedTrackIds,
+					rasterFallbackCandidates
 				}).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: {
@@ -13705,8 +13902,12 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 						mediaKey: s.mediaKey
 					});
 					for (const trackId of res.thumbnailTrackIds) this.thumbnailLandedTracks.add(trackId);
+					for (const trackId of res.firstFrameTrackIds) this.firstFramePendingTracks.delete(trackId);
+					for (const trackId of res.lastFrameTrackIds) this.lastFrameAtByTrack.set(trackId, dispatchTimestamp);
 				}).catch(() => {}).finally(() => {
 					for (const trackId of thumbInFlightTrackIds) this.thumbnailInFlight.delete(trackId);
+					for (const trackId of firstFrameInFlightTrackIds) this.firstFrameInFlight.delete(trackId);
+					for (const trackId of lastFrameInFlightTrackIds) this.lastFrameInFlight.delete(trackId);
 				});
 			}
 		}
@@ -13770,6 +13971,7 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 			}
 			overlayDetections = frame.detections;
 		}
+		const hasMovingTrack = result.tracked.some((t) => t.state === "moving" || t.state === "entered" || t.state === "left");
 		this.ctx.eventBus.emit({
 			id: `pa-${(0, node_crypto.randomUUID)()}`,
 			timestamp: new Date(result.timestamp),
@@ -13784,7 +13986,8 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 				timestamp: result.timestamp,
 				frameWidth: result.frameWidth,
 				frameHeight: result.frameHeight,
-				detections: overlayDetections
+				detections: overlayDetections,
+				hasMovingTrack
 			}
 		});
 	}
@@ -14408,6 +14611,34 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 		});
 		this.emitTrackLifecycle(payload, timestamp);
 	}
+	/**
+	* DEFECT A: build `firstFrame` RETRY targets for confirmed-birth tracks whose
+	* birth capture never landed. A track qualifies when it is still pending
+	* (`firstFramePendingTracks`), is OBSERVED this frame (`matchedThisFrame` — a
+	* coasted/stale box would crop the empty scene), is NOT already targeted this
+	* frame (its birth target), and has no capture in flight (RC-1). Each target is
+	* stamped with the CURRENT frame timestamp so the media carries the real
+	* capture instant, not the birth ts — the earliest AVAILABLE view still beats
+	* no firstFrame at all.
+	*/
+	collectFirstFrameRetries(tracked, timestamp, alreadyTargeted) {
+		if (this.firstFramePendingTracks.size === 0) return [];
+		const bornThisFrame = new Set(alreadyTargeted.map((t) => t.trackId));
+		const retries = [];
+		for (const t of tracked) {
+			if (t.matchedThisFrame === false) continue;
+			if (!this.firstFramePendingTracks.has(t.trackId)) continue;
+			if (bornThisFrame.has(t.trackId)) continue;
+			if (this.firstFrameInFlight.has(t.trackId)) continue;
+			retries.push({
+				trackId: t.trackId,
+				timestamp,
+				bbox: { ...t.bbox },
+				...t.label ? { label: t.label } : {}
+			});
+		}
+		return retries;
+	}
 	buildSnapshotTargets(deviceId, tracked, timestamp, media, frameWidth, frameHeight) {
 		const targets = [];
 		for (const t of tracked) {
@@ -14441,19 +14672,19 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 				now: timestamp,
 				intervalMs: media.snapshotIntervalMs
 			});
-			if (plan.rollingLastFrame) this.lastFrameAtByTrack.set(t.trackId, timestamp);
+			const rollingLastFrame = plan.rollingLastFrame && !this.lastFrameInFlight.has(t.trackId);
 			if (plan.appendSnapshot) this.trackStore.markSnapshotPending(t.trackId, timestamp, t.bbox);
 			const plausibleBox = isPlausibleThumbnailBox(t.bbox, frameWidth, frameHeight);
 			const bestThumbnail = plan.bestThumbnail && plausibleBox && !this.thumbnailInFlight.has(t.trackId);
 			const keyFrame = isNewBest && plausibleBox;
-			if (!plan.appendSnapshot && !plan.rollingLastFrame && !bestThumbnail && !keyFrame) continue;
+			if (!plan.appendSnapshot && !rollingLastFrame && !bestThumbnail && !keyFrame) continue;
 			targets.push({
 				trackId: t.trackId,
 				timestamp,
 				bbox: { ...t.bbox },
 				...t.label ? { label: t.label } : {},
 				appendSnapshot: plan.appendSnapshot,
-				rollingLastFrame: plan.rollingLastFrame,
+				rollingLastFrame,
 				bestThumbnail,
 				keyFrame
 			});
@@ -14704,6 +14935,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: {
@@ -14761,6 +15030,9 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 				this.bestFrameTracker.delete(t.trackId);
 				this.objectEmbeddingBestSelector.delete(t.trackId);
 				this.lastFrameAtByTrack.delete(t.trackId);
+				this.lastFrameInFlight.delete(t.trackId);
+				this.firstFramePendingTracks.delete(t.trackId);
+				this.firstFrameInFlight.delete(t.trackId);
 				this.thumbnailLandedTracks.delete(t.trackId);
 				this.thumbnailInFlight.delete(t.trackId);
 				this.keyFrameInFlight.delete(t.trackId);
@@ -14814,12 +15086,56 @@ 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.lastFrameInFlight.delete(trackId);
+		this.firstFramePendingTracks.delete(trackId);
+		this.firstFrameInFlight.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();
@@ -15025,10 +15341,14 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 		this.bestFrameTracker.delete(track.trackId);
 		this.objectEmbeddingBestSelector.delete(track.trackId);
 		this.lastFrameAtByTrack.delete(track.trackId);
+		this.lastFrameInFlight.delete(track.trackId);
+		this.firstFramePendingTracks.delete(track.trackId);
+		this.firstFrameInFlight.delete(track.trackId);
 		this.thumbnailLandedTracks.delete(track.trackId);
 		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 +15647,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);
@@ -15382,7 +15703,9 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 		return input.kind ? all.filter((m) => m.kind === input.kind) : all;
 	}
 	async getTrackMedia(input) {
-		return this.mediaStore?.listByOwner("track", input.trackId) ?? [];
+		const all = await (this.mediaStore?.listByOwner("track", input.trackId) ?? Promise.resolve([]));
+		const kinds = input.kinds;
+		return kinds && kinds.length > 0 ? all.filter((m) => kinds.includes(m.kind)) : all;
 	}
 	/**
 	* Search object events by text using CLIP cosine similarity.
@@ -15539,6 +15862,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 +16177,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({