@camstack/addon-post-analysis 1.2.139 → 1.2.141

package/dist/pipeline-analytics/index.js

@@ -30502,6 +30502,8 @@ var DEFAULT_TRACKER_CONFIG = {
 	rescueIouThreshold: .1,
 	rescueCentroidFactor: .75,
 	resurrectionWindowMs: 8e3,
+	resurrectionCrowdGuard: true,
+	resurrectionCrowdedIouThreshold: .3,
 	stationarySpeedPx: 2,
 	dedupEnabled: true,
 	dedupSpawnIou: .6,
@@ -30751,6 +30753,35 @@ var SortTracker = class SortTracker {
 		};
 	}
 	/**
+	* How many same-association-group subjects OTHER than `corpse` share the
+	* scene with it: every track LIVE on this frame, plus any other resurrectable
+	* corpse whose lifetime OVERLAPPED the candidate's.
+	*
+	* The overlap clause on the graveyard half is what keeps this guard off the
+	* case the resurrection pass exists for. A single flickering subject leaves a
+	* TRAIL of corpses behind it — that trail is the fragmentation the pass
+	* repairs — but those fragments never coexist: each is born only after the
+	* previous one died. Two distinct people do coexist. Counting corpses without
+	* the overlap test would let a subject's own debris read as a crowd and
+	* re-fragment the very case being protected.
+	*
+	* A live track is counted unconditionally, overlap or not: the subject that
+	* steals an id is very often one whose OWN track was born after the corpse
+	* died (camera 618 — the toddler's track post-dates the older boy's).
+	*/
+	sameGroupPeerCount(corpse, live) {
+		const group = this.assocGroup(corpse.class);
+		let peers = 0;
+		for (const t of live) if (t !== corpse && this.assocGroup(t.class) === group) peers++;
+		for (const other of this.lostTracks) {
+			if (other === corpse) continue;
+			if (!other.resurrectable) continue;
+			if (this.assocGroup(other.class) !== group) continue;
+			if (other.firstSeen <= corpse.lastSeen && corpse.firstSeen <= other.lastSeen) peers++;
+		}
+		return peers;
+	}
+	/**
 	* Loose same-group gate used by the rescue and resurrection passes: accept
 	* when the detection overlaps the track's LAST-KNOWN bbox by `rescueIou`, or
 	* its centroid is within `rescueCentroidFactor × bbox-diagonal`. Always group-
@@ -30865,6 +30896,7 @@ var SortTracker = class SortTracker {
 	}
 	update(detections, timestamp, frameContext) {
 		const frameArea = frameContext ? frameContext.frameWidth * frameContext.frameHeight : 0;
+		const resurrectedScene = /* @__PURE__ */ new Map();
 		if (this.config.maxTrackLifetimeMs > 0) {
 			const alive = [];
 			for (const track of this.tracks) if (timestamp - track.firstSeen > this.config.maxTrackLifetimeMs) {
@@ -30975,6 +31007,10 @@ var SortTracker = class SortTracker {
 			let best;
 			let bestScore = -1;
 			let bestGate = "iou";
+			let bestPeers = 0;
+			let refused;
+			let refusedGate = "iou";
+			let refusedScore = -1;
 			for (const lost of this.lostTracks) {
 				if (!lost.resurrectable) continue;
 				if (timestamp - lost.lostAt > this.config.resurrectionWindowMs) continue;
@@ -30982,13 +31018,27 @@ var SortTracker = class SortTracker {
 				if (gate === null) continue;
 				if (gate === "centroid" && this.isPlausibleBirth(det, frameArea)) continue;
 				const score = iou$2(lost.bbox, det.bbox);
+				const peers = this.sameGroupPeerCount(lost, surviving);
+				if (this.config.resurrectionCrowdGuard && peers > 0 && score < this.config.resurrectionCrowdedIouThreshold) {
+					if (score > refusedScore) {
+						refused = lost;
+						refusedGate = gate;
+						refusedScore = score;
+					}
+					continue;
+				}
 				if (score > bestScore) {
 					best = lost;
 					bestScore = score;
 					bestGate = gate;
+					bestPeers = peers;
 				}
 			}
-			if (!best) continue;
+			if (!best) {
+				if (refused !== void 0) this.reportBind("resurrection-refused", refusedGate, refused, det, timestamp);
+				continue;
+			}
+			resurrectedScene.set(best, bestPeers > 0 ? "multi-subject" : "sole-subject");
 			this.reportBind("resurrection", bestGate, best, det, timestamp);
 			this.lostTracks = this.lostTracks.filter((t) => t !== best);
 			best.bbox = det.bbox;
@@ -31056,17 +31106,21 @@ var SortTracker = class SortTracker {
 		}
 		this.tracks = surviving;
 		this.resolveDuplicates();
-		return this.tracks.filter((t) => this.isConfirmedForEmit(t)).map((t) => ({
-			class: this.resolveReportedClass(t),
-			originalClass: t.originalClass,
-			score: t.score,
-			bbox: t.bbox,
-			trackId: t.id,
-			trackAge: t.hits,
-			velocity: t.velocity,
-			path: [...t.path],
-			matchedThisFrame: t.lastSeen === timestamp
-		}));
+		return this.tracks.filter((t) => this.isConfirmedForEmit(t)).map((t) => {
+			const scene = resurrectedScene.get(t);
+			return {
+				class: this.resolveReportedClass(t),
+				originalClass: t.originalClass,
+				score: t.score,
+				bbox: t.bbox,
+				trackId: t.id,
+				trackAge: t.hits,
+				velocity: t.velocity,
+				path: [...t.path],
+				matchedThisFrame: t.lastSeen === timestamp,
+				...scene !== void 0 ? { resurrectionScene: scene } : {}
+			};
+		});
 	}
 	/**
 	* Remove a track from BOTH the live and graveyard sets so it neither emits
@@ -31780,6 +31834,7 @@ var FrameProcessor = class {
 				zones: zonesByTrack.get(td.trackId) ?? [],
 				state,
 				matchedThisFrame: td.matchedThisFrame !== false,
+				...td.resurrectionScene !== void 0 ? { resurrectionScene: td.resurrectionScene } : {},
 				...labelPatch !== void 0 ? { labelPatch } : {},
 				...emb !== void 0 ? {
 					embedding: emb.embedding,
@@ -38750,8 +38805,77 @@ var FaceRecognizer = class {
 			}
 		});
 	}
+	/**
+	* The track id this face is held under was re-attached from the graveyard in a
+	* scene that had other same-class subjects in it, so the id's continuity is no
+	* longer self-evident. Stop vouching for what is held, without throwing it
+	* away (D282).
+	*
+	* Three things happen, and the asymmetry between them is the whole decision:
+	*
+	* • the crop and the embedding are KEPT. Discarding them would punish exactly
+	*   the case the resurrection pass exists to serve — one subject flickering in
+	*   and out — and a good face is not cheap to come by.
+	* • `recognizedIdentityId` is STRIPPED, along with the peak match/suggestion
+	*   scores. An identity is a claim about WHO, and the one fact just
+	*   established is that nobody knows who this id is on any more.
+	* • the face becomes non-promotable: {@link onTrackEnd} will not write it to
+	*   the gallery while the flag stands.
+	*
+	* The aggregate is deliberately left alone — see the note in `onTrackEnd`.
+	*/
+	quarantineHeldFace(deviceId, trackId) {
+		const held = this.bestFace.get(trackId);
+		if (held === void 0 || held.unverified === true) return;
+		const quarantined = {
+			score: held.score,
+			embedding: held.embedding,
+			embeddingModelId: held.embeddingModelId,
+			bbox: held.bbox,
+			timestamp: held.timestamp,
+			unverified: true,
+			...held.crop !== void 0 ? { crop: held.crop } : {},
+			...held.nativeFaceShortSidePx !== void 0 ? { nativeFaceShortSidePx: held.nativeFaceShortSidePx } : {}
+		};
+		this.bestFace.set(trackId, quarantined);
+		this.bestMatchScore.delete(trackId);
+		this.bestSuggestion.delete(trackId);
+		this.deps.logger.info("face: held face unverified — track id re-attached in a crowded scene", {
+			tags: {
+				deviceId,
+				trackId
+			},
+			meta: {
+				heldScore: held.score,
+				heldAt: held.timestamp,
+				strippedIdentityId: held.recognizedIdentityId ?? null,
+				hasCrop: held.crop !== void 0
+			}
+		});
+	}
+	/**
+	* Ask a FRESH face whether the quarantined held face is still about the same
+	* person, at the same bar the gallery uses to say two vectors are one person
+	* (`similarityThreshold` — one knob over one band, D222).
+	*
+	* Only a face-BEARING frame may answer. An embedding inherited onto the person
+	* track on a face-less frame is the held vector's own descendant, so it would
+	* confirm itself; callers gate on `faceBbox` being present.
+	*/
+	verifyHeldFace(held, probe, threshold) {
+		if (held.embeddingModelId !== probe.embeddingModelId || held.embedding.length !== probe.embedding.length) return {
+			verdict: "incomparable",
+			cosine: 0
+		};
+		const cosine = require_dist.cosineSimilarity(new Float32Array(held.embedding), new Float32Array(probe.embedding));
+		return {
+			verdict: cosine >= threshold ? "confirmed" : "rejected",
+			cosine
+		};
+	}
 	async processFrame(input) {
 		const { settings } = input;
+		for (const t of input.tracked) if (t.resurrectionScene === "multi-subject") this.quarantineHeldFace(input.deviceId, t.trackId);
 		const candidates = input.tracked.filter((t) => Array.isArray(t.embedding) && t.embedding.length > 0 && typeof t.embeddingModelId === "string" && t.confidence >= settings.minFaceConfidence && (t.nativeFaceShortSidePx ?? (t.faceBbox ? Math.min(t.faceBbox.w, t.faceBbox.h) : void 0) ?? Number.POSITIVE_INFINITY) >= settings.minFacePx);
 		if (candidates.length === 0) return;
 		this.deps.logger.debug("face: frame candidates", {
@@ -38811,6 +38935,35 @@ var FaceRecognizer = class {
 		}
 		const labelWork = [];
 		for (const c of candidates) {
+			const quarantined = this.bestFace.get(c.trackId);
+			if (quarantined?.unverified === true && c.faceBbox !== void 0) {
+				const { verdict, cosine } = this.verifyHeldFace(quarantined, {
+					embedding: c.embedding,
+					embeddingModelId: c.embeddingModelId
+				}, settings.similarityThreshold);
+				if (verdict === "confirmed") this.bestFace.set(c.trackId, {
+					...quarantined,
+					unverified: false
+				});
+				else if (verdict === "rejected") {
+					this.bestFace.delete(c.trackId);
+					this.bestTracker.delete(c.trackId);
+					this.aggregates.delete(c.trackId);
+				}
+				if (verdict !== "confirmed") this.deps.logger.info("face: held face not confirmed after a crowded re-attach", {
+					tags: {
+						deviceId: input.deviceId,
+						trackId: c.trackId
+					},
+					meta: {
+						verdict,
+						cosine: Number(cosine.toFixed(3)),
+						threshold: settings.similarityThreshold,
+						heldAt: quarantined.timestamp,
+						droppedHeldFace: verdict === "rejected"
+					}
+				});
+			}
 			const match = matches.get(c.trackId) ?? null;
 			const { state, changed } = updateTrackAggregate(this.aggregates.get(c.trackId) ?? EMPTY_AGGREGATE, match, { confirmFrames: settings.confirmFrames });
 			this.aggregates.set(c.trackId, state);
@@ -38981,6 +39134,20 @@ var FaceRecognizer = class {
 			} });
 			return;
 		}
+		if (held.unverified === true) {
+			this.deps.logger.info("face: dropping unverified held face at close", {
+				tags: {
+					deviceId,
+					trackId
+				},
+				meta: {
+					score: held.score,
+					heldAt: held.timestamp,
+					hasCrop: held.crop !== void 0
+				}
+			});
+			return;
+		}
 		if (held.crop === void 0) {
 			const now = Date.now();
 			if (now - this.lastImagelessLogAt >= FACE_IMAGELESS_LOG_THROTTLE_MS) {

package/dist/pipeline-analytics/index.mjs

@@ -30477,6 +30477,8 @@ var DEFAULT_TRACKER_CONFIG = {
 	rescueIouThreshold: .1,
 	rescueCentroidFactor: .75,
 	resurrectionWindowMs: 8e3,
+	resurrectionCrowdGuard: true,
+	resurrectionCrowdedIouThreshold: .3,
 	stationarySpeedPx: 2,
 	dedupEnabled: true,
 	dedupSpawnIou: .6,
@@ -30726,6 +30728,35 @@ var SortTracker = class SortTracker {
 		};
 	}
 	/**
+	* How many same-association-group subjects OTHER than `corpse` share the
+	* scene with it: every track LIVE on this frame, plus any other resurrectable
+	* corpse whose lifetime OVERLAPPED the candidate's.
+	*
+	* The overlap clause on the graveyard half is what keeps this guard off the
+	* case the resurrection pass exists for. A single flickering subject leaves a
+	* TRAIL of corpses behind it — that trail is the fragmentation the pass
+	* repairs — but those fragments never coexist: each is born only after the
+	* previous one died. Two distinct people do coexist. Counting corpses without
+	* the overlap test would let a subject's own debris read as a crowd and
+	* re-fragment the very case being protected.
+	*
+	* A live track is counted unconditionally, overlap or not: the subject that
+	* steals an id is very often one whose OWN track was born after the corpse
+	* died (camera 618 — the toddler's track post-dates the older boy's).
+	*/
+	sameGroupPeerCount(corpse, live) {
+		const group = this.assocGroup(corpse.class);
+		let peers = 0;
+		for (const t of live) if (t !== corpse && this.assocGroup(t.class) === group) peers++;
+		for (const other of this.lostTracks) {
+			if (other === corpse) continue;
+			if (!other.resurrectable) continue;
+			if (this.assocGroup(other.class) !== group) continue;
+			if (other.firstSeen <= corpse.lastSeen && corpse.firstSeen <= other.lastSeen) peers++;
+		}
+		return peers;
+	}
+	/**
 	* Loose same-group gate used by the rescue and resurrection passes: accept
 	* when the detection overlaps the track's LAST-KNOWN bbox by `rescueIou`, or
 	* its centroid is within `rescueCentroidFactor × bbox-diagonal`. Always group-
@@ -30840,6 +30871,7 @@ var SortTracker = class SortTracker {
 	}
 	update(detections, timestamp, frameContext) {
 		const frameArea = frameContext ? frameContext.frameWidth * frameContext.frameHeight : 0;
+		const resurrectedScene = /* @__PURE__ */ new Map();
 		if (this.config.maxTrackLifetimeMs > 0) {
 			const alive = [];
 			for (const track of this.tracks) if (timestamp - track.firstSeen > this.config.maxTrackLifetimeMs) {
@@ -30950,6 +30982,10 @@ var SortTracker = class SortTracker {
 			let best;
 			let bestScore = -1;
 			let bestGate = "iou";
+			let bestPeers = 0;
+			let refused;
+			let refusedGate = "iou";
+			let refusedScore = -1;
 			for (const lost of this.lostTracks) {
 				if (!lost.resurrectable) continue;
 				if (timestamp - lost.lostAt > this.config.resurrectionWindowMs) continue;
@@ -30957,13 +30993,27 @@ var SortTracker = class SortTracker {
 				if (gate === null) continue;
 				if (gate === "centroid" && this.isPlausibleBirth(det, frameArea)) continue;
 				const score = iou$2(lost.bbox, det.bbox);
+				const peers = this.sameGroupPeerCount(lost, surviving);
+				if (this.config.resurrectionCrowdGuard && peers > 0 && score < this.config.resurrectionCrowdedIouThreshold) {
+					if (score > refusedScore) {
+						refused = lost;
+						refusedGate = gate;
+						refusedScore = score;
+					}
+					continue;
+				}
 				if (score > bestScore) {
 					best = lost;
 					bestScore = score;
 					bestGate = gate;
+					bestPeers = peers;
 				}
 			}
-			if (!best) continue;
+			if (!best) {
+				if (refused !== void 0) this.reportBind("resurrection-refused", refusedGate, refused, det, timestamp);
+				continue;
+			}
+			resurrectedScene.set(best, bestPeers > 0 ? "multi-subject" : "sole-subject");
 			this.reportBind("resurrection", bestGate, best, det, timestamp);
 			this.lostTracks = this.lostTracks.filter((t) => t !== best);
 			best.bbox = det.bbox;
@@ -31031,17 +31081,21 @@ var SortTracker = class SortTracker {
 		}
 		this.tracks = surviving;
 		this.resolveDuplicates();
-		return this.tracks.filter((t) => this.isConfirmedForEmit(t)).map((t) => ({
-			class: this.resolveReportedClass(t),
-			originalClass: t.originalClass,
-			score: t.score,
-			bbox: t.bbox,
-			trackId: t.id,
-			trackAge: t.hits,
-			velocity: t.velocity,
-			path: [...t.path],
-			matchedThisFrame: t.lastSeen === timestamp
-		}));
+		return this.tracks.filter((t) => this.isConfirmedForEmit(t)).map((t) => {
+			const scene = resurrectedScene.get(t);
+			return {
+				class: this.resolveReportedClass(t),
+				originalClass: t.originalClass,
+				score: t.score,
+				bbox: t.bbox,
+				trackId: t.id,
+				trackAge: t.hits,
+				velocity: t.velocity,
+				path: [...t.path],
+				matchedThisFrame: t.lastSeen === timestamp,
+				...scene !== void 0 ? { resurrectionScene: scene } : {}
+			};
+		});
 	}
 	/**
 	* Remove a track from BOTH the live and graveyard sets so it neither emits
@@ -31755,6 +31809,7 @@ var FrameProcessor = class {
 				zones: zonesByTrack.get(td.trackId) ?? [],
 				state,
 				matchedThisFrame: td.matchedThisFrame !== false,
+				...td.resurrectionScene !== void 0 ? { resurrectionScene: td.resurrectionScene } : {},
 				...labelPatch !== void 0 ? { labelPatch } : {},
 				...emb !== void 0 ? {
 					embedding: emb.embedding,
@@ -38687,8 +38742,77 @@ var FaceRecognizer = class {
 			}
 		});
 	}
+	/**
+	* The track id this face is held under was re-attached from the graveyard in a
+	* scene that had other same-class subjects in it, so the id's continuity is no
+	* longer self-evident. Stop vouching for what is held, without throwing it
+	* away (D282).
+	*
+	* Three things happen, and the asymmetry between them is the whole decision:
+	*
+	* • the crop and the embedding are KEPT. Discarding them would punish exactly
+	*   the case the resurrection pass exists to serve — one subject flickering in
+	*   and out — and a good face is not cheap to come by.
+	* • `recognizedIdentityId` is STRIPPED, along with the peak match/suggestion
+	*   scores. An identity is a claim about WHO, and the one fact just
+	*   established is that nobody knows who this id is on any more.
+	* • the face becomes non-promotable: {@link onTrackEnd} will not write it to
+	*   the gallery while the flag stands.
+	*
+	* The aggregate is deliberately left alone — see the note in `onTrackEnd`.
+	*/
+	quarantineHeldFace(deviceId, trackId) {
+		const held = this.bestFace.get(trackId);
+		if (held === void 0 || held.unverified === true) return;
+		const quarantined = {
+			score: held.score,
+			embedding: held.embedding,
+			embeddingModelId: held.embeddingModelId,
+			bbox: held.bbox,
+			timestamp: held.timestamp,
+			unverified: true,
+			...held.crop !== void 0 ? { crop: held.crop } : {},
+			...held.nativeFaceShortSidePx !== void 0 ? { nativeFaceShortSidePx: held.nativeFaceShortSidePx } : {}
+		};
+		this.bestFace.set(trackId, quarantined);
+		this.bestMatchScore.delete(trackId);
+		this.bestSuggestion.delete(trackId);
+		this.deps.logger.info("face: held face unverified — track id re-attached in a crowded scene", {
+			tags: {
+				deviceId,
+				trackId
+			},
+			meta: {
+				heldScore: held.score,
+				heldAt: held.timestamp,
+				strippedIdentityId: held.recognizedIdentityId ?? null,
+				hasCrop: held.crop !== void 0
+			}
+		});
+	}
+	/**
+	* Ask a FRESH face whether the quarantined held face is still about the same
+	* person, at the same bar the gallery uses to say two vectors are one person
+	* (`similarityThreshold` — one knob over one band, D222).
+	*
+	* Only a face-BEARING frame may answer. An embedding inherited onto the person
+	* track on a face-less frame is the held vector's own descendant, so it would
+	* confirm itself; callers gate on `faceBbox` being present.
+	*/
+	verifyHeldFace(held, probe, threshold) {
+		if (held.embeddingModelId !== probe.embeddingModelId || held.embedding.length !== probe.embedding.length) return {
+			verdict: "incomparable",
+			cosine: 0
+		};
+		const cosine = cosineSimilarity$1(new Float32Array(held.embedding), new Float32Array(probe.embedding));
+		return {
+			verdict: cosine >= threshold ? "confirmed" : "rejected",
+			cosine
+		};
+	}
 	async processFrame(input) {
 		const { settings } = input;
+		for (const t of input.tracked) if (t.resurrectionScene === "multi-subject") this.quarantineHeldFace(input.deviceId, t.trackId);
 		const candidates = input.tracked.filter((t) => Array.isArray(t.embedding) && t.embedding.length > 0 && typeof t.embeddingModelId === "string" && t.confidence >= settings.minFaceConfidence && (t.nativeFaceShortSidePx ?? (t.faceBbox ? Math.min(t.faceBbox.w, t.faceBbox.h) : void 0) ?? Number.POSITIVE_INFINITY) >= settings.minFacePx);
 		if (candidates.length === 0) return;
 		this.deps.logger.debug("face: frame candidates", {
@@ -38748,6 +38872,35 @@ var FaceRecognizer = class {
 		}
 		const labelWork = [];
 		for (const c of candidates) {
+			const quarantined = this.bestFace.get(c.trackId);
+			if (quarantined?.unverified === true && c.faceBbox !== void 0) {
+				const { verdict, cosine } = this.verifyHeldFace(quarantined, {
+					embedding: c.embedding,
+					embeddingModelId: c.embeddingModelId
+				}, settings.similarityThreshold);
+				if (verdict === "confirmed") this.bestFace.set(c.trackId, {
+					...quarantined,
+					unverified: false
+				});
+				else if (verdict === "rejected") {
+					this.bestFace.delete(c.trackId);
+					this.bestTracker.delete(c.trackId);
+					this.aggregates.delete(c.trackId);
+				}
+				if (verdict !== "confirmed") this.deps.logger.info("face: held face not confirmed after a crowded re-attach", {
+					tags: {
+						deviceId: input.deviceId,
+						trackId: c.trackId
+					},
+					meta: {
+						verdict,
+						cosine: Number(cosine.toFixed(3)),
+						threshold: settings.similarityThreshold,
+						heldAt: quarantined.timestamp,
+						droppedHeldFace: verdict === "rejected"
+					}
+				});
+			}
 			const match = matches.get(c.trackId) ?? null;
 			const { state, changed } = updateTrackAggregate(this.aggregates.get(c.trackId) ?? EMPTY_AGGREGATE, match, { confirmFrames: settings.confirmFrames });
 			this.aggregates.set(c.trackId, state);
@@ -38918,6 +39071,20 @@ var FaceRecognizer = class {
 			} });
 			return;
 		}
+		if (held.unverified === true) {
+			this.deps.logger.info("face: dropping unverified held face at close", {
+				tags: {
+					deviceId,
+					trackId
+				},
+				meta: {
+					score: held.score,
+					heldAt: held.timestamp,
+					hasCrop: held.crop !== void 0
+				}
+			});
+			return;
+		}
 		if (held.crop === void 0) {
 			const now = Date.now();
 			if (now - this.lastImagelessLogAt >= FACE_IMAGELESS_LOG_THROTTLE_MS) {

package/package.json

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