@camstack/addon-post-analysis 1.2.48 → 1.2.49

package/dist/pipeline-analytics/index.mjs

@@ -1,4 +1,4 @@
-import { $ as object, B as errMsg, C as buildEventKindDescriptor, E as defineCustomActions, F as readDeviceStateFrom, G as isDeviceScopedCap, H as DeviceType, I as subKindsOf, J as _enum, K as nodePin, L as vectorDimFromBase64, M as notificationRulesCapability, N as pipelineAnalyticsCapability, O as encodeVectorBase64, P as plateGalleryCapability, Q as number, R as videoclipsCapability, S as audioMetricsCapability, T as customAction, U as createEvent, V as BaseAddon, W as hydrateSchema, X as boolean, Y as array, Z as literal, _ as TimelapseRuleInputSchema, a as MACRO_LABELS, b as addonWidgetsSourceCapability, c as NcConditionDescriptorSchema, d as NcRuleSchema, et as record, f as NcSnoozeInputSchema, g as OpsLogEntrySchema, h as NcTaxonomySchema, i as EVENT_PAD_MS, j as kebabToCamel, k as faceGalleryCapability, l as NcRuleInputSchema, m as NcSnoozeSuppressedSchema, n as DEFAULT_EVENT_COLOR, nt as unknown, o as NC_CONDITION_CATALOG, p as NcSnoozeSchema, q as sleep, r as EVENT_KIND_BY_CAP, rt as EventCategory, s as NC_TAXONOMY, t as BaseDevice, tt as string, u as NcRulePatchSchema, v as TimelapseRuleSchema, w as cosineSimilarity, x as alarmPanelCapability, y as TrackSourceSchema, z as zoneAnalyticsCapability } from "../dist-4NhN1aPx.mjs";
+import { $ as object, B as errMsg, C as buildEventKindDescriptor, E as defineCustomActions, F as readDeviceStateFrom, G as isDeviceScopedCap, H as DeviceType, I as subKindsOf, J as _enum, K as nodePin, L as vectorDimFromBase64, M as notificationRulesCapability, N as pipelineAnalyticsCapability, O as encodeVectorBase64, P as plateGalleryCapability, Q as number, R as videoclipsCapability, S as audioMetricsCapability, T as customAction, U as createEvent, V as BaseAddon, W as hydrateSchema, X as boolean, Y as array, Z as literal, _ as TimelapseRuleInputSchema, a as MACRO_LABELS, b as addonWidgetsSourceCapability, c as NcConditionDescriptorSchema, d as NcRuleSchema, et as record, f as NcSnoozeInputSchema, g as OpsLogEntrySchema, h as NcTaxonomySchema, i as EVENT_PAD_MS, j as kebabToCamel, k as faceGalleryCapability, l as NcRuleInputSchema, m as NcSnoozeSuppressedSchema, n as DEFAULT_EVENT_COLOR, nt as unknown, o as NC_CONDITION_CATALOG, p as NcSnoozeSchema, q as sleep, r as EVENT_KIND_BY_CAP, rt as EventCategory, s as NC_TAXONOMY, t as BaseDevice, tt as string, u as NcRulePatchSchema, v as TimelapseRuleSchema, w as cosineSimilarity, x as alarmPanelCapability, y as TrackSourceSchema, z as zoneAnalyticsCapability } from "../dist-DYOxxL_e.mjs";
 import { promises } from "node:fs";
 import path from "node:path";
 import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
