@camstack/addon-post-analysis 1.2.118 → 1.2.120

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-CO6pe7bi.js");
+const require_dist = require("../dist-jHCxxZ2_.js");
 let node_fs = require("node:fs");
 node_fs = require_dist.__toESM(node_fs, 1);
 let node_path = require("node:path");
@@ -4398,10 +4398,28 @@ var SCENE_LATCH_INDEXES = [{
 function sceneKey(deviceId, monitorId) {
 	return `${deviceId}:${monitorId}`;
 }
+/**
+* Reseed cap for BOTH scene ledgers.
+*
+* `DurableLedger` defaults to 100_000 and its own docblock says the owner "sets
+* it from the row set it expects". Neither scene ledger did, so the 30s
+* reconcile asked SQLite — through hub-main's event loop, which is the
+* cluster's only queue (D181) — for up to a hundred thousand rows twice a tick,
+* on a hub holding one scene and one latch (measured live 2026-08-25). A bound
+* nobody chose is not a bound.
+*
+* A scene is an operator-drawn monitor on ONE camera and a latch is at most one
+* row per scene, so the row set is `cameras x monitors-per-camera`. 5_000 is
+* ~5 monitors on each of a thousand cameras — far past any installation this
+* ships to, and still small enough that a runaway write loop is CAUGHT by the
+* bound instead of being paged in whole.
+*/
+var SCENE_LEDGER_LOAD_LIMIT = 5e3;
 var SCENE_CONFIG_SPEC = {
 	collection: SCENE_COLLECTION,
 	columns: SCENE_COLUMNS,
 	indexes: SCENE_INDEXES,
+	loadLimit: SCENE_LEDGER_LOAD_LIMIT,
 	writeMode: "write-behind",
 	keyOf: (row) => row.key,
 	toValue: (row) => ({
@@ -4417,6 +4435,7 @@ var SCENE_LATCH_SPEC = {
 	collection: SCENE_LATCH_COLLECTION,
 	columns: SCENE_LATCH_COLUMNS,
 	indexes: SCENE_LATCH_INDEXES,
+	loadLimit: SCENE_LEDGER_LOAD_LIMIT,
 	writeMode: "write-through",
 	keyOf: (row) => row.key,
 	toValue: (row) => ({
@@ -4446,6 +4465,9 @@ var SceneStore = class {
 	config;
 	latch;
 	logger;
+	/** `scenes/latches` as last announced. Null until the first load, so the
+	*  first one always speaks. */
+	lastLoggedCounts = null;
 	constructor(deps) {
 		this.logger = deps.logger;
 		this.config = new DurableLedger({
@@ -4470,10 +4492,20 @@ var SceneStore = class {
 	* a container recreate, "loaded 0" is the one line that explains why every
 	* scene suddenly reads `unknown`, and its absence is what turns a data loss
 	* into a three-hour hunt.
+	*
+	* ON CHANGE ONLY, though — including the first load, where there is nothing
+	* to compare against. This runs on the 30s `SCENE_RELOAD_INTERVAL_MS` tick on
+	* every node, and it used to print unconditionally: measured live 2026-08-25,
+	* `scene state loaded {scenes=1 latches=1}` every 30 seconds forever. A count
+	* reprinted unchanged twice a minute is exactly how the "loaded 0" this line
+	* exists for gets scrolled past.
 	*/
 	async load() {
 		const scenes = await this.config.load();
 		const latches = await this.latch.load();
+		const counts = `${scenes.length}/${latches.length}`;
+		if (counts === this.lastLoggedCounts) return;
+		this.lastLoggedCounts = counts;
 		this.logger.info("scene state loaded", { meta: {
 			scenes: scenes.length,
 			latches: latches.length
@@ -8539,6 +8571,49 @@ var NC_LANGUAGES = ["en", "it"];
 *  surface's view all validate against this one, so a third language is added
 *  to `NC_LANGUAGES` and nowhere else. */
 var NcLanguageSchema = require_dist._enum(NC_LANGUAGES);
+/**
+* Whether two snapshots say the same thing.
+*
+* ## Why this is a function and not `===`
+*
+* The reload guard in `reloadTexts()` used to be
+* `before.overrides === next.overrides`, and `next` comes from
+* `NcTextCatalogStore.load()`, which `parse()`s the row through zod on every
+* call. The right-hand side is therefore a NEW object on every tick by
+* construction: the comparison was `false` at byte-identical content, forever.
+* Measured on the live hub 2026-08-25: 58 "notification texts loaded" lines in
+* 30 minutes on a hub whose language had not changed, from a line whose own
+* docblock promises it fires on CHANGE only.
+*
+* The document is two levels deep and installation-small (at most one entry per
+* language, each a flat key→string map), so the comparison is written out
+* rather than reached for through a deep-equal dependency — and written out it
+* can state the direction that matters: a REMOVED key must not read as equal,
+* which a one-directional key walk would get wrong.
+*/
+function ncTextSnapshotsEqual(a, b) {
+	if (a.language !== b.language) return false;
+	return overrideMapsEqual(a.overrides, b.overrides);
+}
+function overrideMapsEqual(a, b) {
+	const languages = new Set([...Object.keys(a), ...Object.keys(b)]);
+	for (const language of languages) {
+		const left = a[language];
+		const right = b[language];
+		if (left === void 0 || right === void 0) {
+			if (Object.keys(left ?? right ?? {}).length > 0) return false;
+			continue;
+		}
+		if (!flatMapsEqual(left, right)) return false;
+	}
+	return true;
+}
+function flatMapsEqual(a, b) {
+	const keys = Object.keys(a);
+	if (keys.length !== Object.keys(b).length) return false;
+	for (const key of keys) if (a[key] !== b[key]) return false;
+	return true;
+}
 /** The shipped files, keyed by language. Data, never mutated. */
 var NC_TEXT_BUNDLES = {
 	en: en_default,
@@ -22484,7 +22559,7 @@ var NotificationCenter = class NotificationCenter {
 		const before = this.texts.snapshot;
 		const next = await this.textStore.load();
 		this.texts.apply(next);
-		if (before.language === next.language && before.overrides === next.overrides) return;
+		if (ncTextSnapshotsEqual(before, next)) return;
 		this.logger.info("notification texts loaded", { meta: {
 			language: next.language,
 			overriddenKeys: Object.values(next.overrides).reduce((sum, keys) => sum + Object.keys(keys ?? {}).length, 0)
@@ -35459,6 +35534,18 @@ var EmbeddingDispatcher = class {
 	logger;
 	getRemoteFrame;
 	lastEmbedTime = /* @__PURE__ */ new Map();
+	/**
+	* trackId -> the frame pinned for it. Each entry holds a WHOLE decoded RGB
+	* frame (`PendingCrop.frameData`, ~0.7 MB), not a crop.
+	*
+	* Under the shipped `cropStrategy: 'first'` this doubles as the in-flight
+	* DEDUPE FLAG — `'first'` gates on `!pendingCrops.has(trackId)` — and there
+	* is no flush timer for that strategy, so nothing ever sweeps it. Until
+	* 2026-08-25 the delete lived on `processOne`'s success path only: an
+	* `extractCrop` throw or an `encoder.encode` rejection (a cross-process cap
+	* over UDS, with no timeout) stranded the frame permanently AND made that
+	* trackId un-embeddable forever. `processOne` now releases in a `finally`.
+	*/
 	pendingCrops = /* @__PURE__ */ new Map();
 	flushTimer = null;
 	unsubscribe = null;
@@ -35616,7 +35703,6 @@ var EmbeddingDispatcher = class {
 			this._processedCount++;
 			this._totalInferenceMs += inferenceMs;
 			this.lastEmbedTime.set(pending.deviceId, Date.now());
-			this.pendingCrops.delete(pending.trackId);
 			const embeddingId = `${pending.deviceId}/${pending.trackId}/${Date.now()}`;
 			const payload = {
 				deviceId: Number(pending.deviceId),
@@ -35648,8 +35734,21 @@ var EmbeddingDispatcher = class {
 					error: String(err)
 				}
 			});
+		} finally {
+			if (this.pendingCrops.get(pending.trackId) === pending) this.pendingCrops.delete(pending.trackId);
 		}
 	}
+	/**
+	* Decoded frames currently pinned in {@link pendingCrops}.
+	*
+	* ~0.7 MB each (a whole RGB detection frame, not a crop), so this number IS
+	* the dispatcher's memory footprint. Exposed because the entries are
+	* invisible in every functional read: a stranded one looks exactly like a
+	* track that was never detected.
+	*/
+	pendingFrameCount() {
+		return this.pendingCrops.size;
+	}
 };
 /**
 * Re-embed every listed track from its key frame.
@@ -51407,10 +51506,16 @@ var BindingCache = class {
 * `confirm` (S4) is the confirmation-gate re-detect crop: it GATES track birth
 * (the frame path awaits it), so it ranks WITH `firstFrame` at 0 — it must
 * jump every queued lower-priority capture and its call site never sets a
-* `staleAfterMs` (a late confirmation still confirms; a dropped one would
-* fail-open a birth the operator asked to be gated). `face`/`plate` (S4) are
+* `staleAfterMs` (a late confirmation still confirms). `face`/`plate` (S4) are
 * enrichment gallery crops — same rank as `embed`: nice-to-have media that
 * must never displace the track-media ladder above.
+*
+* The admission cap sheds from the TAIL, so a `confirm` can only be shed when
+* every queued entry is priority 0 — and even then the outcome is safe rather
+* than fail-open: `fetchCrop` resolving `null` makes `evaluateBirth` return
+* `undecided(candidate, 'no-crop')`, which is a birth NOT confirmed. This note
+* used to say a dropped confirm would fail open; it does not, and that is what
+* makes shedding admissible at all.
 */
 var DEFAULT_CAPTURE_PRIORITY = {
 	firstFrame: 0,
@@ -51444,9 +51549,14 @@ function deriveFrameDispatchKind(content) {
 }
 var DEFAULT_MAX_IN_FLIGHT_PER_DEVICE = 3;
 var DEFAULT_LOG_WINDOW_MS = 6e4;
+/** One `capture queue full` line per device per this interval. The condition
+*  holds for as long as the lane is saturated; one line per shed request would
+*  be thousands. */
+var OVERFLOW_WARN_THROTTLE_MS = 6e4;
 var CaptureScheduler = class {
 	logger;
 	budget;
+	maxQueued;
 	windowMs;
 	now;
 	lanes = /* @__PURE__ */ new Map();
@@ -51455,9 +51565,12 @@ var CaptureScheduler = class {
 	/** holdKey → refcount of queued/running requests holding it. */
 	heldKeys = /* @__PURE__ */ new Map();
 	windows = /* @__PURE__ */ new Map();
+	/** Per-device throttle for the `capture queue full` warn. */
+	lastOverflowWarnAt = /* @__PURE__ */ new Map();
 	constructor(options) {
 		this.logger = options.logger;
 		this.budget = options.maxInFlightPerDevice ?? DEFAULT_MAX_IN_FLIGHT_PER_DEVICE;
+		this.maxQueued = Math.max(1, options.maxQueuedPerDevice ?? 24);
 		this.windowMs = options.logWindowMs ?? DEFAULT_LOG_WINDOW_MS;
 		this.now = options.now ?? Date.now;
 	}
@@ -51527,6 +51640,7 @@ var CaptureScheduler = class {
 			failed: w.failed,
 			coalesced: w.coalesced,
 			droppedStale: w.droppedStale,
+			droppedOverflow: w.droppedOverflow,
 			cancelled: w.cancelled,
 			maxQueueDepth: w.maxQueueDepth
 		};
@@ -51575,7 +51689,37 @@ var CaptureScheduler = class {
 			throw err;
 		});
 	}
-	/** Queue an over-budget request (priority-ordered, FIFO within priority). */
+	/**
+	* Queue an over-budget request (priority-ordered, FIFO within priority),
+	* under a BOUND enforced here rather than at dequeue.
+	*
+	* ## Why the queue needs its own bound
+	*
+	* `staleAfterMs` is evaluated in {@link pump}, and `pump` only touches the
+	* queue while `inFlight < budget`. A lane that stays saturated therefore
+	* never inspects its queue at all — nothing expires, nothing is shed, and the
+	* queue grows for as long as the pressure lasts. The budget bounds concurrent
+	* WORK; it has never bounded queued work.
+	*
+	* That gap is not theoretical: the per-frame batch dispatch PINS a ~0.7 MB
+	* copy of the detection frame BEFORE queueing (so ring recycling cannot
+	* invalidate it), and the queued closure holds that copy alive. Measured on
+	* the live hub, `hub/pipeline-analytics` ran at rss=3911MB with heapUsed only
+	* 153MB and arrayBuffers=2281MB — 2.28 GB of JS-reachable Buffers, roughly
+	* 3 200 pinned frames, in a runner whose heap limit is 1216 MB. The call site
+	* that pins them says the cost is "bounded by the lane"; it was not.
+	*
+	* Two things happen on the way in, in this order:
+	*
+	*  1. **expire what is already dead.** Entries past their `staleAfterMs` are
+	*     dropped now. They were doomed the moment they expired; `pump` simply
+	*     never got to look. This is the reclaim that costs nothing.
+	*  2. **shed the least important.** Still over the cap, the TAIL goes — the
+	*     queue is ordered by priority, so the tail is by construction the work
+	*     this scheduler already ranked last. Whether that is the newcomer or an
+	*     older low-priority entry is decided by the same ordering that decides
+	*     execution, so a `firstFrame` never loses its place to an `embed`.
+	*/
 	enqueue(lane, input) {
 		return new Promise((resolve, reject) => {
 			const entry = {
@@ -51588,11 +51732,53 @@ var CaptureScheduler = class {
 				},
 				drop: () => resolve(null)
 			};
+			this.dropExpired(input.deviceId, lane);
 			this.insertByPriority(lane, entry);
+			this.shedToCap(input.deviceId, lane);
 			const w = this.window(input.deviceId);
 			if (lane.queue.length > w.maxQueueDepth) w.maxQueueDepth = lane.queue.length;
 		});
 	}
+	/** Drop every queued entry already past its `staleAfterMs`. Entries without
+	*  one (e.g. `confirm`, which gates track birth) are never expired here. */
+	dropExpired(deviceId, lane) {
+		const nowMs = this.now();
+		for (let i = lane.queue.length - 1; i >= 0; i -= 1) {
+			const entry = lane.queue[i];
+			if (entry === void 0) continue;
+			if (entry.staleAfterMs === void 0 || nowMs - entry.enqueuedAt <= entry.staleAfterMs) continue;
+			lane.queue.splice(i, 1);
+			this.bump(deviceId, "droppedStale");
+			entry.drop();
+		}
+	}
+	/** Shed from the tail (lowest priority, newest within it) until the lane is
+	*  at its cap. Loud: a capture that is dropped rather than merely late is a
+	*  missing thumbnail or first frame, and silence would read as "never asked". */
+	shedToCap(deviceId, lane) {
+		let shed = 0;
+		while (lane.queue.length > this.maxQueued) {
+			const victim = lane.queue.pop();
+			if (victim === void 0) break;
+			this.bump(deviceId, "droppedOverflow");
+			victim.drop();
+			shed += 1;
+		}
+		if (shed === 0) return;
+		const nowMs = this.now();
+		if (nowMs - (this.lastOverflowWarnAt.get(deviceId) ?? Number.NEGATIVE_INFINITY) < OVERFLOW_WARN_THROTTLE_MS) return;
+		this.lastOverflowWarnAt.set(deviceId, nowMs);
+		this.logger.warn("capture queue full — shedding the lowest-priority captures for this camera", {
+			tags: { deviceId },
+			meta: {
+				shed,
+				cap: this.maxQueued,
+				queueDepth: lane.queue.length,
+				inFlight: lane.inFlight,
+				budget: this.budget
+			}
+		});
+	}
 	insertByPriority(lane, entry) {
 		let index = lane.queue.length;
 		while (index > 0) {
@@ -51639,6 +51825,7 @@ var CaptureScheduler = class {
 			failed: 0,
 			coalesced: 0,
 			droppedStale: 0,
+			droppedOverflow: 0,
 			cancelled: 0,
 			maxQueueDepth: 0
 		};
@@ -51663,6 +51850,7 @@ var CaptureScheduler = class {
 				failed: w.failed,
 				coalesced: w.coalesced,
 				droppedStale: w.droppedStale,
+				droppedOverflow: w.droppedOverflow,
 				cancelled: w.cancelled,
 				maxQueueDepth: w.maxQueueDepth,
 				queueDepth: this.queueDepth(deviceId),
@@ -52751,6 +52939,36 @@ function buildAudioLabels(input) {
 	}];
 }
 //#endregion
+//#region src/pipeline-analytics/services/event-kinds-prefetch.ts
+/**
+* Resolve linked devices and bindings for `deviceIds` in two calls.
+*
+* Sequential by necessity, not by oversight: the binding set is cameras PLUS
+* everything linked to them, and the linked set is what the first call
+* returns.
+*
+* A camera or linked device missing from a batch answer resolves EMPTY rather
+* than throwing. Both batch endpoints answer for every id they were given, so
+* a gap here is a hub that answered a shorter array than it was asked for —
+* one camera loses its sensor lanes, never the whole request.
+*/
+async function prefetchDeviceTopology(api, deviceIds) {
+	const ids = [...new Set(deviceIds)];
+	const linkedRows = await api.getLinkedDevicesBatch({ deviceIds: ids });
+	const linkedByDevice = new Map(linkedRows.map((row) => [row.deviceId, row]));
+	const bindingTargets = new Set(ids);
+	for (const row of linkedRows) for (const linked of row.devices) bindingTargets.add(linked.deviceId);
+	const bindingRows = await api.getBindingsBatch({ deviceIds: [...bindingTargets] });
+	const bindingsByDevice = new Map(bindingRows.map((row) => [row.deviceId, row]));
+	return {
+		linkedDevices: { getLinkedDevices: async ({ deviceId }) => linkedByDevice.get(deviceId) ?? {
+			mode: "auto",
+			devices: []
+		} },
+		bindings: { getBindings: async ({ deviceId }) => bindingsByDevice.get(deviceId) ?? { entries: [] } }
+	};
+}
+//#endregion
 //#region src/pipeline-analytics/services/event-kinds.ts
 /**
 * Extensible per-device event kinds (Part B).
@@ -53233,8 +53451,14 @@ var EventMediaDispatcher = class {
 	* scheduler request against a 3-slot device lane and can start seconds late,
 	* by which time the handle's ring slot is usually recycled and the by-handle
 	* resolve in {@link captureForFrame} finds nothing (the 2026-07-23 boxed-tile
-	* regression). ~0.7MB per pinned frame, freed with the batch — bounded by the
-	* lane. Returns `null` on a genuine live-window miss.
+	* regression). ~0.7MB per pinned frame, freed with the batch.
+	*
+	* THE COPY IS ONLY AS BOUNDED AS THE QUEUE THAT HOLDS IT. This said "bounded
+	* by the lane" while the lane bounded in-flight execs (3) and nothing at all
+	* bounded the queue behind them, so a saturated camera accumulated pinned
+	* frames without limit — 2.28 GB of `arrayBuffers` measured on the live hub.
+	* Every caller must therefore pass `staleAfterMs`, and `CaptureScheduler`
+	* caps queue depth per device. Returns `null` on a genuine live-window miss.
 	*
 	* Both miss paths are WARN, throttled to one line per device per minute. They
 	* are the FIRST half of a pair whose second half (`capture batch lost`) has
@@ -60708,6 +60932,7 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 						hasSnapshot: snapshotTargets.some((t) => t.appendSnapshot)
 					}),
 					holdKeys: heldCaptureKeys,
+					staleAfterMs: ENRICHMENT_CAPTURE_STALE_MS,
 					exec: () => pinnedFramePromise.then((pinnedFrame) => dispatcher.captureForFrame({
 						deviceId,
 						frameHandle,
@@ -61637,7 +61862,9 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 		this.captureScheduler.request({
 			deviceId,
 			kind: "thumbnail",
+			trackId,
 			holdKeys: [captureCoalesceKey(deviceId, "thumbnail", trackId)],
+			staleAfterMs: ENRICHMENT_CAPTURE_STALE_MS,
 			exec: async () => {
 				const [pinnedFrame, media] = await Promise.all([pinnedFramePromise, this.resolveDeviceMediaSettings(deviceId)]);
 				const res = await dispatcher.captureForFrame({
@@ -63218,11 +63445,20 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 	/**
 	* `listEventKinds` for many cameras, in one call.
 	*
-	* The saving is not only the round-trips the CALLER avoids. Composing one
-	* camera's vocabulary costs a `getCameraStatus`; asked N times that is N
-	* cross-process calls, so the batch takes ONE `getCameraStatuses` for the
-	* whole set and composes from it. What remains per device (linked devices +
-	* their bindings) runs concurrently.
+	* The saving is not the round-trips the CALLER avoids — it is the fan-out
+	* this method used to do on its own. Composing one camera's vocabulary asks
+	* device-manager for its status, its linked devices, and the bindings of
+	* itself plus each linked device; asked per camera that was 1 + N + (N +
+	* linked) cross-process calls. Measured on the live hub 2026-08-25 over this
+	* deployment's 30 cameras: 106 calls, of which 30 concurrent
+	* `getLinkedDevices` alone took 4110 ms — each one runs a full-fleet
+	* `listAll` inside device-manager and thirty of them QUEUE.
+	*
+	* Now three calls for the whole set, whatever N is: one
+	* `getCameraStatuses`, then `prefetchDeviceTopology`'s
+	* `getLinkedDevicesBatch` + `getBindingsBatch`. `composeEventKinds` is
+	* unchanged — it is handed the same per-device client interfaces, backed by
+	* maps instead of RPC.
 	*
 	* A camera whose composition fails yields an EMPTY list rather than dropping
 	* out of the response: a caller that asked for twelve and got eleven cannot
@@ -63240,13 +63476,23 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 		});
 		const statusByDevice = new Map(statuses.map((st) => [st.deviceId, st]));
 		const detectionMacros = require_dist.MACRO_LABELS.map((l) => l.id).filter((id) => id !== "package");
+		const topology = await prefetchDeviceTopology({
+			getLinkedDevicesBatch: (i) => api.deviceManager.getLinkedDevicesBatch.query(i),
+			getBindingsBatch: (i) => api.deviceManager.getBindingsBatch.query(i)
+		}, deviceIds).catch((err) => {
+			this.ctx.logger.warn("listEventKindsBatch: batched device topology unavailable — per-device fallback", { meta: {
+				deviceCount: deviceIds.length,
+				error: require_dist.errMsg(err)
+			} });
+			return null;
+		});
 		return composeEventKindsForDevices(deviceIds, async (deviceId) => {
 			const status = statusByDevice.get(deviceId) ?? null;
 			const detectionOn = status?.detection != null;
 			const audioOn = status?.audio?.enabled === true;
 			return composeEventKinds({
-				linkedDevices: { getLinkedDevices: (i) => api.deviceManager.getLinkedDevices.query(i) },
-				bindings: { getBindings: (i) => api.deviceManager.getBindings.query(i) },
+				linkedDevices: topology?.linkedDevices ?? { getLinkedDevices: (i) => api.deviceManager.getLinkedDevices.query(i) },
+				bindings: topology?.bindings ?? { getBindings: (i) => api.deviceManager.getBindings.query(i) },
 				enabledMacroClasses: async () => detectionOn ? detectionMacros : [],
 				audioEnabled: async () => audioOn,
 				packageZonesEnabled: async (id) => {