@camstack/addon-post-analysis 1.2.127 → 1.2.129

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-BarcMD8R.js");
+const require_dist = require("../dist-DFeeUt_t.js");
 let node_fs = require("node:fs");
 node_fs = require_dist.__toESM(node_fs, 1);
 let node_path = require("node:path");
@@ -27217,6 +27217,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 +27304,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 +27450,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 +27470,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 +29470,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. */
@@ -31823,11 +31931,13 @@ var MediaStore = class {
 	store;
 	logger;
 	writeGate;
+	resolveEventMediaLocation;
 	constructor(deps) {
 		this.storage = deps.storage;
 		this.store = deps.store;
 		this.logger = deps.logger;
 		this.writeGate = deps.writeGate;
+		this.resolveEventMediaLocation = deps.resolveEventMediaLocation;
 	}
 	gated(mutation) {
 		return this.writeGate ? this.writeGate.run(mutation) : mutation();
@@ -31848,7 +31958,8 @@ var MediaStore = class {
 	async putUnchecked(params) {
 		const key = buildKey(params);
 		const path = buildPath(params);
-		const location = locationForOwnerKind(params.ownerKind);
+		const staticLocation = locationForOwnerKind(params.ownerKind);
+		const location = staticLocation === "eventMedia" && this.resolveEventMediaLocation ? await this.resolveEventMediaLocation(params.deviceId) : staticLocation;
 		const record = {
 			deviceId: params.deviceId,
 			ownerKind: params.ownerKind,
@@ -41541,6 +41652,21 @@ var MediaCaptureLogAggregator = class {
 	}
 };
 //#endregion
+//#region src/pipeline-analytics/media-locations.ts
+/**
+* Picks the location a new `eventMedia` blob should be written to, or `null`
+* when none is writable — the caller MUST refuse the write rather than fall
+* back to a read-only location, which would fail far downstream as an opaque
+* filesystem error instead of a named storage decision.
+*/
+function pickWritableMediaLocation(locations, currentDefaultId) {
+	const writable = locations.filter((l) => l.enabled && !l.readOnly);
+	if (writable.length === 0) return null;
+	const keep = writable.find((l) => l.id === currentDefaultId);
+	if (keep) return keep.id;
+	return writable.toSorted((a, b) => b.headroomBytes - a.headroomBytes)[0]?.id ?? null;
+}
+//#endregion
 //#region src/pipeline-analytics/media-relocate-engine.ts
 var PAGE_SIZE = 200;
 var DEFAULT_THROTTLE_MBPS = 40;
@@ -47611,6 +47737,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
@@ -57034,6 +57191,144 @@ function rowFromMetadata(id, metadata) {
 	};
 }
 //#endregion
+//#region src/pipeline-analytics/store/settings-raw-mirror.ts
+/** How long a mirrored entry is served before a refresh is started behind the
+*  next reader. See the module doc for why this matches the per-kind caches'
+*  own window rather than introducing a second staleness bound. */
+var RAW_SETTINGS_STALE_MS = 5e3;
+/**
+* How long a FAILED refresh is not retried.
+*
+* A refresh that throws leaves `fetchedAt` where it was, so without a
+* cooldown every subsequent reader would start another attempt — a broken
+* settings store would be hammered at frame rate by the very mechanism built
+* to stop that.
+*/
+var RAW_SETTINGS_MISS_COOLDOWN_MS = 5e3;
+/**
+* The addon's per-device raw blob (`pipeline-analytics:addon-devices`), kept
+* fresh OFF every per-kind settings cache's hot path.
+*
+* `resolve` is COLD-awaiting and single-flight: a burst of settings kinds
+* (or frames) missing on the same device in the same tick costs ONE read,
+* not one per caller — the exact failure this class exists to remove.
+*/
+var RawDeviceBlobMirror = class {
+	deps;
+	staleMs;
+	missCooldownMs;
+	entries = /* @__PURE__ */ new Map();
+	inFlight = /* @__PURE__ */ new Map();
+	now;
+	constructor(deps, staleMs = RAW_SETTINGS_STALE_MS, missCooldownMs = RAW_SETTINGS_MISS_COOLDOWN_MS) {
+		this.deps = deps;
+		this.staleMs = staleMs;
+		this.missCooldownMs = missCooldownMs;
+		this.now = deps.now ?? (() => Date.now());
+	}
+	/**
+	* The device's raw stored blob.
+	*
+	* COLD awaits — the first settings kind to touch a device has to get the
+	* real answer. WARM returns immediately, stale or not, and starts the
+	* refresh behind the caller.
+	*/
+	async resolve(deviceId) {
+		const entry = this.entries.get(deviceId);
+		if (entry === void 0) return this.load(deviceId);
+		if (this.now() - entry.fetchedAt >= this.staleMs) this.load(deviceId);
+		return entry.value;
+	}
+	/** Drop a device's entry. Called by every in-process writer of this
+	*  device's row, so an operator's own change is never served stale. */
+	invalidate(deviceId) {
+		this.entries.delete(deviceId);
+	}
+	invalidateAll() {
+		this.entries.clear();
+	}
+	async load(deviceId) {
+		const pending = this.inFlight.get(deviceId);
+		if (pending !== void 0) return pending;
+		const run = this.deps.read(deviceId).then((value) => {
+			this.entries.set(deviceId, {
+				value,
+				fetchedAt: this.now()
+			});
+			return value;
+		}).catch((err) => {
+			this.deps.onRefreshFailed?.(deviceId, err);
+			const existing = this.entries.get(deviceId);
+			if (existing !== void 0) {
+				existing.fetchedAt = this.now() - this.staleMs + this.missCooldownMs;
+				return existing.value;
+			}
+			return {};
+		}).finally(() => {
+			this.inFlight.delete(deviceId);
+		});
+		this.inFlight.set(deviceId, run);
+		return run;
+	}
+};
+/**
+* The addon's ONE `addon_settings` row (`pipeline-analytics:addon-settings`),
+* kept fresh OFF every per-kind settings cache's hot path. Same shape as
+* {@link RawDeviceBlobMirror}, singleton rather than keyed — there is exactly
+* one addon store per process.
+*/
+var RawGlobalStoreMirror = class {
+	deps;
+	staleMs;
+	missCooldownMs;
+	entry = null;
+	inFlight = null;
+	now;
+	constructor(deps, staleMs = RAW_SETTINGS_STALE_MS, missCooldownMs = RAW_SETTINGS_MISS_COOLDOWN_MS) {
+		this.deps = deps;
+		this.staleMs = staleMs;
+		this.missCooldownMs = missCooldownMs;
+		this.now = deps.now ?? (() => Date.now());
+	}
+	async resolve() {
+		const entry = this.entry;
+		if (entry === null) return this.load();
+		if (this.now() - entry.fetchedAt >= this.staleMs) this.load();
+		return entry.value;
+	}
+	/** Drop the mirrored store. Called by every in-process global-settings
+	*  writer (`onConfigChanged`), so an operator's own change is never served
+	*  stale. */
+	invalidate() {
+		this.entry = null;
+	}
+	async load() {
+		if (this.inFlight !== null) return this.inFlight;
+		const run = this.deps.read().then((value) => {
+			this.entry = {
+				value,
+				fetchedAt: this.now()
+			};
+			return value;
+		}).catch((err) => {
+			this.deps.onRefreshFailed?.(err);
+			const existing = this.entry;
+			if (existing !== null) {
+				this.entry = {
+					value: existing.value,
+					fetchedAt: this.now() - this.staleMs + this.missCooldownMs
+				};
+				return existing.value;
+			}
+			return {};
+		}).finally(() => {
+			this.inFlight = null;
+		});
+		this.inFlight = run;
+		return run;
+	}
+};
+//#endregion
 //#region src/pipeline-analytics/track-retention-sweep.ts
 /**
 * Sweep every device with persisted tracks: skip retention-disabled devices,
@@ -58090,6 +58385,14 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 	/** Event-media relocation engine (entity-routing Phase 4). */
 	mediaRelocate = null;
 	mediaLocationStorage = null;
+	/**
+	* Cached pick for NEW `eventMedia` writes (`pickWritableMediaLocation`).
+	* Resolved once, never per blob (no-RPC-per-blob, same discipline as
+	* `mediaLocationStorage`'s own root cache) — dropped together with it by
+	* `refreshStorageLocationsForMigration`, since a location's `readOnly` /
+	* `enabled` flags only change via operator reconfig.
+	*/
+	eventMediaWriteLocationCache = null;
 	mediaWriteGate = new MediaWriteGate();
 	storageMigrationLeaseId = null;
 	/** Per-camera history of LINKED-device sensor state changes (Part B). */
@@ -58489,6 +58792,33 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 	audioEpisodeTracks = /* @__PURE__ */ new Map();
 	audioEpisodeLastPersistMs = /* @__PURE__ */ new Map();
 	settingsCaches = new DeviceSettingsCacheHub();
+	/**
+	* The addon-level store and per-device blob, mirrored ONCE and shared by
+	* every settings kind above — see `store/settings-raw-mirror.ts`. Before
+	* this, each kind's cache miss called `resolveGlobalStore()` +
+	* `readDeviceBlob()` directly, so eight kinds expiring in the same window
+	* paid for the same two reads eight times: `get
+	* pipeline-analytics:addon-settings` at 547–694/min, `get
+	* pipeline-analytics:addon-devices` at ~700/min, live 2026-08-26. Invalidated
+	* by every in-process writer: `applyDeviceSettingsPatch` and the retired-
+	* setting purges drop the device mirror, `onConfigChanged` (this process's
+	* own `updateGlobalSettings`) drops the global mirror.
+	*/
+	rawDeviceBlobMirror = new RawDeviceBlobMirror({
+		read: (deviceId) => this.readDeviceBlob(deviceId),
+		onRefreshFailed: (deviceId, err) => {
+			this.ctx.logger.debug("raw device-blob mirror refresh failed — serving last value", {
+				tags: { deviceId },
+				meta: { error: err instanceof Error ? err.message : String(err) }
+			});
+		}
+	});
+	rawGlobalStoreMirror = new RawGlobalStoreMirror({
+		read: () => this.resolveGlobalStore(),
+		onRefreshFailed: (err) => {
+			this.ctx.logger.debug("raw global-store mirror refresh failed — serving last value", { meta: { error: err instanceof Error ? err.message : String(err) } });
+		}
+	});
 	/** Avoids a store read every ~30 Hz audio frame. */
 	audioSettingsCache = this.settingsCaches.registerDeviceCache("audio-detection", SETTINGS_CACHE_TTL_MS);
 	sensitivitySettingsCache = this.settingsCaches.registerDeviceCache("detection-sensitivity", SETTINGS_CACHE_TTL_MS);
@@ -59208,6 +59538,53 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 		this.mediaLocationStorage = routed;
 		return routed;
 	}
+	/**
+	* Resolves which `eventMedia` location a NEW footage-class blob should be
+	* written to (`MediaStoreDeps.resolveEventMediaLocation`). Reflects
+	* `config.readOnly` — an operator draining a location marks it read-only,
+	* and new writes must never land there (the relocate mover, exposed as
+	* `relocateMedia`, empties what is already on it in the background).
+	*
+	* Cached after the first successful resolution — this is a per-blob write
+	* path, and the write-side provider is a declared no-RPC-per-blob bypass
+	* (D-note in `location-aware-media-storage.ts`); re-querying the storage
+	* cap on every blob would undo that. Dropped by
+	* `refreshStorageLocationsForMigration`, same trigger as
+	* `mediaLocationStorage.invalidateRoots()`.
+	*
+	* Degrades to the bare `eventMedia` type ref (pre-2026-08-26 behaviour)
+	* when the storage cap itself is unreachable — a transient RPC failure (or
+	* a test harness that never wires `api.storage`) must not turn every media
+	* write into a hard failure the way "no writable location" does.
+	*/
+	async resolveEventMediaWriteLocation(api, logger, deviceId) {
+		const cached = this.eventMediaWriteLocationCache;
+		if (cached !== null) return cached;
+		let locations;
+		try {
+			locations = await api.storage.listLocations.query({ type: DEFAULT_MEDIA_LOCATION });
+		} catch (err) {
+			logger.debug("pipeline-analytics: eventMedia location list unavailable — writing through the default ref", { meta: { error: require_dist.errMsg(err) } });
+			this.eventMediaWriteLocationCache = DEFAULT_MEDIA_LOCATION;
+			return DEFAULT_MEDIA_LOCATION;
+		}
+		const picked = pickWritableMediaLocation(locations.map((l) => ({
+			id: l.id,
+			readOnly: l.config["readOnly"] === true,
+			enabled: l.enabled !== false,
+			headroomBytes: l.capacity?.availableBytes ?? 0
+		})), locations.find((l) => l.isDefault)?.id ?? "eventMedia");
+		if (picked === null) {
+			const seen = locations.length > 0 ? locations.map((l) => l.id).join(", ") : "(none registered)";
+			logger.error("pipeline-analytics: no writable eventMedia storage location — refusing the write instead of failing far downstream as a filesystem error", {
+				tags: { deviceId },
+				meta: { locationsSeen: seen }
+			});
+			throw new Error(`no writable eventMedia storage location (seen: ${seen})`);
+		}
+		this.eventMediaWriteLocationCache = picked;
+		return picked;
+	}
 	/** Constructs every SQLite-backed store plus the stationary/package-drop/
 	*  sensor plumbing, in the exact pre-S7 order. Returns the non-null bundle
 	*  so the rest of boot consumes the stores without re-narrowing. */
@@ -59266,7 +59643,8 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 			storage,
 			store: api.settingsStore,
 			logger: logger.child("MediaStore"),
-			writeGate: this.mediaWriteGate
+			writeGate: this.mediaWriteGate,
+			resolveEventMediaLocation: (deviceId) => this.resolveEventMediaWriteLocation(api, logger, deviceId)
 		});
 		this.mediaStore = mediaStore;
 		const retrainFrames = new RetrainFrameStore({
@@ -60299,6 +60677,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);
 	}
