@camstack/addon-post-analysis 1.2.207 → 1.2.208

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-sREZj0iq.js");
+const require_dist = require("../dist-CoLA3NHh.js");
 let node_fs = require("node:fs");
 node_fs = require_dist.__toESM(node_fs, 1);
 let node_path = require("node:path");
@@ -27594,10 +27594,63 @@ function squareSubjectCropRegion(bbox, frame) {
 		h: Math.round(side)
 	};
 }
-function wideCentralSquareLayout(bbox, frame, options = {}) {
-	const central = squareSubjectCropRegion(bbox, frame);
+/**
+* How much of the composed picture may be synthesized fill before the canvas
+* NARROWS instead (operator directive, 2026-09-08, track a46599d5 device 3829).
+*
+* A subject flush against a frame edge for its whole life has no containable
+* frame, so `containSubject` keeps the middle square on it and pays the
+* overhang in lateral fill. On that car the bill was 225 px — 21.9% of the
+* picture, and the operator read the blurred stretch as a mirrored duplicate of
+* the scene.
+*
+* Rather than choose between an uncontained subject and a quarter of ambience,
+* the canvas gives up WIDTH: it narrows towards its own central square until
+* the fill is at most this fraction. Aspect then lands between 1:1 and 16:9 —
+* the square is never crossed, because the square is the region that is
+* guaranteed to hold the subject.
+*
+* The cost is real and it is lateral CONTEXT: a wide surface cover-fitting a
+* near-square picture crops top and bottom. That is why this is a cap and not a
+* rule — everything that already composes with a small fill keeps its 16:9.
+*/
+var MAX_LETTERBOX_FRACTION = .1;
+/**
+* The 16:9 width, narrowed just enough to hold the fill under
+* {@link MAX_LETTERBOX_FRACTION}.
+*
+* The canvas is CENTRED on the square, so each side wants `(canvasW - c) / 2`
+* and gets whatever real frame lies there; the rest is fill. Solving
+* `(w - c)/2 - available <= cap * w` for `w` gives the widest canvas that
+* respects the cap on that side, and the binding side is the narrower answer.
+*
+* It is computed from the space available BEFORE the slide, which can only
+* over-estimate the fill: the slide moves the window towards real scene and
+* never away from it. So a layout that the slide would have rescued anyway may
+* come out a few percent narrower than strictly necessary — a smaller error
+* than the band it removes, and in the other direction.
+*
+* Never narrower than the square itself: below that the picture would cut the
+* one region the layout guarantees contains the subject.
+*/
+function cappedCanvasWidth(c, centralX, frameW) {
+	const full = Math.round(c * 16 / 9);
+	const denominator = .5 - MAX_LETTERBOX_FRACTION;
+	const widest = (available) => (c / 2 + Math.max(0, available)) / denominator;
+	const bound = Math.min(widest(centralX), widest(frameW - (centralX + c)));
+	if (!Number.isFinite(bound) || bound >= full) return full;
+	return Math.max(c, Math.round(bound));
+}
+/**
+* The layout at a GIVEN canvas width. `wideCentralSquareLayout` runs it twice:
+* once at the full 16:9 width, and — only when that leaves more fill than
+* {@link MAX_LETTERBOX_FRACTION} — once at the narrowed width. Two passes
+* rather than one predictive formula because the slide's result is what
+* decides, and computing the fill after the slide is exact where predicting it
+* is not.
+*/
+function layoutAtWidth(bbox, frame, options, central, canvasW) {
 	const c = central.w;
-	const canvasW = Math.round(c * 16 / 9);
 	const centralX0 = Math.round((canvasW - c) / 2);
 	const anchorX = central.x - (canvasW - c) / 2;
 	let frameOriginX = anchorX;
@@ -27635,6 +27688,21 @@ function wideCentralSquareLayout(bbox, frame, options = {}) {
 		frameOriginX
 	};
 }
+/** Synthesized fill as a fraction of the composed picture. */
+function letterboxFraction(layout, frame) {
+	const left = Math.max(0, -layout.frameOriginX);
+	const right = Math.max(0, layout.frameOriginX + layout.canvasW - frame.W);
+	return layout.canvasW <= 0 ? 0 : Math.max(left, right) / layout.canvasW;
+}
+function wideCentralSquareLayout(bbox, frame, options = {}) {
+	const central = squareSubjectCropRegion(bbox, frame);
+	const c = central.w;
+	const full = Math.round(c * 16 / 9);
+	const wide = layoutAtWidth(bbox, frame, options, central, full);
+	if (full > frame.W || letterboxFraction(wide, frame) <= .1) return wide;
+	const narrowed = cappedCanvasWidth(c, central.x, frame.W);
+	return narrowed >= full ? wide : layoutAtWidth(bbox, frame, options, central, narrowed);
+}
 /**
 * Fraction of the subject bbox's area that lands inside the CENTRAL SQUARE a
 * square consumer center-crops from the composed 16:9 canvas — i.e. how much
@@ -28578,11 +28646,37 @@ var MediaStore = class {
 				timestamp,
 				deviceId: Number(data["deviceId"])
 			};
-		} catch {
+		} catch (err) {
+			this.logger.warn("media read failed — row kept, blob not served", {
+				tags: { deviceId: Number(data["deviceId"]) },
+				meta: {
+					key,
+					path,
+					location: mediaRowLocation(data),
+					error: String(err)
+				}
+			});
 			return null;
 		}
 	}
 	/**
+	* Can this row's blob be SERVED? The question `getByKey` answers in bytes,
+	* asked without fetching any.
+	*
+	* False covers both permanent causes — no row, and a row whose blob cannot be
+	* reached (deleted, or on a storage location the row names and the cluster no
+	* longer has). They are one answer here because they are one answer to the
+	* viewer: the tile is blank. Which of the two it is belongs in the log line
+	* above, not in a boolean.
+	*/
+	async blobServable(key) {
+		try {
+			return await this.referencedBlobState(key) === "exists";
+		} catch {
+			return false;
+		}
+	}
+	/**
 	* Delete a single media entry by its key (id).
 	* Deletes the blob from storage (best-effort) and removes the index row.
 	*/
@@ -28780,11 +28874,15 @@ var MediaStore = class {
 					...provenance !== void 0 ? { provenance } : {}
 				});
 			} catch (err) {
-				this.logger.debug("media read failed — row kept but blob missing", { meta: {
-					key: row.id,
-					path,
-					error: String(err)
-				} });
+				this.logger.warn("media read failed — row kept, blob not served", {
+					tags: { deviceId: Number(data["deviceId"]) },
+					meta: {
+						key: row.id,
+						path,
+						location: mediaRowLocation(data),
+						error: String(err)
+					}
+				});
 			}
 		}
 		return files;