@@ -6806,6 +6806,34 @@ function isEdgeAwareNewBest(current, candidate, hysteresis) {
 //#endregion
 //#region src/pipeline-analytics/pipeline/label-utils.ts
 /**
+* Every macro class the pipeline can carry on a detection. A `label` exists to
+* say something FINER than the class — a species, a vehicle type, a plate read,
+* an identity — so a value drawn from this set is by definition not a label,
+* whatever produced it.
+*
+* Typed against the macro unions so a new macro class is a compile error here
+* rather than a silent hole. `package` is a first-level macro of the default
+* detector that predates `FirstLevelMacro`, hence the explicit member.
+*/
+var MACRO_CLASSES = new Set([
+	"person",
+	"vehicle",
+	"animal",
+	"package",
+	"face",
+	"plate",
+	"audio"
+]);
+/**
+* Whether a class token is a macro class. EXACT match, no case folding: plate
+* OCR text is upper-case and identities are capitalised, so `PLATE` (a real
+* read) and `Person` (a real name) must survive while `plate` / `person` (the
+* taxonomy tokens) must not.
+*/
+function isMacroClass(value) {
+	return MACRO_CLASSES.has(value);
+}
+/**
 * Opaque internal label markers that carry no human-readable meaning and must
 * never surface on an event/track. The face-embedding (arcface) step pushes a
 * `embedding:<dim>d` marker (score 1.0) onto the parent's labels — it is a
@@ -6836,12 +6864,26 @@ function pickTopLabel(labels, excludeClass) {
 /**
 * Resolve the label to stamp on an ObjectEvent / track: an enrichment label
 * (identity, plate text) takes precedence; otherwise the raw detector class
-* (`originalClass`) when it differs from the macro class; otherwise nothing.
+* (`originalClass`) when it is genuinely FINER than the macro class; otherwise
+* nothing.
+*
+* "Finer" is load-bearing, and `originalClass !== className` alone does not
+* establish it. The two fields come from different time bases — `className` is
+* the tracker's confidence-weighted LIFETIME class vote, `originalClass` is the
+* class of the detection matched into the track THIS frame — and outside
+* `verbosity === 'full'` the runner ships no `debug.originalClass` at all, so
+* the FrameProcessor substitutes `det.macroClass`. A person track that a single
+* animal detection matched into therefore arrived here as
+* `{ className: 'person', originalClass: 'animal' }` and got `label: 'animal'`
+* written on it: a COARSE class in the slot reserved for finer information.
+* A macro class is never an answer, so it is never a label.
 */
 function resolveDetectionLabel(input) {
 	const top = pickTopLabel(input.labels, input.className);
 	if (top) return top;
-	return input.originalClass && input.originalClass !== input.className ? input.originalClass : void 0;
+	const raw = input.originalClass;
+	if (raw === void 0 || raw === input.className || isMacroClass(raw)) return void 0;
+	return raw;
 }
 var DEFAULT_ZONE_TRANSITION_CONFIG = {
 	enterFrames: 2,
@@ -11834,9 +11876,24 @@ var TrackDetailDispatcher = class {
 		dev.scheduler.onResult(req.trackId, req.stepId, topScore, Date.now());
 	}
 	/**
-	* Run the request once via the frameHandle, and — on a miss (null OR throw)
-	* — retry ONCE with a `cropJpeg` fallback when one can be captured. Returns
-	* the detail list, or `null` when both attempts fail to produce a result.
+	* Walk the crop-source ladder for one request, stopping at the first rung that
+	* produces a result. Returns the detail list, or `null` when every rung failed.
+	*
+	* 1. `frameHandle` — cheapest when it hits: no payload moves and the runner's
+	*    leaf children re-cut their ROI at native resolution. Tried first, always.
+	* 2. `frameJpeg` — the freshest frame's FULL raster, fetched from the node that
+	*    owns the handle and handed to the runner UNCUT, so the rectangle still
+	*    comes from the single derivation (D52). This rung exists because rung 1 is
+	*    structurally unreachable for most dispatches: the decode worker's native
+	*    lease is 1.2 s and a tick + inference routinely lands outside it, while
+	*    the retained store holds the frame for 3 s.
+	* 3. `cropJpeg` — the pre-cut tile. Last, because the caller decided its
+	*    rectangle and because in practice the same native miss that emptied rung 1
+	*    empties this one too.
+	*
+	* On D9/D18: the payload that crosses in rung 2 is a COMPRESSED JPEG fetched on
+	* demand, per TRACK per dispatch (≤2 in flight per device, ~1 Hz) and only after
+	* rung 1 missed — never a frame-rate stream, and never raw pixels.
 	*/
 	async runOnce(deviceId, dev, req, frame) {
 		const parent = {
@@ -11853,7 +11910,39 @@ var TrackDetailDispatcher = class {
 			}, frame.nodeId);
 			if (primary !== null) return primary.details;
 		} catch (err) {
-			this.deps.logger.debug("detail primary call failed — trying crop fallback", {
+			this.deps.logger.debug("detail primary call failed — trying frame fallback", {
+				tags: { deviceId },
+				meta: {
+					trackId: req.trackId,
+					stepId: req.stepId,
+					error: String(err)
+				}
+			});
+		}
+		if (this.deps.captureFullFrameBase64 !== void 0 && frame.frameHandle !== void 0) try {
+			const full = await this.deps.captureFullFrameBase64(frame);
+			if (full !== null) if (full.width !== frame.frameWidth || full.height !== frame.frameHeight) this.deps.logger.warn("detail full-frame fallback refused — frame is not the bbox scale", {
+				tags: { deviceId },
+				meta: {
+					trackId: req.trackId,
+					stepId: req.stepId,
+					frameWidth: full.width,
+					frameHeight: full.height,
+					bboxFrameWidth: frame.frameWidth,
+					bboxFrameHeight: frame.frameHeight
+				}
+			});
+			else {
+				const derived = await this.deps.runDetailSubtree({
+					deviceId,
+					frameJpeg: full.base64,
+					parent,
+					steps
+				}, frame.nodeId);
+				if (derived !== null) return derived.details;
+			}
+		} catch (err) {
+			this.deps.logger.debug("detail full-frame fallback call failed", {
 				tags: { deviceId },
 				meta: {
 					trackId: req.trackId,
@@ -11890,12 +11979,14 @@ var TrackDetailDispatcher = class {
 		const now = Date.now();
 		if (now - dev.lastFailWarnAt < FAIL_WARN_THROTTLE_MS) return;
 		dev.lastFailWarnAt = now;
-		this.deps.logger.warn("runDetailSubtree produced no result (frame + crop both missed)", {
+		this.deps.logger.warn("runDetailSubtree produced no result (every crop source missed)", {
 			tags: { deviceId },
 			meta: {
 				trackId: req.trackId,
 				stepId: req.stepId,
-				reason: req.reason
+				reason: req.reason,
+				triedFullFrame: this.deps.captureFullFrameBase64 !== void 0,
+				triedCropJpeg: this.deps.captureCropBase64 !== void 0
 			}
 		});
 	}
@@ -18619,6 +18710,20 @@ function rowToSensorEvent(id, data) {
 function isRecord(x) {
 	return x !== null && typeof x === "object" && !Array.isArray(x);
 }
+/**
+* May the interval this attempt consumed be given back?
+*
+* Pure, and deliberately takes the CURRENT clock as well as the mark: a rollback
+* is only correct while this attempt is still the one the gate is standing on. A
+* later frame's pending mark, or a snapshot that landed in between, has already
+* moved the reference forward and restoring an older one would re-open a window
+* that is legitimately closed.
+*/
+function canRollbackSnapshot(mark, currentLastSnapshotAt) {
+	if (mark === void 0) return false;
+	if (mark.at !== currentLastSnapshotAt) return false;
+	return mark.priorRollbacks < 3;
+}
 //#endregion
 //#region src/pipeline-analytics/store/recent-cursor.ts
 function encodeRecentCursor(cursor) {
@@ -18952,6 +19057,8 @@ var TrackStore = class {
 		t.snapshots.push(snapshot);
 		t.lastSnapshotAt = snapshot.timestamp;
 		t.lastSnapshotBbox = { ...snapshot.position.bbox };
+		delete t.snapshotPending;
+		t.snapshotRollbacks = 0;
 	}
 	/**
 	* Synchronously advance the periodic-snapshot gate reference (clock + bbox) at
@@ -18963,18 +19070,57 @@ var TrackStore = class {
 	* snapshots. Mirrors the synchronous `lastFrameAtByTrack` advance for the
 	* rolling `lastFrame`.
 	*
-	* No rollback: if the write later fails the slot is simply lost (a rare dropped
-	* snapshot is preferable to a burst). `addSnapshot` re-stamps the same
-	* clock/bbox when the real snapshot lands, so the two stay consistent. No-op for
-	* an unknown/expired track (the active entry is dropped on expiry, so there is
-	* no separate map to leak).
+	* The advance is REVERSIBLE. It used to be permanent — this docblock said
+	* "if the write later fails the slot is simply lost" — which made `snapshot`
+	* the only media kind with no retry of any shape while every sibling advanced
+	* its bookkeeping from the ids that actually persisted. See
+	* {@link rollbackSnapshotPending} and `pipeline/snapshot-retry.ts`.
+	*
+	* `addSnapshot` re-stamps the same clock/bbox when the real snapshot lands, so
+	* the two stay consistent. No-op for an unknown/expired track (the active entry
+	* is dropped on expiry, so there is no separate map to leak).
 	*/
 	markSnapshotPending(trackId, timestamp, bbox) {
 		const t = this.active.get(trackId);
 		if (!t) return;
+		t.snapshotPending = {
+			at: timestamp,
+			previous: {
+				at: t.lastSnapshotAt,
+				bbox: t.lastSnapshotBbox ? { ...t.lastSnapshotBbox } : void 0
+			},
+			priorRollbacks: t.snapshotRollbacks ?? 0
+		};
 		t.lastSnapshotAt = timestamp;
 		t.lastSnapshotBbox = { ...bbox };
 	}
+	/**
+	* The capture decided at `timestamp` did NOT land: restore the gate reference
+	* it displaced so the next frame re-evaluates instead of waiting out an
+	* interval that was never used. Returns whether the slot was given back.
+	*
+	* Refused — deliberately — when the attempt is no longer the one the gate
+	* stands on (a snapshot landed, or a newer frame already marked its own
+	* pending), and once the bounded run of non-landings is spent
+	* ({@link SNAPSHOT_MAX_ROLLBACKS}): a camera whose frames are permanently
+	* unresolvable must not re-decide a snapshot on every frame forever.
+	*/
+	rollbackSnapshotPending(trackId, timestamp) {
+		const t = this.active.get(trackId);
+		if (!t) return false;
+		const mark = t.snapshotPending;
+		if (mark?.at !== timestamp) return false;
+		if (!canRollbackSnapshot(mark, t.lastSnapshotAt)) {
+			delete t.snapshotPending;
+			return false;
+		}
+		t.lastSnapshotAt = mark.previous.at;
+		if (mark.previous.bbox) t.lastSnapshotBbox = { ...mark.previous.bbox };
+		else delete t.lastSnapshotBbox;
+		t.snapshotRollbacks = mark.priorRollbacks + 1;
+		delete t.snapshotPending;
+		return true;
+	}
 	lastSnapshotAt(trackId) {
 		return this.active.get(trackId)?.lastSnapshotAt ?? 0;
 	}
@@ -21095,6 +21241,35 @@ function createNativeFrameTransport(deps) {
 		};
 	};
 	const getNativeFullFrameRgb = async (handle, maxWidth) => (await fetchNativeFullFrameTiered(handle, maxWidth))?.frame ?? null;
+	const getFullFrameJpegBase64 = async (handle, maxWidth) => {
+		if (!pipelineRunnerApi?.getNativeCrop) return null;
+		try {
+			const full = await pipelineRunnerApi.getNativeCrop.query({
+				handle,
+				bbox: {
+					x: 0,
+					y: 0,
+					w: 1,
+					h: 1
+				},
+				maxWidth,
+				encodeJpeg: true
+			}, nodePin(handle.nodeId));
+			if (!full?.jpeg || full.width <= 0 || full.height <= 0) return null;
+			return {
+				base64: full.jpeg,
+				width: full.width,
+				height: full.height,
+				tier: full.tier === "ram-fullframe" ? "ram-fullframe" : "native"
+			};
+		} catch (err) {
+			logger.debug("full-frame jpeg fetch failed", { meta: {
+				nodeId: handle.nodeId,
+				error: errMsg(err)
+			} });
+			return null;
+		}
+	};
 	const cropMetricLogger = logger.child("NativeCrop");
 	let nativeHits = 0;
 	let nativeFallbacks = 0;
@@ -21145,6 +21320,7 @@ function createNativeFrameTransport(deps) {
 		getRemoteFrame,
 		getNativeFullFrameRgb,
 		getNativeKeyFrameRgb: fetchNativeFullFrameTiered,
+		getFullFrameJpegBase64,
 		getNativeCropJpeg,
 		captureCrop: createCaptureCrop({
 			tryNativeCrop,
@@ -21509,23 +21685,47 @@ function wireSubscriptions(deps) {
 * `composeEventKinds` builds the `listEventKinds` payload for a camera:
 *   (a) built-ins — motion + audio, always present;
 *   (b) detection classes actually OBSERVED on the device (track history);
-*   (c) sensor kinds contributed by LINKED devices (device-manager
-*       `getLinkedDevices`), one descriptor per bound sensor cap present in
-*       the static `EVENT_KIND_BY_CAP` map. Binding-driven per linked device
-*       (`getBindings`) — never a global cap enumeration (D12).
+*   (c) sensor kinds contributed by the camera's OWN bindings and by its
+*       LINKED devices (device-manager `getLinkedDevices`), one descriptor per
+*       bound sensor cap present in the static `EVENT_KIND_BY_CAP` map.
+*       Binding-driven per device (`getBindings`) — never a global cap
+*       enumeration (D12).
 *
 * `LinkedCamerasCache` is the ingest-side reverse index (sensor device →
-* linked camera ids) with a TTL, so the `DeviceStateChanged` handler stays
-* cheap at bus rate.
+* linked camera ids, plus the camera id set) with a TTL, so the
+* `DeviceStateChanged` handler stays cheap at bus rate.
 */
 /**
+* Mapped sensor/control caps that a CAMERA must NOT contribute for ITSELF.
+*
+* A sensor cap bound on a camera makes the camera both the source and the
+* subject — a doorbell wrapper on camera 615, a native Reolink doorbell, a
+* camera-side button. Those have no other route into the per-camera event
+* substrate, so the camera includes itself.
+*
+* `motion` is the exception, and today the ONLY one: camera motion already
+* has a dedicated camera-native path (`MotionAnalysis` /
+* `MotionOnMotionChanged` → `MotionEvent` rows under the built-in `motion`
+* taxonomy lane). Every real camera provider registers a native `motion` cap
+* on the camera device, so self-inclusion would mint a SECOND, differently
+* named copy (`motion-sensor`) of every motion transition, at motion rate.
+*
+* Add a cap here only when the camera already emits that event through
+* another ingest path — never to reduce noise.
+*/
+var SELF_CAMERA_EXCLUDED_CAPS = new Set(["motion"]);
+/** True when a camera may contribute `capName` for itself. */
+function selfCameraMayEmit(capName) {
+	return !SELF_CAMERA_EXCLUDED_CAPS.has(capName);
+}
+/**
 * Full event-kind taxonomy a camera CAN emit (config-derived):
 *   (a) motion built-in — always;
 *   (b) each enabled detection macro + its taxonomy subs (reverse COCO);
 *   (c) audio macro + its subs when the classifier is enabled;
 *   (d) package kinds when a package zone rule is enabled;
-*   (e) sensor/control kinds from LINKED devices (binding-driven), deduped
-*       per (kind, source deviceId).
+*   (e) sensor/control kinds from the CAMERA'S OWN bindings and from its
+*       LINKED devices (binding-driven), deduped per (kind, source deviceId).
 * Every descriptor carries parentKind/level/iconId/labelKey via the single
 * taxonomy dictionary — no color/icon is declared here.
 */
@@ -21560,6 +21760,7 @@ async function composeEventKinds(deps, deviceId) {
 	const audioP = attempt(deps, "audioEnabled", () => deps.audioEnabled(deviceId));
 	const packageP = attempt(deps, "packageZonesEnabled", async () => deps.packageZonesEnabled ? deps.packageZonesEnabled(deviceId) : false);
 	const linkedP = attempt(deps, "getLinkedDevices", () => deps.linkedDevices.getLinkedDevices({ deviceId }));
+	const selfBindingsP = attempt(deps, "getBindings", () => deps.bindings.getBindings({ deviceId }));
 	pushKind("motion");
 	for (const macro of await macrosP ?? []) {
 		pushKind(macro);
@@ -21576,26 +21777,30 @@ async function composeEventKinds(deps, deviceId) {
 	const devices = (await linkedP)?.devices ?? [];
 	const bindingsPerDevice = await Promise.all(devices.map((linked) => attempt(deps, "getBindings", () => deps.bindings.getBindings({ deviceId: linked.deviceId }))));
 	const seen = /* @__PURE__ */ new Set();
-	for (const [index, linked] of devices.entries()) {
-		const entries = bindingsPerDevice[index]?.entries;
-		if (entries === void 0) continue;
+	const pushSensorKinds = (sourceDeviceId, entries, isSelf) => {
+		if (entries === void 0) return;
 		for (const { capName } of entries) {
+			if (isSelf && !selfCameraMayEmit(capName)) continue;
 			const descriptor = EVENT_KIND_BY_CAP[capName];
 			if (descriptor === void 0) continue;
-			const dedupeKey = `${descriptor.kind}:${linked.deviceId}`;
+			const dedupeKey = `${descriptor.kind}:${sourceDeviceId}`;
 			if (seen.has(dedupeKey)) continue;
 			seen.add(dedupeKey);
 			pushKind(descriptor.kind, {
 				capName,
-				deviceId: linked.deviceId
+				deviceId: sourceDeviceId
 			});
 		}
-	}
+	};
+	pushSensorKinds(deviceId, (await selfBindingsP)?.entries, true);
+	for (const [index, linked] of devices.entries()) pushSensorKinds(linked.deviceId, bindingsPerDevice[index]?.entries, false);
 	return out;
 }
 var DEFAULT_CACHE_TTL_MS = 6e4;
 /**
-* TTL-cached reverse index: source deviceId → camera ids it is linked to.
+* TTL-cached reverse index: source deviceId → camera ids it is linked to,
+* plus the camera id SET the index was built from (so the ingest can ask
+* "is this device itself a camera" without a second enumeration).
 * Rebuilds lazily (single-flight) when stale, so the `DeviceStateChanged`
 * handler pays one map lookup per event in the common case.
 */
@@ -21603,6 +21808,8 @@ var LinkedCamerasCache = class {
 	deps;
 	ttlMs;
 	index = /* @__PURE__ */ new Map();
+	/** Every camera id seen by the last successful build. */
+	cameras = /* @__PURE__ */ new Set();
 	/** Ms timestamp of the last build; null = never built / invalidated. */
 	builtAt = null;
 	building = null;
@@ -21612,23 +21819,37 @@ var LinkedCamerasCache = class {
 	}
 	/** Camera ids linked to `sourceDeviceId` ([] when none). */
 	async camerasFor(sourceDeviceId, nowMs = Date.now()) {
-		if (this.builtAt === null || nowMs - this.builtAt >= this.ttlMs) {
-			this.building ??= this.rebuild(nowMs).finally(() => {
-				this.building = null;
-			});
-			await this.building;
-		}
+		await this.ensureFresh(nowMs);
 		return this.index.get(sourceDeviceId) ?? [];
 	}
+	/**
+	* True when `deviceId` is ITSELF a camera. Answered off the same build as
+	* {@link camerasFor} — a sensor cap bound on a camera needs both facts in
+	* the same event, and a second enumeration would double the cost of the
+	* ingest path for nothing.
+	*/
+	async isCamera(deviceId, nowMs = Date.now()) {
+		await this.ensureFresh(nowMs);
+		return this.cameras.has(deviceId);
+	}
 	/** Drop the cached index (e.g. on link-topology change events). */
 	invalidate() {
 		this.builtAt = null;
 	}
 	/** Test/maintenance hook: replace the index directly. */
-	seed(index, builtAt) {
+	seed(index, builtAt, cameraIds = []) {
 		this.index = new Map(index);
+		this.cameras = new Set(cameraIds);
 		this.builtAt = builtAt;
 	}
+	/** Rebuild (single-flight) when never built or past the TTL. */
+	async ensureFresh(nowMs) {
+		if (this.builtAt !== null && nowMs - this.builtAt < this.ttlMs) return;
+		this.building ??= this.rebuild(nowMs).finally(() => {
+			this.building = null;
+		});
+		await this.building;
+	}
 	async rebuild(nowMs) {
 		try {
 			const cameraIds = await this.deps.cameras.listCameraIds();
@@ -21645,6 +21866,7 @@ var LinkedCamerasCache = class {
 				this.deps.onError?.("getLinkedDevices", err);
 			}
 			this.index = next;
+			this.cameras = new Set(cameraIds);
 			this.builtAt = nowMs;
 		} catch (err) {
 			this.deps.onError?.("listCameraIds", err);
@@ -21653,16 +21875,25 @@ var LinkedCamerasCache = class {
 	}
 };
 /**
-* One `DeviceStateChanged` → N history rows (one per linked camera). The
-* EVENT_KIND_BY_CAP gate exits first so non-sensor cap churn costs one map
-* lookup. Returns the number of rows inserted (0 when unmapped/unlinked).
+* One `DeviceStateChanged` → N history rows, one per camera the event belongs
+* to: the emitting device's LINKED cameras, plus the emitting device ITSELF
+* when it is a camera carrying the sensor cap (a doorbell wrapper bound on
+* camera 615 — see `SELF_CAMERA_EXCLUDED_CAPS` for the one cap that is not
+* self-ingested). The EVENT_KIND_BY_CAP gate exits first so non-sensor cap
+* churn costs one map lookup. Returns the number of rows inserted (0 when
+* unmapped, or when the device belongs to no camera at all).
 * Telemetry-lossy by design (D8) — inserts are best-effort.
 */
 async function ingestSensorStateChange(deps, data, timestamp) {
 	const descriptor = EVENT_KIND_BY_CAP[data.capName];
 	if (descriptor === void 0) return 0;
-	const cameraIds = await deps.cache.camerasFor(data.deviceId);
-	if (cameraIds.length === 0) return 0;
+	const linkedCameraIds = await deps.cache.camerasFor(data.deviceId);
+	const isCamera = await deps.cache.isCamera(data.deviceId);
+	const cameraIds = isCamera && selfCameraMayEmit(data.capName) && !linkedCameraIds.includes(data.deviceId) ? [data.deviceId, ...linkedCameraIds] : linkedCameraIds;
+	if (cameraIds.length === 0) {
+		deps.onDropped?.(isCamera ? "camera-native-cap" : "no-camera", descriptor.kind);
+		return 0;
+	}
 	const slice = data.slice;
 	const value = slice !== null && slice !== void 0 && typeof slice === "object" && !Array.isArray(slice) ? slice : null;
 	const makeId = deps.makeId ?? (() => `pa-sensor-${randomUUID()}`);
@@ -21798,6 +22029,8 @@ var SNAPSHOT_MAX_WIDTH = 960;
 /** Bound the once-per-owner display-fallback memo so a long-lived process never
 *  leaks it. */
 var MAX_LOGGED_DISPLAY_FALLBACKS = 5e3;
+/** One `pinned-frame resolve missed` line per device per minute. */
+var PINNED_MISS_WARN_THROTTLE_MS = 6e4;
 /**
 * Map a detection-frame pixel box (`fromW`×`fromH`, the ≤640 raster the tracker
 * ran on) onto the native full frame (`toW`×`toH`, the 960-downscaled native
@@ -21883,6 +22116,8 @@ var EventMediaDispatcher = class {
 	/** Once-per-owner (`${eventId}:${kind}`) memo for the DISPLAY-crop fallback
 	*  info log — see {@link logDisplayFallbackOnce}. */
 	loggedDisplayFallbacks = /* @__PURE__ */ new Set();
+	/** Per-device throttle for {@link warnPinnedFrameMiss}. */
+	lastPinnedMissWarnAt = /* @__PURE__ */ new Map();
 	constructor(deps) {
 		this.deps = deps;
 		this.sharedNativeFullFrame = createSharedFrameResolver((handle) => this.deps.getNativeFullFrameRgb(handle, SNAPSHOT_MAX_WIDTH));
@@ -21896,30 +22131,48 @@ var EventMediaDispatcher = class {
 	* by which time the handle's ring slot is usually recycled and the by-handle
 	* resolve in {@link captureForFrame} finds nothing (the 2026-07-23 boxed-tile
 	* regression). ~0.7MB per pinned frame, freed with the batch — bounded by the
-	* lane. Returns `null` on a genuine live-window miss (logged at debug — the
-	* caller then omits `pinnedFrame` and captureForFrame's by-handle resolve,
-	* WARN-logged on failure, remains the fallback).
+	* lane. Returns `null` on a genuine live-window miss.
+	*
+	* Both miss paths are WARN, throttled to one line per device per minute. They
+	* are the FIRST half of a pair whose second half (`capture batch lost`) has
+	* always been a warn: a batch that lost its frame is reported with
+	* `pinned: false`, and until 2026-08-07 the reason the pin itself failed was
+	* either at debug (the throw) or nowhere at all (the null return). 383 batch
+	* losses in 3 h had `pinned: false` on 100% of them and nothing said why.
 	*/
 	async resolvePinnedFrame(deviceId, frameHandle) {
 		try {
 			const decoded = await resolveFrame(frameHandle, { getRemoteFrame: this.deps.getRemoteFrame });
-			if (!decoded) return null;
+			if (!decoded) {
+				this.warnPinnedFrameMiss(deviceId, frameHandle, "recycled-before-pin");
+				return null;
+			}
 			return {
 				...decoded,
 				data: Buffer.from(decoded.data)
 			};
 		} catch (err) {
-			this.deps.logger.debug("event media: pinned-frame resolve threw (live window)", {
-				tags: { deviceId },
-				meta: {
-					deviceId,
-					shmId: frameHandle.shmId,
-					error: String(err)
-				}
-			});
+			this.warnPinnedFrameMiss(deviceId, frameHandle, "threw", String(err));
 			return null;
 		}
 	}
+	/** One `pinned-frame resolve missed` line per device per minute. Throttled
+	*  because it fires per capture batch, and the batch's own loss line is not. */
+	warnPinnedFrameMiss(deviceId, frameHandle, reason, error) {
+		const now = Date.now();
+		if (now - (this.lastPinnedMissWarnAt.get(deviceId) ?? 0) < PINNED_MISS_WARN_THROTTLE_MS) return;
+		this.lastPinnedMissWarnAt.set(deviceId, now);
+		this.deps.logger.warn("event media: pinned-frame resolve missed (live window)", {
+			tags: { deviceId },
+			meta: {
+				reason,
+				shmId: frameHandle.shmId,
+				handle: `${frameHandle.shmId}#${frameHandle.slot}#${frameHandle.seq}`,
+				handleNodeId: frameHandle.nodeId,
+				...error !== void 0 ? { error } : {}
+			}
+		});
+	}
 	/**
 	* WARN-log a whole-batch capture abort: every early return in
 	* {@link captureForFrame} loses ALL of the frame's targets at once —
@@ -22772,13 +23025,19 @@ var SyntheticTrackMaterializer = class {
 	* Fetch the linked camera's snapshot under a bounded timeout. A hanging
 	* snapshot cap is skipped (returns null + warns) so the track still lands;
 	* a null / failed fetch is likewise reported and skipped.
+	*
+	* Deliberately NOT `force`. `snapshot.cap.ts` defines `force` as the
+	* operator's refresh button — *"On battery cams this WILL wake the camera —
+	* accept the cost only when the user explicitly asks for it"* — and a
+	* synthetic track is materialised from an EVENT, with nobody asking. Forcing
+	* here walked straight past the snapshot addon's sleep gate and woke a
+	* sleeping battery camera per event (roadmap 4f). Without it the cache
+	* answers: ≤10 s old on a mains camera, and on a battery camera the
+	* intentionally stale-but-honest frame that costs no wake.
 	*/
 	async fetchSnapshot(cameraId) {
 		try {
-			const snap = await withTimeout(this.deps.snapshot.getSnapshot({
-				deviceId: cameraId,
-				force: true
-			}), this.snapshotTimeoutMs);
+			const snap = await withTimeout(this.deps.snapshot.getSnapshot({ deviceId: cameraId }), this.snapshotTimeoutMs);
 			if (snap === null) this.deps.onError?.("getSnapshot", /* @__PURE__ */ new Error("snapshot returned null"));
 			return snap;
 		} catch (err) {
@@ -25760,7 +26019,7 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 			logger: logger.child("EventMediaDispatcher")
 		});
 		this.buildRecognizers(api, logger, stores, transport);
-		this.buildDetailDispatcher(api, logger);
+		this.buildDetailDispatcher(api, logger, transport);
 		const capProviders = this.buildAnalyticsProviders(api, logger);
 		await this.buildNotificationCenter(api, logger, stores);
 		await this.serveEventMediaDataPlane();
@@ -26208,7 +26467,7 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 	*  demand via `pipelineRunner.runDetailSubtree`. The dispatcher owns the
 	*  per-device schedulers, concurrency cap, and 1 s tick; result routing +
 	*  the pinned call + crop fallback are injected here. */
-	buildDetailDispatcher(api, logger) {
+	buildDetailDispatcher(api, logger, transport) {
 		const runnerApi = api.pipelineRunner;
 		this.detailDispatcher = new TrackDetailDispatcher({
 			logger: logger.child("DetailDispatcher"),
@@ -26218,6 +26477,15 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 				return runnerApi.runDetailSubtree.mutate(input);
 			},
 			routeResults: (deviceId, trackId, details, frame) => this.routeDetailResults(deviceId, trackId, details, frame),
+			captureFullFrameBase64: async (frame) => {
+				if (frame.frameHandle === void 0) return null;
+				const full = await transport.getFullFrameJpegBase64(frame.frameHandle, frame.frameWidth);
+				return full === null ? null : {
+					base64: full.base64,
+					width: full.width,
+					height: full.height
+				};
+			},
 			captureCropBase64: async (frame) => {
 				if (frame.frameHandle === void 0 || !this.captureCrop) return null;
 				const buf = await this.captureCrop(frame.frameHandle, { ...frame.bbox }, frame.frameWidth, frame.frameHeight, DETAIL_FALLBACK_CROP_PADDING);
@@ -26842,12 +27110,15 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 				inPrevActive: false,
 				positionsCount: positionsCountById.get(id) ?? 1
 			}) === "resurrection") {
-				log.info("track resumed", { meta: {
-					trackId: id,
-					className: t.className,
-					source,
-					resurrected: true
-				} });
+				log.info("track resumed", {
+					tags: { deviceId },
+					meta: {
+						trackId: id,
+						className: t.className,
+						source,
+						resurrected: true
+					}
+				});
 				if (this.eventMediaDispatcher) {
 					this.residents.setLastFrameAt(deviceId, id, result.timestamp);
 					if (!this.residents.isFirstFrameLanded(id) && !this.residents.isFirstFramePending(id)) this.residents.markFirstFramePending(deviceId, id);
@@ -26982,10 +27253,13 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 		let lostTrackCount = 0;
 		for (const id of prevIds) if (!currentTrackIds.has(id)) {
 			lostTrackCount += 1;
-			log.info("track lost", { meta: {
-				trackId: id,
-				source
-			} });
+			log.info("track lost", {
+				tags: { deviceId },
+				meta: {
+					trackId: id,
+					source
+				}
+			});
 		}
 		this.suppressedBirths.retain(key, currentTrackIds);
 		this.deferredBirths.retain(key, currentTrackIds);
@@ -27222,6 +27496,19 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 							this.residents.markFirstFrameLanded(deviceId, trackId);
 						}
 						for (const trackId of res.lastFrameTrackIds) this.residents.setLastFrameAt(deviceId, trackId, dispatchTimestamp);
+						const landedSnapshots = new Set(res.storedSnapshots.map((s) => s.trackId));
+						for (const target of snapshotTargets) {
+							if (!target.appendSnapshot || landedSnapshots.has(target.trackId)) continue;
+							const gaveBack = this.trackStore?.rollbackSnapshotPending(target.trackId, target.timestamp);
+							log.warn("snapshot capture did not land", {
+								tags: { deviceId },
+								meta: {
+									trackId: target.trackId,
+									timestamp: target.timestamp,
+									intervalReturned: gaveBack === true
+								}
+							});
+						}
 					})
 				}).catch(() => {});
 			}
@@ -29020,8 +29307,16 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 	}
 	/**
 	* Sensor-event ingest handler — `DeviceStateChanged` of a device exposing a
-	* mapped sensor cap. Resolves the linked-camera set through the TTL cache
-	* and inserts ONE row per linked camera. Best-effort (telemetry-lossy).
+	* mapped sensor cap. Resolves the camera set through the TTL cache (the
+	* device's LINKED cameras, plus the device itself when it is a camera
+	* carrying the cap) and inserts ONE row per camera. Best-effort
+	* (telemetry-lossy).
+	*
+	* D8/D11 boundary, stated plainly: the ride here is the LOSSY
+	* `DeviceStateChanged` bus, and there is no reconcile that replays a missed
+	* press from the durable `doorbell.getStatus.lastPressedAt`. A dropped bus
+	* event is a missing history row and a missing notification — never wrong
+	* durable state.
 	*/
 	async handleSensorStateChanged(data, timestamp) {
 		const store = this.sensorEventStore;
@@ -29031,7 +29326,8 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 			await ingestSensorStateChange({
 				sink: store,
 				cache,
-				onPersisted: (ev) => this.notificationCenter?.onSensorEventPersisted(ev)
+				onPersisted: (ev) => this.notificationCenter?.onSensorEventPersisted(ev),
+				onDropped: (reason, kind) => this.logSensorIngestDrop(data, reason, kind)
 			}, data, timestamp);
 		} catch (err) {
 			this.ctx.logger.warn("sensor-event ingest failed", {
@@ -29047,7 +29343,16 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 		if (materializer === null || descriptor === void 0) return;
 		try {
 			const cameraIds = await cache.camerasFor(data.deviceId);
-			if (cameraIds.length === 0) return;
+			if (cameraIds.length === 0) {
+				this.ctx.logger.debug("sensor synthetic-track projection skipped — no linked camera", {
+					tags: { deviceId: data.deviceId },
+					meta: {
+						capName: data.capName,
+						kind: descriptor.kind
+					}
+				});
+				return;
+			}
 			const producingDeviceName = await this.resolveProducingDeviceName(data.deviceId);
 			for (const cameraId of cameraIds) await materializer.materialize({
 				cameraId,
@@ -29068,6 +29373,35 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 		}
 	}
 	/**
+	* Say out loud that a MAPPED sensor cap ingested nothing, and why.
+	*
+	* BOTH branches are `debug`, deliberately. After the self-camera fix neither
+	* is a surprise any more — they are the two designed steady states, and both
+	* ride at bus rate:
+	*
+	*  - `camera-native-cap` is EVERY camera's `motion` slice. Every provider
+	*    binds a native `motion` cap on the camera device and motion churns
+	*    continuously (camera 590 flaps at ~2 Hz), so an `info` here would be a
+	*    log flood measured in millions of lines a day — its own outage.
+	*  - `no-camera` is every sensor in the fleet that no camera links.
+	*
+	* What must never happen again is the branch being INVISIBLE: a doorbell
+	* press that ingested nothing produced not one line for months. A debug line
+	* carrying `deviceId`, `capName`, `kind` and `reason` answers "why is 615
+	* dark" the moment anyone asks it.
+	*/
+	logSensorIngestDrop(data, reason, kind) {
+		const message = reason === "camera-native-cap" ? "sensor-event ingest produced NO row — the camera already emits this cap through its own path" : "sensor-event ingest produced NO row — the device is not a camera and is linked to none";
+		this.ctx.logger.debug(message, {
+			tags: { deviceId: data.deviceId },
+			meta: {
+				capName: data.capName,
+				kind,
+				reason
+			}
+		});
+	}
+	/**
 	* Resolve the NAME of a device (the linked sensor/control that produced a
 	* synthetic event) via the device-manager cap. Best-effort — returns
 	* undefined on any lookup failure or an unknown device so the synthetic