@camstack/addon-post-analysis 1.2.90 → 1.2.91

package/dist/pipeline-analytics/index.js

@@ -2,7 +2,7 @@ Object.defineProperties(exports, {
 	__esModule: { value: true },
 	[Symbol.toStringTag]: { value: "Module" }
 });
-const require_dist = require("../dist-BBIhkNDY.js");
+const require_dist = require("../dist-CTIUuGRB.js");
 let node_fs = require("node:fs");
 node_fs = require_dist.__toESM(node_fs, 1);
 let node_path = require("node:path");
@@ -7786,17 +7786,40 @@ function referencesAudioClass(classes) {
 	if (classes === void 0) return false;
 	return classes.some((c) => c.trim().toLowerCase().startsWith("audio-"));
 }
-function matchesSystemEvent(condition, subject) {
-	if (!condition.kinds.includes(subject.kind)) return false;
-	if (condition.deviceIds !== void 0 && (subject.deviceId === void 0 || !condition.deviceIds.includes(subject.deviceId))) return false;
-	if (condition.deviceTypes !== void 0 && (subject.deviceType === void 0 || !condition.deviceTypes.includes(subject.deviceType))) return false;
-	if (condition.nodeIds !== void 0) {
-		if (!subjectNodes(subject).some((id) => condition.nodeIds.includes(id))) return false;
+/**
+* Match one system subject against one rule's system-event condition.
+*
+* EVERY NARROWING FILTER IS SCOPED TO ITS KIND FAMILY, and the scoping is not
+* decided here: `systemEventFilterApplies` (in `@camstack/types`) is the one
+* statement of it, and both rule editors compute their filter visibility from
+* the same predicate. A filter outside a kind's family is IGNORED — never an
+* exclusion. It used to be an exclusion, and that made the operator's
+* eleven-kind rule with `deviceTypes: ['camera']` deliverable for exactly the
+* two kinds that carry a device type; the other nine failed closed and logged
+* nothing for four days.
+*
+* Inside its family a filter still narrows, and still fails CLOSED when the
+* subject cannot produce the identity it tests.
+*
+* Returns `undefined` on a match.
+*/
+function systemEventExclusion(condition, subject) {
+	if (!condition.kinds.includes(subject.kind)) return "kinds";
+	const applies = (filter) => require_dist.systemEventFilterApplies(subject.kind, filter);
+	if (condition.deviceIds !== void 0 && applies("deviceIds")) {
+		if (subject.deviceId === void 0 || !condition.deviceIds.includes(subject.deviceId)) return "deviceIds";
 	}
-	if (condition.packageNames !== void 0) {
-		if (!subjectPackages(subject).some((name) => condition.packageNames.includes(name))) return false;
+	if (condition.deviceTypes !== void 0 && applies("deviceTypes")) {
+		if (subject.deviceType === void 0 || !condition.deviceTypes.includes(subject.deviceType)) return "deviceTypes";
+	}
+	const wantedNodes = condition.nodeIds;
+	if (wantedNodes !== void 0 && applies("nodeIds")) {
+		if (!subjectNodes(subject).some((id) => wantedNodes.includes(id))) return "nodeIds";
+	}
+	const wantedPackages = condition.packageNames;
+	if (wantedPackages !== void 0 && applies("packageNames")) {
+		if (!subjectPackages(subject).some((name) => wantedPackages.includes(name))) return "packageNames";
 	}
-	return true;
 }
 function subjectNodes(subject) {
 	const ids = [...subject.nodeIds ?? []];
@@ -7812,7 +7835,14 @@ function evaluateRule(rule, subject, deviceState, zoneOwners, sceneStates) {
 	if (subject.kind === "system-event") {
 		if (rule.delivery !== "system-event") return fail("delivery");
 		const condition = rule.conditions.systemEvent;
-		if (condition === void 0 || subject.systemEvent === void 0 || !matchesSystemEvent(condition, subject.systemEvent)) return fail("systemEvent");
+		const systemEvent = subject.systemEvent;
+		if (condition === void 0 || systemEvent === void 0) return fail("systemEvent");
+		const excluded = systemEventExclusion(condition, systemEvent);
+		if (excluded !== void 0) return excluded === "kinds" ? fail("systemEvent") : {
+			matched: false,
+			failedCondition: "systemEvent",
+			excludedBySystemEventFilter: excluded
+		};
 		if (rule.conditions.occupancy !== void 0) return fail("occupancy");
 		if (rule.conditions.audio !== void 0) return fail("audio");
 	} else if (subject.kind === "occupancy-event") {
@@ -20060,6 +20090,39 @@ var NotificationCenter = class NotificationCenter {
 		if (identity.isCamera && identity.detectionActive === false) return "detection-off";
 	}
 	/**
+	* "Your rule covers this kind, and your own filter dropped it."
+	*
+	* INFO, not debug, and unconditional. The alternative is what shipped: a
+	* rule that selected eleven system-event kinds delivered two of them for
+	* four days, and the nine it silently refused produced no line anywhere —
+	* indistinguishable from an intake that had stopped emitting. The filter is
+	* NAMED, and so is the value that failed it, because the fix is always an
+	* edit to that one list.
+	*
+	* `tags.deviceId` carries the SUBJECT's numeric device id (the system
+	* subject's own `deviceId` is the sentinel {@link NC_SYSTEM_DEVICE_ID}), so
+	* "why is 617 louder than 2018?" is answerable by grouping. A node- or
+	* package-scoped exclusion is about no device and carries no tag.
+	*/
+	reportSystemFilterExclusion(rule, subject, filter) {
+		const system = subject.systemEvent;
+		if (system === void 0) return;
+		this.logger.info("system event excluded by a rule filter", {
+			...system.deviceId !== void 0 ? { tags: { deviceId: system.deviceId } } : {},
+			meta: {
+				ruleId: rule.id,
+				rule: rule.name,
+				kind: system.kind,
+				filter,
+				eventId: subject.recordId,
+				subject: system.subject,
+				...system.deviceType !== void 0 ? { deviceType: system.deviceType } : {},
+				...system.nodeId !== void 0 ? { nodeId: system.nodeId } : {},
+				...system.packageName !== void 0 ? { packageName: system.packageName } : {}
+			}
+		});
+	}
+	/**
 	* SAY that the scene gate suppressed this rule.
 	*
 	* A branch that drops work silently logs it — the three-hour media blackout
@@ -20479,6 +20542,7 @@ var NotificationCenter = class NotificationCenter {
 			const evaluation = evaluateRule(rule, subject, (id) => this.deviceStates.get(id), (id) => this.zoneOwners.get(id), (sceneId) => this.sceneStates.get(sceneId));
 			if (!evaluation.matched) {
 				if (evaluation.failedCondition === "scene") this.reportSceneSuppression(rule, subject);
+				if (evaluation.excludedBySystemEventFilter !== void 0) this.reportSystemFilterExclusion(rule, subject, evaluation.excludedBySystemEventFilter);
 				rejections.push(`${rule.name}:${evaluation.failedCondition ?? "unknown"}`);
 				outcomes.push({
 					ruleId: rule.id,
@@ -22379,7 +22443,7 @@ var ncActions = require_dist.defineCustomActions({
 	"nc.getArtifact": require_dist.customAction(require_dist.object({ artifactId: require_dist.string().min(1) }), require_dist.object({ artifact: NcArtifactRecordSchema.nullable() }), { caller: "required" })
 });
 /** Fail-closed caller resolution — an absent forwarded caller is NEVER admin. */
-function requireCaller(caller) {
+function requireCaller$1(caller) {
 	if (!caller || typeof caller.userId !== "string" || caller.userId.length === 0) throw new Error("forbidden: authenticated caller required");
 	return caller;
 }
@@ -22477,14 +22541,14 @@ function makeNcActionHandlers(deps) {
 	};
 	return {
 		"nc.listRules": async (_input, caller) => {
-			const c = requireCaller(caller);
+			const c = requireCaller$1(caller);
 			return { rules: (c.isAdmin ? deps.ruleStore.list() : deps.ruleStore.listForOwner(c.userId)).map((r) => ({
 				...r,
 				readOnly: !c.isAdmin && r.ownerUserId !== c.userId
 			})) };
 		},
 		"nc.listTrackGroups": async (input, caller) => {
-			requireCaller(caller);
+			requireCaller$1(caller);
 			const list = deps.listTrackGroups;
 			if (list === void 0) return { groups: [] };
 			return { groups: [...await list(input)] };
@@ -22494,7 +22558,7 @@ function makeNcActionHandlers(deps) {
 			taxonomy: require_dist.NC_TAXONOMY
 		}),
 		"nc.createRule": async (input, caller) => {
-			const c = requireCaller(caller);
+			const c = requireCaller$1(caller);
 			const parsed = require_dist.NcRuleInputSchema.parse(input.rule);
 			await assertTargetsOwned(parsed.targets.map((t) => t.targetId), c);
 			const rule = await deps.ruleStore.create({
@@ -22508,7 +22572,7 @@ function makeNcActionHandlers(deps) {
 			return { rule };
 		},
 		"nc.updateRule": async (input, caller) => {
-			const c = requireCaller(caller);
+			const c = requireCaller$1(caller);
 			assertRuleEditable(input.ruleId, c);
 			const patch = require_dist.NcRulePatchSchema.parse(input.patch);
 			if (patch.targets !== void 0) await assertTargetsOwned(patch.targets.map((t) => t.targetId), c);
@@ -22521,7 +22585,7 @@ function makeNcActionHandlers(deps) {
 			return { rule };
 		},
 		"nc.deleteRule": async (input, caller) => {
-			const c = requireCaller(caller);
+			const c = requireCaller$1(caller);
 			assertRuleEditable(input.ruleId, c);
 			await deps.ruleStore.delete(input.ruleId);
 			deps.logger.info("nc rule deleted", { meta: {
@@ -22531,11 +22595,11 @@ function makeNcActionHandlers(deps) {
 			return { success: true };
 		},
 		"nc.listSnoozes": async (_input, caller) => {
-			const c = requireCaller(caller);
+			const c = requireCaller$1(caller);
 			return { snoozes: [...deps.snooze.list(c.userId, c.isAdmin)] };
 		},
 		"nc.createSnooze": async (input, caller) => {
-			const c = requireCaller(caller);
+			const c = requireCaller$1(caller);
 			const parsed = require_dist.NcSnoozeInputSchema.parse(input.snooze);
 			if (parsed.ruleId !== void 0) assertRuleVisible(parsed.ruleId, c);
 			const snooze = await deps.snooze.create(parsed, c);
@@ -22548,12 +22612,12 @@ function makeNcActionHandlers(deps) {
 			return { snooze };
 		},
 		"nc.cancelSnooze": async (input, caller) => {
-			const c = requireCaller(caller);
+			const c = requireCaller$1(caller);
 			await deps.snooze.cancel(input.snoozeId, c);
 			return { success: true };
 		},
 		"nc.injectTestEvent": async (input, caller) => {
-			const c = requireCaller(caller);
+			const c = requireCaller$1(caller);
 			if (!c.isAdmin) throw new Error("forbidden: admin required to inject a test event");
 			const inject = deps.injectTestEvent;
 			if (inject === void 0) throw new Error("this node does not host the notification centre — inject on the hub");
@@ -22569,7 +22633,7 @@ function makeNcActionHandlers(deps) {
 			return inject(parsed);
 		},
 		"nc.testRule": async (input, caller) => {
-			const c = requireCaller(caller);
+			const c = requireCaller$1(caller);
 			if (!c.isAdmin) throw new Error("forbidden: admin required to test a rule");
 			const inject = deps.injectTestEvent;
 			if (inject === void 0) throw new Error("this node does not host the notification centre — test on the hub");
@@ -22601,7 +22665,7 @@ function makeNcActionHandlers(deps) {
 			};
 		},
 		"nc.getRuleStatus": async (input, caller) => {
-			const c = requireCaller(caller);
+			const c = requireCaller$1(caller);
 			const status = deps.ruleStatus;
 			if (status === void 0) throw new Error("this node does not host the notification centre — ask the hub");
 			const detection = deps.ruleStore.get(input.ruleId);
@@ -22617,7 +22681,7 @@ function makeNcActionHandlers(deps) {
 			throw new Error(`rule not found: ${input.ruleId}`);
 		},
 		"nc.listTimelapseRules": async (_input, caller) => {
-			const c = requireCaller(caller);
+			const c = requireCaller$1(caller);
 			const tl = requireTimelapse();
 			return { rules: (c.isAdmin ? tl.store.list() : tl.store.listForOwner(c.userId)).map((r) => ({
 				...r,
@@ -22625,7 +22689,7 @@ function makeNcActionHandlers(deps) {
 			})) };
 		},
 		"nc.upsertTimelapseRule": async (input, caller) => {
-			const c = requireCaller(caller);
+			const c = requireCaller$1(caller);
 			const tl = requireTimelapse();
 			if (input.ruleId === void 0) {
 				if (input.rule === void 0) throw new Error("upsertTimelapseRule: rule or ruleId required");
@@ -22661,7 +22725,7 @@ function makeNcActionHandlers(deps) {
 			return { rule };
 		},
 		"nc.deleteTimelapseRule": async (input, caller) => {
-			const c = requireCaller(caller);
+			const c = requireCaller$1(caller);
 			const tl = requireTimelapse();
 			assertTimelapseEditable(input.ruleId, c, tl);
 			await tl.store.delete(input.ruleId);
@@ -22672,7 +22736,7 @@ function makeNcActionHandlers(deps) {
 			return { success: true };
 		},
 		"nc.testTimelapseRule": async (input, caller) => {
-			const c = requireCaller(caller);
+			const c = requireCaller$1(caller);
 			if (!c.isAdmin) throw new Error("forbidden: admin required to produce a test timelapse");
 			const tl = requireTimelapse();
 			deps.logger.info("timelapse test requested", {
@@ -22699,14 +22763,14 @@ function makeNcActionHandlers(deps) {
 			};
 		},
 		"nc.setRuleTargetEnabled": async (input, caller) => {
-			const c = requireCaller(caller);
+			const c = requireCaller$1(caller);
 			assertRuleVisible(input.ruleId, c);
 			await assertTargetsOwned([input.targetId], c);
 			await deps.ruleStore.setRuleTargetEnabled(input.ruleId, input.targetId, input.enabled);
 			return { success: true };
 		},
 		"nc.listSummaryRules": async (_input, caller) => {
-			const c = requireCaller(caller);
+			const c = requireCaller$1(caller);
 			const sum = requireSummary();
 			return { rules: (c.isAdmin ? sum.store.list() : sum.store.listForOwner(c.userId)).map((r) => ({
 				...r,
@@ -22714,7 +22778,7 @@ function makeNcActionHandlers(deps) {
 			})) };
 		},
 		"nc.upsertSummaryRule": async (input, caller) => {
-			const c = requireCaller(caller);
+			const c = requireCaller$1(caller);
 			if (!c.isAdmin) throw new Error("forbidden: admin required to author a summary rule");
 			const sum = requireSummary();
 			if (input.ruleId === void 0) {
@@ -22747,7 +22811,7 @@ function makeNcActionHandlers(deps) {
 			return { rule };
 		},
 		"nc.deleteSummaryRule": async (input, caller) => {
-			const c = requireCaller(caller);
+			const c = requireCaller$1(caller);
 			if (!c.isAdmin) throw new Error("forbidden: admin required to delete a summary rule");
 			await requireSummary().store.delete(input.ruleId);
 			deps.logger.info("summary rule deleted", { meta: {
@@ -22757,7 +22821,7 @@ function makeNcActionHandlers(deps) {
 			return { success: true };
 		},
 		"nc.testSummaryRule": async (input, caller) => {
-			const c = requireCaller(caller);
+			const c = requireCaller$1(caller);
 			if (!c.isAdmin) throw new Error("forbidden: admin required to produce a test summary");
 			const sum = requireSummary();
 			const startMs = input.windowStartMs;
@@ -22804,7 +22868,7 @@ function makeNcActionHandlers(deps) {
 		"nc.setLanguage": async (input) => requireTexts().setLanguage(input.language),
 		"nc.setTextOverrides": async (input) => requireTexts().setOverrides(input.language, input.overrides),
 		"nc.listArtifacts": async (input, caller) => {
-			const c = requireCaller(caller);
+			const c = requireCaller$1(caller);
 			const page = await requireArtifacts().list(input, {
 				userId: c.userId,
 				isAdmin: c.isAdmin
@@ -22816,7 +22880,7 @@ function makeNcActionHandlers(deps) {
 			};
 		},
 		"nc.getArtifact": async (input, caller) => {
-			const c = requireCaller(caller);
+			const c = requireCaller$1(caller);
 			return { artifact: await requireArtifacts().get(input.artifactId, {
 				userId: c.userId,
 				isAdmin: c.isAdmin
@@ -24465,11 +24529,11 @@ var WipeResultSchema = require_dist.object({ deleted: require_dist.number() });
 * and can never be called: the bridge insists on `{}` and the schema rejects
 * it. Verified on the live hub, both directions.
 */
-var NoInputSchema = require_dist.object({});
+var NoInputSchema$1 = require_dist.object({});
 var embeddingActions = require_dist.defineCustomActions({
 	"embedding.rebuild": require_dist.customAction(RebuildInputSchema, RebuildStartedSchema, { auth: "admin" }),
-	"embedding.rebuildStatus": require_dist.customAction(NoInputSchema, RebuildStatusSchema),
-	"embedding.wipe": require_dist.customAction(NoInputSchema, WipeResultSchema, { auth: "admin" })
+	"embedding.rebuildStatus": require_dist.customAction(NoInputSchema$1, RebuildStatusSchema),
+	"embedding.wipe": require_dist.customAction(NoInputSchema$1, WipeResultSchema, { auth: "admin" })
 });
 //#endregion
 //#region src/pipeline-analytics/map-with-concurrency.ts
@@ -30008,6 +30072,220 @@ function createVideoclipsProvider(deps) {
 		}
 	};
 }
+//#endregion
+//#region src/pipeline-analytics/viewer-settings-actions.ts
+/**
+* Viewer settings snapshots — hub-shared named blobs of the viewer's stores.
+*
+* Rides `addons.custom` (`viewerSettings.*`) so it ships with an addon deploy
+* and does not wait on a cap/codegen/server image. Ownership is the
+* authenticated caller (`caller: 'required'`); snapshots are visible to every
+* hub user, overwrite/delete only of one's own.
+*/
+/**
+* @durable class=config owner=pipeline-analytics
+*   write="a signed-in viewer user saves a named snapshot of their local stores"
+*   retention="none — a row goes only when its owner deletes it"
+*/
+var VIEWER_SETTINGS_SNAPSHOTS_COLLECTION = "viewer-settings-snapshots";
+var COLUMNS = [
+	{
+		name: "id",
+		type: "TEXT",
+		primaryKey: true,
+		notNull: true
+	},
+	{
+		name: "name",
+		type: "TEXT",
+		notNull: true
+	},
+	{
+		name: "ownerUserId",
+		type: "TEXT",
+		notNull: true
+	},
+	{
+		name: "ownerUsername",
+		type: "TEXT",
+		notNull: true
+	},
+	{
+		name: "createdAt",
+		type: "INTEGER",
+		notNull: true
+	},
+	{
+		name: "updatedAt",
+		type: "INTEGER",
+		notNull: true
+	},
+	{
+		name: "blob",
+		type: "JSON",
+		notNull: true
+	}
+];
+var NameSchema = require_dist.string().trim().min(1).max(80);
+var BlobSchema = require_dist.record(require_dist.string(), require_dist.unknown());
+var ViewerSettingsSnapshotSummarySchema = require_dist.object({
+	id: require_dist.string(),
+	name: require_dist.string(),
+	ownerUserId: require_dist.string(),
+	ownerUsername: require_dist.string(),
+	createdAt: require_dist.number().int(),
+	updatedAt: require_dist.number().int(),
+	mine: require_dist.boolean()
+});
+var ViewerSettingsSnapshotSchema = ViewerSettingsSnapshotSummarySchema.extend({ blob: BlobSchema });
+var NoInputSchema = require_dist.object({});
+var viewerSettingsActions = require_dist.defineCustomActions({
+	"viewerSettings.list": require_dist.customAction(NoInputSchema, require_dist.object({ snapshots: require_dist.array(ViewerSettingsSnapshotSummarySchema) }), { caller: "required" }),
+	"viewerSettings.save": require_dist.customAction(require_dist.object({
+		name: NameSchema,
+		blob: BlobSchema,
+		ownerUsername: require_dist.string().min(1).max(80)
+	}), require_dist.object({ snapshot: ViewerSettingsSnapshotSummarySchema }), {
+		kind: "mutation",
+		caller: "required"
+	}),
+	"viewerSettings.get": require_dist.customAction(require_dist.object({ id: require_dist.string().min(1) }), require_dist.object({ snapshot: ViewerSettingsSnapshotSchema.nullable() }), { caller: "required" }),
+	"viewerSettings.delete": require_dist.customAction(require_dist.object({ id: require_dist.string().min(1) }), require_dist.object({ success: require_dist.literal(true) }), {
+		kind: "mutation",
+		caller: "required"
+	})
+});
+function requireCaller(caller) {
+	if (!caller) throw new Error("viewerSettings: authenticated caller required");
+	return caller;
+}
+function asRecord(data) {
+	return typeof data === "object" && data !== null ? data : {};
+}
+function toSummary(id, data, callerUserId) {
+	const parsed = ViewerSettingsSnapshotSummarySchema.omit({ mine: true }).safeParse({
+		id,
+		name: data.name,
+		ownerUserId: data.ownerUserId,
+		ownerUsername: data.ownerUsername,
+		createdAt: data.createdAt,
+		updatedAt: data.updatedAt
+	});
+	if (!parsed.success) return null;
+	return {
+		...parsed.data,
+		mine: parsed.data.ownerUserId === callerUserId
+	};
+}
+var ViewerSettingsSnapshotStore = class {
+	store;
+	constructor(store) {
+		this.store = store;
+	}
+	static async declare(store) {
+		await store.declareCollection.mutate({
+			collection: VIEWER_SETTINGS_SNAPSHOTS_COLLECTION,
+			columns: [...COLUMNS],
+			indexes: [{
+				name: "idx_viewer_settings_owner",
+				columns: ["ownerUserId"]
+			}]
+		});
+	}
+	async list(caller) {
+		const rows = await this.store.query.query({
+			collection: VIEWER_SETTINGS_SNAPSHOTS_COLLECTION,
+			filter: {
+				orderBy: {
+					field: "updatedAt",
+					direction: "desc"
+				},
+				limit: 200
+			}
+		});
+		const out = [];
+		for (const row of rows) {
+			const summary = toSummary(row.id, asRecord(row.data), caller.userId);
+			if (summary) out.push(summary);
+		}
+		return out;
+	}
+	async get(id, caller) {
+		const row = (await this.store.query.query({
+			collection: VIEWER_SETTINGS_SNAPSHOTS_COLLECTION,
+			filter: {
+				where: { id },
+				limit: 1
+			}
+		}))[0];
+		if (!row) return null;
+		const data = asRecord(row.data);
+		const summary = toSummary(row.id, data, caller.userId);
+		if (!summary) return null;
+		const blob = BlobSchema.safeParse(data.blob);
+		if (!blob.success) return null;
+		return {
+			...summary,
+			blob: blob.data
+		};
+	}
+	async save(input, caller) {
+		const now = Date.now();
+		const prior = (await this.store.query.query({
+			collection: VIEWER_SETTINGS_SNAPSHOTS_COLLECTION,
+			filter: {
+				where: {
+					ownerUserId: caller.userId,
+					name: input.name
+				},
+				limit: 1
+			}
+		}))[0];
+		const id = prior?.id ?? (0, node_crypto.randomUUID)();
+		const createdAt = typeof asRecord(prior?.data).createdAt === "number" ? asRecord(prior?.data).createdAt : now;
+		await this.store.set.mutate({
+			collection: VIEWER_SETTINGS_SNAPSHOTS_COLLECTION,
+			key: id,
+			value: {
+				name: input.name,
+				ownerUserId: caller.userId,
+				ownerUsername: input.ownerUsername,
+				createdAt,
+				updatedAt: now,
+				blob: input.blob
+			}
+		});
+		return {
+			id,
+			name: input.name,
+			ownerUserId: caller.userId,
+			ownerUsername: input.ownerUsername,
+			createdAt,
+			updatedAt: now,
+			mine: true
+		};
+	}
+	async delete(id, caller) {
+		const row = await this.get(id, caller);
+		if (!row) throw new Error("viewerSettings: snapshot not found");
+		if (row.ownerUserId !== caller.userId && !caller.isAdmin) throw new Error("viewerSettings: only the owner can delete this snapshot");
+		await this.store.delete.mutate({
+			collection: VIEWER_SETTINGS_SNAPSHOTS_COLLECTION,
+			key: id
+		});
+	}
+};
+function makeViewerSettingsActionHandlers(store) {
+	return {
+		"viewerSettings.list": async (_input, caller) => ({ snapshots: await store.list(requireCaller(caller)) }),
+		"viewerSettings.save": async (input, caller) => ({ snapshot: await store.save(input, requireCaller(caller)) }),
+		"viewerSettings.get": async (input, caller) => ({ snapshot: await store.get(input.id, requireCaller(caller)) }),
+		"viewerSettings.delete": async (input, caller) => {
+			await store.delete(input.id, requireCaller(caller));
+			return { success: true };
+		}
+	};
+}
 /**
 * The VIDEO's playback rate — 4×, the same as {@link NC_GIF_SPEED}.
 *
@@ -30814,7 +31092,15 @@ var AudioDetectionSettingsSchema = require_dist.object({
 	/** Flood ceiling: markers per camera per rolling 24 h. This, not the
 	*  thresholds, is what bounds the worst case — a mis-tuned threshold can
 	*  only ever cost the operator this many markers a day. */
-	audioMarkerMaxPerDay: require_dist.number().int().positive().default(12)
+	audioMarkerMaxPerDay: require_dist.number().int().positive().default(12),
+	/** Materialize one event + one synthetic track per classified episode. */
+	audioEpisodeEnabled: require_dist.boolean().default(true),
+	/** Class must be heard continuously this long before the episode opens. */
+	audioEpisodeOpenHoldSec: require_dist.number().nonnegative().default(1.5),
+	/** Class must be absent this long before the episode closes. */
+	audioEpisodeCloseGapSec: require_dist.number().positive().default(12),
+	/** After close, the same class cannot reopen until this elapses. */
+	audioEpisodeCooldownSec: require_dist.number().nonnegative().default(30)
 });
 var AUDIO_DETECTION_DEFAULTS = AudioDetectionSettingsSchema.parse({});
 /**
@@ -30838,6 +31124,159 @@ function resolveAudioDetectionSettings(raw) {
 	return resolved.success ? resolved.data : AUDIO_DETECTION_DEFAULTS;
 }
 //#endregion
+//#region src/pipeline-analytics/audio-episode-hysteresis.ts
+var EMPTY = {
+	pendingClass: null,
+	pendingSinceMs: 0,
+	openClass: null,
+	episodeId: null,
+	lastHeardMs: 0,
+	lastClosedClass: null,
+	lastClosedMs: 0
+};
+function emptyAudioEpisodeState() {
+	return EMPTY;
+}
+function episodeIdFor(className, timestampMs) {
+	return `${className}:${timestampMs}`;
+}
+function inCooldown(state, className, timestampMs, knobs) {
+	return state.lastClosedClass === className && timestampMs - state.lastClosedMs < knobs.cooldownMs;
+}
+function closedState(className, atMs) {
+	return {
+		...EMPTY,
+		lastClosedClass: className,
+		lastClosedMs: atMs
+	};
+}
+function observeAudioEpisode(state, sample, knobs) {
+	if (!knobs.enabled) return {
+		nextState: EMPTY,
+		action: { kind: "none" }
+	};
+	const { timestampMs, className } = sample;
+	const openClass = state.openClass;
+	const openId = state.episodeId;
+	if (openClass !== null && openId !== null) {
+		if (className === openClass) return {
+			nextState: {
+				...state,
+				pendingClass: null,
+				pendingSinceMs: 0,
+				lastHeardMs: timestampMs
+			},
+			action: {
+				kind: "hold",
+				className: openClass,
+				episodeId: openId
+			}
+		};
+		if (className === null) {
+			if (timestampMs - state.lastHeardMs < knobs.closeGapMs) return {
+				nextState: state,
+				action: { kind: "none" }
+			};
+			return {
+				nextState: closedState(openClass, timestampMs),
+				action: {
+					kind: "close",
+					className: openClass,
+					episodeId: openId
+				}
+			};
+		}
+		if (inCooldown(state, className, timestampMs, knobs)) return {
+			nextState: state,
+			action: { kind: "none" }
+		};
+		const pendingSince = state.pendingClass === className ? state.pendingSinceMs : timestampMs;
+		if (knobs.openHoldMs === 0 || state.pendingClass === className && timestampMs - pendingSince >= knobs.openHoldMs) {
+			const openedId = episodeIdFor(className, timestampMs);
+			return {
+				nextState: {
+					pendingClass: null,
+					pendingSinceMs: 0,
+					openClass: className,
+					episodeId: openedId,
+					lastHeardMs: timestampMs,
+					lastClosedClass: openClass,
+					lastClosedMs: timestampMs
+				},
+				action: {
+					kind: "replace",
+					closed: {
+						className: openClass,
+						episodeId: openId
+					},
+					opened: {
+						className,
+						episodeId: openedId
+					}
+				}
+			};
+		}
+		return {
+			nextState: {
+				...state,
+				pendingClass: className,
+				pendingSinceMs: pendingSince
+			},
+			action: { kind: "none" }
+		};
+	}
+	if (className === null) {
+		if (state.pendingClass === null) return {
+			nextState: state,
+			action: { kind: "none" }
+		};
+		return {
+			nextState: {
+				...state,
+				pendingClass: null,
+				pendingSinceMs: 0
+			},
+			action: { kind: "none" }
+		};
+	}
+	if (inCooldown(state, className, timestampMs, knobs)) return {
+		nextState: state,
+		action: { kind: "none" }
+	};
+	const pendingSince = state.pendingClass === className ? state.pendingSinceMs : timestampMs;
+	if (knobs.openHoldMs === 0 || state.pendingClass === className && timestampMs - pendingSince >= knobs.openHoldMs) {
+		const episodeId = episodeIdFor(className, timestampMs);
+		return {
+			nextState: {
+				pendingClass: null,
+				pendingSinceMs: 0,
+				openClass: className,
+				episodeId,
+				lastHeardMs: timestampMs,
+				lastClosedClass: state.lastClosedClass,
+				lastClosedMs: state.lastClosedMs
+			},
+			action: {
+				kind: "open",
+				className,
+				episodeId
+			}
+		};
+	}
+	if (state.pendingClass === className) return {
+		nextState: state,
+		action: { kind: "none" }
+	};
+	return {
+		nextState: {
+			...state,
+			pendingClass: className,
+			pendingSinceMs: timestampMs
+		},
+		action: { kind: "none" }
+	};
+}
+//#endregion
 //#region src/pipeline-analytics/audio-event-router.ts
 /**
 * Decide whether an audio frame is a (meaningful) classification event or a
@@ -48402,6 +48841,51 @@ function buildGlobalSettingsSchema() {
 				}
 			]
 		},
+		{
+			id: "audio-episodes",
+			title: "Audio episodes",
+			description: "One timeline track and one event per classified sound, held open with hysteresis so a long cry is not four tracks. No class filter: speech, crying, a bark — the knobs below are what stop repeats. Leave on for a day or two and judge the spam, then tighten per camera.",
+			columns: 2,
+			fields: [
+				{
+					type: "boolean",
+					key: "audioEpisodeEnabled",
+					label: "Create audio episodes",
+					description: "When off, classified audio still notifies from other paths but does not open a synthetic track or coalesce classification events.",
+					default: AUDIO_DETECTION_DEFAULTS.audioEpisodeEnabled
+				},
+				{
+					type: "number",
+					key: "audioEpisodeOpenHoldSec",
+					label: "Open hold",
+					description: "The class must be heard continuously this long before an episode opens. Filters 200 ms blips.",
+					min: 0,
+					step: .5,
+					default: AUDIO_DETECTION_DEFAULTS.audioEpisodeOpenHoldSec,
+					unit: "s"
+				},
+				{
+					type: "number",
+					key: "audioEpisodeCloseGapSec",
+					label: "Close gap",
+					description: "The class must be absent this long before the episode closes. A pause inside a cry does not start a second track.",
+					min: 1,
+					step: 1,
+					default: AUDIO_DETECTION_DEFAULTS.audioEpisodeCloseGapSec,
+					unit: "s"
+				},
+				{
+					type: "number",
+					key: "audioEpisodeCooldownSec",
+					label: "Cooldown",
+					description: "After an episode closes, the same class cannot reopen until this elapses.",
+					min: 0,
+					step: 5,
+					default: AUDIO_DETECTION_DEFAULTS.audioEpisodeCooldownSec,
+					unit: "s"
+				}
+			]
+		},
 		{
 			id: "face-recognition",
 			title: "Face recognition",
@@ -49887,7 +50371,8 @@ var customActions = {
 	...ncActions,
 	...embeddingActions,
 	...debugActions,
-	...orphanAuditActions
+	...orphanAuditActions,
+	...viewerSettingsActions
 };
 /**
 * Assist threshold when the caller does not pin one. Packages have their own
@@ -49989,7 +50474,12 @@ var LTS_FLUSH_INTERVAL_MS = 6e4;
 var OPS_LOG_RETENTION_MS = 720 * 60 * 6e4;
 /** Throttle for the "overlay synthesis failed" warn — one line / minute / device. */
 var OVERLAY_SYNTHESIS_WARN_THROTTLE_MS = 6e4;
-var AUDIO_EVENT_HEARTBEAT_MS = 5e3;
+/** How recently a spatial track must have been alive to count as "visual
+*  happening" — stamp audio labels on that track instead of opening a
+*  synthetic audio episode. */
+var AUDIO_EPISODE_VISUAL_QUIET_MS = 2e3;
+/** Persist lastSeen on an open synthetic audio track at most this often. */
+var AUDIO_EPISODE_PERSIST_MS = 2e3;
 var MOTION_EVENT_HEARTBEAT_MS = 5e3;
 /**
 * Stored media kinds that carry NO drawn bounding box, in fallback preference
@@ -50461,6 +50951,11 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 	* fallible read on the decision path.
 	*/
 	lastTrackActivityMs = /* @__PURE__ */ new Map();
+	/** Per-device classified-audio episode hysteresis. */
+	audioEpisodeByDevice = /* @__PURE__ */ new Map();
+	/** Open synthetic tracks keyed by hysteresis episodeId. */
+	audioEpisodeTracks = /* @__PURE__ */ new Map();
+	audioEpisodeLastPersistMs = /* @__PURE__ */ new Map();
 	settingsCaches = new DeviceSettingsCacheHub();
 	/** Avoids a store read every ~30 Hz audio frame. */
 	audioSettingsCache = this.settingsCaches.registerDeviceCache("audio-detection", SETTINGS_CACHE_TTL_MS);
@@ -50744,6 +51239,7 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 	*  NAME — its scope list is derived from the classification registry, not
 	*  from a set of store instances. */
 	settingsStore = null;
+	viewerSettingsSnapshots = null;
 	/** Per-scope resume cursors, so a run interrupted by a restart costs one
 	*  page rather than a full rescan. In RAM: losing them costs a rescan, and
 	*  persisting them would be a durable record of a purely advisory position. */
@@ -50881,12 +51377,14 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 					...ncActions,
 					...embeddingActions,
 					...debugActions,
-					...orphanAuditActions
+					...orphanAuditActions,
+					...viewerSettingsActions
 				},
 				actionHandlers: {
 					...ncHandlers,
 					...this.buildEmbeddingActionHandlers(),
-					...this.buildDebugActionHandlers()
+					...this.buildDebugActionHandlers(),
+					...this.viewerSettingsSnapshots ? makeViewerSettingsActionHandlers(this.viewerSettingsSnapshots) : {}
 				}
 			} : {}
 		};
@@ -51061,8 +51559,10 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 			OpsLogStore.declare(api.settingsStore),
 			AnalyticsLts.declare(api.settingsStore),
 			SceneStore.declare(api.settingsStore),
-			NotificationCenter.declare(api.settingsStore)
+			NotificationCenter.declare(api.settingsStore),
+			ViewerSettingsSnapshotStore.declare(api.settingsStore)
 		]);
+		this.viewerSettingsSnapshots = new ViewerSettingsSnapshotStore(api.settingsStore);
 		runLabelTierMigration({
 			store: api.settingsStore,
 			logger: this.ctx.logger,
@@ -52322,6 +52822,11 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 		this.forgetDeviceProcessors(deviceId);
 		this.levelStateByDevice.delete(deviceId);
 		this.lastTrackActivityMs.delete(deviceId);
+		this.audioEpisodeByDevice.delete(deviceId);
+		for (const [episodeId, track] of this.audioEpisodeTracks) if (track.deviceId === deviceId) {
+			this.audioEpisodeTracks.delete(episodeId);
+			this.audioEpisodeLastPersistMs.delete(episodeId);
+		}
 		this.audioMarkers?.forgetDevice(deviceId);
 		this.settingsCaches.clearDevice(deviceId);
 		this.bindingCache?.invalidate(deviceId);
@@ -54218,6 +54723,146 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 			maxPerDay: settings.audioMarkerMaxPerDay
 		};
 	}
+	audioEpisodeKnobs(settings) {
+		return {
+			enabled: settings.audioEpisodeEnabled,
+			openHoldMs: settings.audioEpisodeOpenHoldSec * 1e3,
+			closeGapMs: settings.audioEpisodeCloseGapSec * 1e3,
+			cooldownMs: settings.audioEpisodeCooldownSec * 1e3
+		};
+	}
+	hasLiveVisualTrack(deviceId, atMs) {
+		const at = this.lastTrackActivityMs.get(deviceId);
+		return at !== void 0 && atMs - at < AUDIO_EPISODE_VISUAL_QUIET_MS;
+	}
+	async driveAudioEpisode(input) {
+		const { nextState, action } = observeAudioEpisode(this.audioEpisodeByDevice.get(input.deviceId) ?? emptyAudioEpisodeState(), {
+			timestampMs: input.timestamp,
+			className: input.className
+		}, input.knobs);
+		this.audioEpisodeByDevice.set(input.deviceId, nextState);
+		switch (action.kind) {
+			case "none": return;
+			case "open":
+				await this.openAudioEpisode(input, action);
+				return;
+			case "hold":
+				await this.holdAudioEpisode(input, action);
+				return;
+			case "close":
+				await this.persistAudioEpisodeLastSeen(action, input.timestamp, true);
+				return;
+			case "replace":
+				await this.persistAudioEpisodeLastSeen(action.closed, input.timestamp, true);
+				await this.openAudioEpisode(input, action.opened);
+				return;
+		}
+	}
+	async openAudioEpisode(input, ref) {
+		const ev = {
+			id: (0, node_crypto.randomUUID)(),
+			deviceId: input.deviceId,
+			timestamp: input.timestamp,
+			kind: "audio",
+			rms: input.rms,
+			dbfs: input.dbfs,
+			classification: {
+				className: ref.className,
+				...input.originalClass !== void 0 ? { originalClass: input.originalClass } : {},
+				score: input.score
+			}
+		};
+		this.lastAudioInsertByDevice.set(input.deviceId, {
+			className: ref.className,
+			atMs: input.timestamp
+		});
+		await this.eventStore.insertAudio(ev);
+		this.notificationCenter?.onAudioEventPersisted(ev);
+		this.trackStore?.addAudioLabelEpisode(input.deviceId, ref.className, input.score, input.timestamp);
+		this.ctx.eventBus.emit({
+			id: `pa-${ev.id}`,
+			timestamp: new Date(ev.timestamp),
+			source: {
+				type: "addon",
+				id: "pipeline-analytics",
+				addonId: "pipeline-analytics"
+			},
+			category: require_dist.EventCategory.PipelineAnalyticsDetectionEvent,
+			data: {
+				deviceId: input.deviceId,
+				kind: "audio",
+				eventId: ev.id,
+				timestamp: ev.timestamp
+			}
+		});
+		if (this.hasLiveVisualTrack(input.deviceId, input.timestamp)) return;
+		const materializer = this.syntheticTracks;
+		if (materializer === null) return;
+		try {
+			const track = await materializer.materialize({
+				cameraId: input.deviceId,
+				sourceDeviceId: input.deviceId,
+				source: "audio",
+				kind: ref.className,
+				timestamp: input.timestamp,
+				audioLabels: [{
+					label: ref.className,
+					peakScore: input.score,
+					count: 1,
+					firstAt: input.timestamp,
+					lastAt: input.timestamp
+				}]
+			});
+			if (track) {
+				this.audioEpisodeTracks.set(ref.episodeId, track);
+				this.audioEpisodeLastPersistMs.set(ref.episodeId, input.timestamp);
+			}
+		} catch (err) {
+			this.ctx.logger.warn("audio-episode synthetic track failed", {
+				tags: { deviceId: input.deviceId },
+				meta: {
+					className: ref.className,
+					error: require_dist.errMsg(err)
+				}
+			});
+		}
+	}
+	async holdAudioEpisode(input, ref) {
+		await this.persistAudioEpisodeLastSeen(ref, input.timestamp, false);
+	}
+	async persistAudioEpisodeLastSeen(ref, timestamp, force) {
+		const track = this.audioEpisodeTracks.get(ref.episodeId);
+		if (!track) {
+			if (force) {
+				this.audioEpisodeTracks.delete(ref.episodeId);
+				this.audioEpisodeLastPersistMs.delete(ref.episodeId);
+			}
+			return;
+		}
+		const last = this.audioEpisodeLastPersistMs.get(ref.episodeId) ?? 0;
+		if (!force && timestamp - last < AUDIO_EPISODE_PERSIST_MS) return;
+		const updated = {
+			...track,
+			lastSeen: timestamp
+		};
+		this.audioEpisodeTracks.set(ref.episodeId, updated);
+		this.audioEpisodeLastPersistMs.set(ref.episodeId, timestamp);
+		try {
+			await this.trackStore?.persistSyntheticTrack(updated);
+		} catch (err) {
+			this.ctx.logger.warn("audio-episode lastSeen persist failed", {
+				tags: { deviceId: track.deviceId },
+				meta: {
+					episodeId: ref.episodeId,
+					error: require_dist.errMsg(err)
+				}
+			});
+		}
+		if (force) {
+			this.audioEpisodeTracks.delete(ref.episodeId);
+			this.audioEpisodeLastPersistMs.delete(ref.episodeId);
+		}
+	}
 	async handleAudioResult(data) {
 		if (this.shuttingDown) return;
 		const { deviceId, frame } = data;
@@ -54261,48 +54906,27 @@ var PipelineAnalyticsAddon = class extends require_dist.BaseAddon {
 				});
 				return;
 			}
-			const last = this.lastAudioInsertByDevice.get(deviceId);
-			const sameClass = last?.className === route.className;
-			const heartbeatDue = !last || timestamp - last.atMs >= AUDIO_EVENT_HEARTBEAT_MS;
-			if (sameClass && !heartbeatDue) return;
-			const ev = {
-				id: (0, node_crypto.randomUUID)(),
+			await this.driveAudioEpisode({
 				deviceId,
 				timestamp,
-				kind: "audio",
+				className: route.className,
+				score: topClassification.score,
+				originalClass: topClassification.debug?.originalClass,
 				rms: level?.rms ?? 0,
 				dbfs: level?.dbfs ?? 0,
-				classification: {
-					className: topClassification.macroClass,
-					...topClassification.debug?.originalClass !== void 0 ? { originalClass: topClassification.debug.originalClass } : {},
-					score: topClassification.score
-				}
-			};
-			this.lastAudioInsertByDevice.set(deviceId, {
-				className: route.className,
-				atMs: timestamp
-			});
-			await this.eventStore.insertAudio(ev);
-			this.notificationCenter?.onAudioEventPersisted(ev);
-			this.trackStore?.addAudioLabelEpisode(deviceId, route.className, topClassification.score, timestamp);
-			this.ctx.eventBus.emit({
-				id: `pa-${ev.id}`,
-				timestamp: new Date(ev.timestamp),
-				source: {
-					type: "addon",
-					id: "pipeline-analytics",
-					addonId: "pipeline-analytics"
-				},
-				category: require_dist.EventCategory.PipelineAnalyticsDetectionEvent,
-				data: {
-					deviceId,
-					kind: "audio",
-					eventId: ev.id,
-					timestamp: ev.timestamp
-				}
+				knobs: this.audioEpisodeKnobs(settings)
 			});
 			return;
 		}
+		await this.driveAudioEpisode({
+			deviceId,
+			timestamp,
+			className: null,
+			score: 0,
+			rms: level?.rms ?? 0,
+			dbfs: level?.dbfs ?? 0,
+			knobs: this.audioEpisodeKnobs(settings)
+		});
 		const res = observeLevel(this.levelStateByDevice.get(deviceId) ?? emptyLevelState(), {
 			timestampMs: timestamp,
 			dbfs: level?.dbfs ?? -Infinity