@camstack/addon-post-analysis 1.2.209 → 1.2.210

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-BttKNVmP.js");
+const require_dist = require("../dist-FHSaZkf_.js");
 let node_fs = require("node:fs");
 node_fs = require_dist.__toESM(node_fs, 1);
 let node_path = require("node:path");
@@ -3452,7 +3452,7 @@ var SceneConfirmGate = class {
 		};
 	}
 };
-function clamp$1(v, lo, hi) {
+function clamp$2(v, lo, hi) {
 	return Math.max(lo, Math.min(v, hi));
 }
 /**
@@ -3467,10 +3467,10 @@ async function cropSnapshotRoi(encoded, roi) {
 	const frameW = meta.width ?? 0;
 	const frameH = meta.height ?? 0;
 	if (frameW <= 0 || frameH <= 0) throw new Error("snapshot has no decodable dimensions");
-	const left = clamp$1(Math.round(roi.x * frameW), 0, frameW - 1);
-	const top = clamp$1(Math.round(roi.y * frameH), 0, frameH - 1);
-	const width = clamp$1(Math.round(roi.width * frameW), 1, frameW - left);
-	const height = clamp$1(Math.round(roi.height * frameH), 1, frameH - top);
+	const left = clamp$2(Math.round(roi.x * frameW), 0, frameW - 1);
+	const top = clamp$2(Math.round(roi.y * frameH), 0, frameH - 1);
+	const width = clamp$2(Math.round(roi.width * frameW), 1, frameW - left);
+	const height = clamp$2(Math.round(roi.height * frameH), 1, frameH - top);
 	return {
 		crop: await (0, sharp.default)(encoded).extract({
 			left,
@@ -28633,6 +28633,37 @@ var MediaStore = class {
 		return newKey;
 	}
 	/**
+	* Exchange the bytes+instant held in the `firstFrame` and `lastFrame` slots
+	* (close-time ordering repair, see `pipeline/first-last-frame-order.ts`).
+	*
+	* Both are single-instance kinds, so each `putReplacing` overwrites the slot
+	* it names — the two rows end up holding each other's blob and timestamp.
+	* Nothing is deleted and nothing is re-encoded: both blobs are already the
+	* track's own stored pixels and the only thing wrong with them is which slot
+	* they sit in. The `lastFrame` write lands first so the "ultimo" tile is
+	* never momentarily the older view a viewer just refuted.
+	*/
+	async swapFirstAndLastFrame(input) {
+		await this.gated(async () => {
+			await this.putReplacingUnchecked({
+				deviceId: input.deviceId,
+				ownerKind: "track",
+				ownerId: input.trackId,
+				kind: "lastFrame",
+				timestamp: input.firstFrame.timestamp,
+				data: Buffer.from(input.firstFrame.base64, "base64")
+			});
+			await this.putReplacingUnchecked({
+				deviceId: input.deviceId,
+				ownerKind: "track",
+				ownerId: input.trackId,
+				kind: "firstFrame",
+				timestamp: input.lastFrame.timestamp,
+				data: Buffer.from(input.lastFrame.base64, "base64")
+			});
+		});
+	}
+	/**
 	* Fetch one media entry by its key (id). Returns null if the key is not
 	* found in the index or if the blob is missing from storage.
 	*/
@@ -30505,6 +30536,17 @@ function trackDurationMs(facts) {
 function hasKind(media, kind) {
 	return media.some((m) => m.kind === kind);
 }
+/** Newest instant stamped on a row of `kind`, or `null` when the track owns
+*  none. Single-instance kinds hold at most one row; the max guards a legacy
+*  duplicate, mirroring `decideFirstLastFrameOrder`. */
+function newestOfKind(media, kind) {
+	let newest = null;
+	for (const m of media) {
+		if (m.kind !== kind) continue;
+		if (newest === null || m.timestamp > newest) newest = m.timestamp;
+	}
+	return newest;
+}
 function latestMediaAt(media) {
 	let latest = null;
 	for (const m of media) if (latest === null || m.timestamp > latest) latest = m.timestamp;
@@ -30552,6 +30594,12 @@ function analyseDebugTrack(inventory) {
 		const lag = facts.lastSeen - lastFrameAt;
 		if (lag > 2e3) out.push(finding("LASTFRAME_STALE", "warn", `lastFrame is ${String(lag)} ms older than the track's end.`));
 	}
+	const firstFrameAt = newestOfKind(media, "firstFrame");
+	if (firstFrameAt !== null) {
+		const lastFrameAt = newestOfKind(media, "lastFrame");
+		if (lastFrameAt !== null && firstFrameAt > lastFrameAt) out.push(finding("FIRSTFRAME_AFTER_LASTFRAME", "error", `firstFrame is ${String(firstFrameAt - lastFrameAt)} ms NEWER than lastFrame — the "primo" tile post-dates the "ultimo" one. The first view is captured at the CONFIRMED birth, which the confirmation gate can defer by up to its maxDeferralMs, while keyFrame/thumbnail/lastFrame are stamped at the earlier frame they were cut from.`));
+		if (closed && firstFrameAt > facts.lastSeen) out.push(finding("FIRSTFRAME_AFTER_TRACK_END", "error", `firstFrame was captured ${String(firstFrameAt - facts.lastSeen)} ms AFTER the track's last observation — the tile shows a scene the subject had already left (a birth confirmed on a coasted frame).`));
+	}
 	if (closed && durationMs >= 1e4 && media.length > 0) {
 		const latest = latestMediaAt(media);
 		if (latest !== null) {
@@ -34151,6 +34199,29 @@ function firstFrameRetryBbox(current, birth) {
 	return { ...current };
 }
 //#endregion
+//#region src/pipeline-analytics/pipeline/birth-first-frame-gate.ts
+/**
+* Decide whether the confirmed-birth frame may be dispatched as this track's
+* `firstFrame` capture. Pure; the caller logs the refusal and keeps the
+* `firstFramePending` mark so a later frame retries.
+*
+* `coasted-frame` is reported ahead of `no-frame-handle` when both hold: a
+* handle-less coasted frame would have been refused for BEING coasted whatever
+* the decode plane did, and naming the decode is what would send the next
+* investigation at the wrong subsystem.
+*/
+function decideBirthFirstFrameCapture(input) {
+	if (input.matchedThisFrame === false) return {
+		capture: false,
+		refusedBecause: "coasted-frame"
+	};
+	if (!input.hasFrameHandle) return {
+		capture: false,
+		refusedBecause: "no-frame-handle"
+	};
+	return { capture: true };
+}
+//#endregion
 //#region src/pipeline-analytics/pipeline/events/event-filter.ts
 var DEFAULT_EVENT_EMITTER_CONFIG = {
 	minTrackAge: 3,
@@ -34759,7 +34830,7 @@ var DEFAULT_TRACKER_CONFIG = {
 var PERSON_CLASS = "person";
 var ANIMAL_CLASS = "animal";
 var MAX_PATH_LENGTH = 300;
-function clamp(value, min, max) {
+function clamp$1(value, min, max) {
 	return Math.max(min, Math.min(max, value));
 }
 function iou$3(a, b) {
@@ -35199,8 +35270,8 @@ var SortTracker = class SortTracker {
 			const perFrameX = t.velocity.dx * t.emitIntervalMs;
 			const perFrameY = t.velocity.dy * t.emitIntervalMs;
 			return {
-				x: t.bbox.x + clamp(perFrameX * f, -t.bbox.w, t.bbox.w),
-				y: t.bbox.y + clamp(perFrameY * f, -t.bbox.h, t.bbox.h),
+				x: t.bbox.x + clamp$1(perFrameX * f, -t.bbox.w, t.bbox.w),
+				y: t.bbox.y + clamp$1(perFrameY * f, -t.bbox.h, t.bbox.h),
 				w: t.bbox.w,
 				h: t.bbox.h
 			};
@@ -35209,8 +35280,8 @@ var SortTracker = class SortTracker {
 		const allowX = driftAllowancePx(t.bbox.w, elapsedMs);
 		const allowY = driftAllowancePx(t.bbox.h, elapsedMs);
 		return {
-			x: t.bbox.x + clamp(t.velocity.dx * elapsedMs, -allowX, allowX),
-			y: t.bbox.y + clamp(t.velocity.dy * elapsedMs, -allowY, allowY),
+			x: t.bbox.x + clamp$1(t.velocity.dx * elapsedMs, -allowX, allowX),
+			y: t.bbox.y + clamp$1(t.velocity.dy * elapsedMs, -allowY, allowY),
 			w: t.bbox.w,
 			h: t.bbox.h
 		};
@@ -37287,6 +37358,44 @@ function decideLastFramePromotion(media) {
 	};
 }
 //#endregion
+//#region src/pipeline-analytics/pipeline/first-last-frame-order.ts
+/**
+* Decide whether a closing track's `firstFrame` and `lastFrame` slots hold each
+* other's bytes. Pure — see the module header for the contract.
+*
+* Swap when BOTH slots are filled and the `firstFrame` is STRICTLY newer than
+* the `lastFrame`. Equal timestamps are not an inversion.
+*/
+function decideFirstLastFrameOrder(media) {
+	let firstFrame;
+	let lastFrame;
+	for (const m of media) if (m.kind === "firstFrame") {
+		if (firstFrame === void 0 || m.timestamp > firstFrame.timestamp) firstFrame = m;
+	} else if (m.kind === "lastFrame") {
+		if (lastFrame === void 0 || m.timestamp > lastFrame.timestamp) lastFrame = m;
+	}
+	if (firstFrame === void 0) return {
+		swap: false,
+		skippedBecause: "no-first-frame"
+	};
+	if (lastFrame === void 0) return {
+		swap: false,
+		skippedBecause: "no-last-frame"
+	};
+	if (firstFrame.timestamp <= lastFrame.timestamp) return {
+		swap: false,
+		skippedBecause: "ordered"
+	};
+	return {
+		swap: true,
+		firstFrameKey: firstFrame.key,
+		lastFrameKey: lastFrame.key,
+		firstFrameTimestamp: firstFrame.timestamp,
+		lastFrameTimestamp: lastFrame.timestamp,
+		inversionMs: firstFrame.timestamp - lastFrame.timestamp
+	};
+}
+//#endregion
 //#region src/pipeline-analytics/pipeline/static-track-gate.ts
 /**
 * Net displacement + path span for a track's centroid path, normalized to
@@ -37429,6 +37538,7 @@ var TrackCloser = class {
 			tile = "raster";
 		}
 		await this.maybePromoteLastFrame(t, ownedMedia);
+		await this.repairFirstLastFrameOrder(t);
 		const hasRasterFallback = closure?.rasterFallback !== void 0;
 		let deriveMiss;
 		if (!thumbnailLanded) {
@@ -37772,6 +37882,56 @@ var TrackCloser = class {
 		}
 	}
 	/**
+	* A track's "primo" tile is never newer than its "ultimo" tile
+	* (`first-last-frame-order.ts`). Filed by hand three times on device 3829,
+	* 2026-09-08 — `d035f251`, `448678bb`, `7628b19d`.
+	*
+	* The media list is RE-READ rather than reusing the caller's `ownedMedia`:
+	* `maybePromoteLastFrame` has just run and is precisely what may have put the
+	* older bytes in the `lastFrame` slot, so the caller's copy predates the pair
+	* being ordered here. Best-effort — a failure never blocks the close.
+	*/
+	async repairFirstLastFrameOrder(t) {
+		const store = this.deps.mediaStore();
+		if (!store) return;
+		const media = await store.listByOwner("track", t.trackId);
+		const decision = decideFirstLastFrameOrder(media);
+		if (!decision.swap) return;
+		const firstFrame = media.find((m) => m.key === decision.firstFrameKey);
+		const lastFrame = media.find((m) => m.key === decision.lastFrameKey);
+		if (!firstFrame || !lastFrame) return;
+		try {
+			await store.swapFirstAndLastFrame({
+				deviceId: t.deviceId,
+				trackId: t.trackId,
+				firstFrame,
+				lastFrame
+			});
+			this.deps.logger.warn("firstFrame/lastFrame were out of order — slots swapped", {
+				tags: { deviceId: t.deviceId },
+				meta: {
+					trackId: t.trackId,
+					className: t.className,
+					inversionMs: decision.inversionMs,
+					firstFrameAt: decision.firstFrameTimestamp,
+					lastFrameAt: decision.lastFrameTimestamp,
+					/** How far the late capture ran past the track itself. Positive means
+					*  it was cut from a frame the subject was no longer observed in. */
+					pastTrackEndMs: decision.firstFrameTimestamp - t.lastSeen,
+					durationMs: t.lastSeen - t.firstSeen
+				}
+			});
+		} catch (err) {
+			this.deps.logger.warn("firstFrame/lastFrame order repair failed", {
+				tags: { deviceId: t.deviceId },
+				meta: {
+					trackId: t.trackId,
+					error: String(err)
+				}
+			});
+		}
+	}
+	/**
 	* Key-event importance: score the just-expired track and persist. Peak
 	* confidence comes from the shared best-detection tracker; peak bbox area
 	* + the winning object-event id from one indexed queryObject(trackId) —
@@ -41587,7 +41747,10 @@ var TrackStore = class {
 			retrainStatus: active.retrainStatus ?? "none",
 			debug: active.debug === true,
 			debugNote: active.debugNote ?? "",
-			favourited: active.favourited === true
+			favourited: active.favourited === true,
+			startedAt: active.firstSeen,
+			className: active.className,
+			...displayLabel(active) !== void 0 ? { label: displayLabel(active) } : {}
 		};
 		const persisted = await this.getPersistedByTrackId(trackId);
 		if (!persisted) return null;
@@ -41595,7 +41758,10 @@ var TrackStore = class {
 			retrainStatus: persisted.retrainStatus ?? "none",
 			debug: persisted.debug === true,
 			debugNote: persisted.debugNote ?? "",
-			favourited: persisted.favourited === true
+			favourited: persisted.favourited === true,
+			startedAt: persisted.firstSeen,
+			className: persisted.className,
+			...displayLabel(persisted) !== void 0 ? { label: displayLabel(persisted) } : {}
 		};
 	}
 	/**
@@ -55023,7 +55189,7 @@ var PackageDropDetector = class {
 	async onStationaryChange(change) {
 		try {
 			if (change.phase === "appeared") await this.onAppeared(change.entry, change.timestamp);
-			else await this.onDeparted(change.entry, change.timestamp);
+			else await this.onDeparted(change);
 		} catch (err) {
 			this.deps.onError?.("onStationaryChange", err);
 			this.deps.logger.warn("package-drop detector failed on change", {
@@ -55201,7 +55367,9 @@ var PackageDropDetector = class {
 			}
 		});
 	}
-	async onDeparted(entry, timestamp) {
+	async onDeparted(change) {
+		const entry = change.entry;
+		const timestamp = change.timestamp;
 		if (!(await this.deps.resolveSettings(entry.deviceId)).packageDropPickupEnabled) {
 			this.deps.logger.debug("package pick-up skipped — packageDropPickupEnabled is false", {
 				tags: { deviceId: entry.deviceId },
@@ -55236,13 +55404,25 @@ var PackageDropDetector = class {
 			});
 			return;
 		}
+		const collector = change.collector;
+		const packageTrackId = entry.sourceTrackId ?? entry.id;
+		const mediaTrackId = collector?.trackId ?? packageTrackId;
+		if (collector === void 0) this.deps.logger.info("package pick-up has no collector track — the notification carries the parcel frame", {
+			tags: { deviceId: entry.deviceId },
+			meta: {
+				entryId: entry.id,
+				eventId: pickedUpId,
+				packageTrackId,
+				pickupAt: entry.lastConfirmedAt
+			}
+		});
 		const ev = {
 			id: pickedUpId,
 			kind: "object",
 			deviceId: entry.deviceId,
 			timestamp,
 			source: "pipeline",
-			trackId: entry.sourceTrackId ?? entry.id,
+			trackId: mediaTrackId,
 			className: PACKAGE_EVENT_CLASS,
 			...entry.label !== void 0 ? { label: entry.label } : {},
 			confidence: PACKAGE_IMPORTANCE,
@@ -55256,6 +55436,7 @@ var PackageDropDetector = class {
 			state: PICKED_UP_STATE,
 			frameWidth: entry.frameWidth,
 			frameHeight: entry.frameHeight,
+			...collector?.keyFrameMediaKey !== void 0 ? { mediaKey: collector.keyFrameMediaKey } : {},
 			importance: PACKAGE_IMPORTANCE
 		};
 		await this.deps.events.insertObject(ev);
@@ -55265,6 +55446,7 @@ var PackageDropDetector = class {
 			entryId: entry.id,
 			deliveredEventId: deliveredId,
 			className: entry.className,
+			...collector !== void 0 ? { collectorTrackId: collector.trackId } : {},
 			timestamp
 		});
 		this.deps.logger.info("package picked up", {
@@ -55272,11 +55454,139 @@ var PackageDropDetector = class {
 			meta: {
 				entryId: entry.id,
 				eventId: pickedUpId,
-				deliveredEventId: deliveredId
+				deliveredEventId: deliveredId,
+				mediaTrackId,
+				...collector !== void 0 ? {
+					collectorTrackId: collector.trackId,
+					collectorClassName: collector.className,
+					collectorSkewMs: collector.skewMs
+				} : { collectorTrackId: null }
 			}
 		});
 	}
 };
+/**
+* How long a presence survives in the mirror, in FRAME time.
+*
+* It must outlive the whole detection latency: a pick-up at T is concluded no
+* earlier than T + `PACKAGE_STILLNESS_TTL_MS` (5 min of observed time), and the
+* pick is made at conclusion time. 10 minutes is double that, so a collector
+* noted at the true instant is still there to be named — and a mirror that
+* expires the answer before the question is asked would be the same silent
+* hole in a different place.
+*/
+var PACKAGE_COLLECTOR_RETENTION_MS = 10 * 6e4;
+/** The pick-up instant a stationary entry implies. One derivation, named. */
+function pickupInstantOf(entry) {
+	return entry.lastConfirmedAt;
+}
+var PackageCollectorMirror = class {
+	/** Per device, per track. Every write replaces the record (immutable). */
+	byDevice = /* @__PURE__ */ new Map();
+	/**
+	* Record one sighting. Extends the track's presence span and refreshes its
+	* key-frame handle (a re-shot key frame is a better one, and the newest is
+	* also the nearest to the pick-up — the same trade as above).
+	*/
+	note(obs) {
+		const current = this.byDevice.get(obs.deviceId);
+		const next = /* @__PURE__ */ new Map();
+		const horizon = obs.at - PACKAGE_COLLECTOR_RETENTION_MS;
+		if (current !== void 0) for (const [id, p] of current) {
+			if (p.lastAt < horizon) continue;
+			next.set(id, p);
+		}
+		const prev = next.get(obs.trackId);
+		next.set(obs.trackId, {
+			trackId: obs.trackId,
+			className: obs.className,
+			firstAt: prev === void 0 ? obs.at : Math.min(prev.firstAt, obs.at),
+			lastAt: prev === void 0 ? obs.at : Math.max(prev.lastAt, obs.at),
+			...obs.keyFrameMediaKey !== void 0 ? { keyFrameMediaKey: obs.keyFrameMediaKey } : prev?.keyFrameMediaKey !== void 0 ? { keyFrameMediaKey: prev.keyFrameMediaKey } : {}
+		});
+		this.byDevice.set(obs.deviceId, evictOldest(next));
+	}
+	/**
+	* The track nearest the pick-up instant, or `null` when nobody qualifies.
+	*
+	* `null` is a real answer and not an error: a parcel can stop being seen
+	* because the light changed or the detector lost it, and naming a person who
+	* was not there would be worse than naming nobody. The caller degrades to the
+	* parcel's own owner and logs it.
+	*/
+	pickCollector(input) {
+		const presences = this.byDevice.get(input.deviceId);
+		if (presences === void 0 || presences.size === 0) return null;
+		const maxSkewMs = input.maxSkewMs ?? 3e4;
+		let best = null;
+		let bestLastAt = Number.NEGATIVE_INFINITY;
+		for (const p of presences.values()) {
+			const observedAt = clamp(input.pickupAt, p.firstAt, p.lastAt);
+			const skewMs = Math.abs(observedAt - input.pickupAt);
+			if (skewMs > maxSkewMs) continue;
+			if (best !== null && (skewMs > best.skewMs || skewMs === best.skewMs && p.lastAt <= bestLastAt)) continue;
+			best = {
+				trackId: p.trackId,
+				className: p.className,
+				observedAt,
+				skewMs,
+				...p.keyFrameMediaKey !== void 0 ? { keyFrameMediaKey: p.keyFrameMediaKey } : {}
+			};
+			bestLastAt = p.lastAt;
+		}
+		return best;
+	}
+	/**
+	* Fold one pipeline frame in. Returns how many presences it touched, so the
+	* caller can say "nobody was ever in the drop-off zone" with a number.
+	*
+	* This is the ONLY place the frame-shaped input is interpreted, so the
+	* production path and the test path read the same rules: a non-package class,
+	* inside a configured drop-off zone, on this frame.
+	*/
+	noteFrame(input) {
+		if (input.packageZoneIds.size === 0) return 0;
+		let noted = 0;
+		for (const t of input.tracked) {
+			if (input.packageClasses.has(t.className)) continue;
+			if (!isDelivererInPackageZone(t.zones, input.packageZoneIds)) continue;
+			const keyFrameMediaKey = input.keyFrameMediaKeyFor(t.trackId);
+			this.note({
+				deviceId: input.deviceId,
+				trackId: t.trackId,
+				className: t.className,
+				at: input.timestamp,
+				...keyFrameMediaKey !== void 0 ? { keyFrameMediaKey } : {}
+			});
+			noted += 1;
+		}
+		return noted;
+	}
+	/** Drop a camera's memory (unbind / step disabled / device removal). */
+	forgetDevice(deviceId) {
+		this.byDevice.delete(deviceId);
+	}
+	reset() {
+		this.byDevice.clear();
+	}
+	/** Retained presences for a camera — diagnostics and tests only. */
+	debugPresenceCount(deviceId) {
+		return this.byDevice.get(deviceId)?.size ?? 0;
+	}
+};
+function clamp(value, low, high) {
+	if (value < low) return low;
+	if (value > high) return high;
+	return value;
+}
+/** Keep the newest {@link PACKAGE_COLLECTOR_MAX_PRESENCES} by `lastAt`. */
+function evictOldest(presences) {
+	if (presences.size <= 32) return presences;
+	const ordered = [...presences.values()].sort((a, b) => b.lastAt - a.lastAt);
+	const kept = /* @__PURE__ */ new Map();
+	for (const p of ordered.slice(0, 32)) kept.set(p.trackId, p);
+	return kept;
+}
 //#endregion
 //#region src/pipeline-analytics/pipeline/person-over-vehicle.ts
 /**
@@ -56752,6 +57062,61 @@ function classifyTrackAppearance(input) {
 	if (input.inPrevActive) return "continuing";
 	return input.positionsCount > 1 ? "resurrection" : "birth";
 }
+//#endregion
+//#region src/pipeline-analytics/pipeline/archive-debug-note.ts
+/**
+* Archive the note a clear is about to destroy. Never throws.
+*
+* **Which way this fails, stated once.** The operator pressed a flag button;
+* the archive is this system's own bookkeeping. So a failing archive does NOT
+* block the flag write — the button must do what it says even when SQLite is
+* busy — and it does NOT retry, because the caller is a synchronous cap method
+* an operator is waiting on.
+*
+* What it must never do is lose the sentence quietly. The failure line carries
+* the NOTE TEXT verbatim, plus `tags: { deviceId }` and the trackId, so the
+* words are recoverable from the log by hand and the loss is attributable to
+* one camera. A branch that drops work silently reads as "never happened", and
+* the 3-hour media blackout produced not one line.
+*
+* An EMPTY note archives nothing: there is nothing to keep, and a row of `''`
+* would be a permanent entry in a corpus meant to be mined for sentences.
+*/
+async function archiveNoteBeforeClear(input) {
+	const note = input.current.debugNote;
+	if (note.trim() === "") return;
+	if (input.archive === void 0) {
+		input.logger.warn("debug note dropped — no archive is wired on this runner", {
+			tags: { deviceId: input.deviceId },
+			meta: {
+				deviceId: input.deviceId,
+				trackId: input.trackId,
+				note
+			}
+		});
+		return;
+	}
+	try {
+		await input.archive.append({
+			deviceId: input.deviceId,
+			sourceTrackId: input.trackId,
+			note,
+			...input.current.startedAt !== void 0 ? { trackStartedAt: input.current.startedAt } : {},
+			...input.current.className !== void 0 ? { trackClass: input.current.className } : {},
+			...input.current.label !== void 0 ? { trackLabel: input.current.label } : {}
+		});
+	} catch (err) {
+		input.logger.error("failed to archive a debug note — the text is in this line", {
+			tags: { deviceId: input.deviceId },
+			meta: {
+				deviceId: input.deviceId,
+				trackId: input.trackId,
+				note,
+				error: err instanceof Error ? err.message : String(err)
+			}
+		});
+	}
+}
 /** Thrown when the device is already holding its full staging budget. Distinct
 *  type so a surface can tell "you are out of room" from "that track is gone". */
 var StagingBudgetExceededError = class extends Error {
@@ -56792,7 +57157,10 @@ var TrackAlreadyTrainedError = class extends Error {
 *     caller sent with it. A note surviving the flag is a leftover that reads
 *     as a live request, and the invariant belongs here rather than in the
 *     three surfaces that write this patch — one of which is a browser grid
-*     that has no note UI at all and would never think to clear it.
+*     that has no note UI at all and would never think to clear it. Since
+*     D405 the clear is not a DELETE: `applyTrackFlags` ARCHIVES the note
+*     first, into a table that outlives the track. The invariant above is
+*     unchanged — only where the words go.
 *  2. **No note in the patch → nothing is written.** This is what makes a
 *     cancelled prompt free: the app turns debug on, the operator declines to
 *     type, and the flag still lands. Refusing to write a note must never cost
@@ -56886,6 +57254,13 @@ async function applyTrackFlags(deps, input) {
 		...input.flags.favourited !== void 0 ? { favourited: input.flags.favourited } : {},
 		...resolveNotePatch(deps, input, current)
 	};
+	if (patch.debugNote === "" && current.debugNote !== "") await archiveNoteBeforeClear({
+		deviceId: input.deviceId,
+		trackId: input.trackId,
+		logger,
+		archive: deps.noteArchive,
+		current
+	});
 	if (Object.keys(patch).length > 0) await store.setFlags(input.trackId, patch);
 	const retrainStatus = patch.markForTrain === void 0 ? current.retrainStatus : patch.markForTrain ? "staging" : "none";
 	return {
@@ -59567,6 +59942,261 @@ var IdentityStore = class {
 	}
 };
 //#endregion
+//#region src/pipeline-analytics/store/debug-note-archive-store.ts
+/**
+* DebugNoteArchiveStore — the durable corpus of what operators asked to be
+* checked (D405).
+*
+* A declared SQL-backed collection, like the events ops-log next door, and for
+* the same reason: pipeline-analytics already owns SQLite collections, and an
+* undeclared collection crash-loops the runner. MUST be declared in
+* `onInitialize` before the first write.
+*
+* Collection name: pipeline-analytics:debug-note-archive
+*
+* Two properties separate it from every other table in this addon:
+*
+*  - **It is not track-owned.** It names a track in `sourceTrackId` and that is
+*    PROVENANCE, never ownership — the whole point is that the row outlives the
+*    track, which `debug` deliberately never pinned (D353). It is classified
+*    `never-orphaned` by hand in `collection-classification.ts` so the
+*    ownership derivation cannot see the column and cascade it away.
+*  - **It is bounded by COUNT, not by age.** An age sweep would delete the
+*    corpus for being old, which is the failure this table exists to fix: a
+*    six-month-old note is the most valuable row in it, because the pattern it
+*    describes has had time to repeat. See {@link MAX_ARCHIVED_DEBUG_NOTES}.
+*/
+/**
+* @durable class=ledger owner=pipeline-analytics
+*   write="one row per debug note RETIRED by a review — appended by
+*     `applyTrackFlags` immediately before `debug: false` clears the note off
+*     the track row (D405). Idempotent per (sourceTrackId, note): the row id is
+*     derived from the pair, so reviewing the same track twice cannot double
+*     the corpus. An empty note writes nothing."
+*   retention="NOT track retention and NOT an age clock — deleting a note for
+*     being old is the failure this table fixes. Bounded by ROW COUNT
+*     (MAX_ARCHIVED_DEBUG_NOTES, 5000, fleet-wide), oldest `archivedAt` first,
+*     trimmed on append. ~3 MB of text at the ceiling."
+*/
+var DEBUG_NOTE_ARCHIVE_COLLECTION = "pipeline-analytics:debug-note-archive";
+var DEBUG_NOTE_ARCHIVE_COLUMNS = [
+	{
+		name: "id",
+		type: "TEXT",
+		primaryKey: true,
+		notNull: true
+	},
+	{
+		name: "archivedAt",
+		type: "INTEGER",
+		notNull: true
+	},
+	{
+		name: "deviceId",
+		type: "INTEGER",
+		notNull: true
+	},
+	{
+		name: "sourceTrackId",
+		type: "TEXT",
+		notNull: true
+	},
+	{
+		name: "note",
+		type: "TEXT",
+		notNull: true
+	},
+	{
+		name: "trackStartedAt",
+		type: "INTEGER"
+	},
+	{
+		name: "trackClass",
+		type: "TEXT"
+	},
+	{
+		name: "trackLabel",
+		type: "TEXT"
+	}
+];
+var DEBUG_NOTE_ARCHIVE_INDEXES = [{
+	name: "idx_debugnote_archived_at",
+	columns: ["archivedAt"]
+}, {
+	name: "idx_debugnote_device_at",
+	columns: ["deviceId", "archivedAt"]
+}];
+/**
+* The row id for one `(track, note)` pair.
+*
+* Deterministic on purpose: the idempotency the operator needs is "reviewing
+* twice does not double the row", and a derived primary key gets it from the
+* database rather than from a read-modify-write that two concurrent reviews
+* could interleave through. Truncated to 32 hex characters — 128 bits over a
+* table capped at 5 000 rows.
+*/
+function archiveRowId(sourceTrackId, note) {
+	return (0, node_crypto.createHash)("sha256").update(`${sourceTrackId}${note}`).digest("hex").slice(0, 32);
+}
+var DebugNoteArchiveStore = class {
+	store;
+	logger;
+	now;
+	maxRows;
+	constructor(deps) {
+		this.store = deps.store;
+		this.logger = deps.logger;
+		this.now = deps.now ?? (() => Date.now());
+		this.maxRows = deps.maxRows ?? 5e3;
+	}
+	/** The ceiling a store built without an override enforces. */
+	static defaultMaxRows() {
+		return require_dist.MAX_ARCHIVED_DEBUG_NOTES;
+	}
+	static async declare(store) {
+		await store.declareCollection.mutate({
+			collection: DEBUG_NOTE_ARCHIVE_COLLECTION,
+			columns: [...DEBUG_NOTE_ARCHIVE_COLUMNS],
+			indexes: [...DEBUG_NOTE_ARCHIVE_INDEXES]
+		});
+	}
+	/**
+	* Append one retired note. THROWS if the row cannot be written.
+	*
+	* Deliberately not best-effort, unlike the ops-log's `append`: this is the
+	* only copy of something a person typed, and the caller
+	* (`archiveNoteBeforeClear`) has both the text and the camera and is the
+	* right place to decide what a failure costs — it logs the note verbatim and
+	* lets the operator's flag write proceed. Swallowing here would hide the
+	* failure from the one caller able to preserve the words.
+	*
+	* The TRIM is the exception and is best-effort: the row has already landed,
+	* and failing the append because housekeeping could not run would make the
+	* caller report a note lost that is sitting in the table.
+	*/
+	async append(input) {
+		const note = input.note.trim() === "" ? "" : input.note;
+		if (note === "") return {
+			archived: false,
+			id: null
+		};
+		const id = archiveRowId(input.sourceTrackId, note);
+		if ((await this.store.query.query({
+			collection: "pipeline-analytics:debug-note-archive",
+			filter: {
+				where: { id },
+				limit: 1
+			}
+		})).length > 0) return {
+			archived: false,
+			id
+		};
+		const row = require_dist.ArchivedDebugNoteSchema.parse({
+			id,
+			note,
+			deviceId: input.deviceId,
+			sourceTrackId: input.sourceTrackId,
+			archivedAt: this.now(),
+			trackStartedAt: input.trackStartedAt ?? null,
+			trackClass: input.trackClass ?? null,
+			trackLabel: input.trackLabel ?? null
+		});
+		await this.store.insert.mutate({
+			collection: DEBUG_NOTE_ARCHIVE_COLLECTION,
+			record: {
+				id: row.id,
+				data: {
+					note: row.note,
+					deviceId: row.deviceId,
+					sourceTrackId: row.sourceTrackId,
+					archivedAt: row.archivedAt,
+					trackStartedAt: row.trackStartedAt,
+					trackClass: row.trackClass,
+					trackLabel: row.trackLabel
+				}
+			}
+		});
+		await this.trim();
+		return {
+			archived: true,
+			id: row.id
+		};
+	}
+	/**
+	* Hold the table at its ceiling, oldest first. Best-effort by design — see
+	* {@link append}.
+	*
+	* NOT an age-keyed sweep and must never become one: the boundary below is
+	* computed from the POSITION of the excess rows, never from a clock, so a
+	* quiet fleet keeps its whole corpus for ever and a busy one drops its oldest
+	* questions. Rows sharing the boundary timestamp go together; at a
+	* one-per-review write rate that is a rounding error, and the alternative —
+	* deleting by id, one round trip per row — is the N+1 drain this store layer
+	* spent a release removing.
+	*/
+	async trim() {
+		try {
+			const held = await this.store.count.query({ collection: DEBUG_NOTE_ARCHIVE_COLLECTION });
+			const excess = held - this.maxRows;
+			if (excess <= 0) return;
+			const boundary = (await this.store.query.query({
+				collection: DEBUG_NOTE_ARCHIVE_COLLECTION,
+				filter: {
+					orderBy: {
+						field: "archivedAt",
+						direction: "asc"
+					},
+					limit: excess
+				},
+				columns: ["archivedAt"]
+			})).reduce((acc, r) => {
+				const at = r.data["archivedAt"];
+				return typeof at === "number" && at > acc ? at : acc;
+			}, 0);
+			if (boundary === 0) return;
+			const { deleted } = await this.store.deleteWhere.mutate({
+				collection: DEBUG_NOTE_ARCHIVE_COLLECTION,
+				filter: { whereBetween: { archivedAt: [0, boundary] } }
+			});
+			this.logger.info("debug-note archive trimmed to its ceiling", { meta: {
+				held,
+				ceiling: this.maxRows,
+				deleted
+			} });
+		} catch (err) {
+			this.logger.warn("debug-note archive trim failed — the archive will keep growing", { meta: {
+				ceiling: this.maxRows,
+				error: err instanceof Error ? err.message : String(err)
+			} });
+		}
+	}
+	/** Archived notes, newest first, optionally scoped to one camera. */
+	async list(query) {
+		const filter = {
+			orderBy: {
+				field: "archivedAt",
+				direction: "desc"
+			},
+			limit: query.limit ?? 200
+		};
+		if (query.deviceId !== void 0) filter["where"] = { deviceId: query.deviceId };
+		const rows = await this.store.query.query({
+			collection: DEBUG_NOTE_ARCHIVE_COLLECTION,
+			filter
+		});
+		const out = [];
+		for (const r of rows) {
+			const parsed = require_dist.ArchivedDebugNoteSchema.safeParse({
+				id: r.id,
+				...r.data
+			});
+			if (parsed.success) out.push(parsed.data);
+			else this.logger.debug("debug-note archive: skipped a malformed row", { meta: { id: r.id } });
+		}
+		return out;
+	}
+};
+//#endregion
 //#region src/pipeline-analytics/store/ops-log-store.ts
 /**
 * OpsLogStore — the EVENTS-domain operations audit for pipeline-analytics.
@@ -60930,6 +61560,13 @@ var ANALYTICS_COLLECTIONS = [
 			why: "the drained predecessor of the row above, declared only so its rows can be read once and moved (`viewer-settings-legacy-adoption.ts`). Retention must never touch it: its rows go one way only, to the successor, gated on a re-read that confirms they landed. Delete this entry together with that module."
 		}
 	},
+	{
+		collection: DEBUG_NOTE_ARCHIVE_COLLECTION,
+		classification: {
+			kind: "never-orphaned",
+			why: "the archived operator notes (D405) — the ONE table here whose whole purpose is to outlive the track it names. `debug` never pinned a track against retention and D405 does not change that, so the track a note was written on IS expected to be evicted; deleting the note with it is the failure the archive was built to fix (25–27 notes from one sweep unreadable the same afternoon). Its column is called `sourceTrackId` and not `trackId` precisely so the ownership derivation cannot reach it, and its bound is a fleet-wide ROW COUNT trimmed on append — never an age sweep, which would delete the corpus for the one property that makes it valuable."
+		}
+	},
 	{
 		collection: STATIONARY_COLLECTION,
 		classification: {
@@ -68700,6 +69337,12 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 	eventStore = null;
 	/** Events-domain ops-log (footprint/prune/manual-delete audit). Null until onInitialize. */
 	eventsOpsLog = null;
+	/**
+	* The archived operator debug notes (D405). Null until onInitialize — and
+	* `applyTrackFlags` treats null as "no archive wired": the flag write the
+	* operator asked for never depends on this addon's own bookkeeping.
+	*/
+	debugNoteArchive = null;
 	/** Event-media relocation engine (entity-routing Phase 4). */
 	mediaRelocate = null;
 	mediaLocationStorage = null;
@@ -69257,6 +69900,12 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 	* which would let the streetlight wedge vouch for its own delivery.
 	*/
 	lastNonPackageActivityAt = /* @__PURE__ */ new Map();
+	/**
+	* WHO was in the drop-off zone, and when (D404). The pick-up is CONCLUDED
+	* minutes after the fact, so the collector must be remembered while it is
+	* still true — handles only, never pixels.
+	*/
+	packageCollectors = new PackageCollectorMirror();
 	/** Last time the oversize-sighting drop was logged per device — one line
 	*  per 5 minutes, not one per governor round (the wedge re-sights all
 	*  night; ~300 identical lines would bury the log it exists to serve). */
@@ -69682,6 +70331,10 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 			logger: logger.child("ops-log"),
 			nodeId: ownNodeId
 		});
+		this.debugNoteArchive = new DebugNoteArchiveStore({
+			store: api.settingsStore,
+			logger: logger.child("debug-note-archive")
+		});
 		{
 			const designated = await step("postProcessingNodeState", () => this.postProcessingNodeState.get());
 			this.isPostProcessingNode = ownNodeId === designated;
@@ -70001,6 +70654,7 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 			RetrainFrameStore.declare(api.settingsStore),
 			RetrainAnnotationStore.declare(api.settingsStore),
 			OpsLogStore.declare(api.settingsStore),
+			DebugNoteArchiveStore.declare(api.settingsStore),
 			AnalyticsLts.declare(api.settingsStore),
 			SceneStore.declare(api.settingsStore),
 			NotificationCenter.declare(api.settingsStore),
@@ -71639,6 +72293,7 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 			this.packageStillness.forgetDevice(data.deviceId);
 			this.packageDropDetector?.forgetDevice(data.deviceId);
 			this.lastNonPackageActivityAt.delete(data.deviceId);
+			this.packageCollectors.forgetDevice(data.deviceId);
 			this.packageOversizeLogAt.delete(data.deviceId);
 			this.overlayState.clearDevice(data.deviceId);
 			this.overlaySynthesisWarnAt.delete(data.deviceId);
@@ -71658,6 +72313,7 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 		this.packageStillness.forgetDevice(deviceId);
 		this.packageDropDetector?.forgetDevice(deviceId);
 		this.lastNonPackageActivityAt.delete(deviceId);
+		this.packageCollectors.forgetDevice(deviceId);
 		this.packageOversizeLogAt.delete(deviceId);
 		this.overlayState.clearDevice(deviceId);
 		this.overlaySynthesisWarnAt.delete(deviceId);
@@ -72541,12 +73197,26 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 				this.residents.markFirstFramePending(deviceId, id);
 				this.trackStore.seedSnapshotClock(id, result.timestamp, t.bbox);
 				this.residents.setLastFrameAt(deviceId, id, result.timestamp);
-				if (frameHandle) firstFrameTargets.push({
+				const birthCapture = decideBirthFirstFrameCapture({
+					hasFrameHandle: frameHandle !== void 0,
+					matchedThisFrame: t.matchedThisFrame
+				});
+				if (birthCapture.capture) firstFrameTargets.push({
 					trackId: id,
 					timestamp: result.timestamp,
 					bbox: { ...t.bbox },
 					...patchDisplayLabel(t.labelPatch) !== void 0 ? { label: patchDisplayLabel(t.labelPatch) } : {}
 				});
+				else log.info("birth firstFrame not captured — retry armed", {
+					tags: { deviceId },
+					meta: {
+						trackId: id,
+						className: t.className,
+						source,
+						refusedBecause: birthCapture.refusedBecause,
+						deferredMs: result.timestamp - (this.trackStore?.peekActive(id)?.firstSeen ?? result.timestamp)
+					}
+				});
 			}
 			this.ctx.eventBus.emit({
 				id: `pa-${(0, node_crypto.randomUUID)()}`,
@@ -75256,6 +75926,14 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 			this.lastNonPackageActivityAt.set(input.deviceId, input.timestamp);
 			break;
 		}
+		this.packageCollectors.noteFrame({
+			deviceId: input.deviceId,
+			tracked: input.tracked,
+			packageClasses: input.packageClasses,
+			packageZoneIds: input.packageZoneIds,
+			timestamp: input.timestamp,
+			keyFrameMediaKeyFor: (trackId) => this.residents.keyFrameKey(trackId)
+		});
 		const sightings = [];
 		for (const t of input.tracked) {
 			if (!input.packageClasses.has(t.className)) continue;
@@ -75367,10 +76045,24 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 					meta: { entryId: entry.id }
 				});
 			}).catch(() => void 0);
+			const collector = this.packageCollectors.pickCollector({
+				deviceId: input.deviceId,
+				pickupAt: pickupInstantOf(entry)
+			});
+			if (collector === null) this.ctx.logger.info("package pick-up has no collector in the drop-off zone", {
+				tags,
+				meta: {
+					entryId: entry.id,
+					pickupAt: entry.lastConfirmedAt,
+					departedAt: input.timestamp,
+					presencesKnown: this.packageCollectors.debugPresenceCount(input.deviceId)
+				}
+			});
 			this.packageDropDetector.onStationaryChange({
 				phase: "departed",
 				entry,
-				timestamp: input.timestamp
+				timestamp: input.timestamp,
+				...collector !== null ? { collector } : {}
 			});
 		}
 		for (const entry of outcome.departedWithoutActivity) {
@@ -77495,7 +78187,8 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 				setFlags: (trackId, patch) => trackStore.setFlags(trackId, patch),
 				countStaging: (query) => trackStore.countStaging(query)
 			},
-			logger: this.ctx.logger
+			logger: this.ctx.logger,
+			...this.debugNoteArchive !== null ? { noteArchive: this.debugNoteArchive } : {}
 		}, input);
 		this.ctx.logger.info("track operator flags set", {
 			tags: { deviceId: input.deviceId },
@@ -77626,6 +78319,18 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 		return this.queryFacade.listOpsLog(input);
 	}
 	/**
+	* The archived debug notes, newest first (D405).
+	*
+	* Answers from the archive alone — never from the track rows. The point of
+	* the table is that the tracks these notes were written on are gone, so a
+	* read that joined them would return exactly the rows the archive exists to
+	* replace. An archive that has not been built yet answers EMPTY, which is
+	* true: nothing has been archived on this runner.
+	*/
+	async listArchivedDebugNotes(input) {
+		return await this.debugNoteArchive?.list(input) ?? [];
+	}
+	/**
 	* Track-centric time-based retention (design §5.1). Drains every persisted
 	* track for the device whose `lastSeen < cutoffMs`, page by page, through the
 	* widened cascade — enrolled faces/plates + identity media are exempt (design