@camstack/addon-post-analysis 1.2.50 → 1.2.51

package/dist/{dist-BhadCxSQ.mjs → dist-DTeVOZBt.mjs}

@@ -1,3 +1,4 @@
+import "node:crypto";
 //#region ../types/dist/event-category-41fKf-q9.mjs
 var EventCategory = /* @__PURE__ */ function(EventCategory) {
 	EventCategory["SystemBoot"] = "system.boot";
@@ -7135,6 +7136,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'
@@ -15679,6 +16147,60 @@ var TrackFlagsSchema = object({
 	*  `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(),
@@ -15703,7 +16225,7 @@ 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(),
@@ -15816,7 +16338,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. */
@@ -15897,6 +16419,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({
@@ -15951,7 +16640,7 @@ 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(),
@@ -16442,6 +17131,201 @@ var pipelineAnalyticsCapability = {
 			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()
@@ -17106,6 +17990,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
@@ -30055,6 +30955,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",
@@ -30067,6 +30973,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",
@@ -30127,6 +31039,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",
@@ -30181,6 +31105,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",
@@ -30193,6 +31135,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",
@@ -30223,12 +31171,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",
@@ -32714,4 +33680,4 @@ DEFAULT_NATIVE_LEASE_SETTINGS.budgetMb;
 DEFAULT_NATIVE_LEASE_SETTINGS.activityMs;
 DEFAULT_NATIVE_LEASE_SETTINGS.admission;
 //#endregion
-export { literal as $, faceGalleryCapability as A, videoclipsCapability as B, audioMetricsCapability as C, defineCustomActions as D, customAction as E, pipelineAnalyticsCapability as F, createEvent as G, errMsg as H, plateGalleryCapability as I, nodePin as J, hydrateSchema as K, readDeviceStateFrom as L, isScheduleActive as M, kebabToCamel as N, embeddingEncoderCapability as O, notificationRulesCapability as P, boolean as Q, subKindsOf as R, alarmPanelCapability as S, cosineSimilarity as T, BaseAddon as U, zoneAnalyticsCapability as V, DeviceType as W, _enum as X, sleep as Y, array as Z, RetrainStatusSchema as _, MACRO_LABELS as a, EventCategory as at, TrackSourceSchema as b, NcConditionDescriptorSchema as c, NcRuleSchema as d, number as et, NcSnoozeInputSchema as f, OpsLogEntrySchema as g, NcTaxonomySchema as h, EVENT_PAD_MS as i, unknown as it, hfModelUrl as j, encodeVectorBase64 as k, NcRuleInputSchema as l, NcSnoozeSuppressedSchema as m, DEFAULT_EVENT_COLOR as n, record as nt, NC_CONDITION_CATALOG as o, NcSnoozeSchema as p, isDeviceScopedCap as q, EVENT_KIND_BY_CAP as r, string as rt, NC_TAXONOMY as s, BaseDevice as t, object as tt, NcRulePatchSchema as u, TimelapseRuleInputSchema as v, buildEventKindDescriptor as w, addonWidgetsSourceCapability as x, TimelapseRuleSchema as y, vectorDimFromBase64 as z };
+export { sleep as $, encodeVectorBase64 as A, vectorDimFromBase64 as B, alarmPanelCapability as C, customAction as D, cosineSimilarity as E, notificationRulesCapability as F, buildFfmpegArgs as G, zoneAnalyticsCapability as H, pipelineAnalyticsCapability as I, DeviceType as J, isSoftwareDecode as K, plateGalleryCapability as L, hfModelUrl as M, isScheduleActive as N, defineCustomActions as O, kebabToCamel as P, nodePin as Q, readDeviceStateFrom as R, addonWidgetsSourceCapability as S, buildEventKindDescriptor as T, errMsg as U, videoclipsCapability as V, Fmp4BoxSplitter as W, hydrateSchema as X, createEvent as Y, isDeviceScopedCap as Z, OpsLogEntrySchema as _, LabelAttributionSchema as a, object as at, TimelapseRuleSchema as b, NC_TAXONOMY as c, unknown as ct, NcRulePatchSchema as d, _enum as et, NcRuleSchema as f, NcTaxonomySchema as g, NcSnoozeSuppressedSchema as h, EVENT_PAD_MS as i, number as it, faceGalleryCapability as j, embeddingEncoderCapability as k, NcConditionDescriptorSchema as l, EventCategory as lt, NcSnoozeSchema as m, DEFAULT_EVENT_COLOR as n, boolean as nt, MACRO_LABELS as o, record as ot, NcSnoozeInputSchema as p, BaseAddon as q, EVENT_KIND_BY_CAP as r, literal as rt, NC_CONDITION_CATALOG as s, string as st, BaseDevice as t, array as tt, NcRuleInputSchema as u, RetrainStatusSchema as v, audioMetricsCapability as w, TrackSourceSchema as x, TimelapseRuleInputSchema as y, subKindsOf as z };