@camstack/addon-post-analysis 1.2.128 → 1.2.130

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-D6O14xf_.js");
+const require_dist = require("../dist-CDHL-0gR.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
@@ -8932,7 +8971,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 +9029,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 +9344,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 +9378,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 +9389,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 +9450,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 +9494,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 +9507,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 +12614,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 +19658,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 +21198,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);
@@ -27217,6 +27294,18 @@ var FaceGalleryProvider = class {
 * This module names that state (`model-mismatch`) so the UI can say "this face
 * is in an old feature space" instead of showing 0% and letting the operator
 * conclude the person is not there.
+*
+* ## `buildFaceRescoreReport` stays pure — the CALLER persists
+*
+* This function never touches the store; every input is passed in and nothing
+* is read or written (see its own doc below). The operator asked for this
+* exact recompute, though, and wants the answer to stick — so the ACTION that
+* wraps this report (`rescoreFaceForTrack` in `pipeline-analytics/index.ts`)
+* writes the result onto `Face.suggestedIdentityId` / `suggestedMatchScore`,
+* through `decideRescorePersistence` / `persistRescoreResult` below. That is
+* still not a background job — it is the SAME explicitly-requested call,
+* writing once. A `model-mismatch` report (`comparable: false`) is never
+* written: see `persistRescoreResult`.
 */
 /** The empty report every "cannot score" path returns, so shape never varies. */
 function emptyReport(verdict, input, comparable) {
@@ -27292,6 +27381,52 @@ function buildFaceRescoreReport(input) {
 		...best !== void 0 && second !== void 0 ? { runnerUpGap: best.score - second.score } : {}
 	};
 }
+/**
+* What `face.rescoreTrack` should PERSIST for a COMPARABLE report, decided as
+* its own pure function so the rule is directly testable — separated from the
+* class that owns the store I/O (`rescoreFaceForTrack` in
+* `pipeline-analytics/index.ts`), which only wires this answer to
+* `FaceStore.setSuggestion`.
+*
+* `null` covers every verdict OTHER than `auto-assignable` / `suggestion`, and
+* also an `auto-assignable` / `suggestion` verdict whose best-ranked row is
+* not itself ELIGIBLE (`identities` is ranked by raw score across every
+* comparable identity, eligible or not — see `buildFaceRescoreReport`). Every
+* one of those is a genuine "nothing to suggest right now": never an
+* assignment, and never the winner of an `ambiguous` verdict — the matcher
+* refused to pick one, so this function does not pick one either.
+*
+* Callers MUST gate on `report.comparable` before calling this — a
+* `model-mismatch` report has no verdict worth acting on; see
+* {@link persistRescoreResult}, which does that gating and is the one thing
+* `rescoreFaceForTrack` actually calls.
+*/
+function decideRescorePersistence(report) {
+	if (report.verdict !== "auto-assignable" && report.verdict !== "suggestion") return null;
+	const candidate = report.identities.find((row) => row.eligible);
+	return candidate === void 0 ? null : {
+		identityId: candidate.identityId,
+		score: candidate.score
+	};
+}
+/**
+* Persist `face.rescoreTrack`'s result onto the SUGGESTED tier — the ONE
+* write this explicitly-requested action makes, and the only place that
+* decides whether it happens at all.
+*
+* A non-comparable report (`model-mismatch`) short-circuits BEFORE
+* `ports.setSuggestion` is ever called: a cosine across model spaces is
+* well-formed noise, and persisting it would look exactly like a fresh,
+* meaningful read to every future reader of the row. This is the single most
+* load-bearing branch in this file — the regression it guards against writes
+* garbage that reads as data.
+*/
+async function persistRescoreResult(faceId, report, ports) {
+	if (!report.comparable) return "not-comparable";
+	const candidate = decideRescorePersistence(report);
+	await ports.setSuggestion(faceId, candidate);
+	return candidate !== null ? "written" : "cleared";
+}
 //#endregion
 //#region src/pipeline-analytics/face-rescore-actions.ts
 /**
@@ -27392,8 +27527,10 @@ var FaceRescoreResultSchema = require_dist.object({
 	/** The face's current assignment, so the UI can mark "already this person". */
 	assigned: require_dist.boolean(),
 	assignedIdentityId: require_dist.string().optional(),
-	/** What the track has been SHOWING until now — persisted at detection time.
-	*  Returned so the UI can put the stale number beside the fresh one. */
+	/** What the track has been SHOWING until now — read BEFORE this call
+	*  writes, so it is whatever a previous track close or a previous
+	*  `face.rescoreTrack` last persisted. Returned so the UI can put the stale
+	*  number beside the fresh one. */
 	storedSuggestedIdentityId: require_dist.string().optional(),
 	storedSuggestedMatchScore: require_dist.number().optional(),
 	verdict: FaceRescoreVerdictSchema,
@@ -27410,9 +27547,12 @@ var FaceRescoreResultSchema = require_dist.object({
 });
 var faceRescoreActions = require_dist.defineCustomActions({ 
 /**
-* Read-only by default. `admin` because the report names every enrolled
-* person and how well an arbitrary face matches them — the gallery's shape,
-* which is not a viewer-level fact.
+* Persists its own result onto the SUGGESTED tier (`suggestedIdentityId` /
+* `suggestedMatchScore`) — never an assignment, never automatic; see
+* `rescoreFaceForTrack` in `pipeline-analytics/index.ts` and
+* `persistRescoreResult` in `face-rescore.ts`. `admin` because the report
+* also names every enrolled person and how well an arbitrary face matches
+* them — the gallery's shape, which is not a viewer-level fact.
 */
 "face.rescoreTrack": require_dist.customAction(FaceRescoreInputSchema, FaceRescoreResultSchema, {
 	kind: "mutation",
@@ -29407,6 +29547,51 @@ var FrameProcessor = class {
 	}
 };
 //#endregion
+//#region src/pipeline-analytics/replay/frame-processor-pass.ts
+/**
+* Run a FRESH `FrameProcessor` over a fixed, ordered sequence of frames and
+* return the tracks it produced.
+*
+* No `TrackStore`, no bus, no media — a track here is a summary built
+* ENTIRELY from `FrameProcessor.process()`'s in-memory return value.
+*/
+function runFrameProcessorPass(input) {
+	const processor = new FrameProcessor(input.deviceId, {}, {}, {}, input.source);
+	if (input.zones !== void 0) processor.setZones(input.zones);
+	if (input.detectionRules !== void 0) processor.setDetectionRules(input.detectionRules);
+	if (input.zoneMembershipMinOverlap !== void 0) processor.setZoneMembershipMinOverlap(input.zoneMembershipMinOverlap);
+	const accum = /* @__PURE__ */ new Map();
+	for (const { timestamp, frame } of input.frames) {
+		const result = processor.process({
+			timestamp,
+			frame
+		});
+		for (const td of result.tracked) {
+			const existing = accum.get(td.trackId);
+			const matched = td.matchedThisFrame ? 1 : 0;
+			if (existing === void 0) accum.set(td.trackId, {
+				className: td.className,
+				firstSeenMs: timestamp,
+				lastSeenMs: timestamp,
+				bbox: { ...td.bbox },
+				framesMatched: matched
+			});
+			else {
+				existing.className = td.className;
+				existing.lastSeenMs = timestamp;
+				existing.framesMatched += matched;
+			}
+		}
+	}
+	return { tracks: [...accum.values()].map((t) => ({
+		className: t.className,
+		firstSeenMs: t.firstSeenMs,
+		lastSeenMs: t.lastSeenMs,
+		bbox: t.bbox,
+		framesMatched: t.framesMatched
+	})) };
+}
+//#endregion
 //#region src/pipeline-analytics/pipeline/semantic-detail-bbox.ts
 /** Which box the semantic best-shot should crop: a plate/face DETAIL box
 *  when we have one, otherwise the subject box. */
@@ -47629,6 +47814,37 @@ var FaceStore = class {
 		}
 	}
 	/**
+	* 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
@@ -60020,6 +60236,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();
@@ -60538,6 +60755,21 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 			...input.nodeId !== void 0 ? { nodeId: input.nodeId } : {}
 		});
 	}
+	/**
+	* The FrameProcessor pass of a replay run — see the cap doc on
+	* `runReplayFrameProcessor` for why this is not the `processFrame` method
+	* this addon deliberately does not have.
+	*
+	* `runFrameProcessorPass` is pure w.r.t. this addon's own state: it
+	* constructs a FRESH `FrameProcessor` and does not touch `this.trackStore`,
+	* `this.stationaryRegistry` or any other instance field — unlike
+	* `getOrCreateProcessor` (the production path), which wires both.
+	* `scripts/check-replay-isolation.ts` holds that boundary on the
+	* `replay/` directory this delegates into.
+	*/
+	async runReplayFrameProcessor(input) {
+		return runFrameProcessorPass(input);
+	}
 	async listRetrainAnnotations(input) {
 		return this.requireRetrain().listAnnotations(input.trackId);
 	}
@@ -65487,6 +65719,13 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 	* See `face-rescore.ts` for why the number already on the track cannot answer
 	* that: it was computed during live detection and persisted at track close,
 	* so every enrolment made since is invisible to it.
+	*
+	* The report's result is PERSISTED (`persistRescoreResult`, below) onto
+	* `Face.suggestedIdentityId` / `suggestedMatchScore` — the SAME columns the
+	* live recognizer's suggestion band writes, so a reader never has to know
+	* whether a suggestion came from track close or from this button. Still
+	* never a background job: this write happens once, only because the
+	* operator asked THIS question right now.
 	*/
 	async rescoreFaceForTrack(input) {
 		const api = this.ctx.api;
@@ -65529,6 +65768,7 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 			clusterModelId,
 			params
 		});
+		const persisted = await persistRescoreResult(faceId, report, { setSuggestion: (id, suggestion) => faceStore.setSuggestion(id, suggestion) });
 		this.ctx.logger.info("face rescore", {
 			tags: { deviceId: input.deviceId },
 			meta: {
@@ -65542,7 +65782,8 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 				best: report.identities[0]?.name ?? null,
 				bestScore: report.identities[0]?.score ?? null,
 				storedSuggestion: face.suggestedMatchScore ?? null,
-				reembedded: reembed.succeeded
+				reembedded: reembed.succeeded,
+				persisted
 			}
 		});
 		return {