@@ -60574,6 +60967,7 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 			this.forgetDeviceProcessors(data.deviceId);
 			this.levelStateByDevice.delete(data.deviceId);
 			this.settingsCaches.clearDevice(data.deviceId);
+			this.rawDeviceBlobMirror.invalidate(data.deviceId);
 		}
 	}
 	/** `DeviceUnregistered` handler — subscription topology lives in
@@ -60598,6 +60992,7 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 		}
 		this.audioMarkers?.forgetDevice(deviceId);
 		this.settingsCaches.clearDevice(deviceId);
+		this.rawDeviceBlobMirror.invalidate(deviceId);
 		this.bindingCache?.invalidate(deviceId);
 		this.detectionCoverage?.forget(deviceId);
 		this.zoneAnalytics?.forgetDevice(deviceId);
@@ -61026,6 +61421,17 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 			}] : []
 		];
 	}
+	/**
+	* `BaseAddon.updateGlobalSettings` calls this after the write lands —
+	* gated to the LOCAL node's own write (a sibling-node write returns before
+	* reaching it), which is exactly the scope `rawGlobalStoreMirror` needs to
+	* invalidate: the mirror only ever answers for THIS process, so it only
+	* needs to drop on THIS process's own write (D224).
+	*/
+	async onConfigChanged() {
+		await super.onConfigChanged();
+		this.rawGlobalStoreMirror.invalidate();
+	}
 	async onShutdown() {
 		this.shuttingDown = true;
 		this.sceneEngine?.stop();
@@ -61081,6 +61487,8 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 		this.gatedNodeByDevice.clear();
 		this.levelStateByDevice.clear();
 		this.settingsCaches.clearAll();
+		this.rawDeviceBlobMirror.invalidateAll();
+		this.rawGlobalStoreMirror.invalidate();
 		this.confirmationDetectorStepByNode.clear();
 		this.trackStore?.clearAll();
 		this.stationaryRegistry = null;
@@ -61793,10 +62201,16 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 	*  auto-assigning — see `__tests__/global-settings-cascade.spec.ts`).
 	*  `resolveGlobalStore()` is the sanctioned BaseAddon read (per-node
 	*  projection applied; a raw `readAddonStore` would leak `@node` keys if a
-	*  perNode field is ever declared). */
+	*  perNode field is ever declared).
+	*
+	*  Both raw reads go through `rawGlobalStoreMirror` / `rawDeviceBlobMirror`
+	*  rather than straight to the store: this method is the ONE place all
+	*  eight settings kinds funnel through on a cache miss, so calling the raw
+	*  reads directly here means eight kinds expiring in the same window each
+	*  pay for the same two reads — see `store/settings-raw-mirror.ts`. */
 	async readDeviceSettings(deviceId, resolve) {
-		const globalRaw = this.ctxIfReady !== null ? await this.resolveGlobalStore() : {};
-		const deviceRaw = await this.readDeviceBlob(deviceId);
+		const globalRaw = this.ctxIfReady !== null ? await this.rawGlobalStoreMirror.resolve() : {};
+		const deviceRaw = await this.rawDeviceBlobMirror.resolve(deviceId);
 		return resolve({
 			...globalRaw,
 			...deviceRaw
@@ -63467,6 +63881,7 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 					});
 				}
 				await settings.writeDeviceStore(deviceId, plan.patch);
