@camstack/addon-post-analysis 1.1.39 → 1.1.41

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-DUcGHr9E.js");
+const require_dist = require("../dist-c2pR8PSR.js");
 let node_crypto = require("node:crypto");
 let sharp = require("sharp");
 sharp = require_dist.__toESM(sharp);
@@ -8108,6 +8108,152 @@ function resolveTrackingSettings(raw) {
 	};
 }
 //#endregion
+//#region src/pipeline-analytics/confirmation-gate-settings.ts
+/**
+* Per-device DETECTION CONFIRMATION GATE tuning.
+*
+* Before a NEW track is born (its `start` lifecycle + firstFrame media emitted)
+* the gate optionally re-runs object detection on the HI-RES NATIVE CROP of the
+* detection box. If the crop does not confirm a compatible object above
+* `minConfidence`, the birth is SUPPRESSED — it was a false positive from the
+* low-res detection frame (a static "person" phantom, a parked-truck ghost, a
+* misclassified static object).
+*
+* Ships DORMANT: `enabled` defaults to `false`, so behaviour is byte-identical
+* to today until an operator opts in per camera. The gate is fail-OPEN — any
+* missing frame handle, unavailable inference cap, crop-fetch miss, re-detection
+* error, or timeout ALLOWS the birth (a real track is never suppressed because
+* confirmation was unavailable).
+*
+* Every field is independently overridable per camera; an unknown/invalid value
+* falls back to the field default (never throws on a bad blob) — mirrors
+* {@link resolveTrackingSettings}.
+*/
+var ConfirmationGateSettingsSchema = require_dist.object({
+	/** Master switch. OFF by default → gate never runs, births unchanged. */
+	enabled: require_dist.boolean().default(false),
+	/**
+	* Minimum re-detection score (0..1) required in the crop for a birth to be
+	* confirmed. A detection must clear this AND be class-compatible with the
+	* track's class.
+	*/
+	minConfidence: require_dist.number().min(0).max(1).default(.4),
+	/**
+	* Minimum crop size (px, longest side in detection-frame pixel space) worth
+	* re-detecting. A subject box smaller than this is too tiny to confirm
+	* reliably, so the gate SKIPS it and fails open (confirms the birth). 0 =
+	* confirm every birth regardless of size.
+	*/
+	minCropPx: require_dist.number().int().min(0).default(48),
+	/**
+	* Per-birth confirmation budget (ms). If the crop fetch + re-detection does
+	* not resolve within this window the gate fails open (confirms the birth) so
+	* the synchronous frame path never stalls on inference.
+	*/
+	timeoutMs: require_dist.number().int().min(1).default(300)
+});
+var CONFIRMATION_GATE_DEFAULTS = ConfirmationGateSettingsSchema.parse({});
+/**
+* Resolve a per-device store blob into typed confirmation-gate settings. The
+* gate's fields live under a nested `confirmationGate` key in the per-device
+* store. Each field is validated independently via `.catch(default)` so an
+* invalid/missing field falls back to its default and parse never throws.
+*/
+function resolveConfirmationGateSettings(raw) {
+	const blob = require_dist.record(require_dist.string(), require_dist.unknown()).catch({}).parse(raw.confirmationGate);
+	const s = ConfirmationGateSettingsSchema.shape;
+	return {
+		enabled: s.enabled.catch(CONFIRMATION_GATE_DEFAULTS.enabled).parse(blob.enabled),
+		minConfidence: s.minConfidence.catch(CONFIRMATION_GATE_DEFAULTS.minConfidence).parse(blob.minConfidence),
+		minCropPx: s.minCropPx.catch(CONFIRMATION_GATE_DEFAULTS.minCropPx).parse(blob.minCropPx),
+		timeoutMs: s.timeoutMs.catch(CONFIRMATION_GATE_DEFAULTS.timeoutMs).parse(blob.timeoutMs)
+	};
+}
+//#endregion
+//#region src/pipeline-analytics/confirmation-gate.ts
+/**
+* Map a fine/raw detector or classifier class name to its coarse group. The
+* runtime detector already emits coarse `macroClass` values (person/vehicle/
+* animal), but a track's `className` may carry a finer class from a downstream
+* classifier — this normalizes both sides to the same three groups. Anything
+* unrecognized maps to `other`, which the compatibility check treats as
+* fail-open (compatible with everything) rather than a hard mismatch.
+*/
+function coarseGroupForClass(className) {
+	const c = className.trim().toLowerCase();
+	if (c === "person" || c === "people" || c === "pedestrian" || c === "human") return "person";
+	if (c === "vehicle" || c === "car" || c === "truck" || c === "bus" || c === "van" || c === "motorcycle" || c === "motorbike" || c === "bicycle" || c === "bike") return "vehicle";
+	if (c === "animal" || c === "dog" || c === "cat" || c === "bird" || c === "horse" || c === "sheep" || c === "cow" || c === "bear" || c === "deer" || c === "fox") return "animal";
+	return "other";
+}
+/**
+* A re-detection in the crop is COMPATIBLE with the track's class when both map
+* to the same coarse group. When either side is unknown (`other`) we fail open
+* — treat it as compatible — so an unusual class never wrongly suppresses a
+* real track.
+*/
+function isConfirmationCompatible(trackClassName, detectionMacroClass) {
+	const track = coarseGroupForClass(trackClassName);
+	const det = coarseGroupForClass(detectionMacroClass);
+	if (track === "other" || det === "other") return true;
+	return track === det;
+}
+var failOpen = (trackId, reason) => ({
+	trackId,
+	confirmed: true,
+	reason
+});
+function withTimeout(promise, timeoutMs) {
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => reject(/* @__PURE__ */ new Error("confirmation-timeout")), timeoutMs);
+		promise.then((value) => {
+			clearTimeout(timer);
+			resolve(value);
+		}, (err) => {
+			clearTimeout(timer);
+			reject(err instanceof Error ? err : new Error(String(err)));
+		});
+	});
+}
+async function runConfirmation(candidate, config, deps) {
+	const crop = await deps.fetchCrop(candidate);
+	if (!crop) return failOpen(candidate.trackId, "no-crop");
+	const detections = await deps.redetect(crop);
+	if (detections === null) return failOpen(candidate.trackId, "redetect-error");
+	const confirmed = detections.some((d) => d.score >= config.minConfidence && isConfirmationCompatible(candidate.className, d.macroClass));
+	return {
+		trackId: candidate.trackId,
+		confirmed,
+		reason: confirmed ? "confirmed" : "suppressed"
+	};
+}
+async function confirmOne(candidate, config, deps) {
+	const cropPx = Math.max(candidate.bbox.w, candidate.bbox.h);
+	if (config.minCropPx > 0 && cropPx < config.minCropPx) return failOpen(candidate.trackId, "below-min-crop");
+	try {
+		return await withTimeout(runConfirmation(candidate, config, deps), config.timeoutMs);
+	} catch {
+		return failOpen(candidate.trackId, "timeout");
+	}
+}
+/**
+* Confirm a batch of birth candidates CONCURRENTLY and return the set of
+* trackIds whose births may PROCEED. When the gate is disabled (or there are no
+* candidates) every candidate is confirmed — byte-identical to no gate. The
+* caller runs this once, then processes only the confirmed births, preserving
+* the original birth-loop ordering.
+*/
+async function confirmBirths(candidates, config, deps) {
+	if (!config.enabled || candidates.length === 0) return new Set(candidates.map((c) => c.trackId));
+	const decisions = await Promise.all(candidates.map((c) => confirmOne(c, config, deps)));
+	const confirmed = /* @__PURE__ */ new Set();
+	for (const decision of decisions) {
+		deps.onDecision?.(decision);
+		if (decision.confirmed) confirmed.add(decision.trackId);
+	}
+	return confirmed;
+}
+//#endregion
 //#region src/pipeline-analytics/face-settings.ts
 /**
 * Per-device face-recognition settings. Cascade: a per-device override on top
@@ -11768,6 +11914,15 @@ var DETAIL_FALLBACK_CROP_PADDING = .15;
 *  before re-reading. */
 var CLIP_MODEL_ID_CACHE_TTL_MS = 6e4;
 var SETTINGS_CACHE_TTL_MS = 5e3;
