@camstack/addon-post-analysis 1.2.49 → 1.2.51

package/dist/{dist-BaqsyWbd.js → dist-CnSzKo7x.js}

@@ -19,7 +19,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	value: mod,
 	enumerable: true
 }) : target, mod));
-//#endregion
+require("node:crypto");
 //#region ../types/dist/event-category-41fKf-q9.mjs
 var EventCategory = /* @__PURE__ */ function(EventCategory) {
 	EventCategory["SystemBoot"] = "system.boot";
@@ -6482,7 +6482,20 @@ var BrokerStatsSchema = object({
 		sampleRate: number(),
 		channels: number(),
 		supported: boolean()
-	}).nullable().optional()
+	}).nullable().optional(),
+	/**
+	* BROKER-SIDE AUDIO MUTE (D83). `true` = this broker is deliberately
+	* distributing none of the device's audio, on live or recording.
+	*
+	* Present so a silent camera can be told apart from a broken one on the
+	* stream panel itself, without cross-referencing the switch group: a
+	* broker holding an `audio` track descriptor while `audioMuted` is true is
+	* working exactly as asked. `audioMutedDropped` counts the audio units
+	* thrown away since the current dial — it is how you confirm from stats
+	* alone that the mute is on the packet path and not merely persisted.
+	*/
+	audioMuted: boolean().optional(),
+	audioMutedDropped: number().optional()
 });
 /**
 * Exporter-facing "profile restream" entry. Returned by
@@ -7144,6 +7157,473 @@ function sleep(ms) {
 	return new Promise((resolve) => setTimeout(resolve, Math.max(0, ms)));
 }
 //#endregion
+//#region ../types/dist/fmp4-box-splitter-B53u9-Nu.mjs
+var AUDIO_ENCODER_BY_CODEC = {
+	opus: "libopus",
+	aac: "aac",
+	pcmu: "pcm_mulaw",
+	pcma: "pcm_alaw"
+};
+/**
+* Camera-microphone audio, per codec. Lives HERE rather than in
+* `encode-defaults.ts` only to avoid an import cycle (`encode-defaults` depends
+* on these types); it is re-exported from there, which is where to read it.
+*
+* Every source in this repo is a mono camera mic. The former broker preset
+* encoded Opus at `channels: 2`, spending bitrate duplicating one channel —
+* that is the value this consolidation changed.
+*/
+var AUDIO_PRESETS = {
+	aac: {
+		kind: "encode",
+		codec: "aac",
+		bitrateKbps: 128,
+		sampleRateHz: 48e3,
+		channels: 1
+	},
+	opus: {
+		kind: "encode",
+		codec: "opus",
+		bitrateKbps: 64,
+		sampleRateHz: 48e3,
+		channels: 1
+	},
+	pcmu: {
+		kind: "encode",
+		codec: "pcmu",
+		sampleRateHz: 8e3,
+		channels: 1
+	}
+};
+/** `-hide_banner -loglevel <level>` — every ffmpeg site opens with this. */
+function logBannerArgs(level) {
+	return [
+		"-hide_banner",
+		"-loglevel",
+		level
+	];
+}
+/** `true` when the resolved value means "decode in software" (⇒ no `-hwaccel`). */
+function isSoftwareDecode(decodeHwAccel) {
+	return !decodeHwAccel || decodeHwAccel === "none" || decodeHwAccel === "copy";
+}
+/**
+* Every INPUT option, in order, terminated by `-i <url>`. Nothing may be
+* appended to this list by a caller — that is the whole point of the function.
+*/
+function buildInputArgs(input, decodeHwAccel) {
+	const args = [];
+	if (!isSoftwareDecode(decodeHwAccel)) args.push("-hwaccel", String(decodeHwAccel));
+	if (input.extraArgs?.length) args.push(...input.extraArgs);
+	if (input.analyzeDurationUs !== void 0) args.push("-analyzeduration", String(input.analyzeDurationUs));
+	if (input.probeSizeBytes !== void 0) args.push("-probesize", String(input.probeSizeBytes));
+	if (input.fflags?.length) for (const flag of input.fflags) args.push("-fflags", flag);
+	if (input.rtspTransport) args.push("-rtsp_transport", input.rtspTransport);
+	args.push("-i", input.url);
+	return args;
+}
+/** The `-vf` filter args, or `[]` when a consumer `-vf` already claims the slot. */
+function buildVideoFilterArgs(scale, outputArgs) {
+	if (!scale) return [];
+	if (outputArgs.some((a) => a === "-vf")) return [];
+	if (scale.mode === "exact") return ["-vf", `scale=${scale.width}:${scale.height}`];
+	return ["-vf", `scale='min(${scale.width},iw)':'min(${scale.height},ih)':force_original_aspect_ratio=decrease:force_divisible_by=2`];
+}
+/** Rate-control args for an encode plan. */
+function buildRateControlArgs(video) {
+	const kbps = video.bitrateKbps;
+	if (kbps === void 0) return [];
+	const rc = video.rateControl ?? {
+		kind: "cap",
+		vbvSeconds: 2
+	};
+	const bufsize = Math.max(1, Math.round(kbps * rc.vbvSeconds));
+	return [
+		...rc.kind === "cbr" ? ["-b:v", `${kbps}k`] : [],
+		"-maxrate",
+		`${kbps}k`,
+		"-bufsize",
+		`${bufsize}k`
+	];
+}
+/** The whole video block (`-vf` … `-c:v` … knobs), after `-i`. */
+function buildVideoArgs(video, outputArgs) {
+	if (video.kind === "copy") return [
+		"-c:v",
+		"copy",
+		...video.bitstreamFilter ? ["-bsf:v", video.bitstreamFilter] : []
+	];
+	const args = [
+		...buildVideoFilterArgs(video.scale, outputArgs),
+		"-c:v",
+		video.encoder
+	];
+	if (video.preset !== void 0) args.push("-preset", video.preset);
+	if (video.tune !== void 0) args.push("-tune", video.tune);
+	if (video.profile !== void 0) args.push("-profile:v", video.profile);
+	if (video.level !== void 0) args.push("-level", video.level);
+	if (video.pixelFormat !== void 0) args.push("-pix_fmt", video.pixelFormat);
+	if (video.fps !== void 0) args.push("-r", String(video.fps));
+	if (video.gopFrames !== void 0) args.push("-g", String(video.gopFrames));
+	if (video.forceKeyFramesSeconds !== void 0) args.push("-force_key_frames", `expr:gte(t,n_forced*${video.forceKeyFramesSeconds})`);
+	if (video.bf !== void 0) args.push("-bf", String(video.bf));
+	args.push(...buildRateControlArgs(video));
+	if (video.bitstreamFilter !== void 0) args.push("-bsf:v", video.bitstreamFilter);
+	return args;
+}
+/** The whole audio block, after `-i`. */
+function buildAudioArgs(audio) {
+	if (audio.kind === "none") return ["-an"];
+	if (audio.kind === "copy") return ["-c:a", "copy"];
+	const args = [];
+	if (audio.filter !== void 0) args.push("-af", audio.filter);
+	args.push("-c:a", AUDIO_ENCODER_BY_CODEC[audio.codec]);
+	if (audio.application !== void 0) args.push("-application", audio.application);
+	if (audio.frameDurationMs !== void 0) args.push("-frame_duration", String(audio.frameDurationMs));
+	if (audio.globalHeader === true) args.push("-flags", "+global_header");
+	if (audio.sampleRateHz !== void 0) args.push("-ar", String(audio.sampleRateHz));
+	if (audio.bitrateKbps !== void 0) args.push("-b:a", `${audio.bitrateKbps}k`);
+	if (audio.vbvBufferKbits !== void 0) args.push("-bufsize", `${audio.vbvBufferKbits}k`);
+	if (audio.channels !== void 0) args.push("-ac", String(audio.channels));
+	return args;
+}
+/** RTP output-leg args (`-payload_type`, `-ssrc`, `-sdp_file`, `-f rtp <url>`). */
+function buildRtpOutputArgs(out) {
+	const args = [];
+	if (out.payloadType !== void 0) args.push("-payload_type", String(out.payloadType));
+	if (out.ssrc !== void 0) args.push("-ssrc", String(out.ssrc));
+	if (out.sdpFile !== void 0) args.push("-sdp_file", out.sdpFile);
+	args.push("-f", "rtp", out.url);
+	return args;
+}
+/** `true` when the sink is a raw elementary bytestream that cannot mux audio. */
+function isElementaryVideoSink(sink) {
+	return sink.kind === "stdout" && (sink.container === "h264" || sink.container === "hevc");
+}
+/**
+* The fragmented-MP4 muxer flags, in the order the recorder has proven them
+* (`recorder/addon/ffmpeg-args.ts` passes the same `movflags` string through
+* `-segment_format_options`, across every vendor in the fleet):
+*
+* - `frag_keyframe` — cut a fragment at each key frame, so every fragment
+*   opens on a sync sample. HKSV's whole requirement.
+* - `empty_moov` — write `ftyp`+`moov` up front with no samples in it, which
+*   is what makes the head a standalone INITIALISATION segment.
+* - `default_base_moof` — fragment offsets are self-relative, so a fragment is
+*   demuxable without the bytes that preceded it. D31's byte-range read path
+*   depends on exactly this property of the recorder's segments.
+*/
+var FMP4_MOVFLAGS = "+frag_keyframe+empty_moov+default_base_moof";
+/**
+* The terminal sink args for every non-`rtp-outputs` sink. Exhaustive over the
+* union so a new member cannot fall through to `['-f', container, 'pipe:1']`,
+* which is what a plain `container` read would have done for `mp4` — a valid
+* argv that writes a NON-fragmented, unseekable-to-a-pipe MP4 and produces one
+* unusable byte stream.
+*/
+function buildStdoutOrRtspSinkArgs(sink) {
+	if (sink.kind === "rtsp-listen") return [
+		"-f",
+		"rtsp",
+		"-rtsp_transport",
+		"tcp",
+		"-rtsp_flags",
+		"listen",
+		sink.url
+	];
+	if (sink.kind === "rtp-outputs") return [];
+	return sink.container === "mp4" ? buildFmp4SinkArgs(sink) : [
+		"-f",
+		sink.container,
+		"pipe:1"
+	];
+}
+/**
+* How far BELOW the negotiated fragment length `-min_frag_duration` is set.
+*
+* `-min_frag_duration` refuses to cut before that much media has accumulated,
+* and then waits for the next key frame. Set to exactly `fragmentMs`, the
+* commonest camera configuration in existence — a key-frame grid EQUAL to the
+* requested fragment length — lands the deadline on the same instant as the key
+* frame, loses the race, and skips to the following one: **every fragment comes
+* out at twice the requested length.**
+*
+* Measured on the live fleet 2026-08-07, camera 615, `-c:v copy` (D84):
+*
+* | slot | GOP | `-min_frag_duration` | median gap |
+* | --- | --- | --- | --- |
+* | 1280×720 | 40 f @ 10 fps = 4.0 s | 4000 ms | **7944 ms** |
+* | 1280×720 | 40 f @ 10 fps = 4.0 s | 3600 ms | 3973 ms |
+* | 3840×2160 | 100 f @ 25 fps = 4.0 s | 4000 ms | 8042 ms |
+* | 3840×2160 | 100 f @ 25 fps = 4.0 s | 3600 ms | 3998 ms |
+*
+* A doubled fragment is not a cosmetic overshoot: HKSV requires every fragment
+* to be no longer than the length the controller SELECTED, so the shipped-but-
+* inert phase-1 sink would have violated the contract on its first real clip.
+*
+* 10 % is chosen against the two failures either side of it. Too small and
+* ordinary jitter (measured spread 3953-4096 ms) re-loses the race; too large
+* and a source with a key frame slightly EARLY than the grid gets cut there,
+* yielding a short fragment for no reason.
+*/
+var FMP4_MIN_FRAG_MARGIN = .9;
+/** `-movflags … -min_frag_duration <us> -f mp4 pipe:1`. */
+function buildFmp4SinkArgs(sink) {
+	return [
+		"-movflags",
+		FMP4_MOVFLAGS,
+		"-min_frag_duration",
+		String(Math.max(0, Math.round(sink.fragmentMs * FMP4_MIN_FRAG_MARGIN * 1e3))),
+		"-f",
+		"mp4",
+		"pipe:1"
+	];
+}
+/**
+* A second output mapping source audio to RTP-over-UDP. `0:a:0?` makes the
+* audio optional so a source with no audio skips it instead of failing the
+* whole invocation.
+*/
+function buildAudioSidecarArgs(sidecar) {
+	return [
+		"-map",
+		"0:a:0?",
+		...buildAudioArgs(sidecar.codec === "pcma" ? {
+			kind: "encode",
+			codec: "pcma",
+			sampleRateHz: 8e3,
+			channels: 1
+		} : AUDIO_PRESETS[sidecar.codec]),
+		...buildRtpOutputArgs({
+			url: sidecar.rtpUrl,
+			sdpFile: sidecar.sdpFile
+		})
+	];
+}
+/**
+* Assemble the full ffmpeg argument list. Layout:
+*
+*   -hide_banner -loglevel <level>
+*   [-hwaccel <backend|auto>]        ─┐ INPUT options — strictly before -i.
+*   [<input.extraArgs>]               │
+*   [-fflags <flag>…]                 │
+*   [-rtsp_transport tcp]             │
+*   -i <url>                         ─┘
+*   <video block>  <threads>  <audio block>   ─┐ OUTPUT options.
+*   <consumer outputArgs verbatim>             │
+*   <sink>                                    ─┘ terminal
+*/
+function buildFfmpegArgs(inv) {
+	const head = [...logBannerArgs(inv.logLevel), ...buildInputArgs(inv.input, inv.decodeHwAccel)];
+	const threadArgs = inv.threadCount > 0 ? ["-threads", String(inv.threadCount)] : [];
+	if (inv.sink.kind === "rtp-outputs") {
+		const videoLeg = inv.sink.video ? [
+			"-an",
+			"-map",
+			"0:v:0",
+			...buildVideoArgs(inv.video, inv.outputArgs),
+			...threadArgs,
+			...inv.outputArgs,
+			...buildRtpOutputArgs(inv.sink.video)
+		] : [];
+		const audioLeg = inv.sink.audio ? [
+			"-vn",
+			"-map",
+			"0:a:0?",
+			...buildAudioArgs(inv.audio),
+			...buildRtpOutputArgs(inv.sink.audio)
+		] : [];
+		return [
+			...head,
+			...videoLeg,
+			...audioLeg
+		];
+	}
+	const audioArgs = isElementaryVideoSink(inv.sink) ? ["-an"] : buildAudioArgs(inv.audio);
+	const sinkArgs = buildStdoutOrRtspSinkArgs(inv.sink);
+	return [
+		...head,
+		...buildVideoArgs(inv.video, inv.outputArgs),
+		...threadArgs,
+		...audioArgs,
+		...inv.outputArgs,
+		...sinkArgs,
+		...inv.audioSidecar ? buildAudioSidecarArgs(inv.audioSidecar) : []
+	];
+}
+var DEFAULT_MAX_UNIT_BYTES = 16 * 1024 * 1024;
+/** Header size for a normal box, and for one carrying a 64-bit `largesize`. */
+var BOX_HEADER_BYTES = 8;
+var LARGE_BOX_HEADER_BYTES = 16;
+var Fmp4BoxSplitter = class {
+	maxUnitBytes;
+	/** Bytes of the CURRENT unit plus any partial box after it. */
+	buffer = new Uint8Array(0);
+	/** Where the current unit starts inside {@link buffer}. */
+	unitStart = 0;
+	/** Where the box scanner has reached inside {@link buffer}. */
+	cursor = 0;
+	state = "init";
+	nextSequence = 0;
+	faultReason = null;
+	interstitial = /* @__PURE__ */ new Set();
+	constructor(options = {}) {
+		this.maxUnitBytes = options.maxUnitBytes ?? DEFAULT_MAX_UNIT_BYTES;
+	}
+	/**
+	* Non-null once the stream cannot be split. The splitter emits nothing
+	* further, so a caller polls this to kill the child rather than watching a
+	* silent stall — a fragmenter that quietly stops producing looks exactly like
+	* a camera with no motion.
+	*/
+	get fault() {
+		return this.faultReason;
+	}
+	/** Bytes currently held. The memory bound, observable rather than asserted. */
+	get pendingBytes() {
+		return this.buffer.length - this.unitStart;
+	}
+	/**
+	* Top-level box types seen BETWEEN fragments and discarded — `mfra`, `free`,
+	* a stray `sidx`. Reported rather than dropped in silence: they are legal and
+	* useless to a fragment consumer, but a type nobody expected showing up here
+	* is the first symptom of a muxer that is not writing what we think it is.
+	*/
+	get discardedInterstitialTypes() {
+		return [...this.interstitial];
+	}
+	/**
+	* Feed bytes; get back whatever units completed. Returns `[]` once faulted.
+	*/
+	push(chunk) {
+		if (this.faultReason !== null || chunk.length === 0) return [];
+		this.append(chunk);
+		if (this.pendingBytes > this.maxUnitBytes) return this.fail(`a single fMP4 unit exceeded ${this.maxUnitBytes} bytes — this stream is not fragmented`);
+		return this.drainBoxes();
+	}
+	append(chunk) {
+		if (this.buffer.length === 0) {
+			this.buffer = chunk.slice();
+			return;
+		}
+		const next = new Uint8Array(this.buffer.length + chunk.length);
+		next.set(this.buffer, 0);
+		next.set(chunk, this.buffer.length);
+		this.buffer = next;
+	}
+	/** Consume every COMPLETE top-level box now in the buffer. */
+	drainBoxes() {
+		const units = [];
+		for (;;) {
+			const header = this.readHeader();
+			if (this.faultReason !== null) return units;
+			if (header === null) break;
+			if (this.cursor + header.totalBytes > this.buffer.length) break;
+			const boxStart = this.cursor;
+			const boxEnd = boxStart + header.totalBytes;
+			this.cursor = boxEnd;
+			const unit = this.consumeBox(header.type, boxStart, boxEnd);
+			if (this.faultReason !== null) return units;
+			if (unit !== null) units.push(unit);
+		}
+		this.compact();
+		return units;
+	}
+	/**
+	* Apply one box to the state machine. Returns a unit when this box CLOSED
+	* one, `null` otherwise.
+	*/
+	consumeBox(type, boxStart, boxEnd) {
+		if (this.state === "init") {
+			if (type !== "moof") return null;
+			if (boxStart === this.unitStart) {
+				this.fail("a moof arrived before any initialisation box — there is no ftyp/moov to send");
+				return null;
+			}
+			const init = this.emit("init", this.unitStart, boxStart);
+			this.unitStart = boxStart;
+			this.state = "fragment";
+			return init;
+		}
+		if (this.state === "idle") {
+			if (type !== "moof") {
+				this.interstitial.add(type);
+				this.unitStart = boxEnd;
+				return null;
+			}
+			this.unitStart = boxStart;
+			this.state = "fragment";
+			return null;
+		}
+		if (type !== "mdat") return null;
+		const fragment = this.emit("fragment", this.unitStart, boxEnd);
+		this.unitStart = boxEnd;
+		this.state = "idle";
+		return fragment;
+	}
+	/**
+	* Parse the header at {@link cursor}, or `null` when too few bytes have
+	* arrived to know. Faults on a size the splitter cannot honour.
+	*/
+	readHeader() {
+		const available = this.buffer.length - this.cursor;
+		if (available < BOX_HEADER_BYTES) return null;
+		const view = new DataView(this.buffer.buffer, this.buffer.byteOffset, this.buffer.byteLength);
+		const size = view.getUint32(this.cursor);
+		const type = String.fromCharCode(this.buffer[this.cursor + 4] ?? 0, this.buffer[this.cursor + 5] ?? 0, this.buffer[this.cursor + 6] ?? 0, this.buffer[this.cursor + 7] ?? 0);
+		if (size === 0) {
+			this.fail(`box "${type}" declares size 0 (to EOF) — an unbounded box cannot be fragmented`);
+			return null;
+		}
+		if (size === 1) {
+			if (available < LARGE_BOX_HEADER_BYTES) return null;
+			const large = view.getBigUint64(this.cursor + BOX_HEADER_BYTES);
+			if (large > BigInt(this.maxUnitBytes)) {
+				this.fail(`box "${type}" declares ${large} bytes, over the ${this.maxUnitBytes} byte bound`);
+				return null;
+			}
+			return {
+				type,
+				totalBytes: Number(large)
+			};
+		}
+		if (size < BOX_HEADER_BYTES) {
+			this.fail(`box "${type}" declares an impossible size of ${size} bytes`);
+			return null;
+		}
+		return {
+			type,
+			totalBytes: size
+		};
+	}
+	emit(kind, start, end) {
+		const sequence = this.nextSequence;
+		this.nextSequence += 1;
+		return {
+			kind,
+			data: this.buffer.slice(start, end),
+			sequence
+		};
+	}
+	/**
+	* Drop everything already emitted or discarded. Without this the buffer is
+	* the whole stream and the process dies in hours, not minutes.
+	*/
+	compact() {
+		if (this.unitStart === 0) return;
+		this.buffer = this.buffer.slice(this.unitStart);
+		this.cursor -= this.unitStart;
+		this.unitStart = 0;
+	}
+	fail(reason) {
+		this.faultReason = reason;
+		this.buffer = new Uint8Array(0);
+		this.unitStart = 0;
+		this.cursor = 0;
+		return [];
+	}
+};
+//#endregion
 //#region ../types/dist/err-msg-IQTHeDzc.mjs
 /**
 import { errMsg } from '@camstack/types'
@@ -7313,6 +7793,19 @@ object({
 * | `notifications` | `notificationRules.setDeviceMuted` | `NotificationCenter.evaluateAndEnqueue` returns before any rule is evaluated |
 * | `privacy-mask` | `privacyMask.setMask({ enabled })` → the CAMERA | the camera blanks the masked regions itself; every stream and recording carries the black boxes |
 * | `device-audio` | `privacyMask.setAudioEnabled` → the CAMERA | the camera stops encoding an audio track at all; every consumer sees silent video |
+* | `broker-audio` | `streamBroker.setDeviceAudioMute` → `DeviceOverride.audioMuted` | `StreamBroker.setAudioMuted` drops the audio plane at the source: no `type:'audio'` packet leaves `fanOutEncoded`, no RTP reaches the restreamer, and the restreamer serves the video-only SDP |
+*
+* ## `device-audio` and `broker-audio` are two functions, not two knobs
+*
+* They look adjacent and they are not the same control ([D83](../../../../docs/decisions/adr-0083.md)):
+* `device-audio` writes the CAMERA, so it is hardware privacy — the microphone
+* genuinely stops, it survives CamStack entirely, and it costs a multi-second
+* encoder restart on every flip. `broker-audio` writes THIS server, so it is
+* instant, vendor-independent and reversible without touching the camera, and
+* a camera that ignores or lacks the ISAPI/Reolink control is still silenced.
+* D62 forbids a second switch that *disagrees* with the first; these two
+* cannot disagree, because neither reads the other's store — the camera holds
+* one, the broker holds the other, and each reports its own fact.
 *
 * ## The two switches whose authority is not on this server
 *
@@ -7374,6 +7867,7 @@ var CameraSwitchIdSchema = _enum([
 	"object-detection",
 	"privacy-mask",
 	"device-audio",
+	"broker-audio",
 	"audio-analysis",
 	"recording",
 	"notifications"
@@ -7399,7 +7893,8 @@ var CameraSwitchAuthoritySchema = discriminatedUnion("kind", [
 	object({
 		kind: literal("camera-mask"),
 		capName: string()
-	})
+	}),
+	object({ kind: literal("broker-audio-mute") })
 ]);
 /**
 * Why a switch is not offered for this camera. Rendered instead of the
@@ -9621,7 +10116,25 @@ method(object({
 }), _void(), {
 	kind: "mutation",
 	auth: "admin"
-}), method(object({ brokerId: string() }), boolean()), object({
+}), method(object({ brokerId: string() }), boolean()), method(object({ deviceId: number().int() }), object({
+	muted: boolean(),
+	/**
+	* How many live non-derived brokers currently hold the mute. Purely
+	* diagnostic: `muted` is the policy and is authoritative on its own
+	* (it applies to brokers that do not exist yet), while this says
+	* whether anything is presently being silenced.
+	*/
+	appliedBrokers: number().int().nonnegative()
+})), method(object({
+	deviceId: number().int(),
+	muted: boolean()
+}), object({
+	muted: boolean(),
+	appliedBrokers: number().int().nonnegative()
+}), {
+	kind: "mutation",
+	auth: "admin"
+}), object({
 	deviceId: number().int().nonnegative(),
 	camStreamId: string(),
 	profile: CamProfileSchema
@@ -15577,6 +16090,30 @@ var TrackSourceSchema = _enum([
 	"audio"
 ]);
 /**
+* Where a track sits in the RETRAIN lifecycle (D81).
+*
+*  - `none` — never marked, or un-marked. Evictable.
+*  - `staging` — the operator wants this track as training material and has not
+*    finished with it. **This is the only state retention holds**: the track and
+*    everything it owns (object events, crops, keyframes, CLIP vector) survive
+*    the device's age window.
+*  - `trained` — the retrain page has taken what it needed. The frames it chose
+*    were COPIED into the retrain dataset at selection time, so the dataset no
+*    longer depends on the track's media and the track becomes EVICTABLE again.
+*    Terminal for the plain `markForTrain` toggle: returning it to `staging` is
+*    a deliberate action of the retrain page, not a side effect of a checkbox.
+*
+* There is no `null`. The state is stored `TEXT NOT NULL DEFAULT 'none'` because
+* the store's filter language has only positive equality and `whereIn` — no
+* negation, no IS NULL — so a NULL would be unselectable by ANY predicate and
+* would make the entire pre-column history immortal in one deploy.
+*/
+var RetrainStatusSchema = _enum([
+	"none",
+	"staging",
+	"trained"
+]);
+/**
 * Per-track OPERATOR flags — set by hand from the admin UI or the viewer, never
 * by the pipeline. Spread into `TrackSchema` and `KeyEventSchema` from one place
 * so the two surfaces cannot drift.
@@ -15586,18 +16123,31 @@ var TrackSourceSchema = _enum([
 * columns existed read as absent, and a consumer that needs a boolean should say
 * `flag === true`, not `flag !== false`.
 *
-* What the flags DO is deliberately UNDEFINED at the time of writing: they are
-* operator curation, and the behaviour they drive will be specified separately.
-* In particular a `markForTrain` track is NOT pinned against retention — see
-* `docs/decisions/adr-0059.md` for why that is a store-level change, not a flag.
+* `markForTrain` is the WIRE FACE of {@link RetrainStatusSchema}, not a column:
+* it is exactly `retrainStatus === 'staging'`, in both directions. Writing
+* `true` moves `none → staging`, writing `false` moves `staging → none`, and a
+* `trained` track reports `false` while refusing both writes. The boolean is
+* kept because three surfaces drive a toggle off it; anything that needs to tell
+* "never marked" from "already trained" must read `retrainStatus`.
+*
+* `debug` does NOT pin; it is attention, not durability.
 */
 var TrackFlagFields = {
-	/** Operator marked this track as training material. */
+	/** Operator marked this track as training material — i.e. `retrainStatus` is
+	*  `'staging'`. */
 	markForTrain: boolean().optional(),
 	/** Operator marked this track for diagnostic attention. */
 	debug: boolean().optional()
 };
 /**
+* The lifecycle field itself, on the READ surfaces only (`Track`, `KeyEvent`).
+* Deliberately NOT part of {@link TrackFlagFields}: that group also builds the
+* write patch, and the status is not something the toggle sets — it is what the
+* toggle's boolean is derived from. Absent on an in-RAM track never touched;
+* always present on a persisted row (the column default materialises `'none'`).
+*/
+var TrackRetrainFields = { retrainStatus: RetrainStatusSchema.optional() };
+/**
 * The write half: a PARTIAL patch. An omitted key is left untouched, so setting
 * one flag can never clear the other — the toggles are independent and are
 * driven from three surfaces that do not know about each other.
@@ -15611,13 +16161,92 @@ var TrackFlagsPatchSchema = object(TrackFlagFields);
 var TrackFlagsSchema = object({
 	trackId: string(),
 	markForTrain: boolean(),
-	debug: boolean()
+	debug: boolean(),
+	/** The lifecycle state the boolean was derived from. Required here (unlike on
+	*  a track row) because this shape is only ever produced by the write body,
+	*  which always knows it — and a surface that has just written needs to render
+	*  `trained` without a re-fetch. */
+	retrainStatus: RetrainStatusSchema
+});
+union([literal(1), literal(2)]);
+/**
+* WHO decided a label, and when. Carried per tier so a value can be traced to
+* the step and model that produced it — which is what makes the write rule
+* arguable after the fact ("why is 592's label `dog` and not `Canis lupus`?")
+* and what lets a migrated, UNATTRIBUTED value be told apart from a real one.
+*
+* `stepId` is the pipeline step id (`animal-classifier`, `bird-classifier`,
+* `plate-ocr`, `face-embedding`, `object-detection`), or the sentinel
+* `migration:4g` for a value the 4g migration moved from the single-slot era —
+* that value has no provenance, and the write rule lets ANY properly-attributed
+* write of the same tier replace it regardless of score.
+*/
+var LabelAttributionSchema = object({
+	stepId: string(),
+	modelId: string().optional(),
+	decidedAt: number()
+});
+/**
+* The TIERED label model (roadmap 4g), spread into `TrackSchema` and
+* `ObjectEventSchema` from ONE place so the two surfaces cannot drift — a
+* track and its events always answer the same question the same way.
+*
+* Two scalar columns, not an array: every consumer wants "the coarse one" or
+* "the fine one", and an array made both a scan. `label` is tier 1, `subLabel`
+* is tier 2, and each carries its own score + attribution.
+*
+* **Reading it.** What a human should be shown is `subLabel ?? label` — the
+* finest thing known. Before 4g the single `label` column held the finest
+* value, so a consumer that has not been updated reads the tier-1 slot and
+* shows nothing on a species-only row; that is why the migration puts every
+* pre-4g value in tier 2 (it cannot regress a display that reads the fallback)
+* and why the read surfaces were changed in the same train.
+*
+* **Writing it.** The slots are independent, which is the whole point: a
+* tier-1 write (`bird`) can never overwrite a tier-2 value (`Turdus
+* migratorius`), so fineness cannot regress by construction. Within a tier the
+* higher score wins. One rule, one implementation — see
+* `pipeline/label-tier.ts` in addon-post-analysis.
+*/
+var TieredLabelFields = {
+	/** Tier 1 — the sub-class. See {@link LabelTierSchema}. */
+	label: string().optional(),
+	/** Confidence of the tier-1 value, as reported by the deciding step. */
+	labelScore: number().optional(),
+	/** Provenance of the tier-1 value. See {@link LabelAttributionSchema}. */
+	labelMeta: LabelAttributionSchema.optional(),
+	/** Tier 2 — the instance. See {@link LabelTierSchema}. */
+	subLabel: string().optional(),
+	/** Confidence of the tier-2 value, as reported by the deciding step. */
+	subLabelScore: number().optional(),
+	/** Provenance of the tier-2 value. See {@link LabelAttributionSchema}. */
+	subLabelMeta: LabelAttributionSchema.optional()
+};
+/** Per-camera slice of a training-export estimate. */
+var TrainingExportDeviceTotalsSchema = object({
+	deviceId: number(),
+	tracks: number().int(),
+	files: number().int(),
+	bytes: number().int()
+});
+/**
+* What a training export WOULD contain. Computed from media index rows only —
+* no blob is read to produce this.
+*/
+var TrainingExportSummarySchema = object({
+	generatedAt: number(),
+	trackCount: number().int(),
+	fileCount: number().int(),
+	byteCount: number().int(),
+	/** More marked tracks exist than a single pass carries. */
+	truncated: boolean(),
+	devices: array(TrainingExportDeviceTotalsSchema).readonly()
 });
 var TrackSchema = object({
 	trackId: string(),
 	deviceId: number(),
 	className: string(),
-	label: string().optional(),
+	...TieredLabelFields,
 	producingDeviceName: string().optional(),
 	/** Track provenance. Absent ⇒ `pipeline` (legacy rows). */
 	source: TrackSourceSchema.optional(),
@@ -15656,7 +16285,8 @@ var TrackSchema = object({
 	*  Populated from the persisted envelope columns on historical reads;
 	*  absent on legacy rows, dims-less tracks and active (in-RAM) tracks. */
 	envelope: TrackEnvelopeSchema.optional(),
-	...TrackFlagFields
+	...TrackFlagFields,
+	...TrackRetrainFields
 });
 var BaseEventFields = {
 	id: string(),
@@ -15729,7 +16359,7 @@ var ObjectEventSchema = object({
 	/** Omitted in slim projection. */
 	trackId: string().optional(),
 	className: string(),
-	label: string().optional(),
+	...TieredLabelFields,
 	/** Omitted in slim projection. */
 	confidence: number().optional(),
 	/** Heavy JSON — omitted in slim projection. */
@@ -15810,6 +16440,173 @@ var MediaFileSchema = object({
 * stored blob and a `?variant=thumb` rendering without fetching either.
 */
 var MediaFileInfoSchema = MediaFileSchema.omit({ base64: true });
+/**
+* The MACRO tier of an annotation — a CLOSED set.
+*
+* This is what the exported detector predicts, so a typo here is a new class
+* with one example in it. `label` and `subLabel` are open strings by contrast:
+* the whole point of the page is teaching the model things it does not know
+* yet, and constraining that vocabulary would make it useless.
+*
+* A macro class is NEVER a label. The provider refuses a write whose `label` or
+* `subLabel` is one of these values, in any casing, because once `person`
+* exists in both tiers "every person box" stops being answerable without
+* knowing every string anyone ever typed — and the damage is retroactive.
+*/
+var RetrainMacroClassSchema = _enum([
+	"person",
+	"vehicle",
+	"animal",
+	"package",
+	"face",
+	"plate"
+]);
+/** A subject to learn, or a phantom to unlearn (taught by OMISSION). */
+var RetrainAnnotationKindSchema = _enum(["subject", "model_error"]);
+/** Did a human draw this box, or did the assist propose it? */
+var RetrainAnnotationSourceSchema = _enum(["operator", "assist"]);
+/** Normalised `[0,1]` rectangle against the FULL frame — the canonical form. */
+var RetrainBboxSchema = object({
+	x: number(),
+	y: number(),
+	w: number(),
+	h: number()
+});
+/**
+* One annotated subject.
+*
+* `bbox` is normalised against the full frame, ALWAYS. The per-model shapes
+* (letterboxed root / zone-cropped package / subject-cropped classifier) are
+* derived from it at export and never stored — storing them is how one feature
+* space ends up holding two crops of the same subject (D52).
+*/
+var RetrainAnnotationSchema = object({
+	id: string(),
+	trackId: string(),
+	deviceId: number(),
+	/** The COPY in retrain storage — never the source track's media key. */
+	mediaKey: string(),
+	bbox: RetrainBboxSchema,
+	macroClass: RetrainMacroClassSchema,
+	label: string().optional(),
+	subLabel: string().optional(),
+	kind: RetrainAnnotationKindSchema,
+	source: RetrainAnnotationSourceSchema,
+	/** Which model proposed this box — or, on a `model_error`, drew the phantom. */
+	assistModelId: string().optional(),
+	assistScore: number().optional(),
+	exportedInBatch: string().optional(),
+	createdAt: number()
+});
+/** The write form — the server owns `id`, `createdAt` and the frame binding. */
+var RetrainAnnotationDraftSchema = RetrainAnnotationSchema.omit({
+	id: true,
+	trackId: true,
+	deviceId: true,
+	mediaKey: true,
+	createdAt: true,
+	exportedInBatch: true
+});
+/** A track sitting in `staging`, with everything the worklist needs to rank it. */
+var RetrainTrackSchema = object({
+	trackId: string(),
+	deviceId: number(),
+	className: string(),
+	label: string().optional(),
+	firstSeen: number(),
+	lastSeen: number(),
+	/** How many frames the dataset already holds from this track. */
+	frameCount: number().int(),
+	/** How many subjects have been annotated on those frames. `0` with
+	*  `frameCount: 0` is exactly "staging, still to work". */
+	annotationCount: number().int()
+});
+/** A frame the picker may offer — an index row, no blob was read to produce it. */
+var RetrainFrameCandidateSchema = object({
+	mediaKey: string(),
+	kind: MediaFileKindEnum,
+	timestamp: number(),
+	sizeBytes: number().int(),
+	/** A copy of this original already exists — selecting it is free and cannot
+	*  fail, whatever became of the original. */
+	copied: boolean()
+});
+/** A frame the dataset OWNS: bytes copied at selection time. */
+var RetrainFrameSchema = object({
+	frameId: string(),
+	deviceId: number(),
+	trackId: string(),
+	/** Provenance only. It may already point at nothing — that is expected. */
+	sourceMediaKey: string(),
+	sourceKind: MediaFileKindEnum,
+	sizeBytes: number().int(),
+	width: number().int(),
+	height: number().int(),
+	copiedAt: number()
+});
+/** Why a copy-on-select could not be honoured — named, never a silent skip. */
+var RetrainCopyRefusalSchema = _enum([
+	"source-missing",
+	"unreadable-image",
+	"write-failed"
+]);
+var RetrainFrameSelectionSchema = object({
+	copied: array(RetrainFrameSchema).readonly(),
+	refused: array(object({
+		sourceMediaKey: string(),
+		reason: RetrainCopyRefusalSchema
+	})).readonly()
+});
+var RetrainFrameListSchema = object({
+	candidates: array(RetrainFrameCandidateSchema).readonly(),
+	copies: array(RetrainFrameSchema).readonly(),
+	/** What the page pre-selects — the native key frame when one survives. */
+	autoPickMediaKey: string().optional()
+});
+/** What the operator asked the assist to look for. */
+var RetrainAssistSubjectSchema = discriminatedUnion("kind", [object({
+	kind: literal("package"),
+	zone: RetrainBboxSchema.optional()
+}), object({
+	kind: literal("objects"),
+	modelId: string(),
+	minScore: number().optional()
+})]);
+/**
+* The assist's answer — a discriminated union, because "the model saw nothing"
+* and "this node cannot run that model" lead to different next moves and a
+* nullable result cannot tell them apart.
+*/
+var RetrainAssistResultSchema = discriminatedUnion("kind", [object({
+	kind: literal("proposed"),
+	modelId: string(),
+	stepId: string(),
+	minScore: number(),
+	/** Drafts, ready to edit. `source: 'assist'` until the operator touches one. */
+	proposals: array(RetrainAnnotationDraftSchema).readonly(),
+	/** Returned by the runner but removed by the threshold. */
+	belowThreshold: number().int()
+}), object({
+	kind: literal("refused"),
+	/** `no-zone` is ours; the rest are the runner's own refusal vocabulary. */
+	reason: string(),
+	detail: string().optional()
+})]);
+/** The outcome of a lifecycle move owned by the retrain page. */
+var RetrainTransitionResultSchema = object({
+	trackId: string(),
+	/** Where the track ended up, whatever happened. */
+	retrainStatus: RetrainStatusSchema,
+	/** `false` ⇒ the move was refused or was a no-op; `reason` says which. */
+	changed: boolean(),
+	reason: _enum([
+		"unknown-track",
+		"no-frames-copied",
+		"not-staging",
+		"not-trained",
+		"unchanged"
+	]).optional()
+});
 var DEFAULT_EVENT_QUERY_LIMIT = 1e3;
 var MAX_EVENT_QUERY_LIMIT = 5e3;
 var DeviceEventQueryInput = object({
@@ -15864,13 +16661,14 @@ var KeyEventSchema = object({
 	/** Track start time (firstSeen). */
 	timestamp: number(),
 	className: string(),
-	label: string().optional(),
+	...TieredLabelFields,
 	importance: number(),
 	/** Highest-confidence ObjectEvent id for the track (empty when none). */
 	bestEventId: string(),
 	/** Track lifetime in ms (lastSeen - firstSeen). */
 	windowMs: number().optional(),
-	...TrackFlagFields
+	...TrackFlagFields,
+	...TrackRetrainFields
 });
 object({
 	trackId: string(),
@@ -16232,11 +17030,29 @@ var pipelineAnalyticsCapability = {
 		*
 		* `auth: 'protected'` (the default), NOT `admin`: the viewer is an
 		* authenticated non-admin surface and two of the three call sites are
-		* there. Revisit if a flag ever gains an effect that costs storage —
-		* `deleteTracks` next door is admin for exactly that reason.
+		* there. The note that used to sit here said to revisit this the day a flag
+		* gained an effect that costs storage, and D81 is that day — `markForTrain`
+		* now pins. It STAYS protected, and the reason is that the alternative
+		* makes the feature pointless: marking a track is something you do while
+		* looking at it, on the surface you were already looking at it on, and that
+		* surface is the viewer. What the storage cost gets instead is a BOUND — a
+		* per-device pin budget enforced in the body, refusing a new pin past the
+		* limit while always allowing un-marking. `deleteTracks` next door is still
+		* admin, because destroying evidence and preserving it are not symmetric.
 		*
-		* Returns the RESOLVED state of both flags (absent → `false`) so a caller
-		* can drive its toggle without a re-fetch. Rejects an unknown track.
+		* `markForTrain` writes the retrain LIFECYCLE, not a boolean column: `true`
+		* is `none → staging`, `false` is `staging → none`. A track already
+		* `trained` refuses BOTH — its frames are copies inside the retrain dataset
+		* and re-staging it from a generic toggle is how the same material gets
+		* annotated twice under two ground truths. Returning a trained track to
+		* staging is a deliberate action of the retrain page, which is also the only
+		* thing that produces `trained` in the first place.
+		*
+		* Returns the RESOLVED state of both flags (absent → `false`) plus the
+		* `retrainStatus` they were derived from, so a caller can drive its toggle
+		* — and render a `trained` badge — without a re-fetch. Rejects an unknown
+		* track, a new staging mark on a device already holding its full budget, and
+		* any `markForTrain` write against a trained track.
 		*/
 		setTrackFlags: method(object({
 			/** Log/audit scope only — the trackId is globally unique on its own. */
@@ -16300,6 +17116,237 @@ var pipelineAnalyticsCapability = {
 			kind: "query",
 			auth: "admin"
 		}),
+		/**
+		* The CHEAP QUESTION, asked before any media moves: how big is the dataset
+		* the marked (`markForTrain`) tracks would produce?
+		*
+		* Answered from media INDEX rows only — key, kind, size, timestamp — so it
+		* costs ~2 KB of reads per track and no blob reads at all. The measured harm
+		* behind D56 was a bulk pass that read and base64'd every blob a track owned
+		* before deciding anything, taking hub-main to 82 s busy out of 120; an
+		* export is that same I/O shape, so it inherits the same discipline: know
+		* the size, then decide.
+		*
+		* `truncated` reports that more marked tracks exist than one pass carries.
+		* Empty `deviceIds` ⇒ every device that has marked tracks.
+		*/
+		getTrainingExportSummary: method(object({ deviceIds: array(number()).optional() }), TrainingExportSummarySchema, {
+			kind: "query",
+			auth: "admin"
+		}),
+		/**
+		* Where to download the dataset archive.
+		*
+		* The BYTES do not come back through this cap — they come from the returned
+		* data-plane URL, which streams a tar built entry by entry. A multi-gigabyte
+		* archive base64'd through a unary RPC envelope would be held whole in
+		* memory twice on a hub this repo has already OOM'd once (D9/D18 are the
+		* same lesson about frames). `getDownloadUrl` on `recordingExport` is the
+		* precedent, and this follows it deliberately.
+		*
+		* The archive contains a `manifest.json` FIRST, then the stored media
+		* VERBATIM under `tracks/<deviceId>/<trackId>/…`. No crop is derived and no
+		* model is run: a training set's pixels must be the pixels the pipeline saw.
+		*/
+		getTrainingExportUrl: method(object({ deviceIds: array(number()).optional() }), object({ url: string() }), {
+			kind: "query",
+			auth: "admin"
+		}),
+		/**
+		* The staging worklist for one camera, or for every camera that has one.
+		*
+		* Fetched ON DEMAND, over the staging set only — the page never scans
+		* history, because making the working set small is the entire purpose of
+		* the mark. Each row carries how many frames the dataset already holds from
+		* the track and how many subjects were annotated on them, so
+		* `frameCount: 0` reads as "still to work" without a second call per track.
+		*
+		* `auth: 'admin'`, unlike the viewer-level mark itself: marking a track is
+		* curation you do while looking at it, but building the training set the
+		* fleet's models are fine-tuned on is not.
+		*/
+		listRetrainStaging: method(object({
+			/** Empty ⇒ every camera that has staging tracks. A LIST, not a single
+			*  `deviceId`, deliberately: `deviceId` would make this device-bound and
+			*  route it at one camera's owner, and "every camera" would stop being
+			*  expressible at all. */
+			deviceIds: array(number()).optional(),
+			limit: number().int().min(1).max(500).optional()
+		}), array(RetrainTrackSchema).readonly(), {
+			kind: "query",
+			auth: "admin"
+		}),
+		/**
+		* What a track can contribute, and what it already has.
+		*
+		* `candidates` are the track's whole, unannotated frames — index rows only,
+		* so this is cheap. `copies` are the frames already inside the dataset, and
+		* a candidate whose copy exists is marked `copied: true`: selecting it again
+		* is free and CANNOT fail, whatever became of the original.
+		*
+		* A crop, a thumbnail and `fullFrameBoxed` are never candidates. The last
+		* one matters most: it has the model's own rectangle burned into the pixels,
+		* and a detector trained on it learns to find a green line.
+		*/
+		listRetrainFrames: method(object({ trackId: string() }), RetrainFrameListSchema, {
+			kind: "query",
+			auth: "admin"
+		}),
+		/**
+		* COPY-ON-SELECT — the write that makes `trained` safe to evict.
+		*
+		* Selecting a frame copies its bytes into retrain storage immediately: not
+		* a reference, not a lease. Once the copy exists the dataset no longer
+		* depends on the track's media, which is exactly what lets D81 hand a
+		* `trained` track back to retention.
+		*
+		* The order inside is load-bearing and is pinned by a test: an EXISTING
+		* copy is returned without touching the source, so an original that
+		* evaporated blocks the selection of THAT ORIGINAL and never the copy
+		* already taken. Every refusal comes back named — a dropped selection is
+		* never silent, on the wire or in the log.
+		*/
+		selectRetrainFrames: method(object({
+			deviceId: number(),
+			trackId: string(),
+			mediaKeys: array(string()).min(1)
+		}), RetrainFrameSelectionSchema, {
+			kind: "mutation",
+			auth: "admin"
+		}),
+		/** Un-select a frame: its annotations go first, then the copy and its blob.
+		*  Deliberately destructive and deliberately explicit — it is the only way
+		*  a frame leaves the dataset before export. */
+		deselectRetrainFrame: method(object({
+			deviceId: number(),
+			trackId: string(),
+			frameId: string()
+		}), object({
+			removed: boolean(),
+			removedAnnotations: number().int()
+		}), {
+			kind: "mutation",
+			auth: "admin"
+		}),
+		/**
+		* The pixels of ONE copied frame, base64.
+		*
+		* Through the cap rather than a data plane because it is genuinely one
+		* frame at a time, on demand, at human speed — the shape D9/D18 permit
+		* (what they forbid is frames crossing a boundary at frame RATE). The
+		* annotation canvas needs the image and its exact dimensions in the same
+		* answer: a canvas that places a normalised box against a size it guessed
+		* draws every box in the wrong place.
+		*/
+		getRetrainFrameImage: method(object({ frameId: string() }), object({
+			base64: string(),
+			width: number().int(),
+			height: number().int()
+		}), {
+			kind: "query",
+			auth: "admin"
+		}),
+		/**
+		* Ask the pipeline what it sees, as a PROPOSAL.
+		*
+		* Runs through `pipelineRunner.runStatelessStep` on the COPIED frame, and
+		* every box comes back as a draft with `source: 'assist'` plus the model and
+		* score that produced it. The operator confirms, edits, adds and deletes;
+		* nothing is stored until `saveRetrainAnnotations`.
+		*
+		* For packages the request is `rfdetr-package` on the ZONE CROP at 0.35 —
+		* never the whole frame, where a package detector at that threshold proposes
+		* furniture. A package request with no zone is REFUSED rather than widened,
+		* because the silent widening would look like a bad model for as long as
+		* nobody checked which rectangle it ran on.
+		*/
+		proposeRetrainAnnotations: method(object({
+			deviceId: number(),
+			trackId: string(),
+			frameId: string(),
+			subject: RetrainAssistSubjectSchema,
+			/** Which node runs it. Absent ⇒ wherever an unowned call lands. */
+			nodeId: string().optional()
+		}), RetrainAssistResultSchema, {
+			kind: "mutation",
+			auth: "admin"
+		}),
+		/** Every annotation on a track, oldest first. */
+		listRetrainAnnotations: method(object({ trackId: string() }), array(RetrainAnnotationSchema).readonly(), {
+			kind: "query",
+			auth: "admin"
+		}),
+		/**
+		* Replace EVERY annotation on one frame with the supplied set.
+		*
+		* Whole-frame replacement, not per-box upsert: the unit of ground truth is
+		* the frame, and "the operator deleted a box" must be the same durable
+		* outcome as "the operator never drew it". A per-box patch would let a frame
+		* keep a box the operator removed on a surface that only knew about the
+		* boxes it sent.
+		*
+		* Refuses a macro class typed into `label` or `subLabel` — the tiers are
+		* separate and the guard is at the WRITE, because a mixed taxonomy cannot
+		* be un-mixed by reading it.
+		*/
+		saveRetrainAnnotations: method(object({
+			deviceId: number(),
+			trackId: string(),
+			frameId: string(),
+			annotations: array(RetrainAnnotationDraftSchema)
+		}), array(RetrainAnnotationSchema).readonly(), {
+			kind: "mutation",
+			auth: "admin"
+		}),
+		/**
+		* Finish with a track: `staging → trained`. **The only writer of that
+		* state** — D81 shipped the column with it deliberately unreachable.
+		*
+		* Refuses a track the dataset holds no copies from. `trained` un-pins the
+		* track's media, so completing without a copy is a delete order for material
+		* nothing ever extracted anything from; that refusal IS the safety argument
+		* of D81, expressed as a precondition.
+		*/
+		completeRetrainTrack: method(object({
+			deviceId: number(),
+			trackId: string()
+		}), RetrainTransitionResultSchema, {
+			kind: "mutation",
+			auth: "admin"
+		}),
+		/**
+		* The deliberate return: `trained → staging`, for the rare case.
+		*
+		* The generic `setTrackFlags` toggle refuses this in both directions by
+		* design (D81) — re-staging from a checkbox is how the same material gets
+		* annotated twice under two ground truths. Doing it here means the operator
+		* is looking at the annotations that already exist while they decide, and
+		* those annotations are LEFT ALONE: "put this back" must not be a
+		* destructive act wearing a navigational name.
+		*/
+		restageRetrainTrack: method(object({
+			deviceId: number(),
+			trackId: string()
+		}), RetrainTransitionResultSchema, {
+			kind: "mutation",
+			auth: "admin"
+		}),
+		/**
+		* Where to download the ANNOTATED dataset.
+		*
+		* The sibling of `getTrainingExportUrl` and deliberately not the same
+		* archive: that one streams a marked track's stored media verbatim, this one
+		* streams the retrain COPIES plus an `annotations.json` carrying, for every
+		* subject, the canonical full-frame box AND the geometry derived for each
+		* model shape (letterboxed root / zone-cropped package / subject-cropped
+		* classifier). Derived at export, never stored — one box in, three shapes
+		* out, so two crops of the same subject can never end up in one feature
+		* space (D52).
+		*/
+		getRetrainExportUrl: method(object({ deviceIds: array(number()).optional() }), object({ url: string() }), {
+			kind: "query",
+			auth: "admin"
+		}),
 		getEventMedia: method(object({
 			eventId: string(),
 			kind: MediaFileKindEnum.optional()
@@ -16964,6 +18011,22 @@ var DetailResultSchema = object({
 	bbox: NativeCropBboxSchema.optional(),
 	embedding: string().optional(),
 	label: string().optional(),
+	/**
+	* The tier `label` occupies, copied VERBATIM from the producing step's
+	* `StepDefinition.labelTier` (roadmap 4g). Present only when `label` is.
+	*
+	* It rides the wire rather than being resolved by the consumer because the
+	* declaration lives with the step definition, which only the executing node
+	* has: post-analysis holds no step registry, and re-deriving the tier from
+	* `className` there would be exactly the inference this model exists to
+	* forbid. A `label` that arrives WITHOUT this field is refused by the write
+	* rule and logged (`label tier undeclared`) — an older runner therefore
+	* stops enriching rather than guessing, which is why addon-pipeline is
+	* deployed BEFORE addon-post-analysis.
+	*/
+	labelTier: union([literal(1), literal(2)]).optional(),
+	/** Model that produced `label` — carried into the tier's attribution. */
+	labelModelId: string().optional(),
 	alignedCropJpeg: string().optional(),
 	/** Face short side (px) measured on the NATIVE crop surface. The `bbox`
 	*  above is detection-frame px (≈6× smaller on a 4K camera) — min-face-size
@@ -23132,6 +24195,173 @@ DeviceType.Camera, method(object({
 	status: OsdStatusSchema
 });
 /**
+* `osd-manager` — the ORCHESTRATOR over the device-scope `osd` cap.
+*
+* The `osd` cap is the firmware contract: it probes a camera's overlay
+* SLOTS and writes literal text into one. It has no idea WHERE that text
+* comes from, and it must not — a driver that grew a "show the temperature
+* here" feature would grow it once per vendor.
+*
+* This cap owns the other half: a per-(camera, slot) BINDING that says
+* which value feeds the slot, how it is formatted, and under which
+* conditions it is shown at all. One addon renders every binding on every
+* camera, so a new source costs zero driver code.
+*
+* Three deliberate choices, each with a rejected alternative:
+*
+*  1. A source is `(capName, valuePath)` over the kernel's device
+*     runtime-state mirror — NOT a closed enum of source kinds. Every
+*     cap-keyed slice a device publishes is bindable the day the cap
+*     ships. The rejected alternative (one enum member per source, with
+*     a resolver branch each) is what makes "add the humidity too" a
+*     code change.
+*  2. The display gate reuses `NcConditionsSchema` verbatim — the
+*     notification centre's condition vocabulary — rather than a parallel
+*     model. An operator who has learned one condition editor has learned
+*     both.
+*  3. Because the renderer's facts are device STATE and not a detection
+*     record, only a SUBSET of that vocabulary can be answered here.
+*     `setSlotBinding` REJECTS the rest at write time (see
+*     `getConditionSupport`). It does not accept-then-fail-closed: a
+*     condition that can never be true renders a permanently blank
+*     overlay, and a blank overlay looks exactly like a broken camera.
+*/
+/** Where a slot's value comes from. */
+var OsdSourceSchema = discriminatedUnion("kind", [
+	object({
+		kind: literal("static"),
+		text: string().max(64)
+	}),
+	object({
+		kind: literal("clock"),
+		/** Token pattern: `YYYY MM DD HH mm ss`. Everything else is literal. */
+		pattern: string().min(1).max(32).default("HH:mm"),
+		/** IANA zone. Omitted = the server's zone. */
+		timezone: string().min(1).max(64).optional()
+	}),
+	object({
+		kind: literal("device-state"),
+		deviceId: number().int().optional(),
+		capName: string().min(1).max(64),
+		/** Dot path inside the slice, e.g. `detected`, `value`, `mode`. */
+		valuePath: string().min(1).max(64)
+	})
+]);
+var OsdSlotBindingSchema = object({
+	/** Off = the manager stops driving this slot. It does NOT clear it. */
+	enabled: boolean().default(true),
+	source: OsdSourceSchema,
+	/** `${value}` and `${unit}` are substituted; every occurrence. */
+	template: string().max(96).default("${value}"),
+	/** Truncate with an ellipsis past this length. Absent = no limit. */
+	maxCharacters: number().int().min(4).max(64).optional(),
+	/**
+	* Decimal places for a numeric value. `0` yields an integer — the
+	* documented workaround for firmwares that reject `.` in overlay text.
+	*/
+	maxDecimals: number().int().min(0).max(4).default(1),
+	/** Appended via `${unit}`. The state mirror does not carry units. */
+	unitLabel: string().max(8).optional(),
+	/** Raw value → display text, e.g. `{"true":"MOTION","false":""}`. */
+	valueMap: record(string(), string()).optional(),
+	/** Time windows in which the slot is shown. Absent = always. */
+	schedule: NcScheduleSchema.optional(),
+	/**
+	* Display gate, in the notification centre's condition vocabulary.
+	* Only the keys reported by `getConditionSupport` are accepted.
+	*/
+	conditions: NcConditionsSchema.optional(),
+	/** Rendered when the gate is closed or the value unreadable. Empty = hide. */
+	fallbackText: string().max(64).default("")
+});
+/** One camera slot, as the operator sees it: firmware truth + our binding. */
+var OsdSlotViewSchema = object({
+	slotId: string(),
+	kind: OsdOverlayKindEnum,
+	/** Firmware refuses text edits (a timestamp, the channel name). */
+	readOnly: boolean(),
+	cameraEnabled: boolean(),
+	cameraText: string().optional(),
+	binding: OsdSlotBindingSchema.nullable()
+});
+/**
+* What happened to one slot on one render pass. `unchanged` exists so the
+* operator can tell "we are driving this and the value is steady" from
+* "we never got there" — and so the loop can prove it is not rewriting
+* identical text to the camera every tick.
+*/
+var OsdRenderOutcomeEnum = _enum([
+	"written",
+	"unchanged",
+	"gated",
+	"unreadable",
+	"disabled",
+	"unbound",
+	"failed"
+]);
+var OsdRenderResultSchema = object({
+	slotId: string(),
+	outcome: OsdRenderOutcomeEnum,
+	/** The text the slot should carry. Empty = the slot is switched off. */
+	text: string(),
+	/** Why, whenever the outcome is not a plain write. Never silent. */
+	reason: string().optional()
+});
+var OsdSourceValueTypeEnum = _enum([
+	"number",
+	"boolean",
+	"string",
+	"enum"
+]);
+/**
+* One bindable value, derived from a cap's `runtimeState` schema — never
+* hand-listed. The editor renders from this, so a cap that ships a new
+* state field becomes bindable with no UI change.
+*/
+var OsdSourceOptionSchema = object({
+	deviceId: number().int(),
+	deviceName: string(),
+	capName: string(),
+	valuePath: string(),
+	label: string(),
+	valueType: OsdSourceValueTypeEnum,
+	/** Present for `enum`; the editor offers these as `valueMap` keys. */
+	enumValues: array(string()).readonly().optional()
+});
+method(object({ deviceId: number().int() }), object({
+	supported: boolean(),
+	slots: array(OsdSlotViewSchema)
+}), { auth: "admin" }), method(object({ deviceId: number().int() }), object({ sources: array(OsdSourceOptionSchema) }), { auth: "admin" }), method(object({}), object({
+	supported: array(string()),
+	catalog: array(NcConditionDescriptorSchema)
+}), { auth: "admin" }), method(object({
+	deviceId: number().int(),
+	slotId: string().min(1),
+	binding: OsdSlotBindingSchema
+}), object({
+	slot: OsdSlotViewSchema,
+	render: OsdRenderResultSchema
+}), {
+	kind: "mutation",
+	auth: "admin"
+}), method(object({
+	deviceId: number().int(),
+	slotId: string().min(1)
+}), object({ success: literal(true) }), {
+	kind: "mutation",
+	auth: "admin"
+}), method(object({
+	deviceId: number().int(),
+	slotId: string().min(1),
+	binding: OsdSlotBindingSchema.optional()
+}), OsdRenderResultSchema, {
+	kind: "mutation",
+	auth: "admin"
+}), method(object({ deviceId: number().int() }), object({ results: array(OsdRenderResultSchema) }), {
+	kind: "mutation",
+	auth: "admin"
+});
+/**
 * Feeder connectivity / power status — mirrors the HA petkit device-status
 * enum: `normal` (online, mains), `offline` (not reaching PetKit cloud),
 * `on_batteries` (running on battery backup). `null` until first reported.
@@ -29632,6 +30862,48 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"osdManager.clearSlotBinding": {
+		capName: "osd-manager",
+		capScope: "system",
+		addonId: null,
+		access: "delete"
+	},
+	"osdManager.getConditionSupport": {
+		capName: "osd-manager",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
+	"osdManager.getDeviceOsd": {
+		capName: "osd-manager",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
+	"osdManager.getSourceCatalog": {
+		capName: "osd-manager",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
+	"osdManager.previewSlot": {
+		capName: "osd-manager",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
+	"osdManager.renderDevice": {
+		capName: "osd-manager",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
+	"osdManager.setSlotBinding": {
+		capName: "osd-manager",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"petFeeder.callPet": {
 		capName: "pet-feeder",
 		capScope: "device",
@@ -29704,6 +30976,12 @@ Object.freeze({
 		addonId: null,
 		access: "delete"
 	},
+	"pipelineAnalytics.completeRetrainTrack": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "create"
+	},
 	"pipelineAnalytics.deleteDeviceEvents": {
 		capName: "pipeline-analytics",
 		capScope: "device",
@@ -29716,6 +30994,12 @@ Object.freeze({
 		addonId: null,
 		access: "delete"
 	},
+	"pipelineAnalytics.deselectRetrainFrame": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "create"
+	},
 	"pipelineAnalytics.getActiveTracks": {
 		capName: "pipeline-analytics",
 		capScope: "device",
@@ -29776,6 +31060,18 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"pipelineAnalytics.getRetrainExportUrl": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
+	"pipelineAnalytics.getRetrainFrameImage": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"pipelineAnalytics.getSensorEvents": {
 		capName: "pipeline-analytics",
 		capScope: "device",
@@ -29794,6 +31090,18 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"pipelineAnalytics.getTrainingExportSummary": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
+	"pipelineAnalytics.getTrainingExportUrl": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"pipelineAnalytics.listEventKinds": {
 		capName: "pipeline-analytics",
 		capScope: "device",
@@ -29818,6 +31126,24 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"pipelineAnalytics.listRetrainAnnotations": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
+	"pipelineAnalytics.listRetrainFrames": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
+	"pipelineAnalytics.listRetrainStaging": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"pipelineAnalytics.listTrackMedia": {
 		capName: "pipeline-analytics",
 		capScope: "device",
@@ -29830,6 +31156,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"pipelineAnalytics.proposeRetrainAnnotations": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "create"
+	},
 	"pipelineAnalytics.pruneEvents": {
 		capName: "pipeline-analytics",
 		capScope: "device",
@@ -29860,12 +31192,30 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"pipelineAnalytics.restageRetrainTrack": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "create"
+	},
+	"pipelineAnalytics.saveRetrainAnnotations": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "create"
+	},
 	"pipelineAnalytics.searchObjectEvents": {
 		capName: "pipeline-analytics",
 		capScope: "device",
 		addonId: null,
 		access: "view"
 	},
+	"pipelineAnalytics.selectRetrainFrames": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "create"
+	},
 	"pipelineAnalytics.setTrackFlags": {
 		capName: "pipeline-analytics",
 		capScope: "device",
@@ -31270,6 +32620,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"streamBroker.getDeviceAudioMute": {
+		capName: "stream-broker",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"streamBroker.getPreBufferInfo": {
 		capName: "stream-broker",
 		capScope: "system",
@@ -31390,6 +32746,12 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"streamBroker.setDeviceAudioMute": {
+		capName: "stream-broker",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"streamBroker.setPreBufferDuration": {
 		capName: "stream-broker",
 		capScope: "system",
@@ -32037,6 +33399,66 @@ Object.freeze({
 	"smtp-provider": "email"
 });
 new Set(["devices", "classes"]);
+var WEEKDAY_TO_DAY = {
+	Sun: 0,
+	Mon: 1,
+	Tue: 2,
+	Wed: 3,
+	Thu: 4,
+	Fri: 5,
+	Sat: 6
+};
+/** Resolve (weekday, minute-of-day) of `atMs` in the schedule's timezone.
+*  An invalid/unknown IANA name falls back to the host timezone. */
+function localDayMinute(atMs, timezone) {
+	const d = new Date(atMs);
+	if (timezone !== void 0) try {
+		const parts = new Intl.DateTimeFormat("en-US", {
+			timeZone: timezone,
+			weekday: "short",
+			hour: "numeric",
+			minute: "numeric",
+			hourCycle: "h23"
+		}).formatToParts(d);
+		let weekday;
+		let hour;
+		let minute;
+		for (const p of parts) if (p.type === "weekday") weekday = p.value;
+		else if (p.type === "hour") hour = Number(p.value);
+		else if (p.type === "minute") minute = Number(p.value);
+		const day = weekday !== void 0 ? WEEKDAY_TO_DAY[weekday] : void 0;
+		if (day !== void 0 && hour !== void 0 && minute !== void 0) return {
+			day,
+			minute: hour * 60 + minute
+		};
+	} catch {}
+	return {
+		day: d.getDay(),
+		minute: d.getHours() * 60 + d.getMinutes()
+	};
+}
+/**
+* Is the schedule active at `atMs`? No schedule = always active. Windows
+* are OR'd; a window with `startMinute > endMinute` crosses midnight (it
+* starts on a listed day and spills into the next). `invert` flips the
+* result (active OUTSIDE the windows).
+*/
+function isScheduleActive(schedule, atMs) {
+	if (schedule === void 0) return true;
+	const { day, minute } = localDayMinute(atMs, schedule.timezone);
+	const prevDay = (day + 6) % 7;
+	let inside = false;
+	for (const w of schedule.windows) if (w.startMinute <= w.endMinute) {
+		if (w.days.includes(day) && minute >= w.startMinute && minute < w.endMinute) {
+			inside = true;
+			break;
+		}
+	} else if (w.days.includes(day) && minute >= w.startMinute || w.days.includes(prevDay) && minute < w.endMinute) {
+		inside = true;
+		break;
+	}
+	return schedule.invert === true ? !inside : inside;
+}
 /**
 * TimelapseRule — the STANDALONE scheduled timelapse producer's rule model.
 *
@@ -32321,6 +33743,18 @@ Object.defineProperty(exports, "EventCategory", {
 		return EventCategory;
 	}
 });
+Object.defineProperty(exports, "Fmp4BoxSplitter", {
+	enumerable: true,
+	get: function() {
+		return Fmp4BoxSplitter;
+	}
+});
+Object.defineProperty(exports, "LabelAttributionSchema", {
+	enumerable: true,
+	get: function() {
+		return LabelAttributionSchema;
+	}
+});
 Object.defineProperty(exports, "MACRO_LABELS", {
 	enumerable: true,
 	get: function() {
@@ -32393,6 +33827,12 @@ Object.defineProperty(exports, "OpsLogEntrySchema", {
 		return OpsLogEntrySchema;
 	}
 });
+Object.defineProperty(exports, "RetrainStatusSchema", {
+	enumerable: true,
+	get: function() {
+		return RetrainStatusSchema;
+	}
+});
 Object.defineProperty(exports, "TimelapseRuleInputSchema", {
 	enumerable: true,
 	get: function() {
@@ -32459,6 +33899,12 @@ Object.defineProperty(exports, "buildEventKindDescriptor", {
 		return buildEventKindDescriptor;
 	}
 });
+Object.defineProperty(exports, "buildFfmpegArgs", {
+	enumerable: true,
+	get: function() {
+		return buildFfmpegArgs;
+	}
+});
 Object.defineProperty(exports, "cosineSimilarity", {
 	enumerable: true,
 	get: function() {
@@ -32525,6 +33971,18 @@ Object.defineProperty(exports, "isDeviceScopedCap", {
 		return isDeviceScopedCap;
 	}
 });
+Object.defineProperty(exports, "isScheduleActive", {
+	enumerable: true,
+	get: function() {
+		return isScheduleActive;
+	}
+});
+Object.defineProperty(exports, "isSoftwareDecode", {
+	enumerable: true,
+	get: function() {
+		return isSoftwareDecode;
+	}
+});
 Object.defineProperty(exports, "kebabToCamel", {
 	enumerable: true,
 	get: function() {