@camstack/addon-post-analysis 1.2.19 → 1.2.20

package/dist/pipeline-analytics/index.mjs

@@ -1,4 +1,4 @@
-import { A as errMsg, B as number, D as subKindsOf, E as plateGalleryCapability, F as nodePin, H as string, I as _enum, L as array, M as DeviceType, N as createEvent, O as videoclipsCapability, P as hydrateSchema, R as boolean, S as faceGalleryCapability, T as pipelineAnalyticsCapability, U as EventCategory, V as object, _ as buildEventKindDescriptor, a as NC_CONDITION_CATALOG, b as defineCustomActions, c as NcRuleInputSchema, d as NcTaxonomySchema, f as OpsLogEntrySchema, g as audioMetricsCapability, h as addonWidgetsSourceCapability, i as MACRO_LABELS, j as BaseAddon, k as zoneAnalyticsCapability, l as NcRulePatchSchema, m as TimelapseRuleSchema, n as EVENT_KIND_BY_CAP, o as NC_TAXONOMY, p as TimelapseRuleInputSchema, r as EVENT_PAD_MS, s as NcConditionDescriptorSchema, t as DEFAULT_EVENT_COLOR, u as NcRuleSchema, v as cosineSimilarity, w as notificationRulesCapability, y as customAction, z as literal } from "../dist-C41w6Xvl.mjs";
+import { A as errMsg, B as number, D as subKindsOf, E as plateGalleryCapability, F as nodePin, H as string, I as _enum, L as array, M as DeviceType, N as createEvent, O as videoclipsCapability, P as hydrateSchema, R as boolean, S as faceGalleryCapability, T as pipelineAnalyticsCapability, U as EventCategory, V as object, _ as buildEventKindDescriptor, a as NC_CONDITION_CATALOG, b as defineCustomActions, c as NcRuleInputSchema, d as NcTaxonomySchema, f as OpsLogEntrySchema, g as audioMetricsCapability, h as addonWidgetsSourceCapability, i as MACRO_LABELS, j as BaseAddon, k as zoneAnalyticsCapability, l as NcRulePatchSchema, m as TimelapseRuleSchema, n as EVENT_KIND_BY_CAP, o as NC_TAXONOMY, p as TimelapseRuleInputSchema, r as EVENT_PAD_MS, s as NcConditionDescriptorSchema, t as DEFAULT_EVENT_COLOR, u as NcRuleSchema, v as cosineSimilarity, w as notificationRulesCapability, y as customAction, z as literal } from "../dist-CrAkB8NZ.mjs";
 import { promises } from "node:fs";
 import path from "node:path";
 import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
@@ -1435,6 +1435,94 @@ function resolveDetectionLabel(input) {
 	if (top) return top;
 	return input.originalClass && input.originalClass !== input.className ? input.originalClass : void 0;
 }
+var DEFAULT_ZONE_TRANSITION_CONFIG = {
+	enterFrames: 2,
+	exitFrames: 4
+};
+var NO_TRANSITIONS = {
+	entered: [],
+	exited: []
+};
+function newState() {
+	return {
+		inside: /* @__PURE__ */ new Set(),
+		enterStreak: /* @__PURE__ */ new Map(),
+		exitStreak: /* @__PURE__ */ new Map()
+	};
+}
+var ZoneTransitionTracker = class {
+	config;
+	tracks = /* @__PURE__ */ new Map();
+	constructor(config = {}) {
+		this.config = {
+			...DEFAULT_ZONE_TRANSITION_CONFIG,
+			...config
+		};
+	}
+	/**
+	* Feed one frame's zone membership for one track.
+	*
+	* `currentZoneIds` is the set the geometry says the box is in RIGHT NOW; the
+	* return value is only what has persisted long enough to be believed.
+	*/
+	observe(trackId, currentZoneIds) {
+		const state = this.tracks.get(trackId) ?? newState();
+		this.tracks.set(trackId, state);
+		const now = new Set(currentZoneIds);
+		const entered = [];
+		const exited = [];
+		for (const zoneId of now) {
+			if (state.inside.has(zoneId)) {
+				state.exitStreak.delete(zoneId);
+				continue;
+			}
+			const streak = (state.enterStreak.get(zoneId) ?? 0) + 1;
+			if (streak >= this.config.enterFrames) {
+				state.enterStreak.delete(zoneId);
+				state.inside.add(zoneId);
+				entered.push(zoneId);
+			} else state.enterStreak.set(zoneId, streak);
+		}
+		for (const zoneId of [...state.enterStreak.keys()]) if (!now.has(zoneId)) state.enterStreak.delete(zoneId);
+		for (const zoneId of [...state.inside]) {
+			if (now.has(zoneId)) continue;
+			const streak = (state.exitStreak.get(zoneId) ?? 0) + 1;
+			if (streak >= this.config.exitFrames) {
+				state.exitStreak.delete(zoneId);
+				state.inside.delete(zoneId);
+				exited.push(zoneId);
+			} else state.exitStreak.set(zoneId, streak);
+		}
+		if (entered.length === 0 && exited.length === 0) return NO_TRANSITIONS;
+		return {
+			entered,
+			exited
+		};
+	}
+	/** Zones a track is currently confirmed to be inside. */
+	zonesFor(trackId) {
+		const state = this.tracks.get(trackId);
+		return state ? [...state.inside] : [];
+	}
+	/**
+	* Drop a track and report the zones it was still inside.
+	*
+	* The caller uses these to close the subject's presence — a track that
+	* disappears mid-zone has genuinely left it, and nothing else will ever say
+	* so. Without this, a zone entry would have no matching exit whenever the
+	* subject walked out of frame rather than out of the zone.
+	*/
+	forget(trackId) {
+		const state = this.tracks.get(trackId);
+		if (!state) return [];
+		this.tracks.delete(trackId);
+		return [...state.inside];
+	}
+	/** Number of tracks held — a leak check for the caller's tests. */
+	size() {
+		return this.tracks.size;
+	}
+};
 //#endregion
 //#region src/pipeline-analytics/pipeline/zones/geometry.ts
 /** Ray-casting point-in-polygon test */
