@camstack/addon-post-analysis 1.2.364 → 1.2.366

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-D8XeJhT4.js");
+const require_clip_model_registry = require("../clip-model-registry-CfYSfakK.js");
 let node_fs = require("node:fs");
 node_fs = require_clip_model_registry.__toESM(node_fs, 1);
 let node_path = require("node:path");
@@ -48402,6 +48402,7 @@ function startAlarmPanelConvergence(ports) {
 var NC_ARTIFACT_READ_PREFIX_REF = NC_ARTIFACT_READ_PREFIX;
 var TRAINING_EXPORT_PREFIX_REF = "training-export";
 var RETRAIN_EXPORT_PREFIX_REF = "retrain-export";
+var RETRAIN_FRAME_PREFIX_REF = "retrain-frame";
 var DEBUG_EXPORT_PREFIX_REF = "debug-export";
 var TAPE_EXPORT_PREFIX_REF = "tape-export";
 /**
@@ -48427,6 +48428,13 @@ var PIPELINE_ANALYTICS_PLANE_ACCESS = {
 	/** Every frame behind a marked selection — a corpus, not an item. */
 	[TRAINING_EXPORT_PREFIX_REF]: "admin",
 	[RETRAIN_EXPORT_PREFIX_REF]: "admin",
+	/**
+	* One copied retrain frame by its id. `admin`, not `authenticated`: the item
+	* is single, but the cap that served the same bytes (`getRetrainFrameImage`)
+	* is `auth: 'admin'` and the surface is admin curation — widening the bytes
+	* beyond the method they replace would be a policy change nobody asked for.
+	*/
+	[RETRAIN_FRAME_PREFIX_REF]: "admin",
 	/** Diagnostic bundle: logs, config and frames. */
 	[DEBUG_EXPORT_PREFIX_REF]: "admin",
 	/** A promoted tracking tape and its ground truth (D681) — a corpus, not an item. */
@@ -70955,6 +70963,67 @@ var TrackStore = class {
 	}
 };
 //#endregion
+//#region src/pipeline-analytics/retrain/retrain-origin.ts
+/**
+* Reading the two JSON columns the review rests on — an annotation's `origin`
+* and a frame's `dismissed` set — back into typed values.
+*
+* Parsed with the cap's own schemas rather than cast: a column written by
+* something that bypassed the guard reads as "no origin" / "nothing dismissed",
+* which is the safe direction (a missing snapshot makes a verdict approximate;
+* it never invents one).
+*/
+function parseJsonIfText(value) {
+	if (typeof value !== "string") return value;
+	try {
+		return JSON.parse(value);
+	} catch {
+		return null;
+	}
+}
+/** The stored origin snapshot, or `null` (legacy row / unreadable value). */
+function narrowOrigin(value) {
+	const parsed = require_clip_model_registry.RetrainOriginSchema.safeParse(parseJsonIfText(value));
+	return parsed.success ? parsed.data : null;
+}
+/** The stored dismissed set, or an empty list. */
+function narrowDismissed(value) {
+	const parsed = require_clip_model_registry.RetrainDismissedSchema.array().safeParse(parseJsonIfText(value));
+	return parsed.success ? parsed.data : [];
+}
+/**
+* The stable name of a pipeline box inside its frame. One live track draws one
+* box on a frame, and the track id survives a re-derivation, which is what lets
+* a dismissal made today still match tomorrow's list.
+*/
+function pipelineOriginRef(trackId) {
+	return `pipeline:${trackId}`;
+}
+/** A re-derived pipeline box as the snapshot an annotation or dismissal keeps. */
+function pipelineBoxOrigin(box) {
+	return {
+		source: "pipeline",
+		ref: pipelineOriginRef(box.trackId),
+		bbox: box.bbox,
+		macroClass: box.macroClass,
+		...box.label !== void 0 ? { label: box.label } : {},
+		...box.score !== void 0 ? { score: box.score } : {},
+		...box.modelId !== void 0 ? { modelId: box.modelId } : {}
+	};
+}
+/** The n-th proposal of a detector (`assist`) or vision-LLM (`llm`) run. */
+function proposalOrigin(source, index, facts) {
+	return {
+		source,
+		ref: `${source}:${String(index)}`,
+		bbox: facts.bbox,
+		macroClass: facts.macroClass,
+		...facts.label !== void 0 ? { label: facts.label } : {},
+		...facts.score !== void 0 ? { score: facts.score } : {},
+		...facts.modelId !== void 0 ? { modelId: facts.modelId } : {}
+	};
+}
+//#endregion
 //#region src/pipeline-analytics/retrain/retrain-frame-store.ts
 /**
 * RetrainFrameStore — the COPIES the retrain dataset owns.
@@ -71124,6 +71193,22 @@ var RETRAIN_FRAME_COLUMNS = [
 	{
 		name: "epochMs",
 		type: "INTEGER"
+	}),
+	(
+	/** Bumped by every annotation save; the compare-and-set a save is guarded
+	*  by. The column default makes a pre-revision row read `0`. */
+	{
+		name: "revision",
+		type: "INTEGER",
+		notNull: true,
+		defaultValue: 0
+	}),
+	(
+	/** The proposals the operator deleted (`RetrainDismissed[]`), so a deleted
+	*  pipeline box is not offered again. NULL = none. */
+	{
+		name: "dismissed",
+		type: "JSON"
 	})
 ];
 var RETRAIN_FRAME_INDEXES = [
@@ -71237,7 +71322,9 @@ var RetrainFrameStore = class {
 			...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,
-			...finiteNumber(data["epochMs"]) !== void 0 ? { epochMs: finiteNumber(data["epochMs"]) } : {}
+			...finiteNumber(data["epochMs"]) !== void 0 ? { epochMs: finiteNumber(data["epochMs"]) } : {},
+			revision: finiteNumber(data["revision"]) ?? 0,
+			dismissed: narrowDismissed(data["dismissed"])
 		};
 	}
 	/** The copies with these ids, in the order given; unknown ids are skipped. */
