@camstack/addon-pipeline 1.1.60 → 1.1.61

package/dist/recorder/index.mjs

@@ -1,11 +1,12 @@
-import { A as recordingCapability, D as nodePin, L as errMsg, N as storageEvictableCapability, R as BaseAddon, T as migrateConfigToBands, U as hydrateSchema, V as DeviceType, W as isEvent, Y as selectAssignedProfileSlots, at as record, ct as EventCategory, j as resolveScrubThumbnailGeometry, ot as string, s as EVENT_PAD_MS, u as RecordingConfigSchema } from "../dist-CcqqznPf.mjs";
+import { B as BaseAddon, E as migrateConfigToBands, F as storageEvictableCapability, G as hydrateSchema, K as isEvent, M as recordingExportCapability, N as resolveScrubThumbnailGeometry, O as nodePin, U as DeviceType, Z as selectAssignedProfileSlots, ct as string, d as RecordingConfigSchema, j as recordingCapability, l as ExportRecordSchema, s as EVENT_PAD_MS, st as record, ut as EventCategory, z as errMsg } from "../dist-D16_dBsr.mjs";
 import { n as computeSheetGeometry, r as resolveHubHostname, t as allTilePlacements } from "../sheet-geometry-DcpuGTCm.mjs";
-import { t as createFileDataPlaneHandler } from "../model-download-service-Cp9f4dk6-0wh7OK3s.mjs";
+import { n as createFileDataPlaneHandler, s as parseRangeHeader, t as contentTypeFor } from "../model-download-service-Cp9f4dk6-CwUb5v3Y.mjs";
 import { spawn } from "node:child_process";
 import sharp from "sharp";
-import { promises } from "node:fs";
+import { createReadStream, promises } from "node:fs";
 import path from "node:path";
 import { tmpdir } from "node:os";