@@ -2313,17 +2401,31 @@ var ZoneEngine = class {
 	* dog overlapping `Aiuola` by 4.8% would have been stamped as in it).
 	*/
 	annotateDetection(bbox, zones, frameWidth, frameHeight, mask, maskWidth, maskHeight, minOverlap = MEMBERSHIP_MIN_OVERLAP) {
+		return [...this.splitDetectionZones(bbox, zones, frameWidth, frameHeight, mask, maskWidth, maskHeight, minOverlap).memberships];
+	}
+	/**
+	* {@link annotateDetection}, keeping the zones the bar REJECTED as well as
+	* the ones it admitted. Same geometry, one pass — see
+	* {@link ZoneMembershipSplit} for why the rejected side has to survive.
+	*/
+	splitDetectionZones(bbox, zones, frameWidth, frameHeight, mask, maskWidth, maskHeight, minOverlap = MEMBERSHIP_MIN_OVERLAP) {
 		const memberships = [];
+		const belowBar = [];
 		for (const zone of zones) {
 			const pixelPolygon = zone.polygon.map((p) => normalizeToPixel(p, frameWidth, frameHeight));
 			const overlap = mask && maskWidth && maskHeight ? maskPolygonOverlap(mask, maskWidth, maskHeight, bbox, pixelPolygon, frameWidth, frameHeight) : bboxPolygonOverlap(bbox, pixelPolygon);
-			if (overlap > minOverlap) memberships.push({
+			const entry = {
 				zoneId: zone.id,
 				zoneName: zone.name,
 				overlap
-			});
+			};
+			if (overlap > minOverlap) memberships.push(entry);
+			else if (overlap > 0) belowBar.push(entry);
 		}
-		return memberships;
+		return {
+			memberships,
+			belowBar
+		};
 	}
 	/**
 	* Filter detections through a zone-rule set. `zones` provides the
@@ -2384,6 +2486,66 @@ function ruleApplies(resolved, det, className, maskInfo, _zones, frameWidth, fra
 	return false;
 }
 //#endregion
+//#region src/pipeline-analytics/pipeline/rider-pairing.ts
+/**
+* Fine classes that carry a rider. A scooter/moped reaches us as
+* `motorcycle` (COCO) or `motorbike` depending on the model's label set.
+*/
+var TWO_WHEELERS = new Set([
+	"bicycle",
+	"motorcycle",
+	"motorbike"
+]);
+/** Intersection area of two boxes. */
+function intersection(a, b) {
+	return Math.max(0, Math.min(a.x + a.w, b.x + b.w) - Math.max(a.x, b.x)) * Math.max(0, Math.min(a.y + a.h, b.y + b.h) - Math.max(a.y, b.y));
+}
+/** True when `vehicle` is a two-wheeler that `person` is riding. */
+function isRiderPair(person, vehicle) {
+	if (person.macroClass !== "person") return false;
+	if (vehicle.macroClass !== "vehicle") return false;
+	if (!TWO_WHEELERS.has((vehicle.originalClass ?? "").toLowerCase())) return false;
+	const personArea = person.bbox.w * person.bbox.h;
+	if (!(personArea > 0)) return false;
+	if (intersection(person.bbox, vehicle.bbox) / personArea < .25) return false;
+	return person.bbox.y + person.bbox.h / 2 < vehicle.bbox.y + vehicle.bbox.h / 2;
+}
+/**
+* Pair every rider with their machine. A person is paired at most once — with
+* the two-wheeler they overlap MOST — so two bikes side by side cannot both
+* claim the same rider.
+*/
+function pairRiders(detections) {
+	const people = detections.filter((d) => d.macroClass === "person");
+	const twoWheelers = detections.filter((d) => d.macroClass === "vehicle" && TWO_WHEELERS.has((d.originalClass ?? "").toLowerCase()));
+	if (people.length === 0 || twoWheelers.length === 0) return [];
+	const pairs = [];
+	const claimed = /* @__PURE__ */ new Set();
+	for (const person of people) {
+		let best = null;
+		const personArea = person.bbox.w * person.bbox.h;
+		if (!(personArea > 0)) continue;
+		for (const vehicle of twoWheelers) {
+			if (claimed.has(vehicle.id)) continue;
+			if (!isRiderPair(person, vehicle)) continue;
+			const overlap = intersection(person.bbox, vehicle.bbox) / personArea;
+			if (!best || overlap > best.overlap) best = {
+				vehicle,
+				overlap
+			};
+		}
+		if (best) {
+			claimed.add(best.vehicle.id);
+			pairs.push({
+				personId: person.id,
+				vehicleId: best.vehicle.id,
+				overlap: Math.round(best.overlap * 1e3) / 1e3
+			});
+		}
+	}
+	return pairs;
+}
+//#endregion
 //#region src/pipeline-analytics/pipeline/frame-processor.ts
 /** Mapping from StateAnalyzer's `ObjectState.state` values to the
 *  canonical TrackState enum used on tracks + events. */
