@camstack/addon-post-analysis 1.2.218 → 1.2.219

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-CbQHenLE.js");
+const require_dist = require("../dist-Cnlk6Tyz.js");
 let node_fs = require("node:fs");
 node_fs = require_dist.__toESM(node_fs, 1);
 let node_path = require("node:path");
@@ -8341,8 +8341,55 @@ function incomingFromSystemEvent(event, lookup) {
 		default: return null;
 	}
 }
+/** The shells whose update has its own sentence. Anything else gets the plain
+*  one: a body that names a shell nobody observed is worse than a vague body. */
+var WRAPPER_BODY_KINDS = new Set([
+	"docker",
+	"electron",
+	"native"
+]);
+/**
+* The SHELL announcement (D437) — the container / app bundle a node runs
+* inside is behind the release contract.
+*
+* It is deliberately NOT folded into `server-update-available`: the versions
+* here are the shell's (a seed closure, an app bundle), not the running code's,
+* and on 2026-08-02 the running code was perfectly current on a hub whose image
+* was 13 days old from a repository nothing rebuilt. It also mints no button —
+* no process can replace the shell it is running inside — so the BODY is the
+* whole delivery, and it is chosen by `wrapperKind` so a docker operator is
+* handed the exact command instead of a button that cannot exist.
+*/
+function incomingFromWrapperUpdate(facts, data) {
+	const packages = updatePackages(data);
+	if (packages.length === 0) return null;
+	const head = packages[0];
+	const nodeId = head.nodeId ?? stringField(data, "nodeId");
+	const wrapperKind = stringField(data, "wrapperKind");
+	const bodySuffix = wrapperKind !== void 0 && WRAPPER_BODY_KINDS.has(wrapperKind) ? wrapperKind : null;
+	return systemSubject({
+		facts,
+		kind: "wrapper-update-available",
+		subject: `wrapper:${nodeId ?? "hub"}`,
+		titleKey: "system.wrapper-update-available.title",
+		bodyKey: bodySuffix === null ? "system.wrapper-update-available.body" : `system.wrapper-update-available.body.${bodySuffix}`,
+		textParams: {
+			currentVersion: head.currentVersion,
+			latestVersion: head.latestVersion,
+			...nodeId !== void 0 ? { nodeId } : {}
+		},
+		textCount: 1,
+		packageName: head.packageName,
+		packageNames: [head.packageName],
+		...nodeId !== void 0 ? {
+			nodeId,
+			nodeIds: [nodeId]
+		} : {}
+	});
+}
 function incomingFromUpdateAvailable(facts, data) {
 	const target = stringField(data, "target");
+	if (target === "wrapper") return incomingFromWrapperUpdate(facts, data);
 	if (target !== "addon" && target !== "server") return null;
 	const packages = updatePackages(data);
 	if (packages.length === 0) return null;
@@ -9452,7 +9499,7 @@ var CAMERA_DEVICE_TYPE = "camera";
 /** Kinds whose action is "go and apply an ADDON update". */
 var ADDON_UPDATE_KINDS = new Set(["addon-update-available"]);
 /** Kinds whose action is "go and apply a NODE's own (`@camstack/server`) update". */
-var NODE_UPDATE_KINDS = new Set(["server-update-available"]);
+var NODE_UPDATE_KINDS = new Set(["server-update-available", "wrapper-update-available"]);
 /**
 * Kinds whose action is "go and look at this device's stream".
 *
@@ -10017,6 +10064,11 @@ var en_default = {
 	"system.server-update-available.body": "{{packageName}} {{latestVersion}} is available (current {{currentVersion}})",
 	"system.server-update-available.body.onNode": "{{packageName}} {{latestVersion}} is available (current {{currentVersion}}) on node {{nodeId}}",
 	"system.server-update-available.body.onNodes": "{{packageName}} {{latestVersion}} is available (current {{currentVersion}}) on {{nodes}}",
+	"system.wrapper-update-available.title": "The container or app on {{nodeId}} is out of date",
+	"system.wrapper-update-available.body": "The shell this node runs inside carries {{currentVersion}}; the release contract delivers {{latestVersion}}. Updating the server keeps the code current but never replaces the shell.",
+	"system.wrapper-update-available.body.docker": "This node's image carries seed {{currentVersion}}; the release contract delivers {{latestVersion}}. A container cannot replace its own image — recreate it from the contract image: docker compose pull && docker compose up -d",
+	"system.wrapper-update-available.body.electron": "The desktop app on {{nodeId}} carries {{currentVersion}}; the release contract delivers {{latestVersion}}. The app downloads the new build on its own and installs it the next time it quits.",
+	"system.wrapper-update-available.body.native": "The installed app on {{nodeId}} carries {{currentVersion}}; the release contract delivers {{latestVersion}}. Reinstall it from the current release to converge.",
 	"system.addon-updated.title": {
 		"one": "{{count}} addon updated",
 		"other": "{{count}} addons updated"
@@ -10272,6 +10324,11 @@ var it_default = {
 	"system.server-update-available.body": "{{packageName}} {{latestVersion}} è disponibile (attuale {{currentVersion}})",
 	"system.server-update-available.body.onNode": "{{packageName}} {{latestVersion}} è disponibile (attuale {{currentVersion}}) sul nodo {{nodeId}}",
 	"system.server-update-available.body.onNodes": "{{packageName}} {{latestVersion}} è disponibile (attuale {{currentVersion}}) su {{nodes}}",
+	"system.wrapper-update-available.title": "Il contenitore o l'app di {{nodeId}} è indietro",
+	"system.wrapper-update-available.body": "Il guscio in cui gira questo nodo porta {{currentVersion}}; il contratto di rilascio consegna {{latestVersion}}. Aggiornare il server tiene il codice aggiornato ma non sostituisce mai il guscio.",
+	"system.wrapper-update-available.body.docker": "L'immagine di questo nodo porta il seed {{currentVersion}}; il contratto di rilascio consegna {{latestVersion}}. Un container non può sostituire la propria immagine — ricrealo dall'immagine del contratto: docker compose pull && docker compose up -d",
+	"system.wrapper-update-available.body.electron": "L'app desktop su {{nodeId}} porta {{currentVersion}}; il contratto di rilascio consegna {{latestVersion}}. L'app scarica da sola la nuova build e la installa alla prossima chiusura.",
+	"system.wrapper-update-available.body.native": "L'app installata su {{nodeId}} porta {{currentVersion}}; il contratto di rilascio consegna {{latestVersion}}. Reinstallala dal rilascio corrente per allinearla.",
 	"system.addon-updated.title": {
 		"one": "{{count}} addon aggiornato",
 		"other": "{{count}} addon aggiornati"
@@ -25824,6 +25881,7 @@ function systemEventSubject(kind, scope) {
 	if (kind === "detection-blind") return `detection-blind:${scope.deviceId ?? 0}`;
 	if (kind === "addon-crash-loop") return `addon-crash:${scope.nodeId ?? "hub"}:${TEST_CRASHED_RUNNER}`;
 	if (kind === "addon-update-available" || kind === "server-update-available") return `package:${scope.packageName ?? "@camstack/server"}`;
+	if (kind === "wrapper-update-available") return `wrapper:${scope.nodeId ?? "hub"}`;
 	if (kind === "addon-updated") return `packages:addon-updated:${scope.packageName ?? "pkg"}`;
 	if (kind === "server-updated") return `server-updated:${scope.nodeId ?? "hub"}`;
 	if (kind === "export-completed") return `export:${scope.deviceId ?? 0}`;
@@ -33426,7 +33484,12 @@ var FaceGalleryProvider = class {
 				identityId: input.identityId
 			});
 			assigned += 1;
-		} catch {
+		} catch (err) {
+			this.logger.error("assignFaces refused a face", { meta: {
+				faceId,
+				identityId: input.identityId,
+				error: err instanceof Error ? `${err.name}: ${err.message}` : String(err)
+			} });
 			failed.push(faceId);
 		}
 		return {
@@ -34810,6 +34873,21 @@ var SpawnBesideCoastingSampler = class {
 		this.counts.clear();
 	}
 };
+/** Per-cause counter + sampling decision. One instance per tracker, so the
+*  counts are per camera and per detection source. */
+var TrackLossSampler = class {
+	counts = /* @__PURE__ */ new Map();
+	/** The running count when this loss should be emitted, else `undefined`. */
+	next(cause) {
+		const count = (this.counts.get(cause) ?? 0) + 1;
+		this.counts.set(cause, count);
+		if (count <= 10) return count;
+		return count % 50 === 0 ? count : void 0;
+	}
+	reset() {
+		this.counts.clear();
+	}
+};
 /** Per-reason counter + sampling decision. One instance per tracker, so the
 *  counts are per camera and per detection source. */
 var SpawnRefusalSampler = class {
@@ -34918,6 +34996,16 @@ var SortTracker = class SortTracker {
 	refusalSink = null;
 	/** Per-reason counters behind the sampled spawn-beside-coasting diagnostics. */
 	spawnBesideSampler = new SpawnBesideCoastingSampler();
+	/**
+	* Deliveries to {@link update} since this tracker was constructed. One per
+	* frame the pipeline actually hands over — which is exactly what "the camera
+	* was looking" means, and is NOT derivable from wall clock: a quiet camera
+	* and a busy one span the same seconds (D438).
+	*/
+	frameSeq = 0;
+	/** Sink for track deaths — see {@link setTrackLossObserver}. */
+	trackLossObserver = null;
+	trackLossSampler = new TrackLossSampler();
 	/** Sink for fragmentation diagnostics — see {@link setSpawnBesideCoastingObserver}. */
 	spawnBesideObserver = null;
 	constructor(config = {}) {
@@ -34950,6 +35038,13 @@ var SortTracker = class SortTracker {
 	* Same contract as the other two sinks — the tracker has no `deviceId`, the
 	* caller stamps it, and nothing is computed when no observer is wired.
 	*/
+	/**
+	* Wire the sink for {@link TrackLossRecord}. Nothing is computed when no
+	* observer is attached.
+	*/
+	setTrackLossObserver(observer) {
+		this.trackLossObserver = observer;
+	}
 	setSpawnBesideCoastingObserver(observer) {
 		this.spawnBesideObserver = observer;
 	}
@@ -34964,13 +35059,13 @@ var SortTracker = class SortTracker {
 	reportSpawnBesideCoasting(spawnedId, det, coasting, detections, frameArea, timestamp) {
 		const observer = this.spawnBesideObserver;
 		if (!observer) return;
-		const group = this.assocGroup(det.class);
+		const family = SortTracker.spawnBesideFamily(det.class);
 		const dc = bboxCentroid(det.bbox);
 		let best;
 		let bestDist = Number.POSITIVE_INFINITY;
 		let bestReach = 0;
 		for (const track of coasting) {
-			if (this.assocGroup(track.class) !== group) continue;
+			if (SortTracker.spawnBesideFamily(track.class) !== family) continue;
 			const tc = bboxCentroid(track.bbox);
 			const dist = Math.hypot(tc.x - dc.x, tc.y - dc.y);
 			const reach = this.reacquireReach(track, timestamp, true);
@@ -34985,6 +35080,7 @@ var SortTracker = class SortTracker {
 		const declinedBy = this.explainDecline(best, det, detections, frameArea, timestamp, bestDist);
 		const spawnCount = this.spawnBesideSampler.next(declinedBy);
 		if (spawnCount === void 0) return;
+		const crowd = declinedBy === "crowd-guard" ? this.crowdAround(best, det, detections) : void 0;
 		observer({
 			spawnedTrackId: spawnedId,
 			spawnedClass: det.class,
@@ -35001,6 +35097,8 @@ var SortTracker = class SortTracker {
 			gapMs: timestamp - best.lastSeen,
 			trackAgeMs: timestamp - best.firstSeen,
 			declinedBy,
+			...crowd === void 0 ? {} : { competitorCount: crowd.count },
+			...crowd?.nearestPx === void 0 ? {} : { nearestCompetitorPx: crowd.nearestPx },
 			spawnCount,
 			sampledEvery: 10
 		});
@@ -35015,8 +35113,7 @@ var SortTracker = class SortTracker {
 	* `already-claimed` means.
 	*/
 	explainDecline(track, det, detections, frameArea, timestamp, centroidDist) {
-		if (!this.sameGroupAsMeasured(track.class, det)) return "native-measured-class";
-		if (this.assocGroup(track.class) !== this.assocGroup(det.class)) return "assoc-group";
+		if (track.class !== det.class) return det.nativeRecovery !== void 0 ? "native-measured-class" : "cross-class";
 		if (iou$3(track.bbox, det.bbox) >= this.config.rescueIouThreshold) return "already-claimed";
 		if (centroidDist <= this.reacquireReach(track, timestamp, true)) {
 			if (!this.isPlausibleBirth(det, frameArea)) return "already-claimed";
@@ -35075,14 +35172,44 @@ var SortTracker = class SortTracker {
 	* come back — a graveyarded track may still resurrect, and a line about work
 	* that was not lost is worse than no line.
 	*/
+	/**
+	* Report one track that ended with nothing taking over (D438).
+	*
+	* Deliberately separate from {@link reportTrackLoss}, which speaks only for
+	* spawns that never reached `minHits`. The population under investigation —
+	* animal tracks dying mid-frame after six frames — had all EMITTED, so that
+	* path never saw a single one of them.
+	*
+	* `timestamp` is the frame doing the sweeping, not the track's own clock: the
+	* question is how much passed while nobody was looking.
+	*/
+	reportTrackDeath(track, cause, timestamp) {
+		const observer = this.trackLossObserver;
+		if (!observer) return;
+		const lossCount = this.trackLossSampler.next(cause);
+		if (lossCount === void 0) return;
+		observer({
+			trackId: track.id,
+			trackClass: track.class,
+			cause,
+			framesSinceLastSeen: this.frameSeq - track.lastSeenFrameSeq,
+			msSinceLastSeen: timestamp - track.lastSeen,
+			lifeMs: track.lastSeen - track.firstSeen,
+			positions: track.hits,
+			emitted: track.emitted,
+			lossCount,
+			sampledEvery: 50
+		});
+	}
 	reportTrackLoss(track) {
 		if (track.emitted || track.lossReported) return;
 		track.lossReported = true;
 		this.reportRefusal("unconfirmed-spawn-lost", {
-			class: track.class,
+			class: track.frameClass,
 			originalClass: track.originalClass,
 			score: track.score,
-			bbox: track.bbox
+			bbox: track.bbox,
+			...track.lastNativeRecovery !== void 0 ? { nativeRecovery: track.lastNativeRecovery } : {}
 		}, {
 			threshold: this.config.minHits,
 			measured: track.hits,
@@ -35137,43 +35264,73 @@ var SortTracker = class SortTracker {
 	static pairKey(a, b) {
 		return a < b ? `${a}|${b}` : `${b}|${a}`;
 	}
-	/** Association-gating group of a class. When `classGroupAssoc` is on the
-	*  {person,animal} pair collapses to one group so a per-frame class flip
-	*  (crouch person → animal) re-matches the existing track instead of spawning a
-	*  concurrent id. Every other class is its own group. */
-	assocGroup(cls) {
-		if (this.config.classGroupAssoc && (cls === PERSON_CLASS || cls === ANIMAL_CLASS)) return `${PERSON_CLASS}|${ANIMAL_CLASS}`;
+	/** The two macro-classes a coarse pass confuses on a non-upright person. */
+	static isPersonAnimalPair(a, b) {
+		return a === PERSON_CLASS && b === ANIMAL_CLASS || a === ANIMAL_CLASS && b === PERSON_CLASS;
+	}
+	/**
+	* The family a spawn-beside-coasting line is reported AGAINST — {person,
+	* animal} as one, every other class its own. Reporting only, never a binding
+	* rule: a cross-class pair is exactly what that line exists to name (the
+	* D378 veto, the D439 salvage rule), so a pair the tracker refused must still
+	* be reportable. Independent of `classGroupAssoc` for the same reason.
+	*/
+	static spawnBesideFamily(cls) {
+		if (cls === PERSON_CLASS || cls === ANIMAL_CLASS) return `${PERSON_CLASS}|${ANIMAL_CLASS}`;
 		return cls;
 	}
-	/** Whether a detection may associate to a track under the current class gate:
-	*  exact class when `classGating` is off (no gate at all) — matching the legacy
-	*  contract — otherwise same association group (group == exact class unless
-	*  `classGroupAssoc` widened it to {person,animal}). */
+	/**
+	* A CROSS-CLASS BIND IS A FLIP CLAIM, AND A FLIP IS WEAK (D439).
+	*
+	* `classGroupAssoc` exists for one failure of the COARSE full-frame pass: a
+	* bending person re-labelled `animal` for a frame, over the person's own
+	* box, at the 0.4-0.6 the coarse pass gives a shape it half recognises. That
+	* claim has three parts, and this predicate is all three:
+	*
+	*   - the box was measured by the coarse pass — never `nativeRecovery`. The
+	*     runner's second pass measures the OPPOSITE thing: a 640-800 px native
+	*     square around a motion region the full-frame boxes do NOT account for,
+	*     which is by construction not the subject the full pass already has.
+	*     2026-09-07 07:51:33, an `animal` at `nativeRecoveryScore=0.833`
+	*     absorbed into a person: the D378 half of this rule;
+	*   - it is a {person, animal} pair;
+	*   - it is WEAK — below {@link TrackerConfig.animalOverPersonMaxScore}, the
+	*     same bar the spawn gate uses for the same claim. A `person` at 0.86 or
+	*     an `animal` at 0.92 is not a half-recognised shape, it is a subject,
+	*     and binding it to the other class's track hands one subject's id to
+	*     another (camera 615, 17:11:01: person 0.8616 → animal track
+	*     `a28c1557`, which was then born as a person).
+	*
+	* Where the caller may use it is the fourth part, and it is the caller's:
+	* only the predicted-box passes ({@link greedyAssociate}), where "same place"
+	* is measured against a prediction on the strict `iouThreshold`. The salvage
+	* passes ({@link looseMatch}) never cross classes — their whole premise is
+	* weak overlap, and a weak-overlap cross-class bind is a dog beside its
+	* owner, every time.
+	*/
+	crossClassFlip(trackClass, det) {
+		if (!this.config.classGroupAssoc) return false;
+		if (det.nativeRecovery !== void 0) return false;
+		if (!SortTracker.isPersonAnimalPair(trackClass, det.class)) return false;
+		return det.score < this.config.animalOverPersonMaxScore;
+	}
+	/** Whether a detection may associate to a track on a PREDICTED-BOX pass:
+	*  its own class, or — with `classGroupAssoc` — a weak coarse flip of the
+	*  {person, animal} pair ({@link crossClassFlip}). `classGating` off means no
+	*  gate at all, matching the legacy contract, except that a native-measured
+	*  box still binds only its own class (D378). */
 	associable(trackClass, det) {
-		if (!this.sameGroupAsMeasured(trackClass, det)) return false;
+		if (trackClass === det.class) return true;
+		if (det.nativeRecovery !== void 0) return false;
 		if (!this.config.classGating) return true;
-		return this.assocGroup(trackClass) === this.assocGroup(det.class);
+		return this.crossClassFlip(trackClass, det);
 	}
 	/**
-	* A NATIVE-MEASURED BOX IS ITS OWN SUBJECT ACROSS CLASSES (D378).
-	*
-	* `classGroupAssoc` collapses {person, animal} into one association group for
-	* one failure of the COARSE full-frame pass: a bending person re-labelled
-	* `animal` for a frame, over the person's own box. Letting that box re-match
-	* the person track is strictly better than minting a concurrent id.
-	*
-	* The runner's second pass makes the opposite measurement — the same detector
-	* on a 640-800 px native square around a motion region the full-frame boxes
-	* do NOT account for. Such a box is, by construction, not the subject the
-	* full pass already has; absorbing it into a person track means the animal is
-	* never seen at all, which on 2026-09-07 07:51:33 is exactly what happened to
-	* an `animal` at `nativeRecoveryScore=0.833`.
-	*
-	* So the widening does not apply to a detection carrying `nativeRecovery`:
-	* it associates to its OWN class or it spawns. Every other guard on that
-	* spawn still runs — the per-class score floor, the area floor, the
-	* `dedupSpawnIou` overlap, and `resolveDuplicates` afterwards, where a person
-	* still beats a cross-class animal.
+	* A NATIVE-MEASURED BOX IS ITS OWN SUBJECT ACROSS CLASSES (D378) — the
+	* occlusion gate's copy of the first clause of {@link crossClassFlip}. A
+	* cross-class occluder is not a same-subject claim for a box the native
+	* pass measured: a dog at its owner's knee is 100% contained in the person's
+	* box and is not the person.
 	*/
 	sameGroupAsMeasured(trackClass, det) {
 		if (det.nativeRecovery === void 0) return true;
@@ -35346,9 +35503,16 @@ 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.
+	* How many SAME-CLASS 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.
+	*
+	* Exact class, not the {person, animal} family (D439): a competitor is a
+	* subject the id could actually be handed to, and since a salvage pass binds
+	* its own class only, a person cannot take a dog's id there. Counting the
+	* owner as the dog's competitor split one dog's id 12 times on camera 615 in
+	* 6.6 h — every bind the reach clause accepted, the guard then refused
+	* because the person was on screen.
 	*
 	* 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
@@ -35362,30 +35526,30 @@ var SortTracker = class SortTracker {
 	* 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);
+	sameClassPeerCount(corpse, live) {
 		let peers = 0;
-		for (const t of live) if (t !== corpse && this.assocGroup(t.class) === group) peers++;
+		for (const t of live) if (t !== corpse && t.class === corpse.class) peers++;
 		for (const other of this.lostTracks) {
 			if (other === corpse) continue;
 			if (!other.resurrectable) continue;
-			if (this.assocGroup(other.class) !== group) continue;
+			if (other.class !== corpse.class) 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-
-	* gated (a rescue must never cross association groups) independent of
-	* `classGating`, so a coasting person track can be rescued by its own
-	* crouch→animal flip when `classGroupAssoc` is on, but never by an unrelated
-	* class.
+	* Loose 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 reach. EXACT-class, always, independent of
+	* `classGating` and of `classGroupAssoc` (D439): a salvage pass binds on
+	* weak overlap by definition, and a weak-overlap bind across {person,
+	* animal} is not a crouch flip — a flip sits on the subject's own box — it
+	* is a dog beside its owner, or the owner beside the dog. Until 2026-09-10
+	* this gate crossed the group, and it is where a `person` at 0.86 took over
+	* an animal's id (camera 615, 17:11:01).
 	*/
 	looseMatch(track, det, timestamp, timeScaled = true) {
-		if (!this.sameGroupAsMeasured(track.class, det)) return null;
-		if (this.assocGroup(track.class) !== this.assocGroup(det.class)) return null;
+		if (track.class !== det.class) return null;
 		if (iou$3(track.bbox, det.bbox) >= this.config.rescueIouThreshold) return "iou";
 		const tc = bboxCentroid(track.bbox);
 		const dc = bboxCentroid(det.bbox);
@@ -35431,12 +35595,41 @@ var SortTracker = class SortTracker {
 	* bind time and at report time — the spawn-beside-coasting line has to be able
 	* to say which gate declined without re-running the greedy competition.
 	*/
+	/**
+	* WHO the crowd was, for the record only — this changes no decision.
+	*
+	* {@link isUnambiguousReach} refuses on PRESENCE, with no distance in the
+	* question, so a person at the far corner of a room splits a track as surely
+	* as one standing beside it. Counting them, and measuring the nearest, is
+	* what makes narrowing that rule a decision rather than a guess (D436).
+	*/
+	crowdAround(track, det, detections) {
+		const cx = det.bbox.x + det.bbox.w / 2;
+		const cy = det.bbox.y + det.bbox.h / 2;
+		const counted = [];
+		let nearest;
+		const consider = (bbox) => {
+			counted.push(bbox);
+			const d = Math.hypot(bbox.x + bbox.w / 2 - cx, bbox.y + bbox.h / 2 - cy);
+			if (nearest === void 0 || d < nearest) nearest = d;
+		};
+		for (const t of this.tracks) if (t !== track && t.class === track.class) consider(t.bbox);
+		for (const other of detections) {
+			if (other === det) continue;
+			if (other.class !== track.class) continue;
+			if (counted.some((b) => iou$3(b, other.bbox) > 0)) continue;
+			consider(other.bbox);
+		}
+		return {
+			count: counted.length,
+			nearestPx: nearest
+		};
+	}
 	isUnambiguousReach(track, det, detections) {
-		if (this.sameGroupPeerCount(track, this.tracks) > 0) return false;
-		const group = this.assocGroup(track.class);
+		if (this.sameClassPeerCount(track, this.tracks) > 0) return false;
 		for (const other of detections) {
 			if (other === det) continue;
-			if (this.assocGroup(other.class) === group) return false;
+			if (other.class === track.class) return false;
 		}
 		return true;
 	}
@@ -35473,8 +35666,8 @@ var SortTracker = class SortTracker {
 	* weight; otherwise the latest-frame class (ambiguous vote or voting off).
 	*/
 	resolveReportedClass(t) {
-		if (!this.config.classVotingEnabled || t.classVotes.size === 0) return t.class;
-		let bestClass = t.class;
+		if (!this.config.classVotingEnabled || t.classVotes.size === 0) return t.frameClass;
+		let bestClass = t.frameClass;
 		let bestVote = -1;
 		let total = 0;
 		for (const [cls, v] of t.classVotes) {
@@ -35484,8 +35677,8 @@ var SortTracker = class SortTracker {
 				bestClass = cls;
 			}
 		}
-		if (total <= 0) return t.class;
-		return bestVote / total >= this.config.classVoteMinFraction ? bestClass : t.class;
+		if (total <= 0) return t.frameClass;
+		return bestVote / total >= this.config.classVoteMinFraction ? bestClass : t.frameClass;
 	}
 	/** Whether a detection clears its per-class spawn score floor. Only gates NEW
 	*  spawns — an established track still matches below its floor. */
@@ -35501,16 +35694,67 @@ var SortTracker = class SortTracker {
 		return this.config.confirmBypassEnabled && t.score >= this.config.confirmBypassScore;
 	}
 	/**
+	* The live tracks split into the two tiers that claim a box in a fixed
+	* order (D442, see {@link update}): those already confirmed for emission,
+	* and the provisional ones still under `minHits`. Decided on the state at
+	* the start of the frame, as ByteTrack does. With `minHits: 1` the second
+	* tier is always empty and every pass over it is a no-op.
+	*/
+	associationTiers() {
+		const established = [];
+		const provisional = [];
+		for (const track of this.tracks) if (this.isConfirmedForEmit(track)) established.push(track);
+		else provisional.push(track);
+		return [established, provisional];
+	}
+	/**
+	* The rescue pass. HIGH-score detections the greedy pass left unmatched get
+	* a second, looser chance against the still-unmatched (coasting) tracks of
+	* `tracks` — measured on the track's LAST-KNOWN bbox, never the drifted
+	* prediction. Recovers half-box re-acquisition and small-drift flicker
+	* without spawning a duplicate. Best (highest last-known IoU) pairs first;
+	* LOW detections are reserved for the ByteTrack low stage.
+	*/
+	rescueAssociate(tracks, gates, detections, lowSet, frameArea, timestamp, used, matchedTracks, matched, continuationOnly) {
+		const rescuePairs = [];
+		for (const track of tracks) {
+			if (matchedTracks.has(track)) continue;
+			for (let di = 0; di < detections.length; di++) {
+				if (used.has(di) || lowSet.has(di) || continuationOnly.has(di)) continue;
+				const det = detections[di];
+				const gate = this.looseMatch(track, det, timestamp);
+				if (gate === null || !gates.has(gate)) continue;
+				if (gate === "centroid" && this.isPlausibleBirth(det, frameArea) && !(this.config.reacquireTimeScaled && this.isUnambiguousReach(track, det, detections))) continue;
+				rescuePairs.push({
+					track,
+					detIdx: di,
+					score: iou$3(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;
+			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);
+		}
+	}
+	/**
 	* One greedy IoU association pass over a candidate detection subset against the
-	* currently-UNMATCHED tracks, on each track's PREDICTED box. Highest-IoU pairs
+	* still-UNMATCHED tracks of `tracks` (one association tier — see
+	* {@link associationTiers}), on each track's PREDICTED box. Highest-IoU pairs
 	* bind first; a track/detection binds at most once. Shared by the high-score
 	* first stage and the low-score second stage (different candidate sets + IoU
 	* gates) so the two-tier ByteTrack association stays a single implementation.
 	* Mutates `used` / `matchedTracks` / `matched` in place.
 	*/
-	greedyAssociate(detections, candidateIdxs, iouThreshold, timestamp, used, matchedTracks, matched, continuationOnly) {
+	greedyAssociate(tracks, detections, candidateIdxs, iouThreshold, timestamp, used, matchedTracks, matched, continuationOnly) {
 		const pairs = [];
-		for (const track of this.tracks) {
+		for (const track of tracks) {
 			if (matchedTracks.has(track)) continue;
 			const pbox = this.predicted(track, timestamp);
 			const confirmed = this.isConfirmedForEmit(track);
@@ -35536,6 +35780,7 @@ var SortTracker = class SortTracker {
 		}
 	}
 	update(detections, timestamp, frameContext) {
+		this.frameSeq++;
 		const frameArea = frameContext ? frameContext.frameWidth * frameContext.frameHeight : 0;
 		const continuationOnly = frameContext?.continuationOnly ?? EMPTY_INDEX_SET;
 		const resurrectedScene = /* @__PURE__ */ new Map();
@@ -35546,6 +35791,7 @@ var SortTracker = class SortTracker {
 				track.lostAt = timestamp;
 				track.resurrectable = false;
 				this.reportTrackLoss(track);
+				this.reportTrackDeath(track, "lifetime-cap", timestamp);
 				this.lostTracks.push(track);
 			} else alive.push(track);
 			this.tracks = alive;
@@ -35558,13 +35804,17 @@ var SortTracker = class SortTracker {
 				track.lostAt = track.lastSeen;
 				track.resurrectable = false;
 				this.reportTrackLoss(track);
+				this.reportTrackDeath(track, "stale-beyond-budgets", timestamp);
 				this.lostTracks.push(track);
 			} else alive.push(track);
 			this.tracks = alive;
 		}
 		const stillResurrectable = [];
 		for (const t of this.lostTracks) if (timestamp - t.lostAt <= this.config.resurrectionWindowMs) stillResurrectable.push(t);
-		else this.reportTrackLoss(t);
+		else {
+			this.reportTrackLoss(t);
+			this.reportTrackDeath(t, "graveyard-expired", timestamp);
+		}
 		this.lostTracks = stillResurrectable;
 		const used = /* @__PURE__ */ new Set();
 		const matchedTracks = /* @__PURE__ */ new Set();
@@ -35574,36 +35824,21 @@ var SortTracker = class SortTracker {
 		for (let di = 0; di < detections.length; di++) if (this.config.byteTrackEnabled && detections[di].score < this.config.byteTrackHighThreshold) lowIdxs.push(di);
 		else highIdxs.push(di);
 		const lowSet = new Set(lowIdxs);
-		this.greedyAssociate(detections, highIdxs, this.config.iouThreshold, timestamp, used, matchedTracks, matched, continuationOnly);
-		const rescuePairs = [];
-		for (const track of this.tracks) {
-			if (matchedTracks.has(track)) continue;
-			for (let di = 0; di < detections.length; di++) {
-				if (used.has(di) || lowSet.has(di) || continuationOnly.has(di)) continue;
-				const det = detections[di];
-				const gate = this.looseMatch(track, det, timestamp);
-				if (gate === null) continue;
-				if (gate === "centroid" && this.isPlausibleBirth(det, frameArea) && !(this.config.reacquireTimeScaled && this.isUnambiguousReach(track, det, detections))) continue;
-				rescuePairs.push({
-					track,
-					detIdx: di,
-					score: iou$3(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;
-			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, timestamp, used, matchedTracks, matched, continuationOnly);
+		const [established, provisional] = this.associationTiers();
+		const OVERLAP = new Set(["iou"]);
+		const PROXIMITY = new Set(["centroid", "growth"]);
+		this.greedyAssociate(established, detections, highIdxs, this.config.iouThreshold, timestamp, used, matchedTracks, matched, continuationOnly);
+		this.rescueAssociate(established, OVERLAP, detections, lowSet, frameArea, timestamp, used, matchedTracks, matched, continuationOnly);
+		this.greedyAssociate(provisional, detections, highIdxs, this.config.iouThreshold, timestamp, used, matchedTracks, matched, continuationOnly);
+		this.rescueAssociate(established, PROXIMITY, detections, lowSet, frameArea, timestamp, used, matchedTracks, matched, continuationOnly);
+		this.rescueAssociate(provisional, new Set([...OVERLAP, ...PROXIMITY]), detections, lowSet, frameArea, timestamp, used, matchedTracks, matched, continuationOnly);
+		if (this.config.byteTrackEnabled && lowIdxs.length > 0) for (const tier of [established, provisional]) this.greedyAssociate(tier, detections, lowIdxs, this.config.byteTrackLowIouThreshold, timestamp, used, matchedTracks, matched, continuationOnly);
 		for (const [track, det] of matched) {
-			if (track.class !== det.class) this.reportRefusal("cross-class-absorbed", det, { against: track });
+			if (track.class !== det.class) this.reportRefusal("cross-class-absorbed", det, {
+				against: track,
+				measured: iou$3(this.predicted(track, timestamp), det.bbox),
+				threshold: this.config.animalOverPersonMaxScore
+			});
 			const prevCenter = bboxCentroid({
 				x: track.bbox.x,
 				y: track.bbox.y,
@@ -35619,12 +35854,15 @@ var SortTracker = class SortTracker {
 			const frames = track.age + 1;
 			const dtMs = timestamp - track.lastSeen;
 			track.bbox = det.bbox;
-			track.class = det.class;
+			if (!this.crossClassFlip(track.class, det)) track.class = det.class;
+			track.frameClass = det.class;
 			track.originalClass = det.originalClass;
 			track.score = det.score;
+			track.lastNativeRecovery = det.nativeRecovery;
 			track.age = 0;
 			track.hits++;
 			track.lastSeen = timestamp;
+			track.lastSeenFrameSeq = this.frameSeq;
 			if (dtMs > 0) {
 				track.velocity = {
 					dx: (newCenter.x - prevCenter.x) / dtMs,
@@ -35673,7 +35911,7 @@ var SortTracker = class SortTracker {
 				if (gate === null) continue;
 				if (gate === "centroid" && this.isPlausibleBirth(det, frameArea)) continue;
 				const score = iou$3(lost.bbox, det.bbox);
-				const peers = this.sameGroupPeerCount(lost, surviving);
+				const peers = this.sameClassPeerCount(lost, surviving);
 				if (this.config.resurrectionCrowdGuard && peers > 0 && score < this.config.resurrectionCrowdedIouThreshold) {
 					if (score > refusedScore) {
 						refused = lost;
@@ -35698,12 +35936,15 @@ var SortTracker = class SortTracker {
 			this.lostTracks = this.lostTracks.filter((t) => t !== best);
 			best.bbox = det.bbox;
 			best.class = det.class;
+			best.frameClass = det.class;
 			best.originalClass = det.originalClass;
 			best.score = det.score;
+			best.lastNativeRecovery = det.nativeRecovery;
 			best.age = 0;
 			best.hits++;
 			best.lost = false;
 			best.lastSeen = timestamp;
+			best.lastSeenFrameSeq = this.frameSeq;
 			best.velocity = {
 				dx: 0,
 				dy: 0
@@ -35760,6 +36001,7 @@ var SortTracker = class SortTracker {
 				id: spawnedId,
 				bbox: det.bbox,
 				class: det.class,
+				frameClass: det.class,
 				originalClass: det.originalClass,
 				score: det.score,
 				age: 0,
@@ -35767,6 +36009,7 @@ var SortTracker = class SortTracker {
 				path: [det.bbox],
 				firstSeen: timestamp,
 				lastSeen: timestamp,
+				lastSeenFrameSeq: this.frameSeq,
 				velocity: {
 					dx: 0,
 					dy: 0
@@ -35777,7 +36020,8 @@ var SortTracker = class SortTracker {
 				resurrectable: true,
 				classVotes: new Map([[det.class, det.score > 0 ? det.score : Number.EPSILON]]),
 				emitted: false,
-				lossReported: false
+				lossReported: false,
+				lastNativeRecovery: det.nativeRecovery
 			});
 		}
 		this.tracks = surviving;
@@ -36307,6 +36551,10 @@ var FrameProcessor = class {
 	/** Wire (or clear) the tracker's fragmentation sink — a new id minted beside a
 	*  live coasting track that could have claimed it (D399). Same `deviceId`
 	*  contract as the two sinks above. */
+	/** Wire the sink for track deaths (D438) — pure passthrough to the tracker. */
+	setTrackLossObserver(observer) {
+		this.tracker.setTrackLossObserver(observer);
+	}
 	setSpawnBesideCoastingObserver(observer) {
 		this.tracker.setSpawnBesideCoastingObserver(observer);
 	}
@@ -66696,10 +66944,12 @@ var TrackingSettingsSchema = require_dist.object({
 	minSpawnAreaFracAnimal: require_dist.number().min(0).max(1).default(0),
 	/** Min spawn bbox area for `vehicle` as a fraction of the frame (0 = ungated). */
 	minSpawnAreaFracVehicle: require_dist.number().min(0).max(1).default(0),
-	/** Gate association on a class GROUP ({person,animal}) instead of the exact
-	*  per-frame class, so a person that flips to `animal` for a frame re-matches
-	*  its existing track (no concurrent animal id). Reported label stays via the
-	*  class vote. Off = exact per-frame class gating. */
+	/** Let a person that flips to `animal` for a frame re-match its existing
+	*  track (no concurrent animal id). A flip is the same subject in the same
+	*  place, weakly read (D439): the bind is allowed only on the predicted-box
+	*  passes, only for a coarse box below `animalOverPersonMaxScore`, never on
+	*  the rescue / resurrection passes. Reported label stays via the class
+	*  vote. Off = exact per-frame class gating. */
 	classGroupAssoc: require_dist.boolean().default(true)
 });
 var TRACKING_DEFAULTS = TrackingSettingsSchema.parse({});
@@ -67289,7 +67539,7 @@ function buildDetectionSettingsSections() {
 					type: "boolean",
 					key: "classGroupAssoc",
 					label: "Person/animal group matching",
-					description: "Let a detection that flips between person and animal for a frame (a crouching / bending person is often read as an animal) re-match its existing track instead of spawning a concurrent animal track. The reported class is still decided by the per-track class vote.",
+					description: "Let a detection that flips between person and animal for a frame (a crouching / bending person is often read as an animal) re-match its existing track instead of spawning a concurrent animal track. A flip is the same subject in the same place, weakly read: the cross-class match happens only on the strict predicted-box pass and only for a full-frame box below the \"animal over person max score\" bar — a confident animal beside a person, or a person beside an animal, is its own subject and keeps its own track. The reported class is still decided by the per-track class vote.",
 					default: TRACKING_DEFAULTS.classGroupAssoc
 				},
 				{
@@ -77760,6 +78010,15 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 					}
 				});
 			});
+			p.setTrackLossObserver((record) => {
+				this.ctx.logger.info("tracker: a track ended and nothing took over", {
+					tags: { deviceId },
+					meta: {
+						source,
+						...record
+					}
+				});
+			});
 			p.setSpawnBesideCoastingObserver((record) => {
 				this.ctx.logger.info("tracker: new id minted beside a live coasting track", {
 					tags: { deviceId },