@camstack/addon-export-hap 1.2.128 → 1.2.129

package/dist/hap-export.addon.mjs

@@ -5,7 +5,7 @@ import * as path from "node:path";
 import { join } from "node:path";
 import { createWriteStream, readFileSync } from "node:fs";
 import * as fs from "node:fs/promises";
-import { mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import { once } from "node:events";
 import { createSocket } from "node:dgram";
 import { networkInterfaces } from "node:os";
@@ -5399,7 +5399,7 @@ var ZodIssueCode = {
 var ZodFirstPartyTypeKind;
 ZodFirstPartyTypeKind || (ZodFirstPartyTypeKind = {});
 //#endregion
-//#region ../types/dist/sleep-CiR4z7r9.mjs
+//#region ../types/dist/sleep-CopaBJss.mjs
 /**
 * The audio chunk plane's byte format, and the ONE expansion from a coded
 * window to float samples (D455).
@@ -5599,6 +5599,12 @@ Object.fromEntries([
 		icon: "circle-dot",
 		order: 40
 	},
+	{
+		id: "clips",
+		label: "Clips",
+		icon: "clapperboard",
+		order: 41
+	},
 	{
 		id: "engine",
 		label: "Inference Engine",
@@ -9665,20 +9671,86 @@ var StorageCleanupJobSchema = object({
 });
 var StorageCleanupStatusInputSchema = object({ jobId: string().optional() });
 /**
-* The one typed state of a storage location. Authoritative Zod schema — the TS
-* alias below is `z.infer<>` of it, never a second spelling.
+* The storage-location STATE MODEL (D385) — one typed state, one policy module.
+*
+* A location's state used to be split across two authorities: the typed
+* `enabled` field (THE write switch since D383) and an untyped `config.readOnly`
+* key. They did not mean the same thing — `enabled: false` was still evicted
+* under disk pressure while `config.readOnly` was deliberately excluded — and
+* neither name said which. Every consumer re-derived the difference, and the
+* three questions that actually matter were answered in six places.
+*
+* This module is the ONLY place in the repo allowed to interpret the state. It
+* answers three questions and nothing else:
+*
+*   - may this location be WRITTEN to?   {@link modeMayWrite}
+*   - may this location be READ?          {@link modeMayRead}
+*   - what is its eviction policy?        {@link evictionPolicyForMode}
+*
+* | mode       | write | read | eviction                       |
+* | ---------- | ----- | ---- | ------------------------------ |
+* | `active`   | yes   | yes  | `normal` (pressure + usage cap) |
+* | `readonly` | no    | yes  | `never`                        |
+* | `drain`    | no    | yes  | `drain` (paced, until empty)   |
+* | `disabled` | no    | no   | `never`                        |
+*
+* `scripts/check-storage-location-mode-single-owner.ts` fails the build when
+* anything outside this module reads `config['readOnly']` or compares `enabled`
+* directly. A rule nothing checks has already been broken somewhere.
 */
-var StorageLocationModeSchema = _enum([
+var STORAGE_LOCATION_MODES = [
 	"active",
 	"readonly",
 	"drain",
 	"disabled"
-]);
+];
+/**
+* The one typed state of a storage location. Authoritative Zod schema — the TS
+* alias below is `z.infer<>` of it, never a second spelling.
+*/
+var StorageLocationModeSchema = _enum(STORAGE_LOCATION_MODES);
 _enum([
 	"normal",
 	"never",
 	"drain"
 ]);
+/** Is this mode a write target? Only `active` is. */
+function modeMayWrite(mode) {
+	return mode === "active";
+}
+/**
+* The mode a LEGACY row implies, or `null` when it implies nothing — the row is
+* already stamped, or it carried neither flag.
+*
+* Both legacy flags fold to `readonly`, which is the CONSERVATIVE direction: a
+* state change must never start deleting footage on its own, and it must never
+* make footage that was still being served disappear. `enabled: false` used to
+* leave the location evictable under pressure; folding it to `readonly` stops
+* that, which is a strictly safer answer than the one it replaces.
+*/
+function legacyModeOf(location) {
+	if (location.mode !== void 0) return null;
+	if (location.config["readOnly"] === true) return "readonly";
+	if (location.enabled === false) return "readonly";
+	return null;
+}
+/**
+* The state of a location, stamped or folded. THE one interpretation: a row
+* that predates D385 is never ambiguous, and a stamped `mode` always wins over
+* whatever the legacy pair still says.
+*/
+function resolveLocationMode(location) {
+	return (isStorageLocationMode(location.mode) ? location.mode : void 0) ?? legacyModeOf(location) ?? "active";
+}
+/** Is this one of the four states? The stamped value crosses a wire, and a
+*  value nobody defined must not be rendered as if it were a state. */
+function isStorageLocationMode(value) {
+	return STORAGE_LOCATION_MODES.some((mode) => mode === value);
+}
+/** May this location be written to? */
+function mayWriteToLocation(location) {
+	return modeMayWrite(resolveLocationMode(location));
+}
 /**
 * `StorageLocationType` — an addon-declared id that identifies the *kind* of
 * storage a location serves. Defined here (not in `capabilities/storage.cap.ts`)
@@ -14965,6 +15037,8 @@ method(object({
 	deviceId: number(),
 	capName: string(),
 	wrapperAddonId: string(),
+	/** The `ClipSource.source` id to toggle. Absent = all of the addon's. */
+	sourceId: string().optional(),
 	active: boolean()
 }), _void(), {
 	kind: "mutation",
@@ -24943,29 +25017,257 @@ var ClipSchema = object({
 	holes: array(object({
 		startMs: number(),
 		endMs: number()
-	})).optional()
+	})).optional(),
+	/**
+	* A URL that MAY produce this clip's still, asked only for rows actually on
+	* screen. The opposite of {@link ClipSchema.thumbnail}: that one is VOUCHED
+	* (a JPEG is already on disk), this one is an offer. The route answers 200
+	* with the image, or 204 with `x-camstack-reason` when it could not mint one
+	* — a surface latches that refusal to the instant rather than retrying.
+	*
+	* Never both: a clip with a vouched `thumbnail` needs no mint.
+	*/
+	thumbnailMint: string().optional(),
+	/**
+	* Why no still will be produced for this clip RIGHT NOW — set when the
+	* provider already knows, so the surface draws the glyph and the reason
+	* instead of firing a mint that cannot succeed.
+	*
+	* `sleeping` — a standalone battery camera; a read would be a wake (D549 4).
+	* `camera-refused` — the camera answered the CoverPreview with a refusal.
+	* `no-keyframe` — the window holds no decodable I-frame (an event that sits
+	*   inside no file is the measured case).
+	* `unsupported` — this source cannot mint stills at all.
+	*/
+	thumbnailUnavailable: object({ reason: _enum([
+		"sleeping",
+		"camera-refused",
+		"no-keyframe",
+		"unsupported"
+	]) }).optional(),
+	/**
+	* When the catalog this row came from was last CONFIRMED against the device.
+	* Absent means "this row was read live". A persisted catalog served while a
+	* camera sleeps carries the age it really has — a cached list is never drawn
+	* as current (D549 13).
+	*/
+	catalogAsOf: number().optional(),
+	/**
+	* The camera's OWN type strings for this clip, all of them, unmapped
+	* (`md`, `people`, `dog_cat`, `sched`, …). Kept beside {@link labels}
+	* because a firmware inventing a type must not vanish: the mapping into our
+	* filter vocabulary is lossy on purpose and this is the lossless copy
+	* (D549 20).
+	*/
+	nativeTypes: array(string()).optional(),
+	/**
+	* What the subject DID — `crossline`, `intrude`, `loitering`. A behaviour
+	* travels BESIDE a class, never instead of one, and the class filter ignores
+	* it: "a person crossed a line" is still a person (D549 20).
+	*/
+	behaviours: array(string()).optional(),
+	/**
+	* The same recording as two files — the sub twin (what the row and its
+	* thumbnail are) and its main twin, matched at listing time so a quality
+	* change never re-searches the camera (D549 15). `getClipPlayback`'s
+	* `profile` picks between them: `low | mid` → sub, `high` → main.
+	*/
+	streams: object({
+		sub: object({
+			id: string(),
+			bytes: number().optional()
+		}).optional(),
+		main: object({
+			id: string(),
+			bytes: number().optional()
+		}).optional()
+	}).optional(),
+	/** The camera says it holds a sub-stream copy of this recording. */
+	supportSub: boolean().optional(),
+	/**
+	* Whether this row has bytes behind it. ABSENT means yes — every clip that
+	* IS a file is playable, and only a source that lists EVENTS can produce a
+	* row with nothing to play (the measured case: 1 of 29 hub events on 3628
+	* fell inside no file). Such a row is shown, never dropped and never offered
+	* as playable-then-failing (D549 19).
+	*/
+	playable: boolean().optional(),
+	/** Why {@link playable} is false, verbatim (`no-file-for-window`). */
+	unplayableReason: string().optional()
 });
 var ClipPlaybackSchema = object({
-	/** HLS master URL through the hub data-plane (Range + token in path). */
+	/**
+	* A media URL through the hub data-plane. {@link ClipPlaybackSchema.format}
+	* says what kind — an HLS master playlist for a recording-derived clip, a
+	* progressive MP4 for a native file the vendor addon muxed and serves with
+	* `Range`. The URL is NOT a credential: both planes are registered
+	* `access: 'authenticated'` and the hub's `/addon/<id>/<prefix>` proxy takes
+	* the session cookie, so nothing is appended to it (D549 22).
+	*/
 	playbackUrl: string(),
+	/**
+	* How to play {@link playbackUrl}. Absent means `hls` — the shape every
+	* existing consumer already assumes. A player that branches on this is the
+	* one change a native clip needs; a player that ignores it will hand an MP4
+	* to hls.js and fail parsing it as a manifest.
+	*/
+	format: _enum(["hls", "mp4"]).optional(),
+	/**
+	* Which twin was actually served. A clip that holds only one stream answers
+	* with the one it has, and the surface SAYS so — a missing main twin is
+	* never served silently as if it were the asked-for quality (D549 15).
+	*/
+	served: CamProfileSchema.optional(),
 	/** Optional LAN/remote alternates for the same clip. */
 	playbackEndpoints: array(string()).optional(),
 	token: string().optional()
 });