+				this.rawDeviceBlobMirror.invalidate(deviceId);
 			} catch (err) {
 				this.retiredSettingsChecked.delete(deviceId);
 				this.ctx.logger.warn("retired retention settings migration failed — will retry", {
@@ -63538,6 +63953,7 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 					deviceId
 				});
 				await settings.writeDeviceStore(deviceId, plan.patch);
+				this.rawDeviceBlobMirror.invalidate(deviceId);
 			} catch (err) {
 				this.storedSuggestionCheckedDevices.delete(deviceId);
 				this.ctx.logger.warn("face suggestion threshold purge failed — will retry", {
@@ -65225,6 +65641,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;
@@ -65267,6 +65690,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: {
@@ -65280,7 +65704,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 {
@@ -65684,6 +66109,7 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 	async refreshStorageLocationsForMigration(input) {
 		if (this.storageMigrationLeaseId !== input.leaseId) throw new Error("event-media storage migration lease does not match");
 		this.mediaLocationStorage?.invalidateRoots();
+		this.eventMediaWriteLocationCache = null;
 		return { refreshed: true };
 	}
 	async startStorageMigrationMove(input) {
@@ -65697,6 +66123,32 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 	async cancelStorageMigrationMove(input) {
 		return { cancelled: this.mediaRelocate?.cancel(input.jobId) ?? false };
 	}
+	/**
+	* Move event media between locations — the OPERATOR's mover, no lease.
+	* Twin of `recording.relocateFootage`: same engine (`this.mediaRelocate`)
+	* the lease-gated coordinator move uses, runnable in the background
+	* without pausing anything. `startStorageMigrationMove` above stays
+	* lease-gated for the orchestrated migration; this method must never touch
+	* `storageMigrationLeaseId`.
+	*/
+	async relocateMedia(input) {
+		if (!this.mediaRelocate) throw new Error("media relocation unavailable");
+		const jobId = this.mediaRelocate.start(input);
+		this.ctx.logger.info("pipeline-analytics: media relocate job enqueued", { meta: {
+			jobId,
+			to: input.toLocationId
+		} });
+		return { jobId };
+	}
+	/** Every relocate job this addon knows about, newest first (in RAM: the
+	*  move is resumable, so a lost list costs nothing but the display). */
+	async listRelocateMediaJobs() {
+		return this.mediaRelocate?.list() ?? [];
+	}
+	/** Cancel a running or queued relocate job. */
+	async cancelRelocateMedia(input) {
+		return { cancelled: this.mediaRelocate?.cancel(input.jobId) ?? false };
+	}
 	async listOpsLog(input) {
 		return this.queryFacade.listOpsLog(input);
 	}
@@ -66090,6 +66542,7 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_dist.B
 	}
 	async applyDeviceSettingsPatch(input) {
 		await this.updateDeviceSettings(input.deviceId, input.patch);
+		this.rawDeviceBlobMirror.invalidate(input.deviceId);
 		this.audioSettingsCache.delete(input.deviceId);
 		this.sensitivitySettingsCache.delete(input.deviceId);
 		this.trackingSettingsCache.delete(input.deviceId);