@camstack/addon-post-analysis 1.2.612 → 1.2.614

package/dist/pipeline-analytics/index.js

@@ -2,7 +2,7 @@ Object.defineProperties(exports, {
 	__esModule: { value: true },
 	[Symbol.toStringTag]: { value: "Module" }
 });
-const require_clip_model_registry = require("../clip-model-registry-C7WMvftu.js");
+const require_clip_model_registry = require("../clip-model-registry-CM-m6e1l.js");
 let node_fs = require("node:fs");
 node_fs = require_clip_model_registry.__toESM(node_fs, 1);
 let node_path = require("node:path");
@@ -9499,7 +9499,9 @@ var MigrationMarkerBodySchema = require_clip_model_registry.object({
 });
 /** The orphan audit's resume position: one row, the whole map in one value on purpose. */
 var SweepCursorBodySchema = require_clip_model_registry.object({
-	scopes: require_clip_model_registry.record(require_clip_model_registry.string(), require_clip_model_registry.number()),
+	/** A number is an offset (a settings-store scope); a string is the records
+	*  engine's opaque keyset cursor (a scope walked through its kind). */
+	scopes: require_clip_model_registry.record(require_clip_model_registry.string(), require_clip_model_registry.union([require_clip_model_registry.number(), require_clip_model_registry.string()])),
 	/** Absent on a row written before the walk existed — absent means "from the top". */
 	faceVectorCursor: require_clip_model_registry.number().optional(),
 	/** One cursor per CLIP index, keyed by index name. Absent on an older row. */
@@ -9973,7 +9975,7 @@ var pipelineAnalyticsRecordKinds = require_clip_model_registry.defineRecordKinds
 //#endregion
 //#region src/pipeline-analytics/scene/scene-config-ledger.ts
 /** The engine's page cap for one query; a reseed pages by it, bounded by the ledger limit. */
-var PAGE_SIZE$1 = 1e3;
+var PAGE_SIZE$2 = 1e3;
 /**
 * A row whose monitor JSON no longer validates is SKIPPED, not repaired: a
 * half-parsed scene would report a verdict about a region it cannot describe.
@@ -10011,7 +10013,7 @@ var SceneConfigLedger = class {
 			let seen = 0;
 			let cursor;
 			for (;;) {
-				const limit = Math.min(PAGE_SIZE$1, this.loadLimit - seen);
+				const limit = Math.min(PAGE_SIZE$2, this.loadLimit - seen);
 				if (limit <= 0) break;
 				const page = await this.kind.query({
 					limit,
@@ -12058,6 +12060,28 @@ var EventLedgerCollection = class EventLedgerCollection {
 		if (mapped.limit !== void 0 && out.length > mapped.limit) return out.slice(0, mapped.limit);
 		return out;
 	}
+	/**
+	* One page of the whole kind in `id` order, resumed from the records
+	* engine's OPAQUE keyset cursor (`null` = from the top). The answer's
+	* `nextCursor` is `null` at the end. A keyset cursor names the last row
+	* read, so deleting rows behind it never shifts what comes next — the
+	* reason a bulk walk that reclaims as it goes needs this, not an offset.
+	*
+	* Records only: without `ctx.records` the caller pages the settings store
+	* itself, and asking here throws rather than inventing a cursor.
+	*/
+	async pageById(cursor, limit) {
+		if (this.kind === null) throw new Error(`event ledger ${this.collection}: pageById needs the records kind`);
+		const page = await this.kind.query({
+			order: "id",
+			limit,
+			...cursor === null ? {} : { cursor }
+		});
+		return {
+			rows: page.records.map((row) => recordsRowToLegacy(row, this.legacyAtField)),
+			nextCursor: page.nextCursor
+		};
+	}
 	async getManyByIds(ids) {
 		if (ids.length === 0) return [];
 		if (this.kind === null) return (await this.store.query.query({
@@ -13184,11 +13208,35 @@ var FaceStore = class {
 	* carries no `embeddingModelId`, and those rows were all `arcface-r100`, so
 	* that is what they are stamped with — a KNOWN historical fact, not a
 	* fallback guess. A row that names some other model keeps its own.
+	*
+	* On a records hub the rows are paged through the faces LEDGER: the legacy
+	* table is dropped there, and the adoption copied each row's body whole —
+	* an `embedding` the pass had not drained yet included — so a records-era
+	* row can still need converting (the same shape as `IdentityStore`).
 	*/
 	conversionSpec() {
+		const ledger = this.ledger;
+		const recordsPaging = ledger.usesRecords ? {
+			pageRows: (limit, offset) => ledger.query({
+				orderBy: {
+					field: "id",
+					direction: "asc"
+				},
+				limit,
+				offset
+			}, [
+				"deviceId",
+				"timestamp",
+				"trackId",
+				"embeddingModelId",
+				"embedding"
+			]),
+			drainEmbedding: (id) => ledger.update(id, { embedding: [] })
+		} : {};
 		return {
 			collection: FACES_COLLECTION,
 			vectors: this.vectors,
+			...recordsPaging,
 			write: (id, embedding, data) => {
 				const deviceId = data["deviceId"];
 				const timestamp = data["timestamp"];
@@ -67474,7 +67522,7 @@ async function settleReplaced(deps, sample, replacement, dryRun) {
 	});
 	return "old-removal-retried";
 }
-function tally$1(samples, outcomes, dryRun) {
+function tally$2(samples, outcomes, dryRun) {
 	const count = (kind) => outcomes.filter((o) => o.outcome === kind).length;
 	const refusals = [];
 	for (const o of outcomes) if (o.outcome === "refused" && o.reason !== void 0) refusals.push({
@@ -67546,7 +67594,7 @@ async function reenrolPhotoSamples(deps, options) {
 		outcomes.push(outcomeOf(sample, verdict));
 		await deps.pause(pacingMs);
 	}
-	const result = tally$1(samples, outcomes, dryRun);
+	const result = tally$2(samples, outcomes, dryRun);
 	if (!dryRun && (result.reenrolled > 0 || result.oldRemovalRetried > 0)) await deps.refreshGallery();
 	const { outcomes: _perSample, ...summary } = result;
 	deps.logger.info("face photo re-enrol finished", { meta: { ...summary } });
@@ -78963,24 +79011,11 @@ function createDiscardJob(deps) {
 			});
 			await sleep(0);
 		}
-		for (;;) {
+		const retrainIds = (await deps.retrainFrameLedger.query({})).filter((row) => row.data["locationId"] === locationId).map((row) => row.id);
+		for (let i = 0; i < retrainIds.length; i += MEDIA_PAGE) {
 			if (cancelRequested) return owners;
-			const rows = await deps.store.query.query({
-				collection: RETRAIN_FRAMES_COLLECTION,
-				columns: ["id"],
-				filter: {
-					where: { locationId },
-					limit: MEDIA_PAGE
-				}
-			});
-			if (rows.length === 0) break;
-			for (const row of rows) {
-				await deps.store.delete.mutate({
-					collection: RETRAIN_FRAMES_COLLECTION,
-					key: row.id
-				});
-				deleted += 1;
-			}
+			const page = retrainIds.slice(i, i + MEDIA_PAGE);
+			deleted += await deps.retrainFrameLedger.deleteByIds(page);
 			report({
 				dbRowsDeleted: deleted,
 				detail: `deleted ${deleted} media/retrain rows`
@@ -79032,6 +79067,383 @@ function createDiscardJob(deps) {
 	};
 }
 //#endregion
+//#region src/pipeline-analytics/retention/media-forget-actions.ts
+/**
+* The operator door for the NARROW media-row forget (`media-row-forget.ts`).
+*
+* It forgets `pipeline-analytics:media` rows stamped with ONE location whose
+* file is provably gone, and nothing else: no event, track, object-event,
+* face, plate or identity row is read for deletion, ever. Contrast
+* `storage.discardLocation`, which wipes the disk AND cascades owners.
+*
+* `dryRun` defaults to `true`: an unstated intent destroys nothing. Applying
+* also requires `expectAbsent` — the `absent` count a dry run just reported —
+* so the forget only ever deletes a population a human has already read.
+*/
+/** Hard ceiling on rows one call examines — the call is synchronous. */
+var MEDIA_FORGET_MAX_ROWS = 5e4;
+var MediaForgetInputSchema = require_clip_model_registry.object({
+	locationId: require_clip_model_registry.string().min(1),
+	/** Restrict to these cameras. Omitted = every row stamped with the location. */
+	deviceIds: require_clip_model_registry.array(require_clip_model_registry.number().int()).min(1).optional(),
+	dryRun: require_clip_model_registry.boolean().default(true),
+	/**
+	* Required when `dryRun` is false: the `totals.absent` of the dry run. A
+	* different count at apply time refuses the whole call before any delete.
+	*/
+	expectAbsent: require_clip_model_registry.number().int().nonnegative().optional(),
+	/** Rows examined in this call. Default and max {@link MEDIA_FORGET_MAX_ROWS}. */
+	maxRows: require_clip_model_registry.number().int().min(1).max(MEDIA_FORGET_MAX_ROWS).optional(),
+	/** Detailed rows returned per verdict. Default 20. */
+	sampleSize: require_clip_model_registry.number().int().min(0).max(500).optional()
+});
+var VerdictCountsSchema = require_clip_model_registry.object({
+	rows: require_clip_model_registry.number(),
+	/** File answered ENOENT — the only verdict that may be forgotten. */
+	absent: require_clip_model_registry.number(),
+	/** File is there: relocation is incomplete. Never forgotten. */
+	present: require_clip_model_registry.number(),
+	/** The stat failed with any errno other than ENOENT. Never forgotten. */
+	error: require_clip_model_registry.number(),
+	/** No path, a path escaping the root, or a retention-exempt owner. Never forgotten. */
+	kept: require_clip_model_registry.number(),
+	/** Rows actually deleted (0 on a dry run). */
+	deleted: require_clip_model_registry.number()
+});
+var MediaForgetSampleSchema = require_clip_model_registry.object({
+	mediaId: require_clip_model_registry.number(),
+	deviceId: require_clip_model_registry.number(),
+	kind: require_clip_model_registry.string(),
+	ownerKind: require_clip_model_registry.string(),
+	ownerId: require_clip_model_registry.string(),
+	path: require_clip_model_registry.string(),
+	/** The errno (error) or the reason (kept); absent otherwise. */
+	reason: require_clip_model_registry.string().optional()
+});
+var MediaForgetResultSchema = require_clip_model_registry.object({
+	locationId: require_clip_model_registry.string(),
+	dryRun: require_clip_model_registry.boolean(),
+	root: require_clip_model_registry.string(),
+	/** Rows of this location that were not examined because `maxRows` was hit. */
+	truncated: require_clip_model_registry.boolean(),
+	totals: VerdictCountsSchema,
+	byDevice: require_clip_model_registry.array(VerdictCountsSchema.extend({ deviceId: require_clip_model_registry.number() })),
+	byKind: require_clip_model_registry.array(VerdictCountsSchema.extend({ kind: require_clip_model_registry.string() })),
+	/** Every id the call deletes (dry run: would delete). The exact list. */
+	absentIds: require_clip_model_registry.array(require_clip_model_registry.number()),
+	samples: require_clip_model_registry.object({
+		absent: require_clip_model_registry.array(MediaForgetSampleSchema),
+		present: require_clip_model_registry.array(MediaForgetSampleSchema),
+		error: require_clip_model_registry.array(MediaForgetSampleSchema),
+		kept: require_clip_model_registry.array(MediaForgetSampleSchema)
+	}),
+	/** Absent at classification, no longer ENOENT at delete time: kept. */
+	changedBeforeDelete: require_clip_model_registry.number()
+});
+var mediaForgetActions = require_clip_model_registry.defineCustomActions({ "storage.forgetMissingMedia": require_clip_model_registry.customAction(MediaForgetInputSchema, MediaForgetResultSchema, {
+	kind: "mutation",
+	auth: "admin"
+}) });
+//#endregion
+//#region src/pipeline-analytics/retention/media-row-forget.ts
+/**
+* The NARROW media-row forget: delete `pipeline-analytics:media` rows stamped
+* with ONE storage location whose file is provably gone — and nothing else.
+*
+* Why it exists: a location whose bytes were lost keeps rows naming it, and a
+* cascading cleanup is not an acceptable way to clear them. `reconcileFromDisk`
+* once cascaded ~132 k events away from a read it did not double-check. Here:
+*
+*  - **Only media rows.** No event, track, object-event, face, plate or
+*    identity row is deleted. A parent keeps existing with that media kind
+*    missing — which is exactly what it already serves (`getBytesById` answers
+*    `null` for a missing row as it does for a missing blob).
+*  - **Only `ENOENT` is absence (D49).** Each row's file is `stat`ed under the
+*    location's own root on THIS node. Any other errno keeps the row and is
+*    reported; a present file keeps the row and is reported (relocation is
+*    incomplete). A row with no path, a path that escapes the root, or a
+*    retention-exempt owner (the enrolled gallery) is kept.
+*  - **Only rows stamped with the id.** `locationId IS NULL` rows mean
+*    "wherever eventMedia points now" and are never selected.
+*  - **Only a location nothing writes to.** An active (writable) location is
+*    refused: new rows could land while the walk runs.
+*  - **Dry run first, then the same count.** Applying requires
+*    `expectAbsent`; the whole population is classified before any delete,
+*    and a different absent count refuses the call with nothing written.
+*    Each id is re-`stat`ed right before its batch is deleted, and the delete
+*    predicate repeats `locationId`, so a row repointed in between survives.
+*
+* Occupancy needs no separate bookkeeping: `storage-occupancy` sums
+* `sizeBytes WHERE locationId = ?` on demand, so the row IS the accounting.
+*/
+var PAGE_SIZE$1 = 200;
+var DELETE_BATCH = 200;
+var DEFAULT_SAMPLE_SIZE = 20;
+function errnoOf(err) {
+	if (err instanceof Error && "code" in err && typeof err.code === "string") return err.code;
+	return err instanceof Error ? err.message : String(err);
+}
+function emptyCounts() {
+	return {
+		rows: 0,
+		absent: 0,
+		present: 0,
+		error: 0,
+		kept: 0,
+		deleted: 0
+	};
+}
+function tally$1(counts, verdict) {
+	const rows = counts.rows + 1;
+	switch (verdict) {
+		case "absent": return {
+			...counts,
+			rows,
+			absent: counts.absent + 1
+		};
+		case "present": return {
+			...counts,
+			rows,
+			present: counts.present + 1
+		};
+		case "error": return {
+			...counts,
+			rows,
+			error: counts.error + 1
+		};
+		case "kept": return {
+			...counts,
+			rows,
+			kept: counts.kept + 1
+		};
+	}
+}
+/** The file's absolute path under `root`, or `null` when it would escape it. */
+function resolveUnder(root, relativePath) {
+	const base = node_path.default.resolve(root);
+	const full = node_path.default.resolve(base, relativePath);
+	return full.startsWith(base + node_path.default.sep) ? full : null;
+}
+function toSample(id, data) {
+	return {
+		mediaId: Number(id),
+		deviceId: Number(data["deviceId"] ?? 0),
+		kind: String(data["kind"] ?? ""),
+		ownerKind: String(data["ownerKind"] ?? ""),
+		ownerId: String(data["ownerId"] ?? ""),
+		path: String(data["path"] ?? "")
+	};
+}
+async function probe(stat, absolutePath) {
+	try {
+		await stat(absolutePath);
+		return { verdict: "present" };
+	} catch (err) {
+		const code = errnoOf(err);
+		return code === "ENOENT" ? { verdict: "absent" } : {
+			verdict: "error",
+			reason: code
+		};
+	}
+}
+async function classify(stat, root, id, data) {
+	const sample = toSample(id, data);
+	const ownerKind = sample.ownerKind;
+	if (isMediaOwnerKind(ownerKind) && isRetentionExemptOwnerKind(ownerKind)) return {
+		key: id,
+		sample: {
+			...sample,
+			reason: "retention-exempt owner"
+		},
+		verdict: "kept",
+		absolutePath: null
+	};
+	if (sample.path.length === 0) return {
+		key: id,
+		sample: {
+			...sample,
+			reason: "no path"
+		},
+		verdict: "kept",
+		absolutePath: null
+	};
+	const absolutePath = resolveUnder(root, sample.path);
+	if (absolutePath === null) return {
+		key: id,
+		sample: {
+			...sample,
+			reason: "path escapes the root"
+		},
+		verdict: "kept",
+		absolutePath
+	};
+	const result = await probe(stat, absolutePath);
+	return {
+		key: id,
+		sample: result.reason === void 0 ? sample : {
+			...sample,
+			reason: result.reason
+		},
+		verdict: result.verdict,
+		absolutePath
+	};
+}
+function resolveTarget(locations, locationId, localNodeId) {
+	const location = locations.find((row) => row.id === locationId);
+	if (!location) throw new Error(`forgetMissingMedia refused: unknown location ${locationId}`);
+	if (location.type !== "eventMedia") throw new Error(`forgetMissingMedia refused: ${locationId} is ${location.type}, pipeline-analytics owns eventMedia rows only`);
+	if (require_clip_model_registry.mayWriteToLocation(location)) throw new Error(`forgetMissingMedia refused: ${locationId} is still a write target — set it to drain, readonly or disabled first`);
+	const nodeId = location.nodeId === void 0 || location.nodeId === "" ? "hub" : location.nodeId;
+	if (nodeId !== localNodeId) throw new Error(`forgetMissingMedia refused: ${locationId} lives on node ${nodeId}, this process is ${localNodeId}`);
+	return {
+		location,
+		root: locationBasePath(location)
+	};
+}
+/**
+* Classify every row stamped with `input.locationId` (bounded by `maxRows`),
+* and — only when `dryRun` is false and the absent count equals
+* `expectAbsent` — delete the absent ones, per camera, in batches.
+*/
+async function forgetMissingMediaRows(deps, rawInput) {
+	const input = MediaForgetInputSchema.parse(rawInput);
+	if (!input.dryRun && input.expectAbsent === void 0) throw new Error("forgetMissingMedia refused: an apply needs expectAbsent (the dry run’s totals.absent)");
+	const stat = deps.stat ?? ((p) => node_fs.promises.stat(p));
+	const pace = deps.pace ?? (() => new Promise((resolve) => setImmediate(resolve)));
+	const maxRows = input.maxRows ?? MEDIA_FORGET_MAX_ROWS;
+	const sampleSize = input.sampleSize ?? DEFAULT_SAMPLE_SIZE;
+	const { root } = resolveTarget(await deps.listLocations(), input.locationId, deps.localNodeId);
+	const classified = [];
+	let cursor = 0;
+	let truncated = false;
+	for (;;) {
+		const rows = await deps.store.query.query({
+			collection: MEDIA_COLLECTION,
+			columns: [
+				"id",
+				"deviceId",
+				"ownerKind",
+				"ownerId",
+				"kind",
+				"path"
+			],
+			filter: {
+				where: { locationId: input.locationId },
+				...input.deviceIds ? { whereIn: { deviceId: [...input.deviceIds] } } : {},
+				whereBetween: { id: [cursor + 1, Number.MAX_SAFE_INTEGER] },
+				orderBy: {
+					field: "id",
+					direction: "asc"
+				},
+				limit: PAGE_SIZE$1
+			}
+		});
+		if (rows.length === 0) break;
+		for (const row of rows) {
+			if (classified.length >= maxRows) {
+				truncated = true;
+				break;
+			}
+			classified.push(await classify(stat, root, row.id, row.data));
+			cursor = Math.max(cursor, Number(row.id));
+		}
+		if (truncated || rows.length < PAGE_SIZE$1) break;
+		await pace();
+	}
+	const absentRows = classified.filter((c) => c.verdict === "absent");
+	const deletedIds = /* @__PURE__ */ new Set();
+	let changedBeforeDelete = 0;
+	if (!input.dryRun) {
+		if (absentRows.length !== input.expectAbsent) throw new Error(`forgetMissingMedia refused: ${String(absentRows.length)} rows are absent now, expectAbsent was ${String(input.expectAbsent)} — run the dry run again; nothing was deleted`);
+		const byDevice = /* @__PURE__ */ new Map();
+		for (const row of absentRows) byDevice.set(row.sample.deviceId, [...byDevice.get(row.sample.deviceId) ?? [], row]);
+		for (const [deviceId, rows] of byDevice) for (let at = 0; at < rows.length; at += DELETE_BATCH) {
+			const batch = [];
+			for (const row of rows.slice(at, at + DELETE_BATCH)) if ((row.absolutePath === null ? null : await probe(stat, row.absolutePath))?.verdict === "absent") batch.push(row);
+			else changedBeforeDelete += 1;
+			if (batch.length === 0) continue;
+			const { deleted } = await deps.store.deleteWhere.mutate({
+				collection: MEDIA_COLLECTION,
+				filter: {
+					where: {
+						locationId: input.locationId,
+						deviceId
+					},
+					whereIn: { id: batch.map((row) => row.key) }
+				}
+			});
+			for (const row of batch) deletedIds.add(row.sample.mediaId);
+			deps.logger.info("forgetMissingMedia: forgot media rows whose file is gone", {
+				tags: { deviceId },
+				meta: {
+					locationId: input.locationId,
+					batch: batch.length,
+					deleted,
+					firstId: batch[0]?.sample.mediaId,
+					lastId: batch[batch.length - 1]?.sample.mediaId
+				}
+			});
+			if (deleted !== batch.length) deps.logger.warn("forgetMissingMedia: a batch deleted fewer rows than it named", {
+				tags: { deviceId },
+				meta: {
+					locationId: input.locationId,
+					batch: batch.length,
+					deleted
+				}
+			});
+			await pace();
+		}
+	}
+	let totals = emptyCounts();
+	const perDevice = /* @__PURE__ */ new Map();
+	const perKind = /* @__PURE__ */ new Map();
+	for (const row of classified) {
+		const isDeleted = deletedIds.has(row.sample.mediaId);
+		const bump = (c) => {
+			const next = tally$1(c, row.verdict);
+			return isDeleted ? {
+				...next,
+				deleted: next.deleted + 1
+			} : next;
+		};
+		totals = bump(totals);
+		perDevice.set(row.sample.deviceId, bump(perDevice.get(row.sample.deviceId) ?? emptyCounts()));
+		perKind.set(row.sample.kind, bump(perKind.get(row.sample.kind) ?? emptyCounts()));
+	}
+	const samplesOf = (verdict) => classified.filter((c) => c.verdict === verdict).slice(0, sampleSize).map((c) => c.sample);
+	for (const [deviceId, counts] of perDevice) deps.logger.info("forgetMissingMedia: per-camera verdict", {
+		tags: { deviceId },
+		meta: {
+			locationId: input.locationId,
+			dryRun: input.dryRun,
+			...counts
+		}
+	});
+	return {
+		locationId: input.locationId,
+		dryRun: input.dryRun,
+		root,
+		truncated,
+		totals,
+		byDevice: [...perDevice].map(([deviceId, c]) => ({
+			deviceId,
+			...c
+		})),
+		byKind: [...perKind].map(([kind, c]) => ({
+			kind,
+			...c
+		})),
+		absentIds: absentRows.map((r) => r.sample.mediaId),
+		samples: {
+			absent: samplesOf("absent"),
+			present: samplesOf("present"),
+			error: samplesOf("error"),
+			kept: samplesOf("kept")
+		},
+		changedBeforeDelete
+	};
+}
+//#endregion
 //#region src/pipeline-analytics/retention/media-reclaim.ts
 var MEDIA_RECLAIM_SCOPES = ["motion-still", "track-filmstrip"];
 var DEFAULT_MEDIA_RECLAIM_LIMITS = {
@@ -93359,17 +93771,8 @@ function rowIsGallery(data) {
 * D295 calls "a guard nobody believes".
 */
 function collectionsFor(mode) {
-	if (mode === "gallery") return [{
-		name: MEDIA_COLLECTION,
-		order: "timestamp"
-	}];
-	return [{
-		name: MEDIA_COLLECTION,
-		order: "timestamp"
-	}, {
-		name: RETRAIN_FRAMES_COLLECTION,
-		order: "copiedAt"
-	}];
+	if (mode === "gallery") return [{ lane: "media" }];
+	return [{ lane: "media" }, { lane: "retrainFrames" }];
 }
 /**
 * Does this pass act on this row at all?
@@ -93454,7 +93857,7 @@ var MediaRelocateEngine = class {
 	async countUnstamped() {
 		try {
 			const media = await this.countUnstampedIn(MEDIA_COLLECTION);
-			const retrainFrames = await this.countUnstampedIn(RETRAIN_FRAMES_COLLECTION);
+			const retrainFrames = await this.countUnstampedRetrainFrames();
 			return {
 				media,
 				retrainFrames,
@@ -93506,6 +93909,28 @@ var MediaRelocateEngine = class {
 			};
 		}
 	}
+	/**
+	* The retrain lane's unstamped population. The ledger's records `where` is
+	* equality-only (a `null` predicate is dropped, which would count the whole
+	* dataset), so the rows are read and judged by {@link rowIsUnstamped} — the
+	* dataset is operator-selected and small.
+	*/
+	async countUnstampedRetrainFrames() {
+		const rows = (await this.deps.retrainFrameLedger.query({})).filter((row) => rowIsUnstamped(row.data)).length;
+		return {
+			present: rows > 0,
+			rows
+		};
+	}
+	/** Every row of one lane, oldest-first. */
+	rowsOf(collection) {
+		return collection.lane === "media" ? this.pageRows(MEDIA_COLLECTION, "timestamp") : this.retrainFrameRows();
+	}
+	/** The retrain-frame ledger, read whole and yielded oldest copy first. */
+	async *retrainFrameRows() {
+		const ordered = (await this.deps.retrainFrameLedger.query({})).toSorted((a, b) => Number(a.data["copiedAt"] ?? 0) - Number(b.data["copiedAt"] ?? 0));
+		for (const row of ordered) yield row;
+	}
 	start(input) {
 		for (const j of this.jobs.values()) if (j.state === "running") throw new Error(`a media relocation is already running (${j.jobId})`);
 		this.cancelCensuses("a relocate pass started");
@@ -93609,22 +94034,22 @@ var MediaRelocateEngine = class {
 				let sealable = 0;
 				for (const collection of collectionsFor(mode)) {
 					if (stop()) return null;
-					sealable += await this.deps.store.count.query({
-						collection: collection.name,
+					sealable += collection.lane === "media" ? await this.deps.store.count.query({
+						collection: MEDIA_COLLECTION,
 						filter: { where: { [LOCATION_ID_FIELD]: null } }
-					});
+					}) : (await this.countUnstampedRetrainFrames()).rows ?? 0;
 				}
 				return { rows: sealable };
 			}
 			let rows = 0;
 			for (const collection of collectionsFor(mode)) {
-				const isRetrain = collection.name === RETRAIN_FRAMES_COLLECTION;
-				for await (const row of this.pageRows(collection.name, collection.order)) {
+				const isRetrain = collection.lane === "retrainFrames";
+				for await (const row of this.rowsOf(collection)) {
 					if (stop()) {
 						this.deps.logger.warn("media relocate: census stopped before it finished — reporting the residue as unknown, not as empty", { meta: {
 							mode,
 							toLocationId,
-							collection: collection.name
+							collection: collection.lane
 						} });
 						return null;
 					}
@@ -93632,7 +94057,7 @@ var MediaRelocateEngine = class {
 						this.deps.logger.warn("media relocate: census exceeded its budget — this collection is larger than a walk can answer", { meta: {
 							mode,
 							toLocationId,
-							collection: collection.name,
+							collection: collection.lane,
 							rowsVisited: budget.rowsVisited,
 							rowBudget: MEDIA_CENSUS_ROW_BUDGET,
 							deadlineMs: MEDIA_CENSUS_DEADLINE_MS
@@ -93668,15 +94093,15 @@ var MediaRelocateEngine = class {
 			if (job.mode === "seal") {
 				for (const collection of collectionsFor(job.mode)) {
 					if (job.cancelRequested) break;
-					await this.sealCollection(collection.name, job);
+					await this.sealCollection(collection, job);
 				}
 				job.state = job.cancelRequested ? "cancelled" : "done";
 				return;
 			}
 			for (const collection of collectionsFor(job.mode)) {
 				if (job.cancelRequested) break;
-				const isRetrain = collection.name === RETRAIN_FRAMES_COLLECTION;
-				for await (const row of this.pageRows(collection.name, collection.order)) {
+				const isRetrain = collection.lane === "retrainFrames";
+				for await (const row of this.rowsOf(collection)) {
 					if (job.cancelRequested) break;
 					const data = row.data;
 					if (!selectsRow(job.mode, job.toLocationId, data, isRetrain, job.fromLocationId)) continue;
@@ -93688,7 +94113,7 @@ var MediaRelocateEngine = class {
 					}
 					try {
 						if (await this.samePhysicalLocation(from, job.toLocationId)) {
-							await this.stamp(collection.name, row.id, data, job.toLocationId);
+							await this.stamp(collection, row.id, data, job.toLocationId);
 							continue;
 						}
 						const bytes = await this.deps.storage.read({
@@ -93704,7 +94129,7 @@ var MediaRelocateEngine = class {
 							location: job.toLocationId,
 							relativePath
 						})).length !== bytes.length) throw new Error(`relocated media size mismatch for ${relativePath}`);
-						await this.stamp(collection.name, row.id, data, job.toLocationId);
+						await this.stamp(collection, row.id, data, job.toLocationId);
 						await this.deps.storage.delete({
 							location: from,
 							relativePath
@@ -93715,7 +94140,7 @@ var MediaRelocateEngine = class {
 					} catch (err) {
 						failedRows++;
 						this.deps.logger.debug("media relocate row failed", { meta: {
-							collection: collection.name,
+							collection: collection.lane,
 							key: row.id,
 							error: String(err)
 						} });
@@ -93788,7 +94213,17 @@ var MediaRelocateEngine = class {
 	* reports a completed seal having stamped nothing. Zero unstamped rows is the
 	* single value the migration gate reads as "safe to cut over".
 	*/
-	async sealCollection(collection, job) {
+	async sealCollection(lane, job) {
+		if (lane.lane === "retrainFrames") {
+			for (const row of await this.deps.retrainFrameLedger.query({})) {
+				if (job.cancelRequested) return;
+				if (!rowIsUnstamped(row.data)) continue;
+				await this.deps.retrainFrameLedger.update(row.id, { [LOCATION_ID_FIELD]: job.toLocationId });
+				job.filesMoved += 1;
+			}
+			return;
+		}
+		const collection = MEDIA_COLLECTION;
 		for (;;) {
 			if (job.cancelRequested) return;
 			const batch = await this.deps.store.query.query({
@@ -93809,9 +94244,13 @@ var MediaRelocateEngine = class {
 			job.filesMoved += updated;
 		}
 	}
-	async stamp(collection, key, data, locationId) {
+	async stamp(lane, key, data, locationId) {
+		if (lane.lane === "retrainFrames") {
+			await this.deps.retrainFrameLedger.update(key, { [LOCATION_ID_FIELD]: locationId });
+			return;
+		}
 		await this.deps.store.set.mutate({
-			collection,
+			collection: MEDIA_COLLECTION,
 			key,
 			value: {
 				...data,
@@ -102258,6 +102697,18 @@ function decodeCursorMap(raw) {
 function nonNegativeInt(value) {
 	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? Math.floor(value) : null;
 }
+function decodeScopeCursors(raw) {
+	const out = {};
+	if (raw !== null && typeof raw === "object") for (const [key, cursor] of Object.entries({ ...raw })) {
+		if (typeof cursor === "string" && cursor.length > 0) {
+			out[key] = cursor;
+			continue;
+		}
+		const parsed = nonNegativeInt(cursor);
+		if (parsed !== null) out[key] = parsed;
+	}
+	return out;
+}
 /** Read a stored row back into a cursor map, ignoring anything unreadable. */
 function decodeOrphanAuditCursors(value) {
 	const empty = {
@@ -102269,7 +102720,7 @@ function decodeOrphanAuditCursors(value) {
 	if (value === null || typeof value !== "object") return empty;
 	const row = { ...value };
 	return {
-		scopes: decodeCursorMap(row["scopes"]),
+		scopes: decodeScopeCursors(row["scopes"]),
 		faceVectorCursor: nonNegativeInt(row["faceVectorCursor"]) ?? 0,
 		clipIndexCursors: decodeCursorMap(row["clipIndexCursors"]),
 		updatedAtMs: nonNegativeInt(row["updatedAtMs"]) ?? 0
@@ -103842,7 +104293,9 @@ async function auditScope(scope, deps, limits, cursor) {
 	};
 	const deviceIds = /* @__PURE__ */ new Set();
 	const graceFloor = deps.now() - limits.graceMs;
-	let offset = Math.max(0, cursor);
+	let offset = typeof cursor === "number" ? Math.max(0, cursor) : 0;
+	let keysetCursor = typeof cursor === "string" ? cursor : null;
+	let keyed = keysetCursor !== null;
 	let stoppedBy = "exhausted";
 	let collectionSize = null;
 	try {
@@ -103859,9 +104312,16 @@ async function auditScope(scope, deps, limits, cursor) {
 			stoppedBy = "row-ceiling";
 			break;
 		}
-		const rows = await deps.page(scope.collection, scope.shard, offset, limits.pageSize);
+		if (deps.stop?.() === true) {
+			stoppedBy = "stopped";
+			break;
+		}
+		const keyedPage = deps.pageKeyset === void 0 ? null : await deps.pageKeyset(scope.collection, keysetCursor, limits.pageSize);
+		keyed = keyedPage !== null;
+		const rows = keyedPage !== null ? keyedPage.rows : await deps.page(scope.collection, scope.shard, offset, limits.pageSize);
 		if (rows.length === 0) {
 			offset = 0;
+			keysetCursor = null;
 			break;
 		}
 		const refs = rows.map((row) => scope.resolve(row));
@@ -103948,9 +104408,17 @@ async function auditScope(scope, deps, limits, cursor) {
 		if (deps.breathe) await deps.breathe();
 		if (ceilingHit) {
 			stoppedBy = "reclaim-ceiling";
-			offset += rows.length - reclaimedInPage;
+			if (!keyed) offset += rows.length - reclaimedInPage;
 			break;
 		}
+		if (keyedPage !== null) {
+			if (keyedPage.nextCursor === null) {
+				keysetCursor = null;
+				break;
+			}
+			keysetCursor = keyedPage.nextCursor;
+			continue;
+		}
 		const advanced = rows.length - reclaimedInPage;
 		if (advanced === 0 && rows.length < limits.pageSize) {
 			offset = 0;
@@ -103966,7 +104434,7 @@ async function auditScope(scope, deps, limits, cursor) {
 		collectionSize,
 		coveragePercent: Math.round(tally.examined / collectionSize * 1e3) / 10,
 		stoppedBy,
-		nextCursor: offset
+		nextCursor: keyed ? keysetCursor ?? 0 : offset
 	} });
 	const freedNothing = scope.sizeField === null ? tally.reclaimed === 0 : tally.bytesReclaimed === 0;
 	if (limits.mode === "reclaim" && tally.orphans > 0 && freedNothing) deps.logger.warn("orphan audit: reclaim pass freed no bytes against a standing backlog", { meta: {
@@ -103993,7 +104461,7 @@ async function auditScope(scope, deps, limits, cursor) {
 		unresolvable: tally.unresolvable,
 		deviceIds: [...deviceIds],
 		stoppedBy,
-		nextCursor: offset
+		nextCursor: keyed ? keysetCursor ?? 0 : offset
 	};
 }
 /**
@@ -104085,7 +104553,8 @@ var ORPHAN_AUDIT_DEFAULTS = {
 //#endregion
 //#region src/pipeline-analytics/retention/orphan-reclaimers.ts
 var OBJECT_EVENTS_COLLECTION = "pipeline-analytics:object-events";
-var RAW_DELETE_COLLECTIONS = new Set([OBJECT_EVENTS_COLLECTION, "pipeline-analytics:plates"]);
+var PLATES_COLLECTION = "pipeline-analytics:plates";
+var RAW_DELETE_COLLECTIONS = new Set([OBJECT_EVENTS_COLLECTION]);
 /**
 * The `deleteRow` port: ONE row by its primary key `id` (what every
 * raw-delete collection above declares), answering whether a row went.
@@ -104159,6 +104628,13 @@ function buildOrphanReclaimer(ports) {
 			rows: await ports.deleteTrackAlias(key) ? 1 : 0,
 			bytes: null
 		};
+		if (collection === PLATES_COLLECTION) {
+			const assert = trackIdAssertOf(data);
+			return {
+				rows: await ports.deletePlate(key, assert === null ? void 0 : assert) ? 1 : 0,
+				bytes: null
+			};
+		}
 		if (RAW_DELETE_COLLECTIONS.has(collection)) {
 			const assert = trackIdAssertOf(data);
 			if (collection === OBJECT_EVENTS_COLLECTION && assert === null) {
@@ -104180,6 +104656,87 @@ function buildOrphanReclaimer(ports) {
 	};
 }
 //#endregion
+//#region src/pipeline-analytics/retention/orphan-audit-ledgers.ts
+/** Audited collection → its records-kind ledger. Empty without records. */
+function orphanAuditLedgers(wiring) {
+	if (wiring.records === void 0) return /* @__PURE__ */ new Map();
+	return new Map([
+		[FACES_COLLECTION, wireFaceLedger(wiring)],
+		[PLATES_COLLECTION$1, wirePlateLedger(wiring)],
+		[TRACK_ALIASES_COLLECTION, wireTrackAliasLedger(wiring)]
+	]);
+}
+/** {@link OrphanAuditDeps.pageKeyset} over those ledgers; `null` for any other collection. */
+function keysetPager(ledgers) {
+	return async (collection, cursor, limit) => {
+		const ledger = ledgers.get(collection);
+		if (ledger === void 0) return null;
+		const page = await ledger.pageById(cursor, limit);
+		return {
+			rows: page.rows.map((row) => ({
+				key: row.id,
+				data: row.data
+			})),
+			nextCursor: page.nextCursor
+		};
+	};
+}
+/** The kind's count for a ledger-backed collection, `undefined` for any other. */
+async function ledgerSize(ledgers, collection) {
+	const ledger = ledgers.get(collection);
+	return ledger === void 0 ? void 0 : ledger.count();
+}
+/**
+* The plate reclaim through the plate ledger — records on a hub, the legacy
+* collection only without records. With `assert`, a row whose `trackId` is not
+* the dead track's is KEPT (logged), never deleted.
+*/
+function plateDeleter(plates, logger) {
+	return async (plateId, assert) => {
+		const row = await plates.get(plateId);
+		if (row === null) return false;
+		if (assert !== void 0 && row.data["trackId"] !== assert.trackId) {
+			const deviceId = row.data["deviceId"];
+			logger.warn("orphan audit: plate row now names another track — kept", {
+				...typeof deviceId === "number" ? { tags: { deviceId } } : {},
+				meta: {
+					plateId,
+					expectedTrackId: assert.trackId
+				}
+			});
+			return false;
+		}
+		await plates.deleteKey(plateId);
+		return true;
+	};
+}
+function auditCollectionPorts(store, ledgers) {
+	return {
+		pageKeyset: keysetPager(ledgers),
+		pageByOffset: async (collection, offset, limit) => {
+			return (await store.query.query({
+				collection,
+				filter: {
+					orderBy: {
+						field: "id",
+						direction: "asc"
+					},
+					limit,
+					offset
+				}
+			})).map((row) => ({
+				key: row.id,
+				data: row.data
+			}));
+		},
+		size: async (collection) => {
+			const counted = await ledgerSize(ledgers, collection);
+			if (counted !== void 0) return counted;
+			return store.count.query({ collection });
+		}
+	};
+}
+//#endregion
 //#region src/pipeline-analytics/retention/retired-device-settings.ts
 /**
 * Every retired knob, with the sentence that explains it. The list is the
@@ -114937,6 +115494,7 @@ var customActions = {
 	...orphanAuditActions,
 	...mediaReclaimActions,
 	...locationDiscardActions,
+	...mediaForgetActions,
 	...photoEnrollActions,
 	...faceRescoreActions,
 	...stillnessCalibrationActions
@@ -116727,6 +117285,8 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_clip_m
 	orphanAuditState = { ...IDLE_ORPHAN_AUDIT };
 	/** Frozen-location leftover wipe (events/ on a drained HDD). Detached. */
 	discardJob = null;
+	/** The narrow media-row forget's wiring (`storage.forgetMissingMedia`). */
+	mediaForgetDeps = null;
 	/**
 	* The CLIP indexes' walks (D649), one resume cursor per index, kept in their
 	* OWN field rather than in {@link orphanAuditCursors}: `runOrphanAudit`
@@ -116935,10 +117495,17 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_clip_m
 		const isHub = ownNodeId === "hub";
 		const ncHandlers = isHub ? this.buildNcActionHandlers(api) : void 0;
 		if (isHub) this.reconcileTapePinsInBackground();
+		this.mediaForgetDeps = {
+			listLocations: async () => api.storage.listLocations.query({}),
+			localNodeId: ownNodeId,
+			store: api.settingsStore,
+			logger: logger.child("MediaForget")
+		};
 		this.discardJob = createDiscardJob({
 			listLocations: async () => api.storage.listLocations.query({}),
 			localNodeId: ownNodeId,
 			store: api.settingsStore,
+			retrainFrameLedger: wireRetrainFrameLedger(this.eventLedgerWiring(api.settingsStore)),
 			deleteTrackEvents: async (trackId) => {
 				await this.eventStore?.deleteByTrack(trackId);
 			},
@@ -116959,6 +117526,7 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_clip_m
 					...orphanAuditActions,
 					...mediaReclaimActions,
 					...locationDiscardActions,
+					...mediaForgetActions,
 					...photoEnrollActions,
 					...faceRescoreActions,
 					...stillnessCalibrationActions
@@ -117554,6 +118122,7 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_clip_m
 		});
 		this.mediaRelocate = new MediaRelocateEngine({
 			store: api.settingsStore,
+			retrainFrameLedger: wireRetrainFrameLedger(eventLedgerWiring),
 			storage,
 			logger: logger.child("MediaRelocate"),
 			now: () => Date.now(),
@@ -125296,36 +125865,29 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_clip_m
 		const trackStore = this.trackStore;
 		const eventStore = this.eventStore;
 		const mediaStore = this.mediaStore;
-		if (!trackStore || !eventStore || !mediaStore) {
+		const settingsStore = this.settingsStore;
+		if (!trackStore || !eventStore || !mediaStore || !settingsStore) {
 			if (!alreadyHeld) this.orphanAuditRunning = false;
 			return null;
 		}
 		try {
 			const limits = await this.orphanAuditLimits(overrides);
+			const auditLedgers = orphanAuditLedgers(this.eventLedgerWiring(settingsStore));
+			const plateLedger = wirePlateLedger(this.eventLedgerWiring(settingsStore));
+			const collectionPorts = auditCollectionPorts(settingsStore, auditLedgers);
 			const deps = {
+				pageKeyset: collectionPorts.pageKeyset,
+				stop: () => this.shuttingDown,
 				page: async (collection, shard, offset, limit) => {
 					if (collection === MEDIA_COLLECTION) return (await mediaStore.pageForAudit(shard?.value ?? "", offset, limit)).map((row) => ({
 						key: String(row.mediaId),
 						data: row.data
 					}));
-					return (await this.settingsStore?.query.query({
-						collection,
-						filter: {
-							orderBy: {
-								field: "id",
-								direction: "asc"
-							},
-							limit,
-							offset
-						}
-					}) ?? []).map((row) => ({
-						key: row.id,
-						data: row.data
-					}));
+					return collectionPorts.pageByOffset(collection, offset, limit);
 				},
 				size: async (collection, shard) => {
 					if (collection === MEDIA_COLLECTION) return mediaStore.countForAudit(shard?.value ?? "");
-					return await this.settingsStore?.count.query({ collection }) ?? null;
+					return collectionPorts.size(collection);
 				},
 				liveTrackIds: (ids) => this.liveTrackIdsThroughAliases(ids, trackStore),
 				liveEventIds: (table, ids) => eventStore.existingEventIdsIn(table, ids),
@@ -125348,6 +125910,7 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_clip_m
 							if (aliasStore === null) throw new Error("track alias store not bound");
 							return await aliasStore.deleteAlias(aliasId);
 						},
+						deletePlate: plateDeleter(plateLedger, this.ctx.logger),
 						deleteRow: settingsRowDeleterOf(() => this.settingsStore),
 						logger: this.ctx.logger
 					});
@@ -126769,7 +127332,12 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_clip_m
 				jobId: null
 			},
 			"storage.discardLocationStatus": async () => this.discardJob?.status() ?? IDLE_DISCARD,
-			"storage.discardLocationCancel": async () => this.discardJob?.cancel() ?? { requested: false }
+			"storage.discardLocationCancel": async () => this.discardJob?.cancel() ?? { requested: false },
+			"storage.forgetMissingMedia": async (input) => {
+				const deps = this.mediaForgetDeps;
+				if (deps === null) throw new Error("storage.forgetMissingMedia: not initialised");
+				return forgetMissingMediaRows(deps, input);
+			}
 		};
 	}
 	/**