@camstack/addon-post-analysis 1.2.133 → 1.2.135

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-Dqa0bdV6.js");
+const require_dist = require("../dist-kn_4KEmG.js");
 let node_fs = require("node:fs");
 node_fs = require_dist.__toESM(node_fs, 1);
 let node_path = require("node:path");
@@ -29021,9 +29021,18 @@ function pairRiders(detections) {
 }
 //#endregion
 //#region src/pipeline-analytics/pipeline/tracker/rescue-growth.ts
-/** How far the grown box's centroid may sit, as a multiple of the LARGER
-*  diagonal. 1.35 covers the live 4285605a bird→dog jump (~75px / 59px). */
-var GROWTH_CENTROID_FACTOR = 1.35;
+/**
+* How far the grown box's centroid may sit, as a multiple of the **TRACK's own**
+* diagonal. It was a multiple of the LARGER of the two diagonals until
+* 2026-08-25, which meant the bigger the INTRUDING detection, the further it
+* could reach to steal an identity. Live track `59dfb972` lost its car that
+* way: a 386×752 box 574 px away out-reached a 364×385 track purely because it
+* was 2.07× the area. The reach is now a property of the track alone.
+*
+* 2.3 covers the live `4285605a` bird→dog jump (74.7 px over a 35.8 px crop
+* diagonal = 2.085) with the same ~10% headroom the old 1.35 gave it.
+*/
+var GROWTH_CENTROID_FACTOR = 2.3;
 function intersectionArea(a, b) {
 	const x1 = Math.max(a.x, b.x);
 	const y1 = Math.max(a.y, b.y);
@@ -29032,11 +29041,30 @@ function intersectionArea(a, b) {
 	if (x2 <= x1 || y2 <= y1) return 0;
 	return (x2 - x1) * (y2 - y1);
 }
-/** Same-class partial crop growing into (or collapsing from) a full-body box
-*  with IoU 0. Used by rescue and spawn-dedup so we do not mint a second id.
-*  A SMALL box nested inside a LARGE one is occlusion, not growth — those
-*  stay two tracks (sort-tracker occlusion suite). */
-function growthAdjacentMatch(track, det) {
+/**
+* Same-class partial crop growing into (or collapsing from) a full-body box
+* with IoU 0. Used by rescue and spawn-dedup so we do not mint a second id.
+* A SMALL box nested inside a LARGE one is occlusion, not growth — those
+* stay two tracks (sort-tracker occlusion suite).
+*
+* **Geometry alone cannot make this gate safe, and that is measured, not
+* assumed.** The two live cases:
+*
+* | case | dist | trackDiag | dist/trackDiag | dist/maxDiag | dt | trackDiag/s |
+* | --- | ---: | ---: | ---: | ---: | ---: | ---: |
+* | `4285605a` bird→dog (KEEP) | 74.7 | 35.8 | 2.085 | 1.238 | 170 ms | 12.26 |
+* | `59dfb972` car A→car B (REJECT) | 573.8 | 529.8 | 1.083 | 0.679 | 106 ms | 10.22 |
+*
+* The theft is a *milder* jump than the case the gate exists for, in EVERY
+* scale-relative measure — and still milder once divided by elapsed time. A
+* scale-invariant geometric predicate that accepts the bird therefore MUST
+* accept the car; so must a speed cap expressed in track-diagonals per second.
+* The separator has to be something other than the shape of the two boxes, and
+* the one that holds is track MATURITY ({@link GROWTH_MAX_TRACK_AGE_MS}).
+*/
+function growthAdjacentMatch(track, det, ctx) {
+	if (ctx.trackAgeMs > 1500) return false;
+	if (ctx.gapMs > 1e3) return false;
 	const trackArea = track.w * track.h;
 	const detArea = det.w * det.h;
 	if (trackArea <= 0 || detArea <= 0) return false;
@@ -29046,8 +29074,24 @@ function growthAdjacentMatch(track, det) {
 	if (intersectionArea(track, det) / smaller >= .5) return false;
 	const tc = bboxCentroid(track);
 	const dc = bboxCentroid(det);
-	return Math.hypot(tc.x - dc.x, tc.y - dc.y) <= GROWTH_CENTROID_FACTOR * Math.max(Math.hypot(track.w, track.h), Math.hypot(det.w, det.h));
+	return Math.hypot(tc.x - dc.x, tc.y - dc.y) <= GROWTH_CENTROID_FACTOR * Math.hypot(track.w, track.h);
 }
+/** Per-(stage, gate) counter + sampling decision. One instance per tracker, so
+*  the counts are per camera and per detection source. */
+var LooseBindSampler = class {
+	counts = /* @__PURE__ */ new Map();
+	/** Increment the (stage, gate) counter and answer with the running total when
+	*  this decision should be reported, or `undefined` when it is sampled out. */
+	next(stage, gate) {
+		const key = `${stage}|${gate}`;
+		const count = (this.counts.get(key) ?? 0) + 1;
+		this.counts.set(key, count);
+		if (count === 1 || count % 50 === 0) return count;
+	}
+	reset() {
+		this.counts.clear();
+	}
+};
 //#endregion
 //#region src/pipeline-analytics/pipeline/tracker/sort-tracker.ts
 var DEFAULT_TRACKER_CONFIG = {
@@ -29125,12 +29169,62 @@ var SortTracker = class SortTracker {
 	* moment the pair stops overlapping and are pruned when either track dies.
 	*/
 	dupStreaks = /* @__PURE__ */ new Map();
+	/** Per-(stage, gate) counters behind the sampled salvage-bind diagnostics. */
+	bindSampler = new LooseBindSampler();
+	/** Sink for salvage-bind diagnostics. Null until an owner that knows the
+	*  `deviceId` wires one — see {@link setBindObserver}. */
+	bindObserver = null;
 	constructor(config = {}) {
 		this.config = {
 			...DEFAULT_TRACKER_CONFIG,
 			...config
 		};
 	}
+	/**
+	* Wire the diagnostics sink for the salvage branches (rescue, resurrection,
+	* growth spawn-dedup). The tracker has no `deviceId`; the caller that does
+	* stamps it on the log line. Stage 1 is never reported — it runs per track
+	* per frame at frame-rate.
+	*/
+	setBindObserver(observer) {
+		this.bindObserver = observer;
+	}
+	/** Emit one salvage decision, subject to {@link LOOSE_BIND_LOG_SAMPLE_EVERY}.
+	*  Nothing is computed when no observer is wired. */
+	reportBind(stage, gate, track, det, timestamp) {
+		const observer = this.bindObserver;
+		if (!observer) return;
+		const bindCount = this.bindSampler.next(stage, gate);
+		if (bindCount === void 0) return;
+		const tc = bboxCentroid(track.bbox);
+		const dc = bboxCentroid(det.bbox);
+		const trackArea = track.bbox.w * track.bbox.h;
+		const detArea = det.bbox.w * det.bbox.h;
+		const smaller = Math.min(trackArea, detArea);
+		observer({
+			stage,
+			gate,
+			trackId: track.id,
+			trackClass: track.class,
+			detClass: det.class,
+			detScore: det.score,
+			iou: iou$2(track.bbox, det.bbox),
+			centroidDistPx: Math.hypot(tc.x - dc.x, tc.y - dc.y),
+			trackDiagPx: Math.hypot(track.bbox.w, track.bbox.h),
+			areaRatio: smaller > 0 ? Math.max(trackArea, detArea) / smaller : 0,
+			dtMs: timestamp - track.lastSeen,
+			trackAgeMs: timestamp - track.firstSeen,
+			bindCount,
+			sampledEvery: 50
+		});
+	}
+	/** When the pair is being judged, relative to `track`. */
+	static growthContext(track, timestamp) {
+		return {
+			trackAgeMs: timestamp - track.firstSeen,
+			gapMs: timestamp - track.lastSeen
+		};
+	}
 	/** Whether two macro-classes may be collapsed as the SAME subject. Same class
 	*  always; the {person,animal} pair only when `personAnimalDedup` is on. */
 	dedupCompatible(a, b) {
@@ -29175,8 +29269,15 @@ var SortTracker = class SortTracker {
 	* set of tracks already surviving this frame (matched, coasting, resurrected,
 	* and earlier same-frame spawns).
 	*/
-	isDuplicateSpawn(det, live) {
-		for (const t of live) if (this.dedupCompatible(t.class, det.class) && (iou$2(det.bbox, t.bbox) >= this.config.dedupSpawnIou || growthAdjacentMatch(t.bbox, det.bbox))) return true;
+	isDuplicateSpawn(det, live, timestamp) {
+		for (const t of live) {
+			if (!this.dedupCompatible(t.class, det.class)) continue;
+			if (iou$2(det.bbox, t.bbox) >= this.config.dedupSpawnIou) return true;
+			if (growthAdjacentMatch(t.bbox, det.bbox, SortTracker.growthContext(t, timestamp))) {
+				this.reportBind("spawn-dedup", "growth", t, det, timestamp);
+				return true;
+			}
+		}
 		if (this.config.personAnimalDedup && det.class === ANIMAL_CLASS && det.score < this.config.animalOverPersonMaxScore) {
 			for (const t of live) if (t.class === PERSON_CLASS && iou$2(det.bbox, t.bbox) >= this.config.animalOverPersonIou) return true;
 		}
@@ -29263,15 +29364,36 @@ var SortTracker = class SortTracker {
 	* crouch→animal flip when `classGroupAssoc` is on, but never by an unrelated
 	* class.
 	*/
-	looseMatch(track, det) {
-		if (this.assocGroup(track.class) !== this.assocGroup(det.class)) return false;
-		if (iou$2(track.bbox, det.bbox) >= this.config.rescueIouThreshold) return true;
+	looseMatch(track, det, timestamp) {
+		if (this.assocGroup(track.class) !== this.assocGroup(det.class)) return null;
+		if (iou$2(track.bbox, det.bbox) >= this.config.rescueIouThreshold) return "iou";
 		const tc = bboxCentroid(track.bbox);
 		const dc = bboxCentroid(det.bbox);
 		const dist = Math.hypot(tc.x - dc.x, tc.y - dc.y);
 		const diag = Math.hypot(track.bbox.w, track.bbox.h);
-		if (dist <= this.config.rescueCentroidFactor * diag) return true;
-		return growthAdjacentMatch(track.bbox, det.bbox);
+		if (dist <= this.config.rescueCentroidFactor * diag) return "centroid";
+		if (growthAdjacentMatch(track.bbox, det.bbox, SortTracker.growthContext(track, timestamp))) return "growth";
+		return null;
+	}
+	/**
+	* Whether `det` would mint a track of its own if no salvage branch claimed it:
+	* it clears BOTH spawn floors (per-class score, per-class bbox-area fraction).
+	*
+	* A rescue that rests on PROXIMITY ALONE — the `centroid` clause, reached only
+	* when the overlap is already below `rescueIouThreshold` — must lose to such a
+	* detection. Live track `27855a56` bound a second car 452 px away at IoU 0.058
+	* purely because 452 ≤ 0.75 × the 589×445 track diagonal; the box it stole was
+	* a full-size, floor-clearing vehicle that would have spawned perfectly well
+	* on its own. **A spare track costs media; a stolen track corrupts the plate,
+	* the travelled distance and the last frame of the track it was taken from.**
+	*
+	* The `iou` clause is untouched (real overlap IS evidence), and so is `growth`
+	* — that one is bounded by track maturity inside `growthAdjacentMatch`, and a
+	* partial crop is by construction the same subject, so refusing it here would
+	* re-fragment `4285605a`.
+	*/
+	isPlausibleBirth(det, frameArea) {
+		return this.meetsClassScoreFloor(det) && this.meetsSpawnAreaFloor(det, frameArea);
 	}
 	/** Fold a matched detection's class + score into a track's lifetime vote
 	*  tally. A non-positive score still counts as an infinitesimal vote so a
@@ -29385,20 +29507,25 @@ var SortTracker = class SortTracker {
 			for (let di = 0; di < detections.length; di++) {
 				if (used.has(di) || lowSet.has(di)) continue;
 				const det = detections[di];
-				if (!this.looseMatch(track, det)) continue;
+				const gate = this.looseMatch(track, det, timestamp);
+				if (gate === null) continue;
+				if (gate === "centroid" && this.isPlausibleBirth(det, frameArea)) continue;
 				rescuePairs.push({
 					track,
 					detIdx: di,
-					score: iou$2(track.bbox, det.bbox)
+					score: iou$2(track.bbox, det.bbox),
+					gate
 				});
 			}
 		}
 		rescuePairs.sort((a, b) => b.score - a.score);
 		for (const pair of rescuePairs) {
 			if (matchedTracks.has(pair.track) || used.has(pair.detIdx)) continue;
-			matched.set(pair.track, detections[pair.detIdx]);
+			const det = detections[pair.detIdx];
+			matched.set(pair.track, det);
 			matchedTracks.add(pair.track);
 			used.add(pair.detIdx);
+			this.reportBind("rescue", pair.gate, pair.track, det, timestamp);
 		}
 		if (this.config.byteTrackEnabled && lowIdxs.length > 0) this.greedyAssociate(detections, lowIdxs, this.config.byteTrackLowIouThreshold, used, matchedTracks, matched);
 		for (const [track, det] of matched) {
@@ -29452,17 +29579,22 @@ var SortTracker = class SortTracker {
 			const det = detections[di];
 			let best;
 			let bestScore = -1;
+			let bestGate = "iou";
 			for (const lost of this.lostTracks) {
 				if (!lost.resurrectable) continue;
 				if (timestamp - lost.lostAt > this.config.resurrectionWindowMs) continue;
-				if (!this.looseMatch(lost, det)) continue;
+				const gate = this.looseMatch(lost, det, timestamp);
+				if (gate === null) continue;
+				if (gate === "centroid" && this.isPlausibleBirth(det, frameArea)) continue;
 				const score = iou$2(lost.bbox, det.bbox);
 				if (score > bestScore) {
 					best = lost;
 					bestScore = score;
+					bestGate = gate;
 				}
 			}
 			if (!best) continue;
+			this.reportBind("resurrection", bestGate, best, det, timestamp);
 			this.lostTracks = this.lostTracks.filter((t) => t !== best);
 			best.bbox = det.bbox;
 			best.class = det.class;
@@ -29502,7 +29634,7 @@ var SortTracker = class SortTracker {
 				continue;
 			}
 			if (this.config.occlusionEnabled && occluderBoxes.some((ob) => containment(det.bbox, ob) >= this.config.occlusionContainment)) continue;
-			if (this.config.dedupEnabled && this.isDuplicateSpawn(det, surviving)) {
+			if (this.config.dedupEnabled && this.isDuplicateSpawn(det, surviving, timestamp)) {
 				used.add(di);
 				continue;
 			}
@@ -29561,6 +29693,7 @@ var SortTracker = class SortTracker {
 		this.tracks = [];
 		this.lostTracks = [];
 		this.dupStreaks.clear();
+		this.bindSampler.reset();
 	}
 };
 //#endregion
@@ -29977,6 +30110,16 @@ var FrameProcessor = class {
 	setStationaryGate(gate) {
 		this.stationaryGate = gate;
 	}
+	/**
+	* Wire (or clear) the tracker's salvage-bind diagnostics sink. The tracker
+	* itself knows no `deviceId`; the addon that owns this processor stamps
+	* `tags: { deviceId }` on the line — see the wiring in `pipeline-analytics`.
+	* Only the rescue / resurrection / growth branches report, and they report
+	* sampled: stage 1 runs per track per frame at frame-rate.
+	*/
+	setBindObserver(observer) {
+		this.tracker.setBindObserver(observer);
+	}
 	/** Forget a track in the underlying tracker (used when the addon promotes it
 	*  to a stationary-object registry entry). */
 	dropTrack(trackId) {
@@ -34936,6 +35079,70 @@ async function makeSquareThumb(bytes, size) {
 	}).jpeg({ quality: THUMB_QUALITY }).toBuffer();
 }
 //#endregion
+//#region src/pipeline-analytics/track-media-scope.ts
+/** The stored kind a detail owner's crop is written with. */
+var STORED_DETAIL_CROP_KIND = "crop";
+/** The kinds only a detail owner can produce. */
+var DETAIL_CROP_KINDS = ["faceCrop", "plateCrop"];
+/**
+* Every owner that holds media for `trackId`, in publication order (the track's
+* own rows first, then face, then plate).
+*/
+function trackMediaOwnerScopes(trackId) {
+	return [
+		{
+			ownerKind: "track",
+			ownerId: trackId,
+			publishCropAs: null
+		},
+		{
+			ownerKind: "face",
+			ownerId: `${FACE_MEDIA_OWNER_PREFIX}${trackId}`,
+			publishCropAs: "faceCrop"
+		},
+		{
+			ownerKind: "plate",
+			ownerId: `${PLATE_MEDIA_OWNER_PREFIX}${trackId}`,
+			publishCropAs: "plateCrop"
+		}
+	];
+}
+/**
+* The scopes worth READING for a `kinds`-filtered request.
+*
+* A detail owner can only ever publish `faceCrop` / `plateCrop`, so a request
+* that names neither is answered without opening those two owners — which is
+* what keeps the common per-entry fetch (`kinds: ['keyFrameSmall']`) at exactly
+* its previous cost. The track scope is never skipped: it is the only owner
+* whose kinds are open-ended, and dropping it on a guess is how a listing
+* starts lying about what a track has.
+*/
+function trackMediaScopesForKinds(trackId, kinds) {
+	const scopes = trackMediaOwnerScopes(trackId);
+	if (kinds === void 0 || kinds.length === 0) return scopes;
+	return kinds.some((kind) => DETAIL_CROP_KINDS.includes(kind)) ? scopes : scopes.filter((scope) => scope.publishCropAs === null);
+}
+/**
+* Fold every scope's rows into ONE track media listing: detail crops
+* relabelled, everything filtered to `kinds`, ordered oldest first.
+*
+* `relabel` is injected rather than spread inline so the caller keeps its own
+* concrete row type (`MediaFile` with bytes, `MediaFileInfo` without) — there
+* is no cast and no third shape in between.
+*/
+function collectTrackMedia(scoped, relabel, kinds) {
+	const out = [];
+	for (const { scope, rows } of scoped) for (const row of rows) {
+		if (scope.publishCropAs === null) {
+			out.push(row);
+			continue;
+		}
+		if (row.kind !== STORED_DETAIL_CROP_KIND) continue;
+		out.push(relabel(row, scope.publishCropAs));
+	}
+	return (kinds === void 0 || kinds.length === 0 ? out : out.filter((row) => kinds.includes(row.kind))).toSorted((a, b) => a.timestamp - b.timestamp);
+}
+//#endregion
 //#region src/pipeline-analytics/zone-name-stamp.ts
 /**
 * Copy each track with `zoneNames` stamped on.
@@ -35055,10 +35262,25 @@ var AnalyticsQueryFacade = class {
 		const all = await (this.deps.mediaStore()?.listByOwner("event", input.eventId, input.deviceId) ?? Promise.resolve([]));
 		return input.kind ? all.filter((m) => m.kind === input.kind) : all;
 	}
+	/**
+	* A track's media WITH the bytes, restricted to `kinds` when given.
+	*
+	* Reads every owner a track's media lives under — its own rows plus the face
+	* and plate detail crops, whose stored `kind: 'crop'` is published as
+	* `faceCrop` / `plateCrop`. See `track-media-scope.ts` for why the rename
+	* happens on the way out and not in the caller's question.
+	*/
 	async getTrackMedia(input) {
-		const all = await (this.deps.mediaStore()?.listByOwner("track", input.trackId, input.deviceId) ?? Promise.resolve([]));
-		const kinds = input.kinds;
-		return kinds && kinds.length > 0 ? all.filter((m) => kinds.includes(m.kind)) : all;
+		const store = this.deps.mediaStore();
+		if (store === null) return [];
+		const scopes = trackMediaScopesForKinds(input.trackId, input.kinds);
+		return collectTrackMedia(await Promise.all(scopes.map(async (scope) => ({
+			scope,
+			rows: await store.listByOwner(scope.ownerKind, scope.ownerId, input.deviceId)
+		}))), (row, kind) => ({
+			...row,
+			kind
+		}), input.kinds);
 	}
 	/**
 	* A track's media WITHOUT the bytes.
@@ -35068,9 +35290,21 @@ var AnalyticsQueryFacade = class {
 	* that path reads every blob off disk and base64-encodes it first, so the
 	* response would shrink while the work did not. Measured: 7.67 MB read and
 	* ~10 MB of string allocated, to answer a question the index already holds.
+	*
+	* Covers the same owners as {@link getTrackMedia} — a manifest that listed
+	* fewer keys than the byte read can serve (or more) is the disagreement the
+	* viewer's per-entry loader turns into a red triangle.
 	*/
 	async listTrackMedia(input) {
-		return this.deps.mediaStore()?.listInfoByOwner("track", input.trackId, input.deviceId) ?? Promise.resolve([]);
+		const store = this.deps.mediaStore();
+		if (store === null) return [];
+		return collectTrackMedia(await Promise.all(trackMediaOwnerScopes(input.trackId).map(async (scope) => ({
+			scope,
+			rows: await store.listInfoByOwner(scope.ownerKind, scope.ownerId, input.deviceId)
+		}))), (row, kind) => ({
+			...row,
+			kind
+		}), void 0);
 	}
 	async pruneEventsBefore(input) {
 		const eventStore = this.deps.eventStore();
@@ -64782,6 +65016,15 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 				cooldownSec,
 				minTrackAgeMs: trk.minTrackAgeMs
 			}, source);
+			p.setBindObserver((record) => {
+				this.ctx.logger.debug("tracker: salvage bind", {
+					tags: { deviceId },
+					meta: {
+						source,
+						...record
+					}
+				});
+			});
 			p.setTrackLabelState((trackId) => {
 				const active = this.trackStore?.getActiveByTrack(trackId);
 				return active !== null && active !== void 0 ? {