+import { randomUUID } from "node:crypto";
 //#region src/recorder/segment-path.ts
 function segmentRelPath(deviceId, profile, startMs, durMs, bytes) {
 	if (profile.includes("/")) throw new Error(`segmentRelPath: profile must not contain '/': ${profile}`);
@@ -872,6 +873,15 @@ function noPlayback(deviceId) {
 function playbackDirFor(dataDir, deviceId) {
 	return path.join(dataDir, "playback", String(deviceId));
 }
+/**
+* Absolute path of ONE profile's variant playlist inside the playback dir.
+* `buildPlaybackManifest` writes `<profile>.m3u8` next to the master whenever
+* that profile has overlapping footage — the export engine renders this variant
+* (a single-profile source) rather than the multi-variant master.
+*/
+function playbackVariantPlaylistPath(dataDir, deviceId, profile) {
+	return path.join(playbackDirFor(dataDir, deviceId), `${profile}.m3u8`);
+}
 /** Prefix window the CODECS probe reads — the fragment's moov (with its
 *  avcC/hvcC) leads the file and is ~1-2KB, so 64KB is a generous bound. */
 var PROBE_PREFIX_BYTES = 65536;
@@ -1135,6 +1145,407 @@ function buildRecordingProvider(deps) {
 	};
 }
 //#endregion
+//#region src/recorder/addon/export-store.ts
+/**
+* Recording-export persistence for the recorder addon.
+*
+* Every export job/history row lives in ONE addon-store blob keyed by export
+* id. The whole Zod-validated blob round-trips on every read/write via a
+* {@link DurableState} handle (same pattern as `config-store.ts`), so no field
+* is silently dropped on persist. History rows are never removed by the system
+* (audit) — `deleteExport`/janitor flip `state` and clear the file, keeping the
+* row. A corrupt blob reads back as EMPTY rather than crashing boot.
+*/
+/**
+* The addon-store key holding the exportId → ExportRecord map. Production
+* builds the durable handle via `BaseAddon.state(RECORDING_EXPORTS_KEY,
+* RecordingExportsBlobSchema, {})`; the pure functions below take that handle,
+* so this module never touches the @internal raw addon-store primitive.
+*/
+var RECORDING_EXPORTS_KEY = "recordingExports";
+/** Persisted shape: export id → full ExportRecord. */
+var RecordingExportsBlobSchema = record(string(), ExportRecordSchema);
+/** Read every persisted export row, keyed by export id. */
+async function readExports(state) {
+	const blob = await state.get();
+	return new Map(Object.entries(blob));
+}
+/** Insert or replace one export row. Validates at the boundary. Returns it. */
+async function upsertExport(state, record) {
+	const validated = ExportRecordSchema.parse(record);
+	const map = await readExports(state);
+	map.set(validated.id, validated);
+	await state.set(Object.fromEntries(map));
+	return validated;
+}
+/**
+* Shallow-merge a patch into one export row and persist. Returns the merged
+* record, or null when the id is unknown.
+*/
+async function patchExport(state, id, patch) {
+	const map = await readExports(state);
+	const existing = map.get(id);
+	if (!existing) return null;
+	const merged = ExportRecordSchema.parse({
+		...existing,
+		...patch
+	});
+	map.set(id, merged);
+	await state.set(Object.fromEntries(map));
+	return merged;
+}
+/** Read one export row by id, or null. */
+async function getExportRecord(state, id) {
+	return (await readExports(state)).get(id) ?? null;
+}
+/**
+* List export rows, newest-first, optionally scoped to one device.
+*/
+async function listExportsFor(state, deviceId) {
+	return [...(await readExports(state)).values()].filter((r) => deviceId === void 0 || r.deviceId === deviceId).toSorted((a, b) => b.createdAt - a.createdAt);
+}
+//#endregion
+//#region src/recorder/addon/export-ffmpeg-args.ts
+/** Widest [min,max] speed a single ffmpeg `atempo` filter accepts. Outside this
+*  band audio is dropped rather than chained (kept simple + predictable). */
+var ATEMPO_MIN = .5;
+var ATEMPO_MAX = 2;
+var X264 = [
+	"-c:v",
+	"libx264",
+	"-preset",
+	"veryfast",
+	"-pix_fmt",
+	"yuv420p"
+];
+var FASTSTART = ["-movflags", "+faststart"];
+/** Build the ffmpeg argv for one export render. */
+function buildExportArgs(input) {
+	const { inputPlaylist, outPath, options } = input;
+	const inArgs = ["-i", inputPlaylist];
+	if (options.timelapse) {
+		const everySec = options.timelapse.everyMs / 1e3;
+		const fps = options.timelapse.outputFps ?? 30;
+		return [
+			...inArgs,
+			"-vf",
+			`select='not(mod(t,${everySec}))',setpts=N/FRAME_RATE/TB,fps=${fps}`,
+			"-an",
+			...X264,
+			...FASTSTART,
+			outPath
+		];
+	}
+	const speed = options.speed ?? 1;
+	if (speed === 1) return [
+		...inArgs,
+		"-map",
+		"0",
+		"-c",
+		"copy",
+		...options.includeAudio ? [] : ["-an"],
+		...FASTSTART,
+		outPath
+	];
+	const keepAudio = options.includeAudio && speed >= ATEMPO_MIN && speed <= ATEMPO_MAX;
+	return [
+		...inArgs,
+		"-filter:v",
+		`setpts=PTS/${speed}`,
+		...keepAudio ? [
+			"-filter:a",
+			`atempo=${speed}`,
+			"-c:a",
+			"aac"
+		] : ["-an"],
+		...X264,
+		...FASTSTART,
+		outPath
+	];
+}
+//#endregion
+//#region src/recorder/addon/export-engine.ts
+/**
+* Render engine for recording exports.
+*
+* A FIFO queue with ONE concurrent ffmpeg render (exports are heavy; serialising
+* protects the recording node). Each job: resolve the range's local HLS master
+* playlist → build argv (`buildExportArgs`) → spawn ffmpeg → parse `time=` from
+* stderr for progress → on exit 0 stat the file and mark `ready`; on non-zero
+* mark `failed` and remove the partial. `cancel` SIGKILLs an in-flight render.
+* State transitions patch the DurableState store and emit telemetry events.
+*
+* Unlike `SegmentWriter` there is NO auto-restart — a render runs once; boot
+* re-queue of interrupted jobs is the provider's concern.
+*/
+var STDERR_TAIL_LINES$1 = 12;
+var TIME_RE = /time=(\d+):(\d+):(\d+(?:\.\d+)?)/;
+/** Expected OUTPUT duration (seconds) for progress scaling. */
+function expectedOutSeconds(rec) {
+	const rangeSec = Math.max(.001, (rec.toMs - rec.fromMs) / 1e3);
+	if (rec.options.timelapse) {
+		const everySec = rec.options.timelapse.everyMs / 1e3;
+		const fps = rec.options.timelapse.outputFps ?? 30;
+		return Math.max(.001, rangeSec / everySec / fps);
+	}
+	return rangeSec / (rec.options.speed ?? 1);
+}
+var ExportEngine = class {
+	deps;
+	queue = [];
+	activeId = null;
+	activeProc = null;
+	cancelled = /* @__PURE__ */ new Set();
+	constructor(deps) {
+		this.deps = deps;
+	}
+	/** Queue a persisted `queued` record for rendering. */
+	enqueue(id) {
+		if (this.queue.includes(id) || this.activeId === id) return;
+		this.queue.push(id);
+		this.pump();
+	}
+	/** Abort a queued or in-flight render. */
+	async cancel(id) {
+		this.cancelled.add(id);
+		const idx = this.queue.indexOf(id);
+		if (idx >= 0) this.queue.splice(idx, 1);
+		if (this.activeId === id && this.activeProc) try {
+			this.activeProc.kill("SIGKILL");
+		} catch {}
+		else if (idx >= 0) await this.fail(id, "cancelled");
+	}
+	async pump() {
+		if (this.activeId) return;
+		const id = this.queue.shift();
+		if (!id) return;
+		if (this.cancelled.has(id)) {
+			this.cancelled.delete(id);
+			await this.fail(id, "cancelled");
+			this.pump();
+			return;
+		}
+		this.activeId = id;
+		try {
+			await this.render(id);
+		} catch (err) {
+			await this.fail(id, err instanceof Error ? err.message : String(err));
+		} finally {
+			this.activeId = null;
+			this.activeProc = null;
+			this.pump();
+		}
+	}
+	async render(id) {
+		const rec = await patchExport(this.deps.state, id, {
+			state: "rendering",
+			progressPct: 0
+		});
+		if (!rec) return;
+		const playlist = await this.deps.resolvePlaylist(rec);
+		if (!playlist) {
+			await this.fail(id, "no footage for range");
+			return;
+		}
+		const outPath = this.deps.outPath(rec);
+		const args = buildExportArgs({
+			inputPlaylist: playlist,
+			outPath,
+			options: rec.options
+		});
+		const totalSec = expectedOutSeconds(rec);
+		await new Promise((resolve) => {
+			const proc = this.deps.spawn(this.deps.ffmpegPath ?? "ffmpeg", args);
+			this.activeProc = proc;
+			const stderrTail = [];
+			proc.stderr?.on("data", (chunk) => {
+				const text = chunk instanceof Buffer ? chunk.toString("utf8") : String(chunk);
+				for (const line of text.split("\n")) {
+					const trimmed = line.trim();
+					if (trimmed) {
+						stderrTail.push(trimmed);
+						if (stderrTail.length > STDERR_TAIL_LINES$1) stderrTail.shift();
+					}
+					const m = TIME_RE.exec(line);
+					if (m) {
+						const sec = Number(m[1]) * 3600 + Number(m[2]) * 60 + Number(m[3]);
+						const pct = Math.min(99, Math.round(sec / totalSec * 100));
+						patchExport(this.deps.state, id, { progressPct: pct });
+						this.deps.emit(EventCategory.RecordingExportProgress, {
+							exportId: id,
+							progressPct: pct
+						});
+					}
+				}
+			});
+			proc.on("exit", (code) => {
+				this.activeProc = null;
+				this.finish(id, typeof code === "number" ? code : null, outPath, stderrTail).then(resolve);
+			});
+		});
+	}
+	async finish(id, code, outPath, stderrTail) {
+		if (this.cancelled.has(id)) {
+			this.cancelled.delete(id);
+			await this.deps.removeFile(outPath);
+			await this.fail(id, "cancelled");
+			return;
+		}
+		if (code !== 0) {
+			await this.deps.removeFile(outPath);
+			await this.fail(id, `ffmpeg exited ${code}: ${stderrTail.join(" | ")}`);
+			return;
+		}
+		let bytes = 0;
+		try {
+			bytes = await this.deps.statBytes(outPath);
+		} catch (err) {
+			await this.fail(id, err instanceof Error ? err.message : String(err));
+			return;
+		}
+		await patchExport(this.deps.state, id, {
+			state: "ready",
+			progressPct: 100,
+			fileBytes: bytes,
+			error: null
+		});
+		this.deps.emit(EventCategory.RecordingExportCompleted, {
+			exportId: id,
+			fileBytes: bytes
+		});
+	}
+	async fail(id, error) {
+		await patchExport(this.deps.state, id, {
+			state: "failed",
+			progressPct: null,
+			error
+		});
+		this.deps.emit(EventCategory.RecordingExportFailed, {
+			exportId: id,
+			error
+		});
+	}
+};
+//#endregion
+//#region src/recorder/addon/recording-export-provider.ts
+/**
+* True when at least one indexed segment overlaps `[fromMs, toMs)`. Mirrors the
+* `buildPlaybackManifest` overlap idiom: a segment `[startMs, startMs+durMs)`
+* overlaps the window iff it starts before the window ends AND ends after the
+* window starts.
+*/
+function hasFootage(index, deviceId, profile, fromMs, toMs) {
+	return index.segments(deviceId, profile).some((s) => s.startMs < toMs && s.startMs + s.durMs > fromMs);
+}
+/** Load a record or throw a clear NOT_FOUND-style error. */
+async function requireRecord(state, exportId) {
+	const rec = await getExportRecord(state, exportId);
+	if (!rec) throw new Error(`recordingExport: unknown export "${exportId}"`);
+	return rec;
+}
+/** Build the `recordingExport` provider over the injected deps. */
+function buildRecordingExportProvider(deps) {
+	return {
+		createExport: async ({ deviceId, profile, fromMs, toMs, options }) => {
+			if (!(fromMs < toMs)) throw new Error(`recordingExport: invalid range ${fromMs}..${toMs}`);
+			if (!hasFootage(deps.index, deviceId, profile, fromMs, toMs)) throw new Error(`recordingExport: no footage for ${deviceId}/${profile} in ${fromMs}..${toMs}`);
+			const now = deps.now();
+			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);
+			return saved;
+		},
+		listExports: ({ deviceId }) => listExportsFor(deps.state, deviceId),
+		getExport: ({ exportId }) => requireRecord(deps.state, exportId),
+		cancelExport: async ({ exportId }) => {
+			const existing = await requireRecord(deps.state, exportId);
+			await deps.engine.cancel(exportId);
+			return await getExportRecord(deps.state, exportId) ?? existing;
+		},
+		deleteExport: async ({ exportId }) => {
+			const existing = await requireRecord(deps.state, exportId);
+			await deps.removeFile(deps.outPath(existing));
+			return await patchExport(deps.state, exportId, {
+				state: "deleted",
+				fileBytes: null
+			}) ?? existing;
+		},
+		getDownloadUrl: async ({ exportId }) => {
+			await requireRecord(deps.state, exportId);
+			const url = deps.downloadUrlFor(exportId);
+			return {
+				url,
+				endpoints: [url]
+			};
+		}
+	};
+}
+//#endregion
+//#region src/recorder/addon/export-janitor.ts
+/** States whose file still exists on disk and can be reclaimed. */
+var LIVE_STATES = new Set(["ready"]);
+/**
+* Delete the files of every export past `expiresAt` and flip them to `expired`
+* (row kept). Only `ready` exports hold a file; `queued`/`rendering` are left
+* for the engine, terminal rows are skipped. Returns the expired ids.
+*/
+async function sweepExpiredExports(now, deps) {
+	const rows = await listExportsFor(deps.state);
+	const expired = [];
+	for (const rec of rows) {
+		if (!LIVE_STATES.has(rec.state)) continue;
+		if (rec.expiresAt > now) continue;
+		try {
+			await deps.removeFile(deps.outPath(rec));
+		} catch {}
+		await patchExport(deps.state, rec.id, {
+			state: "expired",
+			fileBytes: null
+		});
+		expired.push(rec.id);
+	}
+	return { expired };
+}
+/**
+* Record a completed download. Stamps `downloadedAt`; when the export is
+* `deleteAfterDownload`, removes the file after `graceMs` (protects immediate
+* client retries) and flips to `deleted`. `scheduleDelete` is injected so the
+* caller controls timer semantics (real setTimeout in prod, immediate in test).
+*/
+async function markDownloaded(id, now, deps, scheduleDelete, graceMs) {
+	const rec = await patchExport(deps.state, id, { downloadedAt: now });
+	if (!rec || !rec.deleteAfterDownload) return;
+	scheduleDelete(() => {
+		(async () => {
+			const current = (await listExportsFor(deps.state)).find((r) => r.id === id);
+			if (!current || current.state !== "ready") return;
+			try {
+				await deps.removeFile(deps.outPath(current));
+			} catch {}
+			await patchExport(deps.state, id, {
+				state: "deleted",
+				fileBytes: null
+			});
+		})();
+	}, graceMs);
+}
+//#endregion
 //#region src/recorder/addon/roots.ts
 /**
 * Storage-root resolution + boot hydrate for the recorder addon.
@@ -3052,6 +3463,14 @@ var MARKER_PAD_POST_MS = EVENT_PAD_MS.postMs;
 *  form the hub reverse-proxy client path `/addon/recorder/playback`. */
 var RECORDER_ADDON_ID = "recorder";
 var PLAYBACK_PREFIX = "playback";