+/** TTL for the per-node confirmation-gate detector-step cache (the node's
+*  default object-detector step rarely changes). */
+var CONFIRMATION_DETECTOR_CACHE_TTL_MS = 6e4;
+/** Padding applied to a birth box before re-detecting it — a little context
+*  around the subject improves the confirmation detector's recall. */
+var CONFIRMATION_CROP_PADDING = .15;
+/** Cap the confirmation crop width so a 4K native surface never floods the
+*  transport just to confirm one small box. */
+var CONFIRMATION_CROP_MAX_WIDTH = 320;
 /** Reconcile cadence for the per-device `zones` / `zoneRules` slice handles.
 *  The `device.state-changed` push doesn't reliably reach a forked child, so
 *  each cached proxy re-pulls both slices on this timer (see ensureProxy) —
@@ -11999,6 +12154,12 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 	settingsCacheByDevice = /* @__PURE__ */ new Map();
 	sensitivityCacheByDevice = /* @__PURE__ */ new Map();
 	trackingCacheByDevice = /* @__PURE__ */ new Map();
+	/** Per-device confirmation-gate settings cache (default off), TTL-mirrored. */
+	confirmationGateCacheByDevice = /* @__PURE__ */ new Map();
+	/** Per-node detector-step cache for the confirmation gate's re-detection —
+	*  the node's default root object-detector reduced to a single childless
+	*  step, resolved lazily from `pipelineExecutor.getGlobalSteps` and reused. */
+	confirmationDetectorStepByNode = /* @__PURE__ */ new Map();
 	faceCacheByDevice = /* @__PURE__ */ new Map();
 	/** GLOBAL face-recognition master switch (addon store), TTL-cached. */
 	faceGlobalEnabledCache = null;
