@camstack/addon-pipeline 1.2.273 → 1.2.275

package/dist/recorder/index.js

@@ -3,8 +3,8 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("../chunk-emK7D4bc.js");
-const require_dist = require("../dist-DRDzfOnl.js");
-const require_node = require("../node-BmTPPuIg.js");
+const require_dist = require("../dist-NYjn7hkE.js");
+const require_node = require("../node-CVYY8a4y.js");
 const require_hub_hostname = require("../hub-hostname-DAJXlOgV.js");
 const require_restream_intent = require("../restream-intent-7uDNqMKs.js");
 const require_retire_root_keys = require("../retire-root-keys-Csb8z2f3.js");
@@ -6129,6 +6129,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
@@ -6137,6 +6152,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 = require_dist.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
@@ -6218,6 +6269,13 @@ var ExportEngine = class {
 		}
 	}
 	async render(id) {
+		const existing = await getExportRecord(this.deps.state, id);
+		if (!existing) return;
+		const subject = require_dist.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
@@ -6246,6 +6304,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, require_dist.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, require_dist.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: require_dist.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, require_dist.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: require_dist.RECORDING_EXPORT_MAX_READ_BYTES
+				}
+			});
+			await this.fail(id, require_dist.clipExportFailure("too-large-to-transfer", `${bytes.byteLength} > ${require_dist.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, require_dist.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, require_dist.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(require_dist.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
@@ -6681,6 +6920,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 = require_dist.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
@@ -6708,6 +6963,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: require_dist.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, {
@@ -13496,6 +13764,581 @@ var PlacementService = class {
 	}
 };
 //#endregion
+//#region src/recorder/addon/videoclip-visits.ts
+/**
+* Videoclip visits — the grain a clip should have on an events-mode camera.
+*
+* Disk writes one fMP4 per ffmpeg roll (~8–12 s). The recorder calendar merges
+* only gaps ≤ 5 s, so a single pantry walk shows up as several availability
+* ranges with ~8 s GOP holes between them. Analytics then mints one 15 s clip
+* per motion heartbeat. A *visit* is the keep-window those fragments belong
+* to: cluster availability with {@link VISIT_MERGE_GAP_MS}, annotate with
+* overlapping events. No second copy of the media; the files stay the source
+* of truth.
+*/
+/** Synthetic event-id slot in `analytics:<start>:<end>:<id>` for a visit clip. */
+var VISIT_EVENT_ID = "visit";
+function clusterFootageVisits(ranges, gapMs = require_dist.VISIT_MERGE_GAP_MS) {
+	if (ranges.length === 0) return [];
+	const sorted = [...ranges].toSorted((a, b) => a.startMs - b.startMs);
+	const visits = [];
+	let pieces = [sorted[0]];
+	let endMs = sorted[0].endMs;
+	for (let i = 1; i < sorted.length; i++) {
+		const next = sorted[i];
+		if (next.startMs <= endMs + gapMs) {
+			pieces.push(next);
+			endMs = Math.max(endMs, next.endMs);
+			continue;
+		}
+		visits.push(finishVisit(pieces, endMs));
+		pieces = [next];
+		endMs = next.endMs;
+	}
+	visits.push(finishVisit(pieces, endMs));
+	return visits;
+}
+function finishVisit(pieces, endMs) {
+	const holes = [];
+	for (let i = 1; i < pieces.length; i++) {
+		const prevEnd = pieces[i - 1].endMs;
+		const nextStart = pieces[i].startMs;
+		if (nextStart > prevEnd) holes.push({
+			startMs: prevEnd,
+			endMs: nextStart
+		});
+	}
+	return {
+		startMs: pieces[0].startMs,
+		endMs,
+		ranges: pieces,
+		holes
+	};
+}
+var KIND_ORDER = [
+	"object",
+	"motion",
+	"audio"
+];
+function eventOverlapsVisit(event, visit, pad) {
+	if (event.timestamp >= visit.startMs && event.timestamp <= visit.endMs) return true;
+	const windowStart = event.timestamp - pad.preMs;
+	const windowEnd = event.timestamp + pad.postMs;
+	return windowStart < visit.endMs && windowEnd > visit.startMs;
+}
+function dominantKind(attached) {
+	for (const kind of KIND_ORDER) if (attached.some((a) => a.kind === kind)) return kind;
+	return "motion";
+}
+/**
+* The instant a recorded still can actually be decoded inside a visit: the
+* midpoint of its LONGEST contiguous range.
+*
+* NOT the midpoint of the visit. A visit spans its holes by construction (it is
+* ranges glued across gaps up to `VISIT_MERGE_GAP_MS`), so the naive midpoint
+* lands in dead air roughly as often as not and the recorder's still route
+* answers 204 for a visit with plenty of footage.
+*/
+function stillInstantMs(ranges) {
+	let best;
+	for (const range of ranges) if (best === void 0 || range.endMs - range.startMs > best.endMs - best.startMs) best = range;
+	if (best === void 0) return void 0;
+	return Math.floor((best.startMs + best.endMs) / 2);
+}
+/**
+* The distinct object classes attached to a visit, most frequent first,
+* capped at {@link MAX_CLIP_LABELS}. Empty when nothing classified overlapped
+* — the caller then omits the field so a motion/audio-only visit keeps its
+* kind label instead of carrying an empty array every consumer length-checks.
+*/
+function dominantLabels(attached) {
+	const counts = /* @__PURE__ */ new Map();
+	for (const a of attached) {
+		if (a.kind !== "object") continue;
+		const name = a.event.className;
+		if (typeof name !== "string" || name.length === 0) continue;
+		counts.set(name, (counts.get(name) ?? 0) + 1);
+	}
+	return [...counts.entries()].toSorted((x, y) => y[1] - x[1]).slice(0, 3).map(([name]) => name);
+}
+function visitsToClips(visits, events, pad, vouched) {
+	const tagged = [
+		...events.object.map((event) => ({
+			kind: "object",
+			event
+		})),
+		...events.motion.map((event) => ({
+			kind: "motion",
+			event
+		})),
+		...events.audio.map((event) => ({
+			kind: "audio",
+			event
+		}))
+	];
+	return visits.map((visit) => {
+		const attached = tagged.filter((t) => eventOverlapsVisit(t.event, visit, pad));
+		const kind = dominantKind(attached);
+		const withThumb = attached.find((a) => a.kind === kind && a.event.mediaUrl && vouched.has(a.event.id)) ?? attached.find((a) => a.event.mediaUrl && vouched.has(a.event.id));
+		const stillAtMs = stillInstantMs(visit.ranges);
+		const labels = dominantLabels(attached);
+		return {
+			id: `analytics:${visit.startMs}:${visit.endMs}:${VISIT_EVENT_ID}`,
+			source: "analytics",
+			kind,
+			timeRange: {
+				startMs: visit.startMs,
+				endMs: visit.endMs
+			},
+			...withThumb?.event.mediaUrl !== void 0 ? { thumbnail: withThumb.event.mediaUrl } : {},
+			...stillAtMs !== void 0 ? { stillAtMs } : {},
+			eventIds: attached.slice(0, 24).map((a) => a.event.id),
+			eventCount: attached.length,
+			holes: [...visit.holes],
+			...labels.length > 0 ? { labels } : {}
+		};
+	}).toSorted((a, b) => b.timeRange.startMs - a.timeRange.startMs);
+}
+//#endregion
+//#region src/recorder/addon/videoclips-provider.ts
+/**
+* Default `videoclips` provider — composes recorded footage visits with the
+* analytics event log. A clip is a time-WINDOW over existing footage, never a
+* separate file: `getClipPlayback` resolves to
+* `recording.getPlaybackManifest(startMs, endMs)`.
+*
+* When availability is present the grain is a *visit* (events-mode keep-window
+* clustered at `VISIT_MERGE_GAP_MS`), not one clip per motion heartbeat. The
+* clip id still encodes the window (`analytics:<startMs>:<endMs>:visit`) so
+* playback is self-contained. Without availability (or when that read fails)
+* the provider falls back to per-event padded windows.
+*
+* Pure helpers (`eventsToClips` / `clusterFootageVisits` / `clipIdFor` /
+* `parseClipId`) are unit-tested in isolation; the provider factory wires
+* injected fetch/resolve deps so the compose logic is testable without I/O.
+*/
+var SOURCE = "analytics";
+/** The addon that registers this provider — stamped on its source row. */
+var CLIP_SOURCE_ADDON_ID = "recorder";
+/**
+* Backstop on the ANNOTATION read — never on the clip list.
+*
+* A visit is annotated by every event inside it, so the clip `limit` must not
+* reach this fetch (one 615 visit legitimately spans 2 345 motion rows). This
+* bound exists only so a pathological camera-day cannot pull an unbounded page:
+* the store orders `timestamp DESC`, so a truncation drops the OLDEST rows and
+* the EARLIEST visits silently lose their annotations — which is why hitting it
+* is logged, per camera, rather than absorbed.
+*/
+var VISIT_EVENT_FETCH_LIMIT = 5e3;
+function clipIdFor(eventId, startMs, endMs) {
+	return `${SOURCE}:${startMs}:${endMs}:${eventId}`;
+}
+/** Parse a default-provider clip id back into its window + event id. Returns
+*  `null` for any id this provider did not mint (e.g. a native clip id). */
+function parseClipId(clipId) {
+	const parts = clipId.split(":");
+	if (parts.length < 4 || parts[0] !== SOURCE) return null;
+	const startMs = Number(parts[1]);
+	const endMs = Number(parts[2]);
+	if (!Number.isFinite(startMs) || !Number.isFinite(endMs)) return null;
+	const eventId = parts.slice(3).join(":");
+	if (!eventId) return null;
+	return {
+		eventId,
+		startMs,
+		endMs
+	};
+}
+/** Map per-kind events into time-ranged clips, newest-first. Pure. */
+function eventsToClips(events, pad, vouched) {
+	const make = (e, kind) => {
+		const startMs = e.timestamp - pad.preMs;
+		const endMs = e.timestamp + pad.postMs;
+		return {
+			id: clipIdFor(e.id, startMs, endMs),
+			source: SOURCE,
+			kind,
+			timeRange: {
+				startMs,
+				endMs
+			},
+			...e.mediaUrl !== void 0 && vouched.has(e.id) ? { thumbnail: e.mediaUrl } : {}
+		};
+	};
+	return [
+		...events.motion.map((e) => make(e, "motion")),
+		...events.object.map((e) => make(e, "object")),
+		...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) {
+	return [
+		...events.motion,
+		...events.object,
+		...events.audio
+	].map((e) => e.id);
+}
+/**
+* Resolve the event ids whose `mediaUrl` is backed by real bytes, mirroring
+* `resolveDefaultEventMedia`: the event's OWN media when it has any, else its
+* owning TRACK's. Up to four batched index reads — one PER EVENT KIND that has
+* any ids (D476: `motion` / `object` / `audio` are separate owner kinds now,
+* so a single combined read can no longer ask "does any of these ids own
+* media" — a motion id and an object id can be the same number post-D474 and
+* are answered by different rows) — plus the track fallback, only over the
+* object events the first pass did not already answer for (motion and audio
+* are trackless roots, so they never need it).
+*
+* THROWS on a failed read. The caller fails closed on the CLAIM and open on the
+* LIST; swallowing here would collapse those two opposite directions into one.
+*/
+async function resolveVouchedEvents(deviceId, events, fetchMediaOwners) {
+	const ownMedia = /* @__PURE__ */ new Set();
+	for (const ownerType of require_dist.EVENT_OWNER_TYPES) {
+		const ownerIds = events[ownerType].map((e) => e.id);
+		if (ownerIds.length === 0) continue;
+		const found = await fetchMediaOwners({
+			deviceId,
+			ownerKind: ownerType,
+			ownerIds
+		});
+		for (const id of found) ownMedia.add(id);
+	}
+	const residualTracks = [];
+	const seenTracks = /* @__PURE__ */ new Set();
+	for (const event of events.object) {
+		const trackId = event.trackId;
+		if (trackId === void 0 || ownMedia.has(event.id) || seenTracks.has(trackId)) continue;
+		seenTracks.add(trackId);
+		residualTracks.push(trackId);
+	}
+	const trackMedia = residualTracks.length === 0 ? /* @__PURE__ */ new Set() : await fetchMediaOwners({
+		deviceId,
+		ownerKind: "track",
+		ownerIds: residualTracks
+	});
+	const vouched = new Set(ownMedia);
+	for (const event of events.object) {
+		const trackId = event.trackId;
+		if (trackId !== void 0 && trackMedia.has(trackId)) vouched.add(event.id);
+	}
+	return vouched;
+}
+/** Keep only clips that actually touch the caller's window. The reads are
+*  widened by {@link leftOverhangMs}; the ANSWER is not. */
+function intersectsWindow(clip, since, until) {
+	return clip.timeRange.startMs < until && clip.timeRange.endMs > since;
+}
+/**
+* How far BEFORE `since` the event + availability reads must reach.
+*
+* A visit straddling `since` keeps its heartbeat rows and loses the transition
+* row — the only one that ever carries a snapshot — so the same visit shows a
+* picture or doesn't depending on where the operator scrolled. One wider range
+* scan on an indexed column buys a list that stops changing under the cursor.
+*/
+function leftOverhangMs(pad) {
+	return require_dist.VISIT_MERGE_GAP_MS + pad.preMs;
+}
+/** No events at all — what the degraded branch annotates its visits with. */
+var NO_EVENTS = {
+	motion: [],
+	object: [],
+	audio: []
+};
+function createVideoclipsProvider(deps) {
+	/**
+	* Cameras whose LAST `listClips` could not read the analytics event log, with
+	* the refusal verbatim.
+	*
+	* Not a cache of anybody else's fact (D224): it is this provider reporting
+	* what IT just did, refreshed on the same call that produces it and cleared
+	* by the next read that succeeds. `listSources` has no window argument and
+	* must not go and ask again — an extra events read on the listing path would
+	* be a second, disagreeing answer to the question `listClips` already
+	* answered.
+	*/
+	const eventsUnreachable = /* @__PURE__ */ new Map();
+	return {
+		listClips: async ({ deviceId, since, until, limit }) => {
+			const readSince = since - leftOverhangMs(deps.defaultPad);
+			let events;
+			try {
+				events = await deps.fetchEvents({
+					deviceId,
+					since: readSince,
+					until,
+					limit: deps.fetchAvailability ? VISIT_EVENT_FETCH_LIMIT : limit
+				});
+			} catch (err) {
+				return await listWithoutEvents(deps, eventsUnreachable, errMessage(err), {
+					deviceId,
+					since,
+					until,
+					readSince,
+					limit
+				});
+			}
+			eventsUnreachable.delete(deviceId);
+			warnOnTruncatedFetch(deps, deviceId, events);
+			let vouched = /* @__PURE__ */ new Set();
+			try {
+				vouched = await resolveVouchedEvents(deviceId, events, deps.fetchMediaOwners);
+			} catch (err) {
+				deps.logWarn?.("videoclips: media presence read failed — listing without thumbnails", {
+					deviceId,
+					events: allEventIds(events).length,
+					error: err instanceof Error ? err.message : String(err)
+				});
+			}
+			let clips = eventsToClips(events, deps.defaultPad, vouched);
+			if (deps.fetchAvailability) try {
+				clips = visitsToClips(clusterFootageVisits(await deps.fetchAvailability({
+					deviceId,
+					since: readSince,
+					until
+				}), require_dist.VISIT_MERGE_GAP_MS), events, deps.defaultPad, vouched);
+			} catch (err) {
+				deps.logWarn?.("videoclips: availability read failed — listing unfiltered", {
+					deviceId,
+					error: err instanceof Error ? err.message : String(err)
+				});
+			}
+			const inWindow = clips.filter((c) => intersectsWindow(c, since, until));
+			const answer = limit != null ? inWindow.slice(0, limit) : inWindow;
+			reportUnvouchedClips(deps, deviceId, answer);
+			return answer;
+		},
+		/**
+		* The one source this provider serves, on every camera: the hub's own
+		* analytics visits over recorded footage.
+		*
+		* Always `ok`, and that is not optimism — this source IS the process
+		* answering the call, so there is no reachability question to report. A
+		* read that fails INSIDE `listClips` degrades that list (and logs it); a
+		* source that cannot be reached at all is reported by the collection
+		* dispatcher, which is the only layer that can tell the difference.
+		* `label` is what the picker draws.
+		*/
+		listSources: async ({ deviceId }) => {
+			const outage = eventsUnreachable.get(deviceId);
+			return [{
+				source: SOURCE,
+				addonId: CLIP_SOURCE_ADDON_ID,
+				label: "CamStack recordings",
+				availability: outage === void 0 ? { state: "ok" } : {
+					state: "ok",
+					reason: `${EVENTS_UNREACHABLE_NOTICE} (${outage})`
+				}
+			}];
+		},
+		getClipPlayback: async ({ deviceId, clipId }) => {
+			const parsed = parseClipId(clipId);
+			if (!parsed) throw new Error(`videoclips: unrecognized clipId "${clipId}"`);
+			return {
+				...await deps.resolvePlayback({
+					deviceId,
+					startMs: parsed.startMs,
+					endMs: parsed.endMs
+				}),
+				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.`);
+		}
+	};
+}
+/** What the source row says while the event log is down. */
+var EVENTS_UNREACHABLE_NOTICE = "The analytics event log could not be read on the last listing — these clips are recorded footage only, with no labels, stills or event counts";
+function errMessage(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+/**
+* Footage present, EVENTS unreachable — the mirror of the two degradations
+* this provider already had, and the one that could not happen while a single
+* addon held both halves (D560).
+*
+* A visit is a window over recorded footage; the events only ANNOTATE it. So
+* when availability answers, the visits are still real and still playable —
+* their ids encode the window — and the honest answer is that list without its
+* annotations. An availability that answered `[]` yields an empty list that is
+* TRUE about footage: with availability present a clip only ever comes from a
+* recorded range, so it is the same answer a successful events read would have
+* given.
+*
+* Without availability (absent, or its read failed too) the clips ARE the
+* events, so there is nothing left that is true to say. That is a REFUSAL
+* naming both reads — never an empty list, which reads as "this camera has no
+* recordings".
+*/
+async function listWithoutEvents(deps, eventsUnreachable, reason, window) {
+	const { deviceId, since, until, readSince, limit } = window;
+	const fetchAvailability = deps.fetchAvailability;
+	if (fetchAvailability === void 0) {
+		eventsUnreachable.set(deviceId, reason);
+		throw new Error(`videoclips: the analytics event log is unreachable for device ${deviceId} (${reason}) and this source lists no recorded footage — refusing rather than answering an empty list`);
+	}
+	let ranges;
+	try {
+		ranges = await fetchAvailability({
+			deviceId,
+			since: readSince,
+			until
+		});
+	} catch (err) {
+		eventsUnreachable.set(deviceId, reason);
+		throw new Error(`videoclips: neither read answered for device ${deviceId} — events: ${reason}; footage: ${errMessage(err)}. Refusing rather than answering an empty list.`);
+	}
+	eventsUnreachable.set(deviceId, reason);
+	deps.logWarn?.("videoclips: event log unreachable — listing the recorded footage visits without their events", {
+		deviceId,
+		error: reason,
+		ranges: ranges.length
+	});
+	const clips = visitsToClips(clusterFootageVisits(ranges, require_dist.VISIT_MERGE_GAP_MS), NO_EVENTS, deps.defaultPad, /* @__PURE__ */ new Set()).filter((clip) => intersectsWindow(clip, since, until));
+	return limit != null ? clips.slice(0, limit) : clips;
+}
+/** The annotation backstop biting is a SILENT loss of the earliest visits'
+*  events — say so, per camera, instead of shipping a thinner list. */
+function warnOnTruncatedFetch(deps, deviceId, events) {
+	if (!deps.fetchAvailability) return;
+	const truncated = [
+		"motion",
+		"object",
+		"audio"
+	].filter((kind) => events[kind].length >= VISIT_EVENT_FETCH_LIMIT);
+	if (truncated.length === 0) return;
+	deps.logWarn?.("videoclips: annotation fetch truncated — earliest visits lose their events", {
+		deviceId,
+		kinds: truncated,
+		limit: VISIT_EVENT_FETCH_LIMIT
+	});
+}
+/** The operator's acceptance criterion as a number: a rising count on one
+*  camera is its motion-snapshot capturer failing, not a quiet day. */
+function reportUnvouchedClips(deps, deviceId, clips) {
+	const clipsWithoutStill = clips.filter((c) => c.thumbnail === void 0).length;
+	if (clipsWithoutStill === 0) return;
+	deps.logInfo?.("videoclips: visit has no vouched still", {
+		deviceId,
+		clipsWithoutStill,
+		clips: clips.length
+	});
+}
+//#endregion
+//#region src/recorder/addon/videoclips-shared.ts
+/** Stringify the numeric event ids of one bucket. Lossless. */
+function toEventLike(events) {
+	return events.map((e) => ({
+		...e,
+		id: String(e.id)
+	}));
+}
+//#endregion
+//#region src/recorder/addon/videoclips-wiring.ts
+/**
+* The `videoclips` source over THIS addon's archive — the deps half.
+*
+* The composer (`videoclips-provider.ts`, `videoclip-visits.ts`) is unchanged
+* and moved here verbatim from `addon-post-analysis`: a clip is still a time
+* WINDOW over recorded footage, visits are still clustered at
+* `VISIT_MERGE_GAP_MS`, and `getClipPlayback` still resolves through
+* `recording.getPlaybackManifest`. What moved is WHO registers it — the addon
+* that owns the footage, not one that borrowed it (D560).
+*
+* All four reads go over `ctx.api`, the recorder's own two included. That is
+* not laziness:
+*
+*   - `recorder` is `placement: 'any-node'`, so several nodes register this
+*     capability and the hub's collection dispatcher resolves the binding to
+*     ONE of them (`addonIdentityOf` strips the `@<nodeId>`). That registration
+*     is not necessarily the node holding this camera's segments.
+*   - `ctx.api.recording.*` is device-scoped and routes to the node that IS
+*     holding them. A short cut to the local `RecordingProvider` would answer a
+*     camera recorded on little-unraid out of the hub's empty index — an empty
+*     clip list on a camera with weeks of footage, which is the exact
+*     misreading this whole line of work exists to end.
+*
+* The events arriving over a process boundary is the new failure mode, and the
+* provider answers it per branch — see `listWithoutEvents`.
+*/
+/**
+* Every log line about a camera carries `tags: { deviceId }`, always the
+* numeric id. A miss rate or a media gap is always asked per camera, and a line
+* that omits the tag cannot answer it.
+*/
+function stamp(logger, level) {
+	return (message, meta) => {
+		logger[level](message, {
+			tags: { deviceId: Number(meta["deviceId"]) },
+			meta
+		});
+	};
+}
+function createRecorderVideoclipsProvider(deps) {
+	const api = deps.api;
+	return createVideoclipsProvider({
+		defaultPad: require_dist.EVENT_PAD_MS,
+		fetchEvents: async ({ deviceId, since, until, limit }) => {
+			const query = {
+				deviceId,
+				since,
+				until,
+				limit,
+				projection: "slim"
+			};
+			const [motion, object, audio] = await Promise.all([
+				api.pipelineAnalytics.getMotionEvents.query(query),
+				api.pipelineAnalytics.getObjectEvents.query(query),
+				api.pipelineAnalytics.getAudioEvents.query(query)
+			]);
+			return {
+				motion: toEventLike(motion),
+				object: toEventLike(object),
+				audio: toEventLike(audio)
+			};
+		},
+		fetchMediaOwners: async ({ deviceId, ownerKind, ownerIds }) => new Set(await api.pipelineAnalytics.ownersWithMedia.query({
+			deviceId,
+			ownerKind,
+			ownerIds
+		})),
+		fetchAvailability: async ({ deviceId, since, until }) => (await api.recording.getAvailability.query({
+			deviceId,
+			fromMs: since,
+			toMs: until
+		})).ranges,
+		logWarn: stamp(deps.logger, "warn"),
+		logInfo: stamp(deps.logger, "info"),
+		resolvePlayback: async ({ deviceId, startMs, endMs }) => {
+			const manifest = await api.recording.getPlaybackManifest.query({
+				deviceId,
+				fromMs: startMs,
+				toMs: endMs
+			});
+			if (manifest.playbackUrl == null) throw new Error(`videoclips: no footage for clip window [${String(startMs)},${String(endMs)}] on device ${String(deviceId)}`);
+			return {
+				playbackUrl: manifest.playbackUrl,
+				...manifest.playbackEndpoints === void 0 ? {} : { playbackEndpoints: [...manifest.playbackEndpoints] }
+			};
+		}
+	});
+}
+//#endregion
 //#region src/recorder/band-engine.ts
 function toMin(hhmm) {
 	const [h, m] = hhmm.split(":");
@@ -16721,6 +17564,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";
@@ -16748,12 +17666,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);
@@ -16762,37 +17674,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(require_dist.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(require_dist.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(require_dist.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 = require_dist.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),
@@ -18567,7 +19575,19 @@ var RecorderV2Addon = class extends require_dist.BaseAddon {
 			outPath: exportOutPath,
 			statBytes: async (p) => (await node_fs.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 node_fs.promises.mkdir(node_path.default.dirname(p), { recursive: true });
+				await node_fs.promises.writeFile(p, bytes);
+			}
 		});
 		const exportProvider = buildRecordingExportProvider({
 			state: exportsState,
@@ -18576,6 +19596,7 @@ var RecorderV2Addon = class extends require_dist.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: () => (0, node_crypto.randomUUID)(),
 			createdBy: () => "operator",
@@ -18653,6 +19674,13 @@ var RecorderV2Addon = class extends require_dist.BaseAddon {
 				capability: require_dist.recordingCapability,
 				provider: recordingProvider
 			},
+			{
+				capability: require_dist.videoclipsCapability,
+				provider: createRecorderVideoclipsProvider({
+					api: this.ctx.api,
+					logger: this.ctx.logger
+				})
+			},
 			{
 				capability: require_dist.storageEvictableCapability,
 				provider: evictableProvider