+/** Data-plane prefix for export MP4 downloads → `/addon/recorder/exports/<id>.mp4`. */
+var EXPORTS_PREFIX = "exports";
+/** How often the export janitor sweeps expired exports. */
+var EXPORT_SWEEP_INTERVAL_MS = 5 * 6e4;
+/** Grace after a completed download before a `deleteAfterDownload` file is removed. */
+var EXPORT_DELETE_GRACE_MS = 6e4;
+/** Only `.mp4` export ids matching this shape are servable (traversal guard). */
+var EXPORT_FILENAME_RE = /^([A-Za-z0-9][A-Za-z0-9_-]*)\.mp4$/;
 /** Narrows the `unknown` extras `SegmentStore`'s logger contract accepts down
 *  to the structured `{ tags, error }` shape the device-scoped call sites
 *  (stat/relocate failures) pass — as opposed to the raw caught error most
@@ -3079,6 +3498,10 @@ var RecorderV2Addon = class extends BaseAddon {
 	playbackBaseUrl = null;
 	/** Scrub-thumbnail service (sink + data-plane + backfill). Null until started. */
 	thumbnailService = null;
+	/** Render engine for recording exports. Null on non-recording nodes. */
+	exportEngine = null;
+	/** Periodic export-expiry sweep timer. Cleared on shutdown. */
+	exportSweepTimer = null;
 	constructor() {
 		super({ ...DEFAULT_CONFIG });
 	}
