@camstack/addon-pipeline 1.2.274 → 1.2.276

package/dist/recorder/index.mjs

@@ -1,5 +1,5 @@
-import { A as RecordingConfigSchema, At as resolveLocationMode, Dt as recordingSignalCapability, Et as recordingExportCapability, Ft as storageOccupancyCapability, G as deriveBatteryPresence, Jt as BaseAddon, Lt as stripRetiredBandPreBufferSec, Mt as resolveRecordingProfiles, N as VISIT_MERGE_GAP_MS, Pt as storageEvictableCapability, Q as evaluateSensorEdge, Sn as string, T as OpsLogEntrySchema, Tt as recordingCapability, Vt as errMsg, Xt as DeviceFeature, Zt as DeviceType, bn as preprocess, d as DEFAULT_EVENTS_BAND_BUFFER_SEC, dn as sleep$1, dt as mayReadLocation, en as customAction, et as evictionPolicyForMode, fn as _enum, ft as mayWriteToLocation, g as EVENT_PAD_MS, h as EVENT_OWNER_TYPES, i as BatteryStatusSchema, j as RecordingSignalStatusSchema, k as RECORDING_EXPORT_MAX_READ_BYTES, mn as boolean, mt as modeMayWrite, ot as isFirstLevelMacroClass, pn as array, pt as migrateLegacyDeviceSignalConfig, q as deriveRecordingMode, rn as hydrateSchema, rt as gbToBytes, sn as nodePin, st as loadContributionCapability, tn as defineCustomActions, tt as evictionPolicyOfLocation, un as selectAssignedProfileSlots, v as ExportRecordSchema, vn as number, wn as EventCategory, xn as record, yn as object, z as batteryCapability, zt as videoclipsCapability } from "../dist-g5MfpiBh.mjs";
-import { a as physicalRootOf, i as NO_COST_CLAIM, t as ChildCostRegistry } from "../node-BXsHQH5h.mjs";
+import { A as RecordingConfigSchema, At as recordingSignalCapability, Cn as number, Dn as string, En as record, Gt as errMsg, H as clipExportFailureOf, It as resolveRecordingProfiles, Mt as resolveCreateExportSubject, N as VISIT_MERGE_GAP_MS, Ot as recordingCapability, Pt as resolveLocationMode, Qt as BaseAddon, Rt as storageEvictableCapability, T as OpsLogEntrySchema, Tn as preprocess, Ut as videoclipsCapability, V as clipExportFailure, Vt as stripRetiredBandPreBufferSec, Y as deriveRecordingMode, _n as _enum, _t as modeMayWrite, an as customAction, cn as hydrateSchema, d as DEFAULT_EVENTS_BAND_BUFFER_SEC, et as evaluateSensorEdge, fn as nodePin, g as EVENT_PAD_MS, gn as sleep$1, gt as migrateLegacyDeviceSignalConfig, h as EVENT_OWNER_TYPES, hn as selectAssignedProfileSlots, ht as mayWriteToLocation, i as BatteryStatusSchema, it as exportSubjectOf, j as RecordingSignalStatusSchema, k as RECORDING_EXPORT_MAX_READ_BYTES, kn as EventCategory, kt as recordingExportCapability, lt as isFirstLevelMacroClass, mt as mayReadLocation, nn as DeviceType, nt as evictionPolicyForMode, on as defineCustomActions, ot as gbToBytes, q as deriveBatteryPresence, rt as evictionPolicyOfLocation, tn as DeviceFeature, ut as loadContributionCapability, v as ExportRecordSchema, vn as array, wn as object, yn as boolean, z as batteryCapability, zt as storageOccupancyCapability } from "../dist-C1pCVJk7.mjs";
+import { a as physicalRootOf, i as NO_COST_CLAIM, t as ChildCostRegistry } from "../node--UY0iepi.mjs";
 import { t as resolveHubHostname } from "../hub-hostname-cCknRYKj.mjs";
 import { d as PREBUFFER_MAX_MS, l as withRecordingIntent, r as RECORDING_PRE_ROLL_REQUEST_MS } from "../restream-intent-DyGmLAU9.mjs";
 import { n as RowMapStore, t as retireRootKeys } from "../retire-root-keys-DZvlso2l.mjs";