@@ -80810,7 +80897,7 @@ async function ensureTrackHierarchyMedia(deps, input) {
 }
 //#endregion
 //#region src/pipeline-analytics/event-media-handler.ts
-var CACHE_CONTROL = "public, max-age=31536000, immutable";
+var CACHE_CONTROL$1 = "public, max-age=31536000, immutable";
 /** Default / clamp bounds for the `thumb` variant edge (px). Mirrors
 *  `shared/frame/square-thumb.ts`; kept here so query parsing stays pure. */
 var THUMB_DEFAULT_SIZE = 160;
@@ -80995,14 +81082,14 @@ function createEventMediaHandler(deps) {
 		if (req.headers["if-none-match"] === etag) {
 			res.writeHead(304, {
 				etag,
-				"cache-control": CACHE_CONTROL,
+				"cache-control": CACHE_CONTROL$1,
 				"server-timing": serverTiming
 			}).end();
 			return;
 		}
 		res.writeHead(200, {
 			"content-type": "image/jpeg",
-			"cache-control": CACHE_CONTROL,
+			"cache-control": CACHE_CONTROL$1,
 			etag,
 			"content-length": String(media.bytes.byteLength),
 			"server-timing": serverTiming
@@ -82932,6 +83019,13 @@ var RETRAIN_ANNOTATION_COLUMNS = [
 		name: "assistScore",
 		type: "REAL"
 	},
+	(
+	/** The proposal the box started from (`RetrainOrigin`), snapshotted at
+	*  accept time. NULL on a row saved before origins existed. */
+	{
+		name: "origin",
+		type: "JSON"
+	}),
 	{
 		name: "exportedInBatch",
 		type: "TEXT"
@@ -83015,6 +83109,7 @@ var RetrainAnnotationStore = class {
 			source: narrowSource(data["source"]),
 			assistModelId: optionalString(data["assistModelId"]),
 			assistScore: typeof score === "number" ? score : void 0,
+			origin: narrowOrigin(data["origin"]),
 			exportedInBatch: optionalString(data["exportedInBatch"]),
 			createdAt: Number(data["createdAt"] ?? 0)
 		};
@@ -83032,12 +83127,14 @@ var RetrainAnnotationStore = class {
 			source: a.source,
 			assistModelId: a.assistModelId ?? null,
 			assistScore: a.assistScore ?? null,
+			origin: a.origin ?? null,
 			exportedInBatch: a.exportedInBatch ?? null,
 			createdAt: a.createdAt
 		};
 	}
 	/**
-	* Replace EVERY annotation on one frame with the supplied set.
+	* Replace EVERY annotation on one frame with the supplied set — atomically,
+	* and only if the frame is still at the revision the caller saw.
 	*
 	* Whole-frame replacement rather than per-box upsert, deliberately: the unit
 	* of ground truth is the frame, and "the operator deleted a box" and "the
@@ -83045,38 +83142,113 @@ var RetrainAnnotationStore = class {
 	* patch API would let a frame keep a box the operator removed on a surface
 	* that only knew about the boxes it sent.
 	*
+	* The old rows' deletion, the new rows, the frame's `dismissed` set and its
+	* bumped `revision` are ONE `settingsStore.transact`, guarded by
+	* `commit.fromRevision`: a crash leaves the frame as it was, a concurrent
+	* save leaves one winner and one `conflict` — never a blend, never a frame
+	* blanked between a delete and an insert.
+	*
 	* Returns the persisted rows so the caller renders ids it can address.
 	*/
-	async replaceForFrame(mediaKey, drafts) {
-		const existing = await this.listByFrame(mediaKey);
+	async replaceForFrame(mediaKey, drafts, commit) {
 		const createdAt = this.now();
 		const rows = drafts.map((d) => ({
 			...d,
+			origin: d.origin ?? null,
 			id: this.newId(),
 			createdAt,
 			mediaKey
 		}));
-		for (const row of rows) await this.store.set.mutate({
-			collection: RETRAIN_ANNOTATIONS_COLLECTION,
-			key: row.id,
-			value: this.toRecord(row)
+		const nextRevision = commit.fromRevision + 1;
+		const result = await this.store.transact.mutate({
+			guard: {
+				collection: RETRAIN_FRAMES_COLLECTION,
+				key: mediaKey,
+				column: "revision",
+				equals: commit.fromRevision
+			},
+			ops: [
+				{
+					op: "deleteWhere",
+					collection: RETRAIN_ANNOTATIONS_COLLECTION,
+					filter: { where: { mediaKey } }
+				},
+				{
+					op: "insertMany",
+					collection: RETRAIN_ANNOTATIONS_COLLECTION,
+					records: rows.map((row) => ({
+						id: row.id,
+						data: this.toRecord(row)
+					}))
+				},
+				{
+					op: "update",
+					collection: RETRAIN_FRAMES_COLLECTION,
+					id: mediaKey,
+					data: {
+						revision: nextRevision,
+						...commit.dismissed !== void 0 ? { dismissed: [...commit.dismissed] } : {}
+					}
+				}
+			]
 		});
-		for (const old of existing) try {
-			await this.store.delete.mutate({
+		if (!result.applied) {
+			const current = result.current;
+			return {
+				kind: "conflict",
+				currentRevision: typeof current === "number" ? current : null
+			};
+		}
+		return {
+			kind: "saved",
+			rows,
+			revision: nextRevision
+		};
+	}
+	/**
+	* Set `origin` on rows that have none, in one guarded transaction with a
+	* revision bump. Rows that already carry an origin, or are not on this frame,
+	* are left untouched and not counted. No eligible row ⇒ no write at all.
+	*/
+	async setOrigins(mediaKey, origins, commit) {
+		const eligible = (await this.listByFrame(mediaKey)).filter((row) => !row.origin && origins.has(row.id));
+		if (eligible.length === 0) return {
+			kind: "updated",
+			updated: 0,
+			revision: commit.fromRevision
+		};
+		const nextRevision = commit.fromRevision + 1;
+		const result = await this.store.transact.mutate({
+			guard: {
+				collection: RETRAIN_FRAMES_COLLECTION,
+				key: mediaKey,
+				column: "revision",
+				equals: commit.fromRevision
+			},
+			ops: [...eligible.map((row) => ({
+				op: "update",
 				collection: RETRAIN_ANNOTATIONS_COLLECTION,
-				key: old.id
-			});
-		} catch (err) {
-			this.logger.warn("retrain annotation replace: stale row delete failed", {
-				tags: { deviceId: old.deviceId },
-				meta: {
-					annotationId: old.id,
-					mediaKey,
-					error: String(err)
-				}
-			});
+				id: row.id,
+				data: { origin: origins.get(row.id) ?? null }
+			})), {
+				op: "update",
+				collection: RETRAIN_FRAMES_COLLECTION,
+				id: mediaKey,
+				data: { revision: nextRevision }
+			}]
+		});
+		if (!result.applied) {
+			const current = result.current;
+			return {
+				kind: "conflict",
+				currentRevision: typeof current === "number" ? current : null
+			};
 		}
-		return rows;
+		return {
+			kind: "updated",
+			updated: eligible.length,
+			revision: nextRevision
+		};
 	}
 	async listByFrame(mediaKey) {
 		return this.queryWhere({ mediaKey }, `frame ${mediaKey}`);
@@ -84196,7 +84368,14 @@ var RetrainLlmAssistService = class {
 			profileId: profile.id,
 			model: answer.model,
 			leftHouse: leavesHouse,
-			proposals: parsed.objects.map((o) => ({
+			proposals: parsed.objects.map((o, index) => ({
+				origin: proposalOrigin("llm", index, {
+					bbox: o.bbox,
+					macroClass: o.macroClass,
+					...o.label !== void 0 ? { label: o.label } : {},
+					score: o.confidence,
+					modelId: answer.model
+				}),
 				bbox: o.bbox,
 				macroClass: o.macroClass,
 				...o.label !== void 0 ? { label: o.label } : {},
@@ -84541,6 +84720,87 @@ async function serveRetrainArchive(_req, res, writeArchive) {
 	}
 }
 //#endregion
+//#region src/pipeline-analytics/retrain/retrain-frame-handler.ts
+var RETRAIN_FRAME_PREFIX = "retrain-frame";
+/** Longest side of a `size=thumb` response. */
+var RETRAIN_THUMB_MAX_SIDE = 480;
+var CACHE_CONTROL = "private, max-age=31536000, immutable";
+/** The path `getRetrainFrameUrl`-style callers compose for a frame. */
+function retrainFramePath$1(addonId, frameId, size) {
+	return `/addon/${addonId}/${RETRAIN_FRAME_PREFIX}/${encodeURIComponent(frameId)}?size=${size}`;
+}
+/** `{ frameId, size }` from the request URL (path after the prefix), or `null`. */
+function parseRetrainFrameRequest(url) {
+	const queryAt = url.indexOf("?");
+	const rawPath = queryAt === -1 ? url : url.slice(0, queryAt);
+	const query = queryAt === -1 ? "" : url.slice(queryAt + 1);
+	const segment = rawPath.replace(/^\/+/, "");
+	if (segment === "" || segment.includes("/")) return null;
+	let frameId;
+	try {
+		frameId = decodeURIComponent(segment);
+	} catch {
+		return null;
+	}
+	if (frameId === "") return null;
+	const size = new URLSearchParams(query).get("size");
+	if (size !== null && size !== "thumb" && size !== "full") return null;
+	return {
+		frameId,
+		size: size ?? "full"
+	};
+}
+function createRetrainFrameHandler(deps) {
+	return async (req, res) => {
+		const method = req.method ?? "GET";
+		if (method !== "GET" && method !== "HEAD") {
+			res.writeHead(405, { allow: "GET, HEAD" });
+			res.end();
+			return;
+		}
+		const request = parseRetrainFrameRequest(req.url ?? "");
+		if (request === null) {
+			res.writeHead(404);
+			res.end();
+			return;
+		}
+		const etag = `"${request.frameId}:${request.size}"`;
+		if (req.headers["if-none-match"] === etag) {
+			res.writeHead(304, {
+				etag,
+				"cache-control": CACHE_CONTROL
+			});
+			res.end();
+			return;
+		}
+		try {
+			const stored = await deps.readFrame(request.frameId);
+			if (stored === null) {
+				res.writeHead(404);
+				res.end();
+				return;
+			}
+			const body = request.size === "thumb" ? await deps.resize(stored, RETRAIN_THUMB_MAX_SIDE) : stored;
+			res.writeHead(200, {
+				"content-type": "image/jpeg",
+				"content-length": String(body.byteLength),
+				"cache-control": CACHE_CONTROL,
+				etag
+			});
+			if (method === "HEAD") res.end();
+			else res.end(body);
+		} catch (err) {
+			deps.logger.warn("retrain frame read failed", { meta: {
+				frameId: request.frameId,
+				size: request.size,
+				error: String(err)
+			} });
+			res.writeHead(500, { "content-type": "text/plain" });
+			res.end("retrain frame read failed");
+		}
+	};
+}
+//#endregion
 //#region src/pipeline-analytics/retrain/retrain-crop-cut.ts
 /**
 * The `crops` layout's cutter: one subject crop from a retrain frame copy.
@@ -84575,6 +84835,15 @@ function retrainCropWindow(input) {
 		height: bottom - top
 	};
 }
+/** A frame re-encoded to a JPEG whose longest side is at most `maxSide` (grid thumbnails). */
+async function resizeRetrainJpeg(bytes, maxSide) {
+	return (0, sharp.default)(bytes).resize({
+		width: maxSide,
+		height: maxSide,
+		fit: "inside",
+		withoutEnlargement: true
+	}).jpeg({ quality: 80 }).toBuffer();
+}
 async function cutRetrainCrop(input) {
 	const window = retrainCropWindow(input);
 	if (window === null) return null;
@@ -85677,9 +85946,27 @@ async function restageRetrainTrack(deps, input) {
 }
 //#endregion
 //#region src/pipeline-analytics/retrain/retrain-service.ts
+/**
+* RetrainService — the bodies behind the eleven `pipelineAnalytics.*Retrain*`
+* cap methods.
+*
+* It exists as a service rather than as eleven more methods on a 7,500-line
+* addon class for the reason `analytics-query-facade.ts` and `track-flags.ts`
+* already exist: the interesting parts (the copy ordering, the assist plan, the
+* lifecycle preconditions) are decidable from injected contracts alone, and a
+* test that had to boot the addon to reach them would not be written.
+*
+* Everything durable lives in two collections and one blob prefix:
+* `pipeline-analytics:retrain-frames` (the copies),
+* `pipeline-analytics:retrain-annotations` (the ground truth), and
+* `retrain/<deviceId>/<trackId>/…` (the pixels). No age sweep and no owner
+* cascade walks any of them — that is the whole point of copying.
+*/
 /** Default page size for the staging worklist. Staging is bounded at 500 per
 *  camera (D81), so this is a page, not a ceiling. */
 var DEFAULT_STAGING_LIMIT = 100;
+/** Tries a last-write-wins save gets when it keeps losing the revision race. */
+var LAST_WRITE_WINS_ATTEMPTS = 3;
 /** 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
@@ -85700,7 +85987,31 @@ function toWireFrame(f) {
 		height: f.height,
 		copiedAt: f.copiedAt,
 		...f.capturedAt !== void 0 ? { capturedAt: f.capturedAt } : {},
-		complete: f.complete
+		complete: f.complete,
+		revision: f.revision ?? 0,
+		dismissed: f.dismissed ?? []
+	};
+}
+/**
+* What the operator did with the proposals on a frame (`retrain-review.ts`).
+*
+* A frame whose rows predate origins is judged against the pipeline boxes
+* re-derived now, and a proposal nobody kept is reported `removed` — both
+* flagged approximate. A frame with snapshots is judged on them alone.
+*/
+function reviewOfFrame(annotations, pipelineBoxes, dismissed) {
+	const legacy = annotations.some((a) => !a.origin);
+	const review = require_clip_model_registry.classifyRetrainReview(annotations.map((a) => ({
+		id: a.id,
+		bbox: a.bbox,
+		macroClass: a.macroClass,
+		...a.label !== void 0 ? { label: a.label } : {},
+		kind: a.kind,
+		origin: a.origin ?? null
+	})), pipelineBoxes.map(pipelineBoxOrigin), dismissed, { inferRemoved: legacy });
+	return {
+		boxes: review.boxes,
+		summary: require_clip_model_registry.summarizeReview(review)
 	};
 }
 function toWireAnnotation(a) {
@@ -85717,6 +86028,7 @@ function toWireAnnotation(a) {
 		source: a.source,
 		...a.assistModelId !== void 0 ? { assistModelId: a.assistModelId } : {},
 		...a.assistScore !== void 0 ? { assistScore: a.assistScore } : {},
+		origin: a.origin ?? null,
 		...a.exportedInBatch !== void 0 ? { exportedInBatch: a.exportedInBatch } : {},
 		createdAt: a.createdAt
 	};
@@ -85798,16 +86110,24 @@ var RetrainService = class {
 		const evidence = this.deps.pipelineEvidence;
 		const ownTracks = /* @__PURE__ */ new Map();
 		const subjectBoxes = /* @__PURE__ */ new Map();
+		const annotationsByFrame = await this.annotationsByFrame(copies);
 		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;
+			const withCollections = {
+				...collections !== null ? {
+					...wire,
+					collectionIds: collectionIds ?? []
+				} : wire,
+				...this.frameUrls(copy.frameId)
+			};
+			const reviewOf = (boxes) => reviewOfFrame(annotationsByFrame.get(copy.frameId) ?? [], boxes, copy.dismissed ?? []);
 			if (evidence === void 0) {
-				out.push(withCollections);
+				out.push({
+					...withCollections,
+					review: reviewOf([])
+				});
 				continue;
 			}
 			const trackId = copy.origin === "track" ? copy.trackId : "";
@@ -85828,11 +86148,32 @@ var RetrainService = class {
 			});
 			out.push({
 				...withCollections,
-				pipelineBoxes
+				pipelineBoxes,
+				review: reviewOf(pipelineBoxes)
 			});
 		}
 		return out;
 	}
+	/** The URLs of a frame's pixels, when a data plane is served for them. */
+	frameUrls(frameId) {
+		const frameUrl = this.deps.frameUrl;
+		if (frameUrl === void 0) return {};
+		return {
+			imageUrl: frameUrl(frameId, "full"),
+			thumbnailUrl: frameUrl(frameId, "thumb")
+		};
+	}
+	/** The saved annotations of these frames, grouped by frame. */
+	async annotationsByFrame(copies) {
+		const grouped = /* @__PURE__ */ new Map();
+		if (copies.length === 0) return grouped;
+		for (const a of await this.deps.annotations.listByFrames(copies.map((c) => c.frameId))) {
+			const list = grouped.get(a.mediaKey);
+			if (list === void 0) grouped.set(a.mediaKey, [a]);
+			else list.push(a);
+		}
+		return grouped;
+	}
 	/**
 	* 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
@@ -85919,7 +86260,10 @@ var RetrainService = class {
 				sourceKind: kindOf.get(mediaId) ?? "keyFrame",
 				...capturedAtOf.has(mediaId) ? { capturedAt: capturedAtOf.get(mediaId) } : {}
 			});
-			if (result.kind === "copied") copied.push(toWireFrame(result.frame));
+			if (result.kind === "copied") copied.push({
+				...toWireFrame(result.frame),
+				...this.frameUrls(result.frame.frameId)
+			});
 			else refused.push({
 				sourceMediaId: result.sourceMediaId,
 				reason: result.reason
@@ -85946,7 +86290,10 @@ var RetrainService = class {
 				complete: input.complete
 			}
 		});
-		return toWireFrame(updated);
+		return {
+			...toWireFrame(updated),
+			...this.frameUrls(updated.frameId)
+		};
 	}
 	/** Un-select: annotations first, then the copy. Never the other way round —
 	*  an annotation whose frame is gone is unopenable and unfixable. The frame's
@@ -86087,9 +86434,16 @@ var RetrainService = class {
 			modelId: result.modelId,
 			stepId: plan.stepId,
 			minScore: plan.minScore,
-			proposals: mapping.proposals.map((p) => {
+			proposals: mapping.proposals.map((p, index) => {
 				const draft = proposalToDraft(p, owner);
 				return {
+					origin: proposalOrigin("assist", index, {
+						bbox: draft.bbox,
+						macroClass: draft.macroClass,
+						...draft.label !== void 0 ? { label: draft.label } : {},
+						...draft.assistScore !== void 0 ? { score: draft.assistScore } : {},
+						...draft.assistModelId !== void 0 ? { modelId: draft.assistModelId } : {}
+					}),
 					bbox: draft.bbox,
 					macroClass: draft.macroClass,
 					...draft.label !== void 0 ? { label: draft.label } : {},
@@ -86136,9 +86490,12 @@ var RetrainService = class {
 			kind: a.kind,
 			source: a.source,
 			...a.assistModelId !== void 0 ? { assistModelId: a.assistModelId } : {},
-			...a.assistScore !== void 0 ? { assistScore: a.assistScore } : {}
+			...a.assistScore !== void 0 ? { assistScore: a.assistScore } : {},
+			origin: a.origin ?? null
 		}));
-		const saved = await this.deps.annotations.replaceForFrame(input.frameId, drafts);
+		const keptRefs = new Set(drafts.flatMap((d) => d.origin ? [d.origin.ref] : []));
+		const dismissed = input.dismissed !== void 0 ? input.dismissed.filter((d) => !keptRefs.has(d.ref)) : void 0;
+		const saved = await this.replaceGuarded(frame, input, drafts, dismissed);
 		const errors = saved.filter((a) => a.kind === "model_error").length;
 		this.deps.logger.info("retrain annotations saved", {
 			tags: { deviceId: input.deviceId },
@@ -86147,12 +86504,99 @@ var RetrainService = class {
 				trackId: frame.trackId,
 				frameId: input.frameId,
 				subjects: saved.length - errors,
-				modelErrors: errors
+				modelErrors: errors,
+				dismissed: dismissed?.length
 			}
 		});
 		return saved.map(toWireAnnotation);
 	}
 	/**
+	* The guarded replace. A caller that names the revision it saw gets exactly
+	* one attempt: a different current revision is a conflict, never a retry —
+	* the point is that it must look again. A caller that names none asked for
+	* last-write-wins, so a race lost between our read and the transaction is
+	* retried on the fresh revision, a bounded number of times.
+	*/
+	async replaceGuarded(frame, input, drafts, dismissed) {
+		return await this.underRevision(frame, input, async (revision) => {
+			const result = await this.deps.annotations.replaceForFrame(input.frameId, drafts, {
+				fromRevision: revision,
+				...dismissed !== void 0 ? { dismissed } : {}
+			});
+			return result.kind === "saved" ? {
+				kind: "done",
+				value: result.rows
+			} : {
+				kind: "conflict",
+				currentRevision: result.currentRevision
+			};
+		});
+	}
+	/**
+	* Run one revision-guarded write. `attempt` is handed the revision to guard
+	* on and reports `done` or `conflict` (the frame moved; `null` = it is gone).
+	*/
+	async underRevision(frame, input, attempt) {
+		let revision = frame.revision ?? 0;
+		for (let tries = 0; tries < LAST_WRITE_WINS_ATTEMPTS; tries += 1) {
+			if (input.expectedRevision !== void 0 && input.expectedRevision !== revision) this.refuseStale(input, revision, input.expectedRevision);
+			const result = await attempt(revision);
+			if (result.kind === "done") return result.value;
+			if (result.currentRevision === null) throw new RetrainAnnotationError(`retrain frame ${input.frameId} vanished`);
+			revision = result.currentRevision;
+			if (input.expectedRevision !== void 0) this.refuseStale(input, revision, input.expectedRevision);
+		}
+		throw new RetrainAnnotationError(`retrain frame ${input.frameId} kept changing under the save — try again`);
+	}
+	/**
+	* Give rows saved before origins existed the origin a caller reconstructed
+	* for them — and touch nothing else (ids, creation time and the export stamp
+	* of the row stay). Only rows that have NO origin yet are written; a row that
+	* already has one is skipped, because a snapshot taken at accept time is
+	* evidence and a reconstruction must never overwrite it.
+	*/
+	async backfillOrigins(input) {
+		const frame = await this.requireFrame(input, "backfill-origins");
+		const wanted = new Map(input.origins.map((o) => [o.annotationId, o.origin]));
+		const result = await this.underRevision(frame, input, async (revision) => {
+			const outcome = await this.deps.annotations.setOrigins(input.frameId, wanted, { fromRevision: revision });
+			return outcome.kind === "updated" ? {
+				kind: "done",
+				value: outcome
+			} : {
+				kind: "conflict",
+				currentRevision: outcome.currentRevision
+			};
+		});
+		this.deps.logger.info("retrain origins backfilled", {
+			tags: { deviceId: input.deviceId },
+			meta: {
+				frameId: input.frameId,
+				updated: result.updated,
+				skipped: input.origins.length - result.updated
+			}
+		});
+		return {
+			updated: result.updated,
+			skipped: input.origins.length - result.updated,
+			revision: result.revision
+		};
+	}
+	refuseStale(input, current, expected) {
+		this.deps.logger.warn("retrain annotations save refused — the frame moved on", {
+			tags: { deviceId: input.deviceId },
+			meta: {
+				frameId: input.frameId,
+				currentRevision: current,
+				expectedRevision: expected
+			}
+		});
+		throw new RetrainAnnotationError(require_clip_model_registry.retrainRevisionConflictMessage(input.frameId, {
+			currentRevision: current,
+			expectedRevision: expected
+		}));
+	}
+	/**
 	* Paginated corpus list for the Frames grid. Index reads only — copies,
 	* annotation counts/classes, collection membership; no JPEG.
 	*/
@@ -111351,6 +111795,8 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_clip_m
 	trainingExportDataPlane = null;
 	/** Handle for the retrain-export data-plane listener (dispose on shutdown). */
 	retrainExportDataPlane = null;
+	/** Handle for the retrain-frame data-plane listener (dispose on shutdown). */
+	retrainFrameDataPlane = null;
 	/** Handle for the debug-export data-plane listener (dispose on shutdown). */
 	debugExportDataPlane = null;
 	/** Handle for the tape-export data-plane listener (dispose on shutdown). */
@@ -113448,7 +113894,8 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_clip_m
 				}),
 				subjectBoxes: (trackId, deviceId) => mediaStore.listSubjectBoxesByOwner("track", trackId, deviceId)
 			},
-			memberships: retrainCollectionStore
+			memberships: retrainCollectionStore,
+			frameUrl: (frameId, size) => retrainFramePath$1(this.ctx.id, frameId, size)
 		});
 		this.retrain = retrain;
 		const retrainStills = new RecordedStillService(buildRecordedStillPorts({
@@ -114552,6 +114999,7 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_clip_m
 			await this.serveNcArtifactPlane();
 			await this.serveTrainingExportPlane();
 			await this.serveRetrainExportPlane();
+			await this.serveRetrainFramePlane();
 			await this.serveDebugExportPlane();
 			await this.serveTapeExportPlane();
 			this.ctx.logger.info("event-media data-plane served", { meta: {
@@ -114703,6 +115151,9 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_clip_m
 	async saveRetrainAnnotations(input) {
 		return this.requireRetrain().saveAnnotations(input);
 	}
+	async backfillRetrainOrigins(input) {
+		return this.requireRetrain().backfillOrigins(input);
+	}
 	async completeRetrainTrack(input) {
 		return this.requireRetrain().complete(input);
 	}
@@ -115183,6 +115634,31 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_clip_m
 		}
 	}
 	/**
+	* The retrain-frame data plane: one copied frame's JPEG (`?size=thumb|full`).
+	* Admin-only like the cap that used to serve it as base64 (D613).
+	*/
+	async serveRetrainFramePlane() {
+		try {
+			const handler = createRetrainFrameHandler({
+				readFrame: async (frameId) => {
+					const frames = this.retrainFrames;
+					if (frames === null) return null;
+					const frame = await frames.get(frameId);
+					return frame === null ? null : frames.readFrame(frame);
+				},
+				resize: resizeRetrainJpeg,
+				logger: this.ctx.logger
+			});
+			this.retrainFrameDataPlane = await this.ctx.dataPlane?.serve({
+				prefix: RETRAIN_FRAME_PREFIX,
+				access: planeAccess("retrain-frame"),
+				handler
+			}) ?? null;
+		} catch (err) {
+			this.ctx.logger.warn("retrain-frame data-plane failed to serve", { meta: { error: require_clip_model_registry.errMsg(err) } });
+		}
+	}
+	/**
 	* Plan the annotated export — INDEX READS ONLY, no blob touched.
 	*
 	* The zone used for the `zoneCrop` derivation is the bounding box of the
@@ -115964,6 +116440,8 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_clip_m
 		this.trainingExportDataPlane = null;
 		await this.retrainExportDataPlane?.dispose();
 		this.retrainExportDataPlane = null;
+		await this.retrainFrameDataPlane?.dispose();
+		this.retrainFrameDataPlane = null;
 		await this.debugExportDataPlane?.dispose();
 		this.debugExportDataPlane = null;
 		await this.tapeExportDataPlane?.dispose();