@camstack/addon-post-analysis 1.2.34 → 1.2.35

package/dist/pipeline-analytics/index.mjs

@@ -1,4 +1,4 @@
-import { $ as EventCategory, A as notificationRulesCapability, B as createEvent, C as cosineSimilarity, D as faceGalleryCapability, F as videoclipsCapability, G as array, H as isDeviceScopedCap, I as zoneAnalyticsCapability, J as number, K as boolean, L as errMsg, M as plateGalleryCapability, N as readDeviceStateFrom, P as subKindsOf, Q as unknown, R as BaseAddon, S as buildEventKindDescriptor, T as defineCustomActions, U as nodePin, V as hydrateSchema, W as _enum, X as record, Y as object, Z as string, _ as TimelapseRuleInputSchema, a as MACRO_LABELS, b as alarmPanelCapability, c as NcConditionDescriptorSchema, d as NcRuleSchema, f as NcSnoozeInputSchema, g as OpsLogEntrySchema, h as NcTaxonomySchema, i as EVENT_PAD_MS, j as pipelineAnalyticsCapability, k as kebabToCamel, l as NcRuleInputSchema, m as NcSnoozeSuppressedSchema, n as DEFAULT_EVENT_COLOR, o as NC_CONDITION_CATALOG, p as NcSnoozeSchema, q as literal, r as EVENT_KIND_BY_CAP, s as NC_TAXONOMY, t as BaseDevice, u as NcRulePatchSchema, v as TimelapseRuleSchema, w as customAction, x as audioMetricsCapability, y as addonWidgetsSourceCapability, z as DeviceType } from "../dist-Bjhp9nkX.mjs";
+import { $ as EventCategory, A as notificationRulesCapability, B as createEvent, C as cosineSimilarity, D as faceGalleryCapability, F as videoclipsCapability, G as array, H as isDeviceScopedCap, I as zoneAnalyticsCapability, J as number, K as boolean, L as errMsg, M as plateGalleryCapability, N as readDeviceStateFrom, P as subKindsOf, Q as unknown, R as BaseAddon, S as buildEventKindDescriptor, T as defineCustomActions, U as nodePin, V as hydrateSchema, W as _enum, X as record, Y as object, Z as string, _ as TimelapseRuleInputSchema, a as MACRO_LABELS, b as alarmPanelCapability, c as NcConditionDescriptorSchema, d as NcRuleSchema, f as NcSnoozeInputSchema, g as OpsLogEntrySchema, h as NcTaxonomySchema, i as EVENT_PAD_MS, j as pipelineAnalyticsCapability, k as kebabToCamel, l as NcRuleInputSchema, m as NcSnoozeSuppressedSchema, n as DEFAULT_EVENT_COLOR, o as NC_CONDITION_CATALOG, p as NcSnoozeSchema, q as literal, r as EVENT_KIND_BY_CAP, s as NC_TAXONOMY, t as BaseDevice, u as NcRulePatchSchema, v as TimelapseRuleSchema, w as customAction, x as audioMetricsCapability, y as addonWidgetsSourceCapability, z as DeviceType } from "../dist-nh2kuzSC.mjs";
 import { promises } from "node:fs";
 import path from "node:path";
 import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
@@ -544,7 +544,132 @@ function mimeFromExtension(file) {
 	return "application/octet-stream";
 }
 //#endregion