@@ -12118,7 +12279,7 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 		let storage = this.ctx.kernel.storage;
 		const mediaRoot = process.env.CAMSTACK_MEDIA_ROOT?.trim();
 		if (mediaRoot) {
-			const { FilesystemStorageProvider } = await Promise.resolve().then(() => require("../node-B7HfyyIy.js"));
+			const { FilesystemStorageProvider } = await Promise.resolve().then(() => require("../node-Bm-b5K4I.js"));
 			storage = new FilesystemStorageProvider(mediaRoot);
 			logger.info("pipeline-analytics: event media rooted at CAMSTACK_MEDIA_ROOT", { meta: { mediaRoot } });
 		}
@@ -12530,6 +12691,7 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 				this.settingsCacheByDevice.delete(data.deviceId);
 				this.sensitivityCacheByDevice.delete(data.deviceId);
 				this.trackingCacheByDevice.delete(data.deviceId);
+				this.confirmationGateCacheByDevice.delete(data.deviceId);
 				this.faceCacheByDevice.delete(data.deviceId);
 				this.mediaCacheByDevice.delete(data.deviceId);
 				this.packageDropCacheByDevice.delete(data.deviceId);
@@ -12547,6 +12709,7 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 			this.settingsCacheByDevice.delete(deviceId);
 			this.sensitivityCacheByDevice.delete(deviceId);
 			this.trackingCacheByDevice.delete(deviceId);
+			this.confirmationGateCacheByDevice.delete(deviceId);
 			this.faceCacheByDevice.delete(deviceId);
 			this.mediaCacheByDevice.delete(deviceId);
 			this.packageDropCacheByDevice.delete(deviceId);
@@ -12898,6 +13061,8 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 		this.settingsCacheByDevice.clear();
 		this.sensitivityCacheByDevice.clear();
 		this.trackingCacheByDevice.clear();
+		this.confirmationGateCacheByDevice.clear();
+		this.confirmationDetectorStepByNode.clear();
 		this.faceCacheByDevice.clear();
 		this.faceGlobalEnabledCache = null;
 		this.mediaCacheByDevice.clear();
