@camstack/addon-post-analysis 1.2.343 → 1.2.344

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-Cd_y9S4U.js");
+const require_clip_model_registry = require("../clip-model-registry-Ca_IbZyD.js");
 let node_fs = require("node:fs");
 node_fs = require_clip_model_registry.__toESM(node_fs, 1);
 let node_path = require("node:path");
@@ -5839,16 +5839,16 @@ function ncDetectionSummary(texts, counts) {
 //#region src/notification-center/timelapse/detection-counts.ts
 /** One normalisation, used on both sides of every comparison — a rule that
 *  named `Person` must match a track classified `person`. */
-function normalise(name) {
+function normalise$1(name) {
 	return name.trim().toLowerCase();
 }
 /** Count per class over the tracks, honouring the rule's selection. */
 function countDetections(input) {
-	const selected = (input.reportClasses ?? []).map(normalise).filter((c) => c.length > 0);
+	const selected = (input.reportClasses ?? []).map(normalise$1).filter((c) => c.length > 0);
 	const seen = /* @__PURE__ */ new Map();
 	for (const t of input.tracks) {
 		if (t.className === void 0) continue;
-		const key = normalise(t.className);
+		const key = normalise$1(t.className);
 		if (key.length === 0) continue;
 		if (selected.length > 0 && !selected.includes(key)) continue;
 		seen.set(key, (seen.get(key) ?? 0) + 1);
@@ -70619,10 +70619,12 @@ var TrackStore = class {
 */
 /**
 * @durable class=ledger owner=pipeline-analytics
-*   write="one row per frame the operator SELECTS into the retrain dataset. The
-*     copy is taken eagerly at selection (copyFrame), not referenced, so the row
-*     records a blob the dataset owns outright; re-selecting the same source reuses
-*     the existing copy rather than writing a second one."
+*   write="one row per frame the operator SELECTS into the retrain dataset, or adds
+*     from the recording at an instant (storeRecordingStill, origin 'recording', no
+*     track). The copy is taken eagerly at selection (copyFrame), not referenced, so
+*     the row records a blob the dataset owns outright; re-selecting the same source
+*     (or the same camera instant) reuses the existing copy rather than writing a
+*     second one."
 *   retention="none — the blobs sit in the 'retrain/' subtree of the artifacts class
 *     (D781), which no owner cascade and no age sweep walks, which is exactly what makes a 'trained' track evictable
 *     again (D81). Rows go only when the operator deselects the frame (deleteFrame,
@@ -70737,6 +70739,19 @@ var RETRAIN_FRAME_COLUMNS = [
 	{
 		name: "complete",
 		type: "BOOLEAN"
+	}),
+	(
+	/** `recording` for a still taken from the recording at an instant (no
+	*  track, no source media row). NULL = a track copy. */
+	{
+		name: "origin",
+		type: "TEXT"
+	}),
+	(
+	/** The recording instant a `recording` still was asked for. */
+	{
+		name: "epochMs",
+		type: "INTEGER"
 	})
 ];
 var RETRAIN_FRAME_INDEXES = [
@@ -70762,6 +70777,8 @@ var RETRAIN_FRAME_INDEXES = [
 		columns: ["locationId"]
 	})
 ];
+/** Ids per `IN (…)` page in {@link RetrainFrameStore.getMany}. */
+var GET_MANY_PAGE = 500;
 /**
 * The copy's id, derived from `(trackId, sourceMediaId)`.
 *
@@ -70774,8 +70791,20 @@ var RETRAIN_FRAME_INDEXES = [
 function retrainFrameId(trackId, sourceMediaId) {
 	return `retrain:${trackId}:${(0, node_crypto.createHash)("sha1").update(String(sourceMediaId)).digest("hex").slice(0, 16)}`;
 }
-function framePath(deviceId, trackId, frameId) {
-	return `${RETRAIN_PATH_PREFIX}/${deviceId}/${trackId}/${frameId.slice(frameId.lastIndexOf(":") + 1)}.jpg`;
+/**
+* A recording still's id, derived from `(deviceId, epochMs)` — the same moment
+* of the same camera is one copy, however many times it is added.
+*/
+function recordingFrameId(deviceId, epochMs) {
+	const digest = (0, node_crypto.createHash)("sha1").update(String(epochMs)).digest("hex").slice(0, 16);
+	return `retrain:rec:${String(deviceId)}:${digest}`;
+}
+/** The directory a recording still sits in, beside the track directories. */
+var RECORDING_STILL_DIR = "recording";
+function framePath(frame) {
+	const leaf = frame.frameId.slice(frame.frameId.lastIndexOf(":") + 1);
+	const dir = frame.origin === "recording" ? RECORDING_STILL_DIR : frame.trackId;
+	return `${RETRAIN_PATH_PREFIX}/${frame.deviceId}/${dir}/${leaf}.jpg`;
 }
 /** A stored number, or `undefined` for NULL / absent / junk. */
 function finiteNumber(value) {
@@ -70820,9 +70849,11 @@ var RetrainFrameStore = class {
 		});
 	}
 	rowToFrame(id, data) {
+		const origin = data["origin"] === "recording" ? "recording" : "track";
 		return {
 			frameId: id,
 			deviceId: Number(data["deviceId"] ?? 0),
+			origin,
 			trackId: String(data["trackId"] ?? ""),
 			sourceMediaId: Number(data["sourceMediaId"] ?? 0),
 			sourceKind: String(data["sourceKind"] ?? "keyFrame"),
@@ -70833,9 +70864,54 @@ var RetrainFrameStore = class {
 			locationId: typeof data["locationId"] === "string" && data["locationId"].length > 0 ? data["locationId"] : null,
 			...finiteNumber(data["capturedAt"]) !== void 0 ? { capturedAt: finiteNumber(data["capturedAt"]) } : {},
 			...finiteNumber(data["chromaSpread"]) !== void 0 ? { chromaSpread: finiteNumber(data["chromaSpread"]) } : {},
-			complete: data["complete"] === true || data["complete"] === 1
+			complete: data["complete"] === true || data["complete"] === 1,
+			...finiteNumber(data["epochMs"]) !== void 0 ? { epochMs: finiteNumber(data["epochMs"]) } : {}
 		};
 	}
+	/** The copies with these ids, in the order given; unknown ids are skipped. */
+	async getMany(frameIds) {
+		if (frameIds.length === 0) return [];
+		try {
+			const byId = /* @__PURE__ */ new Map();
+			for (let i = 0; i < frameIds.length; i += GET_MANY_PAGE) {
+				const page = frameIds.slice(i, i + GET_MANY_PAGE);
+				const rows = await this.store.query.query({
+					collection: RETRAIN_FRAMES_COLLECTION,
+					filter: {
+						whereIn: { id: [...page] },
+						limit: page.length
+					}
+				});
+				for (const r of rows) if (typeof r.id === "string") byId.set(r.id, this.rowToFrame(r.id, r.data));
+			}
+			return frameIds.flatMap((id) => {
+				const frame = byId.get(id);
+				return frame !== void 0 ? [frame] : [];
+			});
+		} catch (err) {
+			this.logger.warn("RetrainFrameStore.getMany failed", { meta: {
+				frames: frameIds.length,
+				error: String(err)
+			} });
+			return [];
+		}
+	}
+	/** Every camera the dataset holds a copy of — a recording still can be the
+	*  only thing a camera contributes, with no track anywhere. */
+	async listDeviceIds() {
+		try {
+			const rows = await this.store.query.query({ collection: RETRAIN_FRAMES_COLLECTION });
+			const ids = /* @__PURE__ */ new Set();
+			for (const r of rows) {
+				const id = Number(r.data["deviceId"]);
+				if (Number.isInteger(id) && id > 0) ids.add(id);
+			}
+			return [...ids].toSorted((a, b) => a - b);
+		} catch (err) {
+			this.logger.warn("RetrainFrameStore.listDeviceIds failed", { meta: { error: String(err) } });
+			return [];
+		}
+	}
 	/** The copy with this id, or `null`. Index read only — no blob is touched. */
 	async get(frameId) {
 		try {
@@ -70852,8 +70928,10 @@ var RetrainFrameStore = class {
 			return null;
 		}
 	}
-	/** Every copy taken from this track, oldest first. */
+	/** Every copy taken from this track, oldest first. A recording still has
+	*  no track and is never answered here. */
 	async listByTrack(trackId) {
+		if (trackId === "") return [];
 		try {
 			return (await this.store.query.query({
 				collection: RETRAIN_FRAMES_COLLECTION,
@@ -70927,7 +71005,7 @@ var RetrainFrameStore = class {
 		try {
 			return await this.storage.read({
 				location: frame.locationId ?? LEGACY_RETRAIN_MEDIA_LOCATION,
-				relativePath: framePath(frame.deviceId, frame.trackId, frame.frameId)
+				relativePath: framePath(frame)
 			});
 		} catch (err) {
 			this.logger.warn("retrain frame copy unreadable", {
@@ -70996,12 +71074,17 @@ var RetrainFrameStore = class {
 				reason: "unreadable-image"
 			};
 		}
-		const path = framePath(input.deviceId, input.trackId, frameId);
+		const path = framePath({
+			...input,
+			frameId,
+			origin: "track"
+		});
 		const locationId = RETRAIN_MEDIA_LOCATION;
 		const chromaSpread = await this.chromaOf(bytes, input.deviceId);
 		const frame = {
 			frameId,
 			deviceId: input.deviceId,
+			origin: "track",
 			trackId: input.trackId,
 			sourceMediaId: input.sourceMediaId,
 			sourceKind: input.sourceKind,
@@ -71076,6 +71159,115 @@ var RetrainFrameStore = class {
 		};
 	}
 	/**
+	* Store a still decoded from the RECORDING at `epochMs` — a frame with no
+	* track and no media row, usually the one the model saw nothing in.
+	*
+	* Same contract as {@link copyFrame}: an existing copy of that moment is
+	* returned untouched; the blob lands before the row; a refusal is named.
+	* `capturedAt` IS the instant — the camera saw this frame then.
+	*/
+	async storeRecordingStill(input) {
+		const frameId = recordingFrameId(input.deviceId, input.epochMs);
+		const existing = await this.get(frameId);
+		if (existing !== null) return {
+			kind: "copied",
+			frame: existing,
+			reused: true
+		};
+		const size = readJpegSize(input.bytes);
+		if (size === null) {
+			this.logger.warn("retrain recording still refused — not a readable JPEG", {
+				tags: { deviceId: input.deviceId },
+				meta: {
+					epochMs: input.epochMs,
+					bytes: input.bytes.length
+				}
+			});
+			return {
+				kind: "refused",
+				reason: "unreadable-image"
+			};
+		}
+		const chromaSpread = await this.chromaOf(input.bytes, input.deviceId);
+		const frame = {
+			frameId,
+			deviceId: input.deviceId,
+			origin: "recording",
+			trackId: "",
+			sourceMediaId: 0,
+			sourceKind: "fullFrame",
+			sizeBytes: input.bytes.length,
+			width: size.width,
+			height: size.height,
+			copiedAt: this.now(),
+			locationId: RETRAIN_MEDIA_LOCATION,
+			capturedAt: input.epochMs,
+			...chromaSpread !== void 0 ? { chromaSpread } : {},
+			complete: false,
+			epochMs: input.epochMs
+		};
+		const path = framePath(frame);
+		const persist = async () => {
+			await this.storage.write({
+				location: RETRAIN_MEDIA_LOCATION,
+				relativePath: path,
+				data: input.bytes
+			});
+			await this.store.set.mutate({
+				collection: RETRAIN_FRAMES_COLLECTION,
+				key: frameId,
+				value: {
+					deviceId: frame.deviceId,
+					trackId: "",
+					sourceMediaId: 0,
+					sourceKind: frame.sourceKind,
+					path,
+					sizeBytes: frame.sizeBytes,
+					width: frame.width,
+					height: frame.height,
+					copiedAt: frame.copiedAt,
+					locationId: RETRAIN_MEDIA_LOCATION,
+					capturedAt: input.epochMs,
+					chromaSpread: frame.chromaSpread ?? null,
+					complete: false,
+					origin: "recording",
+					epochMs: input.epochMs
+				}
+			});
+		};
+		try {
+			if (this.writeGate) await this.writeGate.run(persist);
+			else await persist();
+		} catch (err) {
+			this.logger.error("retrain recording still failed to persist", {
+				tags: { deviceId: input.deviceId },
+				meta: {
+					frameId,
+					epochMs: input.epochMs,
+					error: String(err)
+				}
+			});
+			return {
+				kind: "refused",
+				reason: "write-failed"
+			};
+		}
+		this.logger.info("retrain recording still stored in the dataset", {
+			tags: { deviceId: input.deviceId },
+			meta: {
+				frameId,
+				epochMs: input.epochMs,
+				width: frame.width,
+				height: frame.height
+			}
+		});
+		return {
+			kind: "copied",
+			frame,
+			reused: false
+		};
+	}
+	/**
 	* The operator's "every subject in this frame is boxed" (D785 context: an
 	* unboxed subject is a false positive to a detector evaluation). Only the
 	* operator sets it; nothing derives it from the annotation count, because a
@@ -71108,7 +71300,7 @@ var RetrainFrameStore = class {
 			try {
 				await this.storage.delete({
 					location: frame.locationId ?? LEGACY_RETRAIN_MEDIA_LOCATION,
-					relativePath: framePath(frame.deviceId, frame.trackId, frame.frameId)
+					relativePath: framePath(frame)
 				});
 			} catch {}
 			try {
@@ -71155,7 +71347,7 @@ var RetrainFrameStore = class {
 			if (rowIsDurableRetrainCopy(data)) continue;
 			const frame = this.rowToFrame(row.id, data);
 			const from = frame.locationId ?? LEGACY_RETRAIN_MEDIA_LOCATION;
-			const relativePath = framePath(frame.deviceId, frame.trackId, frame.frameId);
+			const relativePath = framePath(frame);
 			let bytes;
 			try {
 				bytes = await this.storage.read({
@@ -82322,6 +82514,17 @@ var RETRAIN_ANNOTATION_INDEXES = [
 		columns: ["deviceId", "createdAt"]
 	}
 ];
+var ANNOTATION_SOURCES = [
+	"operator",
+	"assist",
+	"pipeline",
+	"llm"
+];
+/** The stored source, narrowed. Unknown reads as `operator` — the least
+*  presumptuous claim a row can make about who drew it. */
+function narrowSource(value) {
+	return ANNOTATION_SOURCES.find((source) => source === value) ?? "operator";
+}
 function optionalString(value) {
 	return typeof value === "string" && value.length > 0 ? value : void 0;
 }
@@ -82329,6 +82532,8 @@ function optionalString(value) {
 function narrowMacroClass(value) {
 	return typeof value === "string" && isRetrainMacroClass(value) ? value : "person";
 }
+/** Frame ids per `IN (…)` page in {@link RetrainAnnotationStore.listByFrames}. */
+var LIST_BY_FRAMES_PAGE = 500;
 var RetrainAnnotationStore = class {
 	store;
 	logger;
@@ -82365,7 +82570,7 @@ var RetrainAnnotationStore = class {
 			label: optionalString(data["label"]),
 			subLabel: optionalString(data["subLabel"]),
 			kind: data["kind"] === "model_error" ? "model_error" : "subject",
-			source: data["source"] === "assist" ? "assist" : "operator",
+			source: narrowSource(data["source"]),
 			assistModelId: optionalString(data["assistModelId"]),
 			assistScore: typeof score === "number" ? score : void 0,
 			exportedInBatch: optionalString(data["exportedInBatch"]),
@@ -82434,6 +82639,32 @@ var RetrainAnnotationStore = class {
 	async listByFrame(mediaKey) {
 		return this.queryWhere({ mediaKey }, `frame ${mediaKey}`);
 	}
+	/** Every annotation of these frames, oldest first — paged `IN (…)`. */
+	async listByFrames(mediaKeys) {
+		const out = [];
+		for (let i = 0; i < mediaKeys.length; i += LIST_BY_FRAMES_PAGE) {
+			const page = mediaKeys.slice(i, i + LIST_BY_FRAMES_PAGE);
+			try {
+				const rows = await this.store.query.query({
+					collection: RETRAIN_ANNOTATIONS_COLLECTION,
+					filter: {
+						whereIn: { mediaKey: [...page] },
+						orderBy: {
+							field: "createdAt",
+							direction: "asc"
+						}
+					}
+				});
+				for (const r of rows) if (typeof r.id === "string") out.push(this.rowToAnnotation(r.id, r.data));
+			} catch (err) {
+				this.logger.warn("RetrainAnnotationStore.listByFrames failed", { meta: {
+					frames: page.length,
+					error: String(err)
+				} });
+			}
+		}
+		return out;
+	}
 	async listByTrack(trackId) {
 		return this.queryWhere({ trackId }, `track ${trackId}`);
 	}
@@ -82547,13 +82778,41 @@ var RetrainAnnotationStore = class {
 //#endregion
 //#region src/pipeline-analytics/retrain/retrain-collection-store.ts
 /**
+* RetrainCollectionStore — named sets over the one retrain corpus.
+*
+* Collections: `pipeline-analytics:retrain-collections` (the names) and
+* `pipeline-analytics:retrain-collection-frames` (the membership).
+*
+* A collection OWNS NO PIXELS. Every frame — copied from a track or stilled
+* from the recording — lives once in `retrain-frames`, with its annotations,
+* its completeness and its export path; a collection is a name the operator
+* gives to a subset of it ("packages porch night", "false-positive cars"). So
+* a frame can be in several collections, a collection's count is its
+* membership, and deleting a collection removes memberships, never a frame
+* another collection or a track still holds. Which trackless frames are left
+* with no reason to exist is the caller's question
+* (`retrain-collection-service.ts`).
+*/
+/**
 * @durable class=ledger owner=pipeline-analytics
 *   write="one row per named training collection the operator creates. Names are
-*     unique on nameKey (lower(trim)); empty names never become rows."
-*   retention="none — operator-owned corpus metadata. Rows leave only when an
-*     explicit delete API lands (not V1)."
+*     unique on nameKey (lower(trim)); empty names never become rows. A rename
+*     rewrites name + nameKey under the same id."
+*   retention="none — operator-owned corpus metadata. A row leaves only when the
+*     operator deletes the collection (deleteRetrainCollection), which removes its
+*     membership rows first."
 */
 var RETRAIN_COLLECTIONS_COLLECTION = "pipeline-analytics:retrain-collections";
+/**
+* @durable class=ledger owner=pipeline-analytics
+*   write="one row per (collection, frame) pair the operator adds — a frame added
+*     from the recording, or an existing retrain frame added to a collection. Keyed
+*     by a hash of the pair, so adding twice is one row."
+*   retention="none — rows leave when the operator removes the frame from the
+*     collection, deletes the collection, or deselects the frame itself. Bounded by
+*     operator curation."
+*/
+var RETRAIN_COLLECTION_FRAMES_COLLECTION = "pipeline-analytics:retrain-collection-frames";
 var RETRAIN_COLLECTION_COLUMNS = [
 	{
 		name: "id",
@@ -82590,6 +82849,41 @@ var RETRAIN_COLLECTION_INDEXES = [{
 	name: "idx_retrain_collections_created",
 	columns: ["createdAt"]
 }];
+var RETRAIN_COLLECTION_FRAME_COLUMNS = [
+	{
+		name: "id",
+		type: "TEXT",
+		primaryKey: true,
+		notNull: true
+	},
+	{
+		name: "collectionId",
+		type: "TEXT",
+		notNull: true
+	},
+	{
+		name: "frameId",
+		type: "TEXT",
+		notNull: true
+	},
+	{
+		name: "deviceId",
+		type: "INTEGER",
+		notNull: true
+	},
+	{
+		name: "addedAt",
+		type: "INTEGER",
+		notNull: true
+	}
+];
+var RETRAIN_COLLECTION_FRAME_INDEXES = [{
+	name: "idx_retrain_coll_frames_collection",
+	columns: ["collectionId", "addedAt"]
+}, {
+	name: "idx_retrain_coll_frames_frame",
+	columns: ["frameId"]
+}];
 function normalizeCollectionName(raw) {
 	const name = raw.trim();
 	if (name.length === 0) return null;
@@ -82598,18 +82892,22 @@ function normalizeCollectionName(raw) {
 		nameKey: name.toLowerCase()
 	};
 }
+/** The membership row's key — one row per pair, whatever the ids contain. */
+function membershipKey(collectionId, frameId) {
+	return (0, node_crypto.createHash)("sha1").update(`${collectionId}\u0000${frameId}`).digest("hex");
+}
+/** Ids per `IN (…)` page. */
+var IN_PAGE = 500;
 var RetrainCollectionStore = class {
 	store;
 	logger;
 	now;
 	newId;
-	countFrames;
 	constructor(deps) {
 		this.store = deps.store;
 		this.logger = deps.logger;
 		this.now = deps.now;
 		this.newId = deps.newId;
-		this.countFrames = deps.countFrames;
 	}
 	static async declare(store) {
 		await store.declareCollection.mutate({
@@ -82617,6 +82915,11 @@ var RetrainCollectionStore = class {
 			columns: [...RETRAIN_COLLECTION_COLUMNS],
 			indexes: [...RETRAIN_COLLECTION_INDEXES]
 		});
+		await store.declareCollection.mutate({
+			collection: RETRAIN_COLLECTION_FRAMES_COLLECTION,
+			columns: [...RETRAIN_COLLECTION_FRAME_COLUMNS],
+			indexes: [...RETRAIN_COLLECTION_FRAME_INDEXES]
+		});
 	}
 	async create(input) {
 		const normalized = normalizeCollectionName(input.name);
@@ -82624,7 +82927,7 @@ var RetrainCollectionStore = class {
 			kind: "refused",
 			reason: "empty-name"
 		};
-		if (await this.findByNameKey(normalized.nameKey) !== null) return {
+		if (await this.findIdByNameKey(normalized.nameKey) !== null) return {
 			kind: "refused",
 			reason: "duplicate-name"
 		};
@@ -82640,6 +82943,7 @@ var RetrainCollectionStore = class {
 				updatedAt: createdAt
 			}
 		});
+		this.logger.info("retrain collection created", { meta: { collectionId: id } });
 		return {
 			kind: "created",
 			collection: {
@@ -82650,6 +82954,7 @@ var RetrainCollectionStore = class {
 			}
 		};
 	}
+	/** Every collection, newest first, each with its membership count (one query). */
 	async list() {
 		let rows;
 		try {
@@ -82664,34 +82969,158 @@ var RetrainCollectionStore = class {
 			this.logger.warn("retrain collections list failed", { meta: { error: String(err) } });
 			return [];
 		}
-		const out = [];
-		for (const row of rows) {
-			const name = typeof row.data["name"] === "string" ? row.data["name"] : "";
-			const createdAt = Number(row.data["createdAt"] ?? 0);
-			const frameCount = this.countFrames !== void 0 ? await this.countFrames(row.id) : 0;
-			out.push({
-				id: row.id,
-				name,
-				createdAt,
-				frameCount
-			});
+		const counts = await this.countMembers(rows.map((r) => r.id));
+		return rows.map((row) => this.toCollection(row.id, row.data, counts.get(row.id) ?? 0));
+	}
+	async getById(id) {
+		const data = await this.readRow(id);
+		if (data === null) return null;
+		const counts = await this.countMembers([id]);
+		return this.toCollection(id, data, counts.get(id) ?? 0);
+	}
+	async rename(input) {
+		const normalized = normalizeCollectionName(input.name);
+		if (normalized === null) return {
+			kind: "refused",
+			reason: "empty-name"
+		};
+		const current = await this.readRow(input.id);
+		if (current === null) return {
+			kind: "refused",
+			reason: "unknown-collection"
+		};
+		const holder = await this.findIdByNameKey(normalized.nameKey);
+		if (holder !== null && holder !== input.id) return {
+			kind: "refused",
+			reason: "duplicate-name"
+		};
+		await this.store.update.mutate({
+			collection: RETRAIN_COLLECTIONS_COLLECTION,
+			id: input.id,
+			data: {
+				name: normalized.name,
+				nameKey: normalized.nameKey,
+				updatedAt: this.now()
+			}
+		});
+		this.logger.info("retrain collection renamed", { meta: { collectionId: input.id } });
+		const counts = await this.countMembers([input.id]);
+		return {
+			kind: "renamed",
+			collection: this.toCollection(input.id, {
+				...current,
+				name: normalized.name
+			}, counts.get(input.id) ?? 0)
+		};
+	}
+	/** Remove the collection and its memberships — members first, so a crash
+	*  never leaves memberships pointing at a name that no longer exists. */
+	async delete(id) {
+		if (await this.readRow(id) === null) return {
+			deleted: false,
+			memberFrameIds: []
+		};
+		const members = await this.membershipRows({ collectionId: id });
+		for (const m of members) await this.store.delete.mutate({
+			collection: RETRAIN_COLLECTION_FRAMES_COLLECTION,
+			key: m.id
+		});
+		await this.store.delete.mutate({
+			collection: RETRAIN_COLLECTIONS_COLLECTION,
+			key: id
+		});
+		this.logger.info("retrain collection deleted", { meta: {
+			collectionId: id,
+			members: members.length
+		} });
+		return {
+			deleted: true,
+			memberFrameIds: members.map((m) => String(m.data["frameId"] ?? ""))
+		};
+	}
+	/** Add a frame. `false` when it was already a member (nothing written). */
+	async addFrame(input) {
+		const key = membershipKey(input.collectionId, input.frameId);
+		const existing = await this.store.get.query({
+			collection: RETRAIN_COLLECTION_FRAMES_COLLECTION,
+			key
+		});
+		if (existing !== null && existing !== void 0) return false;
+		await this.store.set.mutate({
+			collection: RETRAIN_COLLECTION_FRAMES_COLLECTION,
+			key,
+			value: {
+				collectionId: input.collectionId,
+				frameId: input.frameId,
+				deviceId: input.deviceId,
+				addedAt: this.now()
+			}
+		});
+		return true;
+	}
+	/** Remove one membership. `false` when it did not exist. */
+	async removeFrame(input) {
+		const key = membershipKey(input.collectionId, input.frameId);
+		const existing = await this.store.get.query({
+			collection: RETRAIN_COLLECTION_FRAMES_COLLECTION,
+			key
+		});
+		if (existing === null || existing === void 0) return false;
+		await this.store.delete.mutate({
+			collection: RETRAIN_COLLECTION_FRAMES_COLLECTION,
+			key
+		});
+		return true;
+	}
+	/** Remove a frame from EVERY collection — the frame itself is leaving. */
+	async forgetFrame(frameId) {
+		const rows = await this.membershipRows({ frameId });
+		for (const r of rows) await this.store.delete.mutate({
+			collection: RETRAIN_COLLECTION_FRAMES_COLLECTION,
+			key: r.id
+		});
+		return rows.length;
+	}
+	/** The frames of a collection, in the order they were added. */
+	async listFrameIds(collectionId) {
+		return (await this.membershipRows({ collectionId })).toSorted((a, b) => Number(a.data["addedAt"] ?? 0) - Number(b.data["addedAt"] ?? 0)).map((r) => String(r.data["frameId"] ?? "")).filter((id) => id !== "");
+	}
+	/** frameId → the collections it belongs to. Frames in none are absent. */
+	async collectionsOf(frameIds) {
+		const out = /* @__PURE__ */ new Map();
+		for (const row of await this.membershipRowsIn("frameId", frameIds)) {
+			const frameId = String(row.data["frameId"] ?? "");
+			const collectionId = String(row.data["collectionId"] ?? "");
+			if (frameId === "" || collectionId === "") continue;
+			out.set(frameId, [...out.get(frameId) ?? [], collectionId]);
 		}
+		for (const [frameId, ids] of out) out.set(frameId, ids.toSorted());
 		return out;
 	}
-	async getById(id) {
+	/** The frame ids of several collections, de-duplicated. */
+	async frameIdsOf(collectionIds) {
+		const ids = /* @__PURE__ */ new Set();
+		for (const row of await this.membershipRowsIn("collectionId", collectionIds)) {
+			const frameId = String(row.data["frameId"] ?? "");
+			if (frameId !== "") ids.add(frameId);
+		}
+		return [...ids];
+	}
+	toCollection(id, data, frameCount) {
+		return {
+			id,
+			name: typeof data["name"] === "string" ? data["name"] : "",
+			createdAt: Number(data["createdAt"] ?? 0),
+			frameCount
+		};
+	}
+	async readRow(id) {
 		try {
 			const row = await this.store.get.query({
 				collection: RETRAIN_COLLECTIONS_COLLECTION,
 				key: id
 			});
-			if (row === null || row === void 0) return null;
-			const data = row;
-			return {
-				id,
-				name: typeof data["name"] === "string" ? data["name"] : "",
-				createdAt: Number(data["createdAt"] ?? 0),
-				frameCount: this.countFrames !== void 0 ? await this.countFrames(id) : 0
-			};
+			return row === null || row === void 0 ? null : { ...row };
 		} catch (err) {
 			this.logger.warn("retrain collection get failed", { meta: {
 				collectionId: id,
@@ -82700,14 +83129,125 @@ var RetrainCollectionStore = class {
 			return null;
 		}
 	}
+	async countMembers(collectionIds) {
+		const counts = /* @__PURE__ */ new Map();
+		for (const row of await this.membershipRowsIn("collectionId", collectionIds)) {
+			const id = String(row.data["collectionId"] ?? "");
+			counts.set(id, (counts.get(id) ?? 0) + 1);
+		}
+		return counts;
+	}
+	async membershipRows(where) {
+		try {
+			return await this.store.query.query({
+				collection: RETRAIN_COLLECTION_FRAMES_COLLECTION,
+				filter: { where }
+			});
+		} catch (err) {
+			this.logger.warn("retrain collection membership read failed", { meta: {
+				...where,
+				error: String(err)
+			} });
+			return [];
+		}
+	}
+	async membershipRowsIn(field, values) {
+		const out = [];
+		for (let i = 0; i < values.length; i += IN_PAGE) {
+			const page = values.slice(i, i + IN_PAGE);
+			try {
+				out.push(...await this.store.query.query({
+					collection: RETRAIN_COLLECTION_FRAMES_COLLECTION,
+					filter: { whereIn: { [field]: [...page] } }
+				}));
+			} catch (err) {
+				this.logger.warn("retrain collection membership read failed", { meta: {
+					field,
+					values: page.length,
+					error: String(err)
+				} });
+			}
+		}
+		return out;
+	}
+	async findIdByNameKey(nameKey) {
+		try {
+			return (await this.store.query.query({
+				collection: RETRAIN_COLLECTIONS_COLLECTION,
+				filter: {
+					where: { nameKey },
+					limit: 1
+				}
+			}))[0]?.id ?? null;
+		} catch (err) {
+			this.logger.warn("retrain collection findByNameKey failed", { meta: {
+				nameKey,
+				error: String(err)
+			} });
+			return null;
+		}
+	}
+};
+//#endregion
+//#region src/pipeline-analytics/retrain/retrain-collection-service.ts
+/** What each still outcome tells the operator. */
+var STILL_REFUSAL = {
+	"no-recording": {
+		reason: "still-unavailable",
+		detail: "this camera is not recording, so there is no footage to take a frame from"
+	},
+	"no-footage": {
+		reason: "still-unavailable",
+		detail: "no recorded footage covers that instant (a gap, or already pruned)"
+	},
+	"decode-failed": {
+		reason: "still-unavailable",
+		detail: "the footage is there but the frame could not be decoded"
+	},
+	busy: {
+		reason: "still-busy",
+		detail: "the recorder is already decoding other frames — try again in a moment"
+	}
+};
+var RetrainCollectionService = class {
+	deps;
+	constructor(deps) {
+		this.deps = deps;
+	}
+	create(input) {
+		return this.deps.collections.create(input);
+	}
+	list() {
+		return this.deps.collections.list();
+	}
+	rename(input) {
+		return this.deps.collections.rename(input);
+	}
 	/**
-	* Stub until still ingest lands. Validates the collection exists, then
-	* refuses with a named reason so callers can wire UI against a stable shape.
+	* Delete a collection. Its recording stills that no other collection holds
+	* go with it (annotations first); track copies always stay.
 	*/
-	async addRetrainFrameFromRecording(input) {
-		if (await this.getById(input.collectionId) === null) {
-			this.logger.info("retrain collection addFrame refused: unknown-collection", {
-				tags: { deviceId: input.deviceId },
+	async delete(input) {
+		const result = await this.deps.collections.delete(input.id);
+		if (!result.deleted) return {
+			deleted: false,
+			removedFrames: 0
+		};
+		return {
+			deleted: true,
+			removedFrames: await this.dropOrphanStills(result.memberFrameIds)
+		};
+	}
+	/**
+	* Decode the frame at `epochMs` from the camera's recording and add it to
+	* the collection. The moment already in the dataset is reused without a
+	* decode; every refusal is named and writes nothing.
+	*/
+	async addFrameFromRecording(input) {
+		const tags = { deviceId: input.deviceId };
+		if (await this.deps.collections.getById(input.collectionId) === null) {
+			this.deps.logger.info("retrain collection add refused: unknown collection", {
+				tags,
 				meta: {
 					collectionId: input.collectionId,
 					epochMs: input.epochMs
@@ -82718,42 +83258,517 @@ var RetrainCollectionStore = class {
 				reason: "unknown-collection"
 			};
 		}
-		this.logger.info("retrain collection addFrame stub: still-capture-unimplemented", {
-			tags: { deviceId: input.deviceId },
+		const stored = await this.storeStill(input.deviceId, input.epochMs);
+		if (stored.kind === "refused") {
+			this.deps.logger.info("retrain collection add refused", {
+				tags,
+				meta: {
+					collectionId: input.collectionId,
+					epochMs: input.epochMs,
+					reason: stored.reason
+				}
+			});
+			return stored;
+		}
+		await this.deps.collections.addFrame({
+			collectionId: input.collectionId,
+			frameId: stored.frame.frameId,
+			deviceId: input.deviceId
+		});
+		this.deps.logger.info("retrain frame added to a collection from the recording", {
+			tags,
 			meta: {
 				collectionId: input.collectionId,
-				epochMs: input.epochMs
+				frameId: stored.frame.frameId,
+				epochMs: input.epochMs,
+				reused: stored.reused
 			}
 		});
+		const [wire] = await this.deps.retrain.toWireFrames([stored.frame]);
+		if (wire === void 0) throw new Error("retrain: a stored still produced no wire frame");
+		return {
+			kind: "added",
+			collectionId: input.collectionId,
+			frame: wire,
+			reused: stored.reused
+		};
+	}
+	/** Add frames already in the dataset (track copies or stills) to a collection. */
+	async addFrames(input) {
+		if (await this.deps.collections.getById(input.collectionId) === null) return {
+			added: 0,
+			alreadyMember: 0,
+			unknownFrameIds: [...input.frameIds]
+		};
+		const frames = await this.deps.frames.getMany(input.frameIds);
+		const known = new Set(frames.map((f) => f.frameId));
+		let added = 0;
+		let alreadyMember = 0;
+		for (const frame of frames) if (await this.deps.collections.addFrame({
+			collectionId: input.collectionId,
+			frameId: frame.frameId,
+			deviceId: frame.deviceId
+		})) added += 1;
+		else alreadyMember += 1;
+		return {
+			added,
+			alreadyMember,
+			unknownFrameIds: input.frameIds.filter((id) => !known.has(id))
+		};
+	}
+	/**
+	* Remove a frame from a collection. A recording still left in no collection
+	* is deleted with its annotations; a track copy is never deleted here.
+	*/
+	async removeFrame(input) {
+		if (!await this.deps.collections.removeFrame(input)) return {
+			removed: false,
+			deletedFrame: false
+		};
 		return {
+			removed: true,
+			deletedFrame: await this.dropOrphanStills([input.frameId]) > 0
+		};
+	}
+	/** The frames of a collection, as the canvas lists them. */
+	async listFrames(input) {
+		const ids = await this.deps.collections.listFrameIds(input.collectionId);
+		return this.deps.retrain.toWireFrames(await this.deps.frames.getMany(ids));
+	}
+	async storeStill(deviceId, epochMs) {
+		const existing = await this.deps.frames.get(recordingFrameId(deviceId, epochMs));
+		if (existing !== null) return {
+			kind: "stored",
+			frame: existing,
+			reused: true
+		};
+		const still = await this.deps.captureStill(deviceId, epochMs);
+		if (still.outcome !== "ok" || still.jpeg === void 0) {
+			const refusal = still.outcome === "ok" ? STILL_REFUSAL["decode-failed"] : STILL_REFUSAL[still.outcome];
+			return {
+				kind: "refused",
+				reason: refusal.reason,
+				detail: refusal.detail
+			};
+		}
+		const stored = await this.deps.frames.storeRecordingStill({
+			deviceId,
+			epochMs,
+			bytes: still.jpeg
+		});
+		return stored.kind === "copied" ? {
+			kind: "stored",
+			frame: stored.frame,
+			reused: stored.reused
+		} : {
 			kind: "refused",
-			reason: "still-capture-unimplemented",
-			detail: "Still ingest lands in plan Task 3"
+			reason: stored.reason
 		};
 	}
-	async findByNameKey(nameKey) {
-		try {
-			const row = (await this.store.query.query({
-				collection: RETRAIN_COLLECTIONS_COLLECTION,
-				filter: {
-					where: { nameKey },
-					limit: 1
+	/** Delete the recording stills among `frameIds` that no collection holds any more. */
+	async dropOrphanStills(frameIds) {
+		if (frameIds.length === 0) return 0;
+		const memberships = await this.deps.collections.collectionsOf(frameIds);
+		const orphans = (await this.deps.frames.getMany(frameIds)).filter((f) => f.origin === "recording" && (memberships.get(f.frameId)?.length ?? 0) === 0);
+		for (const frame of orphans) await this.deps.retrain.removeFrame(frame);
+		return orphans.length;
+	}
+};
+//#endregion
+//#region src/pipeline-analytics/retrain/retrain-llm-assist.ts
+var ALWAYS_LOCAL_KINDS = new Set(["managed-local", "apple-foundation"]);
+var ALWAYS_CLOUD_KINDS = new Set([
+	"openai",
+	"anthropic",
+	"google"
+]);
+function isPrivateIpv4(host) {
+	const parts = host.split(".").map((p) => Number.parseInt(p, 10));
+	if (parts.length !== 4 || parts.some((p) => !Number.isInteger(p) || p < 0 || p > 255)) return false;
+	const [a, b] = parts;
+	return a === 10 || a === 127 || a === 172 && b >= 16 && b <= 31 || a === 192 && b === 168 || a === 169 && b === 254 || a === 100 && b >= 64 && b <= 127;
+}
+function isLocalHost(rawHost) {
+	const host = rawHost.replace(/^\[|\]$/g, "").toLowerCase();
+	if (host.includes(":")) return host === "::1" || host.startsWith("fc") || host.startsWith("fd") || host.startsWith("fe80");
+	if (host === "localhost" || host.endsWith(".local") || host.endsWith(".lan")) return true;
+	if (isPrivateIpv4(host)) return true;
+	return !host.includes(".") && !host.includes(":");
+}
+/** Does sending a frame to this profile send it outside the house? */
+function llmProfileLeavesHouse(profile) {
+	if (ALWAYS_LOCAL_KINDS.has(profile.kind)) return false;
+	if (ALWAYS_CLOUD_KINDS.has(profile.kind)) return true;
+	if (profile.baseUrl === void 0 || profile.baseUrl === "") return true;
+	try {
+		return !isLocalHost(new URL(profile.baseUrl).hostname);
+	} catch {
+		return true;
+	}
+}
+/** At most this many boxes are sent for review — a prompt, not a dump. */
+var LLM_REVIEW_MAX_BOXES = 50;
+var VERDICTS = [
+	"confirmed",
+	"wrong-class",
+	"not-an-object",
+	"uncertain"
+];
+var SYSTEM_PROMPT = [
+	"You annotate frames from home security cameras to build an object-detection training set.",
+	"Be precise and conservative: only report what is clearly visible.",
+	"Coordinates are normalised to the full frame: x and y are the top-left corner,",
+	"w and h the width and height, all between 0 and 1.",
+	"Answer with JSON only, exactly in the requested schema, with no other text."
+].join(" ");
+/** The JSON schema asked of the model (and enforced again by the parser). */
+function answerJsonSchema(classes) {
+	return {
+		type: "object",
+		additionalProperties: false,
+		required: ["objects", "reviews"],
+		properties: {
+			objects: {
+				type: "array",
+				items: {
+					type: "object",
+					additionalProperties: false,
+					required: [
+						"class",
+						"box",
+						"confidence",
+						"reason"
+					],
+					properties: {
+						class: {
+							type: "string",
+							enum: [...classes]
+						},
+						label: { type: "string" },
+						box: {
+							type: "array",
+							items: { type: "number" },
+							minItems: 4,
+							maxItems: 4
+						},
+						confidence: {
+							type: "number",
+							minimum: 0,
+							maximum: 1
+						},
+						reason: { type: "string" }
+					}
 				}
-			}))[0];
-			if (row === void 0) return null;
+			},
+			reviews: {
+				type: "array",
+				items: {
+					type: "object",
+					additionalProperties: false,
+					required: [
+						"ref",
+						"verdict",
+						"reason"
+					],
+					properties: {
+						ref: { type: "string" },
+						verdict: {
+							type: "string",
+							enum: [...VERDICTS]
+						},
+						suggestedClass: { type: "string" },
+						reason: { type: "string" }
+					}
+				}
+			}
+		}
+	};
+}
+var round = (n) => Math.round(n * 1e3) / 1e3;
+/** Build the request: target classes, the frame size, the boxes to review. */
+function buildLlmAssistRequest(input) {
+	const boxes = input.boxes.slice(0, LLM_REVIEW_MAX_BOXES).map((b) => JSON.stringify({
+		ref: b.ref,
+		class: b.macroClass,
+		...b.label !== void 0 ? { label: b.label } : {},
+		box: [
+			round(b.bbox.x),
+			round(b.bbox.y),
+			round(b.bbox.w),
+			round(b.bbox.h)
+		]
+	}));
+	return {
+		system: SYSTEM_PROMPT,
+		prompt: [
+			`The image is one camera frame, ${String(input.width)}×${String(input.height)} pixels.`,
+			`1. List every object of these classes you can see: ${input.classes.join(", ")}.`,
+			"   For each give class, an optional free-text label (e.g. \"van\", \"postman\"),",
+			"   box [x, y, w, h] normalised to the frame, confidence 0–1, and a short reason.",
+			"   Include small and partly hidden ones; do not include anything else.",
+			boxes.length > 0 ? `2. Review these existing boxes. For each ref say "confirmed", "wrong-class" (with suggestedClass), "not-an-object" or "uncertain", with a short reason:\n${boxes.join("\n")}` : "2. There are no existing boxes to review: answer \"reviews\": [].",
+			"Answer with JSON: {\"objects\": [...], \"reviews\": [...]}."
+		].join("\n"),
+		jsonSchema: answerJsonSchema(input.classes)
+	};
+}
+/** The whole answer: two arrays and nothing else. Items are checked one by one. */
+var AnswerSchema = require_clip_model_registry.strictObject({
+	objects: require_clip_model_registry.array(require_clip_model_registry.unknown()),
+	reviews: require_clip_model_registry.array(require_clip_model_registry.unknown())
+});
+var ObjectSchema = require_clip_model_registry.strictObject({
+	class: require_clip_model_registry.string(),
+	label: require_clip_model_registry.string().optional(),
+	box: require_clip_model_registry.tuple([
+		require_clip_model_registry.number(),
+		require_clip_model_registry.number(),
+		require_clip_model_registry.number(),
+		require_clip_model_registry.number()
+	]),
+	confidence: require_clip_model_registry.number().min(0).max(1),
+	reason: require_clip_model_registry.string().max(500)
+});
+var ReviewSchema = require_clip_model_registry.strictObject({
+	ref: require_clip_model_registry.string(),
+	verdict: require_clip_model_registry._enum(VERDICTS),
+	suggestedClass: require_clip_model_registry.string().optional(),
+	reason: require_clip_model_registry.string().max(500)
+});
+function frameBox(box) {
+	const [x, y, w, h] = box;
+	if (![
+		x,
+		y,
+		w,
+		h
+	].every(Number.isFinite)) return null;
+	if (!(w > 0) || !(h > 0) || x < -.01 || y < -.01) return null;
+	if (x + w > 1.01 || y + h > 1.01) return null;
+	const cx = Math.max(0, x);
+	const cy = Math.max(0, y);
+	return {
+		x: cx,
+		y: cy,
+		w: Math.min(w, 1 - cx),
+		h: Math.min(h, 1 - cy)
+	};
+}
+/** Strip a Markdown code fence a model wrapped its JSON in. */
+function unfence(text) {
+	const trimmed = text.trim();
+	const fence = /^```(?:json)?\s*\n([\s\S]*?)\n?```$/i.exec(trimmed);
+	return fence?.[1] !== void 0 ? fence[1].trim() : trimmed;
+}
+/** A free-text label, never a macro word (the tier rule). */
+function usableLabel(label) {
+	const trimmed = label?.trim();
+	if (trimmed === void 0 || trimmed === "") return void 0;
+	return isRetrainMacroClass(trimmed.toLowerCase()) ? void 0 : trimmed;
+}
+/** Parse the model's answer. See the module header for the rules. */
+function parseLlmAssistAnswer(text, expected) {
+	let raw;
+	try {
+		raw = JSON.parse(unfence(text));
+	} catch {
+		return {
+			kind: "malformed",
+			detail: "the answer is not JSON"
+		};
+	}
+	const answer = AnswerSchema.safeParse(raw);
+	if (!answer.success) return {
+		kind: "malformed",
+		detail: "the answer is not {\"objects\": [...], \"reviews\": [...]}"
+	};
+	const asked = new Set(expected.classes);
+	let rejected = 0;
+	const objects = [];
+	for (const item of answer.data.objects) {
+		const parsed = ObjectSchema.safeParse(item);
+		const cls = parsed.success ? parsed.data.class.trim().toLowerCase() : "";
+		const bbox = parsed.success ? frameBox(parsed.data.box) : null;
+		if (!parsed.success || bbox === null || !asked.has(cls) || !isRetrainMacroClass(cls)) {
+			rejected += 1;
+			continue;
+		}
+		const label = usableLabel(parsed.data.label);
+		objects.push({
+			macroClass: cls,
+			...label !== void 0 ? { label } : {},
+			bbox,
+			confidence: parsed.data.confidence,
+			reason: parsed.data.reason
+		});
+	}
+	const reviews = [];
+	for (const item of answer.data.reviews) {
+		const parsed = ReviewSchema.safeParse(item);
+		if (!parsed.success || !expected.refs.has(parsed.data.ref)) {
+			rejected += 1;
+			continue;
+		}
+		const suggested = parsed.data.suggestedClass?.trim().toLowerCase();
+		reviews.push({
+			ref: parsed.data.ref,
+			verdict: parsed.data.verdict,
+			...suggested !== void 0 && isRetrainMacroClass(suggested) ? { suggestedClass: suggested } : {},
+			reason: parsed.data.reason
+		});
+	}
+	return {
+		kind: "parsed",
+		objects,
+		reviews,
+		rejected
+	};
+}
+//#endregion
+//#region src/pipeline-analytics/retrain/retrain-llm-service.ts
+/** The usage tag every AI-assist call is counted under (`llm.getUsage`). */
+var RETRAIN_LLM_CONSUMER = "retrain-assist";
+/** One frame, one answer: a cold local vision model can take a minute. */
+var RETRAIN_LLM_TIMEOUT_MS = 15e4;
+var RetrainLlmAssistService = class {
+	deps;
+	constructor(deps) {
+		this.deps = deps;
+	}
+	/** The enabled, vision-capable profiles — a text-only one would be refused. */
+	async listProfiles() {
+		return (await this.deps.llm.listProfiles()).filter((p) => p.enabled && p.supportsVision).map((p) => ({
+			id: p.id,
+			name: p.name,
+			model: p.model,
+			kind: p.kind,
+			leavesHouse: llmProfileLeavesHouse(p)
+		}));
+	}
+	async propose(input) {
+		const tags = { deviceId: input.deviceId };
+		const frame = await this.deps.frames.get(input.frameId);
+		if (frame === null || frame.deviceId !== input.deviceId || input.trackId !== void 0 && frame.trackId !== input.trackId) return {
+			kind: "refused",
+			reason: "unknown-frame"
+		};
+		const profile = (await this.deps.llm.listProfiles()).find((p) => p.id === input.profileId);
+		if (profile === void 0) return {
+			kind: "refused",
+			reason: "unknown-profile"
+		};
+		if (!profile.enabled) return {
+			kind: "refused",
+			reason: "profile-disabled"
+		};
+		if (!profile.supportsVision) return {
+			kind: "refused",
+			reason: "no-vision"
+		};
+		const leavesHouse = llmProfileLeavesHouse(profile);
+		if (leavesHouse && !input.allowCloud) {
+			this.deps.logger.warn("retrain AI assist refused: a cloud profile without confirmation", {
+				tags,
+				meta: {
+					frameId: input.frameId,
+					profileId: profile.id
+				}
+			});
 			return {
-				id: row.id,
-				name: typeof row.data["name"] === "string" ? row.data["name"] : "",
-				createdAt: Number(row.data["createdAt"] ?? 0),
-				frameCount: 0
+				kind: "refused",
+				reason: "cloud-not-confirmed",
+				detail: "this profile sends the frame outside the house; confirm the run first"
 			};
-		} catch (err) {
-			this.logger.warn("retrain collection findByNameKey failed", { meta: {
-				nameKey,
-				error: String(err)
-			} });
-			return null;
 		}
+		const bytes = await this.deps.frames.readFrame(frame);
+		if (bytes === null) return {
+			kind: "refused",
+			reason: "unreadable-frame"
+		};
+		const request = buildLlmAssistRequest({
+			classes: input.classes,
+			width: frame.width,
+			height: frame.height,
+			boxes: input.boxes
+		});
+		const answer = await this.deps.llm.generateVision({
+			profileId: profile.id,
+			system: request.system,
+			prompt: request.prompt,
+			jsonSchema: request.jsonSchema,
+			image: bytes
+		});
+		if (!answer.ok) {
+			this.deps.logger.warn("retrain AI assist: the model call failed", {
+				tags,
+				meta: {
+					frameId: input.frameId,
+					profileId: profile.id,
+					code: answer.code
+				}
+			});
+			return {
+				kind: "refused",
+				reason: "llm-error",
+				detail: `${answer.code}: ${answer.message}`
+			};
+		}
+		const parsed = parseLlmAssistAnswer(answer.text, {
+			classes: input.classes,
+			refs: new Set(input.boxes.map((b) => b.ref))
+		});
+		if (parsed.kind === "malformed") {
+			this.deps.logger.warn("retrain AI assist: the answer was refused as malformed", {
+				tags,
+				meta: {
+					frameId: input.frameId,
+					profileId: profile.id,
+					model: answer.model,
+					detail: parsed.detail,
+					answerChars: answer.text.length
+				}
+			});
+			return {
+				kind: "refused",
+				reason: "malformed-answer",
+				detail: parsed.detail
+			};
+		}
+		this.deps.logger.info("retrain AI assist proposed boxes", {
+			tags,
+			meta: {
+				frameId: input.frameId,
+				profileId: profile.id,
+				model: answer.model,
+				leftHouse: leavesHouse,
+				proposals: parsed.objects.length,
+				reviews: parsed.reviews.length,
+				rejected: parsed.rejected
+			}
+		});
+		return {
+			kind: "proposed",
+			profileId: profile.id,
+			model: answer.model,
+			leftHouse: leavesHouse,
+			proposals: parsed.objects.map((o) => ({
+				bbox: o.bbox,
+				macroClass: o.macroClass,
+				...o.label !== void 0 ? { label: o.label } : {},
+				kind: "subject",
+				source: "llm",
+				assistModelId: answer.model,
+				assistScore: o.confidence,
+				reason: o.reason
+			})),
+			reviews: parsed.reviews.map((r) => ({
+				ref: r.ref,
+				verdict: r.verdict,
+				...r.suggestedClass !== void 0 ? { suggestedClass: r.suggestedClass } : {},
+				reason: r.reason
+			})),
+			rejected: parsed.rejected
+		};
 	}
 };
 //#endregion
@@ -83233,12 +84248,18 @@ var RETRAIN_CROP_CONVENTION = require_clip_model_registry.DEFAULT_DETAIL_CROP_CO
 /** Longest side of a `crops`-layout JPEG. Classifier inputs are 224–260 px;
 *  the trainer resizes per model, so this only bounds the upload. */
 var RETRAIN_CROP_MAX_SIDE = 256;
-/** Manifest schema id. v2 = capturedAt / complete / lighting / layout. */
-var RETRAIN_MANIFEST_SCHEMA = "camstack.retrain-export/v2";
-/** Archive path of a frame: `frames/<deviceId>/<trackId>/<frameId leaf>.jpg`. */
+/**
+* Manifest schema id. v2 = capturedAt / complete / lighting / layout.
+* v3 = `origin` (`track` | `recording`), `epochMs` on a recording still,
+* `collectionIds`, and `trackId` ABSENT on a recording still, which has none.
+*/
+var RETRAIN_MANIFEST_SCHEMA = "camstack.retrain-export/v3";
+/** Archive path of a frame: `frames/<deviceId>/<trackId>/<frameId leaf>.jpg`,
+*  or `frames/<deviceId>/recording/<leaf>.jpg` for a recording still. */
 function retrainFramePath(frame) {
 	const leaf = frame.frameId.slice(frame.frameId.lastIndexOf(":") + 1);
-	return `frames/${frame.deviceId}/${frame.trackId}/${leaf}.jpg`;
+	const dir = frame.origin === "recording" ? RECORDING_STILL_DIR : frame.trackId;
+	return `frames/${frame.deviceId}/${dir}/${leaf}.jpg`;
 }
 /** Archive path of a subject crop: `crops/<macroClass>/<annotationId>.jpg`. */
 function retrainCropPath(macroClass, annotationId) {
@@ -83248,13 +84269,15 @@ function retrainCropPath(macroClass, annotationId) {
 * Narrow the planned frames to a filter. Pure. Every field narrows; an empty
 * filter keeps everything. Order is the input's.
 */
-function filterRetrainExport(frames, annotationsByFrame, filter) {
+function filterRetrainExport(frames, annotationsByFrame, filter, collectionsByFrame = /* @__PURE__ */ new Map()) {
 	const wanted = filter.frameIds !== void 0 ? new Set(filter.frameIds) : null;
+	const collections = filter.collectionIds !== void 0 && filter.collectionIds.length > 0 ? new Set(filter.collectionIds) : null;
 	const devices = filter.deviceIds !== void 0 && filter.deviceIds.length > 0 ? new Set(filter.deviceIds) : null;
 	return frames.filter((frame) => {
 		if (wanted !== null && !wanted.has(frame.frameId)) return false;
 		if (devices !== null && !devices.has(frame.deviceId)) return false;
 		if (filter.completeOnly === true && !frame.complete) return false;
+		if (collections !== null && !(collectionsByFrame.get(frame.frameId) ?? []).some((id) => collections.has(id))) return false;
 		if (filter.batchId !== void 0) {
 			if (!(annotationsByFrame.get(frame.frameId) ?? []).some((a) => a.exportedInBatch === filter.batchId)) return false;
 		}
@@ -83309,7 +84332,10 @@ function buildRetrainManifest(input) {
 			frameId: frame.frameId,
 			path: retrainFramePath(frame),
 			deviceId: frame.deviceId,
-			trackId: frame.trackId,
+			origin: frame.origin,
+			...frame.origin === "track" ? { trackId: frame.trackId } : {},
+			...frame.epochMs !== void 0 ? { epochMs: frame.epochMs } : {},
+			collectionIds: input.collectionsByFrame?.get(frame.frameId) ?? [],
 			width: frame.width,
 			height: frame.height,
 			sizeBytes: frame.sizeBytes,
@@ -83348,11 +84374,13 @@ function parseRetrainExportRequest(url) {
 	const params = new URLSearchParams(query);
 	const deviceIds = parseRetrainDeviceIds(url);
 	const frameIds = (params.get("frameIds") ?? "").split(",").map((id) => id.trim()).filter((id) => id.length > 0);
+	const collectionIds = (params.get("collectionIds") ?? "").split(",").map((id) => id.trim()).filter((id) => id.length > 0);
 	const batchId = params.get("batchId")?.trim() ?? "";
 	return {
 		filter: {
 			...deviceIds.length > 0 ? { deviceIds: [...deviceIds] } : {},
 			...frameIds.length > 0 ? { frameIds } : {},
+			...collectionIds.length > 0 ? { collectionIds } : {},
 			...batchId.length > 0 ? { batchId } : {},
 			...params.get("completeOnly") === "1" ? { completeOnly: true } : {}
 		},
@@ -83365,6 +84393,7 @@ function retrainExportQuery(request) {
 	const { filter } = request;
 	if (filter.deviceIds !== void 0 && filter.deviceIds.length > 0) params.set("deviceIds", filter.deviceIds.join(","));
 	if (filter.frameIds !== void 0 && filter.frameIds.length > 0) params.set("frameIds", filter.frameIds.join(","));
+	if (filter.collectionIds !== void 0 && filter.collectionIds.length > 0) params.set("collectionIds", filter.collectionIds.join(","));
 	if (filter.batchId !== void 0) params.set("batchId", filter.batchId);
 	if (filter.completeOnly === true) params.set("completeOnly", "1");
 	if (request.layout === "crops") params.set("layout", "crops");
@@ -83439,6 +84468,178 @@ function createRetrainExportHandler(deps) {
 	};
 }
 //#endregion
+//#region src/pipeline-analytics/retrain/retrain-pipeline-boxes.ts
+/**
+* The boxes the PIPELINE drew on a copied frame — Step 1 of the training
+* screen.
+*
+* A correction has to start from the decision being corrected. Proposing with
+* a fresh model run answers a different question ("what would a model say
+* now"), and the frame the operator is fixing is precisely the one where the
+* live answer was wrong — a re-run that happens to be right hides the phantom
+* the operator came to remove. So the canvas opens with what the track store
+* says the pipeline had on that frame, and the operator accepts, corrects,
+* relabels or deletes it.
+*
+* ## Where a box comes from, best first
+*
+* 1. **The subject box recorded ON the source media row** (D510). Exact by
+*    construction: the box was measured on the frame the blob shows. Only the
+*    copy's own track can have one.
+* 2. **The track position nearest the capture time**, within
+*    {@link PIPELINE_BOX_TOLERANCE_MS}. Positions are frame-rate, so the
+*    nearest one is normally the same detection; the delta is reported so a
+*    reviewer can see how far it was.
+*
+* Every OTHER track alive on the camera at that instant contributes its own
+* nearest position the same way — a frame with three people is three boxes,
+* and a recording still (no track of its own) gets everything the pipeline
+* was tracking at that moment, which is exactly what a missed-object review
+* needs to see is NOT there.
+*
+* Nothing here does I/O. The caller reads the tracks and the subject box.
+*/
+/** How far from the capture time a position may be and still be "this frame".
+*  Positions are recorded at the analysis rate (several per second), so half
+*  a second is a generous match and still not a different moment. */
+var PIPELINE_BOX_TOLERANCE_MS = 500;
+/**
+* How far back a track may have STARTED and still be alive at the frame. The
+* track store windows on `firstSeen`, so a track born before this is not
+* asked about — a vehicle parked for hours is the case it misses, and the
+* operator draws that box by hand.
+*/
+var PIPELINE_TRACK_LOOKBACK_MS = 30 * 6e4;
+/** At most this many tracks of one camera are read around one frame. */
+var PIPELINE_TRACK_AROUND_LIMIT = 200;
+/** The least-wrong macro tier for a class the macro map does not know. The
+*  operator corrects it; what must not happen is the raw string being
+*  promoted into the macro tier. */
+var FALLBACK_MACRO_CLASS = "person";
+/**
+* Split a detector's class into the two tiers.
+*
+* A macro class stays in the macro tier; anything else maps through the COCO
+* macro map, and the class itself becomes the LABEL. A macro word is never a
+* label, in any casing — the tier rule the annotation write enforces.
+*/
+function toRetrainClassTiers(className, label) {
+	const cls = className.trim().toLowerCase();
+	const usableLabel = (value) => {
+		const trimmed = value?.trim();
+		if (trimmed === void 0 || trimmed === "") return void 0;
+		return isRetrainMacroClass(trimmed.toLowerCase()) ? void 0 : trimmed;
+	};
+	if (isRetrainMacroClass(cls)) {
+		const kept = usableLabel(label);
+		return kept !== void 0 ? {
+			macroClass: cls,
+			label: kept
+		} : { macroClass: cls };
+	}
+	const mapped = require_clip_model_registry.COCO_TO_MACRO.mapping[cls];
+	const macroClass = mapped !== void 0 && isRetrainMacroClass(mapped) ? mapped : FALLBACK_MACRO_CLASS;
+	const kept = usableLabel(className);
+	return kept !== void 0 ? {
+		macroClass,
+		label: kept
+	} : { macroClass };
+}
+/** A pixel box as a clamped normalised one, or `null` when nothing is left. */
+function normalise(box, frameWidth, frameHeight) {
+	if (frameWidth === void 0 || frameHeight === void 0) return null;
+	if (!(frameWidth > 0) || !(frameHeight > 0)) return null;
+	const x = clampSpan(box.x, box.w, frameWidth);
+	const y = clampSpan(box.y, box.h, frameHeight);
+	if (x === null || y === null) return null;
+	return {
+		x: x.start,
+		y: y.start,
+		w: x.size,
+		h: y.size
+	};
+}
+/** One axis of a pixel box, normalised and clamped into `[0,1]`. The size is
+*  divided directly when nothing was clamped, so an exact box stays exact. */
+function clampSpan(start, size, extent) {
+	const lo = start / extent;
+	const hi = (start + size) / extent;
+	const s = Math.max(0, lo);
+	const n = lo >= 0 && hi <= 1 ? size / extent : Math.min(1, hi) - s;
+	return n > 0 ? {
+		start: s,
+		size: n
+	} : null;
+}
+function nearestPosition(track, at, tolerance) {
+	let best = null;
+	let bestDelta = Number.POSITIVE_INFINITY;
+	for (const p of track.positions) {
+		const delta = Math.abs(p.timestamp - at);
+		if (delta < bestDelta) {
+			best = p;
+			bestDelta = delta;
+		}
+	}
+	if (best === null || bestDelta > tolerance) return null;
+	return {
+		position: best,
+		deltaMs: bestDelta
+	};
+}
+function boxFor(track, bbox, basis, deltaMs, score) {
+	const tiers = toRetrainClassTiers(track.className, track.label);
+	const subLabel = track.subLabel?.trim();
+	return {
+		bbox,
+		macroClass: tiers.macroClass,
+		...tiers.label !== void 0 ? { label: tiers.label } : {},
+		...subLabel !== void 0 && subLabel !== "" && !isRetrainMacroClass(subLabel.toLowerCase()) ? { subLabel } : {},
+		...score !== void 0 ? { score } : {},
+		...track.modelId !== void 0 ? { modelId: track.modelId } : {},
+		trackId: track.trackId,
+		basis,
+		deltaMs
+	};
+}
+/** The own track's box: the recorded subject box first, the nearest position second. */
+function ownBox(input, tolerance) {
+	const track = input.ownTrack;
+	if (track === null) return null;
+	const at = input.frame.capturedAt;
+	const nearest = at !== void 0 ? nearestPosition(track, at, tolerance) : null;
+	if (input.ownSubjectBox !== null) {
+		const recorded = normalise(input.ownSubjectBox, input.ownSubjectBox.frameWidth, input.ownSubjectBox.frameHeight);
+		if (recorded !== null) return boxFor(track, recorded, "subject-box", 0, nearest?.position.score);
+	}
+	if (nearest === null) return null;
+	const placed = normalise(nearest.position.bbox, track.frameWidth, track.frameHeight);
+	return placed === null ? null : boxFor(track, placed, "position", nearest.deltaMs, nearest.position.score);
+}
+/**
+* Every box the pipeline had on this frame, own track first. Pure.
+*/
+function pipelineBoxesForFrame(input) {
+	const tolerance = input.toleranceMs ?? PIPELINE_BOX_TOLERANCE_MS;
+	const out = [];
+	const own = ownBox(input, tolerance);
+	if (own !== null) out.push(own);
+	const at = input.frame.capturedAt;
+	if (at === void 0) return out;
+	const ownId = input.frame.trackId;
+	const seen = new Set(ownId !== void 0 ? [ownId] : []);
+	for (const track of input.neighbours) {
+		if (seen.has(track.trackId) || track.deviceId !== input.frame.deviceId) continue;
+		seen.add(track.trackId);
+		const nearest = nearestPosition(track, at, tolerance);
+		if (nearest === null) continue;
+		const placed = normalise(nearest.position.bbox, track.frameWidth, track.frameHeight);
+		if (placed === null) continue;
+		out.push(boxFor(track, placed, "position", nearest.deltaMs, nearest.position.score));
+	}
+	return out;
+}
+//#endregion
 //#region src/pipeline-analytics/retrain/retrain-assist.ts
 /** The whole frame, as a normalised rectangle. */
 var WHOLE_FRAME = {
@@ -83509,12 +84710,11 @@ function mapAssistDetails(input) {
 			withoutBox += 1;
 			continue;
 		}
-		const macroClass = isRetrainMacroClass(d.className) ? d.className : FALLBACK_MACRO_CLASS;
-		const label = isRetrainMacroClass(d.className) ? d.label : d.className;
+		const tiers = toRetrainClassTiers(d.className, d.label);
 		proposals.push({
 			bbox,
-			macroClass,
-			...label !== void 0 && label !== "" ? { label } : {},
+			macroClass: tiers.macroClass,
+			...tiers.label !== void 0 ? { label: tiers.label } : {},
 			score: d.score,
 			modelId
 		});
@@ -83525,16 +84725,6 @@ function mapAssistDetails(input) {
 		withoutBox
 	};
 }
-/**
-* Macro tier for a detector class we do not carry as a macro class.
-*
-* The class itself becomes the LABEL (see above) and the macro tier gets a
-* value the operator will almost certainly correct — which is fine, because it
-* is a PROPOSAL and correcting it is the job. What must not happen is the
-* detector's own string being promoted into the macro tier: that is how
-* `postman` becomes a class with one example in it.
-*/
-var FALLBACK_MACRO_CLASS = "person";
 /** A proposal, as a draft annotation ready to store if the operator accepts it. */
 function proposalToDraft(proposal, owner) {
 	return {
@@ -83743,12 +84933,18 @@ async function restageRetrainTrack(deps, input) {
 var DEFAULT_STAGING_LIMIT = 100;
 /** A macro class that failed validation — the write is refused, never coerced. */
 var RetrainAnnotationError = class extends Error {};
+/** A store frame on the wire. A recording still carries no track and no
+*  source media row, and says so by leaving both out. */
 function toWireFrame(f) {
 	return {
 		frameId: f.frameId,
 		deviceId: f.deviceId,
-		trackId: f.trackId,
-		sourceMediaId: f.sourceMediaId,
+		origin: f.origin,
+		...f.origin === "track" ? {
+			trackId: f.trackId,
+			sourceMediaId: f.sourceMediaId
+		} : {},
+		...f.epochMs !== void 0 ? { epochMs: f.epochMs } : {},
 		sourceKind: f.sourceKind,
 		sizeBytes: f.sizeBytes,
 		width: f.width,
@@ -83761,7 +84957,7 @@ function toWireFrame(f) {
 function toWireAnnotation(a) {
 	return {
 		id: a.id,
-		trackId: a.trackId,
+		...a.trackId !== "" ? { trackId: a.trackId } : {},
 		deviceId: a.deviceId,
 		mediaKey: a.mediaKey,
 		bbox: a.bbox,
@@ -83828,11 +85024,116 @@ var RetrainService = class {
 		if (candidates.length === 0) await this.logNoAnnotatableFrame(trackId, media, copies.length);
 		return {
 			candidates,
-			copies: copies.map(toWireFrame),
+			copies: await this.toWireFrames(copies),
 			...autoPick !== null ? { autoPickMediaId: autoPick.mediaId } : {}
 		};
 	}
 	/**
+	* The wire frames, each with the boxes the pipeline drew on it (Step 1) and
+	* the collections it belongs to.
+	*
+	* Index reads only — the track rows and the media rows' subject boxes, no
+	* blob and no inference. One read per distinct track and per distinct
+	* instant, not per box. A failed read degrades to fewer boxes, logged, and
+	* never to a failed listing: the frames are the operator's work and must
+	* stay reachable when the evidence is not.
+	*/
+	async toWireFrames(copies) {
+		const collections = this.deps.memberships !== void 0 && copies.length > 0 ? await this.deps.memberships.collectionsOf(copies.map((c) => c.frameId)).catch((err) => {
+			this.deps.logger.warn("retrain frames: collection membership unreadable", { meta: {
+				frames: copies.length,
+				error: String(err)
+			} });
+			return /* @__PURE__ */ new Map();
+		}) : null;
+		const evidence = this.deps.pipelineEvidence;
+		const ownTracks = /* @__PURE__ */ new Map();
+		const subjectBoxes = /* @__PURE__ */ new Map();
+		const out = [];
+		for (const copy of copies) {
+			const wire = toWireFrame(copy);
+			const collectionIds = collections?.get(copy.frameId);
+			const withCollections = collections !== null ? {
+				...wire,
+				collectionIds: collectionIds ?? []
+			} : wire;
+			if (evidence === void 0) {
+				out.push(withCollections);
+				continue;
+			}
+			const trackId = copy.origin === "track" ? copy.trackId : "";
+			if (trackId !== "" && !ownTracks.has(trackId)) {
+				ownTracks.set(trackId, await this.deps.tracks.getPersistedByTrackId(trackId).catch(() => null));
+				subjectBoxes.set(trackId, await this.readSubjectBoxes(evidence, trackId, copy.deviceId));
+			}
+			const neighbours = copy.capturedAt !== void 0 ? await this.readTracksAround(evidence, copy.deviceId, copy.capturedAt) : [];
+			const pipelineBoxes = pipelineBoxesForFrame({
+				frame: {
+					deviceId: copy.deviceId,
+					...trackId !== "" ? { trackId } : {},
+					...copy.capturedAt !== void 0 ? { capturedAt: copy.capturedAt } : {}
+				},
+				ownTrack: trackId !== "" ? ownTracks.get(trackId) ?? null : null,
+				ownSubjectBox: trackId !== "" ? subjectBoxes.get(trackId)?.get(copy.sourceMediaId) ?? null : null,
+				neighbours
+			});
+			out.push({
+				...withCollections,
+				pipelineBoxes
+			});
+		}
+		return out;
+	}
+	/**
+	* The frame a frame-scoped call names, or a refusal. The frame is the
+	* authority: its camera must be the caller's, and a `trackId`, when the
+	* caller sends one, must be the frame's own — a recording still has none.
+	*/
+	async requireFrame(ref, action) {
+		const frame = await this.deps.frames.get(ref.frameId);
+		const trackMismatch = frame !== null && ref.trackId !== void 0 && (frame.origin !== "track" || frame.trackId !== ref.trackId);
+		if (frame === null || frame.deviceId !== ref.deviceId || trackMismatch) {
+			this.deps.logger.warn(`retrain ${action} refused: the frame does not belong to that camera or track`, {
+				tags: { deviceId: ref.deviceId },
+				meta: {
+					frameId: ref.frameId,
+					...ref.trackId !== void 0 ? { trackId: ref.trackId } : {}
+				}
+			});
+			throw new RetrainAnnotationError(frame === null ? `retrain frame ${ref.frameId} does not exist — select it before annotating it` : `retrain frame ${ref.frameId} does not belong to ${ref.trackId !== void 0 ? `track ${ref.trackId}` : `camera ${String(ref.deviceId)}`}`);
+		}
+		return frame;
+	}
+	async readSubjectBoxes(evidence, trackId, deviceId) {
+		try {
+			const rows = await evidence.subjectBoxes(trackId, deviceId);
+			return new Map(rows.map((r) => [r.mediaId, r.subjectBox]));
+		} catch (err) {
+			this.deps.logger.warn("retrain pipeline boxes: subject boxes unreadable", {
+				tags: { deviceId },
+				meta: {
+					trackId,
+					error: String(err)
+				}
+			});
+			return /* @__PURE__ */ new Map();
+		}
+	}
+	async readTracksAround(evidence, deviceId, atMs) {
+		try {
+			return await evidence.tracksAround(deviceId, atMs);
+		} catch (err) {
+			this.deps.logger.warn("retrain pipeline boxes: tracks around the frame unreadable", {
+				tags: { deviceId },
+				meta: {
+					atMs,
+					error: String(err)
+				}
+			});
+			return [];
+		}
+	}
+	/**
 	* A track with no annotatable frame is a REAL state, and the page has to say
 	* so rather than render an empty strip that reads as a slow load. Two causes,
 	* named apart: the whole-frame media AGED OUT, or the track only ever held
@@ -83885,23 +85186,13 @@ var RetrainService = class {
 	* track the caller names: a frame of another track is refused, loudly.
 	*/
 	async setFrameComplete(input) {
-		const frame = await this.deps.frames.get(input.frameId);
-		if (frame === null || frame.trackId !== input.trackId || frame.deviceId !== input.deviceId) {
-			this.deps.logger.warn("retrain complete refused: the frame does not belong to that track", {
-				tags: { deviceId: input.deviceId },
-				meta: {
-					trackId: input.trackId,
-					frameId: input.frameId
-				}
-			});
-			throw new RetrainAnnotationError(`retrain frame ${input.frameId} does not belong to track ${input.trackId}`);
-		}
-		const updated = await this.deps.frames.setComplete(input.frameId, input.complete);
+		const frame = await this.requireFrame(input, "complete");
+		const updated = await this.deps.frames.setComplete(frame.frameId, input.complete);
 		if (updated === null) throw new RetrainAnnotationError(`retrain frame ${input.frameId} vanished`);
 		this.deps.logger.info("retrain frame completeness set", {
 			tags: { deviceId: input.deviceId },
 			meta: {
-				trackId: input.trackId,
+				trackId: frame.trackId,
 				frameId: input.frameId,
 				complete: input.complete
 			}
@@ -83909,36 +85200,41 @@ var RetrainService = class {
 		return toWireFrame(updated);
 	}
 	/** Un-select: annotations first, then the copy. Never the other way round —
-	*  an annotation whose frame is gone is unopenable and unfixable. */
+	*  an annotation whose frame is gone is unopenable and unfixable. The frame's
+	*  collection memberships go with it. */
 	async deselectFrame(input) {
 		const frame = await this.deps.frames.get(input.frameId);
 		if (frame === null) {
 			this.deps.logger.warn("retrain deselect: no such copied frame", {
 				tags: { deviceId: input.deviceId },
-				meta: {
-					trackId: input.trackId,
-					frameId: input.frameId
-				}
+				meta: { frameId: input.frameId }
 			});
 			return {
 				removed: false,
 				removedAnnotations: 0
 			};
 		}
-		const removedAnnotations = await this.deps.annotations.deleteForFrame(input.frameId);
+		await this.requireFrame(input, "deselect");
+		return {
+			removed: true,
+			removedAnnotations: await this.removeFrame(frame)
+		};
+	}
+	/** Remove a frame from the dataset: annotations, memberships, then the copy. */
+	async removeFrame(frame) {
+		const removedAnnotations = await this.deps.annotations.deleteForFrame(frame.frameId);
+		await this.deps.memberships?.forgetFrame(frame.frameId);
 		await this.deps.frames.deleteFrame(frame);
 		this.deps.logger.info("retrain frame removed from the dataset", {
-			tags: { deviceId: input.deviceId },
+			tags: { deviceId: frame.deviceId },
 			meta: {
-				trackId: input.trackId,
-				frameId: input.frameId,
+				origin: frame.origin,
+				...frame.origin === "track" ? { trackId: frame.trackId } : {},
+				frameId: frame.frameId,
 				removedAnnotations
 			}
 		});
-		return {
-			removed: true,
-			removedAnnotations
-		};
+		return removedAnnotations;
 	}
 	/** The copy's pixels plus its exact dimensions — the canvas needs both. */
 	async getFrameImage(frameId) {
@@ -83978,7 +85274,7 @@ var RetrainService = class {
 			};
 		}
 		const frame = await this.deps.frames.get(input.frameId);
-		if (frame === null) return {
+		if (frame === null || frame.deviceId !== input.deviceId || input.trackId !== void 0 && frame.trackId !== input.trackId) return {
 			kind: "refused",
 			reason: "unknown-frame"
 		};
@@ -84033,8 +85329,8 @@ var RetrainService = class {
 			}
 		});
 		const owner = {
-			trackId: input.trackId,
-			deviceId: input.deviceId,
+			trackId: frame.trackId,
+			deviceId: frame.deviceId,
 			mediaKey: input.frameId
 		};
 		return {
@@ -84057,8 +85353,12 @@ var RetrainService = class {
 			belowThreshold: mapping.belowThreshold
 		};
 	}
-	async listAnnotations(trackId) {
-		return (await this.deps.annotations.listByTrack(trackId)).map(toWireAnnotation);
+	/** The annotations of a track, or of named frames (a recording still has
+	*  no track). One of the two must be given. */
+	async listAnnotations(input) {
+		if (input.trackId !== void 0 && input.trackId !== "") return (await this.deps.annotations.listByTrack(input.trackId)).map(toWireAnnotation);
+		if (input.frameIds !== void 0) return (await this.deps.annotations.listByFrames(input.frameIds)).map(toWireAnnotation);
+		throw new RetrainAnnotationError("listRetrainAnnotations needs a trackId or frameIds");
 	}
 	/**
 	* Replace every annotation on one frame.
@@ -84070,15 +85370,15 @@ var RetrainService = class {
 	* believes they stored.
 	*/
 	async saveAnnotations(input) {
-		if (await this.deps.frames.get(input.frameId) === null) throw new RetrainAnnotationError(`retrain frame ${input.frameId} does not exist — select it before annotating it`);
+		const frame = await this.requireFrame(input, "save");
 		for (const a of input.annotations) {
 			if (!isRetrainMacroClass(a.macroClass)) throw new RetrainAnnotationError(`"${a.macroClass}" is not a macro class`);
 			const violation = checkTierSeparation(a);
 			if (violation !== null) throw new RetrainAnnotationError(`"${violation.value}" is a MACRO CLASS and cannot be a ${violation.field} — the tiers are separate (person / postman / Marco)`);
 		}
 		const drafts = input.annotations.map((a) => ({
-			trackId: input.trackId,
-			deviceId: input.deviceId,
+			trackId: frame.trackId,
+			deviceId: frame.deviceId,
 			mediaKey: input.frameId,
 			bbox: a.bbox,
 			macroClass: a.macroClass,
@@ -84094,7 +85394,8 @@ var RetrainService = class {
 		this.deps.logger.info("retrain annotations saved", {
 			tags: { deviceId: input.deviceId },
 			meta: {
-				trackId: input.trackId,
+				origin: frame.origin,
+				trackId: frame.trackId,
 				frameId: input.frameId,
 				subjects: saved.length - errors,
 				modelErrors: errors
@@ -93496,6 +94797,14 @@ var RECORDED_STILL_PROFILE = "high";
 */
 var RECOVERED_KEY_FRAME_MAX_WIDTH = 1920;
 /**
+* Width cap for a still added to the retrain dataset from the recording.
+*
+* Effectively none: a training frame is wanted at the camera's own resolution
+* (the same pixels a native key frame has), so the bound is only a ceiling
+* against a pathological stream, far above any camera on the fleet.
+*/
+var RETRAIN_STILL_MAX_WIDTH = 7680;
+/**
 * Build the production ports.
 *
 * Every port swallows its own failure into the `null` the policy expects: a
@@ -107191,6 +108500,9 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_clip_m
 	/** The retrain curation surface — see `retrain/retrain-service.ts`. Null
 	*  until the stores are built. */
 	retrain = null;
+	retrainCollections = null;
+	retrainLlmAssist = null;
+	retrainCollectionStore = null;
 	retrainFrames = null;
 	retrainAnnotations = null;
 	/** The NC artifact plane (signed public links for notification media) and its
@@ -109242,7 +110554,14 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_clip_m
 		});
 		this.retrainFrames = retrainFrames;
 		this.retrainAnnotations = retrainAnnotations;
-		this.retrain = new RetrainService({
+		const retrainCollectionStore = new RetrainCollectionStore({
+			store: api.settingsStore,
+			logger: logger.child("RetrainCollections"),
+			now: () => Date.now(),
+			newId: () => (0, node_crypto.randomUUID)()
+		});
+		this.retrainCollectionStore = retrainCollectionStore;
+		const retrain = new RetrainService({
 			tracks: {
 				listStaging: (deviceId, limit) => trackStore.listStaging(deviceId, limit),
 				listDeviceIds: () => trackStore.listDeviceIds(),
@@ -109260,7 +110579,70 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_clip_m
 			frames: retrainFrames,
 			annotations: retrainAnnotations,
 			runner: (input, nodeId) => nodeId === void 0 ? api.pipelineRunner.runStatelessStep.mutate(input) : api.pipelineRunner.runStatelessStep.mutate(input, require_clip_model_registry.nodePin(nodeId)),
-			logger: logger.child("Retrain")
+			logger: logger.child("Retrain"),
+			pipelineEvidence: {
+				tracksAround: (deviceId, atMs) => trackStore.queryHistorical({
+					deviceId,
+					since: atMs - PIPELINE_TRACK_LOOKBACK_MS,
+					until: atMs + PIPELINE_BOX_TOLERANCE_MS,
+					limit: PIPELINE_TRACK_AROUND_LIMIT
+				}),
+				subjectBoxes: (trackId, deviceId) => mediaStore.listSubjectBoxesByOwner("track", trackId, deviceId)
+			},
+			memberships: retrainCollectionStore
+		});
+		this.retrain = retrain;
+		const retrainStills = new RecordedStillService(buildRecordedStillPorts({
+			api: this.ctx.api.recordingArchive,
+			logger: logger.child("RetrainStills"),
+			resolveFfmpeg: this.pinnedFfmpeg
+		}));
+		this.retrainCollections = new RetrainCollectionService({
+			collections: retrainCollectionStore,
+			frames: retrainFrames,
+			annotations: retrainAnnotations,
+			retrain,
+			captureStill: (deviceId, epochMs) => retrainStills.recover(deviceId, epochMs, RETRAIN_STILL_MAX_WIDTH),
+			logger: logger.child("RetrainCollections")
+		});
+		this.retrainLlmAssist = new RetrainLlmAssistService({
+			frames: retrainFrames,
+			llm: {
+				listProfiles: async () => (await api.llm.listProfiles.query({})).map((p) => ({
+					id: p.id,
+					name: p.name,
+					model: p.model,
+					kind: p.kind,
+					...p.baseUrl !== void 0 ? { baseUrl: p.baseUrl } : {},
+					enabled: p.enabled,
+					supportsVision: p.supportsVision
+				})),
+				generateVision: async (request) => {
+					const result = await api.llm.generateVision.mutate({
+						profileId: request.profileId,
+						consumer: RETRAIN_LLM_CONSUMER,
+						system: request.system,
+						prompt: request.prompt,
+						jsonSchema: request.jsonSchema,
+						images: [{
+							bytes: new Uint8Array(request.image),
+							mimeType: "image/jpeg"
+						}],
+						temperature: 0,
+						timeoutMs: RETRAIN_LLM_TIMEOUT_MS
+					});
+					return result.ok ? {
+						ok: true,
+						text: result.text,
+						model: result.model
+					} : {
+						ok: false,
+						code: result.code,
+						message: result.message
+					};
+				}
+			},
+			logger: logger.child("RetrainLlmAssist")
 		});
 		this.mediaRelocate = new MediaRelocateEngine({
 			store: api.settingsStore,
@@ -110444,14 +111826,14 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_clip_m
 		};
 		return this.requireRetrain().propose({
 			deviceId: input.deviceId,
-			trackId: input.trackId,
+			...input.trackId !== void 0 ? { trackId: input.trackId } : {},
 			frameId: input.frameId,
 			subject,
 			...input.nodeId !== void 0 ? { nodeId: input.nodeId } : {}
 		});
 	}
 	async listRetrainAnnotations(input) {
-		return this.requireRetrain().listAnnotations(input.trackId);
+		return this.requireRetrain().listAnnotations(input);
 	}
 	async saveRetrainAnnotations(input) {
 		return this.requireRetrain().saveAnnotations(input);
@@ -110475,6 +111857,46 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_clip_m
 	async setRetrainFrameComplete(input) {
 		return this.requireRetrain().setFrameComplete(input);
 	}
+	requireRetrainLlmAssist() {
+		const service = this.retrainLlmAssist;
+		if (service === null) throw new Error("retrain AI assist: analytics stores unavailable");
+		return service;
+	}
+	async listRetrainAssistProfiles(_input) {
+		return this.requireRetrainLlmAssist().listProfiles();
+	}
+	async proposeRetrainAnnotationsWithLlm(input) {
+		return this.requireRetrainLlmAssist().propose(input);
+	}
+	requireRetrainCollections() {
+		const service = this.retrainCollections;
+		if (service === null) throw new Error("retrain collections: analytics stores unavailable");
+		return service;
+	}
+	async createRetrainCollection(input) {
+		return this.requireRetrainCollections().create(input);
+	}
+	async listRetrainCollections(_input) {
+		return this.requireRetrainCollections().list();
+	}
+	async renameRetrainCollection(input) {
+		return this.requireRetrainCollections().rename(input);
+	}
+	async deleteRetrainCollection(input) {
+		return this.requireRetrainCollections().delete(input);
+	}
+	async addRetrainFrameFromRecording(input) {
+		return this.requireRetrainCollections().addFrameFromRecording(input);
+	}
+	async addRetrainFramesToCollection(input) {
+		return this.requireRetrainCollections().addFrames(input);
+	}
+	async removeRetrainFrameFromCollection(input) {
+		return this.requireRetrainCollections().removeFrame(input);
+	}
+	async listRetrainCollectionFrames(input) {
+		return this.requireRetrainCollections().listFrames(input);
+	}
 	/**
 	* Stream the annotated archive into ONE HTTP request to `target` — the
 	* training upload. Same bytes as the download; never on the hub's disk.
@@ -110830,7 +112252,7 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_clip_m
 		const trackStore = this.trackStore;
 		if (!frameStore || !annotationStore || !trackStore) throw new Error("retrain export: analytics stores unavailable");
 		const deviceIds = request.filter.deviceIds ?? [];
-		const devices = deviceIds.length > 0 ? deviceIds : await trackStore.listDeviceIds();
+		const devices = deviceIds.length > 0 ? deviceIds : [...new Set([...await trackStore.listDeviceIds(), ...await frameStore.listDeviceIds()])];
 		const candidates = /* @__PURE__ */ new Map();
 		const annotationsByFrame = /* @__PURE__ */ new Map();
 		const zones = /* @__PURE__ */ new Map();
@@ -110847,11 +112269,13 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_clip_m
 			const frame = await frameStore.get(frameId);
 			if (frame !== null) candidates.set(frameId, frame);
 		}
-		const frames = filterRetrainExport([...candidates.values()], annotationsByFrame, request.filter);
+		const collectionsByFrame = await this.retrainCollectionStore?.collectionsOf([...candidates.keys()]) ?? /* @__PURE__ */ new Map();
+		const frames = filterRetrainExport([...candidates.values()], annotationsByFrame, request.filter, collectionsByFrame);
 		return {
 			manifest: buildRetrainManifest({
 				frames,
 				annotationsByFrame,
+				collectionsByFrame,
 				zoneForDevice: (deviceId) => zones.get(deviceId) ?? null,
 				generatedAt: Date.now(),
 				batchId: (0, node_crypto.randomUUID)(),