@camstack/addon-post-analysis 1.2.129 → 1.2.131

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-DFeeUt_t.js");
+const require_dist = require("../dist-B8_nKey5.js");
 let node_fs = require("node:fs");
 node_fs = require_dist.__toESM(node_fs, 1);
 let node_path = require("node:path");
@@ -2446,6 +2446,45 @@ var NcArtifactPlane = class {
 		}
 	}
 	/**
+	* Mint a FRESH signed URL for an artefact already sitting on the shelf —
+	* no bytes read, no re-store. The other half of {@link publishIndexed}: that
+	* one stores AND mints once at publish time; this one re-mints on demand for
+	* an id a caller already holds (a history row's `artifactIds`), because the
+	* link `publishIndexed` returned has its own TTL and a caller reaching for
+	* the artefact hours later needs a new one.
+	*
+	* `null` on any of three causes, deliberately indistinguishable to the
+	* caller: no index is wired (nothing to resolve against), the id is unknown
+	* or its artefact has expired past the retained shelf's own age bound, or no
+	* externally-reachable base URL exists for this install. A caller (the Home
+	* Assistant export) must render all three as "no image right now" — never as
+	* a broken link, and never by reusing a URL this call refused to mint.
+	*/
+	async mintUrl(artifactId) {
+		const index = this.deps.index;
+		if (index === void 0) return null;
+		try {
+			const record = await index.resolve(artifactId);
+			if (record === null) return null;
+			if (record.expiresAt <= this.now()) return null;
+			const baseUrl = await this.resolveBaseUrl();
+			if (baseUrl === null) return null;
+			return buildArtifactUrl({
+				baseUrl,
+				routePrefix: this.deps.routePrefix,
+				id: artifactId,
+				secret: this.deps.secret,
+				expMs: this.now() + (this.deps.ttlMs ?? DEFAULT_TTL_MS)
+			});
+		} catch (err) {
+			this.deps.logger.debug("artifact url mint failed", { meta: {
+				artifactId,
+				error: String(err)
+			} });
+			return null;
+		}
+	}
+	/**
 	* Absolutize a path against the SAME base URL an artifact link would use.
 	*
 	* For links this plane does not host but a RECIPIENT still has to open — a
@@ -5374,6 +5413,12 @@ function buildAlarmButtons(input) {
 	}];
 }
 //#endregion
+//#region src/notification-center/cap-caller.ts
+function requireCapCaller(method, caller) {
+	if (caller === void 0 || typeof caller.userId !== "string" || caller.userId.length === 0) throw new Error(`notification-rules.${method} declares caller: 'required' and this call carried no caller identity — an addon-to-addon cap call has no authenticated user`);
+	return caller;
+}
+//#endregion
 //#region src/notification-center/audio-rule-matcher.ts
 /**
 * AudioWatcher — the Notification Center's matcher for audio rules
@@ -8932,7 +8977,7 @@ var NcDispatcher = class {
 				return { ok: true };
 			}
 		}
-		const notification = await this.buildNotification(entry, target);
+		const { notification, artifactIds } = await this.buildNotification(entry, target);
 		const verdict = await this.runConfirmGate(entry, notification);
 		if (verdict !== null && verdict.decision === "suppressed") {
 			this.deps.logger.info("notification suppressed by AI confirm", {
@@ -8990,10 +9035,11 @@ var NcDispatcher = class {
 					...dropped.length > 0 ? { dropped } : {}
 				}
 			});
-			return verdict !== null ? {
+			return {
 				ok: true,
-				confirm: verdict
-			} : { ok: true };
+				...verdict !== null ? { confirm: verdict } : {},
+				...artifactIds.length > 0 ? { artifactIds } : {}
+			};
 		} catch (err) {
 			return {
 				ok: false,
@@ -9304,6 +9350,12 @@ var NcDispatcher = class {
 		});
 		return input.frozen ?? "";
 	}
+	/**
+	* Builds the notification AND returns the artefact ids its media resolve
+	* indexed — see {@link withArtifactUrls}. A tuple rather than a field on
+	* `NcNotificationInput`: the ids are internal (outbox provenance), never
+	* part of what `notification-output` sends to a backend.
+	*/
 	async buildNotification(entry, target) {
 		const subject = entry.payload.subject;
 		const systemEvent = subject.systemEvent;
@@ -9332,7 +9384,8 @@ var NcDispatcher = class {
 			vars: { body: rendered },
 			frozen: rendered
 		}) : rendered;
-		const attachments = [...await this.withArtifactUrls(entry, await this.resolveAttachments(entry)), ...frozenArtifactAttachments(entry)];
+		const resolvedMedia = await this.withArtifactUrls(entry, await this.resolveAttachments(entry));
+		const attachments = [...resolvedMedia.attachments, ...frozenArtifactAttachments(entry)];
 		const params = pickParams(entry.payload.params);
 		const tapUrl = params.clickUrl === void 0 && this.deps.viewerUrlBase !== void 0 ? defaultTapUrl({
 			deviceId: systemEvent !== void 0 ? 0 : subject.deviceId,
@@ -9342,21 +9395,24 @@ var NcDispatcher = class {
 		}) : null;
 		const actions = await this.mintActions(entry, target);
 		return {
-			body,
-			title,
-			priority: clampPriority(paramNumber(entry.payload.params, "priority") ?? entry.payload.priority),
-			...params,
-			...tapUrl !== null ? { clickUrl: tapUrl } : {},
-			tag: entry.payload.group?.key ?? entry.ruleId,
-			...systemEvent !== void 0 ? systemEvent.deviceId !== void 0 ? { deviceId: systemEvent.deviceId } : {} : { deviceId: subject.deviceId },
-			...subject.eventId !== void 0 ? { eventId: subject.eventId } : {},
-			...systemEvent !== void 0 ? { metadata: {
-				systemEventKind: systemEvent.kind,
-				subject: systemEvent.subject,
-				...systemEvent.data
-			} } : {},
-			...attachments.length > 0 ? { attachments } : {},
-			...actions.length > 0 ? { actions } : {}
+			notification: {
+				body,
+				title,
+				priority: clampPriority(paramNumber(entry.payload.params, "priority") ?? entry.payload.priority),
+				...params,
+				...tapUrl !== null ? { clickUrl: tapUrl } : {},
+				tag: entry.payload.group?.key ?? entry.ruleId,
+				...systemEvent !== void 0 ? systemEvent.deviceId !== void 0 ? { deviceId: systemEvent.deviceId } : {} : { deviceId: subject.deviceId },
+				...subject.eventId !== void 0 ? { eventId: subject.eventId } : {},
+				...systemEvent !== void 0 ? { metadata: {
+					systemEventKind: systemEvent.kind,
+					subject: systemEvent.subject,
+					...systemEvent.data
+				} } : {},
+				...attachments.length > 0 ? { attachments } : {},
+				...actions.length > 0 ? { actions } : {}
+			},
+			artifactIds: resolvedMedia.artifactIds
 		};
 	}
 	/**
@@ -9400,11 +9456,28 @@ var NcDispatcher = class {
 			}
 		});
 	}
+	/**
+	* What one delivery's media resolve produced: the attachments ready to ship
+	* (bytes plus a signed url when the plane could mint one) and the ids the
+	* artefact INDEX assigned them, in the same order — still first, then gif,
+	* then clip. The ids never ride on the attachment objects themselves: those
+	* cross to `notification-output` and a notifier backend has no use for an
+	* internal store id, only for `url`/`bytes`.
+	*
+	* `artifactIds` is what lets a delivery's outbox row later answer "which
+	* artefact was this trigger's picture" (`getHistory.artifactIds`) without a
+	* second write path — the outbox writes back exactly the ids this method
+	* handed to a SUCCESSFUL send, never re-deriving them.
+	*/
 	async withArtifactUrls(entry, attachments) {
 		const index = this.deps.indexArtifact;
 		const publish = this.deps.publishArtifact;
-		if (index === void 0 && publish === void 0) return [...attachments];
+		if (index === void 0 && publish === void 0) return {
+			attachments: [...attachments],
+			artifactIds: []
+		};
 		const out = [];
+		const artifactIds = [];
 		let posterId = null;
 		const deviceId = entry.payload.subject.deviceId;
 		const common = {
@@ -9427,6 +9500,7 @@ var NcDispatcher = class {
 					artifactId: null
 				}));
 				if (kind === "event-still" && pub.artifactId !== null) posterId = pub.artifactId;