@@ -13013,70 +13178,88 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 		const prevIds = this.lastActiveTrackIds.get(key) ?? /* @__PURE__ */ new Set();
 		const firstFrameTargets = [];
 		let newTrackCount = 0;
-		for (const id of currentTrackIds) if (!prevIds.has(id)) {
+		const bornCandidates = [];
+		for (const id of currentTrackIds) {
+			if (prevIds.has(id)) continue;
 			const t = result.tracked.find((x) => x.trackId === id);
-			if (t) {
-				if (classifyTrackAppearance({
-					inPrevActive: false,
-					positionsCount: positionsCountById.get(id) ?? 1
-				}) === "resurrection") {
-					log.info("track resumed", { meta: {
-						trackId: id,
-						className: t.className,
-						source,
-						resurrected: true
-					} });
-					continue;
-				}
-				newTrackCount += 1;
-				log.info("track started", { meta: {
+			if (!t) continue;
+			if (classifyTrackAppearance({
+				inPrevActive: false,
+				positionsCount: positionsCountById.get(id) ?? 1
+			}) === "resurrection") {
+				log.info("track resumed", { meta: {
 					trackId: id,
 					className: t.className,
-					source
+					source,
+					resurrected: true
 				} });
-				if (this.eventMediaDispatcher && frameHandle) {
-					firstFrameTargets.push({
-						trackId: id,
-						timestamp: result.timestamp,
-						bbox: { ...t.bbox },
-						...t.label ? { label: t.label } : {}
-					});
-					this.trackStore.seedSnapshotClock(id, result.timestamp, t.bbox);
-				}
-				this.ctx.eventBus.emit({
-					id: `pa-${(0, node_crypto.randomUUID)()}`,
-					timestamp: new Date(result.timestamp),
-					source: {
-						type: "addon",
-						id: "pipeline-analytics",
-						addonId: "pipeline-analytics"
-					},
-					category: require_dist.EventCategory.PipelineAnalyticsTrackStarted,
-					data: {
-						deviceId,
-						trackId: id,
-						className: t.className
-					}
-				});
-				const startPayload = buildTrackLifecyclePayload({
-					deviceId,
+				continue;
+			}
+			bornCandidates.push({
+				id,
+				t
+			});
+		}
+		const confirmedBirths = await this.confirmTrackBirths(bornCandidates.map(({ id, t }) => ({
+			trackId: id,
+			className: t.className,
+			bbox: t.bbox
+		})), {
+			deviceId,
+			frameHandle,
+			frameWidth: result.frameWidth,
+			frameHeight: result.frameHeight
+		});
+		for (const { id, t } of bornCandidates) {
+			if (!confirmedBirths.has(id)) continue;
+			newTrackCount += 1;
+			log.info("track started", { meta: {
+				trackId: id,
+				className: t.className,
+				source
+			} });
+			if (this.eventMediaDispatcher && frameHandle) {
+				firstFrameTargets.push({
 					trackId: id,
-					phase: "start",
-					classes: [t.className],
-					bestClassName: t.className,
-					bestConfidence: t.confidence,
-					firstSeen: result.timestamp,
-					lastSeen: result.timestamp,
-					...t.label !== void 0 ? { label: t.label } : {}
-				});
-				this.emitTrackLifecycle(startPayload, result.timestamp);
-				this.trackLifecycleUpdateMem.set(id, {
-					lastConfidence: t.confidence,
-					lastEmitAt: result.timestamp,
-					...t.label !== void 0 ? { lastLabel: t.label } : {},
-					lastBboxArea: t.bbox.w * t.bbox.h
+					timestamp: result.timestamp,
+					bbox: { ...t.bbox },
+					...t.label ? { label: t.label } : {}
 				});
+				this.trackStore.seedSnapshotClock(id, result.timestamp, t.bbox);
 			}
+			this.ctx.eventBus.emit({
+				id: `pa-${(0, node_crypto.randomUUID)()}`,
+				timestamp: new Date(result.timestamp),
+				source: {
+					type: "addon",
+					id: "pipeline-analytics",
+					addonId: "pipeline-analytics"
+				},
+				category: require_dist.EventCategory.PipelineAnalyticsTrackStarted,
+				data: {
+					deviceId,
+					trackId: id,
+					className: t.className
+				}
+			});
+			const startPayload = buildTrackLifecyclePayload({
+				deviceId,
+				trackId: id,
+				phase: "start",
+				classes: [t.className],
+				bestClassName: t.className,
+				bestConfidence: t.confidence,
+				firstSeen: result.timestamp,
+				lastSeen: result.timestamp,
+				...t.label !== void 0 ? { label: t.label } : {}
+			});
+			this.emitTrackLifecycle(startPayload, result.timestamp);
+			this.trackLifecycleUpdateMem.set(id, {
+				lastConfidence: t.confidence,
+				lastEmitAt: result.timestamp,
+				...t.label !== void 0 ? { lastLabel: t.label } : {},
+				lastBboxArea: t.bbox.w * t.bbox.h
+			});
 		}
 		let lostTrackCount = 0;
 		for (const id of prevIds) if (!currentTrackIds.has(id)) {
@@ -13357,6 +13540,146 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 		});
 		return settings;
 	}
+	/** Per-device confirmation-gate settings (default OFF), TTL-cached like the
+	*  other per-device tunables. */
+	async resolveDeviceConfirmationGateSettings(deviceId) {
+		const now = Date.now();
+		const cached = this.confirmationGateCacheByDevice.get(deviceId);
+		if (cached && now < cached.expiresAt) return cached.settings;
+		const settings = resolveConfirmationGateSettings(await this.ctx?.settings?.readDeviceStore(deviceId) ?? {});
+		this.confirmationGateCacheByDevice.set(deviceId, {
+			settings,
+			expiresAt: now + SETTINGS_CACHE_TTL_MS
+		});
+		return settings;
+	}
+	/**
+	* Narrowed, version-skew-safe handle onto the `pipelineExecutor` cap — same
+	* structural-cast pattern as the `pipelineRunner` handle above. A node whose
+	* executor predates these methods simply yields `undefined`, and the
+	* confirmation gate then fails open (allows the birth).
+	*/
+	pipelineExecutorApi() {
+		const api = this.ctx?.api;
+		if (!api) return void 0;
+		return api.pipelineExecutor;
+	}
+	/**
+	* Resolve (and cache) the confirmation gate's re-detection step for a node:
+	* the node's DEFAULT root object-detector (from `getGlobalSteps`) reduced to a
+	* single CHILDLESS step, so the confirmation run does detection ONLY — no
+	* crop/classifier subtree. Cached per node (TTL) since the node default rarely
+	* changes. `null` ⇒ no detector available ⇒ the gate fails open.
+	*/
+	async resolveConfirmationDetectorStep(nodeId) {
+		const now = Date.now();
+		const cached = this.confirmationDetectorStepByNode.get(nodeId);
+		if (cached && now < cached.expiresAt) return cached.step;
+		let step = null;
+		const executor = this.pipelineExecutorApi();
+		if (executor?.getGlobalSteps) try {
+			const steps = await executor.getGlobalSteps.query(void 0, require_dist.nodePin(nodeId));
+			const detector = steps?.find((s) => s.slot === "detector" && s.enabled) ?? steps?.find((s) => s.slot === "detector");
+			if (detector) step = {
+				addonId: detector.addonId,
+				...detector.modelId ? { modelId: detector.modelId } : {},
+				enabled: true
+			};
+		} catch (err) {
+			this.ctx.logger.debug("confirmation gate: getGlobalSteps failed", { meta: {
+				nodeId,
+				error: require_dist.errMsg(err)
+			} });
+		}
+		this.confirmationDetectorStepByNode.set(nodeId, {
+			step,
+			expiresAt: now + CONFIRMATION_DETECTOR_CACHE_TTL_MS
+		});
+		return step;
+	}
+	/**
+	* Re-run object detection on a confirmation crop JPEG via the frame-owning
+	* node's `pipelineExecutor` (pinned by `nodeId`, matching the native-crop
+	* fetch). Returns the crop's detections, or `null` on any unavailability /
+	* error so the gate fails open.
+	*/
+	async redetectCropForConfirmation(nodeId, deviceId, cropJpeg) {
+		const step = await this.resolveConfirmationDetectorStep(nodeId);
+		if (!step) return null;
+		const executor = this.pipelineExecutorApi();
+		if (!executor?.runPipeline) return null;
+		try {
+			const detections = (await executor.runPipeline.mutate({
+				steps: [step],
+				image: new Uint8Array(cropJpeg),
+				deviceId,
+				plane: "frame"
+			}, require_dist.nodePin(nodeId)))?.detections;
+			if (!detections) return null;
+			return detections.map((d) => ({
+				macroClass: d.macroClass,
+				score: d.score
+			}));
+		} catch (err) {
+			this.ctx.logger.debug("confirmation gate: re-detection failed — fail-open", {
+				tags: { deviceId },
+				meta: { error: require_dist.errMsg(err) }
+			});
+			return null;
+		}
+	}
+	/**
+	* Confirm a batch of track-birth candidates before they are created. Returns
+	* the set of trackIds whose births may PROCEED. When the gate is disabled
+	* (default) or no crop path is available, every candidate is confirmed —
+	* byte-identical to no gate. Confirmations run CONCURRENTLY (one inference per
+	* candidate) and each failure path fails OPEN, so the synchronous frame path
+	* is never blocked or reordered by a slow/failed re-detection.
+	*/
+	async confirmTrackBirths(candidates, params) {
+		const allConfirmed = () => new Set(candidates.map((c) => c.trackId));
+		if (candidates.length === 0) return allConfirmed();
+		const config = await this.resolveDeviceConfirmationGateSettings(params.deviceId);
+		if (!config.enabled) return allConfirmed();
+		const { frameHandle, frameWidth, frameHeight, deviceId } = params;
+		const captureCrop = this.captureCrop;
+		if (!frameHandle || !captureCrop || frameWidth <= 0 || frameHeight <= 0) {
+			this.ctx.logger.debug("confirmation gate: no crop path — births allowed (fail-open)", {
+				tags: { deviceId },
+				meta: {
+					candidates: candidates.length,
+					hasHandle: Boolean(frameHandle)
+				}
+			});
+			return allConfirmed();
+		}
+		const nodeId = frameHandle.nodeId;
+		return confirmBirths(candidates, config, {
+			fetchCrop: (candidate) => captureCrop(frameHandle, {
+				x: candidate.bbox.x,
+				y: candidate.bbox.y,
+				w: candidate.bbox.w,
+				h: candidate.bbox.h
+			}, frameWidth, frameHeight, CONFIRMATION_CROP_PADDING, CONFIRMATION_CROP_MAX_WIDTH),
+			redetect: (cropJpeg) => this.redetectCropForConfirmation(nodeId, deviceId, cropJpeg),
+			onDecision: (decision) => {
+				if (!decision.confirmed) this.ctx.logger.info("confirmation gate: birth suppressed (false positive)", {
+					tags: { deviceId },
+					meta: {
+						trackId: decision.trackId,
+						reason: decision.reason
+					}
+				});
+				else if (decision.reason !== "confirmed") this.ctx.logger.debug("confirmation gate: birth allowed (fail-open)", {
+					tags: { deviceId },
+					meta: {
+						trackId: decision.trackId,
+						reason: decision.reason
+					}
+				});
+			}
+		});
+	}
 	async resolveGlobalFaceEnabled() {
 		const now = Date.now();
 		if (this.faceGlobalEnabledCache && now < this.faceGlobalEnabledCache.expiresAt) return this.faceGlobalEnabledCache.value;
@@ -16069,6 +16392,7 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 		this.settingsCacheByDevice.delete(input.deviceId);
 		this.sensitivityCacheByDevice.delete(input.deviceId);
 		this.trackingCacheByDevice.delete(input.deviceId);
+		this.confirmationGateCacheByDevice.delete(input.deviceId);
 		this.forgetDeviceProcessors(input.deviceId);
 		return { success: true };
 	}