@@ -3156,7 +3579,7 @@ var RecorderV2Addon = class extends BaseAddon {
 			}),
 			brokerCall: makeBrokerCall(brokerHandle)
 		});
-		const recordingProvider = buildRecordingProvider({
+		const recordingDeps = {
 			index: this.index,
 			segmentStore: this.segmentStore,
 			nodeId: this.nodeId,
@@ -3177,11 +3600,42 @@ var RecorderV2Addon = class extends BaseAddon {
 					return true;
 				}
 			}
-		});
+		};
+		const recordingProvider = buildRecordingProvider(recordingDeps);
 		const evictableProvider = new StorageEvictableProvider({
 			index: this.index,
 			store: this.segmentStore
 		});
+		const exportsState = this.exportsStore();
+		const exportCodecCache = /* @__PURE__ */ new Map();
+		const exportOutPath = (rec) => path.join(this.ctx.dataDir, EXPORTS_PREFIX, String(rec.deviceId), `${rec.id}.mp4`);
+		const removeExportFile = async (p) => {
+			await promises.rm(p, { force: true });
+		};
+		this.exportEngine = new ExportEngine({
+			spawn,
+			logger: this.ctx.logger.child("export"),
+			state: exportsState,
+			resolvePlaylist: async (rec) => {
+				if ((await buildPlaybackManifest(recordingDeps, exportCodecCache, rec.deviceId, rec.fromMs, rec.toMs)).localMasterPath === null) return null;
+				return playbackVariantPlaylistPath(this.ctx.dataDir, rec.deviceId, rec.profile);
+			},
+			outPath: exportOutPath,
+			statBytes: async (p) => (await promises.stat(p)).size,
+			removeFile: removeExportFile,
+			emit: (category, data) => this.emitExportEvent(category, data)
+		});
+		const exportProvider = buildRecordingExportProvider({
+			state: exportsState,
+			engine: this.exportEngine,
+			index: this.index,
+			now: () => Date.now(),
+			newId: () => randomUUID(),
+			createdBy: () => "operator",
+			outPath: exportOutPath,
+			removeFile: removeExportFile,
+			downloadUrlFor: (id) => `/addon/${RECORDER_ADDON_ID}/${EXPORTS_PREFIX}/${id}.mp4`
+		});
 		try {
 			const handler = createFileDataPlaneHandler({ getRoots: () => this.playbackRoots() });
 			const served = await this.ctx.dataPlane?.serve({
@@ -3197,6 +3651,19 @@ var RecorderV2Addon = class extends BaseAddon {
 		} catch (err) {
 			this.ctx.logger.warn("recorder playback data-plane failed to serve", { meta: { error: errMsg(err) } });
 		}
+		try {
+			const served = await this.ctx.dataPlane?.serve({
+				prefix: EXPORTS_PREFIX,
+				access: "authenticated",
+				handler: (req, res) => this.serveExportDownload(exportsState, exportOutPath, req, res)
+			});
+			this.ctx.logger.info("recorder exports data-plane served", { meta: {
+				clientBase: served ? `/addon/${RECORDER_ADDON_ID}/${EXPORTS_PREFIX}` : "(no dataPlane facility)",
+				internal: served?.baseUrl
+			} });
+		} catch (err) {
+			this.ctx.logger.warn("recorder exports data-plane failed to serve", { meta: { error: errMsg(err) } });
+		}
 		await this.ensureThumbnailService().serveEarly();
 		this.ctx.logger.info("recorder addon started (continuous write path active)", {
 			tags: { nodeId: this.nodeId },
@@ -3205,13 +3672,20 @@ var RecorderV2Addon = class extends BaseAddon {
 				watchIntervalMs: this.config.watchIntervalMs
 			}
 		});
-		return { providers: [{
-			capability: recordingCapability,
-			provider: recordingProvider
-		}, {
-			capability: storageEvictableCapability,
-			provider: evictableProvider
-		}] };
+		return { providers: [
+			{
+				capability: recordingCapability,
+				provider: recordingProvider
+			},
+			{
+				capability: storageEvictableCapability,
+				provider: evictableProvider
+			},
+			{
+				capability: recordingExportCapability,
+				provider: exportProvider
+			}
+		] };
 	}
 	async onShutdown() {
 		this.eventUnsub?.();
@@ -3221,6 +3695,11 @@ var RecorderV2Addon = class extends BaseAddon {
 		this.segmentStore = null;
 		await this.thumbnailService?.stop();
 		this.thumbnailService = null;
+		if (this.exportSweepTimer !== null) {
+			clearInterval(this.exportSweepTimer);
+			this.exportSweepTimer = null;
+		}
+		this.exportEngine = null;
 	}
 	/**
 	* Boot hydrate: once the hub is reachable (`ctx.api.*` safe), resolve the
@@ -3278,6 +3757,39 @@ var RecorderV2Addon = class extends BaseAddon {
 		} catch (err) {
 			this.ctx.logger.warn("recorder: thumbnail service start failed", { meta: { error: errMsg(err) } });
 		}
+		await this.bootstrapExports();
+	}
+	/**
+	* Resume interrupted exports and arm the expiry sweep. A row left `rendering`
+	* by a crash/restart has no live ffmpeg, so demote it to `queued` and re-enqueue
+	* it alongside any still-`queued` rows. The sweep runs immediately then on an
+	* interval; both are best-effort (a failure never blocks boot).
+	*/
+	async bootstrapExports() {
+		const engine = this.exportEngine;
+		if (!engine) return;
+		const state = this.exportsStore();
+		try {
+			for (const rec of await listExportsFor(state)) {
+				if (rec.state === "rendering") await patchExport(state, rec.id, {
+					state: "queued",
+					progressPct: null
+				});
+				if (rec.state === "queued" || rec.state === "rendering") engine.enqueue(rec.id);
+			}
+		} catch (err) {
+			this.ctx.logger.warn("recorder: export boot re-queue failed", { meta: { error: errMsg(err) } });
+		}
+		if (this.exportSweepTimer === null) {
+			const sweep = () => {
+				sweepExpiredExports(Date.now(), this.exportJanitorDeps()).catch((err) => {
+					this.ctx.logger.warn("recorder: export expiry sweep failed", { meta: { error: errMsg(err) } });
+				});
+			};
+			sweep();
+			this.exportSweepTimer = setInterval(sweep, EXPORT_SWEEP_INTERVAL_MS);
+			this.exportSweepTimer.unref?.();
+		}
 	}
 	/** Construct the thumbnail service once — every dep is a lazy closure, so
 	*  construction is safe in `onInitialize` (before locations resolve). */
@@ -3406,6 +3918,121 @@ var RecorderV2Addon = class extends BaseAddon {
 	configStore() {
 		return this.state(RECORDING_CONFIGS_KEY, RecordingConfigsBlobSchema, {});
 	}
+	/** Durable handle over the exportId→ExportRecord blob (same `BaseAddon.state()`
+	*  wrapper as the config store). */
+	exportsStore() {
+		return this.state(RECORDING_EXPORTS_KEY, RecordingExportsBlobSchema, {});
+	}
+	/** Retention deps shared by the sweep and the download-complete hook. */
+	exportJanitorDeps() {
+		return {
+			state: this.exportsStore(),
+			outPath: (rec) => path.join(this.ctx.dataDir, EXPORTS_PREFIX, String(rec.deviceId), `${rec.id}.mp4`),
+			removeFile: async (p) => {
+				await promises.rm(p, { force: true });
+			}
+		};
+	}
+	/** Emit an export telemetry event through the addon event bus (untyped
+	*  category — the export categories are telemetry, not in the typed catalog). */
+	emitExportEvent(category, data) {
+		const source = {
+			type: "addon",
+			id: RECORDER_ADDON_ID,
+			nodeId: this.nodeId
+		};
+		this.ctx.eventBus.emit({
+			id: randomUUID(),
+			timestamp: /* @__PURE__ */ new Date(),
+			source,
+			category,
+			data
+		});
+	}
+	/**
+	* Dedicated export MP4 download handler. Resolves `<exportId>.mp4` to a `ready`
+	* row's file (traversal-guarded by the id regex + the exact stored path),
+	* streams it with HTTP `Range`, and — when the FINAL byte of a full-file GET is
+	* flushed — records the download so `deleteAfterDownload` can reclaim the file.
+	*/
+	async serveExportDownload(state, outPath, req, res) {
+		if (req.method !== "GET" && req.method !== "HEAD") {
+			res.writeHead(405).end();
+			return;
+		}
+		const urlPath = (req.url ?? "/").split("?")[0] ?? "/";
+		const match = EXPORT_FILENAME_RE.exec(urlPath.replace(/^\/+/, ""));
+		if (!match) {
+			res.writeHead(404).end();
+			return;
+		}
+		const exportId = match[1];
+		const rec = await getExportRecord(state, exportId);
+		if (!rec || rec.state !== "ready") {
+			res.writeHead(404).end();
+			return;
+		}
+		const absPath = outPath(rec);
+		let size;
+		try {
+			const st = await promises.stat(absPath);
+			if (!st.isFile()) {
+				res.writeHead(404).end();
+				return;
+			}
+			size = st.size;
+		} catch {
+			res.writeHead(404).end();
+			return;
+		}
+		const baseHeaders = {
+			"content-type": contentTypeFor(absPath),
+			"accept-ranges": "bytes",
+			"cache-control": "no-cache"
+		};
+		const range = parseRangeHeader(req.headers.range, size);
+		const servesFinalByte = range ? range.end === size - 1 : true;
+		const recordDownloadOnFinish = () => {
+			if (req.method !== "GET" || !servesFinalByte) return;
+			res.once("finish", () => {
+				markDownloaded(exportId, Date.now(), this.exportJanitorDeps(), (fn, ms) => {
+					setTimeout(fn, ms).unref?.();
+				}, EXPORT_DELETE_GRACE_MS).catch((err) => {
+					this.ctx.logger.warn("recorder: markDownloaded failed", { meta: {
+						exportId,
+						error: errMsg(err)
+					} });
+				});
+			});
+		};
+		if (range) {
+			res.writeHead(206, {
+				...baseHeaders,
+				"content-range": `bytes ${range.start}-${range.end}/${size}`,
+				"content-length": String(range.end - range.start + 1)
+			});
+			if (req.method === "HEAD") {
+				res.end();
+				return;
+			}
+			recordDownloadOnFinish();
+			createReadStream(absPath, {
+				start: range.start,
+				end: range.end
+			}).pipe(res);
+			return;
+		}
+		res.writeHead(200, {
+			...baseHeaders,
+			"content-length": String(size)
+		});
+		if (req.method === "HEAD") {
+			res.end();
+			return;
+		}
+		recordDownloadOnFinish();
+		createReadStream(absPath).pipe(res);
+	}
 };
 //#endregion
 export { RecorderV2Addon as default };