@@ -30417,6 +30515,8 @@ function analyseDebugTrack(inventory) {
 	const durationMs = trackDurationMs(facts);
 	const closed = !facts.active;
 	const out = [];
+	const unreadable = inventory.unreadableMedia ?? [];
+	if (unreadable.length > 0) out.push(finding("MEDIA_ROW_WITHOUT_BLOB", "error", `${unreadable.length} of ${media.length} media rows exist in the index but their bytes could not be read — the tile renders blank and every count taken from the index overstates what is there. The blob is missing, or its row names a storage location that no longer resolves.`));
 	if (media.length === 0) out.push(finding("MEDIA_EVICTED_OR_NEVER", "error", "No media at all — either nothing was captured, or it was evicted (a debug mark does not pin retention)."));
 	else if (closed) {
 		const keyFrameMissing = !hasKind(media, "keyFrame");
@@ -30596,12 +30696,15 @@ async function gatherTrack(deps, track) {
 	for (const owner of MEDIA_OWNERS) media.push(...await deps.listMediaInfo(owner.kind, `${owner.prefix}${track.trackId}`));
 	const events = await deps.listEvents(track.trackId);
 	const thumbnailProvenance = await deps.trackThumbnailProvenance(track.trackId);
+	const unreadableMedia = [];
+	for (const row of media) if (!await deps.probeMediaBlob(row.key)) unreadableMedia.push(row.key);
 	return {
 		inventory: {
 			facts: toFacts(track),
 			media,
 			eventCount: events.length,
-			thumbnailProvenance
+			thumbnailProvenance,
+			unreadableMedia
 		},
 		events
 	};
@@ -32637,6 +32740,130 @@ var FaceStore = class {
 	}
 };
 //#endregion
+//#region src/pipeline-analytics/identity-audit.ts
+/**
+* identity-audit — which of a person's ENROLLED samples do not look like the
+* rest of that person.
+*
+* ## Why this exists
+*
+* The gallery is the one input to recognition that nobody re-reads. A sample
+* enrolled from the wrong face keeps voting forever: it pulls the wrong name
+* onto every future match near it, and because auto-assignment then looks
+* confident, nobody goes back to check. The 2026-09-08 sweep found exactly one
+* such pair on this cluster — a sample under one person scoring 0.61 against
+* three samples of another, enrolled from the same camera in the same minute,
+* where every other cross-identity pair on the cluster sits under 0.50.
+*
+* Finding that took a script and a day. This module makes it a question the
+* operator can ask per person, from the Review tab, and act on.
+*
+* ## What it measures
+*
+* Two numbers per sample, and the second is the one that convicts:
+*
+*  - `selfMean` — mean cosine against the person's OTHER samples. Low means
+*    "this does not look like the rest of you", which is suspicious but can
+*    also be a legitimate hard angle, bad light, a mask.
+*  - `bestForeign` — the highest cosine against any OTHER person's samples,
+*    with that person named. High means "this looks like someone we can name",
+*    which is what a mis-enrolment actually looks like.
+*
+* `suspicion` combines them so a sample that looks like somebody else outranks
+* one that merely looks like nobody: the first is a fixable error, the second
+* is often just a difficult photograph.
+*
+* ## What it refuses to do
+*
+* A cosine between vectors from two different face models is a well-formed
+* float with no meaning — `face-matcher` refuses the comparison and so does
+* this (`comparable: false`). It must read as "cannot say", never as an
+* accusation and never as a clean bill: this list ends in a DELETE button.
+*
+* A person with one sample is not judged either. One sample has nothing to
+* disagree with, and the only thing an outlier score could do there is delete
+* the only sample a new person has.
+*
+* Pure — the caller loads the vectors and performs the removal.
+*/
+/** Above this a row is worth the operator's attention. */
+var SUSPICION_FLAG = .5;
+/**
+* How far a foreign match has to stand OUT to count as looking like someone
+* else: `bestForeign - selfMean`. A sample that scores 0.6 against a stranger
+* and 0.7 against its own person is not a mis-enrolment.
+*/
+function foreignExcess(selfMean, foreign) {
+	if (foreign === void 0) return 0;
+	if (selfMean === null) return 0;
+	return Math.max(0, foreign.score - selfMean);
+}
+function meanCosine(target, pool) {
+	let sum = 0;
+	let n = 0;
+	for (const other of pool) {
+		if (other.sampleId === target.sampleId) continue;
+		sum += cosineSimilarity(target.embedding, other.embedding);
+		n += 1;
+	}
+	return n === 0 ? null : sum / n;
+}
+function bestForeignMatch(target, others, modelId) {
+	let best;
+	for (const identity of others) for (const sample of identity.samples) {
+		if (sample.modelId !== modelId) continue;
+		const score = cosineSimilarity(target.embedding, sample.embedding);
+		if (best === void 0 || score > best.score) best = {
+			identityId: identity.identityId,
+			name: identity.name,
+			score
+		};
+	}
+	return best;
+}
+/**
+* Rank one person's samples, worst first.
+*
+* `suspicion` is `(1 - selfMean) / 2` — how far the sample sits from its own
+* person, on [0,1] — plus the foreign EXCESS, which dominates when a sample
+* genuinely resembles somebody the gallery can name. A sample that agrees with
+* its person scores near zero on both terms.
+*/
+function auditIdentitySamples(input) {
+	const comparable = input.samples.filter((s) => s.modelId === input.modelId);
+	const rows = input.samples.map((sample) => {
+		if (sample.modelId !== input.modelId) return {
+			sampleId: sample.sampleId,
+			enrolledAt: sample.enrolledAt,
+			...sample.deviceId === void 0 ? {} : { deviceId: sample.deviceId },
+			comparable: false,
+			selfMean: null,
+			suspicion: 0
+		};
+		const selfMean = meanCosine(sample, comparable);
+		const foreign = bestForeignMatch(sample, input.others, input.modelId);
+		const excess = foreignExcess(selfMean, foreign);
+		const suspicion = selfMean === null ? 0 : (1 - selfMean) / 2 + excess;
+		return {
+			sampleId: sample.sampleId,
+			enrolledAt: sample.enrolledAt,
+			...sample.deviceId === void 0 ? {} : { deviceId: sample.deviceId },
+			comparable: true,
+			selfMean,
+			...foreign === void 0 ? {} : { bestForeign: foreign },
+			suspicion
+		};
+	});
+	rows.sort((a, b) => b.suspicion - a.suspicion);
+	return {
+		identityId: input.identityId,
+		totalSamples: input.samples.length,
+		comparableSamples: comparable.length,
+		flagged: rows.filter((r) => r.suspicion >= SUSPICION_FLAG).length,
+		rows
+	};
+}
+//#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";
@@ -32688,6 +32915,7 @@ var FaceGalleryProvider = class {
 	eventStore;
 	logger;
 	refreshGallery;
+	resolveClusterModelId;
 	eventMediaBaseUrl;
 	eventMediaPathPrefix;
 	emitFaceGalleryChanged;
@@ -32699,6 +32927,7 @@ var FaceGalleryProvider = class {
 		this.eventStore = deps.eventStore;
 		this.logger = deps.logger;
 		this.refreshGallery = deps.refreshGallery;
+		this.resolveClusterModelId = deps.resolveClusterModelId;
 		this.eventMediaBaseUrl = deps.eventMediaBaseUrl;
 		this.eventMediaPathPrefix = deps.eventMediaPathPrefix;
 		this.emitFaceGalleryChanged = deps.emitFaceGalleryChanged;
@@ -32775,6 +33004,67 @@ var FaceGalleryProvider = class {
 		}
 		return result;
 	}
+	/**
+	* Re-analyse one person's enrolled samples against the whole gallery.
+	*
+	* Reads every identity's samples and their vectors — 327 on this cluster —
+	* and ranks the target's own by how little they look like the rest of that
+	* person and how much they look like somebody else (`identity-audit.ts`).
+	* Dot products, no inference, no write.
+	*
+	* The whole gallery is loaded on purpose: the accusation that matters is
+	* "this looks like SOMEONE ELSE", and that cannot be computed from one
+	* person's samples.
+	*/
+	async auditIdentitySamples(input) {
+		const modelId = await this.resolveClusterModelId();
+		if (modelId === null) throw new Error("auditIdentitySamples: the cluster face-embedding model could not be resolved");
+		const identities = await this.identityStore.listIdentities();
+		const target = identities.find((i) => i.id === input.identityId);
+		if (target === void 0) throw new Error(`auditIdentitySamples: no identity ${input.identityId}`);
+		const samplesByIdentity = /* @__PURE__ */ new Map();
+		for (const identity of identities) samplesByIdentity.set(identity.id, await this.identityStore.listSamples(identity.id));
+		const vectors = await this.identityStore.loadSampleVectors([...samplesByIdentity.values()].flat().map((sample) => sample.id));
+		const inputsFor = (identityId) => (samplesByIdentity.get(identityId) ?? []).flatMap((sample) => {
+			const embedding = vectors.get(sample.id);
+			if (embedding === void 0) return [];
+			return [{
+				sampleId: sample.id,
+				embedding,
+				modelId: sample.modelId,
+				enrolledAt: sample.addedAt,
+				...sample.deviceId === void 0 ? {} : { deviceId: sample.deviceId }
+			}];
+		});
+		const report = auditIdentitySamples({
+			identityId: input.identityId,
+			samples: inputsFor(input.identityId),
+			others: identities.filter((identity) => identity.id !== input.identityId).map((identity) => ({
+				identityId: identity.id,
+				name: identity.name,
+				samples: inputsFor(identity.id)
+			})),
+			modelId
+		});
+		const meta = new Map((samplesByIdentity.get(input.identityId) ?? []).map((sample) => [sample.id, sample]));
+		return {
+			identityId: report.identityId,
+			name: target.name,
+			modelId,
+			totalSamples: report.totalSamples,
+			comparableSamples: report.comparableSamples,
+			flagged: report.flagged,
+			flagThreshold: SUSPICION_FLAG,
+			rows: report.rows.map((row) => {
+				const sample = meta.get(row.sampleId);
+				return {
+					...row,
+					source: sample?.source ?? "detected",
+					...sample?.mediaKey === void 0 ? {} : { mediaKey: sample.mediaKey }
+				};
+			})
+		};
+	}
 	async removeSample(input) {
 		const sample = (await this.identityStore.listSamples(input.identityId)).find((s) => s.id === input.sampleId);
 		if (sample?.mediaKey) await this.mediaStore.deleteByKey(sample.mediaKey);
@@ -37403,7 +37693,7 @@ var TrackCloser = class {
 	async maybePromoteLastFrame(t, ownedMedia) {
 		const promotion = decideLastFramePromotion(ownedMedia);
 		if (!promotion.promote) {
-			if (promotion.declinedBecause !== "already-last") this.deps.logger.warn("no lastFrame at close", {
+			if (promotion.declinedBecause === "no-key-frame") this.deps.logger.warn("no lastFrame at close", {
 				tags: { deviceId: t.deviceId },
 				meta: {
 					trackId: t.trackId,
@@ -59023,12 +59313,24 @@ var IdentityStore = class {
 				id: r.id,
 				source: d.source ?? "detected",
 				addedAt: Number(d.addedAt ?? 0),
+				modelId: String(d.modelId ?? ""),
 				...d.mediaKey != null ? { mediaKey: d.mediaKey } : {},
 				...d.sourceMediaKey != null ? { sourceMediaKey: d.sourceMediaKey } : {},
 				...d.deviceId != null ? { deviceId: d.deviceId } : {}
 			};
 		});
 	}
+	/**
+	* The enrolled vectors for these sample ids, straight off the index.
+	*
+	* Exposed because the gallery audit compares samples with each other, and
+	* `loadGallery` — the only other vector read — drops the sample id in favour
+	* of the identity id. An audit that cannot name the sample it accuses has
+	* nothing to offer a Remove button.
+	*/
+	async loadSampleVectors(sampleIds) {
+		return this.vectors.load(sampleIds);
+	}
 	async removeSample(identityId, sampleId) {
 		await this.store.delete.mutate({
 			collection: IDENTITY_SAMPLES_COLLECTION,
@@ -70940,9 +71242,13 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 	/**
 	* The store seam the `debug.*` actions and the debug bundle both read through.
 	*
-	* INDEX READS ONLY — three media-inventory queries and an event query per
-	* track, no blob. The bytes are fetched one at a time, by key, by the export
-	* handler, so a bundle of a hundred tracks never holds more than one file.
+	* Index reads, plus ONE existence probe per media row — never a blob. The
+	* probe is the only thing here that touches the filesystem, and it earns the
+	* trip: every index read in this file counts rows the two serving reads
+	* (`listByOwner`, `getByKey`) silently drop when the bytes are unreachable,
+	* so without it the tab reports tiles the viewer draws blank. The bytes
+	* themselves are still fetched one at a time, by key, by the export handler,
+	* so a bundle of a hundred tracks never holds more than one file.
 	*/
 	buildDebugServiceDeps() {
 		const trackStore = this.trackStore;
@@ -70956,6 +71262,7 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 			listMediaInfo: (ownerKind, ownerId) => mediaStore.listInfoByOwner(ownerKind, ownerId),
 			listEvents: (trackId) => eventStore.queryObjectByTrackIds([trackId]),
 			trackThumbnailProvenance: (trackId) => mediaStore.trackThumbnailProvenance(trackId),
+			probeMediaBlob: (key) => mediaStore.blobServable(key),
 			logger: this.ctx.logger.child("debug"),
 			now: () => Date.now()
 		};
@@ -71657,6 +71964,11 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 			eventStore: stores.eventStore,
 			logger: this.ctx.logger,
 			refreshGallery: () => this.faceRecognizer?.refreshGallery(),
+			resolveClusterModelId: async () => {
+				const api = this.ctx.api;
+				if (!api) return null;
+				return resolveClusterModelPin(api, FACE_EMBEDDING_STEP_ID, { warn: (m, e) => this.ctx.logger.warn(m, e) });
+			},
 			eventMediaBaseUrl: () => this.eventMediaBaseUrl,
 			eventMediaPathPrefix: () => this.eventMediaPathPrefix(),
 			emitFaceGalleryChanged: (payload) => this.emitFaceGalleryChanged(payload)