+/**
+* Why a source cannot answer right now — per SOURCE, never fleet-wide.
+*
+* `ok` is the only state whose clip list may be read as complete. The other
+* three exist because an empty list from a sleeping camera reads as "this
+* camera has no recordings", which is the defect this whole line of work is
+* about: a battery camera nobody woke (`sleeping`), a camera that could not be
+* reached at all (`unreachable`, also what a provider that THREW reports), a
+* camera whose SD card is not mounted (`no-storage`, measured on 640 —
+* `HddInfo mount 0`, honestly nothing to list rather than "no clips"), and a
+* camera whose OWN index disagrees with its OWN calendar (`index-empty`,
+* measured on 618: the calendar marks 3–20 September, days 6–20 list zero
+* files on both streams and both filters, with 177 GB free). That last one is
+* a defect ON THE CAMERA, and the only honest thing a provider can do is say
+* which days it asked for and got nothing — "no clips" would be a lie about a
+* card that is full of them.
+*/
+var ClipSourceAvailabilitySchema = object({
+	state: _enum([
+		"ok",
+		"sleeping",
+		"unreachable",
+		"no-storage",
+		"index-empty"
+	]),
+	/** Free text, shown verbatim. Names the camera's own refusal when there is one. */
+	reason: string().optional(),
+	/** When this source's catalog was last CONFIRMED. A cached list is never
+	*  drawn as current: the surface shows the age whenever it is older than the
+	*  refresh interval. */
+	catalogAsOf: number().optional()
+});
+/**
+* One SOURCE of clips for a camera — a row of the picker, and the namespace
+* every clip id from it is prefixed with (`analytics`,
+* `native:reolink:onboard`, `hksv`, …).
+*
+* A provider lists the sources IT serves for that device, and answers for each
+* of them whether it can answer at all. A provider with nothing to offer on a
+* camera returns `[]` — it is not that camera's business.
+*/
+var ClipSourceSchema = object({
+	/** The value this source stamps on {@link ClipSchema.source}, and the prefix
+	*  of every clip id it mints. `getClipPlayback` routes on it. */
+	source: string(),
+	/** Operator-facing name of the source ("CamStack recordings", "SD card"). */
+	label: string(),
+	/**
+	* The addon that SERVES this row.
+	*
+	* A surface cannot otherwise resolve a source to who answers it, and the
+	* alternative — a `native:reolink:* → provider-reolink` table inside the
+	* widget — is a second authority on provider identity living in the one
+	* package with no business knowing it, wrong the day a third source appears
+	* (D557). One addon may serve SEVERAL sources: `addon-provider-reolink`
+	* answers a hub child with both `native:reolink:onboard` and
+	* `native:reolink:hub`, which is why the per-device switch is keyed by
+	* SOURCE and not by this (D555).
+	*
+	* Optional for version skew only. The collection dispatcher stamps it from
+	* the registry, so a row that travelled through the fan-out carries the
+	* authoritative id whatever the provider filled in.
+	*/
+	addonId: string().optional(),
+	/**
+	* Which API this source resolved to FOR THIS CAMERA, when it has a choice.
+	*
+	* A source may cover one store through more than one surface — the Reolink
+	* provider reads a hub child through the parent's event log and a standalone
+	* through its own file list, because that is what each camera answers. The
+	* CHOICE is the provider's, made from what the camera is, and is never a row
+	* the operator has to understand; but it is REPORTED, because a source that
+	* silently reads a different API on two cameras and then behaves differently
+	* is the thing nobody can debug later. Absent when the source has only one
+	* way to read its store.
+	*/
+	via: string().optional(),
+	availability: ClipSourceAvailabilitySchema,
+	/**
+	* The operator switched this source OFF for this camera.
+	*
+	* Deliberately NOT a member of {@link ClipSourceAvailabilitySchema}'s
+	* vocabulary. That enum models what the source CAN do — a sleeping camera, an
+	* unmounted card, an index that disagrees with its own calendar — and a
+	* switched-off source could answer perfectly well; the operator decided it
+	* should not. Folding the choice in is how `disabled` and `broken` stop being
+	* distinguishable, which is the D62 rule this repo has already paid for twice:
+	* an off switch is REPORTED off (`CameraStatus.switchedOff`, the same word),
+	* and disabled must never look like broken. It is also what lets every
+	* exhaustive consumer of the availability enum keep compiling.
+	*
+	* A switched-off source contributes NO clips (`listClips` never calls it) and
+	* its row carries no `catalogAsOf`: nothing confirms a catalog it is not
+	* allowed to serve, and a frozen age that can only grow draws a stalling
+	* source rather than an off switch.
+	*
+	* The row survives BECAUSE it is the control the operator switches the source
+	* back on from — D554 decision 4's rule ("a source that cannot answer
+	* produces a ROW, not an absence") applied to the one case D556 carved out of
+	* it, and D557's own kept property ("a source is never hidden, only its
+	* rows"). Absent means on.
+	*
+	* A provider never sets this — like {@link ClipSourceSchema.addonId} it is
+	* stamped by the collection dispatcher, which holds the registry's projection
+	* of the persisted authority (D556) and is the only place that knows it.
+	*/
+	switchedOff: boolean().optional()
+});
 DeviceType.Camera, method(object({
 	deviceId: number(),
 	since: number(),
 	until: number(),
-	limit: number().int().positive().optional()
+	limit: number().int().positive().optional(),
+	/**
+	* View filter over {@link ClipSourceSchema.source} values — the
+	* picker's selection, forwarded so a provider need not list what
+	* nobody is looking at. ABSENT means every source this camera has,
+	* which is the honest default for a surface whose whole point is that
+	* nothing is hidden (D554 3). A provider with one source ignores it.
+	*/
+	sources: array(string()).optional()
 }), array(ClipSchema).readonly(), {
 	kind: "query",
-	auth: "admin"
+	auth: "protected"
+}), method(object({ deviceId: number() }), array(ClipSourceSchema).readonly(), {
+	kind: "query",
+	auth: "protected"
 }), method(object({
 	deviceId: number(),
-	clipId: string()
+	clipId: string(),
+	/**
+	* Which twin to serve, on the ONE quality scale the system already has
+	* (`CamProfileSchema`). `low | mid` → the sub file, `high` → the main
+	* twin; both ids are already on the row so this never re-searches the
+	* camera. Absent means the provider's own default (the sub file, which
+	* every source is measured to hold).
+	*
+	* `auto` is deliberately NOT accepted here: a stored file has no
+	* broker session, so the adaptive tier cannot be resolved for it. The
+	* viewer resolves `auto` to a profile the same way live does, before
+	* it calls (D549 15).
+	*/
+	profile: CamProfileSchema.optional()
 }), ClipPlaybackSchema, {
 	kind: "query",
-	auth: "admin"
+	auth: "protected"
 });
 /**
 * Optional client-side hints sent at session creation to help the provider
@@ -38997,6 +39299,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"videoclips.listSources": {
+		capName: "videoclips",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"viewerUi.getStaticDir": {
 		capName: "viewer-ui",
 		capScope: "system",
@@ -41005,6 +41313,11 @@ Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"videoclips.listSources": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"waterHeater.setAway": [{
 		name: "deviceId",
 		form: "single",
@@ -88769,6 +89082,124 @@ function firstExposedAccessorySetupUri(exposed, logger) {
 	}
 }
 //#endregion
+//#region src/hksv/clip-location.ts
+/** The declared id. Deployment-wide; see the docblock for why it is new. */
+var HOMEKIT_CLIPS_LOCATION_TYPE = "homekitClips";
+/** The class subtree under the resolved root. Never written at the root (D327). */
+var HOMEKIT_CLIPS_SUBTREE = "homekit-clips";
+/**
+* The cap calls, HERE and not in the addon.
+*
+* Deliberately co-located with the `mayWriteToLocation` filter below: a file
+* that enumerates storage locations must visibly decide whether it is choosing
+* a WRITE target (`scripts/check-storage-write-target-enabled.ts` enforces
+* exactly that, and it fired when the closure lived in the addon). Splitting
+* the enumeration from the decision is how the backup fan-out grew a second
+* enabled flag.
+*/
+function createClipLocationPorts(api) {
+	return {
+		listLocations: () => api.storage.listLocations.query({}),
+		resolvePath: (locationId) => api.storage.resolve.query({
+			location: locationId,
+			relativePath: ""
+		})
+	};
+}
+var HksvClipLocation = class {
+	input;
+	log;
+	now;
+	revalidateMs;
+	cachedRoot = null;
+	resolvedAt = Number.NEGATIVE_INFINITY;
+	refusal = null;
+	/** What the last warn said, so a per-clip refusal is not a per-clip log line. */
+	announced = null;
+	inFlight = null;
+	constructor(input) {
+		this.input = input;
+		this.log = input.logger;
+		this.now = input.now ?? Date.now;
+		this.revalidateMs = input.revalidateMs ?? 6e4;
+	}
+	/** Why the last resolution produced no root. `null` once one succeeded. */
+	get lastRefusal() {
+		return this.refusal;
+	}
+	/** The doorbell rang (`StorageLocationsChanged`): drop the mirror. */
+	invalidate() {
+		this.resolvedAt = Number.NEGATIVE_INFINITY;
+	}
+	/**
+	* The directory clips are written under, or `null` when there is none right
+	* now. Never throws: the caller's correct move for every refusal is the same
+	* — do not tee this clip, and leave HomeKit alone.
+	*/
+	async root() {
+		if (this.now() - this.resolvedAt < this.revalidateMs) return this.cachedRoot;
+		const inflight = this.inFlight;
+		if (inflight !== null) return inflight;
+		const attempt = this.resolve();
+		this.inFlight = attempt;
+		try {
+			return await attempt;
+		} finally {
+			this.inFlight = null;
+		}
+	}
+	async resolve() {
+		try {
+			const rows = (await this.input.ports.listLocations()).filter((l) => l.type === HOMEKIT_CLIPS_LOCATION_TYPE);
+			if (rows.length === 0) return this.refuse("no-location", {});
+			if (rows.length > 1) this.warnOnce("hksv clip store: more than one HomeKit clips location exists — it is declared single", { ids: rows.map((l) => l.id) });
+			const writable = rows.find((l) => mayWriteToLocation(l));
+			if (writable === void 0) {
+				const first = rows[0];
+				return this.refuse("not-writable", {
+					locationId: first?.id ?? null,
+					mode: first === void 0 ? null : resolveLocationMode(first)
+				});
+			}
+			const root = `${(await this.input.ports.resolvePath(writable.id)).replace(/\/+$/, "")}/${HOMEKIT_CLIPS_SUBTREE}`;
+			this.cachedRoot = root;
+			this.resolvedAt = this.now();
+			this.refusal = null;
+			if (this.announced !== null) {
+				this.announced = null;
+				this.log.info("hksv clip store: the clips location is writable again", { meta: {
+					locationId: writable.id,
+					root
+				} });
+			}
+			return root;
+		} catch (err) {
+			return this.refuse("unreachable", { error: err instanceof Error ? err.message : String(err) });
+		}
+	}
+	refuse(reason, meta) {
+		this.cachedRoot = null;
+		this.resolvedAt = this.now();
+		this.refusal = reason;
+		this.warnOnce("hksv clip store: no writable HomeKit clips location — clips are NOT being kept (HomeKit recording is unaffected)", {
+			reason,
+			...meta
+		});
+		return null;
+	}
+	/**
+	* One line per distinct situation. A refusal that reprinted on every clip
+	* would drown the line that says it CHANGED, and the operator reads the log
+	* to find out which of the two is happening.
+	*/
+	warnOnce(message, meta) {
+		const key = `${message}|${JSON.stringify(meta)}`;
+		if (this.announced === key) return;
+		this.announced = key;
+		this.log.warn(message, { meta });
+	}
+};
+//#endregion
 //#region src/hksv/clip-record.ts
 /**
 * What ONE teed HomeKit clip is, on disk.
@@ -88874,32 +89305,39 @@ function clipStem(clipId) {
 *
 * ## The owner
 *
-* The **export-hap addon**, in its OWN data dir, and nothing else. Not the
-* recorder's storage locations and not the `eventMedia` class:
+* The **export-hap addon**, on its own DECLARED storage location
+* (`homekitClips`, see `clip-location.ts`) — the operator picks the disk. Not
+* the `eventMedia` class and not `recordings`:
 *
-*  - `export-hap` is hub-only and runs in its own runner. The recorder's
-*    location machinery (D385/D386/D389) is another addon's, in another
-*    process, and reaching it would be a cross-runner write on the frame path
-*    of a live HomeKit session — exactly what D9/D18 forbid.
 *  - A teed clip is a DERIVED artifact of a HomeKit session, with no track, no
 *    detection and no event behind it. Filing it under `eventMedia` would put
 *    it inside the post-analysis retention sweep, where its lifetime would be
 *    decided by a policy written for a different question.
-*  - The precedent is D549 decision 13: Reolink's clip thumbnails live in the
-*    vendor addon's data dir under a per-device LRU, outside `eventMedia` and
-*    outside the sweep, for the same reason.
+*  - `recordings` rows belong to the recorder's placement planner, its evictor
+*    and its drain ratchet, and these files are not segments its index knows.
+*  - The precedent for a class of its own is D549 decision 13: Reolink's clip
+*    thumbnails sit outside `eventMedia` and outside the sweep for the same
+*    reason.
 *
-* Layout: `<dataDir>/hksv-clips/<deviceId>/<stem>.{mp4,jpg,json}`. One stem per
-* clip, three extensions, so a pruner deleting a clip never has to guess which
-* JPEG was its.
+* Layout: `<location root>/homekit-clips/<deviceId>/<stem>.{mp4,jpg,json}`. One
+* stem per clip, three extensions, so a pruner deleting a clip never has to
+* guess which JPEG was its; the `homekit-clips/` subtree is mandatory because
+* the location's seeded default SHARES the recordings root (D327).
 *
-* ## The retention, and why these numbers
+* The first cut wrote to `<dataDir>/hksv-clips/`. It was defensible and gave
+* the operator no say, which was the first thing he asked for after seeing it.
+*
+* ## The retention: one preference, three rails
 *
 * HomeKit's own retention is unreadable — HAP has no read-back, so CamStack can
 * never ask "does iOS still have this one?" and reconcile. The store therefore
 * cannot mirror HomeKit's lifetime and does not pretend to: it keeps a bounded
-* recent window and says, per clip, exactly when it started. Four bounds, all
-* enforced on every completion:
+* recent window and says, per clip, exactly when it started.
+*
+* **The AGE is the operator's, per camera**
+* ({@link HksvClipStoreInput.maxAgeMsFor}, cascaded global-default plus
+* per-device override by the addon), defaulting to 14 days. The other three are
+* RAILS, not preferences, and stay fixed:
 *
 *  - **{@link DEFAULT_CLIP_BOUNDS.maxClipBytes} per clip (256 MB).** A clip's
 *    duration is whatever iOS pulled — there is no window we choose — so this
@@ -88912,12 +89350,18 @@ function clipStem(clipId) {
 *    Both bounds exist for the same reason the prebuffer ring has both: at 4K
 *    a fragment is 6.35 MB, a 25x spread, and a count-only bound is a
 *    per-camera disk figure nobody can predict.
-*  - **{@link DEFAULT_CLIP_BOUNDS.maxAgeMs} (14 days)**, so a camera that
-*    stopped recording in March does not hold half a gigabyte forever.
 *  - **{@link DEFAULT_CLIP_BOUNDS.maxStoreBytes} (4 GB)** across every camera,
 *    applied after the per-device pass. Per-device bounds alone multiply by a
 *    camera count the operator changes without thinking about this store.
 *
+* An operator able to set the first to zero could turn the tee into a silent
+* no-op, and one able to raise the last without limit could fill the disk; the
+* age changes neither. The consequence is stated rather than left to be
+* discovered: a retention LONGER than the rails allow does not reach — a busy
+* camera hits 200 clips or 512 MB first. Every prune logs which bound fired
+* (`reason: age | count | bytes`), so "my 30 days did nothing" has an answer in
+* the log instead of a theory.
+*
 * A file nobody prunes is a disk that fills, and the pruner is the only thing
 * standing between a permanent prebuffer and that.
 *
@@ -88930,8 +89374,6 @@ function clipStem(clipId) {
 * deleted — this repo has twice shipped a green test because the fake supplied
 * what production forgot, and a promise is not a file.
 */
