@camstack/addon-pipeline 1.2.273 → 1.2.275

package/dist/{dist-DRDzfOnl.js → dist-NYjn7hkE.js}

@@ -5360,7 +5360,7 @@ var ZodIssueCode = {
 var ZodFirstPartyTypeKind;
 ZodFirstPartyTypeKind || (ZodFirstPartyTypeKind = {});
 //#endregion
-//#region ../types/dist/sleep-CopaBJss.mjs
+//#region ../types/dist/sleep-BVhJDJka.mjs
 /**
 * The audio chunk plane's byte format, and the ONE expansion from a coded
 * window to float samples (D455).
@@ -5592,12 +5592,6 @@ Object.fromEntries([
 		icon: "circle-dot",
 		order: 40
 	},
-	{
-		id: "clips",
-		label: "Clips",
-		icon: "clapperboard",
-		order: 41
-	},
 	{
 		id: "engine",
 		label: "Inference Engine",
@@ -7108,6 +7102,18 @@ function systemMethod(input, output, options) {
 		systemOnly: true
 	};
 }
+/**
+* A method a SOURCE of a collection cap may legitimately not serve — OPTIONAL
+* on `InferProvider`. The `providerOptional: true` literal is what
+* `InferProvider` keys on; see {@link CapabilityMethodSchema.providerOptional}
+* for when this is the honest answer and when it is a soft stub.
+*/
+function optionalMethod(input, output, options) {
+	return {
+		...method(input, output, options),
+		providerOptional: true
+	};
+}
 /** Shorthand to define an event schema */
 function event(data) {
 	return { data };
@@ -8347,6 +8353,8 @@ var EVENT_OWNER_TYPES = [
 * nothing failing until a caller asked.
 */
 var EventOwnerTypeSchema = _enum(EVENT_OWNER_TYPES);
+/** The same list as a Zod enum, for the cap input that carries it. */
+var MediaPresenceOwnerKindSchema = _enum([...EVENT_OWNER_TYPES, "track"]);
 new Set(EVENT_OWNER_TYPES);
 var EncodeProfileSchema = object({
 	video: object({
@@ -9327,6 +9335,24 @@ var DetectionCatalogClassMapSchema = object({
 	preserveOriginal: boolean()
 });
 /**
+* THE canonical event-clip pad: the time window a single-timestamp analytics
+* event expands to when joined with footage (clip window = `[timestamp - preMs,
+* timestamp + postMs]`). Matches the admin-ui clip window (−5s/+10s).
+*
+* Every consumer derives from this ONE constant so event↔footage boundaries
+* agree everywhere (C1): today that is the `videoclips` default provider
+* (addon-post-analysis), which pads its clip windows with it. The recorder used
+* to pad in-RAM playback markers with it too; those markers had no reader
+* anywhere in the repo and were deleted on 2026-08-29.
+*
+* NOTE: this is a UI/JOIN convention, NOT the `events`-band keep/discard gate —
+* that uses the per-device `preBufferSec`/`postBufferSec` config.
+*/
+var EVENT_PAD_MS = {
+	preMs: 5e3,
+	postMs: 1e4
+};
+/**
 * Numeric day-of-week: 0 = Sunday … 6 = Saturday (matches `Date.getDay`).
 * Named `RecordingWeekday` to avoid collision with the string-union
 * `Weekday` exported from `interfaces/timezones.ts`.
@@ -9543,7 +9569,20 @@ function stripRetiredBandPreBufferSec(config) {
 		strippedBands
 	};
 }
-DEFAULT_EVENTS_BAND_BUFFER_SEC.postBufferSec * 1e3;
+/**
+* Adjacent recorded ranges closer than this belong to the SAME videoclip visit.
+*
+* This is NOT the recorder calendar merge (`RANGE_MERGE_GAP_MS = 5s`). That
+* threshold is for the timeline bar, which must show exact holes — including
+* the ~8s GOP/keyframe rolls measured on events-mode cameras (dispensa 1438,
+* 2026-08-16). A videoclip is the events-mode keep-window (writer session),
+* whose idle bound is `postBufferSec`. Using that default (30s) glues those
+* intra-visit holes without joining visits hours apart.
+*
+* Segments stay the source of truth on disk (`startMs-durMs-bytes.m4s`); a
+* visit is derived, not a second copy of the files.
+*/
+var VISIT_MERGE_GAP_MS = DEFAULT_EVENTS_BAND_BUFFER_SEC.postBufferSec * 1e3;
 /**
 * Per-device retention overrides. Every field is optional; an unset or `0`
 * value inherits the node-wide recorder default. Only footage-lifetime limits
@@ -16442,8 +16481,6 @@ 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",
@@ -23935,7 +23972,11 @@ DeviceType.Camera, method(object({ deviceId: number() }), array(TrackSchema).rea
 	ownerType: EventOwnerTypeSchema,
 	eventId: number().int(),
 	deviceId: number()
-}), array(MediaFileInfoSchema).readonly()), method(SearchObjectEventsInput, array(ScoredObjectEventSchema).readonly()), method(object({}), WipeObjectEmbeddingsResultSchema, {
+}), array(MediaFileInfoSchema).readonly()), method(object({
+	deviceId: number(),
+	ownerKind: MediaPresenceOwnerKindSchema,
+	ownerIds: array(string()).max(5e3)
+}), array(string()).readonly()), method(SearchObjectEventsInput, array(ScoredObjectEventSchema).readonly()), method(object({}), WipeObjectEmbeddingsResultSchema, {
 	kind: "mutation",
 	auth: "admin"
 }), method(RebuildObjectEmbeddingsInput, RebuildObjectEmbeddingsResultSchema, {
@@ -27163,6 +27204,18 @@ method(VectorDeclareIndexInputSchema, _void(), {
 	kind: "mutation",
 	auth: "admin"
 }), method(VectorStatsInputSchema, VectorStatsResultSchema, { auth: "admin" });
+_enum([
+	"queue-full",
+	"camera-backoff",
+	"sleeping",
+	"camera-refused",
+	"no-keyframe",
+	"no-catalog-row",
+	"unsupported",
+	"unknown-device",
+	"uid-missing"
+]);
+_enum(["deferred", "final"]);
 var ClipSchema = object({
 	/** Opaque, provider-namespaced id. The default provider encodes the time
 	*  window so `getClipPlayback` is self-contained (no event re-query). */
@@ -27313,7 +27366,25 @@ var ClipSchema = object({
 	*/
 	playable: boolean().optional(),
 	/** Why {@link playable} is false, verbatim (`no-file-for-window`). */
-	unplayableReason: string().optional()
+	unplayableReason: string().optional(),
+	/**
+	* This clip is STILL BEING WRITTEN, so {@link ClipSchema.timeRange}`.endMs`
+	* is not its end.
+	*
+	* Absent — the common case — means the row is closed and its `endMs` is the
+	* end of the recording. Present and `true` means the source told us the file
+	* has no end yet, and the `endMs` we carry is whatever the camera's index
+	* entry happened to hold: on a Reolink E1 Outdoor PoE (592, measured
+	* 2026-09-20) the newest file `…_192927_000000_…_0.mp4` reported an `endTime`
+	* of 19:29:56 and STILL reported it eight minutes later, while the file went
+	* on growing. A surface that drew 29 s there was lying about a clip that
+	* plays for minutes, on the one row the operator looks at first.
+	*
+	* `endMs` is deliberately still a number: it is the best bound anything has
+	* for a mint window or a byte fetch, and every consumer already requires it.
+	* This flag says what it is WORTH, and a duration is not drawn from it.
+	*/
+	inProgress: boolean().optional()
 });
 var ClipPlaybackSchema = object({
 	/**
@@ -27359,6 +27430,59 @@ var ClipPlaybackSchema = 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 = _enum(["authorised"]);
+/**
+* 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 = object({
+	base64: string(),
+	contentType: string(),
+	/** Suggested filename, extension included. */
+	name: string(),
+	bytes: 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: 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: number().positive().optional()
+});
 var ClipSourceAvailabilitySchema = object({
 	state: _enum([
 		"ok",
@@ -27396,99 +27520,205 @@ var ClipSourceSchema = object({
 	* 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).
+	* (D557). One addon may serve SEVERAL sources, which is why the per-device
+	* switch is keyed by SOURCE and not by this (D555) — `addon-provider-reolink`
+	* served a hub child two of them until the two views were measured to be one
+	* store read twice (D555) and then read ONE way (D565).
 	*
 	* 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()
+	availability: ClipSourceAvailabilitySchema
 });
-DeviceType.Camera, method(object({
-	deviceId: number(),
-	since: number(),
-	until: number(),
-	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: "protected"
-}), method(object({ deviceId: number() }), array(ClipSourceSchema).readonly(), {
-	kind: "query",
-	auth: "protected"
-}), method(object({
-	deviceId: number(),
-	clipId: string(),
+var videoclipsCapability = {
+	name: "videoclips",
+	scope: "device",
+	mode: "collection",
+	kind: "wrapper",
+	defaultActive: true,
+	/** A clip is a window over a camera's footage — the cap is meaningless on a
+	*  sensor, a button or an event emitter, and the `defaultActive` auto-bind
+	*  reads this to decide which devices it may claim. */
+	deviceTypes: [DeviceType.Camera],
 	/**
-	* 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: "protected"
-});
+	* The Clips section of a camera's device details is FRAMEWORK-DERIVED (D14):
+	* the aggregator turns this declaration into the `type:'widget'` section and
+	* `DeviceDetail.tsx` is never edited. `videoclips` is the first WRAPPER cap
+	* to declare one — every previous `host/` widget cap is `deviceNative` — so
+	* `device-config-widget-wrapped-binding.spec.ts` pins that a `kind:'wrapped'`
+	* binding entry derives the same section a native one does.
+	*
+	* **It is a SECTION of the Recording tab, at the end of it — not a tab of
+	* its own.** It shipped as a `clips` top-tab and the operator rejected the
+	* placement: *"utilizzerei la stessa tab recordings, lì abbiamo già tutto il
+	* necessario, una nuova sezione alla fine per le clips"*. The Recording tab
+	* already holds the recorder's panel, the schedule bands and the unified
+	* retention policy; footage the camera itself holds is the same question,
+	* asked of a different store. `order: 100` puts it after all of them with
+	* room left in front. The `clips` entry in `WELL_KNOWN_TABS` went with it —
+	* a well-known id nobody declares is an invitation to mint the tab again.
+	*
+	* `topTab` stays: the browser owns a pane (a day's tiles, a source list and
+	* a player) and the Config tab's inner bar has no room for one. The widget
+	* itself is `host/clips-browser` in ui-library's `HOST_WIDGETS`, and because
+	* the admin Recordings page renders every `location:'top-tab'` +
+	* `tab:'recording'` section behind its camera picker
+	* (`CameraRecordingSettingsSection`), this declaration lands the section on
+	* BOTH surfaces with no second wiring.
+	*/
+	deviceConfig: { ui: {
+		kind: "widget",
+		widgetId: "host/clips-browser",
+		tab: "recording",
+		topTab: true,
+		label: "Clips",
+		order: 100
+	} },
+	methods: {
+		listClips: method(object({
+			deviceId: number(),
+			since: number(),
+			until: number(),
+			limit: number().int().positive().optional(),
+			/**
+			* WHICH provider to ask — the `addonId` a {@link ClipSourceSchema} row
+			* carries, never a source id and never a list. **Required** (D554 amended).
+			*
+			* 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 — *"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: string().min(1)
+		}), array(ClipSchema).readonly(), {
+			kind: "query",
+			auth: "protected"
+		}),
+		/**
+		* The sources this camera has, WITH the reason any of them cannot answer.
+		*
+		* Asked separately from `listClips` because an empty clip list is
+		* ambiguous and this is the only place the ambiguity is resolved: every
+		* bound provider contributes its own rows, and a provider that could not
+		* be reached at all still produces one row saying so. A surface that draws
+		* "no clips" without reading this is drawing a guess.
+		*/
+		listSources: method(object({ deviceId: number() }), array(ClipSourceSchema).readonly(), {
+			kind: "query",
+			auth: "protected"
+		}),
+		getClipPlayback: method(object({
+			deviceId: number(),
+			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: "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: optionalMethod(object({
+			deviceId: number(),
+			clipId: 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: 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: 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"
+		})
+	}
+};
 /**
 * Optional client-side hints sent at session creation to help the provider
 * pick the best native source. All fields optional — a viewer that knows
@@ -33779,13 +34009,101 @@ var ExportStateSchema = _enum([
 	"expired",
 	"deleted"
 ]);
-/** One export job / history row. */
+/**
+* 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 = discriminatedUnion("kind", [object({
+	kind: literal("footage"),
+	deviceId: number(),
+	profiles: array(string()).min(1),
+	fromMs: number(),
+	toMs: number()
+}), object({
+	kind: literal("clip"),
+	deviceId: number(),
+	provider: string().min(1),
+	source: string().min(1),
+	sourceLabel: string().min(1),
+	clipId: 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: object({
+		sinceMs: number(),
+		untilMs: number()
+	}),
+	profile: _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()
+})]);
+/**
+* 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 = object({
 	id: string(),
 	deviceId: number(),
 	profile: string(),
 	fromMs: number(),
 	toMs: 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. */
@@ -33802,6 +34120,49 @@ var ExportRecordSchema = object({
 	/** Failure reason when state is 'failed'; null otherwise. */
 	error: 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 = _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 = object({
 	url: string(),
@@ -33839,29 +34200,150 @@ var ExportBytesSchema = object({
 	name: string(),
 	bytes: 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 — ONE object carrying an optional {@link ExportSubject},
+* never a union of two inputs.
+*
+* 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 = object({
+	deviceId: number(),
+	/** @deprecated Prefer `profiles`. Kept so timelapse/notifiers keep working. */
+	profile: string().optional(),
+	profiles: array(string()).min(1).optional(),
+	/** Footage only — a clip's boundaries are the camera's. */
+	fromMs: number().optional(),
+	toMs: number().optional(),
+	/** What to export. Absent means the legacy flat footage request. */
+	subject: ExportSubjectSchema.optional(),
+	options: ExportOptionsSchema
+}).superRefine((v, ctx) => {
+	if (v.subject?.kind === "clip") {
+		if (v.subject.deviceId !== v.deviceId) ctx.addIssue({
+			code: 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: 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: 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: 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: 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. */
-		createExport: method(object({
-			deviceId: number(),
-			/** @deprecated Prefer `profiles`. Kept so timelapse/notifiers keep working. */
-			profile: string().optional(),
-			profiles: array(string()).min(1).optional(),
-			fromMs: number(),
-			toMs: number(),
-			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({
-				code: ZodIssueCode.custom,
-				message: "pass profiles[] (min 1) or legacy profile",
-				path: ["profiles"]
-			});
-		}), ExportRecordSchema, {
+		/**
+		* 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: method(CreateExportInputSchema, ExportRecordSchema, {
 			kind: "mutation",
 			auth: "protected"
 		}),
@@ -39469,6 +39951,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"pipelineAnalytics.ownersWithMedia": {
+		capName: "pipeline-analytics",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"pipelineAnalytics.pauseForStorageMigration": {
 		capName: "pipeline-analytics",
 		capScope: "device",
@@ -42067,6 +42555,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"videoclips.readClipBytes": {
+		capName: "videoclips",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"viewerUi.getStaticDir": {
 		capName: "viewer-ui",
 		capScope: "system",
@@ -43369,6 +43863,11 @@ Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"pipelineAnalytics.ownersWithMedia": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"pipelineAnalytics.proposeRetrainAnnotations": [{
 		name: "deviceId",
 		form: "single",
@@ -44080,6 +44579,11 @@ Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"videoclips.readClipBytes": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"waterHeater.setAway": [{
 		name: "deviceId",
 		form: "single",
@@ -45899,6 +46403,12 @@ Object.defineProperty(exports, "COCO_TO_MACRO", {
 		return COCO_TO_MACRO;
 	}
 });
+Object.defineProperty(exports, "CamProfileSchema", {
+	enumerable: true,
+	get: function() {
+		return CamProfileSchema;
+	}
+});
 Object.defineProperty(exports, "DEFAULT_AUDIO_ANALYZER_CONFIG", {
 	enumerable: true,
 	get: function() {
@@ -45959,6 +46469,18 @@ Object.defineProperty(exports, "DeviceType", {
 		return DeviceType;
 	}
 });
+Object.defineProperty(exports, "EVENT_OWNER_TYPES", {
+	enumerable: true,
+	get: function() {
+		return EVENT_OWNER_TYPES;
+	}
+});
+Object.defineProperty(exports, "EVENT_PAD_MS", {
+	enumerable: true,
+	get: function() {
+		return EVENT_PAD_MS;
+	}
+});
 Object.defineProperty(exports, "EncodeProfileSchema", {
 	enumerable: true,
 	get: function() {
@@ -46067,6 +46589,12 @@ Object.defineProperty(exports, "RingBuffer", {
 		return RingBuffer;
 	}
 });
+Object.defineProperty(exports, "VISIT_MERGE_GAP_MS", {
+	enumerable: true,
+	get: function() {
+		return VISIT_MERGE_GAP_MS;
+	}
+});
 Object.defineProperty(exports, "YAMNET_TO_MACRO", {
 	enumerable: true,
 	get: function() {
@@ -46139,6 +46667,18 @@ Object.defineProperty(exports, "cameraStreamsCapability", {
 		return cameraStreamsCapability;
 	}
 });
+Object.defineProperty(exports, "clipExportFailure", {
+	enumerable: true,
+	get: function() {
+		return clipExportFailure;
+	}
+});
+Object.defineProperty(exports, "clipExportFailureOf", {
+	enumerable: true,
+	get: function() {
+		return clipExportFailureOf;
+	}
+});
 Object.defineProperty(exports, "createEvent", {
 	enumerable: true,
 	get: function() {
@@ -46265,6 +46805,12 @@ Object.defineProperty(exports, "expandAudioChunkToF32le", {
 		return expandAudioChunkToF32le;
 	}
 });
+Object.defineProperty(exports, "exportSubjectOf", {
+	enumerable: true,
+	get: function() {
+		return exportSubjectOf;
+	}
+});
 Object.defineProperty(exports, "failureContributionCapability", {
 	enumerable: true,
 	get: function() {
@@ -46517,6 +47063,12 @@ Object.defineProperty(exports, "resolveClusterStepModelId", {
 		return resolveClusterStepModelId;
 	}
 });
+Object.defineProperty(exports, "resolveCreateExportSubject", {
+	enumerable: true,
+	get: function() {
+		return resolveCreateExportSubject;
+	}
+});
 Object.defineProperty(exports, "resolveEgressDecodeHwAccel", {
 	enumerable: true,
 	get: function() {
@@ -46601,6 +47153,12 @@ Object.defineProperty(exports, "union", {
 		return union;
 	}
 });
+Object.defineProperty(exports, "videoclipsCapability", {
+	enumerable: true,
+	get: function() {
+		return videoclipsCapability;
+	}
+});
 Object.defineProperty(exports, "webrtcSessionCapability", {
 	enumerable: true,
 	get: function() {