@camstack/addon-provider-reolink 1.2.131 → 1.2.132

package/dist/addon.js

@@ -20082,13 +20082,26 @@ var TrackAudioLabelSchema = object({
 *  - `audio` — an audio event on the camera itself that was anomalous for
 *    THAT camera, loud, and heard while nothing visual was happening (D62).
 *
+*  - `onboard` — the CAMERA's own firmware, paired with a decoded frame in
+*    that frame's pixel space. A real root detector and a SPATIAL one: its
+*    boxes are the same kind of fact `pipeline`'s are, produced by a different
+*    detector.
+*
+* `onboard` was missing here while `DetectionSourceSchema` already had it, so
+* a persisted onboard track failed `safeParse` on read and came back with NO
+* source at all — which `isSpatialTrack` then admitted by accident, through the
+* `undefined` arm rather than by anybody's decision, and which `excludeSources`
+* could not name.
+*
 * The spatial subsystems (tracker association, occupancy count, re-id /
 * embedding, resurrection) MUST skip every synthetic source. Test for that
-* with `isSpatialTrack`, which allow-lists `pipeline` — a `!== 'sensor'`
-* check silently readmits every source added after it was written.
+* with `isSpatialTrack`, which allow-lists the spatial sources explicitly — a
+* `!== 'sensor'` check silently readmits every source added after it was
+* written.
 */
 var TrackSourceSchema = _enum([
 	"pipeline",
+	"onboard",
 	"sensor",
 	"audio"
 ]);
@@ -22170,13 +22183,39 @@ var MotionSourceEnum = _enum([
 */
 var MotionSourcesSchema = array(MotionSourceEnum);
 /**
-* Which root detectors a camera runs. Deliberately the SAME vocabulary
-* post-analysis already tags every detection with (`DetectionSource`) rather
-* than a second spelling of the same two ideas — the value an operator picks
-* here is the value that comes back on the track, the overlay and the debug
-* row.
+* Which root detector a camera runs — EXACTLY ONE.
+*
+* Deliberately the SAME vocabulary post-analysis already tags every detection
+* with (`DetectionSource`) rather than a second spelling of the same two
+* ideas: the value an operator picks here is the value that comes back on the
+* track, the overlay and the debug row.
+*
+* ## Why one, and why it is still an array
+*
+* Two roots on one camera is a capability nobody asked for and the operator has
+* since ruled out. It was never free: both planes feed the SAME per-device
+* stationary registry, both can promote the same parked object, and the two
+* detectors disagree about the same box by construction — which is the
+* disagreement D505 had to arbitrate. Removing the case removes the arbitration.
+*
+* The ARRAY shape survives because the stored settings and the attach payload
+* already speak it on every camera of every fleet, and a cap input that
+* suddenly refuses a stored value makes the camera un-attachable — a fail-closed
+* in the one direction that costs an operator their cameras. So the wire stays
+* tolerant and the TYPE is exact: a longer list is truncated to its first
+* element rather than refused, and `max(1)` is what every consumer can then
+* rely on.
+*
+* AT MOST one, not exactly one. The EMPTY list is a legal, deliberate pick —
+* a camera an operator left with no root detector — and `planDetectionSources`
+* has always said so: inventing a root for them is how a default acts without
+* anybody choosing it. Tightening this to `length(1)` broke that, and the
+* suite caught it.
+*
+* Measured before tightening (2026-09-15, this fleet, 6 h of attaches): 3327
+* `["pipeline"]` and 2 `["onboard"]`. Not one camera had two.
 */
-var DetectionSourcesSchema = array(DetectionSourceSchema);
+var DetectionSourcesSchema = preprocess((value) => Array.isArray(value) && value.length > 1 ? value.slice(0, 1) : value, array(DetectionSourceSchema).max(1));
 /**
 * Input shape for `pipeline-runner.reportMotion` cap method. Exported
 * so cap-side consumers (the orchestrator forward, the runner addon's
@@ -145521,6 +145560,29 @@ function buildOsdSection(snapshot, values, opts) {
 	};
 }
 //#endregion
+//#region src/snapshot-wake-gate.ts
+/**
+* Decide whether a snapshot read may reach the camera's socket.
+*
+* Pure, and deliberately total: three inputs, no clock, no cooldown, no
+* fallible read (D49 — a gate that can be talked out of its answer by a
+* stale timestamp is not a gate).
+*/
+function decideSnapshotCameraAccess(input) {
+	if (!input.isBattery || !input.sleeping) return {
+		kind: "proceed",
+		stampCooldown: false
+	};
+	if (!input.force) return {
+		kind: "refuse",
+		reason: "sleeping"
+	};
+	return {
+		kind: "proceed",
+		stampCooldown: true
+	};
+}
+//#endregion
 //#region src/raw-state.ts
 /**
 * Source tag for every raw-state blob this provider emits.
@@ -150315,9 +150377,9 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 	}
 	registerNativeCapabilities() {
 		this.ctx.registerNativeCap(snapshotCapability, {
-			getSnapshot: async ({ deviceId }) => {
+			getSnapshot: async ({ deviceId, force }) => {
 				if (deviceId !== this.id) throw new Error(`ReolinkCamera: deviceId mismatch, expected ${this.id}, got ${deviceId}`);
-				return this.fetchSnapshotWithSingleFlight();
+				return this.fetchSnapshotWithSingleFlight(force === true);
 			},
 			invalidateCache: async () => {}
 		});
@@ -150760,33 +150822,6 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 			status: this.state.battery
 		}));
 	}
-	/**
-	* Gate for a PROACTIVE camera read, checked BEFORE `ensureApi()`.
-	*
-	* The login itself is the wake. On a sleeping UDP/battery camera the
-	* lib's discovery + handshake nudges the firmware awake (same reason
-	* `refreshParentSettingsSnapshot` refuses to call `ensureApi` while
-	* asleep), so gating only the explicit `wakeUp()` call is useless —
-	* by the time we reach it the camera is already up. Production logs
-	* showed exactly that: a background read produced a full
-	* `Connecting to Reolink` → BCUDP discovery → `battery sleep state
-	* committed` (awake) → whole refresh cascade, on a camera that had
-	* been asleep for six minutes.
-	*
-	* Returns `false` when the caller must serve cache / bail out without
-	* touching the socket. Stamps the cooldown when it does let a wake
-	* through, so "at most one proactive wake per
-	* `PROACTIVE_WAKE_COOLDOWN_MS`" holds across ALL proactive callers
-	* rather than per-caller.
-	*
-	* Demand-driven paths never call this — see `canProactivelyWake`.
-	*/
-	allowProactiveCameraAccess(reason) {
-		if (!this.isBattery || !this.sleeping) return true;
-		if (!this.canProactivelyWake(reason)) return false;
-		this.markWakeIssued();
-		return true;
-	}
 	updateBatteryCache(info) {
 		const mapped = this.mapBatteryInfo(info);
 		const now = Date.now();
@@ -151066,12 +151101,27 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 		}
 		await this.refreshCameraEmailConfig().catch(() => {});
 	}
-	async fetchSnapshotWithSingleFlight() {
+	/**
+	* @param force - the caller's `snapshot.getSnapshot({ force })`. THE gate:
+	*   without it a sleeping battery camera is never touched, whatever the
+	*   cache holds. See `snapshot-wake-gate.ts` for why the flag — and not a
+	*   cooldown — is what decides.
+	*/
+	async fetchSnapshotWithSingleFlight(force) {
 		if (this.snapshotInFlight) return this.snapshotInFlight;
-		if (!this.allowProactiveCameraAccess("snapshot")) {
-			this.ctx.logger.debug("snapshot: skipped — sleeping battery cam inside wake cooldown", { tags: { deviceId: this.id } });
+		const access = decideSnapshotCameraAccess({
+			isBattery: this.isBattery,
+			sleeping: this.sleeping,
+			force
+		});
+		if (access.kind === "refuse") {
+			this.ctx.logger.info("snapshot: refused — battery cam asleep and no operator force", {
+				tags: { deviceId: this.id },
+				meta: { reason: access.reason }
+			});
 			return null;
 		}
+		if (access.stampCooldown) this.markWakeIssued();
 		const promise = (async () => {
 			let api;
 			try {

package/dist/addon.mjs

@@ -20077,13 +20077,26 @@ var TrackAudioLabelSchema = object({
 *  - `audio` — an audio event on the camera itself that was anomalous for
 *    THAT camera, loud, and heard while nothing visual was happening (D62).
 *
+*  - `onboard` — the CAMERA's own firmware, paired with a decoded frame in
+*    that frame's pixel space. A real root detector and a SPATIAL one: its
+*    boxes are the same kind of fact `pipeline`'s are, produced by a different
+*    detector.
+*
+* `onboard` was missing here while `DetectionSourceSchema` already had it, so
+* a persisted onboard track failed `safeParse` on read and came back with NO
+* source at all — which `isSpatialTrack` then admitted by accident, through the
+* `undefined` arm rather than by anybody's decision, and which `excludeSources`
+* could not name.
+*
 * The spatial subsystems (tracker association, occupancy count, re-id /
 * embedding, resurrection) MUST skip every synthetic source. Test for that
-* with `isSpatialTrack`, which allow-lists `pipeline` — a `!== 'sensor'`
-* check silently readmits every source added after it was written.
+* with `isSpatialTrack`, which allow-lists the spatial sources explicitly — a
+* `!== 'sensor'` check silently readmits every source added after it was
+* written.
 */
 var TrackSourceSchema = _enum([
 	"pipeline",
+	"onboard",
 	"sensor",
 	"audio"
 ]);
@@ -22165,13 +22178,39 @@ var MotionSourceEnum = _enum([
 */
 var MotionSourcesSchema = array(MotionSourceEnum);
 /**
-* Which root detectors a camera runs. Deliberately the SAME vocabulary
-* post-analysis already tags every detection with (`DetectionSource`) rather
-* than a second spelling of the same two ideas — the value an operator picks
-* here is the value that comes back on the track, the overlay and the debug
-* row.
+* Which root detector a camera runs — EXACTLY ONE.
+*
+* Deliberately the SAME vocabulary post-analysis already tags every detection
+* with (`DetectionSource`) rather than a second spelling of the same two
+* ideas: the value an operator picks here is the value that comes back on the
+* track, the overlay and the debug row.
+*
+* ## Why one, and why it is still an array
+*
+* Two roots on one camera is a capability nobody asked for and the operator has
+* since ruled out. It was never free: both planes feed the SAME per-device
+* stationary registry, both can promote the same parked object, and the two
+* detectors disagree about the same box by construction — which is the
+* disagreement D505 had to arbitrate. Removing the case removes the arbitration.
+*
+* The ARRAY shape survives because the stored settings and the attach payload
+* already speak it on every camera of every fleet, and a cap input that
+* suddenly refuses a stored value makes the camera un-attachable — a fail-closed
+* in the one direction that costs an operator their cameras. So the wire stays
+* tolerant and the TYPE is exact: a longer list is truncated to its first
+* element rather than refused, and `max(1)` is what every consumer can then
+* rely on.
+*
+* AT MOST one, not exactly one. The EMPTY list is a legal, deliberate pick —
+* a camera an operator left with no root detector — and `planDetectionSources`
+* has always said so: inventing a root for them is how a default acts without
+* anybody choosing it. Tightening this to `length(1)` broke that, and the
+* suite caught it.
+*
+* Measured before tightening (2026-09-15, this fleet, 6 h of attaches): 3327
+* `["pipeline"]` and 2 `["onboard"]`. Not one camera had two.
 */
-var DetectionSourcesSchema = array(DetectionSourceSchema);
+var DetectionSourcesSchema = preprocess((value) => Array.isArray(value) && value.length > 1 ? value.slice(0, 1) : value, array(DetectionSourceSchema).max(1));
 /**
 * Input shape for `pipeline-runner.reportMotion` cap method. Exported
 * so cap-side consumers (the orchestrator forward, the runner addon's
@@ -145516,6 +145555,29 @@ function buildOsdSection(snapshot, values, opts) {
 	};
 }
 //#endregion
+//#region src/snapshot-wake-gate.ts
+/**
+* Decide whether a snapshot read may reach the camera's socket.
+*
+* Pure, and deliberately total: three inputs, no clock, no cooldown, no
+* fallible read (D49 — a gate that can be talked out of its answer by a
+* stale timestamp is not a gate).
+*/
+function decideSnapshotCameraAccess(input) {
+	if (!input.isBattery || !input.sleeping) return {
+		kind: "proceed",
+		stampCooldown: false
+	};
+	if (!input.force) return {
+		kind: "refuse",
+		reason: "sleeping"
+	};
+	return {
+		kind: "proceed",
+		stampCooldown: true
+	};
+}
+//#endregion
 //#region src/raw-state.ts
 /**
 * Source tag for every raw-state blob this provider emits.
@@ -150310,9 +150372,9 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 	}
 	registerNativeCapabilities() {
 		this.ctx.registerNativeCap(snapshotCapability, {
-			getSnapshot: async ({ deviceId }) => {
+			getSnapshot: async ({ deviceId, force }) => {
 				if (deviceId !== this.id) throw new Error(`ReolinkCamera: deviceId mismatch, expected ${this.id}, got ${deviceId}`);
-				return this.fetchSnapshotWithSingleFlight();
+				return this.fetchSnapshotWithSingleFlight(force === true);
 			},
 			invalidateCache: async () => {}
 		});
@@ -150755,33 +150817,6 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 			status: this.state.battery
 		}));
 	}
-	/**
-	* Gate for a PROACTIVE camera read, checked BEFORE `ensureApi()`.
-	*
-	* The login itself is the wake. On a sleeping UDP/battery camera the
-	* lib's discovery + handshake nudges the firmware awake (same reason
-	* `refreshParentSettingsSnapshot` refuses to call `ensureApi` while
-	* asleep), so gating only the explicit `wakeUp()` call is useless —
-	* by the time we reach it the camera is already up. Production logs
-	* showed exactly that: a background read produced a full
-	* `Connecting to Reolink` → BCUDP discovery → `battery sleep state
-	* committed` (awake) → whole refresh cascade, on a camera that had
-	* been asleep for six minutes.
-	*
-	* Returns `false` when the caller must serve cache / bail out without
-	* touching the socket. Stamps the cooldown when it does let a wake
-	* through, so "at most one proactive wake per
-	* `PROACTIVE_WAKE_COOLDOWN_MS`" holds across ALL proactive callers
-	* rather than per-caller.
-	*
-	* Demand-driven paths never call this — see `canProactivelyWake`.
-	*/
-	allowProactiveCameraAccess(reason) {
-		if (!this.isBattery || !this.sleeping) return true;
-		if (!this.canProactivelyWake(reason)) return false;
-		this.markWakeIssued();
-		return true;
-	}
 	updateBatteryCache(info) {
 		const mapped = this.mapBatteryInfo(info);
 		const now = Date.now();
@@ -151061,12 +151096,27 @@ var ReolinkCamera = class ReolinkCamera extends BaseDevice {
 		}
 		await this.refreshCameraEmailConfig().catch(() => {});
 	}
-	async fetchSnapshotWithSingleFlight() {
+	/**
+	* @param force - the caller's `snapshot.getSnapshot({ force })`. THE gate:
+	*   without it a sleeping battery camera is never touched, whatever the
+	*   cache holds. See `snapshot-wake-gate.ts` for why the flag — and not a
+	*   cooldown — is what decides.
+	*/
+	async fetchSnapshotWithSingleFlight(force) {
 		if (this.snapshotInFlight) return this.snapshotInFlight;
-		if (!this.allowProactiveCameraAccess("snapshot")) {
-			this.ctx.logger.debug("snapshot: skipped — sleeping battery cam inside wake cooldown", { tags: { deviceId: this.id } });
+		const access = decideSnapshotCameraAccess({
+			isBattery: this.isBattery,
+			sleeping: this.sleeping,
+			force
+		});
+		if (access.kind === "refuse") {
+			this.ctx.logger.info("snapshot: refused — battery cam asleep and no operator force", {
+				tags: { deviceId: this.id },
+				meta: { reason: access.reason }
+			});
 			return null;
 		}
+		if (access.stampCooldown) this.markWakeIssued();
 		const promise = (async () => {
 			let api;
 			try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/addon-provider-reolink",
-  "version": "1.2.131",
+  "version": "1.2.132",
   "description": "Reolink camera device provider addon for CamStack — native Baichuan protocol",
   "keywords": [
     "camstack",