+				if (pub.artifactId !== null) artifactIds.push(pub.artifactId);
 				out.push(pub.url === null ? { ...att } : {
 					...att,
 					url: pub.url
@@ -9439,7 +9513,10 @@ var NcDispatcher = class {
 				url
 			});
 		}
-		return out;
+		return {
+			attachments: out,
+			artifactIds
+		};
 	}
 	/** The full attachment list: the policy still (zone-cropped when the rule
 	*  froze zone ids) plus the footage cut from the broker's clip ring when
@@ -12543,13 +12620,17 @@ var NcOutbox = class {
 		}
 		const now = this.now();
 		if (result.ok) {
+			const payloadPatch = {
+				...result.confirm !== void 0 ? { confirmVerdict: result.confirm } : {},
+				...result.artifactIds !== void 0 && result.artifactIds.length > 0 ? { artifactIds: result.artifactIds } : {}
+			};
 			const sent = {
 				...entry,
 				status: "sent",
 				updatedAt: now,
-				...result.confirm !== void 0 ? { payload: {
+				...Object.keys(payloadPatch).length > 0 ? { payload: {
 					...entry.payload,
-					confirmVerdict: result.confirm
+					...payloadPatch
 				} } : {}
 			};
 			this.pending.delete(entry.id);
@@ -19583,7 +19664,8 @@ function outboxEntryToHistory(texts, entry) {
 			zones: [...s.zones],
 			timestamp: s.timestamp,
 			...s.systemEvent !== void 0 ? { systemEvent: historySystemEvent(texts, s.systemEvent) } : {}
-		}
+		},
+		...entry.payload.artifactIds !== void 0 && entry.payload.artifactIds.length > 0 ? { artifactIds: [...entry.payload.artifactIds] } : {}
 	};
 }
 /** The watched question in one grep-able token. */
@@ -21122,6 +21204,7 @@ var NotificationCenter = class NotificationCenter {
 				}
 				return { entries: mapped };
 			},
+			resolveArtifactUrl: async ({ artifactId }) => ({ url: await this.deps.resolveArtifactUrl?.(artifactId) ?? null }),
 			listDeviceMutes: async () => ({ mutedDeviceIds: this.deviceMutes.listMuted() }),
 			setDeviceMuted: async ({ deviceId, muted }) => {
 				await this.deviceMutes.setMuted(deviceId, muted);
@@ -21131,10 +21214,13 @@ var NotificationCenter = class NotificationCenter {
 				});
 				return { success: true };
 			},
-			listSnoozes: async ({ caller }) => ({ snoozes: [...this.snoozes.listVisibleTo(caller.userId, caller.isAdmin)] }),
-			createSnooze: async ({ snooze, caller }) => ({ snooze: await this.createSnooze(snooze, caller) }),
+			listSnoozes: async ({ caller }) => {
+				const who = requireCapCaller("listSnoozes", caller);
+				return { snoozes: [...this.snoozes.listVisibleTo(who.userId, who.isAdmin)] };
+			},
+			createSnooze: async ({ snooze, caller }) => ({ snooze: await this.createSnooze(snooze, requireCapCaller("createSnooze", caller)) }),
 			cancelSnooze: async ({ snoozeId, caller }) => {
-				await this.cancelSnooze(snoozeId, caller);
+				await this.cancelSnooze(snoozeId, requireCapCaller("cancelSnooze", caller));
 				return { success: true };
 			},
 			getAlarmConfig: async () => this.alarmConfig(),
@@ -26759,6 +26845,639 @@ function updateTrackAggregate(prev, match, opts) {
 	};
 }
 //#endregion
