@camstack/addon-pipeline 0.1.19 → 0.2.0

package/dist/recorder/index.mjs

@@ -0,0 +1,2095 @@
+import { G as recordingCapability, J as storageEvictableCapability, K as selectAssignedProfileSlots, P as hydrateSchema, T as createDurableState, at as record, g as RecordingConfigSchema, i as BaseAddon, j as errMsg, ot as string, p as EventCategory, z as migrateConfigToBands } from "../dist-C5jnNl0n.mjs";
+import { promises } from "node:fs";
+import path from "node:path";
+import { createFileDataPlaneHandler } from "@camstack/core";
+import { spawn } from "node:child_process";
+//#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}`);
+	const d = new Date(startMs);
+	const p2 = (n) => String(n).padStart(2, "0");
+	return `${deviceId}/${profile}/${d.getUTCFullYear()}/${p2(d.getUTCMonth() + 1)}/${p2(d.getUTCDate())}/${p2(d.getUTCHours())}/${startMs}-${durMs}-${bytes}.m4s`;
+}
+var SEG_RE = /^(\d+)\/([^/]+)\/\d{4}\/\d{2}\/\d{2}\/\d{2}\/(\d+)-(\d+)-(\d+)\.m4s$/;
+function parseSegmentPath(relPath) {
+	const m = SEG_RE.exec(relPath);
+	if (!m) return null;
+	return {
+		deviceId: Number(m[1]),
+		profile: m[2],
+		startMs: Number(m[3]),
+		durMs: Number(m[4]),
+		bytes: Number(m[5])
+	};
+}
+//#endregion
+//#region src/recorder/merge-ranges.ts
+function mergeRanges(segments, gapToleranceMs) {
+	if (segments.length === 0) return [];
+	const sorted = [...segments].toSorted((a, b) => a.startMs - b.startMs);
+	const out = [];
+	let curStart = sorted[0].startMs;
+	let curEnd = sorted[0].startMs + sorted[0].durMs;
+	for (let i = 1; i < sorted.length; i++) {
+		const s = sorted[i];
+		if (s.startMs <= curEnd + gapToleranceMs) curEnd = Math.max(curEnd, s.startMs + s.durMs);
+		else {
+			out.push({
+				startMs: curStart,
+				endMs: curEnd
+			});
+			curStart = s.startMs;
+			curEnd = s.startMs + s.durMs;
+		}
+	}
+	out.push({
+		startMs: curStart,
+		endMs: curEnd
+	});
+	return out;
+}
+//#endregion
+//#region src/recorder/recording-index.ts
+/**
+* In-memory footage index, keyed by deviceId → (relativePath → SegmentRow).
+* The framework `storage` cap's `list()` is the ground truth: `hydrateDevice`
+* rebuilds a camera's set from a `list()` result, and `addSegment`/`removeSegments`
+* keep it write-through on finalize/evict. Because every row is derived from a
+* segment path (which encodes start/dur/bytes), the index can never drift from
+* disk. No SQLite, no persistence of its own.
+*/
+var RecordingIndex = class {
+	byDevice = /* @__PURE__ */ new Map();
+	mapFor(deviceId) {
+		let m = this.byDevice.get(deviceId);
+		if (!m) {
+			m = /* @__PURE__ */ new Map();
+			this.byDevice.set(deviceId, m);
+		}
+		return m;
+	}
+	/**
+	* Replace a device's segments FOR ONE LOCATION from a `storage.list` result (paths relative to that
+	* location root). Rows on other locations are preserved. Non-segment paths and other devices are ignored.
+	*/
+	hydrateDevice(deviceId, locationId, relPaths) {
+		const m = this.mapFor(deviceId);
+		for (const [path, existing] of m) if (existing.locationId === locationId) m.delete(path);
+		for (const path of relPaths) {
+			const p = parseSegmentPath(path);
+			if (!p || p.deviceId !== deviceId) continue;
+			m.set(path, {
+				deviceId: p.deviceId,
+				profile: p.profile,
+				startMs: p.startMs,
+				durMs: p.durMs,
+				bytes: p.bytes,
+				path,
+				locationId
+			});
+		}
+	}
+	/** Insert/replace one finalized segment (idempotent by path). */
+	addSegment(s) {
+		this.mapFor(s.deviceId).set(s.path, s);
+	}
+	/** Remove segments by relative path, routing each path to the correct device map via its encoded deviceId. */
+	removeSegments(paths) {
+		for (const p of paths) {
+			const parsed = parseSegmentPath(p);
+			if (!parsed) continue;
+			this.byDevice.get(parsed.deviceId)?.delete(p);
+		}
+	}
+	/** Rows for a device (optionally one profile), sorted by start. */
+	segments(deviceId, profile) {
+		const m = this.byDevice.get(deviceId);
+		if (!m) return [];
+		return [...m.values()].filter((s) => profile == null || s.profile === profile).toSorted((a, b) => a.startMs - b.startMs);
+	}
+	/** Aggregate accounting for a device across ALL its locations (use `accountingForLocation` for one location). */
+	accounting(deviceId) {
+		const m = this.byDevice.get(deviceId);
+		if (!m || m.size === 0) return {
+			bytes: 0,
+			count: 0,
+			oldestMs: null,
+			newestMs: null
+		};
+		let bytes = 0;
+		let oldestMs = Infinity;
+		let newestMs = -Infinity;
+		for (const s of m.values()) {
+			bytes += s.bytes;
+			if (s.startMs < oldestMs) oldestMs = s.startMs;
+			if (s.startMs > newestMs) newestMs = s.startMs;
+		}
+		return {
+			bytes,
+			count: m.size,
+			oldestMs,
+			newestMs
+		};
+	}
+	/** All segments on a storage location across every device, oldest-first. */
+	segmentsOnLocation(locationId) {
+		const out = [];
+		for (const m of this.byDevice.values()) for (const s of m.values()) if (s.locationId === locationId) out.push(s);
+		return out.toSorted((a, b) => a.startMs - b.startMs);
+	}
+	/** Aggregate accounting for a storage location across every device. */
+	accountingForLocation(locationId) {
+		let bytes = 0;
+		let count = 0;
+		let oldestMs = Infinity;
+		let newestMs = -Infinity;
+		for (const m of this.byDevice.values()) for (const s of m.values()) {
+			if (s.locationId !== locationId) continue;
+			bytes += s.bytes;
+			count += 1;
+			if (s.startMs < oldestMs) oldestMs = s.startMs;
+			if (s.startMs > newestMs) newestMs = s.startMs;
+		}
+		if (count === 0) return {
+			bytes: 0,
+			count: 0,
+			oldestMs: null,
+			newestMs: null
+		};
+		return {
+			bytes,
+			count,
+			oldestMs,
+			newestMs
+		};
+	}
+	/** Binary-search a start-sorted slice for the segment containing epochMs. */
+	segmentAtIn(segs, epochMs) {
+		if (segs.length === 0) return null;
+		let lo = 0;
+		let hi = segs.length - 1;
+		let cand = -1;
+		while (lo <= hi) {
+			const mid = lo + hi >> 1;
+			if (segs[mid].startMs <= epochMs) {
+				cand = mid;
+				lo = mid + 1;
+			} else hi = mid - 1;
+		}
+		if (cand < 0) return null;
+		const seg = segs[cand];
+		return epochMs < seg.startMs + seg.durMs ? seg : null;
+	}
+	/** The segment whose [startMs, startMs+durMs) window contains `epochMs`, or null if `epochMs` falls in a gap / there is no footage. */
+	segmentAt(deviceId, profile, epochMs) {
+		return this.segmentAtIn(this.segments(deviceId, profile), epochMs);
+	}
+	/**
+	* If epochMs is covered, returns it unchanged. Otherwise returns the start of the
+	* next covered segment forward. Returns null if there is no forward coverage
+	* (epoch past all footage, or no footage at all). Only snaps forward — never backward.
+	*/
+	nearestCoveredEdge(deviceId, profile, epochMs) {
+		const segs = this.segments(deviceId, profile);
+		if (segs.length === 0) return null;
+		if (this.segmentAtIn(segs, epochMs) !== null) return epochMs;
+		const next = segs.find((s) => s.startMs >= epochMs);
+		return next ? next.startMs : null;
+	}
+	ranges(deviceId, profile, fromMs, toMs, gapToleranceMs) {
+		return mergeRanges(this.segments(deviceId, profile).filter((s) => s.startMs + s.durMs > fromMs && s.startMs < toMs), gapToleranceMs).map((r) => ({
+			startMs: Math.max(r.startMs, fromMs),
+			endMs: Math.min(r.endMs, toMs)
+		}));
+	}
+};
+//#endregion
+//#region src/recorder/segment-store.ts
+var SegmentStore = class {
+	deps;
+	constructor(deps) {
+		this.deps = deps;
+	}
+	async hydrate(deviceId, location) {
+		const paths = await this.deps.list({
+			location,
+			prefix: `${deviceId}/`
+		});
+		this.deps.index.hydrateDevice(deviceId, location, paths);
+	}
+	async onFinalized(input) {
+		let bytes;
+		try {
+			bytes = await this.deps.statBytes(input.flatAbsPath);
+		} catch (err) {
+			this.deps.logger.warn("segment stat failed", err);
+			return null;
+		}
+		if (bytes <= 0) return null;
+		const relPath = segmentRelPath(input.deviceId, input.profile, input.startMs, input.durMs, bytes);
+		const toAbs = `${input.locationRoot}/${relPath}`;
+		try {
+			await this.deps.moveFile(input.flatAbsPath, toAbs);
+		} catch (err) {
+			this.deps.logger.warn("segment relocate failed", err);
+			return null;
+		}
+		const row = {
+			deviceId: input.deviceId,
+			profile: input.profile,
+			startMs: input.startMs,
+			durMs: input.durMs,
+			bytes,
+			path: relPath,
+			locationId: input.locationId
+		};
+		this.deps.index.addSegment(row);
+		return row;
+	}
+	/**
+	* Delete `rows` via the storage cap under `location` and de-index the ones that delete
+	* successfully; returns the reclaimed byte total. Precondition: every row must belong to
+	* `location` (`row.locationId === location`) — the caller guarantees this (e.g. the evictable
+	* provider feeds rows from `segmentsOnLocation(location)`). Mixed-location rows would be deleted
+	* against the wrong location.
+	*/
+	async evict(location, rows) {
+		let reclaimed = 0;
+		const removed = [];
+		for (const r of rows) try {
+			await this.deps.deletePath({
+				location,
+				relativePath: r.path
+			});
+			removed.push(r.path);
+			reclaimed += r.bytes;
+		} catch (err) {
+			this.deps.logger.warn("segment delete failed", err);
+		}
+		if (removed.length > 0) this.deps.index.removeSegments(removed);
+		return reclaimed;
+	}
+};
+//#endregion
+//#region src/recorder/evict-select.ts
+var DAY_MS$2 = 1440 * 60 * 1e3;
+var GB = 1e9;
+function selectEvictions(segments, limits) {
+	const oldestFirst = [...segments].toSorted((a, b) => a.startMs - b.startMs);
+	const selected = /* @__PURE__ */ new Set();
+	const out = [];
+	const select = (s) => {
+		if (selected.has(s.path)) return;
+		selected.add(s.path);
+		out.push(s);
+	};
+	if (limits.maxAgeDays != null && limits.maxAgeDays > 0) {
+		const cutoff = limits.nowMs - limits.maxAgeDays * DAY_MS$2;
+		for (const s of oldestFirst) if (s.startMs < cutoff) select(s);
+	}
+	if (limits.maxSizeGb != null && limits.maxSizeGb > 0) {
+		const cap = limits.maxSizeGb * GB;
+		let remaining = 0;
+		for (const s of oldestFirst) if (!selected.has(s.path)) remaining += s.bytes;
+		for (const s of oldestFirst) {
+			if (remaining <= cap) break;
+			if (selected.has(s.path)) continue;
+			select(s);
+			remaining -= s.bytes;
+		}
+	}
+	return out;
+}
+/**
+* Pick the oldest segments whose cumulative bytes reach `targetBytes` (free ≈ targetBytes).
+* Oldest-first, no pinning. Returns all segments if the target exceeds the total; empty for a non-positive target.
+*
+* Selection is segment-granular: the actual reclaimable bytes may EXCEED `targetBytes` by up to
+* the size of the last selected segment (a 1-byte target still evicts one whole segment). Callers
+* sizing a reclaim share (e.g. StoragePressureManager) should expect this overshoot.
+*/
+function selectEvictionsByBytes(segments, targetBytes) {
+	if (targetBytes <= 0) return [];
+	const oldestFirst = [...segments].toSorted((a, b) => a.startMs - b.startMs);
+	const out = [];
+	let freed = 0;
+	for (const s of oldestFirst) {
+		if (freed >= targetBytes) break;
+		out.push(s);
+		freed += s.bytes;
+	}
+	return out;
+}
+//#endregion
+//#region src/recorder/storage-evictable-provider.ts
+/**
+* Implements the `storage-evictable` cap surface for recording footage. The core
+* StoragePressureManager owns the trigger (per-location free-space monitoring); this
+* provider decides WHAT footage is expendable (oldest-first, no pinning) and deletes it
+* via `SegmentStore.evict`, which removes the file through the `storage` cap and de-indexes.
+*
+* The cap's `locationId` is used directly as the storage `location` (identity); see Plan 2d
+* notes. Wiring this class to the cap + the SegmentStore happens in Plan 2e.
+*/
+var StorageEvictableProvider = class {
+	deps;
+	constructor(deps) {
+		this.deps = deps;
+	}
+	async getEvictableUsage(input) {
+		return { bytes: this.deps.index.accountingForLocation(input.locationId).bytes };
+	}
+	async evict(input) {
+		const onLocation = this.deps.index.segmentsOnLocation(input.locationId);
+		const victims = selectEvictionsByBytes(onLocation, input.targetBytes);
+		return {
+			reclaimedBytes: await this.deps.store.evict(input.locationId, victims),
+			exhausted: victims.length >= onLocation.length
+		};
+	}
+};
+//#endregion
+//#region src/recorder/redundant-segments.ts
+/**
+* Return the indices (into `segs`) of segments safe to delete: those fully
+* contained within a kept segment `[coverStart, coverEnd]`. Sorting by start
+* ascending, then by end DESCENDING, guarantees the containing (longer) segment
+* is seen first and kept, and any shorter segment nested inside it is removed.
+*/
+function selectRedundantSegments(segs) {
+	if (segs.length < 2) return [];
+	const order = segs.map((s, i) => ({
+		start: s.startMs,
+		end: s.startMs + s.durMs,
+		i
+	})).toSorted((a, b) => a.start - b.start || b.end - a.end);
+	const remove = [];
+	let coverStart = Number.NEGATIVE_INFINITY;
+	let coverEnd = Number.NEGATIVE_INFINITY;
+	for (const seg of order) if (seg.start >= coverStart && seg.end <= coverEnd && seg.end > seg.start) remove.push(seg.i);
+	else {
+		coverStart = seg.start;
+		coverEnd = seg.end;
+	}
+	return remove;
+}
+//#endregion
+//#region src/recorder/janitor.ts
+/** Group an array by a string key. */
+function groupBy(items, key) {
+	const out = /* @__PURE__ */ new Map();
+	for (const it of items) {
+		const k = key(it);
+		const arr = out.get(k);
+		if (arr) arr.push(it);
+		else out.set(k, [it]);
+	}
+	return out;
+}
+async function runRedundancyJanitor(deps) {
+	let files = 0;
+	let bytes = 0;
+	for (const deviceId of deps.deviceIds) {
+		const byProfile = groupBy(deps.segmentsFor(deviceId), (r) => r.profile);
+		for (const [profile, rows] of byProfile) {
+			const sorted = [...rows].toSorted((a, b) => a.startMs - b.startMs);
+			const redundant = selectRedundantSegments(sorted);
+			if (redundant.length === 0) continue;
+			const victims = redundant.map((i) => sorted[i]);
+			for (const [location, vrows] of groupBy(victims, (v) => v.locationId)) try {
+				const reclaimed = await deps.evict(location, vrows);
+				files += vrows.length;
+				bytes += reclaimed;
+			} catch (err) {
+				deps.logger.warn("janitor: evict failed (skipping)", { meta: {
+					deviceId,
+					profile,
+					location,
+					count: vrows.length,
+					error: err instanceof Error ? err.message : String(err)
+				} });
+			}
+		}
+	}
+	if (files > 0) deps.logger.info("janitor: removed redundant recording segments", { meta: {
+		files,
+		bytes
+	} });
+	return {
+		files,
+		bytes
+	};
+}
+//#endregion
+//#region src/recorder/event-map.ts
+var EventMap = class {
+	byDevice = /* @__PURE__ */ new Map();
+	record(deviceId, marker) {
+		const list = this.byDevice.get(deviceId) ?? [];
+		list.push({ ...marker });
+		this.byDevice.set(deviceId, list);
+	}
+	events(deviceId, fromMs, toMs) {
+		const list = this.byDevice.get(deviceId);
+		if (!list) return [];
+		return list.filter((e) => e.t >= fromMs && e.t <= toMs).toSorted((a, b) => a.t - b.t);
+	}
+	prune(nowMs, maxAgeMs) {
+		const cutoff = nowMs - maxAgeMs;
+		let dropped = 0;
+		for (const [deviceId, list] of this.byDevice) {
+			const kept = list.filter((e) => e.t >= cutoff);
+			dropped += list.length - kept.length;
+			this.byDevice.set(deviceId, kept);
+		}
+		return dropped;
+	}
+};
+//#endregion
+//#region src/recorder/event-capture.ts
+function markerFromMotion(data, pad) {
+	if (!data.detected) return null;
+	return {
+		t: data.timestamp,
+		startMs: data.timestamp - pad.padPreMs,
+		endMs: data.timestamp + pad.padPostMs,
+		source: "motion",
+		...data.regions !== void 0 ? { metadata: { regions: data.regions } } : {}
+	};
+}
+function subscribeEventCapture(deps) {
+	const { eventBus, map, padPreMs, padPostMs, onMotion } = deps;
+	return eventBus.subscribe({ category: EventCategory.MotionOnMotionChanged }, (event) => {
+		const mk = markerFromMotion(event.data, {
+			padPreMs,
+			padPostMs
+		});
+		if (!mk) return;
+		map.record(event.data.deviceId, mk);
+		onMotion?.(event.data.deviceId, event.data.timestamp);
+	});
+}
+//#endregion
+//#region src/recorder/day-bucket.ts
+/** Pure helpers to bucket recording segment starts into local calendar days. */
+var DAY_MS$1 = 1440 * 60 * 1e3;
+/**
+* Epoch (UTC ms) of the local midnight that starts the day containing `ms`.
+* `tzOffsetMinutes` is minutes to ADD to UTC to get local time — i.e. the client
+* sends `-new Date().getTimezoneOffset()`. Returning a UTC epoch (not a date
+* string) lets the viewer compare directly against the epoch it computes per
+* calendar cell, so markers line up regardless of timezone.
+*/
+function localMidnightEpoch(ms, tzOffsetMinutes) {
+	const off = tzOffsetMinutes * 6e4;
+	const local = ms + off;
+	return local - (local % DAY_MS$1 + DAY_MS$1) % DAY_MS$1 - off;
+}
+/**
+* Sorted, distinct local-midnight epochs for every segment start in [fromMs, toMs).
+*/
+function distinctRecordingDays(startsMs, fromMs, toMs, tzOffsetMinutes) {
+	const days = /* @__PURE__ */ new Set();
+	for (const s of startsMs) {
+		if (s < fromMs || s >= toMs) continue;
+		days.add(localMidnightEpoch(s, tzOffsetMinutes));
+	}
+	return [...days].toSorted((a, b) => a - b);
+}
+//#endregion
+//#region src/recorder/playlist.ts
+/** A VOD variant playlist with an absolute wall-clock anchor per segment. */
+function buildVariantPlaylist(segments) {
+	const maxDur = segments.reduce((m, s) => Math.max(m, s.durMs), 0);
+	const lines = [
+		"#EXTM3U",
+		"#EXT-X-VERSION:7",
+		"#EXT-X-PLAYLIST-TYPE:VOD",
+		`#EXT-X-TARGETDURATION:${Math.ceil(maxDur / 1e3)}`,
+		"#EXT-X-MEDIA-SEQUENCE:0"
+	];
+	segments.forEach((s, i) => {
+		if (i > 0) lines.push("#EXT-X-DISCONTINUITY");
+		lines.push(`#EXT-X-PROGRAM-DATE-TIME:${new Date(s.startMs).toISOString()}`);
+		lines.push(`#EXTINF:${(s.durMs / 1e3).toFixed(3)},`);
+		lines.push(s.uri);
+	});
+	lines.push("#EXT-X-ENDLIST");
+	return lines.join("\n") + "\n";
+}
+/** A master (multi-variant) playlist enabling client ABR / profile selection. */
+function buildMasterPlaylist(variants) {
+	const lines = ["#EXTM3U", "#EXT-X-VERSION:7"];
+	for (const v of variants) {
+		const attrs = [`BANDWIDTH=${v.bandwidth}`];
+		if (v.resolution) attrs.push(`RESOLUTION=${v.resolution.width}x${v.resolution.height}`);
+		if (v.codecs) attrs.push(`CODECS="${v.codecs}"`);
+		attrs.push(`NAME="${v.profile}"`);
+		lines.push(`#EXT-X-STREAM-INF:${attrs.join(",")}`);
+		lines.push(v.uri);
+	}
+	return lines.join("\n") + "\n";
+}
+//#endregion
+//#region src/recorder/recording-device-settings.ts
+function buildRecordingDeviceSchema() {
+	return { sections: [{
+		id: "recording-playback",
+		tab: "recording",
+		location: "top-tab",
+		title: "Recording",
+		order: 10,
+		fields: [{
+			type: "widget",
+			key: "_recordingPanel",
+			label: "",
+			widgetId: "host/recording-panel"
+		}]
+	}] };
+}
+//#endregion
+//#region src/recorder/addon/config-store.ts
+/**
+* Per-device recording-config persistence for the recorder addon.
+*
+* Every camera's `RecordingConfig` lives in ONE addon-store blob keyed by
+* (stringified) numeric deviceId — enumerable for boot hydrate (so the addon
+* knows which devices have persisted footage to index without scanning every
+* device store). The whole Zod-validated blob round-trips on every read/write
+* via a {@link createDurableState} handle, so no per-device field can be
+* silently dropped on persist. A corrupt blob reads back as EMPTY rather than
+* crashing boot.
+*
+* On read the legacy `mode`/`schedules`/`triggers` fields are derived once into
+* the authoritative `bands` via `migrateConfigToBands`, then persisted, so the
+* UI reads `bands` directly forever after.
+*/
+/** The addon-store key holding the deviceId → RecordingConfig map. */
+var RECORDING_CONFIGS_KEY = "recordingConfigs";
+/** Persisted shape: stringified numeric deviceId → full RecordingConfig. */
+var RecordingConfigsBlobSchema = record(string(), RecordingConfigSchema);
+/** Cold-start default for a camera that has never been configured: disabled, no bands. */
+var DEFAULT_DEVICE_CONFIG = {
+	enabled: false,
+	bands: []
+};
+function blobState(store) {
+	return createDurableState({
+		key: RECORDING_CONFIGS_KEY,
+		schema: RecordingConfigsBlobSchema,
+		fallback: {},
+		read: () => store.readAddonStore(),
+		write: (patch) => store.writeAddonStore(patch)
+	});
+}
+function serialize(map) {
+	const out = {};
+	for (const [id, config] of map) out[String(id)] = config;
+	return out;
+}
+/** Read every persisted device config, keyed by numeric deviceId. */
+async function readDeviceConfigs(store) {
+	const blob = await blobState(store).get();
+	const map = /* @__PURE__ */ new Map();
+	for (const [key, config] of Object.entries(blob)) {
+		const id = Number(key);
+		if (Number.isInteger(id)) map.set(id, config);
+	}
+	return map;
+}
+/**
+* The persisted config for a device with `bands` guaranteed materialized.
+* Legacy blobs (mode/schedules/triggers, no bands) are migrated into bands and
+* re-persisted so the stored shape converges on the authoritative model. An
+* unconfigured device returns {@link DEFAULT_DEVICE_CONFIG}.
+*/
+async function loadDeviceConfig(store, deviceId) {
+	const stored = (await readDeviceConfigs(store)).get(deviceId);
+	if (!stored) return DEFAULT_DEVICE_CONFIG;
+	if (stored.bands) return stored;
+	const migrated = {
+		...stored,
+		bands: migrateConfigToBands(stored)
+	};
+	await saveDeviceConfig(store, deviceId, migrated);
+	return migrated;
+}
+/**
+* Persist (insert or replace) a device's config. Validates against
+* `RecordingConfigSchema` at the boundary (untrusted cap input). Returns the
+* validated config that was persisted.
+*/
+async function saveDeviceConfig(store, deviceId, config) {
+	const validated = RecordingConfigSchema.parse(config);
+	const map = await readDeviceConfigs(store);
+	map.set(deviceId, validated);
+	await blobState(store).set(serialize(map));
+	return validated;
+}
+/**
+* Determine the active recording mode for a config's bands — the value the
+* `recording` cap status reports. `continuous` wins when any band records
+* continuously, else `events` when any band exists, else `off`.
+*/
+function activeModeForConfig(config) {
+	const bands = config.bands ?? [];
+	if (!config.enabled || bands.length === 0) return "off";
+	if (bands.some((b) => b.mode === "continuous")) return "continuous";
+	return "events";
+}
+//#endregion
+//#region src/recorder/addon/recording-provider.ts
+/**
+* Builds the `recording` cap provider (`IRecordingProvider`) on the recorder
+* core. NO ffmpeg / segment writing here — that arrives in B2/B3. This shell
+* answers reads from the v2 `RecordingIndex` (hydrated from `storage.list`),
+* persists per-device config via durable-state, and prunes footage through
+* `selectEvictions` + `SegmentStore.evict`.
+*/
+/** Bandwidth hint per profile for the master playlist (real bitrate is a later refinement). */
+var PROFILE_BANDWIDTH = {
+	high: 4e6,
+	mid: 15e5,
+	low: 5e5
+};
+var DEFAULT_BANDWIDTH = 1e6;
+/**
+* Max gap (ms) between consecutive segments still treated as ONE continuous
+* availability range. Absorbs the few-ms EXTINF-rounding jitter at every segment
+* boundary and a single dropped/late ~4s segment; a larger gap (recorder off,
+* multiple missing segments) splits the ranges so real discontinuities show.
+*/
+var RANGE_MERGE_GAP_MS = 5e3;
+/** Empty "no playback" manifest. */
+function noPlayback(deviceId) {
+	return {
+		deviceId,
+		localMasterPath: null,
+		playbackUrl: null,
+		playbackEndpoints: []
+	};
+}
+/** Absolute dir the playback playlists for a device are written to (served root = `<dataDir>/playback`). */
+function playbackDirFor(dataDir, deviceId) {
+	return path.join(dataDir, "playback", String(deviceId));
+}
+/**
+* Build a master + per-profile variant HLS playlist on disk for the requested
+* window and return a RELATIVE playback URL through the hub's data-plane
+* reverse-proxy. Only segments actually present on disk are referenced (a
+* missing file would 404 mid-playlist). Returns "no playback" when the device
+* has no footage in range or the data-plane isn't served yet. Variant/segment
+* URIs are relative so the master + variants + segments form a self-contained
+* tree the player resolves against the master URL.
+*/
+async function buildPlaybackManifest(deps, deviceId, fromMs, toMs) {
+	const base = deps.playbackBaseUrl();
+	if (base === null) return noPlayback(deviceId);
+	const rootById = new Map(deps.locations().map((l) => [l.id, l.root]));
+	const playbackDir = playbackDirFor(deps.dataDir, deviceId);
+	const profiles = [...new Set(deps.index.segments(deviceId).map((s) => s.profile))];
+	const variants = [];
+	for (const profile of profiles) {
+		const segs = deps.index.segments(deviceId, profile).filter((s) => s.startMs < toMs && s.startMs + s.durMs > fromMs).toSorted((a, b) => a.startMs - b.startMs);
+		if (segs.length === 0) continue;
+		const variantSegments = [];
+		for (const s of segs) {
+			const rel = segmentRelPath(deviceId, profile, s.startMs, s.durMs, s.bytes);
+			const root = rootById.get(s.locationId);
+			if (root === void 0) continue;
+			try {
+				await promises.stat(path.join(root, rel));
+			} catch {
+				continue;
+			}
+			variantSegments.push({
+				uri: rel.split("/").slice(1).join("/"),
+				startMs: s.startMs,
+				durMs: s.durMs
+			});
+		}
+		if (variantSegments.length === 0) continue;
+		await promises.mkdir(playbackDir, { recursive: true });
+		await promises.writeFile(path.join(playbackDir, `${profile}.m3u8`), buildVariantPlaylist(variantSegments), "utf8");
+		variants.push({
+			profile,
+			bandwidth: PROFILE_BANDWIDTH[profile] ?? DEFAULT_BANDWIDTH,
+			uri: `${profile}.m3u8`
+		});
+	}
+	if (variants.length === 0) return noPlayback(deviceId);
+	await promises.mkdir(playbackDir, { recursive: true });
+	const masterPath = path.join(playbackDir, "master.m3u8");
+	await promises.writeFile(masterPath, buildMasterPlaylist(variants), "utf8");
+	const playbackUrl = `${base}/${deviceId}/master.m3u8?from=${fromMs}&to=${toMs}`;
+	return {
+		deviceId,
+		localMasterPath: masterPath,
+		playbackUrl,
+		playbackEndpoints: [playbackUrl]
+	};
+}
+/** Number of days in ms — for the retention floor returned by `pruneFootage`. */
+var DAY_MS = 1440 * 60 * 1e3;
+function statusFor(deps, deviceId, config) {
+	return {
+		deviceId,
+		enabled: config.enabled,
+		activeMode: activeModeForConfig(config),
+		nodeId: deps.nodeId,
+		storageBytes: deps.index.accounting(deviceId).bytes
+	};
+}
+/** Group a device's segments by their storage location id. */
+function segmentsByLocation(rows) {
+	const out = /* @__PURE__ */ new Map();
+	for (const r of rows) {
+		const list = out.get(r.locationId);
+		if (list) list.push(r);
+		else out.set(r.locationId, [r]);
+	}
+	return out;
+}
+/**
+* Build the `IRecordingProvider`. The provider is a thin façade over the v2
+* core; all storage I/O flows through the injected deps.
+*/
+function buildRecordingProvider(deps) {
+	const readFile = deps.readFile ?? ((absPath) => promises.readFile(absPath));
+	return {
+		getStatus: async ({ deviceId }) => {
+			return statusFor(deps, deviceId, await loadDeviceConfig(deps.configStore, deviceId));
+		},
+		getAvailability: async ({ deviceId, fromMs, toMs }) => {
+			return {
+				deviceId,
+				ranges: [...new Set(deps.index.segments(deviceId).map((s) => s.profile))].flatMap((profile) => deps.index.ranges(deviceId, profile, fromMs, toMs, RANGE_MERGE_GAP_MS).map((r) => ({
+					profile,
+					startMs: r.startMs,
+					endMs: r.endMs
+				})))
+			};
+		},
+		getDaysWithRecordings: async ({ deviceId, fromMs, toMs, tzOffsetMinutes }) => {
+			return {
+				deviceId,
+				days: distinctRecordingDays(deps.index.segments(deviceId).map((s) => s.startMs), fromMs, toMs, tzOffsetMinutes)
+			};
+		},
+		getPlaybackManifest: ({ deviceId, fromMs, toMs }) => buildPlaybackManifest(deps, deviceId, fromMs, toMs),
+		getStorageUsage: async () => {
+			const locations = deps.locations();
+			const devices = [];
+			const seenDevices = /* @__PURE__ */ new Set();
+			for (const loc of locations) for (const row of deps.index.segmentsOnLocation(loc.id)) seenDevices.add(row.deviceId);
+			let totalUsedBytes = 0;
+			for (const deviceId of seenDevices) {
+				const usedBytes = deps.index.accounting(deviceId).bytes;
+				totalUsedBytes += usedBytes;
+				devices.push({
+					deviceId,
+					usedBytes
+				});
+			}
+			const locationUsages = await Promise.all(locations.map(async (loc) => {
+				const cap = await deps.capacity(loc.root);
+				return {
+					locationId: loc.id,
+					usedBytes: deps.index.accountingForLocation(loc.id).bytes,
+					availableBytes: cap.availableBytes,
+					totalBytes: cap.totalBytes
+				};
+			}));
+			devices.sort((a, b) => b.usedBytes - a.usedBytes);
+			return {
+				nodeId: deps.nodeId,
+				totalUsedBytes,
+				devices,
+				locations: locationUsages
+			};
+		},
+		getDeviceConfig: async ({ deviceId }) => loadDeviceConfig(deps.configStore, deviceId),
+		locateSegment: async ({ deviceId, profile, epochMs }) => {
+			const seg = deps.index.segmentAt(deviceId, profile, epochMs);
+			if (seg) return {
+				kind: "segment",
+				startMs: seg.startMs,
+				durMs: seg.durMs,
+				bytes: seg.bytes
+			};
+			return {
+				kind: "gap",
+				nearestEdgeMs: deps.index.nearestCoveredEdge(deviceId, profile, epochMs)
+			};
+		},
+		readSegmentBytes: async ({ deviceId, profile, startMs }) => {
+			const seg = deps.index.segments(deviceId, profile).find((s) => s.startMs === startMs);
+			if (!seg) throw new Error(`recording: no segment at start ${startMs} for ${deviceId}/${profile}`);
+			const loc = deps.locations().find((l) => l.id === seg.locationId);
+			if (!loc) throw new Error(`recording: unknown location ${seg.locationId}`);
+			const data = await readFile(path.join(loc.root, seg.path));
+			return { data: Uint8Array.from(data) };
+		},
+		setDeviceConfig: async ({ deviceId, config }) => {
+			const saved = await saveDeviceConfig(deps.configStore, deviceId, config);
+			if (deps.onConfigChanged) try {
+				await deps.onConfigChanged(deviceId);
+			} catch (err) {
+				deps.logger.warn("recorder: re-evaluate after setDeviceConfig failed", {
+					tags: { deviceId },
+					meta: { error: errMsg(err) }
+				});
+			}
+			return saved;
+		},
+		rescanStorage: async ({ deviceId }) => {
+			const locations = await deps.refreshLocations();
+			await deps.hydrateDevice(deviceId, locations);
+			return statusFor(deps, deviceId, await loadDeviceConfig(deps.configStore, deviceId));
+		},
+		pruneFootage: async ({ deviceId }) => {
+			const retention = (await loadDeviceConfig(deps.configStore, deviceId)).retention;
+			const nowMs = Date.now();
+			const victims = selectEvictions(deps.index.segments(deviceId), {
+				maxAgeDays: retention?.maxAgeDays,
+				maxSizeGb: retention?.maxSizeGb,
+				nowMs
+			});
+			let reclaimedBytes = 0;
+			let deletedBuckets = 0;
+			for (const [locationId, locVictims] of segmentsByLocation(victims)) try {
+				const freed = await deps.segmentStore.evict(locationId, locVictims);
+				reclaimedBytes += freed;
+				if (freed > 0) deletedBuckets += locVictims.length;
+			} catch (err) {
+				deps.logger.warn("recorder pruneFootage evict failed for location", {
+					tags: { deviceId },
+					meta: {
+						locationId,
+						error: errMsg(err)
+					}
+				});
+			}
+			return {
+				floorMs: deps.index.accounting(deviceId).oldestMs ?? (retention?.maxAgeDays ? nowMs - retention.maxAgeDays * DAY_MS : null),
+				deletedBuckets,
+				reclaimedBytes
+			};
+		},
+		getDeviceSettingsContribution: async () => hydrateSchema(buildRecordingDeviceSchema(), {}),
+		getDeviceLiveContribution: async () => null,
+		applyDeviceSettingsPatch: async ({ patch }) => {
+			const keys = Object.keys(patch ?? {});
+			if (keys.length > 0) deps.logger.debug("recorder: ignoring legacy settings patch (widget owns settings)", { meta: { keys } });
+			return { success: true };
+		}
+	};
+}
+//#endregion
+//#region src/recorder/addon/roots.ts
+/**
+* Storage-root resolution + boot hydrate for the recorder addon.
+*
+* Recordings live in the managed `recordings` / `recordingsLow` storage
+* locations (operator-configurable, multi-disk-ready), resolved through the
+* `storage` cap. The v2 `RecordingIndex` is hydrated by walking each location
+* root's `<deviceId>/` subtree on disk — segment paths encode start/dur/bytes,
+* so the in-memory index can never drift from disk. (We walk the filesystem
+* directly instead of `storage.list` because that cap lists only a directory's
+* IMMEDIATE children, not the `<deviceId>/<profile>/Y/M/D/H/*.m4s` tree — using
+* it dropped the entire index to ~empty on every restart/rescan; the recorder
+* already does local fs I/O for stat/move on these same roots.)
+*/
+/** The two recordings location types the recorder addon writes/reads. */
+var RECORDING_LOCATION_TYPES = new Set(["recordings", "recordingsLow"]);
+/**
+* Resolve every recordings storage location (`recordings` + `recordingsLow`)
+* to `{ id, root }`. Returns an empty list when the storage cap is unreachable
+* or no recordings location exists — callers degrade rather than crash.
+*/
+async function resolveRecordingsLocations(api, logger) {
+	try {
+		const recordings = (await api.storage.listLocations.query({})).filter((l) => RECORDING_LOCATION_TYPES.has(l.type));
+		return Promise.all(recordings.map(async (l) => ({
+			id: l.id,
+			root: await api.storage.resolve.query({
+				location: l.id,
+				relativePath: ""
+			})
+		})));
+	} catch (err) {
+		logger.warn("recorder: listLocations failed — no recordings locations resolved", { meta: { error: errMsg(err) } });
+		return [];
+	}
+}
+/**
+* Hydrate the v2 `RecordingIndex` for one device from every recordings location
+* by recursively walking `<root>/<deviceId>/` for `*.m4s` segments and feeding
+* the location-relative paths (`<deviceId>/<profile>/Y/M/D/H/<file>.m4s`, which
+* `parseSegmentPath` understands) to `index.hydrateDevice`. A missing device dir
+* (no footage yet) and any per-location failure are warned + skipped
+* (best-effort), so one bad volume never blocks the rest of the hydrate.
+*/
+async function hydrateDeviceFromStorage(_api, index, deviceId, locations, logger) {
+	for (const loc of locations) {
+		const deviceDir = path.join(loc.root, String(deviceId));
+		let entries;
+		try {
+			entries = await promises.readdir(deviceDir, { recursive: true });
+		} catch (err) {
+			if (err.code !== "ENOENT") logger.warn("recorder: hydrateDevice walk failed for location", {
+				tags: { deviceId },
+				meta: {
+					locationId: loc.id,
+					error: errMsg(err)
+				}
+			});
+			continue;
+		}
+		const relPaths = entries.filter((e) => e.endsWith(".m4s")).map((e) => `${deviceId}/${e.split(path.sep).join("/")}`);
+		index.hydrateDevice(deviceId, loc.id, relPaths);
+	}
+}
+//#endregion
+//#region src/recorder/addon/ffmpeg-args.ts
+/** ffmpeg argv: pull RTSP (TCP), copy video / transcode audio to AAC, write
+*  fragmented-mp4 segments named by epoch seconds FLAT under `outDir`, plus a
+*  rolling `live.m3u8` playlist. The recorder segment-watcher tails the
+*  playlist and hands each finalized flat file to `SegmentStore.onFinalized`,
+*  which stats + relocates it into the bucket tree (`segmentRelPath`). */
+function buildPassthroughArgs(a) {
+	return [
+		"-rtsp_transport",
+		"tcp",
+		"-i",
+		a.rtspUrl,
+		"-map",
+		"0",
+		"-c:v",
+		"copy",
+		"-c:a",
+		"aac",
+		"-f",
+		"segment",
+		"-segment_time",
+		String(a.segmentSeconds),
+		"-segment_format",
+		"mp4",
+		"-segment_format_options",
+		"movflags=+frag_keyframe+empty_moov+default_base_moof",
+		"-reset_timestamps",
+		"1",
+		"-strftime",
+		"1",
+		"-segment_list",
+		`${a.outDir}/live.m3u8`,
+		"-segment_list_type",
+		"m3u8",
+		`${a.outDir}/%s.m4s`
+	];
+}
+//#endregion
+//#region src/recorder/addon/segment-writer.ts
+/** Max CONSECUTIVE rapid restarts before giving up (reset by a stable run). */
+var MAX_RESTARTS = 10;
+/** How many trailing ffmpeg stderr lines to keep for the give-up diagnostic. */
+var STDERR_TAIL_LINES = 12;
+/** Restart backoff: base delay, doubled per consecutive attempt, capped. */
+var RESTART_BASE_MS = 500;
+var RESTART_MAX_MS = 1e4;
+/** A process that ran at least this long is "stable" → reset the restart count,
+*  so sporadic blips over a long lifetime never accumulate into a give-up. */
+var STABLE_RUN_MS = 3e4;
+/** Supervises one passthrough ffmpeg for a single (camera, profile). */
+var SegmentWriter = class {
+	cfg;
+	deps;
+	proc = null;
+	stopped = false;
+	restarts = 0;
+	restartTimer = null;
+	startedAt = 0;
+	constructor(cfg, deps) {
+		this.cfg = cfg;
+		this.deps = deps;
+	}
+	start() {
+		if (this.stopped || this.proc) return;
+		const args = buildPassthroughArgs(this.cfg);
+		const proc = this.deps.spawn(this.deps.ffmpegPath ?? "ffmpeg", args);
+		this.proc = proc;
+		this.startedAt = Date.now();
+		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) continue;
+				stderrTail.push(trimmed);
+				if (stderrTail.length > STDERR_TAIL_LINES) stderrTail.shift();
+			}
+		});
+		proc.on("exit", (code) => {
+			this.proc = null;
+			if (this.stopped) return;
+			const ranMs = Date.now() - this.startedAt;
+			if (ranMs >= STABLE_RUN_MS) this.restarts = 0;
+			if (this.restarts >= MAX_RESTARTS) {
+				this.deps.logger.warn("SegmentWriter giving up after max restarts", { meta: {
+					outDir: this.cfg.outDir,
+					code,
+					stderrTail: stderrTail.join(" | ")
+				} });
+				this.stopped = true;
+				this.deps.onGaveUp?.();
+				return;
+			}
+			this.restarts++;
+			const delayMs = Math.min(RESTART_BASE_MS * 2 ** (this.restarts - 1), RESTART_MAX_MS);
+			this.deps.logger.info("SegmentWriter restarting", { meta: {
+				outDir: this.cfg.outDir,
+				attempt: this.restarts,
+				delayMs,
+				ranMs
+			} });
+			this.restartTimer = setTimeout(() => {
+				this.restartTimer = null;
+				this.start();
+			}, delayMs);
+		});
+	}
+	stop() {
+		this.stopped = true;
+		if (this.restartTimer) {
+			clearTimeout(this.restartTimer);
+			this.restartTimer = null;
+		}
+		this.proc?.kill();
+		this.proc = null;
+	}
+};
+//#endregion
+//#region src/recorder/addon/segment-watcher.ts
+/**
+* Poll-based tail of an ffmpeg `-segment_list` (`live.m3u8`) for one
+* (camera, profile) output dir — recorder variant.
+*
+* Adapted from the old recorder (`addon-pipeline/src/recorder/segment-watcher.ts`).
+* The robust playlist-tailing core is unchanged: it polls `live.m3u8`, derives
+* `startMs` from the flat `<epochSec>.m4s` filename, corrects the inflated
+* first-segment EXTINF duration against the successor's start, and handles
+* pending/phantom (file-not-yet-flushed) entries with a bounded retry.
+*
+* KEY ADAPTATION vs the old watcher: this watcher does NOT relocate the flat
+* file, does NOT classify a continuous/events subtree, and does NOT touch a RAM
+* index. For each finalized flat segment it simply calls
+* `onFinalized(startMs, durMs, flatAbsPath)` and lets the v2 `SegmentStore`
+* (`onFinalized`) do the stat + relocate-into-bucket + index. The watcher only
+* verifies the flat file is on disk (so `onFinalized` does not race the flush)
+* before handing it off; the SegmentStore re-stats for the authoritative byte
+* count that goes into the path. B2 records CONTINUOUS bands only, so there is
+* no subtree to classify.
+*/
+var EPOCH_NAME_RE = /^(\d+)\.m4s$/;
+/** How many consecutive ticks to wait for a finalized segment's flat file to
+*  land before giving up on it (a genuine phantom). At a 2s watch interval this
+*  is ~16s — far longer than ffmpeg's slow-first-segment flush. */
+var MAX_PENDING_TICKS = 8;
+/**
+* Derive `startMs` (epoch milliseconds) from a flat ffmpeg segment path
+* (`<epochSec>.m4s`, possibly absolute). Returns null for any non-epoch path.
+*/
+function parseEpochStartMs(segPath) {
+	const m = EPOCH_NAME_RE.exec(path.basename(segPath));
+	if (!m) return null;
+	const epochSec = Number(m[1]);
+	return Number.isFinite(epochSec) ? epochSec * 1e3 : null;
+}
+/**
+* Correct a finalized segment's duration. ffmpeg's first-segment `#EXTINF` is
+* unreliable under `-c copy` from RTSP — it is inflated by the initial PTS
+* offset (observed: 87.961s for a segment whose successor starts only 12s
+* later). A segment physically cannot outlast the start of the next segment, so
+* when a successor exists we clamp the rounded EXTINF to the inter-segment gap.
+* For normal segments EXTINF (millisecond-accurate) is below the
+* integer-second start gap and wins, preserving sub-second precision. When
+* there is no successor (genuine last segment) or the gap is non-positive
+* (restart / same-second), we trust EXTINF.
+*/
+function correctedDurMs(durSeconds, startMs, nextStartMs) {
+	const extinfMs = Math.round(durSeconds * 1e3);
+	if (nextStartMs === null) return extinfMs;
+	const gapMs = nextStartMs - startMs;
+	if (gapMs <= 0) return extinfMs;
+	return Math.min(extinfMs, gapMs);
+}
+/** Parse a `live.m3u8` body into ordered `#EXTINF` → segment-path pairs. */
+function parseLivePlaylist(body) {
+	const lines = body.split("\n");
+	const out = [];
+	let pendingDur = null;
+	for (const raw of lines) {
+		const line = raw.trim();
+		if (line.length === 0) continue;
+		if (line.startsWith("#EXTINF:")) {
+			const v = line.slice(8).replace(/,.*$/, "");
+			const dur = Number(v);
+			pendingDur = Number.isFinite(dur) ? dur : null;
+			continue;
+		}
+		if (line.startsWith("#")) continue;
+		if (pendingDur !== null) {
+			out.push({
+				durSeconds: pendingDur,
+				segPath: line
+			});
+			pendingDur = null;
+		}
+	}
+	return out;
+}
+/** `fs.stat` size, or null when the path does not exist. */
+async function statSize(p) {
+	try {
+		return (await promises.stat(p)).size;
+	} catch {
+		return null;
+	}
+}
+/**
+* Process ONE finalized playlist entry: verify the flat file is on disk and, if
+* so, hand it to `onFinalized` (the v2 SegmentStore stats + relocates + indexes
+* it). Returns:
+*   - `'retained'` — the flat file is on disk and was handed off;
+*   - `'skipped'`  — not a relocatable epoch-named segment (caller advances past it);
+*   - `'pending'`  — a valid segment whose flat file has NOT landed on disk yet.
+*      ffmpeg's first segment is slow to flush, so the caller must RETRY this
+*      entry on a later tick instead of orphaning it.
+*
+* Unlike the old recorder, this watcher does NOT relocate or re-stat: the
+* SegmentStore owns the move + the authoritative byte count.
+*/
+async function handleSegmentEntry(outDir, entry, durMs, onFinalized, logger) {
+	const flatAbsPath = path.isAbsolute(entry.segPath) ? entry.segPath : path.join(outDir, entry.segPath);
+	const startMs = parseEpochStartMs(flatAbsPath);
+	if (startMs === null) return "skipped";
+	if (await statSize(flatAbsPath) === null) {
+		logger.debug("segment flat file not on disk yet — will retry", { meta: { path: flatAbsPath } });
+		return "pending";
+	}
+	onFinalized(startMs, durMs, flatAbsPath);
+	return "retained";
+}
+/**
+* Decide which playlist entries are FINALIZABLE this tick and their corrected
+* durations, given the previously-processed high-water mark. Pure (no I/O) so
+* the tick loop is just: read file → plan → hand each off → advance mark.
+*
+* The live tail entry is held back while recording continues: a segment's true
+* duration needs its SUCCESSOR's start (ffmpeg's first-segment EXTINF is
+* inflated by the initial PTS offset). Once `#EXT-X-ENDLIST` appears the tail
+* is flushed too — by then it is never the unreliable first segment.
+*/
+function planFinalizations(body, processed) {
+	const entries = parseLivePlaylist(body);
+	const endlist = body.includes("#EXT-X-ENDLIST");
+	const hw = entries.length < processed ? 0 : processed;
+	const finalizable = endlist ? entries.length : Math.max(0, entries.length - 1);
+	const toHandle = [];
+	for (let i = hw; i < finalizable; i++) {
+		const entry = entries[i];
+		const startMs = parseEpochStartMs(entry.segPath);
+		const nextStartMs = i + 1 < entries.length ? parseEpochStartMs(entries[i + 1].segPath) : null;
+		const durMs = startMs === null ? Math.round(entry.durSeconds * 1e3) : correctedDurMs(entry.durSeconds, startMs, nextStartMs);
+		toHandle.push({
+			entry,
+			durMs
+		});
+	}
+	return {
+		toHandle,
+		from: hw,
+		processed: Math.max(hw, finalizable)
+	};
+}
+/**
+* Start polling `<outDir>/live.m3u8`. Returns a handle whose `stop()`
+* cancels the timer. Errors during a tick are swallowed (logged at debug)
+* — a transient read race self-corrects on the next interval.
+*/
+function startSegmentWatcher(deps) {
+	const playlistPath = path.join(deps.outDir, "live.m3u8");
+	let processed = 0;
+	let stopped = false;
+	let ticking = false;
+	let pendingIndex = -1;
+	let pendingTicks = 0;
+	const tick = async () => {
+		if (stopped || ticking) return;
+		ticking = true;
+		try {
+			let body;
+			try {
+				body = await promises.readFile(playlistPath, "utf8");
+			} catch {
+				return;
+			}
+			const plan = planFinalizations(body, processed);
+			let index = plan.from;
+			for (const { entry, durMs } of plan.toHandle) {
+				if (await handleSegmentEntry(deps.outDir, entry, durMs, deps.onFinalized, deps.logger) === "pending") {
+					if (pendingIndex === index) {
+						pendingTicks++;
+						if (pendingTicks >= MAX_PENDING_TICKS) {
+							deps.logger.warn("segment file never landed — skipping", { meta: { seg: entry.segPath } });
+							pendingIndex = -1;
+							pendingTicks = 0;
+							index++;
+							continue;
+						}
+					} else {
+						pendingIndex = index;
+						pendingTicks = 1;
+					}
+					break;
+				}
+				index++;
+			}
+			if (pendingIndex !== index) {
+				pendingIndex = -1;
+				pendingTicks = 0;
+			}
+			processed = index;
+		} finally {
+			ticking = false;
+		}
+	};
+	const timer = setInterval(() => {
+		tick();
+	}, deps.intervalMs);
+	timer.unref?.();
+	return { stop() {
+		stopped = true;
+		clearInterval(timer);
+	} };
+}
+//#endregion
+//#region src/recorder/addon/readiness-restore.ts
+var ReadinessRestore = class {
+	deps;
+	pending = /* @__PURE__ */ new Map();
+	draining = false;
+	rerun = false;
+	unsub = null;
+	constructor(deps) {
+		this.deps = deps;
+	}
+	/** Seed the pending set, subscribe to readiness, and drain once immediately
+	*  (covers the already-ready case). Returns when the first drain settles. */
+	async start(items) {
+		for (const [k, v] of items) this.pending.set(k, v);
+		if (this.unsub === null) this.unsub = this.deps.subscribeReady(() => {
+			this.drain();
+		});
+		await this.drain();
+	}
+	/** Add (or replace) one pending item without re-subscribing. Does NOT drain. */
+	add(key, value) {
+		this.pending.set(key, value);
+	}
+	/** Remove one pending item (e.g. the camera was disabled before it attached). */
+	remove(key) {
+		this.pending.delete(key);
+	}
+	/** Unsubscribe from readiness. Call on shutdown. */
+	stop() {
+		this.unsub?.();
+		this.unsub = null;
+		this.pending.clear();
+	}
+	get pendingCount() {
+		return this.pending.size;
+	}
+	hasPending(key) {
+		return this.pending.has(key);
+	}
+	/** Attempt every still-pending item; repeat once if a readiness signal arrived
+	*  mid-flight. Re-entrant and self-coalescing. */
+	async drain() {
+		if (this.draining) {
+			this.rerun = true;
+			return;
+		}
+		if (this.pending.size === 0) return;
+		this.draining = true;
+		try {
+			do {
+				this.rerun = false;
+				for (const [key, value] of [...this.pending]) try {
+					await this.deps.attempt(key, value);
+					this.pending.delete(key);
+				} catch (err) {
+					this.deps.onDefer?.(key, value, err);
+				}
+			} while (this.rerun && this.pending.size > 0);
+		} finally {
+			this.draining = false;
+		}
+	}
+};
+//#endregion
+//#region src/recorder/band-engine.ts
+function toMin(hhmm) {
+	const [h, m] = hhmm.split(":");
+	return Number(h) * 60 + Number(m);
+}
+function bandActiveAt(band, date) {
+	const wd = date.getDay();
+	const prevWd = (wd + 6) % 7;
+	const t = date.getHours() * 60 + date.getMinutes();
+	const s = toMin(band.start);
+	const e = toMin(band.end);
+	const applies = (d) => band.days.length === 0 || band.days.includes(d);
+	if (s < e) return applies(wd) && t >= s && t < e;
+	if (s > e) return applies(wd) && t >= s || applies(prevWd) && t < e;
+	return applies(wd);
+}
+function activeBandAt(config, date) {
+	return config.bands.find((b) => bandActiveAt(b, date)) ?? null;
+}
+//#endregion
+//#region src/recorder/addon/band-decision.ts
+/**
+* Is an `events` band's live demand window open at `atMs`? True iff a trigger
+* the band listens for fired within `postBufferSec` of now. `preBufferSec` is
+* deliberately NOT consulted here (see file header).
+*/
+function eventsBandDemanded(band, triggers, atMs) {
+	const postMs = (band.postBufferSec ?? 0) * 1e3;
+	const fresh = (lastMs) => lastMs != null && atMs - lastMs <= postMs;
+	if (band.triggers?.motion && fresh(triggers.lastMotionMs)) return true;
+	if (band.triggers?.audioThresholdDbfs != null && fresh(triggers.lastAudioMs)) return true;
+	return false;
+}
+/**
+* Should recording (any mode) be active for this device at `at`? The live
+* attach/detach gate: enabled + a band covers `at` + that band demands now
+* (continuous always; events within `postBufferSec` of a qualifying trigger).
+*/
+function shouldRecordAt(config, triggers, at) {
+	if (!config.enabled) return false;
+	const bands = config.bands;
+	if (!bands || bands.length === 0) return false;
+	const band = activeBandAt({ bands }, at);
+	if (!band) return false;
+	if (band.mode === "continuous") return true;
+	return eventsBandDemanded(band, triggers, at.getTime());
+}
+/**
+* Should a finalized segment `[segStartMs, segEndMs]` recorded under an
+* `events` band be KEPT (else discarded)? Kept iff it overlaps any qualifying
+* trigger's full window `[trigger - preBufferSec, trigger + postBufferSec]`.
+* This is where `preBufferSec` retroactively retains pre-trigger footage.
+*/
+function segmentRetainedForEvents(segStartMs, segEndMs, band, triggers) {
+	const preMs = (band.preBufferSec ?? 0) * 1e3;
+	const postMs = (band.postBufferSec ?? 0) * 1e3;
+	const overlaps = (lastMs) => lastMs != null && segStartMs <= lastMs + postMs && segEndMs >= lastMs - preMs;
+	if (band.triggers?.motion && overlaps(triggers.lastMotionMs)) return true;
+	if (band.triggers?.audioThresholdDbfs != null && overlaps(triggers.lastAudioMs)) return true;
+	return false;
+}
+//#endregion
+//#region src/recorder/addon/recording-controller.ts
+/**
+* recorder recording controller — the B2 continuous-band write path.
+*
+* Owns, per (deviceId, profile), the lifecycle of:
+*   - a broker stream lease (`getStreamWithCodec`, released on detach),
+*   - an ffmpeg `SegmentWriter` (passthrough segmenter into a temp outDir),
+*   - a `live.m3u8` `SegmentWatcher` that hands each finalized flat segment to
+*     the v2 `SegmentStore.onFinalized` (stat + relocate + index).
+*
+* Per device it decides whether a CONTINUOUS band is active right now
+* (`shouldRecordContinuousAt`) and ensures the writer set is running iff so.
+* It re-evaluates on three triggers:
+*   1. `setDeviceConfig` (operator changed the bands / enable),
+*   2. a periodic tick (catches band boundaries crossed with no config change),
+*   3. a `stream-broker` ready transition (boot restore — via `ReadinessRestore`).
+*
+* EVENTS bands are treated as "not recording continuously" in B2 — B3 adds
+* trigger-gating. The enable intent is persisted in durable-state by the
+* config-store, so `restoreEnabledDevices` on boot re-attaches every device
+* whose persisted config records continuously now.
+*
+* Source acquisition rides the broker's single source dial: the controller
+* gates each broker call on the broker's readiness via the cached capability
+* handle (`useCapability(...).call(fn)`) — no bespoke retry/backoff, the
+* `ReadinessRegistry` is the single source of truth.
+*/
+var DEFAULT_WATCH_INTERVAL_MS = 2e3;
+/** Periodic re-evaluation to catch band boundaries crossed with no config change. */
+var TICK_MS = 3e4;
+var RecordingController = class {
+	deps;
+	active = /* @__PURE__ */ new Map();
+	/** Latest qualifying trigger timestamps per device — drives `events`-band gating. */
+	triggers = /* @__PURE__ */ new Map();
+	restore = null;
+	tickTimer = null;
+	stopped = false;
+	constructor(deps) {
+		this.deps = deps;
+	}
+	now() {
+		return this.deps.now?.() ?? Date.now();
+	}
+	/**
+	* Boot restore: seed the readiness-gated queue with every persisted device and
+	* (re)evaluate each on every `stream-broker` ready transition. Also arms the
+	* periodic tick. Idempotent — safe to call once after the index is hydrated.
+	*/
+	async start() {
+		if (this.stopped) return;
+		let ids;
+		try {
+			ids = await this.deps.enabledDeviceIds();
+		} catch (err) {
+			this.deps.logger.warn("recorder controller: reading persisted devices failed", { meta: { error: errMsg(err) } });
+			ids = [];
+		}
+		this.restore = new ReadinessRestore({
+			subscribeReady: (handler) => this.deps.onBrokerReady(handler),
+			attempt: async (deviceId) => {
+				await this.evaluateDevice(deviceId);
+			},
+			onDefer: (deviceId, _v, err) => this.deps.logger.warn("recorder controller: device evaluate deferred (retries on next broker ready)", {
+				tags: { deviceId },
+				meta: { error: errMsg(err) }
+			})
+		});
+		if (this.tickTimer === null) {
+			this.tickTimer = setInterval(() => {
+				this.tick();
+			}, TICK_MS);
+			this.tickTimer.unref?.();
+		}
+		await this.restore.start(ids.map((id) => [id, true]));
+	}
+	/** Re-evaluate every currently-tracked OR active device on the periodic tick. */
+	async tick() {
+		if (this.stopped) return;
+		const ids = new Set(this.active.keys());
+		let persisted = [];
+		try {
+			persisted = await this.deps.enabledDeviceIds();
+		} catch {}
+		for (const id of persisted) ids.add(id);
+		for (const id of ids) try {
+			await this.evaluateDevice(id);
+		} catch (err) {
+			this.deps.logger.warn("recorder controller: tick evaluate failed", {
+				tags: { deviceId: id },
+				meta: { error: errMsg(err) }
+			});
+		}
+	}
+	/**
+	* Re-evaluate one device after a config change (called from `setDeviceConfig`).
+	* Failures propagate so the caller can surface them, but the persisted config
+	* has already been written by the time this runs.
+	*/
+	async onConfigChanged(deviceId) {
+		if (this.stopped) return;
+		await this.evaluateDevice(deviceId);
+	}
+	/**
+	* One profile's ffmpeg writer exhausted its bounded inner restarts and gave
+	* up. The device is still in `active` with a dead writer, so `evaluateDevice`
+	* would short-circuit at "already recording — converged" and never recover.
+	* Detach the WHOLE device (releases every broker lease + stops watchers, so the
+	* idle source can re-dial cleanly), then re-evaluate: if the band still demands
+	* recording, `evaluateDevice` re-queues + re-attaches a fresh writer set. If
+	* the broker is not ready, the re-attach throws and the device stays on the
+	* readiness queue (retried on the next broker ready) — and the periodic tick is
+	* the backstop. Bounded OUTER retry (TICK_MS cadence), never a tight loop.
+	*/
+	async recoverWriterGaveUp(deviceId) {
+		if (this.stopped) return;
+		this.deps.logger.warn("recorder: writer gave up — detaching + re-evaluating device", { tags: { deviceId } });
+		try {
+			await this.detachDevice(deviceId);
+			await this.evaluateDevice(deviceId);
+		} catch (err) {
+			this.restore?.add(deviceId, true);
+			this.deps.logger.warn("recorder: writer give-up recovery deferred (retries on next broker ready/tick)", {
+				tags: { deviceId },
+				meta: { error: errMsg(err) }
+			});
+		}
+	}
+	/** Current trigger state for a device (cold default = no triggers seen). */
+	triggersFor(deviceId) {
+		return this.triggers.get(deviceId) ?? {
+			lastMotionMs: null,
+			lastAudioMs: null
+		};
+	}
+	/**
+	* Record a qualifying trigger (motion/audio) for a device and converge: an
+	* `events` band whose window this opens attaches now; the periodic tick
+	* detaches it once `postBufferSec` elapses. Called from the addon's
+	* EventCapture subscription. The qualification test (motion detected / audio
+	* over threshold) is done upstream — by the time we're here, it qualified.
+	*/
+	async onTrigger(deviceId, source, atMs) {
+		if (this.stopped) return;
+		const prev = this.triggersFor(deviceId);
+		this.triggers.set(deviceId, {
+			lastMotionMs: source === "motion" ? atMs : prev.lastMotionMs,
+			lastAudioMs: source === "audio" ? atMs : prev.lastAudioMs
+		});
+		await this.evaluateDevice(deviceId);
+	}
+	/**
+	* Decide-and-converge for one device: if its active band demands recording now
+	* (continuous always; events within `postBufferSec` of a trigger) and the
+	* device is enabled, ensure its writer set is running; otherwise stop it.
+	* Re-attaches via the readiness queue if the broker is not ready (the broker
+	* call throws → `ReadinessRestore.attempt` defers → retried on next ready).
+	*/
+	async evaluateDevice(deviceId) {
+		if (this.stopped) return;
+		const config = await this.deps.loadConfig(deviceId);
+		if (!shouldRecordAt(config, this.triggersFor(deviceId), new Date(this.now()))) {
+			await this.detachDevice(deviceId);
+			this.restore?.remove(deviceId);
+			return;
+		}
+		if (this.active.has(deviceId)) return;
+		this.restore?.add(deviceId, true);
+		const profiles = await this.resolveProfiles(deviceId, config.profiles);
+		if (profiles.length === 0) throw new Error(`recorder controller: no assigned broker sources for device ${deviceId}`);
+		const segmentSeconds = config.segmentSeconds ?? this.deps.segmentSeconds;
+		const recordings = [];
+		try {
+			for (const profile of profiles) recordings.push(await this.attachProfile(deviceId, profile, segmentSeconds));
+		} catch (err) {
+			for (const r of recordings) await this.teardownProfile(deviceId, r);
+			throw err;
+		}
+		this.active.set(deviceId, recordings);
+		this.deps.logger.info("recorder pinned broker source(s) for recording", {
+			tags: { deviceId },
+			meta: {
+				profiles,
+				segmentSeconds,
+				pipelineKeys: recordings.map((r) => r.pipelineKey)
+			}
+		});
+	}
+	/**
+	* Pick which profiles to record. The broker enumerates assigned profile slots,
+	* deduped by physical source (`selectAssignedProfileSlots`) so the same camera
+	* encoder is never recorded twice. An operator `override` DISABLES the
+	* unselected profiles (assigned ∩ selection); a selection matching none of the
+	* assigned sources is ignored (record every assigned source — minimum of 1).
+	*/
+	async resolveProfiles(deviceId, override) {
+		const assigned = selectAssignedProfileSlots(await this.deps.brokerCall(() => this.deps.api.streamBroker.listAllProfileSlots.query()), deviceId).map((slot) => slot.profile);
+		if (!override || override.length === 0) return assigned;
+		const selected = assigned.filter((p) => override.includes(p));
+		return selected.length > 0 ? selected : assigned;
+	}
+	/**
+	* Attach one (device, profile): acquire the broker source, mkdir the temp
+	* outDir, spawn the SegmentWriter, and start the watcher that feeds finalized
+	* flat segments into `SegmentStore.onFinalized`.
+	*/
+	async attachProfile(deviceId, profile, segmentSeconds) {
+		const source = await this.deps.brokerCall(() => this.deps.api.streamBroker.getStreamWithCodec.mutate({
+			deviceId,
+			video: "copy",
+			audio: "aac",
+			profile,
+			...this.deps.consumerHostname !== void 0 ? { hostname: this.deps.consumerHostname } : {},
+			tag: `recorder:${deviceId}/${profile}`
+		}));
+		const outDir = path.join(this.deps.tmpRoot, String(deviceId), profile);
+		await promises.mkdir(outDir, { recursive: true });
+		const writer = new SegmentWriter({
+			rtspUrl: source.url,
+			outDir,
+			segmentSeconds
+		}, {
+			spawn: this.deps.spawn,
+			logger: this.deps.logger,
+			onGaveUp: () => {
+				this.recoverWriterGaveUp(deviceId);
+			}
+		});
+		writer.start();
+		const placement = this.resolvePlacement(profile);
+		return {
+			profile,
+			writer,
+			watcher: startSegmentWatcher({
+				outDir,
+				intervalMs: this.deps.watchIntervalMs > 0 ? this.deps.watchIntervalMs : DEFAULT_WATCH_INTERVAL_MS,
+				onFinalized: (startMs, durMs, flatAbsPath) => {
+					this.handleFinalizedSegment(deviceId, profile, placement, startMs, durMs, flatAbsPath);
+				},
+				logger: this.deps.logger
+			}),
+			pipelineKey: source.pipelineKey,
+			outDir
+		};
+	}
+	/**
+	* Index a finalized segment — unless it was recorded under an `events` band
+	* and falls OUTSIDE every trigger's `[trigger-preBufferSec, trigger+postBufferSec]`
+	* window, in which case it is discarded (deleted, never indexed). Continuous
+	* footage (or any segment with no active events band) is always indexed: the
+	* keep/discard gate touches `events`-mode segments only, so the continuous
+	* path is unchanged.
+	*/
+	async handleFinalizedSegment(deviceId, profile, placement, startMs, durMs, flatAbsPath) {
+		try {
+			const band = activeBandAt({ bands: (await this.deps.loadConfig(deviceId)).bands ?? [] }, new Date(startMs + durMs));
+			if (band?.mode === "events" && !segmentRetainedForEvents(startMs, startMs + durMs, band, this.triggersFor(deviceId))) {
+				await promises.unlink(flatAbsPath).catch(() => {});
+				return;
+			}
+			await this.deps.segmentStore.onFinalized({
+				deviceId,
+				profile,
+				locationId: placement.id,
+				locationRoot: placement.root,
+				flatAbsPath,
+				startMs,
+				durMs
+			});
+		} catch (err) {
+			this.deps.logger.warn("recorder: onFinalized failed", {
+				tags: { deviceId },
+				meta: {
+					profile,
+					error: errMsg(err)
+				}
+			});
+		}
+	}
+	/**
+	* Resolve the storage location a profile writes to: `low` → the recordingsLow
+	* location when present, every other profile → the recordings location. Falls
+	* back to the first resolved location when the preferred type is absent — both
+	* types resolve to the same path today, so the split is free-and-future-proof.
+	*/
+	resolvePlacement(profile) {
+		const locations = this.deps.locations();
+		if (locations.length === 0) throw new Error("recorder controller: no recordings storage locations resolved");
+		const preferLow = profile === "low";
+		return locations.find((l) => preferLow ? l.id === "recordingsLow" : l.id === "recordings") ?? locations[0];
+	}
+	/** Stop one profile's writer + watcher and release its broker lease. */
+	async teardownProfile(deviceId, r) {
+		try {
+			r.watcher.stop();
+		} catch {}
+		try {
+			r.writer.stop();
+		} catch {}
+		try {
+			await this.deps.api.streamBroker.releaseStreamWithCodec.mutate({ pipelineKey: r.pipelineKey });
+		} catch (err) {
+			this.deps.logger.warn("recorder: releaseStreamWithCodec failed", {
+				tags: { deviceId },
+				meta: {
+					profile: r.profile,
+					pipelineKey: r.pipelineKey,
+					error: errMsg(err)
+				}
+			});
+		}
+	}
+	/** Stop every profile recording for a device (no-op when not recording). */
+	async detachDevice(deviceId) {
+		const recordings = this.active.get(deviceId);
+		if (!recordings) return;
+		this.active.delete(deviceId);
+		for (const r of recordings) await this.teardownProfile(deviceId, r);
+		this.deps.logger.info("recorder unpinned broker source(s) — recording stopped", {
+			tags: { deviceId },
+			meta: { pipelineKeys: recordings.map((r) => r.pipelineKey) }
+		});
+	}
+	/** Tear EVERYTHING down: timer, restore subscription, every writer/watcher/lease. */
+	async stop() {
+		this.stopped = true;
+		if (this.tickTimer !== null) {
+			clearInterval(this.tickTimer);
+			this.tickTimer = null;
+		}
+		this.restore?.stop();
+		this.restore = null;
+		for (const deviceId of [...this.active.keys()]) await this.detachDevice(deviceId);
+	}
+};
+/** Build a `stream-broker` readiness scope for one node. */
+function brokerScope(nodeId) {
+	return {
+		type: "node",
+		nodeId
+	};
+}
+/** Default broker readiness gate timeout (ms) — matches the old recorder. */
+var BROKER_READY_TIMEOUT_MS = 1e4;
+/** Wrap a cached capability handle into the `brokerCall` gate the controller needs. */
+function makeBrokerCall(handle) {
+	return (fn) => handle.call(fn, BROKER_READY_TIMEOUT_MS);
+}
+//#endregion
+//#region src/recorder/addon/recording-hub-host.ts
+/**
+* Resolve the host a REMOTE recording node should use to dial the hub-only
+* stream-broker's restream port.
+*
+* The broker mints `127.0.0.1` restream URLs (hub-local). When the operator
+* designates an AGENT as the recording node, that agent's recorder must pull
+* from the hub, so it needs the hub's cluster-resolvable host. Resolution
+* order:
+*
+*   1. `override` — the `recordingHubHostname` global setting, when the
+*      operator set one explicitly (e.g. the auto-derived host isn't reachable
+*      for RTSP on the recording interface).
+*   2. `hubUrl` — derived from the agent's `CAMSTACK_HUB_URL` (the address it
+*      already uses to reach the hub). The RTSP restream port differs from the
+*      hub API port, but the HOST is the same — only the host is extracted.
+*
+* Returns `undefined` when neither yields a host (the caller logs and the pull
+* stays hub-local, which simply won't reach a remote node — never a crash).
+*
+* Pure: the env string is passed in (not read here) so it can be unit-tested.
+*/
+function resolveRecordingHubHostname(override, hubUrl) {
+	const trimmedOverride = override?.trim();
+	if (trimmedOverride !== void 0 && trimmedOverride.length > 0) return trimmedOverride;
+	return extractHost(hubUrl);
+}
+/** Extract the bare host from a URL/authority string, scheme + port optional. */
+function extractHost(raw) {
+	const value = raw?.trim();
+	if (value === void 0 || value.length === 0) return void 0;
+	try {
+		const parsed = new URL(value);
+		if (parsed.hostname.length > 0) return parsed.hostname;
+	} catch {}
+	const authority = value.replace(/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//, "").split("/")[0] ?? "";
+	if (authority.startsWith("[")) {
+		const end = authority.indexOf("]");
+		if (end > 0) return authority.slice(0, end + 1);
+	}
+	const host = authority.split(":")[0] ?? "";
+	return host.length > 0 ? host : void 0;
+}
+//#endregion
+//#region src/recorder/addon/index.ts
+/**
+* recorder addon SHELL — recording + storage-evictable providers on the
+* unit-tested recorder core (`recorder/*.ts`).
+*
+* B1 scope (THIS file): the addon lifecycle + provider wiring with NO ffmpeg
+* and NO live recording. It resolves the `recordings` / `recordingsLow`
+* storage roots via the `storage` cap, hydrates the v2 `RecordingIndex` from
+* `storage.list` for every persisted-config device on boot, persists per-device
+* band config via durable-state, answers the `recording` cap reads from the
+* index, prunes footage via `selectEvictions` + `SegmentStore.evict`, and
+* mounts the v2 `StorageEvictableProvider` for disk-pressure eviction.
+*
+* DEFERRED to B2/B3 (search "B2/B3 HOOK" below for the exact insertion points):
+*   - ffmpeg `SegmentWriter` (per-profile passthrough segmenter)
+*   - segment watcher → `SegmentStore.onFinalized` (stat + relocate + index)
+*   - `BandEngine` attach/detach on enable/disable (`activeBandAt`/`bandActiveAt`)
+*   - `EventCapture` (motion/audio markers feeding events-mode bands)
+*   - playback data-plane (getPlaybackManifest currently STUBs null)
+*
+* The old recorder (`addon-pipeline/src/recorder`) stays the live `recording`
+* provider until the controller swaps the manifest entry in a later step — this
+* file ships dormant (separate tree, not wired into the manifest yet).
+*/
+var DEFAULT_CONFIG = {
+	segmentSeconds: 4,
+	watchIntervalMs: 2e3
+};
+/** Playback-marker window padding around a motion event (EventMap only; the
+*  controller's events-band gating uses the raw trigger ms, not this pad). */
+var MARKER_PAD_PRE_MS = 2e3;
+var MARKER_PAD_POST_MS = 5e3;
+/** This addon's manifest id + the playback data-plane prefix — together they
+*  form the hub reverse-proxy client path `/addon/recorder/playback`. */
+var RECORDER_ADDON_ID = "recorder";
+var PLAYBACK_PREFIX = "playback";
+/** Default designated recording node (`recordingNodeId` global setting). The
+*  stream-broker is hub-only and recording is a single-node global function, so
+*  the hub is the safe default — mirrors pipeline-analytics' post-processing
+*  node gate. */
+var RECORDING_NODE_DEFAULT = "hub";
+/** Node the hub-only `stream-broker` runs on. Every recorder — on the hub or on
+*  a designated agent — gates on, and pulls from, THIS node's broker. */
+var BROKER_HOST_NODE_ID = "hub";
+var RecorderV2Addon = class extends BaseAddon {
+	nodeId = "hub";
+	/** True when THIS node is the designated recording node (`recordingNodeId`).
+	*  Every other node stays fully inert — registers no providers, serves no
+	*  playback, runs no controller. Resolved in `onInitialize`. */
+	isRecordingNode = true;
+	index = new RecordingIndex();
+	segmentStore = null;
+	/** Continuous + events band write-path controller (ffmpeg writers + watchers). */
+	controller = null;
+	/** Per-device motion/audio markers for playback (B3 events feed the controller). */
+	eventMap = new EventMap();
+	/** Unsubscribe handle for the EventCapture motion subscription. */
+	eventUnsub = null;
+	/** Resolved recordings locations (id + root). Refreshed on boot + rescan. */
+	resolvedLocations = [];
+	/** Base URL of the playback HTTP data-plane, null until served in onHubReachable. */
+	playbackBaseUrl = null;
+	constructor() {
+		super({ ...DEFAULT_CONFIG });
+	}
+	async onInitialize() {
+		const raw = this.ctx.kernel.localNodeId ?? this.ctx.id;
+		this.nodeId = raw.includes("/") ? raw.split("/")[0] : raw;
+		const store = await this.ctx.settings?.readAddonStore() ?? {};
+		const rawNode = store["recordingNodeId"];
+		const designated = typeof rawNode === "string" && rawNode.length > 0 ? rawNode : RECORDING_NODE_DEFAULT;
+		this.isRecordingNode = this.nodeId === designated;
+		if (!this.isRecordingNode) {
+			this.ctx.logger.info("recorder INERT on this node — recording assigned elsewhere", { meta: {
+				ownNodeId: this.nodeId,
+				designatedNode: designated
+			} });
+			return { providers: [] };
+		}
+		const rawHubHostname = store["recordingHubHostname"];
+		const consumerHostname = this.nodeId === BROKER_HOST_NODE_ID ? void 0 : resolveRecordingHubHostname(typeof rawHubHostname === "string" ? rawHubHostname : void 0, process.env["CAMSTACK_HUB_URL"]);
+		if (this.nodeId !== BROKER_HOST_NODE_ID) {
+			this.ctx.logger.info("recorder is a REMOTE recording node — pulling broker streams cross-node", { meta: {
+				ownNodeId: this.nodeId,
+				brokerHost: BROKER_HOST_NODE_ID,
+				consumerHostname: consumerHostname ?? "(unresolved)"
+			} });
+			if (consumerHostname === void 0) this.ctx.logger.warn("recorder: could not resolve the hub host for cross-node pull — set the `recordingHubHostname` global setting or CAMSTACK_HUB_URL; recording will not reach this node", { meta: { ownNodeId: this.nodeId } });
+		}
+		const segmentStoreDeps = {
+			index: this.index,
+			list: (input) => this.ctx.api.storage.list.query(input),
+			deletePath: (input) => this.ctx.api.storage.delete.mutate(input),
+			statBytes: async (absPath) => (await promises.stat(absPath)).size,
+			moveFile: async (fromAbs, toAbs) => {
+				await promises.mkdir(path.dirname(toAbs), { recursive: true });
+				await promises.rename(fromAbs, toAbs);
+			},
+			logger: { warn: (message, extras) => this.ctx.logger.warn(message, { meta: { extras } }) }
+		};
+		this.segmentStore = new SegmentStore(segmentStoreDeps);
+		const tmpRoot = path.join(this.ctx.dataDir, "rec-tmp");
+		const brokerHandle = this.ctx.useCapability("stream-broker", brokerScope(BROKER_HOST_NODE_ID));
+		this.controller = new RecordingController({
+			api: this.ctx.api,
+			logger: this.ctx.logger,
+			nodeId: this.nodeId,
+			segmentStore: this.segmentStore,
+			loadConfig: (deviceId) => loadDeviceConfig(this.configStore(), deviceId),
+			enabledDeviceIds: async () => [...(await readDeviceConfigs(this.configStore())).keys()],
+			locations: () => this.resolvedLocations,
+			tmpRoot,
+			spawn,
+			segmentSeconds: this.config.segmentSeconds,
+			watchIntervalMs: this.config.watchIntervalMs,
+			...consumerHostname !== void 0 ? { consumerHostname } : {},
+			onBrokerReady: (handler) => this.ctx.onCapabilityStateChange("stream-broker", brokerScope(BROKER_HOST_NODE_ID), (state) => {
+				if (state === "ready") handler();
+			}),
+			brokerCall: makeBrokerCall(brokerHandle)
+		});
+		const recordingProvider = buildRecordingProvider({
+			index: this.index,
+			segmentStore: this.segmentStore,
+			nodeId: this.nodeId,
+			logger: this.ctx.logger,
+			configStore: this.configStore(),
+			locations: () => this.resolvedLocations,
+			refreshLocations: () => this.refreshLocations(),
+			capacity: (root) => this.locationCapacity(root),
+			hydrateDevice: (deviceId, locations) => hydrateDeviceFromStorage(this.ctx.api, this.index, deviceId, locations, this.ctx.logger),
+			onConfigChanged: (deviceId) => this.controller?.onConfigChanged(deviceId) ?? Promise.resolve(),
+			dataDir: this.ctx.dataDir,
+			playbackBaseUrl: () => this.playbackBaseUrl
+		});
+		const evictableProvider = new StorageEvictableProvider({
+			index: this.index,
+			store: this.segmentStore
+		});
+		try {
+			const handler = createFileDataPlaneHandler({ getRoots: () => this.playbackRoots() });
+			const served = await this.ctx.dataPlane?.serve({
+				prefix: PLAYBACK_PREFIX,
+				access: "authenticated",
+				handler
+			});
+			this.playbackBaseUrl = served ? `/addon/${RECORDER_ADDON_ID}/${PLAYBACK_PREFIX}` : null;
+			this.ctx.logger.info("recorder playback data-plane served", { meta: {
+				clientBase: this.playbackBaseUrl ?? "(no dataPlane facility)",
+				internal: served?.baseUrl
+			} });
+		} catch (err) {
+			this.ctx.logger.warn("recorder playback data-plane failed to serve", { meta: { error: errMsg(err) } });
+		}
+		this.ctx.logger.info("recorder addon started (continuous write path active)", {
+			tags: { nodeId: this.nodeId },
+			meta: {
+				segmentSeconds: this.config.segmentSeconds,
+				watchIntervalMs: this.config.watchIntervalMs
+			}
+		});
+		return { providers: [{
+			capability: recordingCapability,
+			provider: recordingProvider
+		}, {
+			capability: storageEvictableCapability,
+			provider: evictableProvider
+		}] };
+	}
+	async onShutdown() {
+		this.eventUnsub?.();
+		this.eventUnsub = null;
+		await this.controller?.stop();
+		this.controller = null;
+		this.segmentStore = null;
+	}
+	/**
+	* Boot hydrate: once the hub is reachable (`ctx.api.*` safe), resolve the
+	* recordings locations and rebuild the in-memory index from `storage.list`
+	* for every device that has a persisted config. The list result is the
+	* ground truth — segment paths encode start/dur/bytes, so the index can never
+	* drift from disk.
+	*/
+	async onHubReachable() {
+		if (!this.isRecordingNode) return;
+		this.resolvedLocations = await resolveRecordingsLocations(this.ctx.api, this.ctx.logger);
+		if (this.resolvedLocations.length === 0) {
+			this.ctx.logger.warn("recorder: no recordings storage locations resolved — index not hydrated");
+			return;
+		}
+		let configs;
+		try {
+			configs = await readDeviceConfigs(this.configStore());
+		} catch (err) {
+			this.ctx.logger.warn("recorder: reading persisted device configs failed — skipping hydrate", { meta: { error: errMsg(err) } });
+			return;
+		}
+		for (const deviceId of configs.keys()) await hydrateDeviceFromStorage(this.ctx.api, this.index, deviceId, this.resolvedLocations, this.ctx.logger);
+		this.ctx.logger.info("recorder: hydrated index from storage", { meta: {
+			deviceCount: configs.size,
+			locationCount: this.resolvedLocations.length
+		} });
+		const store = this.segmentStore;
+		if (store) try {
+			await runRedundancyJanitor({
+				deviceIds: [...configs.keys()],
+				segmentsFor: (deviceId, profile) => this.index.segments(deviceId, profile),
+				evict: (location, rows) => store.evict(location, rows),
+				logger: this.ctx.logger
+			});
+		} catch (err) {
+			this.ctx.logger.warn("recorder: redundancy janitor failed", { meta: { error: errMsg(err) } });
+		}
+		try {
+			await this.controller?.start();
+		} catch (err) {
+			this.ctx.logger.warn("recorder: controller start failed", { meta: { error: errMsg(err) } });
+		}
+		if (this.eventUnsub === null) this.eventUnsub = subscribeEventCapture({
+			eventBus: this.ctx.eventBus,
+			map: this.eventMap,
+			padPreMs: MARKER_PAD_PRE_MS,
+			padPostMs: MARKER_PAD_POST_MS,
+			onMotion: (deviceId, atMs) => {
+				this.controller?.onTrigger(deviceId, "motion", atMs);
+			}
+		});
+	}
+	/** Re-resolve recordings locations (rescanStorage picks up newly-added disks). */
+	async refreshLocations() {
+		this.resolvedLocations = await resolveRecordingsLocations(this.ctx.api, this.ctx.logger);
+		return this.resolvedLocations;
+	}
+	/**
+	* Roots the playback data-plane handler searches, IN ORDER: `<dataDir>/playback`
+	* FIRST (the freshly-written master/variant `.m3u8` playlists), then every
+	* recordings location root (the segment `.m4s` files at
+	* `<root>/<deviceId>/<profile>/Y/M/D/H/<file>`). Playlists-first matters: the
+	* OLD recorder left stale `<recordingsRoot>/<deviceId>/master.m3u8` playlists
+	* that would otherwise shadow ours; segments never collide (only `.m4s` live in
+	* the location roots, only `.m3u8` in the playback dir), so the two form one
+	* served tree with our playlists authoritative.
+	*/
+	playbackRoots() {
+		return [path.join(this.ctx.dataDir, "playback"), ...this.resolvedLocations.map((l) => l.root)];
+	}
+	/** Free + total bytes on a location's volume (`statfs`); null when unstattable. */
+	async locationCapacity(root) {
+		try {
+			const st = await promises.statfs(root);
+			return {
+				availableBytes: st.bavail * st.bsize,
+				totalBytes: st.blocks * st.bsize
+			};
+		} catch {
+			return {
+				availableBytes: null,
+				totalBytes: null
+			};
+		}
+	}
+	/**
+	* Global settings surfaced in the admin UI (and persisted to the addon
+	* store). The cluster Recording tab drives `recordingNodeId` via a node
+	* picker; `recordingHubHostname` is an advanced override for cross-node
+	* pulls. Both take effect on addon restart (read once in `onInitialize`).
+	*/
+	globalSettingsSchema() {
+		return this.schema({ sections: [{
+			id: "cluster-recording",
+			title: "Cluster recording",
+			description: "Which node runs recording (continuous + events write path). A SINGLE node — no multi-node balancing; every other node stays fully inert. Default: hub.",
+			columns: 1,
+			fields: [{
+				type: "text",
+				key: "recordingNodeId",
+				label: "Recording node",
+				description: "Node id that records + serves playback (e.g. \"hub\"). Leave \"hub\" unless you intentionally move recording to an agent. Takes effect on addon restart.",
+				default: RECORDING_NODE_DEFAULT
+			}, {
+				type: "text",
+				key: "recordingHubHostname",
+				label: "Hub host (cross-node)",
+				description: "Advanced: only used when the recording node is an AGENT. The hub's host the agent dials to pull broker streams (the RTSP restream port must be reachable there). Leave empty to auto-derive from the agent's hub connection.",
+				default: ""
+			}]
+		}] });
+	}
+	/** The addon-store slice config-store reads/writes the deviceId→config blob on. */
+	configStore() {
+		const settings = this.ctx.settings;
+		if (!settings) throw new Error("RecorderV2Addon: ctx.settings unavailable — cannot persist recording config");
+		return {
+			readAddonStore: () => settings.readAddonStore(),
+			writeAddonStore: (patch) => settings.writeAddonStore(patch)
+		};
+	}
+};
+//#endregion
+export { RecorderV2Addon as default };