+//#region src/notification-center/alarm/alarm-mode-coverage.ts
+/**
+* Whether the panel just BECAME armed, in the sense a person means.
+*
+* Two transitions reach an `armed_*` state and only one of them is an arm:
+*
+*  - `arming`/`disarmed` → `armed_away` is somebody arming the alarm. Announce.
+*  - `triggered` → `armed_away` is the siren's duration ending and the panel
+*    re-arming itself. Announcing it would send "Away armed" in the middle of
+*    a break-in, seconds after the alarm notification, saying nothing new.
+*
+* `armed_home` → `armed_away` IS an arm: the operator changed mode, and the
+* set of devices covered just changed with it — which is the whole content of
+* the message.
+*
+* A null `previous` is the FIRST publish and never announces. A hub restarting
+* while armed re-publishes `armed_away`, and nobody armed anything — every
+* deploy would otherwise send one. Handled here rather than by the caller
+* happening to wire the hook late, because "it works because of the order two
+* unrelated things run in" is how this stops working.
+*/
+function shouldAnnounceArm(previous, next) {
+	if (previous === null) return false;
+	if (!next.startsWith("armed_")) return false;
+	if (previous === next) return false;
+	if (previous === "triggered") return false;
+	return true;
+}
+/** The mode inside an `armed_<mode>` state, or null for any other state. */
+function armModeOf(state, modes) {
+	for (const mode of modes) if (state === armedStateFor(mode)) return mode;
+	return null;
+}
+/** The `deviceState` word a rule must gate on for `mode` to cover it. */
+function armedStateFor(mode) {
+	return `armed_${mode}`;
+}
+/**
+* One entry per mode the panel offers, including modes nothing is gated on.
+*
+* Empty modes are KEPT rather than filtered: "Night arms nothing" is the single
+* most useful thing this can tell an operator, and a list that omits it looks
+* identical to a list where night is covered.
+*/
+function alarmModeCoverage(rules, panelDeviceId, modes) {
+	return modes.map((mode) => coverageFor(rules, panelDeviceId, mode));
+}
+function coverageFor(rules, panelDeviceId, mode) {
+	const wanted = armedStateFor(mode);
+	const ids = /* @__PURE__ */ new Set();
+	let ruleCount = 0;
+	let allDevices = false;
+	for (const rule of rules) {
+		if (!rule.enabled) continue;
+		const gate = rule.conditions.deviceState;
+		if (gate === void 0 || gate.deviceId !== panelDeviceId) continue;
+		if (!gate.states.includes(wanted)) continue;
+		ruleCount += 1;
+		const scope = rule.conditions.devices;
+		if (scope === void 0 || scope.length === 0) {
+			allDevices = true;
+			continue;
+		}
+		for (const id of scope) ids.add(id);
+	}
+	return {
+		mode,
+		ruleCount,
+		allDevices,
+		deviceIds: [...ids].toSorted((a, b) => a - b)
+	};
+}
+/**
+* "Away armed — 3 cameras: Front door, Garage, Gate."
+*
+* Names, not ids: this is read by a person standing at a door. An id that has
+* no name falls back to `Device <id>` rather than being dropped — a silently
+* shorter list would understate what is armed, which is the one error this
+* message must not make.
+*
+* Returns null when the mode covers NOTHING and no rule is gated on it. A
+* notification saying "Night armed" that is followed by nothing happening all
+* night is worse than no notification: it is a false assurance. The caller
+* still logs the arm.
+*/
+function buildArmAnnouncement(coverage, deviceNames) {
+	if (coverage.ruleCount === 0) return null;
+	const title = `${modeLabel(coverage.mode)} armed`;
+	if (coverage.allDevices) return {
+		title,
+		body: `Every device is armed (${plural$1(coverage.ruleCount, "rule")}).`
+	};
+	if (coverage.deviceIds.length === 0) return {
+		title,
+		body: `${plural$1(coverage.ruleCount, "rule")}, no device restriction.`
+	};
+	const names = coverage.deviceIds.map((id) => deviceNames.get(id) ?? `Device ${id}`);
+	return {
+		title,
+		body: `${plural$1(names.length, "device")} armed: ${names.join(", ")}.`
+	};
+}
+function modeLabel(mode) {
+	return mode.charAt(0).toUpperCase() + mode.slice(1).replace(/_/g, " ");
+}
+function plural$1(n, one) {
+	return n === 1 ? `1 ${one}` : `${n} ${one}s`;
+}
+//#endregion
 //#region src/notification-center/alarm/alarm-state-machine.ts