+//#region src/pipeline-analytics/store/face-sort.ts
+var DEFAULT_FACE_SORT = {
+	by: "timestamp",
+	direction: "desc"
+};
+/** Resolve a caller's partial request into a complete order. */
+function resolveFaceSort(input) {
+	return {
+		by: input?.sortBy ?? DEFAULT_FACE_SORT.by,
+		direction: input?.sortDirection ?? DEFAULT_FACE_SORT.direction
+	};
+}
+/**
+* True when the store's `timestamp`-indexed paging already emits rows in the
+* requested order, so a paged read may STOP as soon as `limit` rows have passed
+* the filter.
+*
+* False for `suggestionConfidence`: the most certain suggestion may be the
+* oldest row in the window, so an early stop would silently answer with the
+* newest N ranked — the exact defect this order was added to remove.
+*/
+function sortIsServedByTimestampPaging(order) {
+	return order.by === "timestamp";
+}
+/** Certainty, or `null` when the row has none. Null and undefined are the same
+*  answer — the relational backend surfaces an unset REAL column as SQL NULL. */
+function certaintyOf(face) {
+	return face.suggestedMatchScore ?? null;
+}
+/** Newest first, then `id` ascending. The tail of every comparison. */
+function compareTiebreak(a, b) {
+	if (a.timestamp !== b.timestamp) return b.timestamp - a.timestamp;
+	if (a.id === b.id) return 0;
+	return a.id < b.id ? -1 : 1;
+}
+function compareFaces(a, b, order) {
+	if (order.by === "timestamp") {
+		if (a.timestamp !== b.timestamp) return order.direction === "desc" ? b.timestamp - a.timestamp : a.timestamp - b.timestamp;
+		return compareTiebreak(a, b);
+	}
+	const aScore = certaintyOf(a);
+	const bScore = certaintyOf(b);
+	if (aScore === null && bScore !== null) return 1;
+	if (aScore !== null && bScore === null) return -1;
+	if (aScore !== null && bScore !== null && aScore !== bScore) return order.direction === "desc" ? bScore - aScore : aScore - bScore;
+	return compareTiebreak(a, b);
+}
+/** Immutable sort — the input array is never reordered in place. */
+function sortFaces(faces, order) {
+	return faces.toSorted((a, b) => compareFaces(a, b, order));
+}
+/**
+* Rank `faces` and keep at most `limit` of them.
+*
+* This is what lets the confidence order stay bounded: a paged sweep folds each
+* page in through here, so the retained set is the caller's `limit`, never the
+* corpus — even though the sweep itself has to walk the whole window.
+*/
+function rankAndCap(faces, order, limit) {
+	const sorted = sortFaces(faces, order);
+	return limit === void 0 ? sorted : sorted.slice(0, limit);
+}
+//#endregion
+//#region src/pipeline-analytics/store/face-store.ts
+/**
+* @durable class=ledger owner=pipeline-analytics
+*   write="one UPSERT per track that produced a face detail — the id is
+*     'face-<trackId>', so a track has at most one row and the recognizer
+*     overwrites it as a better read lands (embedding, match cosine, crop keys).
+*     The row is rewritten again when the operator enrols it, which flips
+*     `assigned` and stamps the identity."
+*   retention="TRACK-OWNED and clockless (D61): unassigned rows leave with their
+*     track through FaceStore.deleteByTracks, and enrolled (`assigned`) rows are
+*     exempt from that and from every sweep — an assignment is a curation act.
+*     The only other bound is capacity: pruneCapOverflow holds each camera's
+*     UNASSIGNED buffer to bufferMaxPerDevice newest rows (default 50). At 10.8 KB
+*     of JSON embedding per row, that cap is what keeps the table small."
+*/
+var FACES_COLLECTION = "pipeline-analytics:faces";
+/**
+* Rows per page for the two whole-collection sweeps below.
+*
+* A face row is one of the two WIDEST row shapes in the hub's database: it
+* carries a JSON `embedding` on every single row, measured at **10.8 KB
+* average** where a motion event is 78 bytes. Both sweeps used to read the
+* collection in ONE statement with no `limit`.
+*
+* To be exact about what that did and did not cause: this table holds **372
+* rows / 4.0 MB** on the live hub, so it was *not* the read that killed
+* hub-main on 2026-08-07 (that was the multi-camera track feed — see
+* `RECENT_FANOUT_ROW_BUDGET` in `track-store.ts`). It is a full scan whose cost
+* grows with a table nothing else bounds, which is the same defect one incident
+* earlier. `pruneCapOverflow` is what keeps the row count small — and it was
+* itself one of the two unbounded readers, so the bound and the thing enforcing
+* it were the same loop.
+*
+* The engine now refuses an unbounded read (`query-bounds.ts`), so paging here
+* is not belt-and-braces: without it these two methods would silently see only
+* the newest N rows and the buffer would grow forever.
+*
+* 1 000 keeps peak transfer around 11 MB while staying under the engine's own
+* cap, so the page is always the caller's bound and never the engine's.
+*/
+var FACE_SWEEP_PAGE = 1e3;
+/**
+* Refuses to loop forever if a page ever fails to advance. 1 000 pages is a
+* million faces — far past anything real, and reached only by a bug.
+*/
+var FACE_SWEEP_MAX_PAGES = 1e3;
+var FACE_COLUMNS = [
+	{
+		name: "id",
+		type: "TEXT",
+		primaryKey: true,
+		notNull: true
+	},
+	{
+		name: "deviceId",
+		type: "INTEGER",
+		notNull: true
+	},
+	{
+		name: "trackId",
+		type: "TEXT",
+		notNull: true
+	},
+	{
+		name: "timestamp",
+		type: "INTEGER",
+		notNull: true
+	},
+	{
+		name: "embedding",
+		type: "JSON",
+		notNull: true
+	},
+	{
+		name: "embeddingModelId",
+		type: "TEXT"
+	},
+	{
+		name: "mediaKey",
+		type: "TEXT"
+	},
+	{
+		name: "recognizedIdentityId",
+		type: "TEXT"
+	},
+	{
+		name: "assigned",
+		type: "BOOLEAN",
+		notNull: true
+	},
+	{
+		name: "assignedSampleId",
+		type: "TEXT"
+	},
+	{
+		name: "keyFrameMediaKey",
+		type: "TEXT"
+	},
+	{
+		name: "faceBbox",
+		type: "JSON"
+	},
+	{
+		name: "bestMatchScore",
+		type: "REAL"
+	},
+	{
+		name: "nativeFaceShortSidePx",
+		type: "REAL"
+	},
+	{
+		name: "suggestedIdentityId",
+		type: "TEXT"
+	},
+	{
+		name: "suggestedMatchScore",
+		type: "REAL"
+	}
+];
+var FACE_INDEXES = [{
+	name: "idx_faces_device_ts",
+	columns: ["deviceId", "timestamp"]
+}, {
+	name: "idx_faces_track",
+	columns: ["trackId"]
+}];
+/**
+* `since` / `until` as a store predicate.
+*
+* The filter surface has exactly one range form, `whereBetween`, and it is
+* inclusive on both ends — so a one-sided window is expressed by pinning the
+* other end to the edge of the safe integer range rather than by omitting it.
+* Returns `{}` when the caller named no window, so the read stays exactly the
+* unwindowed one.
+*/
+function buildTimestampWindow(input) {
+	if (input.since === void 0 && input.until === void 0) return {};
+	return { whereBetween: { timestamp: [input.since ?? Number.MIN_SAFE_INTEGER, input.until ?? Number.MAX_SAFE_INTEGER] } };
+}
+/**
+* One stored row → one {@link Face}.
+*
+* The single documented type boundary of this store: `SettingsRecord.data` is
+* `Record<string, unknown>` on the wire and the column set is declared right
+* here in {@link FACE_COLUMNS}, so this is the one place allowed to name the
+* shape it wrote.
+*
+* It also owns the NULL normalisation, and that is not cosmetic: the relational
+* backend surfaces an unset optional column as SQL NULL, and `FaceInfo`'s
+* optional strings REJECT null — an un-normalised row fails
+* `faceGallery.listRecentFaces` output validation and the People page renders
+* empty. This used to be copied out three times, which is three chances to
+* forget the next additive column.
+*/
+function rowToFace(id, raw) {
+	const data = raw;
+	return {
+		...data,
+		id,
+		assigned: Boolean(data.assigned),
+		mediaKey: data.mediaKey ?? void 0,
+		recognizedIdentityId: data.recognizedIdentityId ?? void 0,
+		assignedSampleId: data.assignedSampleId ?? void 0,
+		keyFrameMediaKey: data.keyFrameMediaKey ?? void 0,
+		faceBbox: data.faceBbox ?? void 0,
+		bestMatchScore: data.bestMatchScore ?? void 0,
+		nativeFaceShortSidePx: data.nativeFaceShortSidePx ?? void 0,
+		suggestedIdentityId: data.suggestedIdentityId ?? void 0,
+		suggestedMatchScore: data.suggestedMatchScore ?? void 0
+	};
+}
+var FaceStore = class {
+	store;
+	logger;
+	constructor(deps) {
+		this.store = deps.store;
+		this.logger = deps.logger;
+	}
+	static async declare(store) {
+		await store.declareCollection.mutate({
+			collection: FACES_COLLECTION,
+			columns: [...FACE_COLUMNS],
+			indexes: [...FACE_INDEXES]
+		});
+	}
+	/**
+	* Upsert one buffered face. Keyed by `face.id` (the worker uses one stable
+	* id per track → one entry per track). `set` replaces an existing row.
+	*/
+	async insert(face) {
+		const { id, ...rest } = face;
+		try {
+			await this.store.set.mutate({
+				collection: FACES_COLLECTION,
+				key: id,
+				value: rest
+			});
+		} catch (err) {
+			this.logger.warn("FaceStore.insert failed", {
+				tags: { deviceId: face.deviceId },
+				meta: {
+					faceId: id,
+					error: String(err)
+				}
+			});
+		}
+	}
+	/**
+	* Recent UNASSIGNED faces (the enrollment buffer), newest first.
+	*
+	* NOTE: `assigned` is normalized via `Boolean()` on read so the production
+	* SQLite backend (which returns INTEGER 0/1) is handled correctly.
+	*/
+	async listRecentFaces(input) {
+		const where = {};
+		if (input.deviceId !== void 0) where["deviceId"] = input.deviceId;
+		return (await this.store.query.query({
+			collection: FACES_COLLECTION,
+			filter: {
+				where,
+				orderBy: {
+					field: "timestamp",
+					direction: "desc"
+				},
+				limit: input.limit ?? 100
+			}
+		})).map((r) => rowToFace(r.id, r.data)).filter((f) => !f.assigned);
+	}
+	/**
+	* The per-device `prune(deviceId, cutoffMs, maxPerDevice)` that used to sit
+	* here is GONE (D61). It had no production caller — only tests — and it was
+	* an age-keyed deletion of a track-OWNED entity, i.e. the exact thing the
+	* retention model now forbids. A leftover that describes the wrong design
+	* still reads as permission to use it.
+	*/
+	/**
+	* Hold the unassigned face buffer to `maxPerDevice` newest rows per camera.
+	*
+	* **This is a CAPACITY bound, not an age one.** It used to be both: a face
+	* was deleted if it was older than `bufferRetentionDays` OR beyond the cap.
+	* The age half was a fifth clock over a track-OWNED entity — a face row
+	* carries a `trackId`, so it belongs to its track and cascades with it — and
+	* it aged crops out from under tracks that were still well inside their own
+	* retention window. It is gone (D61). What remains is the ring-buffer
+	* property the recognizer actually depends on: the gallery of recent
+	* unassigned faces stays small.
+	*
+	* ENROLLED (`assigned`) rows are skipped entirely and do not consume cap
+	* slots. Returns all deleted ids (the caller removes their crops).
+	*/
+	async pruneCapOverflow(input) {
+		/**
+		* Paged, not one statement. Only three scalars per row survive the page —
+		* the `embedding` string that dominates the row is dropped as soon as the
+		* page goes out of scope, so peak heap is one page rather than the whole
+		* face table. The prune still considers EVERY row, which is what makes it a
+		* capacity bound rather than a bound on the newest page.
+		*/
+		const byDevice = /* @__PURE__ */ new Map();
+		for (let page = 0; page < FACE_SWEEP_MAX_PAGES; page++) {
+			const rows = await this.store.query.query({
+				collection: FACES_COLLECTION,
+				filter: {
+					orderBy: {
+						field: "timestamp",
+						direction: "desc"
+					},
+					limit: FACE_SWEEP_PAGE,
+					offset: page * FACE_SWEEP_PAGE
+				}
+			});
+			if (rows.length === 0) break;
+			for (const r of rows) {
+				const data = r.data;
+				if (data.assigned) continue;
+				const deviceId = Number(data.deviceId ?? -1);
+				const list = byDevice.get(deviceId) ?? [];
+				list.push({
+					id: r.id,
+					timestamp: Number(data.timestamp ?? 0)
+				});
+				byDevice.set(deviceId, list);
+			}
+			if (rows.length < 1e3) break;
+		}
+		const toDelete = /* @__PURE__ */ new Set();
+		for (const list of byDevice.values()) {
+			list.sort((a, b) => b.timestamp - a.timestamp);
+			list.forEach((row, idx) => {
+				if (idx >= input.maxPerDevice) toDelete.add(row.id);
+			});
+		}
+		const deleted = [];
+		for (const id of toDelete) try {
+			await this.store.delete.mutate({
+				collection: FACES_COLLECTION,
+				key: id
+			});
+			deleted.push(id);
+		} catch (err) {
+			this.logger.warn("FaceStore.pruneCapOverflow delete failed", { meta: {
+				faceId: id,
+				error: String(err)
+			} });
+		}
+		return deleted;
+	}
+	/** Flip `assigned` to true and record which identity was matched. Optionally persist the sample id. */
+	async markAssigned(faceId, identityId, sampleId) {
+		const data = {
+			assigned: true,
+			recognizedIdentityId: identityId
+		};
+		if (sampleId !== void 0) data["assignedSampleId"] = sampleId;
+		try {
+			await this.store.update.mutate({
+				collection: FACES_COLLECTION,
+				id: faceId,
+				data
+			});
+		} catch (err) {
+			this.logger.warn("FaceStore.markAssigned failed", { meta: {
+				faceId,
+				error: String(err)
+			} });
+		}
+	}
+	/** Clear the assignment: set assigned=false, clear recognizedIdentityId and assignedSampleId. */
+	async clearAssignment(faceId) {
+		try {
+			await this.store.update.mutate({
+				collection: FACES_COLLECTION,
+				id: faceId,
+				data: {
+					assigned: false,
+					recognizedIdentityId: null,
+					assignedSampleId: null
+				}
+			});
+		} catch (err) {
+			this.logger.warn("FaceStore.clearAssignment failed", { meta: {
+				faceId,
+				error: String(err)
+			} });
+		}
+	}
+	/**
+	* Persist a `face.rescoreTrack` result onto the SUGGESTED tier — the ONE
+	* write that explicitly-requested action makes. `suggestion: null` means
+	* the recompute found no candidate worth offering and CLEARS both columns
+	* (a genuine "the gallery has nothing for this face right now" result, not
+	* a no-op left at whatever they held before). Never touches `assigned` /
+	* `recognizedIdentityId` — a suggestion is never an assignment. The caller
+	* is responsible for never calling this with a non-comparable (`model-
+	* mismatch`) report; this method persists whatever it is given.
+	*/
+	async setSuggestion(faceId, suggestion) {
+		const data = suggestion === null ? {
+			suggestedIdentityId: null,
+			suggestedMatchScore: null
+		} : {
+			suggestedIdentityId: suggestion.identityId,
+			suggestedMatchScore: suggestion.score
+		};
+		try {
+			await this.store.update.mutate({
+				collection: FACES_COLLECTION,
+				id: faceId,
+				data
+			});
+		} catch (err) {
+			this.logger.warn("FaceStore.setSuggestion failed", { meta: {
+				faceId,
+				error: String(err)
+			} });
+		}
+	}
+	/**
+	* `TrackScopedStore` contract for the retention cascade: delete the buffered
+	* face rows of the given tracks that are NOT assigned. Reuses the EXACT
+	* `assigned` exemption that `prune`/`pruneAll` apply (see the
+	* `!(r.data.assigned)` predicate above) so ENROLLED faces SURVIVE retention.
+	* Per-track ISOLATED + best-effort per row — one bad track or row never
+	* aborts the batch. (Crop media of these rows is removed by `MediaStore`.)
+	*/
+	async deleteByTracks(trackIds) {
+		let removed = 0;
+		for (const trackId of trackIds) try {
+			const eligible = (await this.store.query.query({
+				collection: FACES_COLLECTION,
+				filter: { where: { trackId } }
+			})).filter((r) => !r.data.assigned);
+			for (const row of eligible) try {
+				await this.store.delete.mutate({
+					collection: FACES_COLLECTION,
+					key: row.id
+				});
+				removed++;
+			} catch (err) {
+				this.logger.warn("FaceStore.deleteByTracks delete failed", { meta: {
+					faceId: row.id,
+					error: String(err)
+				} });
+			}
+		} catch (err) {
+			this.logger.warn("FaceStore.deleteByTracks query failed", { meta: {
+				trackId,
+				error: String(err)
+			} });
+		}
+		return [{
+			family: "faces",
+			rows: removed,
+			bytes: 0
+		}];
+	}
+	/** Delete a single buffered face row by id (its crop media is removed by the
+	*  caller — the FaceStore owns rows, not blobs). Best-effort. */
+	async delete(faceId) {
+		try {
+			await this.store.delete.mutate({
+				collection: FACES_COLLECTION,
+				key: faceId
+			});
+		} catch (err) {
+			this.logger.warn("FaceStore.delete failed", { meta: {
+				faceId,
+				error: String(err)
+			} });
+		}
+	}
+	/**
+	* Retrieve a single face by id. Returns null if not found.
+	*/
+	async get(faceId) {
+		const raw = await this.store.get.query({
+			collection: FACES_COLLECTION,
+			key: faceId
+		});
+		if (!raw) return null;
+		return rowToFace(faceId, raw);
+	}
+	/**
+	* Update internal fields of a face (used for partial mutation, e.g. setting recognizedIdentityId).
+	* Not exposed publicly — intended for internal use and tests only.
+	*/
+	async update(faceId, data) {
+		try {
+			await this.store.update.mutate({
+				collection: FACES_COLLECTION,
+				id: faceId,
+				data
+			});
+		} catch (err) {
+			this.logger.warn("FaceStore.update failed", { meta: {
+				faceId,
+				error: String(err)
+			} });
+		}
+	}
+	/**
+	* List recent faces across the cluster, or across a named set of cameras.
+	*
+	* filter:
+	*  - 'all' (default)        → every row
+	*  - 'unassigned'           → !assigned
+	*  - 'recognized'           → !assigned && recognizedIdentityId != null
+	*  - 'identified'           → recognizedIdentityId != null, including manual assignments
+	*
+	* `deviceIds`, `since` and `until` are pushed INTO the query — they narrow
+	* what is read, not what is returned. `filter` and the ordering cannot be
+	* (the first is a computed predicate, the second is a contract this backend
+	* does not implement — see `face-sort.ts`), so they are applied here.
+	*
+	* **`limit` counts rows that PASSED the filter, never rows that were
+	* discarded.** That is the whole reason this pages instead of asking the
+	* store for `limit` rows: with `filter:'unassigned'` the newest N rows may be
+	* entirely assigned while matches wait just beyond them.
+	*
+	* The previous answer was to fetch the WHOLE collection and slice after
+	* filtering. That is the read that killed hub-main (`query-bounds.ts`) —
+	* every face row carries a JSON `embedding`, so "all rows" is the widest
+	* table in the database materialised at once, to render a gallery of at most
+	* a few hundred tiles.
+	*
+	* So: PAGE. Under the default `timestamp` order the store's paging already
+	* emits rows in the answer's order, so the sweep stops the moment enough
+	* MATCHES exist and the common case costs one page. Under
+	* `suggestionConfidence` it cannot — the most certain suggestion may be the
+	* oldest row — so the sweep walks the window and folds each page through
+	* `rankAndCap`, which holds the RETAINED set to `limit` even though the read
+	* is wider. Narrow the read with `since` / `until`.
+	*
+	* An **empty `deviceIds` reads nothing at all**: `[]` is a request for no
+	* cameras, not an omission (the `deviceManager.listFleet` contract).
+	*/
+	async listAllRecentFaces(input) {
+		if (input.deviceIds !== void 0 && input.deviceIds.length === 0) return [];
+		const order = resolveFaceSort(input);
+		const pagingServesTheOrder = sortIsServedByTimestampPaging(order);
+		const filterMode = input.filter ?? "all";
+		const matches = (f) => {
+			if (filterMode === "unassigned") return !f.assigned;
+			if (filterMode === "recognized") return !f.assigned && f.recognizedIdentityId != null;
+			if (filterMode === "identified") return f.recognizedIdentityId != null;
+			return true;
+		};
+		const storeFilter = {
+			...input.deviceIds !== void 0 ? { whereIn: { deviceId: [...new Set(input.deviceIds)] } } : {},
+			...buildTimestampWindow(input),
+			orderBy: {
+				field: "timestamp",
+				direction: pagingServesTheOrder ? order.direction : "desc"
+			}
+		};
+		let result = [];
+		for (let page = 0; page < FACE_SWEEP_MAX_PAGES; page++) {
+			const rows = await this.store.query.query({
+				collection: FACES_COLLECTION,
+				filter: {
+					...storeFilter,
+					limit: FACE_SWEEP_PAGE,
+					offset: page * FACE_SWEEP_PAGE
+				}
+			});
+			if (rows.length === 0) break;
+			const matched = [];
+			for (const r of rows) {
+				const face = rowToFace(r.id, r.data);
+				if (matches(face)) matched.push(face);
+			}
+			if (pagingServesTheOrder) {
+				const merged = [...result, ...matched];
+				if (input.limit !== void 0 && merged.length >= input.limit) return merged.slice(0, input.limit);
+				result = merged;
+			} else result = rankAndCap([...result, ...matched], order, input.limit);
+			if (rows.length < 1e3) break;
+		}
+		return pagingServesTheOrder ? result : rankAndCap(result, order, input.limit);
+	}
+	/** One real face row per camera currently attributed to an identity. */
+	async listCameraRefsForIdentity(identityId) {
+		const byDevice = /* @__PURE__ */ new Map();
+		for (let page = 0; page < FACE_SWEEP_MAX_PAGES; page++) {
+			const rows = await this.store.query.query({
+				collection: FACES_COLLECTION,
+				filter: {
+					where: { recognizedIdentityId: identityId },
+					orderBy: {
+						field: "timestamp",
+						direction: "desc"
+					},
+					limit: FACE_SWEEP_PAGE,
+					offset: page * FACE_SWEEP_PAGE
+				}
+			});
+			if (rows.length === 0) break;
+			for (const row of rows) {
+				const deviceId = Number(row.data["deviceId"]);
+				if (Number.isInteger(deviceId) && !byDevice.has(deviceId)) byDevice.set(deviceId, row.id);
+			}
+			if (rows.length < 1e3) break;
+		}
+		return [...byDevice].map(([deviceId, faceId]) => ({
+			deviceId,
+			faceId
+		}));
+	}
+};
+//#endregion
 //#region src/pipeline-analytics/face-gallery-provider.ts
 /** Attribution of a face identity NAMED BY THE OPERATOR in the gallery. */
 var OPERATOR_FACE_STEP_ID = "operator:face-gallery";