@@ -6122,6 +6122,21 @@ function errnoCode(raw) {
 }
 //#endregion
 //#region src/recorder/addon/export-engine.ts
+/**
+* How long an operator's authorised wake stays spendable.
+*
+* One authorised yes is ONE wake (D558 § 5.2 rule 3), and the two ways a job
+* outlives its yes without anybody meaning it are both real here: it can sit
+* behind {@link EXPORT_MAX_CONCURRENT} long renders, and it can be re-queued
+* after a restart. Five minutes is generous against a job measured at 4–6 s
+* end to end and short enough that a camera is never woken for a tap the
+* operator has forgotten making.
+*
+* Past it the export FAILS with `wake-expired` — a named row the operator can
+* retry with one tap, which re-asks for the authorisation — rather than
+* silently waking the camera on a yes from an hour ago.
+*/
+var CLIP_WAKE_TTL_MS = 5 * 6e4;
 /** Stderr lines retained for the failure LOG. ffmpeg prints one line per failed
 *  segment before the decisive "Error opening input" summary, so a short tail can
 *  push the actual cause out of the window (it very nearly did — the line that
@@ -6130,6 +6145,42 @@ function errnoCode(raw) {
 var STDERR_TAIL_LINES$1 = 40;
 var TIME_RE = /time=(\d+):(\d+):(\d+(?:\.\d+)?)/;
 /**
+* How far a delivered clip's duration may sit from its catalog span before it
+* is worth a line. A remux rounds, a GOP boundary moves a fraction of a
+* second; two seconds is past both and well under D568's own "materially
+* shorter" retry threshold, so this reports a disagreement the PRODUCER
+* already decided to serve rather than second-guessing its completion rule.
+*/
+var CLIP_DURATION_TOLERANCE_MS = 2e3;
+/**
+* The source id of the recorder's OWN `videoclips` provider — a visit over
+* footage we wrote, not a file a camera holds (D560).
+*
+* Duplicating the literal rather than importing `videoclips-provider.ts`
+* keeps the engine free of the provider (and of the analytics event reads it
+* carries); the two are pinned together by
+* `export-engine-clip-fetch.spec.ts`.
+*/
+var ANALYTICS_CLIP_SOURCE = "analytics";
+/**
+* Read a producer's refusal as one of the named clip-export failures.
+*
+* A producer that speaks the vocabulary is believed — `clipExportFailureOf`
+* recovers its token, so a `sleeping` stays `sleeping` all the way to the
+* modal. Anything else is `fetch-failed` **with the producer's words kept
+* verbatim**: inventing a more specific token from prose is how a surface's
+* table came to render every refusal on this fleet as `Refused: <prose>`
+* (ClipStillRefusalCode's own docblock). The one exception is the size bound,
+* which the producer states in numbers rather than in a token, and which the
+* operator must be able to tell from a network failure.
+*/
+function classifyClipFetchFailure(detail) {
+	const spoken = clipExportFailureOf(detail);
+	if (spoken !== null) return spoken;
+	if (/too large/i.test(detail)) return "too-large-to-transfer";
+	return "fetch-failed";
+}
+/**
 * The floor under which an MP4 cannot hold a single decodable frame.
 *
 * **Exit 0 is not the same question as "the file holds a video".** A timelapse
@@ -6211,6 +6262,13 @@ var ExportEngine = class {
 		}
 	}
 	async render(id) {
+		const existing = await getExportRecord(this.deps.state, id);
+		if (!existing) return;
+		const subject = exportSubjectOf(existing);
+		if (subject.kind === "clip" && subject.source !== ANALYTICS_CLIP_SOURCE) {
+			await this.fetchClip(id, existing, subject);
+			return;
+		}
 		const rec = await patchExport(this.deps.state, id, {
 			state: "rendering",
 			progressPct: 0
@@ -6239,6 +6297,187 @@ var ExportEngine = class {
 		}
 	}
 	/**
+	* The CLIP branch: one by-handle fetch, under a bound, written straight to
+	* the export path. No playlist, no ffmpeg, no second completion rule.
+	*
+	* The recorder cannot produce these bytes itself — talking to the camera is
+	* the owning addon's monopoly (one session per host, the sleep gate before
+	* `getApi()`, a cmd-5 transfer whose completion is an idle window proved
+	* against the catalog span, D549 17 / D568) — and there is no addon→addon
+	* byte transport, so the producer's own cap read is the seam (D558 § 3).
+	*
+	* `progressPct` stays `null` for the whole fetch. The job is measured at
+	* 4–6 s end to end and only two of its phases have a real denominator; a
+	* ramp would be a number nothing measured (D558 § 5.1).
+	*
+	* Every exit is named. A branch that accepts work and produces nothing is
+	* the branch this repo keeps losing work in (D391), and a clip export has
+	* five such branches a footage render does not have.
+	*/
+	async fetchClip(id, rec, subject) {
+		const tags = { deviceId: rec.deviceId };
+		const now = (this.deps.now ?? Date.now)();
+		if (subject.wake !== void 0 && now - rec.createdAt > 3e5) {
+			const waitedMs = now - rec.createdAt;
+			this.deps.logger.warn("clip export refused: it outlived the wake it was granted", {
+				tags,
+				meta: {
+					exportId: id,
+					clipId: subject.clipId,
+					waitedMs,
+					ttlMs: CLIP_WAKE_TTL_MS
+				}
+			});
+			await this.fail(id, clipExportFailure("wake-expired", `queued ${Math.round(waitedMs / 1e3)}s ago, past the ${Math.round(CLIP_WAKE_TTL_MS / 1e3)}s an authorised wake stays spendable — ask again to wake the camera`));
+			return;
+		}
+		const fetchClipBytes = this.deps.fetchClipBytes;
+		const writeExportFile = this.deps.writeExportFile;
+		if (fetchClipBytes === void 0 || writeExportFile === void 0) {
+			this.deps.logger.error("clip export refused: this recorder has no clip byte reader wired", {
+				tags,
+				meta: {
+					exportId: id,
+					clipId: subject.clipId
+				}
+			});
+			await this.fail(id, clipExportFailure("fetch-failed", "this recorder has no clip byte reader wired"));
+			return;
+		}
+		await patchExport(this.deps.state, id, {
+			state: "rendering",
+			progressPct: null
+		});
+		this.deps.logger.info("clip export fetch starting", {
+			tags,
+			meta: {
+				exportId: id,
+				clipId: subject.clipId,
+				source: subject.source,
+				provider: subject.provider,
+				profile: subject.profile,
+				wake: subject.wake ?? "none"
+			}
+		});
+		let answer;
+		try {
+			answer = await fetchClipBytes({
+				deviceId: subject.deviceId,
+				clipId: subject.clipId,
+				profile: subject.profile,
+				maxBytes: RECORDING_EXPORT_MAX_READ_BYTES,
+				...subject.wake !== void 0 ? { wake: subject.wake } : {}
+			});
+		} catch (err) {
+			const detail = err instanceof Error ? err.message : String(err);
+			const code = classifyClipFetchFailure(detail);
+			this.deps.logger.warn("clip export fetch failed", {
+				tags,
+				meta: {
+					exportId: id,
+					clipId: subject.clipId,
+					reason: code,
+					error: detail
+				}
+			});
+			await this.fail(id, clipExportFailure(code, detail));
+			return;
+		}
+		if (this.cancelled.has(id)) {
+			this.cancelled.delete(id);
+			await this.fail(id, "cancelled");
+			return;
+		}
+		const bytes = Buffer.from(answer.base64, "base64");
+		if (bytes.byteLength > 52428800) {
+			this.deps.logger.warn("clip export refused: the answer exceeded the transfer bound", {
+				tags,
+				meta: {
+					exportId: id,
+					bytes: bytes.byteLength,
+					maxBytes: RECORDING_EXPORT_MAX_READ_BYTES
+				}
+			});
+			await this.fail(id, clipExportFailure("too-large-to-transfer", `${bytes.byteLength} > ${RECORDING_EXPORT_MAX_READ_BYTES} bytes`));
+			return;
+		}
+		if (bytes.byteLength < 1024) {
+			this.deps.logger.error("clip export produced no video", {
+				tags,
+				meta: {
+					exportId: id,
+					clipId: subject.clipId,
+					bytes: bytes.byteLength,
+					minBytes: EXPORT_MIN_PLAUSIBLE_BYTES
+				}
+			});
+			await this.fail(id, clipExportFailure("fetch-failed", `the source answered ${bytes.byteLength} bytes, under the ${EXPORT_MIN_PLAUSIBLE_BYTES} a playable MP4 needs`));
+			return;
+		}
+		const outPath = this.deps.outPath(rec);
+		try {
+			await writeExportFile(outPath, bytes);
+		} catch (err) {
+			const detail = err instanceof Error ? err.message : String(err);
+			this.deps.logger.error("clip export could not be written", {
+				tags,
+				meta: {
+					exportId: id,
+					outPath,
+					error: detail
+				}
+			});
+			await this.deps.removeFile(outPath);
+			await this.fail(id, clipExportFailure("fetch-failed", `could not write the export: ${detail}`));
+			return;
+		}
+		const servedPatch = answer.served !== rec.profile ? { profile: answer.served } : {};
+		if (answer.served !== rec.profile) this.deps.logger.warn("clip export served a different twin than the catalog projected", {
+			tags,
+			meta: {
+				exportId: id,
+				clipId: subject.clipId,
+				asked: subject.profile,
+				projected: rec.profile,
+				served: answer.served
+			}
+		});
+		const claimedMs = rec.toMs - rec.fromMs;
+		if (answer.durationMs !== void 0 && Math.abs(answer.durationMs - claimedMs) > CLIP_DURATION_TOLERANCE_MS) this.deps.logger.warn("clip export duration disagrees with the catalog row", {
+			tags,
+			meta: {
+				exportId: id,
+				clipId: subject.clipId,
+				catalogSpanMs: claimedMs,
+				deliveredMs: answer.durationMs
+			}
+		});
+		await patchExport(this.deps.state, id, {
+			state: "ready",
+			progressPct: 100,
+			fileBytes: bytes.byteLength,
+			error: null,
+			...servedPatch
+		});
+		this.deps.logger.info("clip export ready", {
+			tags,
+			meta: {
+				exportId: id,
+				clipId: subject.clipId,
+				outPath,
+				bytes: bytes.byteLength,
+				served: answer.served
+			}
+		});
+		this.deps.emit(EventCategory.RecordingExportCompleted, {
+			exportId: id,
+			fileBytes: bytes.byteLength,
+			deviceId: rec.deviceId,
+			...rec.options.title !== void 0 ? { title: rec.options.title } : {},
+			...rec.options.notifyTargetIds !== void 0 && rec.options.notifyTargetIds.length > 0 ? { notifyTargetIds: rec.options.notifyTargetIds } : {}
+		});
+	}
+	/**
 	* The record's options with any dense overlay moved onto ffmpeg's clock.
 	*
 	* The translation is reported on EVERY render that carries an overlay, not
@@ -6674,6 +6913,22 @@ function isInterrupted(record) {
 	return record.state === "queued" || record.state === "rendering";
 }
 /**
+* Did this row carry an operator's authorised WAKE?
+*
+* A re-queue is the third of the three ways D558 § 5.2 rule 3 names for
+* spending one yes twice, and it is the quietest: the row reaches the fetch
+* hours after the tap, wakes the camera, and nothing in the log says the
+* operator did not ask for it. So a clip export holding a wake is FAILED by
+* name instead — a row he can retry with one tap, which re-asks for the
+* authorisation. A clip export WITHOUT a wake is re-queued like any render:
+* there is nothing to spend, and a sleeping camera refuses at its own gate
+* exactly as it did the first time.
+*/
+function carriesAnAuthorisedWake(record) {
+	const subject = exportSubjectOf(record);
+	return subject.kind === "clip" && subject.wake !== void 0;
+}
+/**
 * Hand every interrupted row back to the engine, once, at boot.
 *
 * A row past its `expiresAt` is FAILED rather than re-rendered: hours of
@@ -6701,6 +6956,19 @@ async function reconcileInterruptedExports(deps) {
 			toMs: row.toMs,
 			createdAt: row.createdAt
 		};
+		if (carriesAnAuthorisedWake(row)) {
+			expired += 1;
+			await patchExport(deps.state, row.id, {
+				state: "failed",
+				progressPct: null,
+				error: clipExportFailure("wake-expired", "interrupted by a restart — one authorised wake is one wake, so ask again to wake the camera")
+			});
+			deps.logger.warn("clip export abandoned: it was interrupted while holding a wake", {
+				tags,
+				meta
+			});
+			continue;
+		}
 		if (row.expiresAt <= now) {
 			expired += 1;
 			await patchExport(deps.state, row.id, {
@@ -13523,6 +13791,73 @@ function clusterFootageVisits(ranges, gapMs = VISIT_MERGE_GAP_MS) {
 	visits.push(finishVisit(pieces, endMs));
 	return visits;
 }
+/**
+* A visit per BURST OF EVENTS, clamped to the footage that exists behind it.
+*
+* ## Why this replaced clustering the availability
+*
+* {@link VISIT_MERGE_GAP_MS}'s own docblock states the claim: 30 s "glues
+* those intra-visit holes without joining visits hours apart". It was applied
+* to the wrong input. {@link clusterFootageVisits} clusters AVAILABILITY, and
+* availability only has gaps on an EVENTS-MODE camera, where the writer opens
+* and closes around activity. A camera that records continuously has none —
+* so the visit became the recording session.
+*
+* Measured on 592, 2026-09-21, 24 h: seven rows covering the whole day, one of
+* them 7 h 58 m. Clustering the same day's EVENTS at the same 30 s gives 46
+* visits overnight and 36 in the day, median 17 s, longest 99 s. The constant
+* was right; the input was not. No duration cap: it would split by the clock
+* rather than by what happened, and nothing here needs splitting that way.
+*
+* ## What the footage is still for
+*
+* It CLAMPS, it does not define. A visit keeps only the pieces it actually
+* covers, because {@link stillInstantMs} takes the midpoint of the longest
+* piece — handed the whole session's range it would put the still hours from
+* the event. A burst with no footage behind it is dropped: an event the
+* recorder never kept is not a clip, and listing it is a row that opens onto
+* nothing.
+*/
+function clusterEventVisits(events, ranges, gapMs, pad) {
+	if (events.length === 0 || ranges.length === 0) return [];
+	const times = [...events].map((e) => e.timestamp).toSorted((a, b) => a - b);
+	const sortedRanges = [...ranges].toSorted((a, b) => a.startMs - b.startMs);
+	const bursts = [];
+	let first = times[0];
+	let last = times[0];
+	for (let i = 1; i < times.length; i++) {
+		const t = times[i];
+		if (t - last <= gapMs) {
+			last = t;
+			continue;
+		}
+		bursts.push({
+			startMs: first - pad.preMs,
+			endMs: last + pad.postMs
+		});
+		first = t;
+		last = t;
+	}
+	bursts.push({
+		startMs: first - pad.preMs,
+		endMs: last + pad.postMs
+	});
+	const visits = [];
+	for (const burst of bursts) {
+		const pieces = [];
+		for (const range of sortedRanges) {
+			const startMs = Math.max(range.startMs, burst.startMs);
+			const endMs = Math.min(range.endMs, burst.endMs);
+			if (endMs > startMs) pieces.push({
+				startMs,
+				endMs
+			});
+		}
+		if (pieces.length === 0) continue;
+		visits.push(finishVisit(pieces, pieces[pieces.length - 1].endMs));
+	}
+	return visits;
+}
 function finishVisit(pieces, endMs) {
 	const holes = [];
 	for (let i = 1; i < pieces.length; i++) {
@@ -13697,13 +14032,17 @@ function eventsToClips(events, pad, vouched) {
 		...events.audio.map((e) => make(e, "audio"))
 	].toSorted((a, b) => b.timeRange.startMs - a.timeRange.startMs);
 }
-/** Every id in the three buckets, in the order the composers tag them. */
-function allEventIds(events) {
+/** Every event in the three buckets, in the order the composers tag them. */
+function allEvents(events) {
 	return [
 		...events.motion,
 		...events.object,
 		...events.audio
-	].map((e) => e.id);
+	];
+}
+/** Every id in the three buckets, in the order the composers tag them. */
+function allEventIds(events) {
+	return allEvents(events).map((e) => e.id);
 }
 /**
 * Resolve the event ids whose `mediaUrl` is backed by real bytes, mirroring
@@ -13820,11 +14159,12 @@ function createVideoclipsProvider(deps) {
 			}
 			let clips = eventsToClips(events, deps.defaultPad, vouched);
 			if (deps.fetchAvailability) try {
-				clips = visitsToClips(clusterFootageVisits(await deps.fetchAvailability({
+				const ranges = await deps.fetchAvailability({
 					deviceId,
 					since: readSince,
 					until
-				}), VISIT_MERGE_GAP_MS), events, deps.defaultPad, vouched);
+				});
+				clips = visitsToClips(clusterEventVisits(allEvents(events), ranges, VISIT_MERGE_GAP_MS, deps.defaultPad), events, deps.defaultPad, vouched);
 			} catch (err) {
 				deps.logWarn?.("videoclips: availability read failed — listing unfiltered", {
 					deviceId,
@@ -13870,6 +14210,20 @@ function createVideoclipsProvider(deps) {
 				}),
 				format: "hls"
 			};
+		},
+		/**
+		* This source has no bytes to hand over, and says so rather than
+		* inventing a path to them.
+		*
+		* An `analytics` clip is a time WINDOW over footage the recorder already
+		* owns — there is no file behind it, and a caller that wants it as one
+		* asks for it as an EXPORT, where the source playlist and
+		* `export-dense-map` handle the holes a visit spans by construction
+		* (D558 § 5.4.3). Reading it here would be this addon fetching from
+		* itself, over a cap channel, in base64.
+		*/
+		readClipBytes: async ({ clipId }) => {
+			throw new Error(`videoclips: "${clipId}" is an analytics visit — a window over recorded footage with no file behind it. Export it through recordingExport with the same clip subject; the recorder renders it from its own segments.`);
 		}
 	};
 }