@@ -2421,6 +2583,17 @@ var FrameProcessor = class {
 	zoneMembershipMinOverlap;
 	/** See {@link getLastZoneOverlaps}. */
 	lastZoneOverlaps;
+	/** See {@link getLastZoneRejections}. */
+	lastZoneRejections;
+	/** Zone crossings per track — the producer of `zone.enter` / `zone.exit`. */
+	zoneTransitions = new ZoneTransitionTracker();
+	/**
+	* Last zone membership seen per track, so an event for a track that is GONE
+	* this frame still carries the zones it was in. See the use site.
+	*/
+	lastZonesByTrack = /* @__PURE__ */ new Map();
+	/** See {@link getLastRiderPairs}. */
+	lastRiderPairs = [];
 	zoneEngine = new ZoneEngine();
 	/** Optional stationary-object gate (parked-object suppression). Null until
 	*  the addon wires it via {@link setStationaryGate}. */
@@ -2435,6 +2608,7 @@ var FrameProcessor = class {
 		this.detectionRules = [];
 		this.zoneMembershipMinOverlap = 0;
 		this.lastZoneOverlaps = /* @__PURE__ */ new Map();
+		this.lastZoneRejections = /* @__PURE__ */ new Map();
 	}
 	setZones(zones) {
 		this.zones = zones;
@@ -2452,6 +2626,12 @@ var FrameProcessor = class {
 	setZoneMembershipMinOverlap(minOverlap) {
 		this.zoneMembershipMinOverlap = Number.isFinite(minOverlap) && minOverlap >= 0 && minOverlap <= 1 ? minOverlap : 0;
 	}
+	/** Rider pairings folded on the most recent frame — the PERSON half that was
+	*  dropped so the passage counts once, as a vehicle. Reported so both
+	*  entities stay on the record rather than one silently disappearing. */
+	getLastRiderPairs() {
+		return this.lastRiderPairs;
+	}
 	/** Per-track zone memberships WITH their overlap fractions, from the most
 	*  recent frame. The engine computes these and the pipeline previously
 	*  discarded everything but the ids — which is why no amount of production
@@ -2459,6 +2639,13 @@ var FrameProcessor = class {
 	getLastZoneOverlaps() {
 		return this.lastZoneOverlaps;
 	}
+	/** Per-track zones the membership bar REJECTED (0 < overlap ≤ the bar), from
+	*  the most recent frame. Raising the bar otherwise makes the stamping log go
+	*  quiet for exactly the cases it was armed to measure — see
+	*  `ZoneMembershipSplit` in `zones/zone-engine.ts`. */
+	getLastZoneRejections() {
+		return this.lastZoneRejections;
+	}
 	setDetectionRules(rules) {
 		this.detectionRules = rules;
 	}
@@ -2551,7 +2738,24 @@ var FrameProcessor = class {
 			});
 		}
 		const { passed } = this.zoneEngine.filterDetections(flatDetections, this.zones, this.detectionRules, frameWidth, frameHeight, (fd) => fd.detection.class);
-		const filteredDetections = passed.map((fd) => fd.detection);
+		let filteredDetections = passed.map((fd) => fd.detection);
+		const riderPairs = pairRiders(filteredDetections.map((d, i) => ({
+			id: String(i),
+			macroClass: d.class,
+			...d.originalClass !== void 0 ? { originalClass: d.originalClass } : {},
+			bbox: d.bbox,
+			score: d.score
+		})));
+		if (riderPairs.length > 0) {
+			const riderIdx = new Set(riderPairs.map((p) => Number(p.personId)));
+			this.lastRiderPairs = riderPairs.map((p) => ({
+				overlap: p.overlap,
+				personScore: filteredDetections[Number(p.personId)]?.score ?? 0,
+				vehicleScore: filteredDetections[Number(p.vehicleId)]?.score ?? 0,
+				vehicleClass: filteredDetections[Number(p.vehicleId)]?.originalClass ?? "two-wheeler"
+			}));
+			filteredDetections = filteredDetections.filter((_, i) => !riderIdx.has(i));
+		} else if (this.lastRiderPairs.length > 0) this.lastRiderPairs = [];
 		const gate = this.stationaryGate ? this.stationaryGate.filter({
 			detections: filteredDetections,
 			frameWidth,
@@ -2567,16 +2771,47 @@ var FrameProcessor = class {
 			frameHeight
 		});
 		const objectStates = this.stateAnalyzer.analyze(trackedDetections, timestamp);
-		const rawEvents = this.eventEmitter.emit(trackedDetections, objectStates, [], [], String(this.deviceId));
 		const zonesByTrack = /* @__PURE__ */ new Map();
 		const overlapsByTrack = /* @__PURE__ */ new Map();
+		const rejectedByTrack = /* @__PURE__ */ new Map();
 		for (const td of trackedDetections) {
 			const m = maskByBbox.get(td.bbox);
-			const memberships = this.zoneEngine.annotateDetection(td.bbox, this.zones, frameWidth, frameHeight, m?.mask, m?.width, m?.height, this.zoneMembershipMinOverlap);
+			const { memberships, belowBar } = this.zoneEngine.splitDetectionZones(td.bbox, this.zones, frameWidth, frameHeight, m?.mask, m?.width, m?.height, this.zoneMembershipMinOverlap);
 			zonesByTrack.set(td.trackId, memberships.map((m2) => m2.zoneId));
 			if (memberships.length > 0) overlapsByTrack.set(td.trackId, memberships);
+			if (belowBar.length > 0) rejectedByTrack.set(td.trackId, belowBar);
 		}
 		this.lastZoneOverlaps = overlapsByTrack;
+		this.lastZoneRejections = rejectedByTrack;
+		for (const [trackId, zoneIds] of zonesByTrack) this.lastZonesByTrack.set(trackId, zoneIds);
+		for (const state of objectStates) {
+			if (zonesByTrack.has(state.trackId)) continue;
+			const remembered = this.lastZonesByTrack.get(state.trackId);
+			if (remembered && remembered.length > 0) zonesByTrack.set(state.trackId, remembered);
+		}
+		const zoneEvents = [];
+		const pushZoneEvent = (type, zoneId, detection) => {
+			const zone = this.zones.find((z) => z.id === zoneId);
+			zoneEvents.push({
+				type,
+				zoneId,
+				zoneName: zone?.name ?? zoneId,
+				trackId: detection.trackId,
+				detection,
+				timestamp
+			});
+		};
+		for (const td of trackedDetections) {
+			const crossings = this.zoneTransitions.observe(td.trackId, zonesByTrack.get(td.trackId) ?? []);
+			for (const zoneId of crossings.entered) pushZoneEvent("zone-enter", zoneId, td);
+			for (const zoneId of crossings.exited) pushZoneEvent("zone-exit", zoneId, td);
+		}
+		const rawEvents = this.eventEmitter.emit(trackedDetections, objectStates, zoneEvents, [], String(this.deviceId));
+		for (const state of objectStates) {
+			if (state.state !== "leaving") continue;
+			this.zoneTransitions.forget(state.trackId);
+			this.lastZonesByTrack.delete(state.trackId);
+		}
 		const tracked = trackedDetections.map((td) => {
 			const state = mapObjectStateToTrackState(objectStates.find((o) => o.trackId === td.trackId)?.state);
 			const label = resolveDetectionLabel({
@@ -2614,10 +2849,22 @@ var FrameProcessor = class {
 				} : {}
 			};
 		});
+		const crossingOf = (e) => {
+			const direction = e.type === "zone.enter" ? "enter" : e.type === "zone.exit" ? "exit" : void 0;
+			if (direction === void 0) return void 0;
+			const ze = e.zoneEvents[0];
+			if (ze === void 0) return void 0;
+			return {
+				direction,
+				zoneId: ze.zoneId,
+				zoneName: ze.zoneName
+			};
+		};
 		const toObjectEvent = (e, forcedState) => {
 			const td = trackedDetections.find((t) => t.trackId === e.detection.trackId);
 			const state = forcedState ?? mapObjectStateToTrackState(objectStates.find((o) => o.trackId === e.detection.trackId)?.state);
 			const zones = zonesByTrack.get(e.detection.trackId) ?? [];
+			const crossing = crossingOf(e);
 			const label = td ? resolveDetectionLabel({
 				className: td.class,
 				originalClass: td.originalClass,
@@ -2641,6 +2888,7 @@ var FrameProcessor = class {
 				},
 				zones,
 				state,
+				...crossing !== void 0 ? { zoneCrossing: crossing } : {},
 				...label ? { label } : {},
 				frameWidth,
 				frameHeight
@@ -3539,7 +3787,8 @@ var DEFAULT_ZERO_MEDIA_POLICY_CONFIG = {
 * for the full contract.
 */
 function decideZeroMediaPolicy(input, config = DEFAULT_ZERO_MEDIA_POLICY_CONFIG) {
-	if (input.hasMedia) return "persist";
+	if (input.hasBestMedia) return "persist";
+	if (input.hasMedia) return input.hasRasterFallback ? "raster-fallback" : "persist";
 	if (input.durationMs < config.suppressMaxDurationMs && !input.confirmed) return "suppress";
 	if (!input.hasRasterFallback && input.durationMs < config.nothingToShowMaxDurationMs) return "suppress";
 	return input.hasRasterFallback ? "raster-fallback" : "persist";
@@ -3733,9 +3982,11 @@ var TrackCloser = class {
 		const duration = t.lastSeen - t.firstSeen;
 		const closure = this.deps.residents.closure(t.trackId);
 		const ownedMedia = await this.deps.mediaStore()?.listByOwner("track", t.trackId) ?? [];
+		const hasBestMedia = ownedMedia.some((m) => m.kind === "thumbnail" || m.kind === "keyFrame");
 		const outcome = decideZeroMediaPolicy({
 			durationMs: duration,
 			hasMedia: ownedMedia.length > 0,
+			hasBestMedia,
 			confirmed: closure?.confirmed ?? false,
 			hasRasterFallback: closure?.rasterFallback !== void 0
 		});
@@ -4077,6 +4328,7 @@ function subjectFromObjectEvent(ev) {
 		...ev.trackId !== void 0 ? { trackId: ev.trackId } : {},
 		source: ev.source ?? "pipeline",
 		...ev.importance !== void 0 ? { importance: ev.importance } : {},
+		...ev.zoneCrossing !== void 0 ? { crossing: ev.zoneCrossing } : {},
 		...bboxPatch(normalizeBbox(ev.bbox, ev.frameWidth, ev.frameHeight))
 	};
 }
@@ -4243,6 +4495,7 @@ function presentConditionIds(c) {
 	if (c.minDwellSeconds !== void 0) ids.push("minDwellSeconds");
 	if (c.zones !== void 0) ids.push("zones");
 	if (c.zonesExclude !== void 0 && c.zonesExclude.length > 0) ids.push("zonesExclude");
+	if (c.crossing !== void 0 && c.crossing !== "enter") ids.push("crossing");
 	if (c.labelEquals !== void 0 && c.labelEquals.length > 0) ids.push("labelEquals");
 	if (c.identities !== void 0 && c.identities.length > 0) ids.push("identities");
 	if (c.identitiesExclude !== void 0 && c.identitiesExclude.length > 0) ids.push("identitiesExclude");
@@ -4278,6 +4531,21 @@ function matchesOccupancy(occ, s) {
 		case "<=": return s.occupied === false && s.threshold === occ.count + 1;
 	}
 }
+/**
+* The zone ids a `zones` / `zonesExclude` condition tests against: the
+* record's membership PLUS the zone it crossed, when it is a crossing.
+*
+* The union is what makes an EXIT addressable. Membership is computed from the
+* box's current geometry, so on the frame an exit is confirmed the subject is
+* by definition no longer in the zone — a rule scoped to "Uscio" would never
+* see the exit from Uscio. An ENTRY's zone is already in the membership, so
+* this changes nothing for every rule that exists today.
+*/
+function zonesVisitedBy(subject) {
+	const visited = new Set(subject.zones);
+	if (subject.crossing !== void 0) visited.add(subject.crossing.zoneId);
+	return visited;
+}
 function toLowerSet(values) {
 	return new Set(values.map((v) => v.trim().toLowerCase()));
 }
@@ -4363,14 +4631,20 @@ function evaluateRule(rule, subject) {
 	if (c.minDwellSeconds !== void 0) {
 		if (subject.dwellSeconds === void 0 || subject.dwellSeconds < c.minDwellSeconds) return fail("minDwellSeconds");
 	}
+	if (c.crossing !== "any") {
+		const direction = subject.crossing?.direction;
+		if (c.crossing === "exit") {
+			if (direction !== "exit") return fail("crossing");
+		} else if (direction === "exit") return fail("crossing");
+	}
 	if (c.zones !== void 0) {
-		const visited = new Set(subject.zones);
+		const visited = zonesVisitedBy(subject);
 		if (c.zones.match === "all") {
 			for (const id of c.zones.ids) if (!visited.has(id)) return fail("zones");
 		} else if (!c.zones.ids.some((id) => visited.has(id))) return fail("zones");
 	}
 	if (c.zonesExclude !== void 0 && c.zonesExclude.length > 0) {
-		const visited = new Set(subject.zones);
+		const visited = zonesVisitedBy(subject);
 		if (c.zonesExclude.some((id) => visited.has(id))) return fail("zonesExclude");
 	}
 	if (c.customZones !== void 0 && c.customZones.length > 0) {
@@ -4499,10 +4773,28 @@ function matchesPlate(label, values, maxDistance) {
 	for (const v of values) if (levenshtein(plate, normalizePlate(v)) <= maxDistance) return true;
 	return false;
 }
-/** Stable cooldown key per the rule's throttle scope. */
+/**
+* Should this subject's class be part of the cooldown key?
+*
+* AUDIO is unconditional and predates the setting: a rule opted into several
+* audio classes (dog + scream) must not have a safety-relevant scream
+* swallowed by an unrelated bark's 60 s window.
+*
+* Every other subject gets the same treatment only when the rule ASKS for it
+* (`granularity: 'per-class'`) — cat→dog fires at once, cat→cat still waits.
+* Absent / `shared` reproduces the class-agnostic key byte for byte, because
+* changing how often an operator's existing rules fire is not a side effect
+* anyone asked for.
+*/
+function keysPerClass(rule, subject) {
+	if (subject.kind === "audio-event") return true;
+	return rule.throttle.granularity === "per-class";
+}
+/** Stable cooldown key per the rule's throttle scope + class granularity. */
 function cooldownKey(rule, subject) {
-	const audioClass = subject.kind === "audio-event" && subject.classNames[0] !== void 0 ? `:c:${subject.classNames[0]}` : "";
-	return rule.throttle.scope === "rule" ? `r:${rule.id}${audioClass}` : `r:${rule.id}:d:${subject.deviceId}${audioClass}`;
+	const first = subject.classNames[0];
+	const classKey = keysPerClass(rule, subject) && first !== void 0 ? `:c:${first}` : "";
+	return rule.throttle.scope === "rule" ? `r:${rule.id}${classKey}` : `r:${rule.id}:d:${subject.deviceId}${classKey}`;
 }
 /** True when the rule fired within its cooldown window before `now`. */
 function isCoolingDown(rule, lastFiredAt, now) {
@@ -6292,6 +6584,13 @@ var TimelapseStore = class {
 };
 //#endregion
 //#region src/notification-center/index.ts
+/**
+* How often the "matched NO rule" report may fire per device. Long enough that
+* a busy camera prints one line rather than one per event, short enough that a
+* rule which has stopped matching is visible within minutes rather than by
+* comparison with another system fifteen hours later.
+*/
+var NO_MATCH_REPORT_INTERVAL_MS = 6e4;
 var DEFAULT_DRAIN_INTERVAL_MS = 2e3;
 var DEFAULT_RULE_RELOAD_INTERVAL_MS = 3e4;
 var DEFAULT_RECONCILE_WINDOW_MS = 15 * 6e4;
@@ -6402,6 +6701,9 @@ var NotificationCenter = class NotificationCenter {
 	occupancyEnabled = false;
 	/** In-memory cooldown map — seeded from persisted outbox rows on start. */
 	lastFiredAt = /* @__PURE__ */ new Map();
+	/** Per-device rate limit for the "matched NO rule" report — see `reportNoMatch`. */
+	lastNoMatchReportAt = /* @__PURE__ */ new Map();
+	noMatchSuppressed = /* @__PURE__ */ new Map();
 	/**
 	* Serialized evaluation chain. The persist hooks are fire-and-forget for
 	* the frame path, but two concurrent evaluations of the same device
@@ -6733,9 +7035,12 @@ var NotificationCenter = class NotificationCenter {
 			return;
 		}
 		const now = this.now();
+		let anyMatched = false;
+		const rejections = [];
 		for (const rule of candidates) {
 			const evaluation = evaluateRule(rule, subject);
 			if (!evaluation.matched) {
+				rejections.push(`${rule.name}:${evaluation.failedCondition ?? "unknown"}`);
 				this.logger.debug("rule did not match", {
 					tags: { deviceId: subject.deviceId },
 					meta: {
@@ -6779,7 +7084,33 @@ var NotificationCenter = class NotificationCenter {
 			});
 			const userTargets = await this.resolveUserTargets(rule, subject.deviceId);
 			if (await this.outbox.enqueue(this.buildEntries(rule, subject, kind, evaluation.matchedOn, userTargets)) > 0) this.lastFiredAt.set(key, now);
+			anyMatched = true;
+		}
+		if (!anyMatched && rejections.length > 0) this.reportNoMatch(subject, kind, rejections, now);
+	}
+	/** See the call site. Bounded to one line per device per window. */
+	reportNoMatch(subject, kind, rejections, now) {
+		const last = this.lastNoMatchReportAt.get(subject.deviceId) ?? 0;
+		const suppressed = this.noMatchSuppressed.get(subject.deviceId) ?? 0;
+		if (now - last < NO_MATCH_REPORT_INTERVAL_MS) {
+			this.noMatchSuppressed.set(subject.deviceId, suppressed + 1);
+			return;
 		}
+		this.lastNoMatchReportAt.set(subject.deviceId, now);
+		this.noMatchSuppressed.set(subject.deviceId, 0);
+		this.logger.info("event matched NO rule", {
+			tags: { deviceId: subject.deviceId },
+			meta: {
+				kind,
+				rejectedBy: rejections,
+				classes: subject.classNames,
+				...subject.confidence !== void 0 ? { confidence: subject.confidence } : {},
+				...subject.zones.length > 0 ? { zones: subject.zones } : { zones: [] },
+				eventId: subject.recordId,
+				...subject.trackId !== void 0 ? { trackId: subject.trackId } : {},
+				...suppressed > 0 ? { alsoSuppressedSinceLastReport: suppressed } : {}
+			}
+		});
 	}
 	buildEntries(rule, subject, kind, matchedOn, userTargets = []) {
 		const hasEventMedia = kind === "object-event" || kind === "package-event";
@@ -7874,6 +8205,63 @@ function classifyTrackAppearance(input) {
 	return input.positionsCount > 1 ? "resurrection" : "birth";
 }
 //#endregion
+//#region src/pipeline-analytics/pipeline/suppressed-births.ts
+/**
+* Memory of births the confirmation gate rejected, per device.
+*
+* The gate runs AFTER the TrackStore upsert, and it has to: the upsert's
+* position count is what distinguishes a true birth from a tracker
+* resurrection. So a rejected birth has already been written by the time the
+* verdict exists. It correctly gets no `start`, no media and no notification —
+* but the record stayed, and surfaced in `listRecentTracks`. On 2026-07-31 six
+* full-frame phantoms on device 615 in nine minutes were every one of them
+* suppressed AND listed.
+*
+* Retracting once is not enough. The tracker keeps carrying a rejected id for
+* as long as the phantom persists — 27 seconds in the worst measured case — and
+* every later frame would write it straight back. So the rejection is
+* remembered until the id stops being tracked, and only then forgotten.
+*
+* Kept as its own module because the state is the part with real risk: forget
+* too early and the phantom returns, never forget and a camera producing
+* phantoms continuously grows this set for the process's lifetime.
+*/
+var SuppressedBirthRegistry = class {
+	byDevice = /* @__PURE__ */ new Map();
+	/** Record that this birth was rejected; later frames must not re-upsert it. */
+	reject(deviceKey, trackId) {
+		let ids = this.byDevice.get(deviceKey);
+		if (!ids) {
+			ids = /* @__PURE__ */ new Set();
+			this.byDevice.set(deviceKey, ids);
+		}
+		ids.add(trackId);
+	}
+	isRejected(deviceKey, trackId) {
+		return this.byDevice.get(deviceKey)?.has(trackId) === true;
+	}
+	/**
+	* Forget every rejected id the tracker is no longer carrying.
+	*
+	* Called once per frame with the ids present THIS frame. An id absent from
+	* that set can never be upserted again, so holding it serves nothing.
+	*/
+	retain(deviceKey, currentTrackIds) {
+		const ids = this.byDevice.get(deviceKey);
+		if (!ids) return;
+		for (const id of ids) if (!currentTrackIds.has(id)) ids.delete(id);
+		if (ids.size === 0) this.byDevice.delete(deviceKey);
+	}
+	/** Rejected ids currently held for a device — diagnostics and tests. */
+	size(deviceKey) {
+		return this.byDevice.get(deviceKey)?.size ?? 0;
+	}
+	/** Drop a device's memory wholesale (device removed / pipeline reset). */
+	clearDevice(deviceKey) {
+		this.byDevice.delete(deviceKey);
+	}
+};
+//#endregion
 //#region src/pipeline-analytics/pipeline/key-event-query.ts
 async function rankKeyEvents(candidates, options, peakLookup) {
 	const scored = [];
@@ -8378,9 +8766,9 @@ async function extractCrop(frameData, frameWidth, frameHeight, bbox) {
 * padding === 0 is the identity operation. Pure, immutable — always returns a
 * new object.
 *
-* NOTE: clamping is single-sided — when the box hugs an edge, the origin is
-* clamped to 0/keeps the full padded extent against the opposite bound, so the
-* crop can extend slightly further on the far side than the symmetric padding
+* NOTE: clamping SHIFTS, it does not truncate — a window that overflows a
+* bound slides inward and keeps the extent that was asked for, on either side.
+* It shrinks only when the padded window is larger than the frame itself
 * would (e.g. a left-hugging box gains a bit more right-side context). This is
 * acceptable for detection crops (more context, never out of [0,1]); the
 * downstream `extractCrop` clamps to pixel bounds again regardless.
@@ -8390,13 +8778,13 @@ function padBbox(bbox, padding) {
 	const rawY = bbox.y - padding * bbox.h;
 	const rawW = bbox.w * (1 + 2 * padding);
 	const rawH = bbox.h * (1 + 2 * padding);
-	const x = Math.max(0, rawX);
-	const y = Math.max(0, rawY);
+	const w = Math.min(rawW, 1);
+	const h = Math.min(rawH, 1);
 	return {
-		x,
-		y,
-		w: Math.min(rawW, 1 - x),
-		h: Math.min(rawH, 1 - y)
+		x: Math.min(Math.max(0, rawX), 1 - w),
+		y: Math.min(Math.max(0, rawY), 1 - h),
+		w,
+		h
 	};
 }
 //#endregion
@@ -12091,7 +12479,11 @@ function squareSubjectCropRegion(bbox, frame) {
 *      cases). `C` becomes the middle square of the output.
 *   2. canvas: `canvasW = round(c × 16/9)`, `canvasH = c`.
 *   3. anchor: place the canvas so `C` is its horizontal middle →
-*      `frameOriginX = C.x − (canvasW − c)/2` (frame-x mapping to canvas-x 0).
+*      `frameOriginX = C.x − (canvasW − c)/2` (frame-x mapping to canvas-x 0),
+*      then CLAMP the window fully inside the frame whenever it fits. The
+*      subject therefore drifts off-centre near a frame edge and the output
+*      carries no padding at all. Centring is a preference; containing the
+*      subject is the contract, and clamping cannot break it.
 *   4. in-frame slab: intersect `[frameOriginX, frameOriginX + canvasW]` with
 *      `[0, W]`; the slab is that intersection at full height `c` (C ⊆ frame ⇒
 *      the vertical extent is always in-frame). Its canvas offset is
@@ -12103,13 +12495,8 @@ function wideCentralSquareLayout(bbox, frame) {
 	const canvasW = Math.round(c * 16 / 9);
 	const centralX0 = Math.round((canvasW - c) / 2);
 	let frameOriginX = central.x - (canvasW - c) / 2;
-	if (canvasW <= frame.W) {
-		const slideRightMax = Math.max(0, bbox.x - central.x);
-		const slideLeftMax = Math.max(0, central.x + c - (bbox.x + bbox.w));
-		if (frameOriginX < 0) frameOriginX += Math.min(-frameOriginX, slideRightMax);
-		const overRight = frameOriginX + canvasW - frame.W;
-		if (overRight > 0) frameOriginX -= Math.min(overRight, slideLeftMax);
-	} else frameOriginX = (frame.W - canvasW) / 2;
+	if (canvasW <= frame.W) frameOriginX = Math.min(Math.max(0, frameOriginX), frame.W - canvasW);
+	else frameOriginX = (frame.W - canvasW) / 2;
 	const fxa = Math.max(0, frameOriginX);
 	const slabW = Math.min(frame.W, frameOriginX + canvasW) - fxa;
 	const slabOffsetX = fxa - frameOriginX;
@@ -12158,10 +12545,17 @@ var LETTERBOX_BLUR_BRIGHTNESS = .55;
 /**
 * Compose the native-resolution 16:9 central-square WINDOW (`thumbnail`) from the
 * in-frame slab fetched for `layout`. The slab is placed at its computed offset
-* on a 16:9 canvas; any lateral part of the window outside the frame (a subject
-* flush against a frame edge — the geometry already slides the window in-frame
-* wherever the subject has slack) is filled with a BLURRED, dimmed stretch of
-* the slab itself instead of dead black bars (operator triage 2026-07-22).
+* on a 16:9 canvas; any lateral part of the window outside the frame is filled
+* with a BLURRED, dimmed stretch of the slab itself instead of dead black bars
+* (operator triage 2026-07-22).
+*
+* **That fill is now nearly unreachable, and deliberately so.** The geometry
+* clamps the window fully inside the frame whenever it fits, so a subject
+* against a frame edge yields real pixels off-centre rather than ambience
+* (operator directive 2026-07-31). Only a window WIDER THAN THE FRAME ITSELF
+* still pads — there is no more scene to slide into — which is why this code
+* stays. If you are looking at a blurred band in a best shot, the window was
+* wider than the frame; do not go looking for a sliding bug.
 * When the whole window is in-frame (`slab` already spans the full canvas) the
 * slab is returned VERBATIM (no re-encode). NEVER upscales the real image —
 * the canvas is at the slab's native scale; only the out-of-frame ambience fill
@@ -13284,6 +13678,13 @@ var ZoneAnalyticsProvider = class {
 					zones: snapshot.zones.length
 				}
 			});
+			this.ctx.emitOccupancyChanged?.({
+				deviceId: input.deviceId,
+				timestamp: input.timestamp,
+				totalObjects: total,
+				byClass: snapshot.frame.byClass,
+				zones: snapshot.zones.length
+			});
 		}
 		this.snapshots.set(input.deviceId, snapshot);
 		this.appendHistory(input.deviceId, snapshot);
@@ -15016,6 +15417,15 @@ function buildDetectionSettingsSections() {
 					step: .05,
 					default: TRACKING_DEFAULTS.rescueIouThreshold
 				},
+				{
+					type: "number",
+					key: "rescueCentroidFactor",
+					label: "Rescue centroid distance",
+					description: "The other half of the rescue gate: how far a detection’s centre may sit from the track’s last-known centre, as a fraction of the box diagonal. A rescue must pass BOTH this and the rescue IoU, so raising the IoU alone does not tighten re-attachment.",
+					min: 0,
+					step: .05,
+					default: TRACKING_DEFAULTS.rescueCentroidFactor
+				},
 				{
 					type: "number",
 					key: "stationarySpeedPx",
@@ -15297,6 +15707,16 @@ function buildDetectionSettingsSections() {
 					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.",
 					default: TRACKING_DEFAULTS.classGroupAssoc
+				},
+				{
+					type: "number",
+					key: "zoneMembershipMinOverlap",
+					label: "Zone membership minimum overlap",
+					description: "How much of a detection box must fall inside a zone for the detection to be STAMPED with it — as a fraction of the BOX area, not of the zone. 0 stamps on any touch, which is what let a plant brushing a zone by 6% fire a \"person on the doorstep\" rule. Only a stamped zone can match a zone-scoped notification rule. Read the \"zone membership stamped on event\" log line to choose the value: it prints the achieved percentage per zone.",
+					min: 0,
+					max: 1,
+					step: .05,
+					default: TRACKING_DEFAULTS.zoneMembershipMinOverlap
 				}
 			]
 		},
@@ -19866,6 +20286,9 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 	*  dataPlane facility in the current environment). */
 	eventMediaBaseUrl = null;
 	lastActiveTrackIds = /* @__PURE__ */ new Map();
+	/** See `pipeline/suppressed-births.ts` — rejected births must not be
+	*  re-upserted, and must be forgotten when the tracker drops the id. */
+	suppressedBirths = new SuppressedBirthRegistry();
 	lastFrameDimsByDevice = /* @__PURE__ */ new Map();
 	lastAudioInsertByDevice = /* @__PURE__ */ new Map();
 	lastMotionInsertByDevice = /* @__PURE__ */ new Map();
@@ -20449,6 +20872,22 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 		const zoneAnalytics = new ZoneAnalyticsProvider({
 			logger: logger.child("ZoneAnalytics"),
 			fetchDevice: (deviceId) => this.ctx.fetchDevice(deviceId),
+			emitOccupancyChanged: (payload) => this.ctx.eventBus.emit({
+				id: `za-occ-${payload.deviceId}-${payload.timestamp}`,
+				timestamp: new Date(payload.timestamp),
+				source: {
+					type: "addon",
+					id: "pipeline-analytics",
+					addonId: "pipeline-analytics"
+				},
+				category: EventCategory.ZoneAnalyticsOccupancyChanged,
+				data: {
+					deviceId: payload.deviceId,
+					totalObjects: payload.totalObjects,
+					byClass: payload.byClass,
+					zones: payload.zones
+				}
+			}),
 			listStationaryObjects: (deviceId) => this.stationaryRegistry?.listViews(deviceId) ?? [],
 			listStationaryDeviceIds: () => this.stationaryRegistry?.deviceIds() ?? [],
 			resolveZones: (deviceId) => this.resolveDeviceZones(deviceId),
@@ -20896,6 +21335,15 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 			timestamp: frame.timestamp,
 			frame
 		});
+		for (const r of processor.getLastRiderPairs()) this.ctx.logger.info("rider folded into vehicle", {
+			tags: { deviceId },
+			meta: {
+				vehicleClass: r.vehicleClass,
+				personScore: r.personScore,
+				vehicleScore: r.vehicleScore,
+				overlap: r.overlap
+			}
+		});
 		if (source === "pipeline") this.stationaryRegistry?.noteFrame(deviceId, result.timestamp);
 		if (this.stationaryRegistry && (result.stationaryConfirmed.length > 0 || result.stationaryWoken.length > 0)) this.stationaryRegistry.applyFrameOutcome({
 			deviceId,
@@ -20926,6 +21374,7 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 		const positionsCountById = /* @__PURE__ */ new Map();
 		for (const t of result.tracked) {
 			currentTrackIds.add(t.trackId);
+			if (this.suppressedBirths.isRejected(key, t.trackId)) continue;
 			const center = {
 				x: t.bbox.x + t.bbox.w / 2,
 				y: t.bbox.y + t.bbox.h / 2
@@ -20992,7 +21441,16 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 			frameHeight: result.frameHeight
 		});
 		for (const { id, t } of bornCandidates) {
-			if (!confirmedBirths.has(id)) continue;
+			if (!confirmedBirths.has(id)) {
+				this.suppressedBirths.reject(key, id);
+				this.trackStore?.dropActive(id);
+				log.info("birth suppressed — track record retracted", { meta: {
+					trackId: id,
+					className: t.className,
+					source
+				} });
+				continue;
+			}
 			newTrackCount += 1;
 			log.info("track started", { meta: {
 				trackId: id,
@@ -21053,6 +21511,7 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 				source
 			} });
 		}
+		this.suppressedBirths.retain(key, currentTrackIds);
 		this.lastActiveTrackIds.set(key, currentTrackIds);
 		const stationarySettings = this.stationarySettingsFromCache(deviceId);
 		if (source === "pipeline" && this.stationaryRegistry && stationarySettings.enabled) {
@@ -21124,6 +21583,7 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 		await Promise.all([...result.objectEvents, ...result.appearanceEvents].map((e) => this.eventStore.insertObject(e)));
 		if (this.notificationCenter !== null) {
 			const overlaps = processor.getLastZoneOverlaps();
+			const rejections = processor.getLastZoneRejections();
 			for (const e of result.objectEvents) {
 				if (e.zones && e.zones.length > 0) {
 					const m = e.trackId ? overlaps.get(e.trackId) : void 0;
@@ -21142,6 +21602,22 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 						}
 					});
 				}
+				const rejected = e.trackId ? rejections.get(e.trackId) : void 0;
+				if (rejected !== void 0 && rejected.length > 0) this.ctx.logger.info("zone membership REJECTED by the bar", {
+					tags: { deviceId },
+					meta: {
+						eventId: e.id,
+						trackId: e.trackId,
+						className: e.className,
+						minOverlap: trk.zoneMembershipMinOverlap,
+						stamped: e.zones?.length ?? 0,
+						zones: rejected.map((z) => ({
+							id: z.zoneId,
+							name: z.zoneName,
+							overlapPct: Math.round(z.overlap * 1e3) / 10
+						}))
+					}
+				});
 				this.notificationCenter.onObjectEventPersisted(e);
 			}
 		}