@@ -26772,6 +27491,36 @@ var OPERATOR_FACE_STEP_ID = "operator:face-gallery";
 * stalled pipeline.
 */
 var FACE_CROP_FETCH_CONCURRENCY = 16;
+/**
+* How many unassigned faces `suggestFaceClusters` reads when the caller names
+* no {@link SuggestFaceClustersInput.maxFacesScanned}.
+*
+* Clustering used to read EVERY unassigned face on the hub, unconditionally:
+* its only bound (`limit`) cut the finished clusters, so it shortened the
+* ANSWER and never the work. A UI showing a window of 100 paid for a scan of
+* the whole corpus — on an addon whose disk is under contention — and no caller
+* had any way to ask for less.
+*
+* `FACE_SWEEP_PAGE` is chosen on purpose rather than a round number: it is
+* exactly ONE store page, so on the live corpus (372 face rows) the default
+* reads what it read before, one page, and nothing about today's answers
+* changes. What changes is the ceiling — the unbounded scan cannot come back as
+* the table grows.
+*/
+var SUGGEST_CLUSTERS_DEFAULT_FACE_POOL = FACE_SWEEP_PAGE;
+/**
+* The camera set a face listing is scoped to, as ONE value.
+*
+* `deviceIds` is the authority whenever it is present — including when it is
+* EMPTY, which reads nothing (a request for no cameras is a request, not an
+* omission). `deviceId` is the legacy single-camera form and only applies when
+* no set was named, so the two can never disagree about the answer.
+*/
+function resolveFaceDeviceScope(input) {
+	if (input?.deviceIds !== void 0) return { deviceIds: input.deviceIds };
+	if (input?.deviceId !== void 0) return { deviceIds: [input.deviceId] };
+	return {};
+}
 var FaceGalleryProvider = class {
 	identityStore;
 	faceStore;
@@ -26907,9 +27656,13 @@ var FaceGalleryProvider = class {
 	}
 	async listRecentFaces(input) {
 		const faces = await this.faceStore.listAllRecentFaces({
-			deviceId: input?.deviceId,
+			...resolveFaceDeviceScope(input),
 			limit: input?.limit,
-			filter: input?.filter
+			filter: input?.filter,
+			since: input?.since,
+			until: input?.until,
+			sortBy: input?.sortBy,
+			sortDirection: input?.sortDirection
 		});
 		const identities = await this.identityStore.listIdentities();
 		const nameMap = new Map(identities.map((i) => [i.id, i.name]));
@@ -27165,16 +27918,34 @@ var FaceGalleryProvider = class {
 	* Suggest clusters of look-alike UNASSIGNED faces (greedy cosine on their
 	* embeddings) so the operator can batch-assign a whole group. Embeddings stay
 	* server-side; only faceId groupings are returned.
+	*
+	* TWO bounds, and they cut different things — which is the whole point of the
+	* rename:
+	*  - `maxFacesScanned` bounds the POOL, i.e. the work. Newest unassigned
+	*    faces first, default {@link SUGGEST_CLUSTERS_DEFAULT_FACE_POOL}.
+	*  - `maxClusters` (formerly the ambiguous `limit`) bounds the ANSWER.
+	*    It has never made this method read one row less.
 	*/
 	async suggestFaceClusters(input) {
 		const threshold = input?.threshold ?? .5;
 		const minClusterSize = input?.minClusterSize ?? 2;
-		let clusters = clusterByEmbedding((await this.faceStore.listAllRecentFaces({ filter: "unassigned" })).filter((f) => Array.isArray(f.embedding) && f.embedding.length > 0).map((f) => ({
+		const maxFacesScanned = input?.maxFacesScanned ?? SUGGEST_CLUSTERS_DEFAULT_FACE_POOL;
+		const maxClusters = input?.maxClusters ?? input?.limit;
+		const faces = await this.faceStore.listAllRecentFaces({
+			filter: "unassigned",
+			limit: maxFacesScanned
+		});
+		if (faces.length >= maxFacesScanned) this.logger.info("suggestFaceClusters pool saturated — older faces not considered", { meta: {
+			maxFacesScanned,
+			scanned: faces.length,
+			threshold,
+			minClusterSize
+		} });
+		const clusters = clusterByEmbedding(faces.filter((f) => Array.isArray(f.embedding) && f.embedding.length > 0).map((f) => ({
 			id: f.id,
 			embedding: f.embedding
 		})), threshold).filter((c) => c.size >= minClusterSize);
-		if (input?.limit !== void 0) clusters = clusters.slice(0, input.limit);
-		return clusters;
+		return maxClusters === void 0 ? clusters : clusters.slice(0, maxClusters);
 	}
 };
 //#endregion
@@ -47419,553 +48190,6 @@ function stripNulls$1(data) {
 	return out;
 }
 //#endregion
-//#region src/pipeline-analytics/store/face-store.ts
-/**
-* @durable class=ledger owner=pipeline-analytics
-*   write="one UPSERT per track that produced a face detail — the id is
-*     'face-<trackId>', so a track has at most one row and the recognizer
-*     overwrites it as a better read lands (embedding, match cosine, crop keys).
-*     The row is rewritten again when the operator enrols it, which flips
-*     `assigned` and stamps the identity."
-*   retention="TRACK-OWNED and clockless (D61): unassigned rows leave with their
-*     track through FaceStore.deleteByTracks, and enrolled (`assigned`) rows are
-*     exempt from that and from every sweep — an assignment is a curation act.
-*     The only other bound is capacity: pruneCapOverflow holds each camera's
-*     UNASSIGNED buffer to bufferMaxPerDevice newest rows (default 50). At 10.8 KB
-*     of JSON embedding per row, that cap is what keeps the table small."
-*/
-var FACES_COLLECTION = "pipeline-analytics:faces";
-/**
-* Rows per page for the two whole-collection sweeps below.
-*
-* A face row is one of the two WIDEST row shapes in the hub's database: it
-* carries a JSON `embedding` on every single row, measured at **10.8 KB
-* average** where a motion event is 78 bytes. Both sweeps used to read the
-* collection in ONE statement with no `limit`.
-*
-* To be exact about what that did and did not cause: this table holds **372
-* rows / 4.0 MB** on the live hub, so it was *not* the read that killed
-* hub-main on 2026-08-07 (that was the multi-camera track feed — see
-* `RECENT_FANOUT_ROW_BUDGET` in `track-store.ts`). It is a full scan whose cost
-* grows with a table nothing else bounds, which is the same defect one incident
-* earlier. `pruneCapOverflow` is what keeps the row count small — and it was
-* itself one of the two unbounded readers, so the bound and the thing enforcing
-* it were the same loop.
-*
-* The engine now refuses an unbounded read (`query-bounds.ts`), so paging here
-* is not belt-and-braces: without it these two methods would silently see only
-* the newest N rows and the buffer would grow forever.
-*
-* 1 000 keeps peak transfer around 11 MB while staying under the engine's own
-* cap, so the page is always the caller's bound and never the engine's.
-*/
-var FACE_SWEEP_PAGE = 1e3;
-/**
-* Refuses to loop forever if a page ever fails to advance. 1 000 pages is a
-* million faces — far past anything real, and reached only by a bug.
-*/
-var FACE_SWEEP_MAX_PAGES = 1e3;
-var FACE_COLUMNS = [
-	{
-		name: "id",
-		type: "TEXT",
-		primaryKey: true,
-		notNull: true
-	},
-	{
-		name: "deviceId",
-		type: "INTEGER",
-		notNull: true
-	},
-	{
-		name: "trackId",
-		type: "TEXT",
-		notNull: true
-	},
-	{
-		name: "timestamp",
-		type: "INTEGER",
-		notNull: true
-	},
-	{
-		name: "embedding",
-		type: "JSON",
-		notNull: true
-	},
-	{
-		name: "embeddingModelId",
-		type: "TEXT"
-	},
-	{
-		name: "mediaKey",
-		type: "TEXT"
-	},
-	{
-		name: "recognizedIdentityId",
-		type: "TEXT"
-	},
-	{
-		name: "assigned",
-		type: "BOOLEAN",
-		notNull: true
-	},
-	{
-		name: "assignedSampleId",
-		type: "TEXT"
-	},
-	{
-		name: "keyFrameMediaKey",
-		type: "TEXT"
-	},
-	{
-		name: "faceBbox",
-		type: "JSON"
-	},
-	{
-		name: "bestMatchScore",
-		type: "REAL"
-	},
-	{
-		name: "nativeFaceShortSidePx",
-		type: "REAL"
-	},
-	{
-		name: "suggestedIdentityId",
-		type: "TEXT"
-	},
-	{
-		name: "suggestedMatchScore",
-		type: "REAL"
-	}
-];
-var FACE_INDEXES = [{
-	name: "idx_faces_device_ts",
-	columns: ["deviceId", "timestamp"]
-}, {
-	name: "idx_faces_track",
-	columns: ["trackId"]
-}];
-var FaceStore = class {
-	store;
-	logger;
-	constructor(deps) {
-		this.store = deps.store;
-		this.logger = deps.logger;
-	}
-	static async declare(store) {
-		await store.declareCollection.mutate({
-			collection: FACES_COLLECTION,
-			columns: [...FACE_COLUMNS],
-			indexes: [...FACE_INDEXES]
-		});
-	}
-	/**
-	* Upsert one buffered face. Keyed by `face.id` (the worker uses one stable
-	* id per track → one entry per track). `set` replaces an existing row.
-	*/
-	async insert(face) {
-		const { id, ...rest } = face;
-		try {
-			await this.store.set.mutate({
-				collection: FACES_COLLECTION,
-				key: id,
-				value: rest
-			});
-		} catch (err) {
-			this.logger.warn("FaceStore.insert failed", {
-				tags: { deviceId: face.deviceId },
-				meta: {
-					faceId: id,
-					error: String(err)
-				}
-			});
-		}
-	}
-	/**
-	* Recent UNASSIGNED faces (the enrollment buffer), newest first.
-	*
-	* NOTE: `assigned` is normalized via `Boolean()` on read so the production
-	* SQLite backend (which returns INTEGER 0/1) is handled correctly.
-	*/
-	async listRecentFaces(input) {
-		const where = {};
-		if (input.deviceId !== void 0) where["deviceId"] = input.deviceId;
-		return (await this.store.query.query({
-			collection: FACES_COLLECTION,
-			filter: {
-				where,
-				orderBy: {
-					field: "timestamp",
-					direction: "desc"
-				},
-				limit: input.limit ?? 100
-			}
-		})).map((r) => {
-			const data = r.data;
-			return {
-				id: r.id,
-				...data,
-				assigned: Boolean(r.data.assigned),
-				mediaKey: data.mediaKey ?? void 0,
-				recognizedIdentityId: data.recognizedIdentityId ?? void 0,
-				assignedSampleId: data.assignedSampleId ?? void 0,
-				keyFrameMediaKey: data.keyFrameMediaKey ?? void 0,
-				faceBbox: data.faceBbox ?? void 0,
-				bestMatchScore: data.bestMatchScore ?? void 0,
-				nativeFaceShortSidePx: data.nativeFaceShortSidePx ?? void 0,
-				suggestedIdentityId: data.suggestedIdentityId ?? void 0,
-				suggestedMatchScore: data.suggestedMatchScore ?? void 0
-			};
-		}).filter((f) => !f.assigned);
-	}
-	/**
-	* The per-device `prune(deviceId, cutoffMs, maxPerDevice)` that used to sit
-	* here is GONE (D61). It had no production caller — only tests — and it was
-	* an age-keyed deletion of a track-OWNED entity, i.e. the exact thing the
-	* retention model now forbids. A leftover that describes the wrong design
-	* still reads as permission to use it.
-	*/
-	/**
-	* Hold the unassigned face buffer to `maxPerDevice` newest rows per camera.
-	*
-	* **This is a CAPACITY bound, not an age one.** It used to be both: a face
-	* was deleted if it was older than `bufferRetentionDays` OR beyond the cap.
-	* The age half was a fifth clock over a track-OWNED entity — a face row
-	* carries a `trackId`, so it belongs to its track and cascades with it — and
-	* it aged crops out from under tracks that were still well inside their own
-	* retention window. It is gone (D61). What remains is the ring-buffer
-	* property the recognizer actually depends on: the gallery of recent
-	* unassigned faces stays small.
-	*
-	* ENROLLED (`assigned`) rows are skipped entirely and do not consume cap
-	* slots. Returns all deleted ids (the caller removes their crops).
-	*/
-	async pruneCapOverflow(input) {
-		/**
-		* Paged, not one statement. Only three scalars per row survive the page —
-		* the `embedding` string that dominates the row is dropped as soon as the
-		* page goes out of scope, so peak heap is one page rather than the whole
-		* face table. The prune still considers EVERY row, which is what makes it a
-		* capacity bound rather than a bound on the newest page.
-		*/
-		const byDevice = /* @__PURE__ */ new Map();
-		for (let page = 0; page < FACE_SWEEP_MAX_PAGES; page++) {
-			const rows = await this.store.query.query({
-				collection: FACES_COLLECTION,
-				filter: {
-					orderBy: {
-						field: "timestamp",
-						direction: "desc"
-					},
-					limit: FACE_SWEEP_PAGE,
-					offset: page * FACE_SWEEP_PAGE
-				}
-			});
-			if (rows.length === 0) break;
-			for (const r of rows) {
-				const data = r.data;
-				if (data.assigned) continue;
-				const deviceId = Number(data.deviceId ?? -1);
-				const list = byDevice.get(deviceId) ?? [];
-				list.push({
-					id: r.id,
-					timestamp: Number(data.timestamp ?? 0)
-				});
-				byDevice.set(deviceId, list);
-			}
-			if (rows.length < 1e3) break;
-		}
-		const toDelete = /* @__PURE__ */ new Set();
-		for (const list of byDevice.values()) {
-			list.sort((a, b) => b.timestamp - a.timestamp);
-			list.forEach((row, idx) => {
-				if (idx >= input.maxPerDevice) toDelete.add(row.id);
-			});
-		}
-		const deleted = [];
-		for (const id of toDelete) try {
-			await this.store.delete.mutate({
-				collection: FACES_COLLECTION,
-				key: id
-			});
-			deleted.push(id);
-		} catch (err) {
-			this.logger.warn("FaceStore.pruneCapOverflow delete failed", { meta: {
-				faceId: id,
-				error: String(err)
-			} });
-		}
-		return deleted;
-	}
-	/** Flip `assigned` to true and record which identity was matched. Optionally persist the sample id. */
-	async markAssigned(faceId, identityId, sampleId) {
-		const data = {
-			assigned: true,
-			recognizedIdentityId: identityId
-		};
-		if (sampleId !== void 0) data["assignedSampleId"] = sampleId;
-		try {
-			await this.store.update.mutate({
-				collection: FACES_COLLECTION,
-				id: faceId,
-				data
-			});
-		} catch (err) {
-			this.logger.warn("FaceStore.markAssigned failed", { meta: {
-				faceId,
-				error: String(err)
-			} });
-		}
-	}
-	/** Clear the assignment: set assigned=false, clear recognizedIdentityId and assignedSampleId. */
-	async clearAssignment(faceId) {
-		try {
-			await this.store.update.mutate({
-				collection: FACES_COLLECTION,
-				id: faceId,
-				data: {
-					assigned: false,
-					recognizedIdentityId: null,
-					assignedSampleId: null
-				}
-			});
-		} catch (err) {
-			this.logger.warn("FaceStore.clearAssignment failed", { meta: {
-				faceId,
-				error: String(err)
-			} });
-		}
-	}
-	/**
-	* Persist a `face.rescoreTrack` result onto the SUGGESTED tier — the ONE
-	* write that explicitly-requested action makes. `suggestion: null` means
-	* the recompute found no candidate worth offering and CLEARS both columns
-	* (a genuine "the gallery has nothing for this face right now" result, not
-	* a no-op left at whatever they held before). Never touches `assigned` /
-	* `recognizedIdentityId` — a suggestion is never an assignment. The caller
-	* is responsible for never calling this with a non-comparable (`model-
-	* mismatch`) report; this method persists whatever it is given.
-	*/
-	async setSuggestion(faceId, suggestion) {
-		const data = suggestion === null ? {
-			suggestedIdentityId: null,
-			suggestedMatchScore: null
-		} : {
-			suggestedIdentityId: suggestion.identityId,
-			suggestedMatchScore: suggestion.score
-		};
-		try {
-			await this.store.update.mutate({
-				collection: FACES_COLLECTION,
-				id: faceId,
-				data
-			});
-		} catch (err) {
-			this.logger.warn("FaceStore.setSuggestion failed", { meta: {
-				faceId,
-				error: String(err)
-			} });
-		}
-	}
-	/**
-	* `TrackScopedStore` contract for the retention cascade: delete the buffered
-	* face rows of the given tracks that are NOT assigned. Reuses the EXACT
-	* `assigned` exemption that `prune`/`pruneAll` apply (see the
-	* `!(r.data.assigned)` predicate above) so ENROLLED faces SURVIVE retention.
-	* Per-track ISOLATED + best-effort per row — one bad track or row never
-	* aborts the batch. (Crop media of these rows is removed by `MediaStore`.)
-	*/
-	async deleteByTracks(trackIds) {
-		let removed = 0;
-		for (const trackId of trackIds) try {
-			const eligible = (await this.store.query.query({
-				collection: FACES_COLLECTION,
-				filter: { where: { trackId } }
-			})).filter((r) => !r.data.assigned);
-			for (const row of eligible) try {
-				await this.store.delete.mutate({
-					collection: FACES_COLLECTION,
-					key: row.id
-				});
-				removed++;
-			} catch (err) {
-				this.logger.warn("FaceStore.deleteByTracks delete failed", { meta: {
-					faceId: row.id,
-					error: String(err)
-				} });
-			}
-		} catch (err) {
-			this.logger.warn("FaceStore.deleteByTracks query failed", { meta: {
-				trackId,
-				error: String(err)
-			} });
-		}
-		return [{
-			family: "faces",
-			rows: removed,
-			bytes: 0
-		}];
-	}
-	/** Delete a single buffered face row by id (its crop media is removed by the
-	*  caller — the FaceStore owns rows, not blobs). Best-effort. */
-	async delete(faceId) {
-		try {
-			await this.store.delete.mutate({
-				collection: FACES_COLLECTION,
-				key: faceId
-			});
-		} catch (err) {
-			this.logger.warn("FaceStore.delete failed", { meta: {
-				faceId,
-				error: String(err)
-			} });
-		}
-	}
-	/**
-	* Retrieve a single face by id. Returns null if not found.
-	*/
-	async get(faceId) {
-		const raw = await this.store.get.query({
-			collection: FACES_COLLECTION,
-			key: faceId
-		});
-		if (!raw) return null;
-		const data = raw;
-		return {
-			id: faceId,
-			...data,
-			assigned: Boolean(raw.assigned),
-			mediaKey: data.mediaKey ?? void 0,
-			recognizedIdentityId: data.recognizedIdentityId ?? void 0,
-			assignedSampleId: data.assignedSampleId ?? void 0,
-			keyFrameMediaKey: data.keyFrameMediaKey ?? void 0,
-			faceBbox: data.faceBbox ?? void 0,
-			bestMatchScore: data.bestMatchScore ?? void 0,
-			nativeFaceShortSidePx: data.nativeFaceShortSidePx ?? void 0,
-			suggestedIdentityId: data.suggestedIdentityId ?? void 0,
-			suggestedMatchScore: data.suggestedMatchScore ?? void 0
-		};
-	}
-	/**
-	* Update internal fields of a face (used for partial mutation, e.g. setting recognizedIdentityId).
-	* Not exposed publicly — intended for internal use and tests only.
-	*/
-	async update(faceId, data) {
-		try {
-			await this.store.update.mutate({
-				collection: FACES_COLLECTION,
-				id: faceId,
-				data
-			});
-		} catch (err) {
-			this.logger.warn("FaceStore.update failed", { meta: {
-				faceId,
-				error: String(err)
-			} });
-		}
-	}
-	/**
-	* List ALL recent faces across all devices, newest-first.
-	*
-	* filter:
-	*  - 'all' (default)        → every row
-	*  - 'unassigned'           → !assigned
-	*  - 'recognized'           → !assigned && recognizedIdentityId != null
-	*  - 'identified'           → recognizedIdentityId != null, including manual assignments
-	*/
-	async listAllRecentFaces(input) {
-		/**
-		* The filter is applied in memory, so a DB `limit` of N cannot be the
-		* caller's N: with `filter:'unassigned'` the newest N rows may be entirely
-		* assigned while matches wait just beyond them.
-		*
-		* The previous answer was to fetch the WHOLE collection and slice after
-		* filtering. That is the read that killed hub-main (`query-bounds.ts`) —
-		* every face row carries a JSON `embedding`, so "all rows" is the widest
-		* table in the database materialised at once, to render a gallery of at
-		* most a few hundred tiles.
-		*
-		* PAGE instead, and stop as soon as enough MATCHES exist. The pathological
-		* case (a filter that matches nothing) walks the whole collection exactly
-		* as before but one bounded page at a time; the common case stops after the
-		* first page. Semantics are unchanged: the limit is still applied after the
-		* filter, never before it.
-		*/
-		const filterMode = input.filter ?? "all";
-		const matches = (f) => {
-			if (filterMode === "unassigned") return !f.assigned;
-			if (filterMode === "recognized") return !f.assigned && f.recognizedIdentityId != null;
-			if (filterMode === "identified") return f.recognizedIdentityId != null;
-			return true;
-		};
-		const result = [];
-		for (let page = 0; page < FACE_SWEEP_MAX_PAGES; page++) {
-			const rows = await this.store.query.query({
-				collection: FACES_COLLECTION,
-				filter: {
-					...input.deviceId !== void 0 ? { where: { deviceId: input.deviceId } } : {},
-					orderBy: {
-						field: "timestamp",
-						direction: "desc"
-					},
-					limit: FACE_SWEEP_PAGE,
-					offset: page * FACE_SWEEP_PAGE
-				}
-			});
-			if (rows.length === 0) break;
-			for (const r of rows) {
-				const data = r.data;
-				const face = {
-					id: r.id,
-					...data,
-					assigned: Boolean(r.data.assigned),
-					mediaKey: data.mediaKey ?? void 0,
-					recognizedIdentityId: data.recognizedIdentityId ?? void 0,
-					assignedSampleId: data.assignedSampleId ?? void 0,
-					keyFrameMediaKey: data.keyFrameMediaKey ?? void 0,
-					faceBbox: data.faceBbox ?? void 0,
-					bestMatchScore: data.bestMatchScore ?? void 0,
-					nativeFaceShortSidePx: data.nativeFaceShortSidePx ?? void 0,
-					suggestedIdentityId: data.suggestedIdentityId ?? void 0,
-					suggestedMatchScore: data.suggestedMatchScore ?? void 0
-				};
-				if (matches(face)) result.push(face);
-				if (input.limit !== void 0 && result.length >= input.limit) return result;
-			}
-			if (rows.length < 1e3) break;
-		}
-		return result;
-	}
-	/** One real face row per camera currently attributed to an identity. */
-	async listCameraRefsForIdentity(identityId) {
-		const byDevice = /* @__PURE__ */ new Map();
-		for (let page = 0; page < FACE_SWEEP_MAX_PAGES; page++) {
-			const rows = await this.store.query.query({
-				collection: FACES_COLLECTION,
-				filter: {
-					where: { recognizedIdentityId: identityId },
-					orderBy: {
-						field: "timestamp",
-						direction: "desc"
-					},
-					limit: FACE_SWEEP_PAGE,
-					offset: page * FACE_SWEEP_PAGE
-				}
-			});
-			if (rows.length === 0) break;
-			for (const row of rows) {
-				const deviceId = Number(row.data["deviceId"]);
-				if (Number.isInteger(deviceId) && !byDevice.has(deviceId)) byDevice.set(deviceId, row.id);
-			}
-			if (rows.length < 1e3) break;
-		}
-		return [...byDevice].map(([deviceId, faceId]) => ({
-			deviceId,
-			faceId
-		}));
-	}
-};
-//#endregion
 //#region src/pipeline-analytics/store/identity-store.ts
 /**
 * IdentityStore — per-person identity registry for face recognition.
@@ -60159,6 +60383,7 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 			cancelVision: async (requestId) => {
 				await api.llm.cancel.mutate({ requestId });
 			},
+			resolveArtifactUrl: async (artifactId) => await this.ncArtifactPlane?.mintUrl(artifactId) ?? null,
 			mintActionUrl: (input) => this.ncActionMintUrl?.(input) ?? Promise.resolve(null),
 			readDeviceStates: async (ids) => {
 				const out = /* @__PURE__ */ new Map();