-/** The directory under the addon's data dir. Ours, and only ours. */
-var CLIP_DIR_NAME = "hksv-clips";
 /** See the class docblock for what each number is, and where it comes from. */
 var DEFAULT_CLIP_BOUNDS = {
 	maxClipBytes: 256 * 1024 * 1024,
@@ -88955,6 +89397,11 @@ var HksvClipStore = class {
 		};
 		this.now = input.now ?? Date.now;
 	}
+	/** This camera's retention. One authority, asked at every prune. */
+	maxAgeMsFor(deviceId) {
+		const resolved = this.input.maxAgeMsFor?.(deviceId);
+		return resolved === void 0 || !Number.isFinite(resolved) || resolved <= 0 ? this.bounds.maxAgeMs : resolved;
+	}
 	/** The per-clip ceiling the tee enforces while writing. */
 	get maxClipBytes() {
 		return this.bounds.maxClipBytes;
@@ -88967,8 +89414,10 @@ var HksvClipStore = class {
 	async open(input) {
 		const clipId = clipIdFor(input.deviceId, input.startedAtMs, input.streamId);
 		const names = clipFileNames(clipId);
-		const dir = this.deviceDir(input.deviceId);
 		const tags = { deviceId: input.deviceId };
+		const root = await this.resolveRootOrWarn(tags);
+		if (root === null) return null;
+		const dir = this.deviceDir(root, input.deviceId);
 		try {
 			await mkdir(dir, { recursive: true });
 			const sink = await createFileSink(join(dir, names.clip));
@@ -88979,7 +89428,7 @@ var HksvClipStore = class {
 			return {
 				clipId,
 				sink,
-				complete: (outcome) => this.complete(clipId, input, names, outcome)
+				complete: (outcome) => this.complete(clipId, input, names, outcome, root)
 			};
 		} catch (err) {
 			this.inFlight.delete(clipId);
@@ -88995,7 +89444,9 @@ var HksvClipStore = class {
 	}
 	/** Every sidecar for a camera, newest first. What a later provider lists. */
 	async listRecords(deviceId) {
-		const dir = this.deviceDir(deviceId);
+		const root = await this.rootOrNull();
+		if (root === null) return [];
+		const dir = this.deviceDir(root, deviceId);
 		let names;
 		try {
 			names = await readdir(dir);
@@ -89012,7 +89463,9 @@ var HksvClipStore = class {
 	}
 	/** iOS sent `ack`: HomeKit itself kept this clip. Recorded on the sidecar. */
 	async acknowledge(deviceId, clipId) {
-		const path = join(this.deviceDir(deviceId), clipFileNames(clipId).record);
+		const root = await this.rootOrNull();
+		if (root === null) return;
+		const path = join(this.deviceDir(root, deviceId), clipFileNames(clipId).record);
 		const record = await this.readRecord(path, deviceId);
 		if (record === null) return;
 		await this.writeRecord(path, {
@@ -89020,12 +89473,41 @@ var HksvClipStore = class {
 			acknowledgedByHomeKit: true
 		});
 	}
-	deviceDir(deviceId) {
-		return join(this.input.rootDir, String(deviceId));
+	/**
+	* The root, or `null` with ONE warn. Never throws: the caller's correct move
+	* for every refusal is identical — no clip, HomeKit untouched.
+	*/
+	async resolveRootOrWarn(tags) {
+		try {
+			const root = await this.input.resolveRoot();
+			if (root !== null) return root;
+		} catch (err) {
+			this.log.warn("hksv clip store: resolving the clips location FAILED — nothing is teed", {
+				tags,
+				meta: { error: err instanceof Error ? err.message : String(err) }
+			});
+			return null;
+		}
+		this.log.warn("hksv clip store: no writable clips location — this camera keeps no HomeKit clips", {
+			tags,
+			meta: {}
+		});
+		return null;
+	}
+	/** The root for a READ. Quiet: a read with no location is simply empty. */
+	async rootOrNull() {
+		try {
+			return await this.input.resolveRoot();
+		} catch {
+			return null;
+		}
+	}
+	deviceDir(root, deviceId) {
+		return join(root, String(deviceId));
 	}
-	async complete(clipId, input, names, outcome) {
+	async complete(clipId, input, names, outcome, root) {
 		this.inFlight.delete(clipId);
-		const dir = this.deviceDir(input.deviceId);
+		const dir = this.deviceDir(root, input.deviceId);
 		const tags = { deviceId: input.deviceId };
 		const clipPath = join(dir, names.clip);
 		if (!outcome.sawInit || outcome.bytes === 0) {
@@ -89082,7 +89564,7 @@ var HksvClipStore = class {
 				thumbnailUnavailable: record.thumbnailUnavailable?.reason ?? null
 			}
 		});
-		await this.prune(input.deviceId);
+		await this.prune(root, input.deviceId);
 		return record;
 	}
 	/**
@@ -89129,26 +89611,31 @@ var HksvClipStore = class {
 	* sidecars, so a stem whose sidecar never landed — a crash mid-write — is
 	* seen and removed instead of occupying the disk invisibly forever.
 	*/
-	async prune(deviceId) {
-		const cutoff = this.now() - this.bounds.maxAgeMs;
-		const perDevice = await this.scanDevice(deviceId);
-		await this.enforce(perDevice, cutoff, this.bounds.maxClipsPerDevice, this.bounds.maxBytesPerDevice);
+	async prune(root, deviceId) {
+		const perDevice = await this.scanDevice(root, deviceId);
+		await this.enforce(perDevice, this.bounds.maxClipsPerDevice, this.bounds.maxBytesPerDevice);
 		let deviceIds;
 		try {
-			deviceIds = (await readdir(this.input.rootDir, { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => Number.parseInt(e.name, 10)).filter((id) => Number.isFinite(id));
+			deviceIds = (await readdir(root, { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => Number.parseInt(e.name, 10)).filter((id) => Number.isFinite(id));
 		} catch {
 			return;
 		}
 		const all = [];
-		for (const id of deviceIds) all.push(...await this.scanDevice(id));
-		await this.enforce(all, cutoff, Number.POSITIVE_INFINITY, this.bounds.maxStoreBytes);
+		for (const id of deviceIds) all.push(...await this.scanDevice(root, id));
+		await this.enforce(all, Number.POSITIVE_INFINITY, this.bounds.maxStoreBytes);
 	}
-	async enforce(clips, ageCutoff, maxCount, maxBytes) {
+	/**
+	* Enforce the bounds, oldest first. The AGE is asked per clip's CAMERA — two
+	* cameras with different retentions share this pass, and folding them into
+	* one cutoff would silently give every camera the shortest.
+	*/
+	async enforce(clips, maxCount, maxBytes) {
+		const now = this.now();
 		const ordered = [...clips].sort((a, b) => b.startedAtMs - a.startedAtMs);
 		let kept = 0;
 		let bytes = 0;
 		for (const clip of ordered) {
-			const tooOld = clip.startedAtMs < ageCutoff;
+			const tooOld = clip.startedAtMs < now - this.maxAgeMsFor(clip.deviceId);
 			const overCount = kept >= maxCount;
 			const overBytes = bytes + clip.bytes > maxBytes;
 			if (!tooOld && !overCount && !overBytes) {
@@ -89175,8 +89662,8 @@ var HksvClipStore = class {
 			}
 		});
 	}
-	async scanDevice(deviceId) {
-		const dir = this.deviceDir(deviceId);
+	async scanDevice(root, deviceId) {
+		const dir = this.deviceDir(root, deviceId);
 		let names;
 		try {
 			names = await readdir(dir);
@@ -89222,7 +89709,19 @@ var HksvClipStore = class {
 		} catch {
 			return null;
 		}
-		const parsed = HksvClipRecordSchema.safeParse(JSON.parse(raw));
+		let parsed;
+		try {
+			parsed = HksvClipRecordSchema.safeParse(JSON.parse(raw));
+		} catch (err) {
+			this.log.warn("hksv clip store: a sidecar is not readable JSON — the clip is not listed", {
+				tags: { deviceId },
+				meta: {
+					path,
+					error: err instanceof Error ? err.message : String(err)
+				}
+			});
+			return null;
+		}
 		if (parsed.success) return parsed.data;
 		this.log.warn("hksv clip store: a sidecar could not be read — the clip is not listed", {
 			tags: { deviceId },
@@ -89233,8 +89732,19 @@ var HksvClipStore = class {
 		});
 		return null;
 	}
+	/**
+	* ATOMICALLY: a temp file plus a rename, never a `writeFile` in place.
+	*
+	* The sidecar is the only thing that says a clip exists, and it is read
+	* concurrently — by the pruner, and later by whatever lists these clips. A
+	* plain write is visible half-finished, and a half-finished sidecar reads as
+	* a corrupt clip rather than a clip being written. `rename` within one
+	* directory is atomic, so a reader sees the old record or the new one.
+	*/
 	async writeRecord(path, record) {
-		await writeFile(path, JSON.stringify(record, null, 2), "utf8");
+		const staging = `${path}.tmp`;
+		await writeFile(staging, JSON.stringify(record, null, 2), "utf8");
+		await rename(staging, path);
 	}
 };
 function stemOf(fileName) {
@@ -105199,7 +105709,8 @@ async function buildHksvRecording(input) {
 		fps,
 		fragmentLengthMs
 	});
-	const clipStore = bctx.options.hksvClipStore;
+	const keepClips = bctx.options.hapDeviceSettings.keepHomekitClips !== false;
+	const clipStore = keepClips ? bctx.options.hksvClipStore : null;
 	const openClipTee = clipStore === null ? void 0 : createClipTeeFactory({
 		logger: log,
 		deviceId: numericDeviceId,
@@ -105235,7 +105746,8 @@ async function buildHksvRecording(input) {
 		advertisedFps: advertisedResolution?.[2] ?? null,
 		fragmentLengthMs,
 		sourceGopMs: gopMs ?? "unknown",
-		clipsKept: openClipTee !== void 0
+		clipsKept: openClipTee !== void 0,
+		clipsSwitchedOn: keepClips
 	} });
 	return {
 		options,
@@ -106519,6 +107031,39 @@ function resolveHksvRecording(settings) {
 * negotiation is built we say `streaming-enabled: false`, so declining is the
 * only thing a controller can do with it.
 */
+/**
+* Keep a copy of what we send HomeKit, for this camera.
+*
+* ABSENT MEANS ON, for the same reason as `resolveHksvRecording` and one
+* stronger: HKSV has no read-back, so every recording made while this said
+* "off by accident" is gone permanently. Only an explicit `false` turns it off.
+*/
+function resolveKeepHomekitClips(settings) {
+	return settings?.keepClips !== false;
+}
+/** What ships, and what an unset global resolves to. */
+var DEFAULT_CLIP_RETENTION_DAYS = 14;
+/** The rails on the retention itself. Zero would silently disable the tee. */
+var MIN_CLIP_RETENTION_DAYS = 1;
+var MAX_CLIP_RETENTION_DAYS = 365;
+/**
+* This camera's retention in days: per-device override → global default →
+* {@link DEFAULT_CLIP_RETENTION_DAYS}.
+*
+* The cascade rule the repo already pays for (`stationary-settings.ts`):
+* **reset == unset**. A cleared override and a key that was never written must
+* resolve to the same number, or the Reset button is a lie. A value outside the
+* rails is not stored as a lie either — it falls back rather than turning the
+* tee into a no-op (0 days) or an unbounded archive.
+*/
+function resolveClipRetentionDays(settings, globalDefaultDays) {
+	const fleet = clampRetentionDays(globalDefaultDays) ?? 14;
+	return clampRetentionDays(settings?.clipRetentionDays) ?? fleet;
+}
+function clampRetentionDays(value) {
+	if (typeof value !== "number" || !Number.isFinite(value) || value < MIN_CLIP_RETENTION_DAYS) return null;
+	return Math.min(Math.floor(value), MAX_CLIP_RETENTION_DAYS);
+}
 function resolveMultiTierService(settings) {
 	return settings?.multiTierService === true;
 }
@@ -106546,6 +107091,7 @@ var DEFAULT_CONFIG = {
 	fixedPin: "",
 	interfaceName: "",
 	ptzPulseMs: 400,
+	clipRetentionDays: 14,
 	identity: {
 		username: "",
 		pincode: "",
@@ -106618,6 +107164,8 @@ var ExportHapAddon = class extends BaseAddon {
 	* failure to exist is one line at boot and not a surprise mid-recording.
 	*/
 	hksvClipStore = null;
+	/** Resolves the declared `homekitClips` location; the doorbell invalidates it. */
+	hksvClipLocation = null;
 	/**
 	* THE bridge. Lazily created and published the first time a non-camera
 	* accessory needs it; never torn down while the addon runs, because an
@@ -106644,9 +107192,14 @@ var ExportHapAddon = class extends BaseAddon {
 			this.lastError = errMsg(err);
 			this.ctx.logger.error("export-hap: HAP storage init failed", { meta: { error: this.lastError } });
 		}
+		this.hksvClipLocation = new HksvClipLocation({
+			logger: this.ctx.logger.child("hksv-clips"),
+			ports: createClipLocationPorts(this.ctx.api)
+		});
 		this.hksvClipStore = new HksvClipStore({
 			logger: this.ctx.logger.child("hksv-clips"),
-			rootDir: path.join(this.ctx.dataDir, CLIP_DIR_NAME),
+			resolveRoot: () => this.hksvClipLocation?.root() ?? Promise.resolve(null),
+			maxAgeMsFor: (deviceId) => resolveClipRetentionDays(this.findEntry(deviceId)?.settings, this.config.clipRetentionDays) * 24 * 60 * 60 * 1e3,
 			mintThumbnail: createClipThumbnailMinter({ runner: createFfmpegClipThumbnailRunner({
 				ffmpegBinaryPath: "ffmpeg",
 				spawnFn: spawn
@@ -106678,6 +107231,7 @@ var ExportHapAddon = class extends BaseAddon {
 		});
 		this.subscribeDeviceProvisionedForReconcile();
 		this.subscribeDeviceReadyForReconcile();
+		this.subscribeStorageLocationsForClips();
 		this.disposeSharedRebuildTimers();
 		return [{
 			capability: deviceExportCapability,
@@ -106848,6 +107402,7 @@ var ExportHapAddon = class extends BaseAddon {
 				hapDeviceSettings: {
 					streamPreference: entrySettings.streamPreference ?? "auto",
 					hksvRecording: resolveHksvRecording(entrySettings),
+					keepHomekitClips: resolveKeepHomekitClips(entrySettings),
 					multiTierService: resolveMultiTierService(entrySettings),
 					allowTranscode: entrySettings.allowTranscode !== false
 				}
@@ -106961,6 +107516,21 @@ var ExportHapAddon = class extends BaseAddon {
 	* whether the reconcile actually rebuilds anything. Shared by the two
 	* triggers below.
 	*/
+	/**
+	* The clips location moved. A DOORBELL, not a payload: the event names which
+	* row changed and the re-read is the authority (`StorageLocationsChangedPayload`
+	* says so itself). Dropping the mirror is all this does — the next clip
+	* resolves it again, and a missed event self-heals on the revalidation
+	* window, so nothing here gates on a fallible read (D49).
+	*/
+	subscribeStorageLocationsForClips() {
+		const unsubscribe = this.ctx.eventBus.subscribe({ category: EventCategory.StorageLocationsChanged }, () => {
+			this.hksvClipLocation?.invalidate();
+		});
+		this.ctx.addDisposer(async () => {
+			unsubscribe();
+		});
+	}
 	subscribeDeviceLifecycleForReconcile(category) {
 		const unsubscribe = this.ctx.eventBus.subscribe({ category }, (event) => {
 			const data = event.data;
@@ -107159,6 +107729,14 @@ var ExportHapAddon = class extends BaseAddon {
 					requiresRestart: true,
 					placement: { tab: "advanced" }
 				}),
+				this.field({
+					type: "number",
+					key: "clipRetentionDays",
+					label: "Keep HomeKit clips for (days)",
+					description: "CamStack keeps its own copy of every clip it sends to HomeKit Secure Video — HomeKit itself never gives one back. This is the fleet default; each camera can override it, and each can switch the copies off entirely. Clips are also capped at 200 per camera, 512 MB per camera and 4 GB overall — whichever limit is reached first wins, and the log names which one.",
+					default: DEFAULT_CONFIG.clipRetentionDays,
+					placement: { tab: "advanced" }
+				}),
 				this.field({
 					type: "number",
 					key: "ptzPulseMs",
@@ -107182,6 +107760,8 @@ var ExportHapAddon = class extends BaseAddon {
 		const multiTierKey = `hap:${deviceId}:multiTierService`;
 		const useBridgeKey = `hap:${deviceId}:useBridge`;
 		const allowTranscodeKey = `hap:${deviceId}:allowTranscode`;
+		const keepClipsKey = `hap:${deviceId}:keepClips`;
+		const clipRetentionKey = `hap:${deviceId}:clipRetentionDays`;
 		const mapper = this.exposed.get(String(deviceId)) ?? null;
 		const paired = mapper ? accessoryPaired(mapper.accessory) : false;
 		const bridged = mapper !== null && this.bridgeHost?.holds(mapper.accessory) === true;
@@ -107252,6 +107832,31 @@ var ExportHapAddon = class extends BaseAddon {
 				},
 				immediate: true
 			},
+			{
+				type: "boolean",
+				key: keepClipsKey,
+				label: "Keep CamStack copies of HomeKit clips",
+				description: "Save a copy of every clip sent to HomeKit Secure Video, on the “HomeKit Clips” storage location. HomeKit never gives a clip back, so a recording made with this off cannot be recovered later. Off saves the disk and one thumbnail decode per clip; the HomeKit recording itself is unchanged either way.",
+				style: "switch",
+				value: resolveKeepHomekitClips(settings),
+				showWhen: {
+					field: hksvKey,
+					equals: true
+				},
+				immediate: true
+			},
+			{
+				type: "number",
+				key: clipRetentionKey,
+				label: "Keep this camera’s clips for (days)",
+				description: `How long this camera’s kept clips survive before they are pruned, oldest first. Leave at ${this.config.clipRetentionDays} to follow the fleet default. The per-camera caps (200 clips, 512 MB) and the 4 GB overall cap still apply — whichever is reached first wins, and the prune log names it.`,
+				value: resolveClipRetentionDays(settings, this.config.clipRetentionDays),
+				showWhen: {
+					field: keepClipsKey,
+					equals: true
+				},
+				immediate: true
+			},
 			{
 				type: "boolean",
 				key: allowTranscodeKey,
@@ -107339,6 +107944,8 @@ var ExportHapAddon = class extends BaseAddon {
 		const useBridgeKey = `hap:${deviceId}:useBridge`;
 		const allowTranscodeKey = `hap:${deviceId}:allowTranscode`;
 		const multiTierKey = `hap:${deviceId}:multiTierService`;
+		const keepClipsKey = `hap:${deviceId}:keepClips`;
+		const clipRetentionKey = `hap:${deviceId}:clipRetentionDays`;
 		const enabledValue = enabledKey in patch ? Boolean(patch[enabledKey]) : wasEnabled;
 		const streamPreferenceRaw = streamPreferenceKey in patch ? patch[streamPreferenceKey] : current?.settings?.streamPreference;
 		const streamPreference = typeof streamPreferenceRaw === "string" && streamPreferenceRaw.trim().length > 0 ? streamPreferenceRaw : "auto";
@@ -107346,13 +107953,20 @@ var ExportHapAddon = class extends BaseAddon {
 		const useBridge = useBridgeKey in patch ? Boolean(patch[useBridgeKey]) : current?.settings?.useBridge !== false;
 		const allowTranscode = allowTranscodeKey in patch ? Boolean(patch[allowTranscodeKey]) : current?.settings?.allowTranscode !== false;
 		const multiTierService = multiTierKey in patch ? Boolean(patch[multiTierKey]) : resolveMultiTierService(current?.settings);
+		const keepClips = keepClipsKey in patch ? Boolean(patch[keepClipsKey]) : resolveKeepHomekitClips(current?.settings);
+		const clipRetentionDays = clipRetentionKey in patch ? resolveClipRetentionDays({
+			streamPreference,
+			clipRetentionDays: Number(patch[clipRetentionKey])
+		}, this.config.clipRetentionDays) : resolveClipRetentionDays(current?.settings, this.config.clipRetentionDays);
 		const nextSettings = {
 			...current?.settings ?? DEFAULT_DEVICE_SETTINGS,
 			streamPreference,
 			hksvRecording,
 			useBridge,
 			allowTranscode,
-			multiTierService
+			multiTierService,
+			keepClips,
+			clipRetentionDays
 		};
 		if (!enabledValue) {
 			if (wasEnabled) await this.unexposeDevice(deviceIdStr);
@@ -107365,6 +107979,7 @@ var ExportHapAddon = class extends BaseAddon {
 		}
 		const currentPref = current?.settings?.streamPreference ?? "auto";
 		const currentHksv = resolveHksvRecording(current?.settings);
+		const currentKeepClips = resolveKeepHomekitClips(current?.settings);
 		const mapperKind = current?.mapperKind ?? "generic";
 		const wasBridged = shouldBridge({
 			mapperKind,
@@ -107375,7 +107990,7 @@ var ExportHapAddon = class extends BaseAddon {
 			useBridge
 		});
 		await this.updateEntrySettings(deviceIdStr, nextSettings);
-		if (currentPref !== streamPreference || currentHksv !== hksvRecording || wasBridged !== willBridge) {
+		if (currentPref !== streamPreference || currentHksv !== hksvRecording || currentKeepClips !== keepClips || wasBridged !== willBridge) {
 			log.info("export-hap: per-camera export settings changed — refreshing accessory", { meta: {
 				streamPreference: {
 					from: currentPref,
@@ -107385,6 +108000,10 @@ var ExportHapAddon = class extends BaseAddon {
 					from: currentHksv,
 					to: hksvRecording
 				},
+				keepClips: {
+					from: currentKeepClips,
+					to: keepClips
+				},
 				bridged: {
 					from: wasBridged,
 					to: willBridge
@@ -107415,4 +108034,4 @@ function errMsg(err) {
 	return err instanceof Error ? err.message : String(err);
 }
 //#endregion
-export { ExportHapAddon, ExportHapAddon as default, unpublishAccessory as i, initHapStorage as n, publishStandalone as r, resolveHksvRecording, resolveMultiTierService, deriveUsername as t };
+export { DEFAULT_CLIP_RETENTION_DAYS, ExportHapAddon, ExportHapAddon as default, unpublishAccessory as i, initHapStorage as n, publishStandalone as r, resolveClipRetentionDays, resolveHksvRecording, resolveKeepHomekitClips, resolveMultiTierService, deriveUsername as t };