+/**
+* Defaults an operator can change per panel. `home` has no exit delay on
+* purpose — nobody is leaving — but the shared value is applied to every mode
+* until per-mode delays are asked for.
+*
+* `triggeredDurationSec: 0` = "sound until somebody disarms it". That is what
+* the panel did before the field existed, so an install that never opens the
+* tab keeps behaving exactly as it did — a default that silently re-armed
+* every existing alarm after N seconds would be a behaviour change nobody
+* asked for.
+*/
+var DEFAULT_DELAYS = {
+	exitDelaySec: 30,
+	entryDelaySec: 20,
+	triggeredDurationSec: 0
+};
 var DISARMED = {
 	target: "disarmed",
 	fired: false,
@@ -561,6 +686,7 @@ function armedState(mode) {
 * answer is still correct the moment anyone asks.
 */
 function stateAt(m, now) {
+	if (m.clearAt !== void 0 && now >= m.clearAt) return m.target;
 	if (m.fired) return "triggered";
 	if (m.triggerAt !== void 0) return now >= m.triggerAt ? "triggered" : "pending";
 	if (m.armedAt !== void 0) return now >= m.armedAt ? m.target : "arming";
@@ -614,19 +740,24 @@ function disarm(now) {
 * intruder walking past two sensors would otherwise postpone the alarm.
 */
 function trigger(m, delays, now) {
+	const state = stateAt(m, now);
+	if (state === "triggered" || state === "pending") return m;
 	if (!isArmed(m, now)) return m;
-	if (m.fired || m.triggerAt !== void 0) return m;
-	if (delays.entryDelaySec <= 0) return {
-		...m,
-		fired: true,
-		changedAt: now
-	};
+	const base = settle(m, now);
+	const firesAt = now + Math.max(0, delays.entryDelaySec) * 1e3;
 	return {
-		...m,
-		triggerAt: now + delays.entryDelaySec * 1e3,
+		...base,
+		triggerAt: firesAt,
+		...autoClear(delays, firesAt),
+		fired: false,
 		changedAt: now
 	};
 }
+/** `clearAt` iff the operator asked for a bounded siren — see {@link AlarmDelays}. */
+function autoClear(delays, firesAt) {
+	if (delays.triggeredDurationSec <= 0) return {};
+	return { clearAt: firesAt + delays.triggeredDurationSec * 1e3 };
+}
 /**
 * Settle the machine so a stored value never depends on when it is read.
 *
@@ -635,10 +766,16 @@ function trigger(m, delays, now) {
 * than only in the reading of it.
 */
 function settle(m, now) {
+	if (m.clearAt !== void 0 && now >= m.clearAt) return {
+		target: m.target,
+		fired: false,
+		changedAt: m.clearAt
+	};
 	if (m.triggerAt !== void 0 && now >= m.triggerAt) return {
 		target: m.target,
 		fired: true,
-		changedAt: m.triggerAt
+		changedAt: m.triggerAt,
+		...m.clearAt !== void 0 ? { clearAt: m.clearAt } : {}
 	};
 	if (m.armedAt !== void 0 && now >= m.armedAt) return {
 		target: m.target,
@@ -667,21 +804,12 @@ function settle(m, now) {
 * and re-publish when a delay elapses.
 */
 /** Every arm mode a camstack-owned panel offers. */
-var MODES = [
+var NC_ALARM_MODES = [
 	"home",
 	"away",
 	"night"
 ];
 /**
-* Defaults an operator can change per panel. `home` has no exit delay on
-* purpose — nobody is leaving — but the shared value is applied to every mode
-* until per-mode delays are asked for.
-*/
-var DEFAULT_DELAYS = {
-	exitDelaySec: 30,
-	entryDelaySec: 20
-};
-/**
 * How often the panel re-publishes while a delay is running.
 *
 * The state is computed from an INSTANT, so this tick only decides how quickly
@@ -697,30 +825,94 @@ var TICK_MS = 1e3;
 var ncAlarmPanelSchema = object({
 	exitDelaySec: number().int().min(0).max(600).default(DEFAULT_DELAYS.exitDelaySec),
 	entryDelaySec: number().int().min(0).max(600).default(DEFAULT_DELAYS.entryDelaySec),
+	triggeredDurationSec: number().int().min(0).max(3600).default(DEFAULT_DELAYS.triggeredDurationSec),
+	/** Send a notification when a mode takes effect. Off until asked for. */
+	announceArm: boolean().default(false),
+	/** Target ids that announcement goes to — see `NcAlarmSettingsSchema`. */
+	announceTargets: array(string()).default([]),
 	machine: record(string(), unknown()).optional()
 });
+/** `armed_home` and friends — the only targets a machine may settle into. */
+function isArmTarget(value) {
+	return value === "disarmed" || typeof value === "string" && value.startsWith("armed_");
+}
+function optionalInstant(value) {
+	return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+/**
+* Rebuild the machine from the persisted blob, or null when there is nothing
+* trustworthy in it.
+*
+* A type GUARD, not a cast: the blob has survived a schema change once already
+* (`clearAt` did not exist), and the failure mode of a cast here is an alarm
+* that reports a state it cannot reach. Anything unrecognised falls back to
+* DISARMED, which is the state an operator will notice.
+*
+* Exported for the test that proves a pre-`clearAt` blob still restores.
+*/
+function machineFromPersisted(raw) {
+	if (raw === null || typeof raw !== "object") return null;
+	const rec = { ...raw };
+	if (!isArmTarget(rec["target"]) || typeof rec["changedAt"] !== "number") return null;
+	const armedAt = optionalInstant(rec["armedAt"]);
+	const triggerAt = optionalInstant(rec["triggerAt"]);
+	const clearAt = optionalInstant(rec["clearAt"]);
+	return {
+		target: rec["target"],
+		...armedAt !== void 0 ? { armedAt } : {},
+		...triggerAt !== void 0 ? { triggerAt } : {},
+		...clearAt !== void 0 ? { clearAt } : {},
+		fired: rec["fired"] === true,
+		changedAt: rec["changedAt"]
+	};
+}
 var NcAlarmPanelDevice = class extends BaseDevice {
 	features = [];
 	machine = DISARMED;
 	delays = DEFAULT_DELAYS;
 	ticker = null;
+	onArmed = null;
+	/**
+	* The state the last publish reported. Null until the first one, so the
+	* BOOT publish never announces: a hub restarting while armed would otherwise
+	* announce "Away armed" on every deploy.
+	*/
+	lastPublished = null;
 	constructor(ctx) {
 		super(ctx, ncAlarmPanelSchema, { type: ctx.deviceMeta.type });
-		this.delays = {
-			exitDelaySec: this.config.get("exitDelaySec"),
-			entryDelaySec: this.config.get("entryDelaySec")
-		};
+		this.delays = this.readDelays();
 		this.restore();
 		this.registerAlarmCap();
 		this.publish();
 	}
-	/** Fire a trigger at the panel. Called by the notification center when a rule
-	*  that arms the alarm matches. Ignored unless the panel is armed. */
-	onRuleTriggered(now = Date.now()) {
-		const next = trigger(this.machine, this.delays, now);
-		if (next === this.machine) return;
-		this.machine = next;
-		this.publish(now);
+	/** The operator-visible configuration, as the cap serves it. */
+	settings() {
+		return {
+			...this.readDelays(),
+			announceArm: this.config.get("announceArm"),
+			announceTargets: [...this.config.get("announceTargets")]
+		};
+	}
+	/**
+	* Apply an editor's patch and return what the panel settled on.
+	*
+	* The new delays take effect on the NEXT transition, never retroactively: a
+	* machine already counting down keeps the instants it was given. Re-deriving
+	* `armedAt` from a delay the operator changed mid-exit would move the arm
+	* instant under somebody who is walking out of the door.
+	*/
+	async applySettings(patch) {
+		if (patch.exitDelaySec !== void 0) await this.config.set("exitDelaySec", patch.exitDelaySec);
+		if (patch.entryDelaySec !== void 0) await this.config.set("entryDelaySec", patch.entryDelaySec);
+		if (patch.triggeredDurationSec !== void 0) await this.config.set("triggeredDurationSec", patch.triggeredDurationSec);
+		if (patch.announceArm !== void 0) await this.config.set("announceArm", patch.announceArm);
+		if (patch.announceTargets !== void 0) await this.config.set("announceTargets", [...patch.announceTargets]);
+		this.delays = this.readDelays();
+		return this.settings();
+	}
+	/** Wire the arm announcement. See {@link NcAlarmArmedHook}. */
+	setArmedHook(hook) {
+		this.onArmed = hook;
 	}
 	/** Current lifecycle word — what the `deviceState` gate compares against. */
 	currentState(now = Date.now()) {
@@ -743,19 +935,24 @@ var NcAlarmPanelDevice = class extends BaseDevice {
 				this.publish();
 			},
 			trigger: async () => {
-				this.machine = {
-					...this.machine,
-					fired: true,
-					changedAt: Date.now()
-				};
-				this.publish();
+				const now = Date.now();
+				const next = trigger(this.machine, this.delays, now);
+				if (next === this.machine) {
+					this.ctx.logger.info("alarm trigger ignored — the panel is not armed", {
+						tags: { deviceId: this.id },
+						meta: { state: stateAt(this.machine, now) }
+					});
+					return;
+				}
+				this.machine = next;
+				this.publish(now);
 			}
 		});
 	}
 	status(now = Date.now()) {
 		return {
 			state: stateAt(this.machine, now),
-			availableModes: [...MODES],
+			availableModes: [...NC_ALARM_MODES],
 			requiresCode: false,
 			lastChangedAt: this.machine.changedAt
 		};
@@ -769,11 +966,48 @@ var NcAlarmPanelDevice = class extends BaseDevice {
 	*/
 	publish(now = Date.now()) {
 		this.machine = settle(this.machine, now);
+		const state = stateAt(this.machine, now);
 		this.runtimeState.setCapState("alarm-panel", this.status(now));
 		this.persist();
-		if (this.machine.armedAt !== void 0 || this.machine.triggerAt !== void 0) this.startTicking();
+		this.announceIfArmed(state);
+		if (this.machine.armedAt !== void 0 || this.machine.triggerAt !== void 0 || this.machine.clearAt !== void 0) this.startTicking();
 		else this.stopTicking();
 	}
+	/**
+	* Fire the arm hook on the transition INTO an armed mode.
+	*
+	* Never throws into the publish path: an announcement that could take the
+	* panel's own state update with it would make a notification failure look
+	* like an alarm failure.
+	*/
+	announceIfArmed(state) {
+		const previous = this.lastPublished;
+		this.lastPublished = state;
+		const hook = this.onArmed;
+		if (hook === null) return;
+		if (!shouldAnnounceArm(previous, state)) return;
+		const mode = armModeOf(state, NC_ALARM_MODES);
+		if (mode === null) return;
+		try {
+			hook(mode);
+		} catch (err) {
+			this.ctx.logger.warn("alarm arm announcement failed", {
+				tags: { deviceId: this.id },
+				meta: {
+					mode,
+					error: String(err)
+				}
+			});
+		}
+	}
+	/** The three durations, read from the persisted config. */
+	readDelays() {
+		return {
+			exitDelaySec: this.config.get("exitDelaySec"),
+			entryDelaySec: this.config.get("entryDelaySec"),
+			triggeredDurationSec: this.config.get("triggeredDurationSec")
+		};
+	}
 	startTicking() {
 		if (this.ticker !== null) return;
 		this.ticker = setInterval(() => this.publish(), TICK_MS);
@@ -790,17 +1024,9 @@ var NcAlarmPanelDevice = class extends BaseDevice {
 		this.config.set("machine", { ...this.machine });
 	}
 	restore() {
-		const raw = this.config.get("machine");
-		if (raw === null || typeof raw !== "object") return;
-		const m = raw;
-		if (typeof m.target !== "string" || typeof m.changedAt !== "number") return;
-		this.machine = {
-			target: m.target,
-			...typeof m.armedAt === "number" ? { armedAt: m.armedAt } : {},
-			...typeof m.triggerAt === "number" ? { triggerAt: m.triggerAt } : {},
-			fired: m.fired === true,
-			changedAt: m.changedAt
-		};
+		const restored = machineFromPersisted(this.config.get("machine"));
+		if (restored === null) return;
+		this.machine = restored;
 	}
 };
 //#endregion
@@ -5068,14 +5294,21 @@ function readSensorEventType(value) {
 	const eventType = last["eventType"];
 	return typeof eventType === "string" && eventType.length > 0 ? eventType : void 0;
 }
-/** Build the subject for a `device-event` evaluation (a persisted SensorEvent —
-*  one row per linked camera; `deviceId` is the CAMERA). */
+/**
+* Build the subject for a `device-event` evaluation (a persisted SensorEvent —
+* one row per linked camera; `deviceId` is the CAMERA).
+*
+* BOTH ids ride along. The camera is what the notification shows; the sensor is
+* what the operator named in the rule. Carrying only the camera is what made a
+* sensor-scoped rule unmatched — see {@link NcRuleSubject.sourceDeviceId}.
+*/
 function subjectFromSensorEvent(ev) {
 	const eventType = readSensorEventType(ev.value);
 	return {
 		kind: "device-event",
 		recordId: ev.id,
 		deviceId: ev.deviceId,
+		...ev.sourceDeviceId !== ev.deviceId ? { sourceDeviceId: ev.sourceDeviceId } : {},
 		timestamp: ev.timestamp,
 		classNames: [],
 		zones: [],
@@ -5307,7 +5540,7 @@ function evaluateRule(rule, subject, deviceState) {
 		if (current === void 0) return fail("deviceState");
 		if (!toLowerSet(c.deviceState.states).has(current.trim().toLowerCase())) return fail("deviceState");
 	}
-	if (c.devices !== void 0 && c.devices.length > 0 && !c.devices.includes(subject.deviceId)) return fail("devices");
+	if (c.devices !== void 0 && c.devices.length > 0 && !matchesDeviceScope(c.devices, subject)) return fail("devices");
 	if (c.source !== void 0 && c.source !== "any") {
 		if ((subject.source ?? "pipeline") !== c.source) return fail("source");
 	}
@@ -5494,6 +5727,28 @@ function keysPerClass(rule, subject) {
 	return rule.throttle.granularity === "per-class";
 }
 /** Stable cooldown key per the rule's throttle scope + class granularity. */
+/**
+* Does the rule's device scope cover this subject?
+*
+* EITHER id matches, and both are needed for the same rule to be authorable
+* the two ways an operator thinks about it:
+*
+*  - "when anything happens on the front-door CAMERA" → the camera id, which
+*    is what a sensor row is attributed to;
+*  - "when the front-door CONTACT opens" → the sensor id, which is the device
+*    the operator actually cares about and the one they pick in the Devices
+*    tab. Before this, that rule matched nothing, ever, silently.
+*
+* Consequence worth knowing: a sensor linked to N cameras persists N rows, so
+* a SENSOR-scoped rule is evaluated N times for one door opening. The rule's
+* own throttle is what collapses that — `scope: 'rule'` gives one
+* notification, `scope: 'device'` gives one per camera, which is the right
+* choice when each carries its own picture.
+*/
+function matchesDeviceScope(scope, subject) {
+	if (scope.includes(subject.deviceId)) return true;
+	return subject.sourceDeviceId !== void 0 && scope.includes(subject.sourceDeviceId);
+}
 function cooldownKey(rule, subject) {
 	const first = subject.classNames[0];
 	const classKey = keysPerClass(rule, subject) && first !== void 0 ? `:c:${first}` : "";
@@ -5768,6 +6023,82 @@ var NcDispatcher = class {
 			return false;
 		}
 	}
+	/**
+	* Send a Notification-Center-composed message to ONE target.
+	*
+	* Never throws and never retries — see {@link NcAnnouncementSendInput}. Every
+	* way of not delivering produces a line: an announcement that silently did
+	* not arrive is indistinguishable from the alarm not having armed, which is
+	* the exact confusion this feature exists to remove.
+	*/
+	async deliverAnnouncement(input) {
+		const tags = input.deviceId !== void 0 ? { deviceId: input.deviceId } : void 0;
+		let target;
+		try {
+			target = await this.resolveTarget(input.targetId);
+		} catch (err) {
+			this.deps.logger.warn("announcement: target catalog unreachable", {
+				...tags !== void 0 ? { tags } : {},
+				meta: {
+					reason: input.reason,
+					targetId: input.targetId,
+					error: String(err)
+				}
+			});
+			return false;
+		}
+		if (target === null || !target.enabled) {
+			this.deps.logger.warn("announcement: target gone or disabled", {
+				...tags !== void 0 ? { tags } : {},
+				meta: {
+					reason: input.reason,
+					targetId: input.targetId
+				}
+			});
+			return false;
+		}
+		try {
+			const result = await this.deps.send({
+				addonId: target.addonId,
+				targetId: target.id,
+				notification: {
+					title: input.title,
+					body: input.body,
+					priority: 2,
+					...input.deviceId !== void 0 ? { deviceId: input.deviceId } : {}
+				}
+			});
+			if (!result.success) {
+				this.deps.logger.warn("announcement send failed", {
+					...tags !== void 0 ? { tags } : {},
+					meta: {
+						reason: input.reason,
+						targetId: target.id,
+						error: result.error
+					}
+				});
+				return false;
+			}
+			this.deps.logger.info("announcement delivered", {
+				...tags !== void 0 ? { tags } : {},
+				meta: {
+					reason: input.reason,
+					target: target.name
+				}
+			});
+			return true;
+		} catch (err) {
+			this.deps.logger.warn("announcement send threw", {
+				...tags !== void 0 ? { tags } : {},
+				meta: {
+					reason: input.reason,
+					targetId: target.id,
+					error: String(err)
+				}
+			});
+			return false;
+		}
+	}
 	/** Device display names for a set of ids, for the digest's lines. */
 	async resolveDeviceNames(deviceIds) {
 		const out = /* @__PURE__ */ new Map();
@@ -8124,6 +8455,19 @@ var TimelapseStore = class {
 * CRUD served elsewhere becomes effective within one rule-reload tick.
 */
 /**
+* What `getAlarmConfig` answers on a node with no panel.
+*
+* The DEFAULTS, not zeroes: paired with `deviceId: null` this tells a client
+* "there is no panel here" while still describing the shape it would have.
+* Zeroes would render as "no entry delay", which is a claim about an alarm
+* that does not exist.
+*/
+var NC_ALARM_SETTINGS_FALLBACK = {
+	...DEFAULT_DELAYS,
+	announceArm: false,
+	announceTargets: []
+};
+/**
 * How often the "matched NO rule" report may fire per device. Long enough that
 * a busy camera prints one line rather than one per event, short enough that a
 * rule which has stopped matching is visible within minutes rather than by
@@ -8249,6 +8593,8 @@ var NotificationCenter = class NotificationCenter {
 	/** True when ≥1 enabled `device-event` rule declares an occupancy condition —
 	*  the watcher is idle (zero per-frame cost) otherwise. */
 	occupancyEnabled = false;
+	/** The panel this node owns, or null. See {@link NcAlarmPanelPort}. */
+	alarmPanel = null;
 	/** In-memory cooldown map — seeded from persisted outbox rows on start. */
 	lastFiredAt = /* @__PURE__ */ new Map();
 	/** Per-device rate limit for the "matched NO rule" report — see `reportNoMatch`. */
@@ -8679,9 +9025,105 @@ var NotificationCenter = class NotificationCenter {
 			cancelSnooze: async ({ snoozeId, caller }) => {
 				await this.cancelSnooze(snoozeId, caller);
 				return { success: true };
+			},
+			getAlarmConfig: async () => this.alarmConfig(),
+			setAlarmConfig: async ({ patch }) => {
+				const panel = this.alarmPanel;
+				if (panel === null) throw new Error("this node has no alarm panel");
+				const settings = await panel.applySettings(patch);
+				this.logger.info("alarm settings changed", {
+					tags: { deviceId: panel.deviceId },
+					meta: {
+						exitDelaySec: settings.exitDelaySec,
+						entryDelaySec: settings.entryDelaySec,
+						triggeredDurationSec: settings.triggeredDurationSec,
+						announceArm: settings.announceArm,
+						announceTargets: settings.announceTargets.length
+					}
+				});
+				return this.alarmConfig();
 			}
 		};
 	}
+	/**
+	* Adopt the panel this node owns. Called once by the addon after
+	* `ensureAlarmPanel`; a node without one never calls it and the cap then
+	* answers `deviceId: null`.
+	*/
+	setAlarmPanel(panel) {
+		this.alarmPanel = panel;
+	}
+	/** Settings + the DERIVED coverage. Read together — see the cap doc. */
+	alarmConfig() {
+		const panel = this.alarmPanel;
+		if (panel === null) return {
+			deviceId: null,
+			settings: NC_ALARM_SETTINGS_FALLBACK,
+			coverage: []
+		};
+		return {
+			deviceId: panel.deviceId,
+			settings: panel.settings(),
+			coverage: this.coverageFor(panel).map((c) => ({
+				...c,
+				deviceIds: [...c.deviceIds]
+			}))
+		};
+	}
+	coverageFor(panel) {
+		return alarmModeCoverage(this.rules.list(), panel.deviceId, panel.availableModes());
+	}
+	/**
+	* Say which devices a mode just armed.
+	*
+	* Called by the panel on the transition INTO an armed mode. Fire-and-forget
+	* and never able to fail the panel: `announceArm` returns void, and every
+	* branch that sends nothing logs why — a mode that arms nothing is the most
+	* important thing this can report, and it is exactly the case where no
+	* message goes out.
+	*/
+	announceArm(mode) {
+		this.deliverArmAnnouncement(mode).catch((err) => {
+			this.logger.warn("alarm arm announcement failed", { meta: {
+				mode,
+				error: String(err)
+			} });
+		});
+	}
+	async deliverArmAnnouncement(mode) {
+		const panel = this.alarmPanel;
+		if (panel === null) return;
+		const settings = panel.settings();
+		const tags = { deviceId: panel.deviceId };
+		if (!settings.announceArm) return;
+		if (settings.announceTargets.length === 0) {
+			this.logger.info("alarm armed but no announcement target is configured", {
+				tags,
+				meta: { mode }
+			});
+			return;
+		}
+		const coverage = this.coverageFor(panel).find((c) => c.mode === mode);
+		if (coverage === void 0) return;
+		const message = buildArmAnnouncement(coverage, await this.dispatcher.resolveDeviceNames(coverage.deviceIds));
+		if (message === null) {
+			this.logger.warn("alarm armed into a mode no enabled rule is gated on", {
+				tags,
+				meta: {
+					mode,
+					state: `armed_${mode}`
+				}
+			});
+			return;
+		}
+		for (const targetId of settings.announceTargets) await this.dispatcher.deliverAnnouncement({
+			reason: "alarm-arm",
+			targetId,
+			title: message.title,
+			body: message.body,
+			deviceId: panel.deviceId
+		});
+	}
 	/** Append one evaluation to the serialized chain (see {@link evalChain}). */
 	scheduleEvaluation(subject, kind, logContext) {
 		this.evalChain = this.evalChain.then(async () => {
@@ -22660,6 +23102,17 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 	*  `notification-rules` provider (CRUD over the central store) is
 	*  registered from every node. */
 	notificationCenter = null;
+	/**
+	* The live alarm panel on THIS node, or null.
+	*
+	* Held, where the earlier note said not to. The objection then was a field
+	* nothing reads growing into a second source of truth for which device the
+	* alarm is — and it stands: the panel is still addressed by stable id
+	* everywhere else. This reference exists because two things now READ it, and
+	* neither can go through the device id: the settings tab, which needs the
+	* panel's own config, and the arm announcement, which the panel pushes.
+	*/
+	alarmPanelDevice = null;
 	/** THE single owner of capture pressure (S3, refactor spec 2026-07-22):
 	*  every native-fetch call site routed so far (the per-frame batch media
 	*  dispatch + `persistKeyFrames`; part B routes the rest) goes through ONE
@@ -22950,14 +23403,18 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 					return found === void 0 ? null : { id: found.id };
 				},
 				createDevice: async ({ stableId, integrationId, name }) => {
-					return { id: (await devices.create(stableId, NC_ALARM_DEVICE_CLASS, {}, null, {
+					const device = await devices.create(stableId, NC_ALARM_DEVICE_CLASS, {}, null, {
 						type: NC_ALARM_DEVICE_TYPE,
 						name,
 						integrationId
-					})).id };
+					});
+					this.holdAlarmPanel(device);
+					return { id: device.id };
 				},
 				adoptDevice: async ({ stableId }) => {
-					return { id: (await devices.create(stableId, NC_ALARM_DEVICE_CLASS, {}, null, void 0)).id };
+					const device = await devices.create(stableId, NC_ALARM_DEVICE_CLASS, {}, null, void 0);
+					this.holdAlarmPanel(device);
+					return { id: device.id };
 				}
 			});
 			if (result.created) this.ctx.logger.info("notification-center alarm panel ready", { tags: { deviceId: result.deviceId } });
@@ -22965,6 +23422,41 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 			this.ctx.logger.warn("alarm panel could not be ensured — rules still notify", { meta: { error: err instanceof Error ? err.message : String(err) } });
 		}
 	}
+	/**
+	* Keep the constructed panel, if that is what came back.
+	*
+	* An `instanceof` narrowing rather than a cast: `devices.create` promises an
+	* `IDevice`, and the only honest way to know it is the alarm is to ask. A
+	* cast here would compile against any future device class and fail at the
+	* first `settings()` call, in production, with the tab already open.
+	*/
+	holdAlarmPanel(device) {
+		if (!(device instanceof NcAlarmPanelDevice)) {
+			this.ctx.logger.warn("alarm panel is not the expected device class — settings tab disabled");
+			return;
+		}
+		this.alarmPanelDevice = device;
+	}
+	/**
+	* Join the panel and the Notification Center, once both exist.
+	*
+	* They are built in that order (`ensureAlarmPanel` runs before the centre is
+	* constructed) and neither can reach the other on its own, so the join is
+	* here. A node with no panel simply never calls it, and the cap answers
+	* `deviceId: null` — which is what an agent node should say.
+	*/
+	wireAlarmPanel(center) {
+		const panel = this.alarmPanelDevice;
+		if (panel === null) return;
+		center.setAlarmPanel({
+			deviceId: panel.id,
+			settings: () => panel.settings(),
+			applySettings: (patch) => panel.applySettings(patch),
+			availableModes: () => NC_ALARM_MODES
+		});
+		panel.setArmedHook((mode) => center.announceArm(mode));
+		this.ctx.logger.info("alarm panel wired to the notification center", { tags: { deviceId: panel.id } });
+	}
 	async declareCollections(api) {
 		await TrackStore.declare(api.settingsStore);
 		await MediaStore.declare(api.settingsStore);
@@ -23450,6 +23942,7 @@ var PipelineAnalyticsAddon = class extends BaseAddon {
 				})).tracks;
 			}
 		});
+		this.wireAlarmPanel(this.notificationCenter);
 		await this.serveNcActionPlane(this.notificationCenter);
 		await this.notificationCenter.start({ evaluation: this.isPostProcessingNode });
 	}