@camstack/types 1.2.236 → 1.2.238

package/dist/index.js

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_sleep = require("./sleep-Cqxm5OIN.js");
+const require_sleep = require("./sleep-C0n7gucP.js");
 const require_event_category = require("./event-category-BVfsrBYA.js");
 const require_canonical_hash = require("./canonical-hash-CSE4ioRi.js");
 const require_enums = require("./enums.js");
@@ -27164,13 +27164,14 @@ var vectorStoreCapability = {
 *
 * A device-scoped wrapper COLLECTION (D549 decision 2, D554): every provider a
 * camera has is a SOURCE, and they are listed beside each other — never one
-* substituted for another. The DEFAULT provider (`analytics`, registered by
-* the RECORDER — the addon that owns the footage, D560 — `defaultActive: true`)
-* composes the analytics event log (markers + thumbnails, read over `ctx.api`)
-* with the recorder's own `getPlaybackManifest` — a clip is a time-WINDOW over
-* existing footage, never a separate file. A camera that exposes NATIVE onboard
-* clips (Reolink SD card, a hub's storage, HKSV) adds its own catalog
-* ALONGSIDE that one.
+* substituted for another, and none of them privileged by name. One source,
+* `analytics`, is registered by the RECORDER — the addon that owns the
+* footage, D560 — and composes the analytics event log (markers + thumbnails,
+* read over `ctx.api`) with the recorder's own `getPlaybackManifest`: a clip
+* is a time-WINDOW over existing footage, never a separate file. A camera that
+* exposes NATIVE onboard clips (Reolink SD card, a hub's storage, HKSV) adds
+* its own catalog ALONGSIDE that one. (`defaultActive` above is the CAP's
+* auto-bind to cameras, not a ranking among these sources — there is none.)
 *
 * The mount stays per-device (`resolveCapMount` → `device-scoped`), and a
 * device's SOURCES are its BINDINGS: `deviceManager.getBindings(deviceId)` is
@@ -27180,10 +27181,17 @@ var vectorStoreCapability = {
 * native provider, as the hub-local registration and as an
 * `<addonId>@<nodeId>` one (D554 amended 2026-09-20).
 *
-* `listClips` is asked of ONE provider at a time
-* ({@link videoclipsCapability.methods.listClips} `provider`), defaulting to
-* the bound one, which is CamStack on every camera today. It is NOT a union
-* over everything a camera has: *"l'utilizzatore è uno solo"*.
+* `listClips` is asked of ONE provider at a time, and NAMING it is REQUIRED
+* ({@link videoclipsCapability.methods.listClips} `provider`, D554 amended). It is not
+* a union over everything a camera has: *"l'utilizzatore è uno solo"*. There
+* is no default, because a collection cap's binding set is DERIVED and PLURAL
+* (D554 amended, `getBindings` step 0) — "the bound one" does not exist to
+* resolve to, and the one thing that could take its place is a second
+* authority naming a provider per camera, which D554 decision 3 rejected.
+* The pick is a SURFACE's to make, from the {@link ClipSourceSchema} rows it
+* already holds, and it says which one it made (D569 § 1–3).
+* {@link videoclipsCapability.methods.listSources} is the method that fans out
+* — one row per source, by construction.
 * {@link videoclipsCapability.methods.getClipPlayback} dispatches by the
 * source namespace inside the clip id, which is why ids are self-contained.
 *
@@ -27454,6 +27462,77 @@ var ClipPlaybackSchema = zod.z.object({
 * which days it asked for and got nothing — "no clips" would be a lie about a
 * card that is full of them.
 */
+/**
+* The operator's authorisation to WAKE a sleeping camera for one clip read.
+*
+* ONE value, absent by default, and it is a `force`-shaped operator signal in
+* exactly the sense `snapshot-wake-gate.ts` uses the word: *"`snapshot.getSnapshot`'s
+* `force` flag, and nothing else… a background caller must never set it…
+* Stale but honest beats woken"*. A scheduler, a retry, a reconcile and a
+* prefetch never set it; a surface sets it only behind the same confirm the
+* "Wake and refresh" gesture uses, and it is refused below 15 % battery
+* exactly as that gesture is.
+*
+* The gate is decided BEFORE `getApi()`, because on UDP the login IS the wake
+* (D549) — a read that opened a session and then checked would have woken the
+* camera to find out it was not allowed to.
+*
+* **One authorised yes is one wake.** `next-natural` — take the clip the next
+* time the camera is awake for its own reasons — is deliberately not a member:
+* it was proposed, it is free on the battery, and the operator declined it on
+* 2026-09-20 (*"Quando un export viene richiesto si sveglia la camera."*,
+* D558 "Considered and not taken").
+*/
+var ClipWakeSchema = zod.z.enum(["authorised"]);
+/**
+* Hard ceiling on ONE {@link videoclipsCapability.methods.readClipBytes} — the
+* same 50 MiB `RECORDING_EXPORT_MAX_READ_BYTES` uses, and for the same second
+* reason: the envelope is unary, so a base64 payload is held whole (~1.33× its
+* size) in the provider AND in the caller, on a hub this repo has already
+* OOM'd once (D9/D18).
+*
+* Measured clips sit far below it — 92 KB–2.29 MB for a sub twin, 455 KB for a
+* 16 s main clip — so the bound bites rarely. "Rarely" is not "never": a long
+* 4K main twin can exceed it, and above the bound the provider REFUSES with
+* the size in the message, never truncates. Half a video is worse than an
+* honest refusal.
+*
+* The clean follow-on is a CHUNKED read so a `high` twin of a long clip stops
+* being refusable at all. That is a later slice, named here so the bound is
+* not mistaken for a design ceiling.
+*/
+var VIDEOCLIPS_MAX_READ_BYTES = 50 * 1024 * 1024;
+/**
+* A clip's finished bytes, inline — the twin of `recordingExport.readExportBytes`.
+*
+* `bytes` is the DECODED length, so nobody infers it from the base64 length,
+* and `served` says which twin the caller actually got.
+*/
+var ClipBytesSchema = zod.z.object({
+	base64: zod.z.string(),
+	contentType: zod.z.string(),
+	/** Suggested filename, extension included. */
+	name: zod.z.string(),
+	bytes: zod.z.number().int().nonnegative(),
+	/**
+	* Which twin was actually served — the same contract
+	* {@link ClipPlaybackSchema.served} carries, and REQUIRED here because the
+	* export record persists it: a row read a week later must say the same thing
+	* the panel said at the moment of the tap. A missing main twin is never
+	* served silently as if it were the asked-for quality (D549 15).
+	*/
+	served: require_sleep.CamProfileSchema,
+	/**
+	* The DECODED duration of the delivered file, when the fetch measured one.
+	*
+	* A clip fetch verifies its own completion against the catalog row and
+	* retries a materially short pass (D568); this is that measurement, carried
+	* so a consumer can say the same thing rather than re-deriving it. Absent
+	* when the producer did not measure — never zero, which would say the file
+	* is empty.
+	*/
+	durationMs: zod.z.number().positive().optional()
+});
 var ClipSourceAvailabilitySchema = zod.z.object({
 	state: zod.z.enum([
 		"ok",
@@ -27555,22 +27634,40 @@ var videoclipsCapability = {
 			limit: zod.z.number().int().positive().optional(),
 			/**
 			* WHICH provider to ask — the `addonId` a {@link ClipSourceSchema} row
-			* carries, never a source id and never a list.
+			* carries, never a source id and never a list. **Required** (D554 amended).
 			*
-			* Absent means the device's BOUND provider, which is CamStack on every
-			* camera today because that is what `deviceManager.getBindings`
-			* answers with. A provider the device is not bound to is refused by
-			* name rather than answered by another one (D552's
-			* `rejectUnresolvedAddonPin` rule).
+			* A provider the device is not bound to is refused by name rather than
+			* answered by another one (D552's `rejectUnresolvedAddonPin` rule).
+			*
+			* It was optional, documented as "absent means the device's BOUND
+			* provider, which is CamStack on every camera". No code implemented
+			* that. Measured on the live hub 2026-09-20 — device 592, bound to
+			* `recorder` AND `provider-reolink` — a bare call with `limit: 3`
+			* answered SIX rows, three from each source, merged newest-first:
+			* `device-collection-dispatch.ts` simply left the fan-out un-narrowed,
+			* so absence bought the union this method exists not to be, and
+			* `limit` meant `limit × sources`.
+			*
+			* There is nothing to restore the default to. `getBindings` answers a
+			* collection cap with a DERIVED, PLURAL set (D554 amended, step 0);
+			* `setWrapperActive` — the singleton authority that could name one —
+			* throws for a collection cap by design. Naming CamStack here instead
+			* would privilege one addon by id inside a surface whose premise is
+			* that sources are peers, and would be wrong on the first camera with
+			* no recorder binding. So absence is REFUSED, in the schema, where the
+			* generated types make it unomittable rather than merely discouraged.
+			*
+			* The default belongs to the SURFACE, which has the `listSources` rows
+			* and can say which one it picked (D569 § 1–3; the viewer already
+			* always sends this).
 			*
 			* It replaced `sources?: string[]`, a VIEW filter over source ids that
 			* assumed the answer was a fan-out over everything a camera has. The
-			* operator settled otherwise on 2026-09-20 — *"il get videoclips
-			* prendere un provider opzionale, di default va su camstack"*,
-			* *"l'utilizzatore è uno solo"* — so the list is asked of one provider
-			* at a time and there is nothing to filter out of it.
+			* operator settled otherwise on 2026-09-20 — *"l'utilizzatore è uno
+			* solo"* — so the list is asked of one provider at a time and there is
+			* nothing to filter out of it.
 			*/
-			provider: zod.z.string().optional()
+			provider: zod.z.string().min(1)
 		}), zod.z.array(ClipSchema).readonly(), {
 			kind: "query",
 			auth: "protected"
@@ -27607,6 +27704,68 @@ var videoclipsCapability = {
 		}), ClipPlaybackSchema, {
 			kind: "query",
 			auth: "protected"
+		}),
+		/**
+		* This clip's BYTES, base64, bounded — the by-handle read a clip EXPORT
+		* pulls once (D558).
+		*
+		* `getClipPlayback` is the right answer for a player: it hands back a URL
+		* on a plane the hub serves `access:'authenticated'`, which a browser and a
+		* viewer session satisfy. It is the wrong answer for another ADDON. There
+		* is no addon→addon byte transport in this framework — `AddonDataPlane`
+		* only lets an addon SERVE, on `127.0.0.1` behind a per-listener secret
+		* only the hub may present — so a recorder that wants a camera's clip
+		* cannot fetch that URL. This method is the one seam that exists for it,
+		* and it is deliberately the same shape (and the same bound) as
+		* `recordingExport.readExportBytes`, which exists for the mirror-image
+		* reason.
+		*
+		* Routing needs no `provider` pin: the id is source-prefixed and
+		* self-contained, so `device-collection-dispatch.ts` rule 3 hands the call
+		* to the source that claims it — and an id nobody claims is REFUSED rather
+		* than answered by another source.
+		*
+		* The producer reuses the fetch path it already has, completion rules
+		* included: a clip is taken by cmd 5 and finished on a short idle window
+		* whose result is PROVED against the catalog row's own span, retried once
+		* when it comes up materially short, and served-and-named when it is still
+		* short (D568). A second fetch with different completion rules is exactly
+		* the second authority D558 refuses to create.
+		*
+		* Every refusal THROWS with its reason and none of them is silent — the
+		* sleep gate (decided before `getApi()`, liftable only by
+		* {@link ClipWakeSchema}), a catalog row nobody claims, a clip with no
+		* bytes behind it, a mux that failed, and the size bound. The caller turns
+		* that reason into an operator-facing one; a truncated file is never an
+		* answer.
+		*/
+		readClipBytes: require_sleep.optionalMethod(zod.z.object({
+			deviceId: zod.z.number(),
+			clipId: zod.z.string().min(1),
+			/**
+			* Which twin to fetch, on the mapping D549 15 already fixed:
+			* `low | mid` → the sub file, `high` → the main twin. `auto` is not
+			* accepted here for the same reason it is not accepted by
+			* `getClipPlayback` — a stored file has no broker session, so the
+			* adaptive tier cannot be resolved for it.
+			*/
+			profile: require_sleep.CamProfileSchema.optional(),
+			/**
+			* The CALLER's byte bound, so an over-size clip is refused before it is
+			* read and encoded rather than after. Capped by
+			* {@link VIDEOCLIPS_MAX_READ_BYTES} whatever is passed; absent means
+			* that ceiling.
+			*/
+			maxBytes: zod.z.number().int().positive().optional(),
+			/**
+			* The operator's authorisation to wake a sleeping camera for this
+			* read. Absent — the default — means a sleeping standalone battery
+			* camera is REFUSED by name, before any session is opened.
+			*/
+			wake: ClipWakeSchema.optional()
+		}), ClipBytesSchema, {
+			kind: "query",
+			auth: "protected"
 		})
 	}
 };
@@ -37127,13 +37286,135 @@ var ExportStateSchema = zod.z.enum([
 	"expired",
 	"deleted"
 ]);
-/** One export job / history row. */
+/**
+* A stretch of footage THIS system recorded — the only thing `createExport`
+* could export before D558, and still the shape every legacy caller sends.
+*/
+var ExportFootageSubjectSchema = zod.z.object({
+	kind: zod.z.literal("footage"),
+	deviceId: zod.z.number(),
+	profiles: zod.z.array(zod.z.string()).min(1),
+	fromMs: zod.z.number(),
+	toMs: zod.z.number()
+});
+/**
+* A CLIP — a finished file with boundaries the camera chose, listed by one of
+* the device's `videoclips` sources.
+*
+* There is deliberately **no `fromMs`/`toMs` here**. The camera chose them,
+* no surface on this path asks for them (there is no drag and no
+* `datetime-local` pair — D558 § 5.4.3), and they reach the record only as the
+* projection. A range in the subject would be a second place the boundaries
+* live and the one a caller could get wrong.
+*
+* `provider` is the **addonId** of the source's serving addon — the `provider`
+* pin `videoclips.listClips` REQUIRES since D554 was amended on 2026-09-20.
+* There was never a default: a bare call fanned out and returned the union of
+* every source with `limit` meaning `limit × sources`. The catalog check that
+* validates this subject names it, so it asks exactly the source the operator
+* picked.
+*
+* `source` is that source's id (the namespace `clipId` is prefixed with), and
+* `sourceLabel` is its operator-facing name FROZEN at creation — a history row
+* still reads "SD card" after the source is unbound.
+*
+* `profile` is exactly ONE, and it is what was ASKED. What was SERVED lands on
+* the record's top-level `profile`, so a clip with no main twin renders the
+* divergence instead of hiding it (D549 15; measured on 592, 17 of 546 clips
+* had no main twin, so a silent fallback would be right 96.9 % of the time).
+* `auto` is not a member: a stored file has no broker session, so the adaptive
+* tier cannot be resolved for it.
+*/
+var ExportClipSubjectSchema = zod.z.object({
+	kind: zod.z.literal("clip"),
+	deviceId: zod.z.number(),
+	provider: zod.z.string().min(1),
+	source: zod.z.string().min(1),
+	sourceLabel: zod.z.string().min(1),
+	clipId: zod.z.string().min(1),
+	/**
+	* WHERE IN THE CATALOG to confirm this clip — the day window the surface was
+	* already listing when the operator picked the segment.
+	*
+	* It is **not** a time range control and it never becomes one: the record's
+	* `fromMs`/`toMs` come from the catalog ROW and from nothing a caller
+	* supplied (D558 § 5.4.3), and a window that does not contain the clip is a
+	* `catalog-miss`, not a silently wider search. It exists because
+	* `videoclips.listClips` takes `since`/`until` and has no by-handle twin:
+	* the catalog check D558 asks for is literally that call, and a call needs a
+	* window. The surface has one — `ClipsBrowser`'s `dayWindow`, one local
+	* wall-clock day, which is also the only width measured to be cheap (one
+	* day on 592 lists 171 clips in 712 ms, a busy day 546 in 2.0 s; twenty days
+	* of one child's events took 3.6–5.4 s).
+	*/
+	catalogWindow: zod.z.object({
+		sinceMs: zod.z.number(),
+		untilMs: zod.z.number()
+	}),
+	profile: zod.z.enum([
+		"high",
+		"mid",
+		"low"
+	]),
+	/**
+	* The operator's authorisation to wake a sleeping camera for this export.
+	* ONE definition, in the cap that owns the clip read ({@link ClipWakeSchema}),
+	* because the gate that honours it is the clip provider's sleep gate — a
+	* second enum here would be a second contract. Absent by default; never
+	* settable by a scheduler or a retry.
+	*
+	* **One authorised yes is ONE wake.** A failed clip export is retried only by
+	* an operator act that asks again; a queued job that outlived its wake fails
+	* with a reason rather than waking on its turn; and this subject carries
+	* exactly one profile precisely so one tap is never two fetches (D558 § 5.2).
+	*/
+	wake: ClipWakeSchema.optional()
+});
+/**
+* WHAT an export is — the authority, as opposed to the four top-level fields
+* the Library sorts and labels on (D558 § 2.2).
+*
+* Read it through {@link exportSubjectOf}, never off the record directly: the
+* field is optional for the history rows written before it existed, and that
+* absence has exactly one interpreter.
+*/
+var ExportSubjectSchema = zod.z.discriminatedUnion("kind", [ExportFootageSubjectSchema, ExportClipSubjectSchema]);
+/**
+* One export job / history row.
+*
+* **`subject` is the AUTHORITY on what was exported. `deviceId`, `profile`,
+* `fromMs` and `toMs` are its PROJECTION** — kept top-level because the whole
+* Library sorts and labels on them (`library-items.ts` orders an export by
+* `fromMs`; `export-format.ts` draws `rangeLabel` from the pair), and a row
+* that did not fill them would sort under the epoch and render a blank range.
+* Write to the subject and read from the projection and the two will disagree;
+* the projection is derived at creation and never edited afterwards.
+*
+* And they mean DIFFERENT FACTS for the two kinds, which is the part a reader
+* who knows only the recording export will get wrong:
+*
+* | field | `kind:'footage'` | `kind:'clip'` |
+* | --- | --- | --- |
+* | `fromMs`/`toMs` | the stretch the operator ASKED for | the camera's own boundaries, always `clip.timeRange`, never anything a caller supplied |
+* | `profile` | the stream rendered | the twin actually SERVED (`subject.profile` is the one asked for) |
+*
+* Same type, different fact — the shape this repo keeps getting wrong (D385's
+* two authorities, D224's second copy).
+*/
 var ExportRecordSchema = zod.z.object({
 	id: zod.z.string(),
 	deviceId: zod.z.number(),
 	profile: zod.z.string(),
 	fromMs: zod.z.number(),
 	toMs: zod.z.number(),
+	/**
+	* What this export IS. Optional ONLY for the rows written before D558: the
+	* store parses every row through this schema on every read, so a required
+	* field would make the export AUDIT — which is the whole reason rows survive
+	* file deletion — unreadable in one release. Absence means `footage`, and
+	* {@link exportSubjectOf} is the one place that says so.
+	*/
+	subject: ExportSubjectSchema.optional(),
 	options: ExportOptionsSchema,
 	state: ExportStateSchema,
 	/** 0–100 while rendering; null otherwise. */
@@ -37150,6 +37431,49 @@ var ExportRecordSchema = zod.z.object({
 	/** Failure reason when state is 'failed'; null otherwise. */
 	error: zod.z.string().nullable()
 });
+/**
+* Every way a clip export can fail, as a TOKEN — never prose.
+*
+* A branch that accepts work and produces nothing is the branch this repo
+* keeps losing work in (D391), and a clip export has five places to lose it
+* that a recording export does not have. The token is what a surface may key
+* a table on; the PROSE — the camera's own words, the source's verbatim
+* refusal — travels with it, in the same `ExportRecord.error` string, after a
+* `: `. Two separate things in one field because the field is one field:
+* `ClipStillRefusalCodeSchema` split them across two HTTP headers for the same
+* reason, and the surface that keyed on the whole header rendered every
+* refusal on this fleet as `Refused: <prose>`.
+*
+* Compose with {@link clipExportFailure}, read back with
+* {@link clipExportFailureOf}. Never hand-spell the separator.
+*/
+var ClipExportFailureSchema = zod.z.enum([
+	"catalog-miss",
+	"catalog-unreachable",
+	"no-file-for-window",
+	"clip-in-progress",
+	"unsupported-option",
+	"sleeping",
+	"camera-refused",
+	"fetch-failed",
+	"too-large-to-transfer",
+	"wake-expired"
+]);
+/** `<token>: <prose>` — the ONE composition of a clip export's failure string. */
+function clipExportFailure(code, detail) {
+	return detail.length > 0 ? `${code}: ${detail}` : code;
+}
+/**
+* The token out of an {@link ExportRecord.error}, or null when the string did
+* not come from {@link clipExportFailure} (every footage failure, and every
+* error thrown by something that never heard of this vocabulary).
+*/
+function clipExportFailureOf(error) {
+	if (error === null) return null;
+	const head = error.split(":", 1)[0] ?? "";
+	const parsed = ClipExportFailureSchema.safeParse(head.trim());
+	return parsed.success ? parsed.data : null;
+}
 /** Candidate download URLs (LAN first, then operator extra hosts). */
 var ExportDownloadSchema = zod.z.object({
 	url: zod.z.string(),
@@ -37187,35 +37511,149 @@ var ExportBytesSchema = zod.z.object({
 	name: zod.z.string(),
 	bytes: zod.z.number().int().nonnegative()
 });
+/** Canonical `profiles[]`, falling back to the legacy singular `profile`. */
+function resolveExportProfiles(input) {
+	if (input.profiles !== void 0 && input.profiles.length > 0) return [...input.profiles];
+	if (typeof input.profile === "string" && input.profile.length > 0) return [input.profile];
+	return [];
+}
 /**
-* `createExport` input. `profiles` is the canonical field (min 1). A legacy
-* singular `profile` is still accepted so existing callers do not break.
+* `createExport` input — ONE object carrying an optional {@link ExportSubject},
+* never a union of two inputs.
 *
-* Must remain a ZodObject (`.loose()` for out-of-band `nodeId`).
+* It has to be a ZodObject: generated routers call `.input.loose()` so the
+* out-of-band `nodeId` selector survives the wire parse, and `.loose()` is a
+* ZodObject method a `z.discriminatedUnion` does not have. That is why the
+* discriminant sits one level down, in `subject`, and why
+* {@link resolveCreateExportSubject} — not a `z.preprocess` wrapper, which
+* would have produced a schema with no `.loose()` — is the one reading of a
+* legacy flat input as a subject.
+*
+* **`deviceId` stays REQUIRED at the top level**, for both kinds, and a clip
+* subject naming a different one is REFUSED. Not symmetry: `METHOD_DEVICE_SELECTORS`
+* (generated) maps top-level fields and one-level object arrays, so per-device
+* scope enforcement in `scope-access.ts` reads THIS field and cannot see
+* `subject.deviceId`. A deviceId that lived only in the subject would let a
+* principal scoped to one camera create an export — and, on the clip path, a
+* WAKE — for another.
+*
+* **A clip carries no time range**, and one supplied alongside a clip subject
+* is refused rather than ignored: there is no drag on this path and nothing to
+* normalise (D558 § 5.4.3). The record's `fromMs`/`toMs` come from the clip's
+* own `timeRange` and from nowhere else.
 */
 var CreateExportInputSchema = zod.z.object({
 	deviceId: zod.z.number(),
 	/** @deprecated Prefer `profiles`. Kept so timelapse/notifiers keep working. */
 	profile: zod.z.string().optional(),
 	profiles: zod.z.array(zod.z.string()).min(1).optional(),
-	fromMs: zod.z.number(),
-	toMs: zod.z.number(),
+	/** Footage only — a clip's boundaries are the camera's. */
+	fromMs: zod.z.number().optional(),
+	toMs: zod.z.number().optional(),
+	/** What to export. Absent means the legacy flat footage request. */
+	subject: ExportSubjectSchema.optional(),
 	options: ExportOptionsSchema
 }).superRefine((v, ctx) => {
-	if ((v.profiles !== void 0 && v.profiles.length > 0 ? v.profiles : v.profile !== void 0 ? [v.profile] : []).length < 1) ctx.addIssue({
+	if (v.subject?.kind === "clip") {
+		if (v.subject.deviceId !== v.deviceId) ctx.addIssue({
+			code: zod.z.ZodIssueCode.custom,
+			message: `subject.deviceId (${v.subject.deviceId}) must equal deviceId (${v.deviceId}) — the top-level field is what per-device scope enforcement reads`,
+			path: ["subject", "deviceId"]
+		});
+		if (v.fromMs !== void 0 || v.toMs !== void 0) ctx.addIssue({
+			code: zod.z.ZodIssueCode.custom,
+			message: "a clip export asks for no time range: the camera chose the boundaries and they are read from the catalog row",
+			path: ["fromMs"]
+		});
+		return;
+	}
+	if (v.subject?.kind === "footage" && v.subject.deviceId !== v.deviceId) ctx.addIssue({
+		code: zod.z.ZodIssueCode.custom,
+		message: `subject.deviceId (${v.subject.deviceId}) must equal deviceId (${v.deviceId})`,
+		path: ["subject", "deviceId"]
+	});
+	const fromMs = v.subject?.kind === "footage" ? v.subject.fromMs : v.fromMs;
+	const toMs = v.subject?.kind === "footage" ? v.subject.toMs : v.toMs;
+	if (typeof fromMs !== "number" || typeof toMs !== "number") ctx.addIssue({
+		code: zod.z.ZodIssueCode.custom,
+		message: "a footage export needs fromMs and toMs",
+		path: ["fromMs"]
+	});
+	if ((v.subject?.kind === "footage" ? [...v.subject.profiles] : resolveExportProfiles(v)).length < 1) ctx.addIssue({
 		code: zod.z.ZodIssueCode.custom,
 		message: "pass profiles[] (min 1) or legacy profile",
 		path: ["profiles"]
 	});
 });
+/**
+* The ONE reading of a `createExport` input as a {@link ExportSubject}.
+*
+* Every consumer goes through this: a provider that branched on
+* `input.subject !== undefined` in one place and on `input.fromMs` in another
+* would be two authorities on what was asked for, which is how the flat fields
+* and the subject drift apart.
+*
+* Throws on a footage input with no range — an input that parsed cannot reach
+* that, and a caller that skipped the parse gets a named refusal rather than
+* `NaN` boundaries on a durable row.
+*/
+function resolveCreateExportSubject(input) {
+	if (input.subject !== void 0) return input.subject;
+	const profiles = resolveExportProfiles(input);
+	if (typeof input.fromMs !== "number" || typeof input.toMs !== "number") throw new Error("recording-export: a footage export needs fromMs and toMs");
+	return {
+		kind: "footage",
+		deviceId: input.deviceId,
+		profiles,
+		fromMs: input.fromMs,
+		toMs: input.toMs
+	};
+}
+/**
+* The ONE interpreter of a stored row's subject.
+*
+* `ExportRecord.subject` is optional for exactly one reason — the history rows
+* written before D558 — and "absent means footage, built from the projection"
+* is a statement that must live in one place. Anything that reads
+* `rec.subject` directly and falls back inline is the second authority.
+*/
+function exportSubjectOf(rec) {
+	if (rec.subject !== void 0) return rec.subject;
+	return {
+		kind: "footage",
+		deviceId: rec.deviceId,
+		profiles: [rec.profile],
+		fromMs: rec.fromMs,
+		toMs: rec.toMs
+	};
+}
 var recordingExportCapability = {
 	name: "recording-export",
 	scope: "system",
 	mode: "singleton",
 	methods: {
-		/** Queue a render of `[fromMs,toMs)` for `deviceId`/`profiles` (legacy
-		*  singular `profile` still accepted). Fails fast when no footage covers
-		*  the range. One job per profile; returns the first queued record. */
+		/**
+		* Queue an export of {@link ExportSubjectSchema}.
+		*
+		* `kind:'footage'` — a render of `[fromMs,toMs)` for `deviceId`/`profiles`
+		* (legacy flat input, singular `profile` included, still accepted and
+		* rewritten). Fails fast when no footage covers the range. One job per
+		* profile; **returns the first queued record and the others are reachable
+		* only through `listExports`** — a defect named in D558 § 6.3 and the
+		* reason a clip subject carries exactly ONE profile.
+		*
+		* `kind:'clip'` — a finished file the camera holds, validated against the
+		* device's clip CATALOG (`videoclips.listClips`, at the subject's
+		* `provider`) instead of the recording index, and fetched once by handle
+		* under a bound. Its `fromMs`/`toMs` come from the catalog row and from
+		* nowhere else; a caller supplying a range is refused.
+		*
+		* A clip export reuses the six {@link ExportStateSchema} members and adds
+		* none: the viewer maps an unknown state string to `failed`, so a seventh
+		* member renders every live export — of both kinds — as FAILED on every
+		* installed app (D558 § 6.1, pinned by `export-state-members.spec.ts`).
+		* `subject.kind` is what tells a surface what `rendering` means.
+		*/
 		createExport: require_sleep.method(CreateExportInputSchema, ExportRecordSchema, {
 			kind: "mutation",
 			auth: "protected"
@@ -51097,6 +51535,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"videoclips.readClipBytes": {
+		capName: "videoclips",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"viewerUi.getStaticDir": {
 		capName: "viewer-ui",
 		capScope: "system",
@@ -53388,6 +53832,11 @@ var METHOD_DEVICE_SELECTORS = Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"videoclips.readClipBytes": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"waterHeater.setAway": [{
 		name: "deviceId",
 		form: "single",
@@ -59052,12 +59501,15 @@ exports.CarbonMonoxideStatusSchema = CarbonMonoxideStatusSchema;
 exports.ChargingStatus = require_sleep.ChargingStatus;
 exports.ClientNetworkStatsSchema = ClientNetworkStatsSchema;
 exports.ClimateControlStatusSchema = ClimateControlStatusSchema;
+exports.ClipBytesSchema = ClipBytesSchema;
+exports.ClipExportFailureSchema = ClipExportFailureSchema;
 exports.ClipPlaybackSchema = ClipPlaybackSchema;
 exports.ClipSchema = ClipSchema;
 exports.ClipSourceAvailabilitySchema = ClipSourceAvailabilitySchema;
 exports.ClipSourceSchema = ClipSourceSchema;
 exports.ClipStillDispositionSchema = ClipStillDispositionSchema;
 exports.ClipStillRefusalCodeSchema = ClipStillRefusalCodeSchema;
+exports.ClipWakeSchema = ClipWakeSchema;
 exports.ClusterAddonNodeDeploymentSchema = ClusterAddonNodeDeploymentSchema;
 exports.ClusterAddonStatusEntrySchema = ClusterAddonStatusEntrySchema;
 exports.CollectionColumnSchema = CollectionColumnSchema;
@@ -59217,15 +59669,18 @@ exports.EventMediaProductionSchema = EventMediaProductionSchema;
 exports.EventOwnerTypeSchema = EventOwnerTypeSchema;
 exports.EventSourceType = require_enums.EventSourceType$1;
 exports.ExportBytesSchema = ExportBytesSchema;
+exports.ExportClipSubjectSchema = ExportClipSubjectSchema;
 exports.ExportDenseRangeSchema = ExportDenseRangeSchema;
 exports.ExportDenseSchema = ExportDenseSchema;
 exports.ExportDownloadSchema = ExportDownloadSchema;
+exports.ExportFootageSubjectSchema = ExportFootageSubjectSchema;
 exports.ExportOptionsSchema = ExportOptionsSchema;
 exports.ExportRecordSchema = ExportRecordSchema;
 exports.ExportSetupFieldSchema = ExportSetupFieldSchema;
 exports.ExportSetupSchema = ExportSetupSchema;
 exports.ExportSpeedSchema = ExportSpeedSchema;
 exports.ExportStateSchema = ExportStateSchema;
+exports.ExportSubjectSchema = ExportSubjectSchema;
 exports.ExportTimelapseSchema = ExportTimelapseSchema;
 exports.ExposedDeviceSchema = ExposedDeviceSchema;
 exports.ExposureModeSchema = ExposureModeSchema;
@@ -59952,6 +60407,7 @@ exports.UpdateStatusSchema = UpdateStatusSchema;
 exports.UpdateUserInputSchema = UpdateUserInputSchema;
 exports.UserRecordSchema = UserRecordSchema;
 exports.UserSummarySchema = UserSummarySchema;
+exports.VIDEOCLIPS_MAX_READ_BYTES = VIDEOCLIPS_MAX_READ_BYTES;
 exports.VISIT_MERGE_GAP_MS = VISIT_MERGE_GAP_MS;
 exports.VacuumControlStatusSchema = VacuumControlStatusSchema;
 exports.VacuumStateSchema = VacuumStateSchema;
@@ -60072,6 +60528,8 @@ exports.classifyBearerPrincipal = classifyBearerPrincipal;
 exports.classifyStream = classifyStream;
 exports.classifyStreams = classifyStreams;
 exports.climateControlCapability = climateControlCapability;
+exports.clipExportFailure = clipExportFailure;
+exports.clipExportFailureOf = clipExportFailureOf;
 exports.clusterModelSettingKey = clusterModelSettingKey;
 exports.clusterStepSettingFieldsFor = clusterStepSettingFieldsFor;
 exports.clusterStepSettingKey = clusterStepSettingKey;
@@ -60171,6 +60629,7 @@ exports.evictionPolicyForMode = evictionPolicyForMode;
 exports.evictionPolicyOfLocation = evictionPolicyOfLocation;
 exports.expandAudioChunkToF32le = require_sleep.expandAudioChunkToF32le;
 exports.expandCapMethods = require_sleep.expandCapMethods;
+exports.exportSubjectOf = exportSubjectOf;
 exports.extractNestedAddonId = extractNestedAddonId;
 exports.extractSourceInfoFromMetadata = extractSourceInfoFromMetadata;
 exports.faceGalleryCapability = faceGalleryCapability;
@@ -60305,6 +60764,7 @@ exports.oauthIntegrationCapability = oauthIntegrationCapability;
 exports.objectInputDeclaresAddonId = objectInputDeclaresAddonId;
 exports.objectInputDeclaresRequiredDeviceId = objectInputDeclaresRequiredDeviceId;
 exports.occupancyScope = occupancyScope;
+exports.optionalMethod = require_sleep.optionalMethod;
 exports.osdCapability = osdCapability;
 exports.osdManagerCapability = osdManagerCapability;
 exports.overlayClusterStepSettings = overlayClusterStepSettings;
@@ -60372,10 +60832,12 @@ exports.resolveBucketMs = resolveBucketMs;
 exports.resolveCapMount = require_sleep.resolveCapMount;
 exports.resolveClusterStepModelId = resolveClusterStepModelId;
 exports.resolveContainerPrimaryChild = resolveContainerPrimaryChild;
+exports.resolveCreateExportSubject = resolveCreateExportSubject;
 exports.resolveDetectionRuntime = resolveDetectionRuntime;
 exports.resolveDeviceControlKind = resolveDeviceControlKind;
 exports.resolveDeviceProfile = resolveDeviceProfile;
 exports.resolveEgressDecodeHwAccel = resolveEgressDecodeHwAccel;
+exports.resolveExportProfiles = resolveExportProfiles;
 exports.resolveFormat = resolveFormat;
 exports.resolveHydratedFieldValue = require_sleep.resolveHydratedFieldValue;
 exports.resolveLocationIcon = resolveLocationIcon;