@@ -17275,6 +17629,81 @@ function makeBrokerCall(handle) {
 	return (fn) => handle.call(fn, BROKER_READY_TIMEOUT_MS);
 }
 //#endregion
+//#region src/recorder/addon/export-clip-catalog.ts
+/**
+* Catalog page size for the confirm.
+*
+* One local day is the window (`ExportClipSubject.catalogWindow`) and a busy
+* day on 592 measured 546 rows, so 1 000 holds a day with room and still
+* bounds a pathological camera. A truncated page would read as "this clip is
+* gone", which is the one answer this gate must never give wrongly.
+*/
+var EXPORT_CLIP_CATALOG_LIMIT = 1e3;
+/**
+* Which twin this row can actually serve for the asked profile.
+*
+* The mapping is the one D549 15 already fixed — `low | mid` → the sub file,
+* `high` → the main twin — and both ids are resolved at LISTING time, so this
+* never re-searches the camera. A row that holds only one twin answers with
+* the one it has and the caller SAYS so: the ask stays on `subject.profile`
+* and this lands on the record's top-level `profile`, so a week later the row
+* still tells the operator he was handed the sub stream.
+*
+* A row with no `streams` block at all is not a fallback and not a guess: the
+* ask is carried through and the producer's own `served` is what corrects it.
+*/
+function servedTwinFor(clip, asked) {
+	const streams = clip.streams;
+	if (streams === void 0) return asked;
+	const hasMain = streams.main !== void 0;
+	const hasSub = streams.sub !== void 0;
+	if (asked === "high") return hasMain ? "high" : hasSub ? "low" : asked;
+	return hasSub ? asked : hasMain ? "high" : asked;
+}
+/**
+* Judge one catalog answer for one clip subject. Pure — the I/O is the
+* caller's, so every refusal below is unit-testable without a camera.
+*/
+function judgeClipRow(subject, rows) {
+	const clip = rows.find((row) => row.id === subject.clipId);
+	if (clip === void 0) return {
+		ok: false,
+		refusal: {
+			code: "catalog-miss",
+			detail: `"${subject.sourceLabel}" does not list ${subject.clipId} between ${subject.catalogWindow.sinceMs} and ${subject.catalogWindow.untilMs}`
+		}
+	};
+	if (clip.playable === false) return {
+		ok: false,
+		refusal: {
+			code: "no-file-for-window",
+			detail: clip.unplayableReason ?? "no bytes"
+		}
+	};
+	if (clip.inProgress === true) return {
+		ok: false,
+		refusal: {
+			code: "clip-in-progress",
+			detail: "the camera is still writing this recording, so it has no end to export yet"
+		}
+	};
+	const { startMs, endMs } = clip.timeRange;
+	if (!(startMs < endMs)) return {
+		ok: false,
+		refusal: {
+			code: "catalog-miss",
+			detail: `the row carries no usable span (${startMs}..${endMs})`
+		}
+	};
+	return {
+		ok: true,
+		accepted: {
+			clip,
+			served: servedTwinFor(clip, subject.profile)
+		}
+	};
+}
+//#endregion
 //#region src/recorder/addon/recording-export-provider.ts
 /** Content type of every rendered export — the engine only ever writes MP4. */
 var EXPORT_CONTENT_TYPE = "video/mp4";
