@camstack/system 1.2.55 → 1.2.57

package/dist/builtins/doorbell/virtual-doorbell.addon.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-CblJsHb-.js");
+const require_dist = require("../../dist-BupxnZOi.js");
 //#region src/builtins/doorbell/trigger-engine.ts
 /**
 * Pure trigger logic for the virtual-doorbell builtin — edge detection over
@@ -37,6 +37,30 @@ var SOURCE_CAP_ACTIVE_FIELD = {
 	vibration: "detected",
 	tamper: "tampered"
 };
+/**
+* The same caps → the slice field carrying the ms-epoch timestamp of the
+* last transition. Every source cap MUST appear here (guarded by a spec):
+* without a transition timestamp the engine cannot tell a genuine press
+* from a boot-time hydration when the FIRST slice it ever sees is already
+* active, and errs towards silence — swallowing the press.
+*
+* These timestamps are UPSTREAM ones, not ingest ones: the Home Assistant
+* provider derives them from `state.last_changed`, so they survive our own
+* restarts and correctly read as "hours ago" for a state that has been
+* active for hours. `motion` names its rise timestamp `lastDetectedAt`.
+*/
+var SOURCE_CAP_CHANGED_AT_FIELD = {
+	contact: "lastChangedAt",
+	binary: "lastChangedAt",
+	switch: "lastChangedAt",
+	motion: "lastDetectedAt",
+	flood: "lastChangedAt",
+	gas: "lastChangedAt",
+	smoke: "lastChangedAt",
+	"carbon-monoxide": "lastChangedAt",
+	vibration: "lastChangedAt",
+	tamper: "lastChangedAt"
+};
 /** Cap names whose presence in a device's bindings qualify it as a source. */
 var SOURCE_CAPS = Object.keys(SOURCE_CAP_ACTIVE_FIELD);
 /**
@@ -73,14 +97,46 @@ function sliceActiveValue(capName, slice) {
 	const raw = slice[field];
 	return typeof raw === "boolean" ? raw : null;
 }
+/** Ms-epoch transition timestamp a source cap's slice carries, or null when
+*  it is absent, non-numeric or the zero "never observed" sentinel. */
+function sliceChangedAt(capName, slice) {
+	const field = SOURCE_CAP_CHANGED_AT_FIELD[capName];
+	if (field === void 0) return null;
+	const raw = slice[field];
+	if (typeof raw !== "number" || !Number.isFinite(raw) || raw <= 0) return null;
+	return raw;
+}
+function ignoredResult(reason) {
+	return {
+		fired: [],
+		debounced: [],
+		ignored: reason
+	};
+}
 /**
 * Stateful (but side-effect-free towards the outside) trigger engine.
 *
 * Tracks the last observed binary value per (sourceDevice, cap) so a
 * `DeviceStateChanged` re-emission (the slice's `lastChangedAt` moves while
-* the binary value does not) never double-fires, and the FIRST observation
-* after boot only seeds the baseline — a state hydration at startup must not
-* ring anybody's doorbell.
+* the binary value does not) never double-fires.
+*
+* FIRST SIGHTINGS. Seeding the baseline and never firing was wrong for the
+* one case that matters: a momentary source (a button wired to a Home
+* Assistant switch) is NOT re-pushed in its resting `off` state after a hub
+* restart, so after every restart — several a day — the first slice the
+* engine ever sees for it is the PRESS ITSELF, already active. That press
+* was eaten whole; a real one on 2026-08-05 left no trace anywhere.
+*
+* The discriminator is the source's own transition timestamp. A first
+* sighting that is already active rings only when its transition can be
+* proved to have happened AFTER this engine started watching AND within
+* `firstSightingFreshnessMs`. Both halves earn their keep: freshness alone
+* would ring on a boot hydration of a state that flipped seconds before the
+* restart, and "after we started" alone would ring, on a long-lived
+* process, for a source adopted today whose state flipped yesterday. An
+* undateable first sighting (no timestamp, or a zero sentinel) does NOT
+* ring — the ambiguous case errs towards silence, but reports
+* `baseline-seeded-stale-active` so the caller can say so out loud.
 */
 var DoorbellTriggerEngine = class {
 	assignments = [];
@@ -90,9 +146,14 @@ var DoorbellTriggerEngine = class {
 	lastFiredAt = /* @__PURE__ */ new Map();
 	debounceMs;
 	now;
+	firstSightingFreshnessMs;
+	/** When this engine started watching — the floor for a first-sighting rise. */
+	startedAt;
 	constructor(options) {
 		this.debounceMs = options?.debounceMs ?? 2e3;
 		this.now = options?.now ?? Date.now;
+		this.firstSightingFreshnessMs = options?.firstSightingFreshnessMs ?? 3e4;
+		this.startedAt = this.now();
 	}
 	/** Replace the full assignment set (rebuilt whenever settings change). */
 	setAssignments(assignments) {
@@ -106,35 +167,77 @@ var DoorbellTriggerEngine = class {
 		return this.assignments.some((a) => a.sourceDeviceId === deviceId);
 	}
 	/**
-	* Feed one `DeviceStateChanged` slice. Returns the camera ids whose
-	* doorbell should ring (already debounced). Only a false→true rise on a
-	* recognised source cap fires; baseline-only sightings, re-emissions, and
-	* the falling edge return an empty array.
+	* Feed one `DeviceStateChanged` slice. Reports which cameras should ring,
+	* which were suppressed by the debounce window, and — when nothing was
+	* matched at all — WHY. Only a rise to active on a recognised source cap
+	* can ring; re-emissions and the falling edge never do.
 	*/
 	onStateSlice(deviceId, capName, slice) {
 		const value = sliceActiveValue(capName, slice);
-		if (value === null) return [];
+		if (value === null) return ignoredResult(isSourceCap(capName) ? "non-boolean-value" : "unknown-cap");
 		const key = `${deviceId}:${capName}`;
 		const prior = this.lastValues.get(key);
 		this.lastValues.set(key, value);
-		if (prior === void 0 || prior === value) return [];
-		if (!value) return [];
-		return this.matchAndDebounce((a) => a.sourceDeviceId === deviceId);
+		if (prior === void 0) {
+			if (!value) return ignoredResult("baseline-seeded-inactive");
+			if (!this.roseAfterWeStartedWatching(capName, slice)) return ignoredResult("baseline-seeded-stale-active");
+			return this.matchAndDebounce(deviceId);
+		}
+		if (prior === value) return ignoredResult("no-change");
+		if (!value) return ignoredResult("falling-edge");
+		return this.matchAndDebounce(deviceId);
 	}
-	matchAndDebounce(predicate) {
+	/**
+	* Can this slice PROVE its active state is a transition we would have
+	* witnessed had we been listening — i.e. recent, and after we started?
+	*/
+	roseAfterWeStartedWatching(capName, slice) {
+		const changedAt = sliceChangedAt(capName, slice);
+		if (changedAt === null) return false;
+		return changedAt >= Math.max(this.startedAt, this.now() - this.firstSightingFreshnessMs);
+	}
+	matchAndDebounce(sourceDeviceId) {
 		const now = this.now();
 		const fired = [];
+		const debounced = [];
 		for (const assignment of this.assignments) {
-			if (!predicate(assignment)) continue;
+			if (assignment.sourceDeviceId !== sourceDeviceId) continue;
 			const last = this.lastFiredAt.get(assignment.cameraId);
-			if (last !== void 0 && now - last < this.debounceMs) continue;
+			if (last !== void 0 && now - last < this.debounceMs) {
+				debounced.push(assignment.cameraId);
+				continue;
+			}
 			this.lastFiredAt.set(assignment.cameraId, now);
 			fired.push(assignment.cameraId);
 		}
-		return fired;
+		if (fired.length === 0 && debounced.length === 0) return ignoredResult("no-assignment");
+		return {
+			fired,
+			debounced,
+			ignored: null
+		};
 	}
 };
 //#endregion
+//#region src/builtins/doorbell/binding-mirror.ts
+/**
+* Fold one SUCCESSFUL bindings read into the mirror. A read that failed must
+* never reach this function — an unanswerable store carries no information
+* and must leave the mirror exactly as it was.
+*/
+function nextBindingState(previous, boundNow) {
+	if (boundNow) return "bound";
+	return previous === "unbind-pending" || previous === "unbound" ? "unbound" : "unbind-pending";
+}
+/** May a ring proceed? Only a corroborated unbind stops one. */
+function allowsRing(state) {
+	return state !== "unbound";
+}
+/** True only when a read has positively confirmed the binding. */
+function hasConfirmedBinding(state) {
+	return state === "bound";
+}
+//#endregion
 //#region src/builtins/doorbell/doorbell-settings.ts
 /**
 * Pure per-camera settings parsing/normalization for the virtual-doorbell
@@ -227,10 +330,6 @@ function applyDoorbellSourcesPatch(current, patchValue) {
 }
 //#endregion
 //#region src/builtins/doorbell/virtual-doorbell.addon.ts
-/** Reload the camera→source assignment map at most this often (lazily,
-*  on trigger traffic). Covers devices/settings appearing after boot
-*  without a settings save. */
-var ASSIGNMENTS_TTL_MS = 6e4;
 /** Structural narrowing helper for untrusted bus payloads. */
 function isRecord(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -286,19 +385,32 @@ function parseDoorbellSlice(slice) {
 *      bumps the camera's `doorbell` runtime-state counters via the
 *      standard `deviceState.setCapSlice` plumbing.
 *
-* Fires ONLY for cameras where the wrapper is BOUND (checked against
-* `deviceManager.getBindings`) and at least one source device is configured.
+* Fires ONLY for cameras with at least one configured source device that
+* this wrapper is BOUND to. The binding is NOT re-derived on the ring path:
+* it is mirrored in memory (`binding-mirror.ts`) and refreshed on the
+* assignment-reload cadence, because a fallible read must never be able to
+* destroy a one-shot press.
 */
 var VirtualDoorbellAddon = class extends require_dist.BaseAddon {
 	engine;
 	/** Monotonic guard: assignments are reloaded lazily on trigger traffic. */
 	assignmentsLoadedAt = 0;
 	assignmentsLoading = null;
+	/**
+	* Per-camera mirror of "is this wrapper still the active doorbell
+	* binding". Written ONLY off the ring path; read on it. See
+	* `binding-mirror.ts` for why a single negative read is not believed.
+	*/
+	bindingMirror = /* @__PURE__ */ new Map();
 	constructor() {
-		super({ debounceMs: 2e3 });
+		super({
+			debounceMs: 2e3,
+			assignmentsTtlMs: 6e4
+		});
 		this.engine = new DoorbellTriggerEngine({ debounceMs: 2e3 });
 	}
 	async onInitialize() {
+		this.engine = new DoorbellTriggerEngine({ debounceMs: this.config.debounceMs });
 		this.ctx.logger.info("Virtual doorbell wrapper initialized");
 		this.subscribe({ category: require_dist.EventCategory.DeviceStateChanged }, (event) => {
 			const data = parseDeviceStateChanged(event.data);
@@ -318,22 +430,62 @@ var VirtualDoorbellAddon = class extends require_dist.BaseAddon {
 	async handleStateChanged(data) {
 		if (!isSourceCap(data.capName)) return;
 		await this.ensureAssignments();
-		const cameraIds = this.engine.onStateSlice(data.deviceId, data.capName, data.slice);
-		for (const cameraId of cameraIds) await this.fireDoorbell(cameraId, Date.now());
+		const result = this.engine.onStateSlice(data.deviceId, data.capName, data.slice);
+		this.logSuppressions(data, result);
+		for (const cameraId of result.fired) await this.fireDoorbell(cameraId, Date.now());
+	}
+	/**
+	* Say out loud every case where a rise did NOT become a ring. Silence
+	* reads as "never happened": three real presses on camera 615 produced
+	* zero operator-visible lines because the drop logged at `debug`.
+	*/
+	logSuppressions(data, result) {
+		for (const cameraId of result.debounced) this.ctx.logger.info("virtual-doorbell: rise suppressed by the debounce window", {
+			tags: { deviceId: cameraId },
+			meta: {
+				sourceDeviceId: data.deviceId,
+				capName: data.capName
+			}
+		});
+		if (result.ignored === "baseline-seeded-stale-active") {
+			const message = "virtual-doorbell: first slice seen for this source is already ACTIVE but its transition could not be dated — seeded as baseline, a press may have been swallowed";
+			const options = {
+				tags: { deviceId: data.deviceId },
+				meta: { capName: data.capName }
+			};
+			if (this.engine.hasSource(data.deviceId)) this.ctx.logger.warn(message, options);
+			else this.ctx.logger.debug(message, options);
+			return;
+		}
+		if (result.ignored === "no-assignment") this.ctx.logger.debug("virtual-doorbell: rise on a source no camera is wired to", {
+			tags: { deviceId: data.deviceId },
+			meta: { capName: data.capName }
+		});
 	}
 	/**
-	* Ring the camera's virtual doorbell: verify the wrapper is BOUND to
-	* the camera, bump the `doorbell` runtime-state counters through the
-	* canonical `deviceState.setCapSlice` write, and emit the typed
-	* `DoorbellOnPressed` event with the CAMERA as source — byte-shaped
-	* like a native firmware ring so every downstream consumer (UI
-	* toast, notifier rules, exporters) is agnostic to the origin.
+	* Ring the camera's virtual doorbell: bump the `doorbell` runtime-state
+	* counters through the canonical `deviceState.setCapSlice` write, and
+	* emit the typed `DoorbellOnPressed` event with the CAMERA as source —
+	* byte-shaped like a native firmware ring so every downstream consumer
+	* (UI toast, notifier rules, exporters) is agnostic to the origin.
+	*
+	* The binding gate here is a pure in-memory read. It performs NO I/O and
+	* cannot fail: the whole point of the mirror is that the ring path can no
+	* longer be talked out of ringing by a store that answered badly.
 	*/
 	async fireDoorbell(cameraId, timestamp) {
-		if (!await this.isWrapperBound(cameraId)) {
-			this.ctx.logger.debug("virtual-doorbell: trigger matched but wrapper not bound — skipping", { tags: { deviceId: cameraId } });
+		const binding = this.bindingMirror.get(cameraId);
+		if (!allowsRing(binding)) {
+			this.ctx.logger.warn("virtual-doorbell: ring DROPPED — the wrapper is not bound to this camera, but a trigger source is still configured for it", {
+				tags: { deviceId: cameraId },
+				meta: { bindingState: binding }
+			});
 			return;
 		}
+		if (!hasConfirmedBinding(binding)) this.ctx.logger.warn("virtual-doorbell: ringing on an unconfirmed binding — the bindings store has not corroborated an unbind, and a one-shot press is never dropped on an unproven read", {
+			tags: { deviceId: cameraId },
+			meta: { bindingState: binding ?? "never-read" }
+		});
 		try {
 			const next = {
 				lastPressedAt: timestamp,
@@ -367,17 +519,51 @@ var VirtualDoorbellAddon = class extends require_dist.BaseAddon {
 			meta: { timestamp }
 		});
 	}
-	/** True when THIS wrapper is the active `doorbell` binding for the camera. */
-	async isWrapperBound(cameraId) {
+	/**
+	* Fold one bindings read for `cameraId` into the mirror. Runs on the
+	* assignment-reload cadence, never while firing.
+	*
+	* A read that THROWS carries no information and leaves the mirror exactly
+	* as it was — the previous verdict keeps standing. A read that succeeds
+	* but omits our activation only ARMS a revocation; `nextBindingState`
+	* requires a second consecutive negative before the camera goes silent,
+	* because a genuine unbind and a store answering from an empty snapshot
+	* (D44) are indistinguishable in a single response.
+	*/
+	async refreshBindingMirror(cameraId) {
+		let entries;
 		try {
-			return (await this.ctx.api.deviceManager.getBindings.query({ deviceId: cameraId })).entries.some((entry) => entry.capName === require_dist.doorbellCapability.name && entry.kind === "wrapped" && entry.providerAddonId === this.ctx.id);
+			entries = (await this.ctx.api.deviceManager.getBindings.query({ deviceId: cameraId })).entries;
 		} catch (err) {
-			this.ctx.logger.debug("virtual-doorbell: getBindings failed — treating as unbound", {
+			this.ctx.logger.warn("virtual-doorbell: binding check failed — keeping the last known verdict, NOT treating this as an unbind", {
 				tags: { deviceId: cameraId },
-				meta: { error: require_dist.errMsg(err) }
+				meta: {
+					error: require_dist.errMsg(err),
+					bindingState: this.bindingMirror.get(cameraId)
+				}
 			});
-			return false;
+			return;
 		}
+		const boundNow = entries.some((entry) => entry.capName === require_dist.doorbellCapability.name && entry.kind === "wrapped" && entry.providerAddonId === this.ctx.id);
+		const previous = this.bindingMirror.get(cameraId);
+		const next = nextBindingState(previous, boundNow);
+		this.bindingMirror.set(cameraId, next);
+		if (next !== previous && next !== "bound") this.ctx.logger.warn("virtual-doorbell: bindings read did not see this wrapper", {
+			tags: { deviceId: cameraId },
+			meta: {
+				from: previous ?? "never-read",
+				to: next
+			}
+		});
+	}
+	/**
+	* Record a binding we observed FIRST-HAND. Both callers are cap methods
+	* the router only reaches by resolving this wrapper for this device —
+	* which it can only do through the binding — so a call is direct evidence
+	* and outranks anything the store says.
+	*/
+	confirmBindingFromCapCall(deviceId) {
+		this.bindingMirror.set(deviceId, nextBindingState(this.bindingMirror.get(deviceId), true));
 	}
 	/**
 	* Lazily (re)build the camera→source assignment set from every
@@ -386,7 +572,8 @@ var VirtualDoorbellAddon = class extends require_dist.BaseAddon {
 	* eagerly by `applyDeviceSettingsPatch`.
 	*/
 	async ensureAssignments() {
-		if (Date.now() - this.assignmentsLoadedAt < ASSIGNMENTS_TTL_MS) return;
+		const now = Date.now();
+		if (this.assignmentsLoadedAt > 0 && now - this.assignmentsLoadedAt < this.config.assignmentsTtlMs) return;
 		if (this.assignmentsLoading) return this.assignmentsLoading;
 		this.assignmentsLoading = this.loadAssignments().then(() => {
 			this.assignmentsLoadedAt = Date.now();
@@ -398,17 +585,29 @@ var VirtualDoorbellAddon = class extends require_dist.BaseAddon {
 		return this.assignmentsLoading;
 	}
 	async loadAssignments() {
+		if (!this.ctx.settings) {
+			this.ctx.logger.warn("virtual-doorbell: no settings store — every camera reads ZERO trigger sources, no doorbell can ring");
+			return;
+		}
 		const cameras = (await this.ctx.api.deviceManager.listAll.query({})).filter((d) => d.type === require_dist.DeviceType.Camera);
 		const assignments = [];
+		const configuredCameras = [];
 		for (const camera of cameras) {
 			const sources = await this.readDeviceSources(camera.id);
+			if (sources.length > 0) configuredCameras.push(camera.id);
 			for (const source of sources) assignments.push({
 				cameraId: camera.id,
 				sourceDeviceId: source.deviceId
 			});
 		}
+		for (const cameraId of configuredCameras) await this.refreshBindingMirror(cameraId);
+		const hadAssignments = this.engine.getAssignments().length > 0;
 		this.engine.setAssignments(assignments);
-		this.ctx.logger.debug("virtual-doorbell: assignments loaded", { meta: { count: assignments.length } });
+		if (hadAssignments && assignments.length === 0) this.ctx.logger.warn("virtual-doorbell: assignment reload went from configured to EMPTY — every camera just lost its trigger sources");
+		this.ctx.logger.debug("virtual-doorbell: assignments loaded", { meta: {
+			count: assignments.length,
+			configuredCameras: configuredCameras.length
+		} });
 	}
 	invalidateAssignments() {
 		this.assignmentsLoadedAt = 0;
@@ -425,7 +624,7 @@ var VirtualDoorbellAddon = class extends require_dist.BaseAddon {
 				capName: require_dist.doorbellCapability.name
 			}));
 		} catch (err) {
-			this.ctx.logger.debug("virtual-doorbell: getCapSlice failed during getStatus", {
+			this.ctx.logger.warn("virtual-doorbell: getCapSlice failed during getStatus", {
 				tags: { deviceId },
 				meta: { error: require_dist.errMsg(err) }
 			});
@@ -477,6 +676,7 @@ var VirtualDoorbellAddon = class extends require_dist.BaseAddon {
 	async buildDeviceSettingsContribution(deviceId) {
 		const device = await this.lookupDevice(deviceId);
 		if (device && device.type !== require_dist.DeviceType.Camera) return null;
+		this.confirmBindingFromCapCall(deviceId);
 		const sources = await this.readDeviceSources(deviceId);
 		return { sections: [{
 			id: "virtual-doorbell",
@@ -499,6 +699,7 @@ var VirtualDoorbellAddon = class extends require_dist.BaseAddon {
 	}
 	async saveDeviceSettingsPatch(deviceId, patch) {
 		if (!this.ctx.settings) throw new Error("[virtual-doorbell] settings store unavailable — cannot persist per-device settings");
+		this.confirmBindingFromCapCall(deviceId);
 		if ("doorbellSources" in patch) {
 			const next = applyDoorbellSourcesPatch(await this.ctx.settings.readDeviceStore(deviceId), patch[KEY_SOURCES]);
 			await this.ctx.settings.writeDeviceStore(deviceId, next);