@camstack/addon-post-analysis 1.2.341 → 1.2.343

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-BOAYW16o.js");
+const require_clip_model_registry = require("../clip-model-registry-Cd_y9S4U.js");
 let node_fs = require("node:fs");
 node_fs = require_clip_model_registry.__toESM(node_fs, 1);
 let node_path = require("node:path");
@@ -23,6 +23,8 @@ let node_timers_promises = require("node:timers/promises");
 let node_util = require("node:util");
 let node_buffer = require("node:buffer");
 let node_zlib = require("node:zlib");
+let node_http = require("node:http");
+let node_https = require("node:https");
 //#region src/pipeline-analytics/media-occupancy.ts
 /** The bare type ref legacy NULL-stamped media rows belong to. */
 var LEGACY_MEDIA_TYPE = "eventMedia";
@@ -7028,18 +7030,44 @@ function clockCondition(now) {
 * does not.
 */
 function resolveCondition(input) {
-	if (input.forcedMode === "day" || input.forcedMode === "night") return input.forcedMode;
-	if (input.chromaSpread !== void 0 && input.chromaSpread < IR_CHROMA_THRESHOLD) return IR;
+	return resolveConditionDetailed(input).condition;
+}
+/**
+* {@link resolveCondition}, plus the layer that answered. A consumer that
+* reports a day/night split (the retrain export, D785) must be able to tell a
+* measured IR frame from an almanac or a clock guess.
+*/
+function resolveConditionDetailed(input) {
+	if (input.forcedMode === "day" || input.forcedMode === "night") return {
+		condition: input.forcedMode,
+		source: "forced"
+	};
+	if (input.chromaSpread !== void 0 && input.chromaSpread < IR_CHROMA_THRESHOLD) return {
+		condition: IR,
+		source: "ir-chroma"
+	};
 	if (input.coordinates) {
 		const times = sunTimes(input.coordinates.lat, input.coordinates.lng, input.now);
 		if (times) {
 			const t = input.now.getTime();
-			if (Math.abs(t - times.rise) <= TWILIGHT_BAND_MS) return DAWN;
-			if (Math.abs(t - times.set) <= TWILIGHT_BAND_MS) return DUSK;
-			return t >= times.rise && t < times.set ? DAY : NIGHT;
+			if (Math.abs(t - times.rise) <= TWILIGHT_BAND_MS) return {
+				condition: DAWN,
+				source: "sun"
+			};
+			if (Math.abs(t - times.set) <= TWILIGHT_BAND_MS) return {
+				condition: DUSK,
+				source: "sun"
+			};
+			return {
+				condition: t >= times.rise && t < times.set ? DAY : NIGHT,
+				source: "sun"
+			};
 		}
 	}
-	return clockCondition(input.now);
+	return {
+		condition: clockCondition(input.now),
+		source: "clock"
+	};
 }
 //#endregion
 //#region src/shared/llm-vision/parse-model-json.ts
@@ -7172,8 +7200,8 @@ async function raceTimeout(call, timeoutMs) {
 * detail the encoder can see.
 */
 async function downscaleJpeg(bytes, maxPx) {
-	const { default: sharp$19 } = await import("sharp");
-	const out = await sharp$19(Buffer.from(bytes)).resize({
+	const { default: sharp$20 } = await import("sharp");
+	const out = await sharp$20(Buffer.from(bytes)).resize({
 		width: maxPx,
 		height: maxPx,
 		fit: "inside",
@@ -19384,8 +19412,8 @@ async function deriveSyntheticMedia(jpeg, bbox, timestamp) {
 	];
 	if (bbox === void 0) return files;
 	try {
-		const { default: sharp$18 } = await import("sharp");
-		const meta = await sharp$18(Buffer.from(jpeg)).metadata();
+		const { default: sharp$19 } = await import("sharp");
+		const meta = await sharp$19(Buffer.from(jpeg)).metadata();
 		const W = meta.width ?? 0;
 		const H = meta.height ?? 0;
 		if (W === 0 || H === 0) return files;
@@ -19393,7 +19421,7 @@ async function deriveSyntheticMedia(jpeg, bbox, timestamp) {
 		const top = Math.max(0, Math.min(H - 1, Math.floor(bbox.y * H)));
 		const width = Math.max(1, Math.min(W - left, Math.ceil(bbox.w * W)));
 		const height = Math.max(1, Math.min(H - top, Math.ceil(bbox.h * H)));
-		const cropBuf = await sharp$18(Buffer.from(jpeg)).extract({
+		const cropBuf = await sharp$19(Buffer.from(jpeg)).extract({
 			left,
 			top,
 			width,
@@ -19415,7 +19443,7 @@ async function deriveSyntheticMedia(jpeg, bbox, timestamp) {
 		});
 		const stroke = Math.max(2, Math.round(Math.min(W, H) / 240));
 		const overlay = Buffer.from(`<svg width="${W}" height="${H}"><rect x="${left}" y="${top}" width="${width}" height="${height}" fill="none" stroke="#22d3ee" stroke-width="${stroke}"/></svg>`);
-		const boxedBuf = await sharp$18(Buffer.from(jpeg)).composite([{
+		const boxedBuf = await sharp$19(Buffer.from(jpeg)).composite([{
 			input: overlay,
 			top: 0,
 			left: 0
@@ -26452,8 +26480,8 @@ var NcDispatcher = class {
 		try {
 			const points = (await this.deps.getZonePolygons?.(deviceId, zoneIds) ?? []).flat();
 			if (points.length === 0) return null;
-			const { default: sharp$17 } = await import("sharp");
-			const img = sharp$17(Buffer.from(jpeg));
+			const { default: sharp$18 } = await import("sharp");
+			const img = sharp$18(Buffer.from(jpeg));
 			const meta = await img.metadata();
 			const W = meta.width ?? 0;
 			const H = meta.height ?? 0;
@@ -70560,8 +70588,11 @@ var TrackStore = class {
 * RetrainFrameStore — the COPIES the retrain dataset owns.
 *
 * Collection: `pipeline-analytics:retrain-frames`.
-* Blobs: `retrain/<deviceId>/<trackId>/<hash>.jpg`, on the default media
-* location, under a path prefix NO owner cascade and NO age sweep walks.
+* Blobs: `retrain/<deviceId>/<trackId>/<hash>.jpg` under the `artifacts`
+* class root — the dataset is that class's fourth tenant (D341), addressed
+* through the permanent row ref {@link RETRAIN_MEDIA_LOCATION}. Never the
+* footage volume: the 2026-08-17 recordings wipe took the whole dataset with
+* it while it lived on `eventMedia` (D197). See D781.
 *
 * ## Why a copy, and why at selection time
 *
@@ -70592,16 +70623,37 @@ var TrackStore = class {
 *     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."
-*   retention="none — the blobs sit under a 'retrain' prefix no owner cascade and no
-*     age sweep walks, which is exactly what makes a 'trained' track evictable
+*   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,
 *     after its annotations). Bounded only by operator selection — nothing caps the
 *     table or the disk it consumes."
 */
 var RETRAIN_FRAMES_COLLECTION = "pipeline-analytics:retrain-frames";
-/** Storage location for retrain copies — the same default media root the event
-*  media lives on, under a prefix nothing else enumerates. */
-var RETRAIN_MEDIA_LOCATION = "eventMedia";
+/**
+* The PERMANENT location ref every retrain copy is written under (D781).
+*
+* Not a declared storage class: it is the rows' `locationId`, which the
+* media-storage wiring maps onto the `artifacts` class root — exactly how the
+* enrolled gallery's `galleryMedia` ref works (D341). The copies are curation
+* work with NO retention, so they share the one durable class rather than the
+* footage class, which is quota-evicted, drained and wipeable per disk. Rows
+* are never restamped for a root move: the ref is remapped instead, and the
+* singleton repoint carries the whole `artifacts` tree, `retrain/` included.
+*/
+var RETRAIN_MEDIA_LOCATION = "retrainMedia";
+/**
+* Where copies taken before D781 live: a NULL `locationId` meant "wherever
+* `eventMedia` points", and a concrete `eventMedia:*` id was stamped by the
+* seal or a relocate pass. The boot reconcile
+* ({@link RetrainFrameStore.relocateLegacyCopies}) moves them onto
+* {@link RETRAIN_MEDIA_LOCATION}; until it has, reads resolve them here.
+*/
+var LEGACY_RETRAIN_MEDIA_LOCATION = "eventMedia";
+/** Is this row already on the durable retrain tenant? */
+function rowIsDurableRetrainCopy(data) {
+	return data?.["locationId"] === RETRAIN_MEDIA_LOCATION;
+}
 /** Path prefix of every retrain copy. Never `<deviceId>/events/…`: the orphan
 *  audit resolves ownership from INDEX rows, but a future filesystem-side tool
 *  must be able to tell the two corpora apart by path alone. */
@@ -70659,11 +70711,32 @@ var RETRAIN_FRAME_COLUMNS = [
 		notNull: true
 	},
 	(
-	/** NULL = current eventMedia default; stamped when migration moves a copy
-	* before the logical default is repointed. */
+	/** `retrainMedia` for every copy taken since D781. NULL (the eventMedia
+	* default) or a concrete `eventMedia:*` id only on a pre-D781 copy the boot
+	* reconcile has not moved yet. */
 	{
 		name: "locationId",
 		type: "TEXT"
+	}),
+	(
+	/** When the CAMERA captured the frame — the source media row's timestamp.
+	*  NULL on a copy taken before D785. */
+	{
+		name: "capturedAt",
+		type: "INTEGER"
+	}),
+	(
+	/** Mean channel spread of the copy (`chromaSpread`), measured once at copy
+	*  time; below `IR_CHROMA_THRESHOLD` the frame is IR. NULL = not measured. */
+	{
+		name: "chromaSpread",
+		type: "REAL"
+	}),
+	(
+	/** The operator's "every subject in this frame is boxed". NULL = no. */
+	{
+		name: "complete",
+		type: "BOOLEAN"
 	})
 ];
 var RETRAIN_FRAME_INDEXES = [
@@ -70704,6 +70777,10 @@ function retrainFrameId(trackId, sourceMediaId) {
 function framePath(deviceId, trackId, frameId) {
 	return `${RETRAIN_PATH_PREFIX}/${deviceId}/${trackId}/${frameId.slice(frameId.lastIndexOf(":") + 1)}.jpg`;
 }
+/** A stored number, or `undefined` for NULL / absent / junk. */
+function finiteNumber(value) {
+	return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
 var RetrainFrameStore = class {
 	store;
 	storage;
@@ -70711,7 +70788,7 @@ var RetrainFrameStore = class {
 	readSource;
 	now;
 	writeGate;
-	resolveEventMediaLocation;
+	measureChroma;
 	constructor(deps) {
 		this.store = deps.store;
 		this.storage = deps.storage;
@@ -70719,28 +70796,20 @@ var RetrainFrameStore = class {
 		this.readSource = deps.readSource;
 		this.now = deps.now;
 		this.writeGate = deps.writeGate;
-		this.resolveEventMediaLocation = deps.resolveEventMediaLocation;
+		this.measureChroma = deps.measureChroma;
 	}
-	/**
-	* The location a NEW copy is written to, and the id its row NAMES.
-	*
-	* `null` = "no concrete location was resolved", which persists as the legacy
-	* NULL row. A resolver that throws must not refuse the copy — losing an
-	* operator's selection is worse than an unstamped row the seal can fix — but
-	* it says so, because that branch re-creates the exact population a
-	* non-blocking migration is gated on.
-	*/
-	async resolveWriteLocation(deviceId) {
-		if (!this.resolveEventMediaLocation) return null;
+	/** The copy's chroma, or `undefined` when it cannot be measured. */
+	async chromaOf(bytes, deviceId) {
+		if (!this.measureChroma) return void 0;
 		try {
-			const resolved = await this.resolveEventMediaLocation(deviceId);
-			return resolved === RETRAIN_MEDIA_LOCATION ? null : resolved;
+			const value = await this.measureChroma(bytes);
+			return Number.isFinite(value) ? value : void 0;
 		} catch (err) {
-			this.logger.warn("retrain copy could not resolve its eventMedia location — the row is written UNSTAMPED and a storage repoint would re-aim it at a disk that does not hold it", {
+			this.logger.warn("retrain copy chroma could not be measured — its day/night falls back to the sun", {
 				tags: { deviceId },
 				meta: { error: String(err) }
 			});
-			return null;
+			return;
 		}
 	}
 	static async declare(store) {
@@ -70761,7 +70830,10 @@ var RetrainFrameStore = class {
 			width: Number(data["width"] ?? 0),
 			height: Number(data["height"] ?? 0),
 			copiedAt: Number(data["copiedAt"] ?? 0),
-			locationId: typeof data["locationId"] === "string" && data["locationId"].length > 0 ? data["locationId"] : null
+			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
 		};
 	}
 	/** The copy with this id, or `null`. Index read only — no blob is touched. */
@@ -70801,6 +70873,31 @@ var RetrainFrameStore = class {
 			return [];
 		}
 	}
+	/**
+	* The copies of one camera the operator marked complete. A complete frame
+	* with no box is a hard negative, so an export cannot find these through
+	* the annotation table alone.
+	*/
+	async listCompleteByDevice(deviceId, limit) {
+		try {
+			return (await this.store.query.query({
+				collection: RETRAIN_FRAMES_COLLECTION,
+				filter: {
+					where: {
+						deviceId,
+						complete: true
+					},
+					limit
+				}
+			})).filter((r) => typeof r.id === "string").map((r) => this.rowToFrame(r.id, r.data));
+		} catch (err) {
+			this.logger.warn("RetrainFrameStore.listCompleteByDevice failed", {
+				tags: { deviceId },
+				meta: { error: String(err) }
+			});
+			return [];
+		}
+	}
 	/** How many copies each of these tracks already owns — one query, so the
 	*  staging list can badge "worked / not worked" without N round trips. */
 	async countsByTrack(trackIds) {
@@ -70829,7 +70926,7 @@ var RetrainFrameStore = class {
 	async readFrame(frame) {
 		try {
 			return await this.storage.read({
-				location: frame.locationId ?? RETRAIN_MEDIA_LOCATION,
+				location: frame.locationId ?? LEGACY_RETRAIN_MEDIA_LOCATION,
 				relativePath: framePath(frame.deviceId, frame.trackId, frame.frameId)
 			});
 		} catch (err) {
@@ -70900,7 +70997,8 @@ var RetrainFrameStore = class {
 			};
 		}
 		const path = framePath(input.deviceId, input.trackId, frameId);
-		const locationId = await this.resolveWriteLocation(input.deviceId);
+		const locationId = RETRAIN_MEDIA_LOCATION;
+		const chromaSpread = await this.chromaOf(bytes, input.deviceId);
 		const frame = {
 			frameId,
 			deviceId: input.deviceId,
@@ -70911,11 +71009,14 @@ var RetrainFrameStore = class {
 			width: size.width,
 			height: size.height,
 			copiedAt: this.now(),
-			locationId
+			locationId,
+			...input.capturedAt !== void 0 ? { capturedAt: input.capturedAt } : {},
+			...chromaSpread !== void 0 ? { chromaSpread } : {},
+			complete: false
 		};
 		const persist = async () => {
 			await this.storage.write({
-				location: locationId ?? RETRAIN_MEDIA_LOCATION,
+				location: locationId,
 				relativePath: path,
 				data: bytes
 			});
@@ -70932,7 +71033,10 @@ var RetrainFrameStore = class {
 					width: frame.width,
 					height: frame.height,
 					copiedAt: frame.copiedAt,
-					locationId: frame.locationId
+					locationId: frame.locationId,
+					capturedAt: frame.capturedAt ?? null,
+					chromaSpread: frame.chromaSpread ?? null,
+					complete: false
 				}
 			});
 		};
@@ -70972,6 +71076,27 @@ var RetrainFrameStore = class {
 		};
 	}
 	/**
+	* 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
+	* frame with zero boxes may be a complete hard negative.
+	*
+	* @returns the updated frame, or `null` when no such copy exists.
+	*/
+	async setComplete(frameId, complete) {
+		const existing = await this.get(frameId);
+		if (existing === null) return null;
+		await this.store.update.mutate({
+			collection: RETRAIN_FRAMES_COLLECTION,
+			id: frameId,
+			data: { complete }
+		});
+		return {
+			...existing,
+			complete
+		};
+	}
+	/**
 	* Drop a copy and its blob — the operator un-selecting a frame.
 	*
 	* The caller must have removed the frame's annotations first; this store does
@@ -70982,7 +71107,7 @@ var RetrainFrameStore = class {
 		const remove = async () => {
 			try {
 				await this.storage.delete({
-					location: frame.locationId ?? RETRAIN_MEDIA_LOCATION,
+					location: frame.locationId ?? LEGACY_RETRAIN_MEDIA_LOCATION,
 					relativePath: framePath(frame.deviceId, frame.trackId, frame.frameId)
 				});
 			} catch {}
@@ -71004,6 +71129,95 @@ var RetrainFrameStore = class {
 		if (this.writeGate) await this.writeGate.run(remove);
 		else await remove();
 	}
+	/**
+	* Move every copy still on the footage class onto the durable retrain
+	* tenant (D781): copy → read back → restamp → delete the source.
+	*
+	* A reconcile, not a one-shot: one query of a collection bounded by
+	* operator selection, so it is cheap when converged, and it is what would
+	* notice a pre-D781 copy restored from anywhere. The order is the gallery
+	* reconcile's (D341) and for the same reason: the row is restamped only
+	* after the new blob reads back, so a crash at any point leaves a row that
+	* names a location holding its bytes.
+	*
+	* A copy whose bytes are already gone is COUNTED and LOGGED, never deleted:
+	* its annotations are the operator's work, and only the operator decides
+	* to drop them (deselecting the frame).
+	*/
+	async relocateLegacyCopies() {
+		const rows = await this.store.query.query({ collection: RETRAIN_FRAMES_COLLECTION });
+		let relocated = 0;
+		let missing = 0;
+		let failed = 0;
+		for (const row of rows) {
+			if (typeof row.id !== "string") continue;
+			const data = row.data;
+			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);
+			let bytes;
+			try {
+				bytes = await this.storage.read({
+					location: from,
+					relativePath
+				});
+			} catch (err) {
+				missing += 1;
+				this.logger.warn("retrain copy has NO bytes on the footage class — its row and annotations are kept; deselect the frame to drop it", {
+					tags: { deviceId: frame.deviceId },
+					meta: {
+						frameId: frame.frameId,
+						trackId: frame.trackId,
+						from,
+						error: String(err)
+					}
+				});
+				continue;
+			}
+			const move = async () => {
+				await this.storage.write({
+					location: RETRAIN_MEDIA_LOCATION,
+					relativePath,
+					data: bytes
+				});
+				if (!(await this.storage.read({
+					location: RETRAIN_MEDIA_LOCATION,
+					relativePath
+				})).equals(bytes)) throw new Error("read-back differs from the source");
+				await this.store.update.mutate({
+					collection: RETRAIN_FRAMES_COLLECTION,
+					id: frame.frameId,
+					data: { locationId: RETRAIN_MEDIA_LOCATION }
+				});
+				await this.storage.delete({
+					location: from,
+					relativePath
+				});
+			};
+			try {
+				if (this.writeGate) await this.writeGate.run(move);
+				else await move();
+				relocated += 1;
+			} catch (err) {
+				failed += 1;
+				this.logger.error("retrain copy could not be moved off the footage class", {
+					tags: { deviceId: frame.deviceId },
+					meta: {
+						frameId: frame.frameId,
+						trackId: frame.trackId,
+						from,
+						error: String(err)
+					}
+				});
+			}
+		}
+		return {
+			relocated,
+			missing,
+			failed
+		};
+	}
 };
 //#endregion
 //#region src/pipeline-analytics/retention/location-class-wipe.ts
@@ -82543,6 +82757,322 @@ var RetrainCollectionStore = class {
 	}
 };
 //#endregion
+//#region src/pipeline-analytics/retrain/retrain-archive-upload.ts
+/**
+* The HTTP sink behind `pipelineAnalytics.writeRetrainArchive`: ONE request
+* whose body is the archive, written chunk by chunk with backpressure honoured
+* (D447) — the archive is never assembled in memory or on disk.
+*
+* The target is admin-supplied (the training orchestrator hands over a
+* provider's presigned URL or its upload route). Its headers may carry a
+* credential, so they are sent and never logged.
+*/
+function openRetrainUploadSink(target) {
+	const url = new URL(target.url);
+	const req = (url.protocol === "https:" ? node_https.request : node_http.request)(url, {
+		method: target.method,
+		headers: {
+			"content-type": "application/x-tar",
+			...target.headers
+		}
+	});
+	let failure = null;
+	const answer = new Promise((resolve, reject) => {
+		req.on("response", resolve);
+		req.on("error", (err) => {
+			failure = err;
+			reject(err);
+		});
+	});
+	answer.catch(() => void 0);
+	return {
+		sink: { write: (chunk) => new Promise((resolve, reject) => {
+			if (failure !== null) {
+				reject(failure);
+				return;
+			}
+			if (req.write(chunk, (err) => {
+				if (err) reject(err);
+			})) resolve();
+			else req.once("drain", resolve);
+		}) },
+		finish: async () => {
+			req.end();
+			const res = await answer;
+			res.resume();
+			const status = res.statusCode ?? 0;
+			if (status < 200 || status >= 300) throw new Error(`retrain upload refused by the target: HTTP ${status}`);
+			return status;
+		},
+		abort: (reason) => {
+			req.destroy(new Error(reason));
+		}
+	};
+}
+//#endregion
+//#region src/pipeline-analytics/training-export/tar-stream.ts
+/**
+* A minimal POSIX ustar writer — enough to emit a dataset archive entry by
+* entry, without ever holding the archive in memory.
+*
+* ## Why hand-rolled rather than the `tar` package
+*
+* `tar` is in the workspace and is the right tool for what it does: archive a
+* set of paths under one `cwd`. This is a different job. A track's media lives
+* across several storage LOCATION roots (`eventMedia` and whatever else the
+* operator relocated to), under paths that encode nothing a training set wants —
+* `615/events/track/<uuid>/keyFrame.jpg` — and every entry has to be RENAMED on
+* the way in, to `tracks/615/<trackId>/keyFrame.jpg`. `tar.create` takes a list
+* of paths relative to a single cwd and gives no rename hook, so using it would
+* mean staging a whole shadow tree on disk first: a full second copy of the
+* dataset, written and then deleted, to avoid writing 100 lines.
+*
+* So: ustar, which is a 512-byte header and a 512-byte-padded body per entry,
+* fully specified, and asserted against the system `tar` binary in the spec next
+* door rather than against my reading of the format.
+*
+* ## What this deliberately does NOT do
+*
+* No gzip — the payload is JPEG, already compressed; a gzip pass would burn CPU
+* on the hub for a percent or two. No long-name (GNU/PAX) extension: ustar
+* splits a path across a 155-byte prefix and a 100-byte name, and
+* {@link tarNameTooLong} reports a path that will not fit so the caller can skip
+* it and SAY it skipped it, rather than emitting a silently truncated entry.
+*/
+var BLOCK_SIZE = 512;
+var NAME_MAX = 100;
+var PREFIX_MAX = 155;
+/**
+* Split a path into the ustar `prefix` + `name` pair, or `null` when it cannot
+* be represented. The split must land on a `/`, and each half has its own cap.
+*/
+function splitUstarName(name) {
+	if (Buffer.byteLength(name) <= NAME_MAX) return {
+		prefix: "",
+		name
+	};
+	for (let i = name.length - 1; i >= 0; i--) {
+		if (name[i] !== "/") continue;
+		const head = name.slice(0, i);
+		const tail = name.slice(i + 1);
+		if (Buffer.byteLength(tail) > NAME_MAX) break;
+		if (Buffer.byteLength(head) <= PREFIX_MAX) return {
+			prefix: head,
+			name: tail
+		};
+	}
+	return null;
+}
+/** True when a path cannot be represented as a ustar entry name. */
+function tarNameTooLong(name) {
+	return splitUstarName(name) === null;
+}
+function writeString(block, value, offset, length) {
+	block.write(value.slice(0, length - 1), offset, length - 1, "utf8");
+}
+/** ustar numeric field: zero-padded octal, NUL-terminated. */
+function writeOctal(block, value, offset, length) {
+	const text = Math.floor(value).toString(8).padStart(length - 1, "0");
+	block.write(text.slice(-(length - 1)), offset, length - 1, "ascii");
+}
+/**
+* The 512-byte header for one regular file.
+*
+* The checksum is computed with the checksum field itself read as eight spaces —
+* that is the format's rule, and getting it wrong produces an archive that looks
+* fine until something tries to read it.
+*/
+function tarHeader(entry) {
+	const split = splitUstarName(entry.name);
+	if (split === null) throw new Error(`tar: entry name too long for ustar: ${entry.name}`);
+	const block = Buffer.alloc(BLOCK_SIZE);
+	writeString(block, split.name, 0, NAME_MAX);
+	writeOctal(block, 420, 100, 8);
+	writeOctal(block, 0, 108, 8);
+	writeOctal(block, 0, 116, 8);
+	writeOctal(block, entry.body.length, 124, 12);
+	writeOctal(block, Math.floor(entry.mtimeMs / 1e3), 136, 12);
+	block.write("        ", 148, 8, "ascii");
+	block.write("0", 156, 1, "ascii");
+	block.write("ustar\0", 257, 6, "ascii");
+	block.write("00", 263, 2, "ascii");
+	writeString(block, split.prefix, 345, PREFIX_MAX);
+	let sum = 0;
+	for (const byte of block) sum += byte;
+	writeOctal(block, sum, 148, 7);
+	block.write("\0", 154, 1, "ascii");
+	block.write(" ", 155, 1, "ascii");
+	return block;
+}
+/** Zero padding that rounds a body up to the 512-byte block. */
+function tarPadding(size) {
+	const remainder = size % BLOCK_SIZE;
+	return remainder === 0 ? Buffer.alloc(0) : Buffer.alloc(BLOCK_SIZE - remainder);
+}
+/** Header + body + padding for one entry, ready to write. */
+function tarBlocks(entry) {
+	return [
+		tarHeader(entry),
+		entry.body,
+		tarPadding(entry.body.length)
+	];
+}
+/** The two zero blocks that terminate an archive. */
+function tarTrailer() {
+	return Buffer.alloc(BLOCK_SIZE * 2);
+}
+//#endregion
+//#region src/pipeline-analytics/retrain/retrain-archive-writer.ts
+/**
+* The annotated archive body, written to ANY sink.
+*
+* One body, two consumers: the data-plane download (`retrain-export-handler`,
+* sink = the HTTP response) and `pipelineAnalytics.writeRetrainArchive` (sink
+* = one streamed HTTP upload to a training provider). The disciplines are the
+* training export's: the manifest is the first entry, one JPEG is in memory at
+* a time, a pause between files keeps the hub's one thread available, and the
+* batch id is stamped only on what the sink actually received.
+*/
+var RETRAIN_MANIFEST_ENTRY = "annotations.json";
+/** Pause between files so a large export cannot monopolise the hub's thread. */
+var RETRAIN_ARCHIVE_PACING_MS = 25;
+async function writeRetrainArchiveTo(deps) {
+	const { plan, logger } = deps;
+	const pacingMs = deps.pacingMs ?? RETRAIN_ARCHIVE_PACING_MS;
+	const hash = (0, node_crypto.createHash)("sha256");
+	let bytes = 0;
+	const write = async (chunk) => {
+		hash.update(chunk);
+		bytes += chunk.length;
+		await deps.sink.write(chunk);
+	};
+	const writeEntry = async (name, body, mtimeMs) => {
+		for (const block of tarBlocks({
+			name,
+			body,
+			mtimeMs
+		})) await write(block);
+	};
+	const mtimeMs = deps.now();
+	await writeEntry(RETRAIN_MANIFEST_ENTRY, Buffer.from(JSON.stringify(plan.manifest, null, 2), "utf8"), mtimeMs);
+	const byId = new Map(plan.manifest.frames.map((f) => [f.frameId, f]));
+	const shipped = [];
+	let missing = 0;
+	let crops = 0;
+	for (const frame of plan.frames) {
+		const entry = byId.get(frame.frameId);
+		if (entry === void 0) continue;
+		if (tarNameTooLong(entry.path)) {
+			missing += 1;
+			logger.warn("retrain export skipped a frame — path too long for the archive", {
+				tags: { deviceId: frame.deviceId },
+				meta: {
+					trackId: frame.trackId,
+					frameId: frame.frameId,
+					path: entry.path
+				}
+			});
+			continue;
+		}
+		const frameBytes = await deps.readFrame(frame);
+		if (frameBytes === null) {
+			missing += 1;
+			logger.warn("retrain export skipped a frame — the COPY is unreadable", {
+				tags: { deviceId: frame.deviceId },
+				meta: {
+					trackId: frame.trackId,
+					frameId: frame.frameId
+				}
+			});
+			continue;
+		}
+		await writeEntry(entry.path, frameBytes, mtimeMs);
+		for (const annotation of entry.annotations) {
+			if (annotation.cropPath === void 0) continue;
+			const crop = deps.cutCrop ? await deps.cutCrop(frameBytes, frame, annotation) : null;
+			if (crop === null) {
+				logger.warn("retrain export skipped a crop — it could not be cut", {
+					tags: { deviceId: frame.deviceId },
+					meta: {
+						frameId: frame.frameId,
+						annotationId: annotation.id,
+						cropPath: annotation.cropPath
+					}
+				});
+				continue;
+			}
+			await writeEntry(annotation.cropPath, crop, mtimeMs);
+			crops += 1;
+		}
+		shipped.push(frame.frameId);
+		if (pacingMs > 0) await new Promise((resolve) => setTimeout(resolve, pacingMs));
+	}
+	await write(tarTrailer());
+	await deps.markExported(shipped, plan.manifest.batchId);
+	const stats = {
+		batchId: plan.manifest.batchId,
+		frames: shipped.length,
+		crops,
+		annotations: plan.manifest.annotationCount,
+		missing,
+		bytes,
+		sha256: hash.digest("hex")
+	};
+	logger.info("retrain export complete", { meta: {
+		...stats,
+		layout: plan.manifest.layout,
+		modelErrors: plan.manifest.modelErrorCount
+	} });
+	return stats;
+}
+//#endregion
+//#region src/pipeline-analytics/retrain/retrain-crop-cut.ts
+/**
+* The `crops` layout's cutter: one subject crop from a retrain frame copy.
+*
+* A classifier must be trained on the crop the runtime feeds it, so the
+* rectangle comes from THE detail-crop derivation (`deriveDetailCropRect`,
+* `types/src/pipeline/detail-crop.ts`) with the convention the manifest
+* records — never a second rectangle maths. This is the second permitted
+* caller of that derivation (`scripts/check-clip-crop-single-owner.ts`): it
+* writes training files, never a vector, so it cannot split a feature space;
+* what it must not do is cut differently, and calling the one function is how
+* it doesn't.
+*/
+/** The pixel window to extract, or `null` when nothing of it is inside the frame. */
+function retrainCropWindow(input) {
+	const { frameWidth: fw, frameHeight: fh, bbox } = input;
+	const rect = require_clip_model_registry.deriveDetailCropRect({
+		x: bbox.x * fw,
+		y: bbox.y * fh,
+		w: bbox.w * fw,
+		h: bbox.h * fh
+	}, fw, fh, input.convention);
+	const left = Math.max(0, Math.floor(rect.x));
+	const top = Math.max(0, Math.floor(rect.y));
+	const right = Math.min(fw, Math.ceil(rect.x + rect.w));
+	const bottom = Math.min(fh, Math.ceil(rect.y + rect.h));
+	if (right - left < 1 || bottom - top < 1) return null;
+	return {
+		left,
+		top,
+		width: right - left,
+		height: bottom - top
+	};
+}
+async function cutRetrainCrop(input) {
+	const window = retrainCropWindow(input);
+	if (window === null) return null;
+	let pipeline = (0, sharp.default)(input.frameBytes).extract(window);
+	if (input.maxSide > 0) pipeline = pipeline.resize({
+		width: input.maxSide,
+		height: input.maxSide,
+		fit: "inside",
+		withoutEnlargement: true
+	});
+	return pipeline.jpeg({ quality: 92 }).toBuffer();
+}
+//#endregion
 //#region src/pipeline-analytics/retrain/retrain-geometry.ts
 function clamp01(v) {
 	return v < 0 ? 0 : v > 1 ? 1 : v;
@@ -82638,15 +83168,99 @@ function deriveSubjectCropRect(bbox, padding) {
 	};
 }
 //#endregion
+//#region src/pipeline-analytics/retrain/retrain-lighting.ts
+function isNight(condition) {
+	return condition === "night" || condition === "ir";
+}
+function retrainFrameLighting(input) {
+	if (input.capturedAt === void 0) {
+		const measured = resolveConditionDetailed({
+			...input.chromaSpread !== void 0 ? { chromaSpread: input.chromaSpread } : {},
+			now: /* @__PURE__ */ new Date(0)
+		});
+		return measured.source === "ir-chroma" ? {
+			condition: measured.condition,
+			night: true,
+			source: measured.source
+		} : null;
+	}
+	const resolved = resolveConditionDetailed({
+		...input.chromaSpread !== void 0 ? { chromaSpread: input.chromaSpread } : {},
+		...input.coordinates !== null ? { coordinates: input.coordinates } : {},
+		now: new Date(input.capturedAt)
+	});
+	return {
+		...resolved,
+		night: isNight(resolved.condition)
+	};
+}
+//#endregion
 //#region src/pipeline-analytics/retrain/retrain-export.ts
+/**
+* The ANNOTATED dataset export — the retrain page's own archive.
+*
+* Sibling of `training-export/`, deliberately not the same thing. That one
+* streams a marked track's stored media verbatim and knows nothing about what
+* is in it; this one streams the frames the operator SELECTED (already copied
+* into retrain storage) plus the ground truth they drew.
+*
+* ## The one interesting decision
+*
+* `annotations.json` carries, for every subject, the canonical full-frame box
+* AND the geometry derived for each model shape. **Derived here, at export,
+* never stored** — one box in, three shapes out. Storing the derived shapes is
+* how two crops of the same subject end up in one feature space, which is the
+* failure already recorded for CLIP (D52). A consumer that wants a different
+* input size or a different padding re-derives from the canonical box; nothing
+* in the database has to change and nothing can disagree.
+*
+* Everything else follows the export next door: index reads to plan, one JPEG
+* in memory at a time, a yield between files, and NO inference — a training
+* set's pixels are the pixels the pipeline saw.
+*/
 var RETRAIN_EXPORT_PREFIX = "retrain-export";
-/** Padding a subject-crop classifier is trained with. One number, one place. */
-var CLASSIFIER_CROP_PADDING = .2;
+/**
+* Padding a subject-crop classifier is trained with: the RUNTIME detail-crop
+* padding, read from the one convention `deriveDetailCropRect` cuts with
+* (`types/src/pipeline/detail-crop.ts`), never a second literal. It was `0.2`
+* here while the runtime fed `0.15`, so a classifier trained from this export
+* learned on more context than it is ever given live.
+*/
+var CLASSIFIER_CROP_PADDING = require_clip_model_registry.DEFAULT_DETAIL_CROP_CONVENTION.paddingRatio;
+/** The convention a `crops` layout cuts with — the runtime default, recorded
+*  in the manifest so a consumer never has to assume it. */
+var RETRAIN_CROP_CONVENTION = require_clip_model_registry.DEFAULT_DETAIL_CROP_CONVENTION;
+/** 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`. */
 function retrainFramePath(frame) {
 	const leaf = frame.frameId.slice(frame.frameId.lastIndexOf(":") + 1);
 	return `frames/${frame.deviceId}/${frame.trackId}/${leaf}.jpg`;
 }
+/** Archive path of a subject crop: `crops/<macroClass>/<annotationId>.jpg`. */
+function retrainCropPath(macroClass, annotationId) {
+	return `crops/${macroClass}/${annotationId}.jpg`;
+}
+/**
+* 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) {
+	const wanted = filter.frameIds !== void 0 ? new Set(filter.frameIds) : 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 (filter.batchId !== void 0) {
+			if (!(annotationsByFrame.get(frame.frameId) ?? []).some((a) => a.exportedInBatch === filter.batchId)) return false;
+		}
+		return true;
+	});
+}
 /**
 * Derive every per-model shape for one annotation.
 *
@@ -82667,6 +83281,8 @@ function deriveAll(annotation, frame, zone) {
 }
 /** Build the manifest. Pure — index rows in, JSON out, no blob touched. */
 function buildRetrainManifest(input) {
+	const layout = input.layout ?? "frames";
+	const coordinates = input.coordinates ?? null;
 	let annotationCount = 0;
 	let modelErrorCount = 0;
 	const frames = input.frames.map((frame) => {
@@ -82674,6 +83290,7 @@ function buildRetrainManifest(input) {
 		const annotations = (input.annotationsByFrame.get(frame.frameId) ?? []).map((a) => {
 			annotationCount += 1;
 			if (a.kind === "model_error") modelErrorCount += 1;
+			const derived = deriveAll(a, frame, zone);
 			return {
 				id: a.id,
 				macroClass: a.macroClass,
@@ -82684,7 +83301,8 @@ function buildRetrainManifest(input) {
 				...a.assistModelId !== void 0 ? { assistModelId: a.assistModelId } : {},
 				...a.assistScore !== void 0 ? { assistScore: a.assistScore } : {},
 				bbox: a.bbox,
-				derived: deriveAll(a, frame, zone)
+				...layout === "crops" && derived.subjectCrop !== void 0 ? { cropPath: retrainCropPath(a.macroClass, a.id) } : {},
+				derived
 			};
 		});
 		return {
@@ -82697,11 +83315,22 @@ function buildRetrainManifest(input) {
 			sizeBytes: frame.sizeBytes,
 			sourceKind: frame.sourceKind,
 			copiedAt: frame.copiedAt,
+			...frame.capturedAt !== void 0 ? { capturedAt: frame.capturedAt } : {},
+			complete: frame.complete,
+			lighting: retrainFrameLighting({
+				...frame.capturedAt !== void 0 ? { capturedAt: frame.capturedAt } : {},
+				...frame.chromaSpread !== void 0 ? { chromaSpread: frame.chromaSpread } : {},
+				coordinates
+			}),
 			...zone !== null ? { zoneUsed: zone } : {},
 			annotations
 		};
 	});
 	return {
+		schema: RETRAIN_MANIFEST_SCHEMA,
+		layout,
+		detailCropConvention: RETRAIN_CROP_CONVENTION,
+		...layout === "crops" ? { cropMaxSide: RETRAIN_CROP_MAX_SIDE } : {},
 		generatedAt: input.generatedAt,
 		batchId: input.batchId,
 		frameCount: frames.length,
@@ -82712,123 +83341,36 @@ function buildRetrainManifest(input) {
 	};
 }
 //#endregion
-//#region src/pipeline-analytics/training-export/tar-stream.ts
-/**
-* A minimal POSIX ustar writer — enough to emit a dataset archive entry by
-* entry, without ever holding the archive in memory.
-*
-* ## Why hand-rolled rather than the `tar` package
-*
-* `tar` is in the workspace and is the right tool for what it does: archive a
-* set of paths under one `cwd`. This is a different job. A track's media lives
-* across several storage LOCATION roots (`eventMedia` and whatever else the
-* operator relocated to), under paths that encode nothing a training set wants —
-* `615/events/track/<uuid>/keyFrame.jpg` — and every entry has to be RENAMED on
-* the way in, to `tracks/615/<trackId>/keyFrame.jpg`. `tar.create` takes a list
-* of paths relative to a single cwd and gives no rename hook, so using it would
-* mean staging a whole shadow tree on disk first: a full second copy of the
-* dataset, written and then deleted, to avoid writing 100 lines.
-*
-* So: ustar, which is a 512-byte header and a 512-byte-padded body per entry,
-* fully specified, and asserted against the system `tar` binary in the spec next
-* door rather than against my reading of the format.
-*
-* ## What this deliberately does NOT do
-*
-* No gzip — the payload is JPEG, already compressed; a gzip pass would burn CPU
-* on the hub for a percent or two. No long-name (GNU/PAX) extension: ustar
-* splits a path across a 155-byte prefix and a 100-byte name, and
-* {@link tarNameTooLong} reports a path that will not fit so the caller can skip
-* it and SAY it skipped it, rather than emitting a silently truncated entry.
-*/
-var BLOCK_SIZE = 512;
-var NAME_MAX = 100;
-var PREFIX_MAX = 155;
-/**
-* Split a path into the ustar `prefix` + `name` pair, or `null` when it cannot
-* be represented. The split must land on a `/`, and each half has its own cap.
-*/
-function splitUstarName(name) {
-	if (Buffer.byteLength(name) <= NAME_MAX) return {
-		prefix: "",
-		name
+//#region src/pipeline-analytics/retrain/retrain-export-handler.ts
+/** The export request a URL carries (`getRetrainExportUrl` composes it). */
+function parseRetrainExportRequest(url) {
+	const query = url.includes("?") ? url.slice(url.indexOf("?") + 1) : "";
+	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 batchId = params.get("batchId")?.trim() ?? "";
+	return {
+		filter: {
+			...deviceIds.length > 0 ? { deviceIds: [...deviceIds] } : {},
+			...frameIds.length > 0 ? { frameIds } : {},
+			...batchId.length > 0 ? { batchId } : {},
+			...params.get("completeOnly") === "1" ? { completeOnly: true } : {}
+		},
+		layout: params.get("layout") === "crops" ? "crops" : "frames"
 	};
-	for (let i = name.length - 1; i >= 0; i--) {
-		if (name[i] !== "/") continue;
-		const head = name.slice(0, i);
-		const tail = name.slice(i + 1);
-		if (Buffer.byteLength(tail) > NAME_MAX) break;
-		if (Buffer.byteLength(head) <= PREFIX_MAX) return {
-			prefix: head,
-			name: tail
-		};
-	}
-	return null;
 }
-/** True when a path cannot be represented as a ustar entry name. */
-function tarNameTooLong(name) {
-	return splitUstarName(name) === null;
-}
-function writeString(block, value, offset, length) {
-	block.write(value.slice(0, length - 1), offset, length - 1, "utf8");
-}
-/** ustar numeric field: zero-padded octal, NUL-terminated. */
-function writeOctal(block, value, offset, length) {
-	const text = Math.floor(value).toString(8).padStart(length - 1, "0");
-	block.write(text.slice(-(length - 1)), offset, length - 1, "ascii");
+/** The query string `parseRetrainExportRequest` reads back. */
+function retrainExportQuery(request) {
+	const params = new URLSearchParams();
+	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.batchId !== void 0) params.set("batchId", filter.batchId);
+	if (filter.completeOnly === true) params.set("completeOnly", "1");
+	if (request.layout === "crops") params.set("layout", "crops");
+	const text = params.toString();
+	return text.length > 0 ? `?${text}` : "";
 }
-/**
-* The 512-byte header for one regular file.
-*
-* The checksum is computed with the checksum field itself read as eight spaces —
-* that is the format's rule, and getting it wrong produces an archive that looks
-* fine until something tries to read it.
-*/
-function tarHeader(entry) {
-	const split = splitUstarName(entry.name);
-	if (split === null) throw new Error(`tar: entry name too long for ustar: ${entry.name}`);
-	const block = Buffer.alloc(BLOCK_SIZE);
-	writeString(block, split.name, 0, NAME_MAX);
-	writeOctal(block, 420, 100, 8);
-	writeOctal(block, 0, 108, 8);
-	writeOctal(block, 0, 116, 8);
-	writeOctal(block, entry.body.length, 124, 12);
-	writeOctal(block, Math.floor(entry.mtimeMs / 1e3), 136, 12);
-	block.write("        ", 148, 8, "ascii");
-	block.write("0", 156, 1, "ascii");
-	block.write("ustar\0", 257, 6, "ascii");
-	block.write("00", 263, 2, "ascii");
-	writeString(block, split.prefix, 345, PREFIX_MAX);
-	let sum = 0;
-	for (const byte of block) sum += byte;
-	writeOctal(block, sum, 148, 7);
-	block.write("\0", 154, 1, "ascii");
-	block.write(" ", 155, 1, "ascii");
-	return block;
-}
-/** Zero padding that rounds a body up to the 512-byte block. */
-function tarPadding(size) {
-	const remainder = size % BLOCK_SIZE;
-	return remainder === 0 ? Buffer.alloc(0) : Buffer.alloc(BLOCK_SIZE - remainder);
-}
-/** Header + body + padding for one entry, ready to write. */
-function tarBlocks(entry) {
-	return [
-		tarHeader(entry),
-		entry.body,
-		tarPadding(entry.body.length)
-	];
-}
-/** The two zero blocks that terminate an archive. */
-function tarTrailer() {
-	return Buffer.alloc(BLOCK_SIZE * 2);
-}
-//#endregion
-//#region src/pipeline-analytics/retrain/retrain-export-handler.ts
-var RETRAIN_MANIFEST_ENTRY = "annotations.json";
-/** Yield between files so a large export cannot monopolise the hub's one
-*  thread — the same discipline the training export follows. */
-var PACING_MS = 25;
 function parseRetrainDeviceIds(url) {
 	const query = url.includes("?") ? url.slice(url.indexOf("?") + 1) : "";
 	const raw = new URLSearchParams(query).get("deviceIds");
@@ -82851,10 +83393,10 @@ function createRetrainExportHandler(deps) {
 			res.end();
 			return;
 		}
-		const deviceIds = parseRetrainDeviceIds(req.url ?? "");
+		const request = parseRetrainExportRequest(req.url ?? "");
 		let plan;
 		try {
-			plan = await deps.buildPlan(deviceIds);
+			plan = await deps.buildPlan(request);
 		} catch (err) {
 			deps.logger.warn("retrain export plan failed", { meta: { error: String(err) } });
 			res.writeHead(500, { "content-type": "text/plain" });
@@ -82868,7 +83410,8 @@ function createRetrainExportHandler(deps) {
 			"x-camstack-retrain-frames": String(plan.manifest.frameCount),
 			"x-camstack-retrain-annotations": String(plan.manifest.annotationCount),
 			"x-camstack-retrain-model-errors": String(plan.manifest.modelErrorCount),
-			"x-camstack-retrain-batch": plan.manifest.batchId
+			"x-camstack-retrain-batch": plan.manifest.batchId,
+			"x-camstack-retrain-layout": plan.manifest.layout
 		});
 		if (method === "HEAD") {
 			res.end();
@@ -82881,61 +83424,18 @@ function createRetrainExportHandler(deps) {
 			});
 			if (!ok) res.once("drain", resolve);
 		});
-		const mtimeMs = deps.now();
-		for (const block of tarBlocks({
-			name: RETRAIN_MANIFEST_ENTRY,
-			body: Buffer.from(JSON.stringify(plan.manifest, null, 2), "utf8"),
-			mtimeMs
-		})) await write(block);
-		const shipped = [];
-		let missing = 0;
-		for (const frame of plan.frames) {
-			const entry = plan.manifest.frames.find((f) => f.frameId === frame.frameId);
-			if (entry === void 0) continue;
-			if (tarNameTooLong(entry.path)) {
-				missing += 1;
-				deps.logger.warn("retrain export skipped a frame — path too long for the archive", {
-					tags: { deviceId: frame.deviceId },
-					meta: {
-						trackId: frame.trackId,
-						frameId: frame.frameId,
-						path: entry.path
-					}
-				});
-				continue;
-			}
-			const bytes = await deps.readFrame(frame);
-			if (bytes === null) {
-				missing += 1;
-				deps.logger.warn("retrain export skipped a frame — the COPY is unreadable", {
-					tags: { deviceId: frame.deviceId },
-					meta: {
-						trackId: frame.trackId,
-						frameId: frame.frameId
-					}
-				});
-				continue;
-			}
-			for (const block of tarBlocks({
-				name: entry.path,
-				body: bytes,
-				mtimeMs
-			})) await write(block);
-			shipped.push(frame.frameId);
-			await new Promise((resolve) => setTimeout(resolve, PACING_MS));
-		}
-		await write(tarTrailer());
+		await writeRetrainArchiveTo({
+			plan,
+			readFrame: deps.readFrame,
+			cutCrop: deps.cutCrop,
+			sink: { write },
+			markExported: deps.markExported,
+			logger: deps.logger,
+			now: deps.now
+		});
 		await new Promise((resolve) => {
 			res.end(resolve);
 		});
-		await deps.markExported(shipped, plan.manifest.batchId);
-		deps.logger.info("retrain export complete", { meta: {
-			batchId: plan.manifest.batchId,
-			frames: shipped.length,
-			missing,
-			annotations: plan.manifest.annotationCount,
-			modelErrors: plan.manifest.modelErrorCount
-		} });
 	};
 }
 //#endregion
@@ -83253,7 +83753,9 @@ function toWireFrame(f) {
 		sizeBytes: f.sizeBytes,
 		width: f.width,
 		height: f.height,
-		copiedAt: f.copiedAt
+		copiedAt: f.copiedAt,
+		...f.capturedAt !== void 0 ? { capturedAt: f.capturedAt } : {},
+		complete: f.complete
 	};
 }
 function toWireAnnotation(a) {
@@ -83356,6 +83858,7 @@ var RetrainService = class {
 	async selectFrames(input) {
 		const media = await this.deps.media.listTrackMedia(input.trackId);
 		const kindOf = new Map(media.map((m) => [m.mediaId, m.kind]));
+		const capturedAtOf = new Map(media.map((m) => [m.mediaId, m.timestamp]));
 		const copied = [];
 		const refused = [];
 		for (const mediaId of input.mediaIds) {
@@ -83363,7 +83866,8 @@ var RetrainService = class {
 				deviceId: input.deviceId,
 				trackId: input.trackId,
 				sourceMediaId: mediaId,
-				sourceKind: kindOf.get(mediaId) ?? "keyFrame"
+				sourceKind: kindOf.get(mediaId) ?? "keyFrame",
+				...capturedAtOf.has(mediaId) ? { capturedAt: capturedAtOf.get(mediaId) } : {}
 			});
 			if (result.kind === "copied") copied.push(toWireFrame(result.frame));
 			else refused.push({
@@ -83376,6 +83880,34 @@ var RetrainService = class {
 			refused
 		};
 	}
+	/**
+	* The operator's "every subject in this frame is boxed". Scoped to the
+	* 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);
+		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,
+				frameId: input.frameId,
+				complete: input.complete
+			}
+		});
+		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. */
 	async deselectFrame(input) {
@@ -84588,7 +85120,8 @@ function selectsRow(mode, toLocationId, data, isRetrain, fromLocationId) {
 	if (mode === "seal") return rowIsUnstamped(data);
 	if (mediaRowLocation(data) === toLocationId) return false;
 	if (mode === "gallery") return !isRetrain && rowIsGallery(data);
-	return isRetrain || !rowIsGallery(data);
+	if (isRetrain) return !rowIsDurableRetrainCopy(data);
+	return !rowIsGallery(data);
 }
 var MediaRelocateEngine = class {
 	deps;
@@ -97247,7 +97780,7 @@ var ANALYTICS_COLLECTIONS = [
 		collection: RETRAIN_FRAMES_COLLECTION,
 		classification: {
 			kind: "never-orphaned",
-			why: "the frame COPIES the dataset owns outright, under a `retrain` prefix no owner cascade and no age sweep walks (D81). Also declares `trackId` as provenance. Rows go only through `deleteFrame`, after their annotations, on operator deselection. NOTE: nothing caps this table or the disk it consumes — that is a deliberate decision, not an oversight, and it is the one collection here whose bound is an operator's habit."
+			why: "the frame COPIES the dataset owns outright, in the `retrain/` subtree of the durable `artifacts` class (D781), which no owner cascade and no age sweep walks (D81). Also declares `trackId` as provenance. Rows go only through `deleteFrame`, after their annotations, on operator deselection. NOTE: nothing caps this table or the disk it consumes — that is a deliberate decision, not an oversight, and it is the one collection here whose bound is an operator's habit."
 		}
 	},
 	{
@@ -108514,6 +109047,9 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_clip_m
 			resolveRoot: (locationId) => locationId === LEGACY_ADDON_DATA_GALLERY_LOCATION ? Promise.resolve(node_path.default.join(this.ctx.dataDir, "gallery")) : locationId === GALLERY_MEDIA_LOCATION ? this.ctx.api.storage.resolve.query({
 				location: ARTIFACTS_MEDIA_LOCATION,
 				relativePath: GALLERY_TENANT_SUBPATH
+			}) : locationId === RETRAIN_MEDIA_LOCATION ? this.ctx.api.storage.resolve.query({
+				location: ARTIFACTS_MEDIA_LOCATION,
+				relativePath: ""
 			}) : this.ctx.api.storage.resolve.query({
 				location: locationId,
 				relativePath: ""
@@ -108692,7 +109228,7 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_clip_m
 			logger: logger.child("RetrainFrames"),
 			now: () => Date.now(),
 			writeGate: this.mediaWriteGate,
-			resolveEventMediaLocation: (deviceId) => this.resolveEventMediaWriteLocation(api, logger, deviceId),
+			measureChroma: (bytes) => chromaSpread(bytes),
 			readSource: async (mediaKey) => {
 				const file = await mediaStore.getById(mediaKey);
 				return file === null ? null : Buffer.from(file.base64, "base64");
@@ -109929,10 +110465,59 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_clip_m
 	/** Where to stream the ANNOTATED dataset from. Bytes never cross the cap. */
 	async getRetrainExportUrl(input) {
 		if (this.retrainExportDataPlane === null) throw new Error("retrain export: data plane unavailable on this node");
-		const ids = input.deviceIds ?? [];
-		const query = ids.length > 0 ? `?deviceIds=${ids.join(",")}` : "";
+		const { layout, ...filter } = input;
+		const query = retrainExportQuery({
+			filter,
+			layout: layout ?? "frames"
+		});
 		return { url: `/addon/${this.ctx.id}/${RETRAIN_EXPORT_PREFIX}${query}` };
 	}
+	async setRetrainFrameComplete(input) {
+		return this.requireRetrain().setFrameComplete(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.
+	*/
+	async writeRetrainArchive(input) {
+		const frameStore = this.retrainFrames;
+		if (frameStore === null) throw new Error("retrain export: analytics stores unavailable");
+		const plan = await this.buildRetrainExportPlan({
+			filter: input.filter,
+			layout: input.layout
+		});
+		const upload = openRetrainUploadSink(input.target);
+		const host = new URL(input.target.url).host;
+		try {
+			const stats = await writeRetrainArchiveTo({
+				plan,
+				readFrame: (frame) => frameStore.readFrame(frame),
+				cutCrop: this.retrainCropCutter(),
+				sink: upload.sink,
+				markExported: (frameIds, batchId) => this.markRetrainExported(frameIds, batchId),
+				logger: this.ctx.logger,
+				now: () => Date.now()
+			});
+			const status = await upload.finish();
+			this.ctx.logger.info("retrain archive uploaded", { meta: {
+				host,
+				status,
+				...stats,
+				layout: input.layout
+			} });
+			return {
+				...stats,
+				status
+			};
+		} catch (err) {
+			upload.abort(require_clip_model_registry.errMsg(err));
+			this.ctx.logger.warn("retrain archive upload failed", { meta: {
+				host,
+				error: require_clip_model_registry.errMsg(err)
+			} });
+			throw err;
+		}
+	}
 	/**
 	* The store seam the `debug.*` actions and the debug bundle both read through.
 	*
@@ -110214,15 +110799,10 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_clip_m
 	async serveRetrainExportPlane() {
 		try {
 			const handler = createRetrainExportHandler({
-				buildPlan: (deviceIds) => this.buildRetrainExportPlan(deviceIds),
+				buildPlan: (request) => this.buildRetrainExportPlan(request),
 				readFrame: (frame) => this.retrainFrames?.readFrame(frame) ?? Promise.resolve(null),
-				markExported: async (frameIds, batchId) => {
-					const store = this.retrainAnnotations;
-					if (!store || frameIds.length === 0) return;
-					const ids = [];
-					for (const frameId of frameIds) for (const a of await store.listByFrame(frameId)) ids.push(a.id);
-					await store.markExported(ids, batchId);
-				},
+				cutCrop: this.retrainCropCutter(),
+				markExported: (frameIds, batchId) => this.markRetrainExported(frameIds, batchId),
 				logger: this.ctx.logger,
 				now: () => Date.now()
 			});
@@ -110244,13 +110824,14 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_clip_m
 	* reference rectangle is implicit is a box nobody can check. A camera with no
 	* zones simply has no `zoneCrop` geometry — absent, never a clamped guess.
 	*/
-	async buildRetrainExportPlan(deviceIds) {
+	async buildRetrainExportPlan(request) {
 		const frameStore = this.retrainFrames;
 		const annotationStore = this.retrainAnnotations;
 		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 frames = [];
+		const candidates = /* @__PURE__ */ new Map();
 		const annotationsByFrame = /* @__PURE__ */ new Map();
 		const zones = /* @__PURE__ */ new Map();
 		for (const deviceId of devices) {
@@ -110259,22 +110840,56 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_clip_m
 				const existing = annotationsByFrame.get(annotation.mediaKey) ?? [];
 				annotationsByFrame.set(annotation.mediaKey, [...existing, annotation]);
 			}
+			for (const frame of await frameStore.listCompleteByDevice(deviceId, RETRAIN_EXPORT_MAX)) candidates.set(frame.frameId, frame);
 		}
 		for (const frameId of annotationsByFrame.keys()) {
+			if (candidates.has(frameId)) continue;
 			const frame = await frameStore.get(frameId);
-			if (frame !== null) frames.push(frame);
+			if (frame !== null) candidates.set(frameId, frame);
 		}
+		const frames = filterRetrainExport([...candidates.values()], annotationsByFrame, request.filter);
 		return {
 			manifest: buildRetrainManifest({
 				frames,
 				annotationsByFrame,
 				zoneForDevice: (deviceId) => zones.get(deviceId) ?? null,
 				generatedAt: Date.now(),
-				batchId: (0, node_crypto.randomUUID)()
+				batchId: (0, node_crypto.randomUUID)(),
+				layout: request.layout,
+				coordinates: await this.siteCoordinates()
 			}),
 			frames
 		};
 	}
+	/** Stamp the batch on the annotations of the frames an archive carried. */
+	async markRetrainExported(frameIds, batchId) {
+		const store = this.retrainAnnotations;
+		if (!store || frameIds.length === 0) return;
+		const ids = [];
+		for (const frameId of frameIds) for (const a of await store.listByFrame(frameId)) ids.push(a.id);
+		await store.markExported(ids, batchId);
+	}
+	/** The `crops` layout's cutter, with the convention the manifest records. */
+	retrainCropCutter() {
+		return (frameBytes, frame, annotation) => cutRetrainCrop({
+			frameBytes,
+			frameWidth: frame.width,
+			frameHeight: frame.height,
+			bbox: annotation.bbox,
+			convention: RETRAIN_CROP_CONVENTION,
+			maxSide: RETRAIN_CROP_MAX_SIDE
+		}).catch((err) => {
+			this.ctx.logger.warn("retrain crop could not be cut", {
+				tags: { deviceId: frame.deviceId },
+				meta: {
+					frameId: frame.frameId,
+					annotationId: annotation.id,
+					error: require_clip_model_registry.errMsg(err)
+				}
+			});
+			return null;
+		});
+	}
 	/** Bounding box of a camera's zones, or null when it declares none. */
 	async retrainZoneForDevice(deviceId) {
 		try {
@@ -110422,6 +111037,28 @@ var PipelineAnalyticsAddon = class PipelineAnalyticsAddon extends require_clip_m
 		}, LTS_FLUSH_INTERVAL_MS);
 		this.startOrphanAuditTimer();
 		this.reconcileGalleryMediaLocation();
+		this.reconcileRetrainCopiesLocation();
+	}
+	/**
+	* Move pre-D781 retrain copies off the footage class onto the durable
+	* `retrainMedia` tenant, and say how many have no bytes left.
+	*/
+	async reconcileRetrainCopiesLocation() {
+		const retrainFrames = this.retrainFrames;
+		if (!retrainFrames) return;
+		try {
+			const result = await retrainFrames.relocateLegacyCopies();
+			if (result.relocated === 0 && result.missing === 0 && result.failed === 0) return;
+			this.ctx.logger.info("retrain copies reconciled onto the durable retrain tenant", { meta: {
+				...result,
+				location: RETRAIN_MEDIA_LOCATION
+			} });
+		} catch (err) {
+			this.ctx.logger.warn("retrain copies reconcile failed — the copies stay on eventMedia", { meta: {
+				error: require_clip_model_registry.errMsg(err),
+				location: ARTIFACTS_MEDIA_LOCATION
+			} });
+		}
 	}
 	/**
 	* Move enrolled-gallery blobs off the footage volume, and say out loud how