@@ -17302,12 +17731,6 @@ function exportFileName(rec) {
 async function hasFootage(index, deviceId, profile, fromMs, toMs) {
 	return (await index.segmentsInWindow(deviceId, profile, fromMs, toMs)).some((s) => s.startMs < toMs && s.startMs + s.durMs > fromMs);
 }
-/** Canonical `profiles[]`, falling back to the legacy singular `profile`. */
-function resolveExportProfiles(input) {
-	if (input.profiles !== void 0 && input.profiles.length > 0) return [...input.profiles];
-	if (typeof input.profile === "string" && input.profile.length > 0) return [input.profile];
-	return [];
-}
 /** Load a record or throw a clear NOT_FOUND-style error. */
 async function requireRecord(state, exportId) {
 	const rec = await getExportRecord(state, exportId);
@@ -17316,37 +17739,133 @@ async function requireRecord(state, exportId) {
 }
 /** Build the `recordingExport` provider over the injected deps. */
 function buildRecordingExportProvider(deps) {
+	/**
+	* Persist one `queued` row and hand it to the engine. The ONE place a record
+	* is born, for both kinds — so the fields nothing about the subject decides
+	* (the lifetime, the audit stamp, the null progress) cannot drift apart.
+	*/
+	const queueOne = async (fields, options, now) => {
+		const saved = await upsertExport(deps.state, {
+			...fields,
+			id: deps.newId(),
+			options,
+			state: "queued",
+			progressPct: null,
+			fileBytes: null,
+			expiresAt: now + options.maxLifeMs,
+			deleteAfterDownload: options.deleteAfterDownload,
+			downloadedAt: null,
+			createdAt: now,
+			createdBy: deps.createdBy(),
+			error: null
+		});
+		deps.engine.enqueue(saved.id);
+		return saved;
+	};
+	/**
+	* The clip branch's fail-fast gate — the catalog, never the recording index.
+	*
+	* Refuses BEFORE a row exists, so an operator gets the reason in the answer
+	* to his own tap instead of discovering it on a `failed` row a minute later,
+	* and so a refusal never spends a wake.
+	*/
+	const createClipExport = async (subject, options) => {
+		const tags = { deviceId: subject.deviceId };
+		if (options.timelapse !== void 0 || options.speed !== void 0 && options.speed !== 1) {
+			const detail = "a clip is remuxed, never re-timed — drop speed/timelapse";
+			deps.logger.warn("clip export refused: a render option a remux cannot honour", {
+				tags,
+				meta: {
+					clipId: subject.clipId,
+					speed: options.speed,
+					timelapse: options.timelapse
+				}
+			});
+			throw new Error(clipExportFailure("unsupported-option", detail));
+		}
+		let rows;
+		try {
+			rows = await deps.clipCatalog.listClips({
+				deviceId: subject.deviceId,
+				since: subject.catalogWindow.sinceMs,
+				until: subject.catalogWindow.untilMs,
+				provider: subject.provider,
+				limit: EXPORT_CLIP_CATALOG_LIMIT
+			});
+		} catch (err) {
+			const detail = err instanceof Error ? err.message : String(err);
+			deps.logger.warn("clip export refused: the clip catalog could not be read", {
+				tags,
+				meta: {
+					clipId: subject.clipId,
+					provider: subject.provider,
+					error: detail
+				}
+			});
+			throw new Error(clipExportFailure("catalog-unreachable", detail), { cause: err });
+		}
+		const outcome = judgeClipRow(subject, rows);
+		if (!outcome.ok) {
+			deps.logger.warn("clip export refused by the catalog gate", {
+				tags,
+				meta: {
+					clipId: subject.clipId,
+					provider: subject.provider,
+					reason: outcome.refusal.code,
+					detail: outcome.refusal.detail
+				}
+			});
+			throw new Error(clipExportFailure(outcome.refusal.code, outcome.refusal.detail));
+		}
+		const { clip, served } = outcome.accepted;
+		const record = await queueOne({
+			deviceId: subject.deviceId,
+			profile: served,
+			fromMs: clip.timeRange.startMs,
+			toMs: clip.timeRange.endMs,
+			subject
+		}, options, deps.now());
+		deps.logger.info("clip export queued", {
+			tags,
+			meta: {
+				exportId: record.id,
+				clipId: subject.clipId,
+				source: subject.source,
+				provider: subject.provider,
+				askedProfile: subject.profile,
+				servedProfile: served,
+				wake: subject.wake ?? "none",
+				fromMs: record.fromMs,
+				toMs: record.toMs
+			}
+		});
+		return record;
+	};
 	return {
 		createExport: async (input) => {
-			const { deviceId, fromMs, toMs, options } = input;
-			const profiles = resolveExportProfiles(input);
-			if (profiles.length < 1) throw new Error("recording-export: profiles must contain at least one profile");
+			const subject = resolveCreateExportSubject(input);
+			if (subject.kind === "clip") return await createClipExport(subject, input.options);
+			const { deviceId, profiles, fromMs, toMs } = subject;
+			const { options } = input;
 			if (!(fromMs < toMs)) throw new Error(`recording-export: invalid range ${fromMs}..${toMs}`);
 			for (const profile of profiles) if (!await hasFootage(deps.index, deviceId, profile, fromMs, toMs)) throw new Error(`recording-export: no footage for ${deviceId}/${profile} in ${fromMs}..${toMs}`);
 			const now = deps.now();
-			let first = null;
-			for (const profile of profiles) {
-				const record = {
-					id: deps.newId(),
-					deviceId,
-					profile,
-					fromMs,
-					toMs,
-					options,
-					state: "queued",
-					progressPct: null,
-					fileBytes: null,
-					expiresAt: now + options.maxLifeMs,
-					deleteAfterDownload: options.deleteAfterDownload,
-					downloadedAt: null,
-					createdAt: now,
-					createdBy: deps.createdBy(),
-					error: null
-				};
-				const saved = await upsertExport(deps.state, record);
-				deps.engine.enqueue(saved.id);
-				first ??= saved;
-			}
+			const [head, ...rest] = profiles;
+			if (head === void 0) throw new Error("recording-export: profiles must contain at least one profile");
+			const first = await queueOne({
+				deviceId,
+				profile: head,
+				fromMs,
+				toMs,
+				subject
+			}, options, now);
+			for (const profile of rest) await queueOne({
+				deviceId,
+				profile,
+				fromMs,
+				toMs,
+				subject
+			}, options, now);
 			return first;
 		},
 		listExports: ({ deviceId }) => listExportsFor(deps.state, deviceId),
@@ -19121,7 +19640,19 @@ var RecorderV2Addon = class extends BaseAddon {
 			outPath: exportOutPath,
 			statBytes: async (p) => (await promises.stat(p)).size,
 			removeFile: removeExportFile,
-			emit: (category, data) => this.emitExportEvent(category, data)
+			emit: (category, data) => this.emitExportEvent(category, data),
+			now: () => Date.now(),
+			fetchClipBytes: async (req) => await this.ctx.api.videoclips.readClipBytes.query({
+				deviceId: req.deviceId,
+				clipId: req.clipId,
+				profile: req.profile,
+				maxBytes: req.maxBytes,
+				...req.wake !== void 0 ? { wake: req.wake } : {}
+			}),
+			writeExportFile: async (p, bytes) => {
+				await promises.mkdir(path.dirname(p), { recursive: true });
+				await promises.writeFile(p, bytes);
+			}
 		});
 		const exportProvider = buildRecordingExportProvider({
 			state: exportsState,
@@ -19130,6 +19661,7 @@ var RecorderV2Addon = class extends BaseAddon {
 				if (this.index.hydrationOf(deviceId, fromMs, toMs) !== "hydrated") await hydrateWindowFromStorage(this.index, deviceId, fromMs, toMs, this.resolvedLocations, this.ctx.logger, this.segmentHours ?? void 0);
 				return this.index.segments(deviceId, profile);
 			} },
+			clipCatalog: { listClips: async (input) => await this.ctx.api.videoclips.listClips.query(input) },
 			now: () => Date.now(),
 			newId: () => randomUUID(),
 			createdBy: () => "operator",