@camstack/types 1.2.236 → 1.2.238

package/dist/addon.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_err_msg = require("./err-msg-COpsHMw2.js");
 //#region src/generated/cap-input-defaults.ts

package/dist/addon.mjs

@@ -1,4 +1,4 @@
-import { A as DeviceType, At as emitReadiness, Ct as DATAPLANE_SECRET_HEADER, Dt as normalizeAddonInitResult, Et as BaseAddon, G as ReadinessRegistry, H as nodePin, I as expandCapMethods, K as ReadinessTimeoutError, S as DEVICE_CHILDREN_BATCH_MAX, T as describeCustomActions, Tt as DisposerChain, U as readNodePin, Y as scopeKey, a as asJsonObject, b as deviceOpsCapability, d as BOOT_RECOVERY_BACKOFF_MS, f as DEVICE_SCOPED_CAPS, h as createEventBusSliceSource, j as adminUiCapability, m as createDeviceProxy, p as isDeviceScopedCap, s as asString, t as sleep, u as parseJsonUnknown, x as viewerUiCapability } from "./sleep-CaB_hL5g.mjs";
+import { A as DeviceType, Dt as BaseAddon, Et as DisposerChain, I as expandCapMethods, K as ReadinessRegistry, Ot as normalizeAddonInitResult, S as DEVICE_CHILDREN_BATCH_MAX, T as describeCustomActions, U as nodePin, W as readNodePin, X as scopeKey, a as asJsonObject, b as deviceOpsCapability, d as BOOT_RECOVERY_BACKOFF_MS, f as DEVICE_SCOPED_CAPS, h as createEventBusSliceSource, j as adminUiCapability, jt as emitReadiness, m as createDeviceProxy, p as isDeviceScopedCap, q as ReadinessTimeoutError, s as asString, t as sleep, u as parseJsonUnknown, wt as DATAPLANE_SECRET_HEADER, x as viewerUiCapability } from "./sleep-BVhJDJka.mjs";
 import { t as EventCategory } from "./event-category-BVDXG4tB.mjs";
 import { t as errMsg } from "./err-msg-IQTHeDzc.mjs";
 //#region src/generated/cap-input-defaults.ts

package/dist/capabilities/capability-definition.d.ts

@@ -107,6 +107,29 @@ export interface CapabilityMethodSchema<TInput extends z.ZodType = z.ZodType, TO
      * rationale as the status-Partial on native providers.
      */
     readonly systemOnly?: boolean;
+    /**
+     * When true the method is OPTIONAL on `InferProvider` — a source of a
+     * COLLECTION cap may legitimately not serve it.
+     *
+     * Not the same thing as {@link systemOnly}, which is about the native/system
+     * split of ONE addon. This is about peers: a `mode:'collection'` cap's
+     * providers are sources listed beside each other, none privileged, and they
+     * do genuinely different things. `videoclips.readClipBytes` is the case —
+     * the recorder's `analytics` source is a time WINDOW over footage with no
+     * file behind it at all, so demanding the method of it buys a throwing stub,
+     * and a throwing stub reads exactly like a method somebody forgot.
+     *
+     * The RUNTIME already treated absence as a named case: `callSource`
+     * (`device-collection-dispatch.ts`) answers a missing method with
+     * `NOT_IMPLEMENTED` naming the cap, the source and the method, and
+     * `isCollectionArrayMethod` lets a missing ARRAY method contribute `[]`
+     * rather than emptying the fan-out. This flag stops the TYPE from demanding
+     * what the framework never needed.
+     *
+     * Use it only where a source's ABSENCE of the method is a fact about that
+     * source, never to soften a method somebody has not got round to writing.
+     */
+    readonly providerOptional?: boolean;
     /**
      * Opt-in caller-identity injection (D-1). When `'required'`, the hub
      * cap-router injects a server-derived {@link CapCaller} into the input
@@ -804,8 +827,16 @@ type ProviderMethodInput<M, TIn extends z.ZodType> = M extends {
 } ? z.infer<TIn> & {
     readonly caller: CapCaller;
 } : z.infer<TIn>;
+/** One provider method's callable shape, subscription arm included. */
+type ProviderMethodFn<M> = M extends CapabilityMethodSchema<infer TIn, infer TOut> ? M['kind'] extends 'subscription' ? (input: z.infer<TIn>, push: (value: z.infer<TOut>) => void) => (() => void) | void : (input: ProviderMethodInput<M, TIn>) => Promise<z.infer<TOut>> : never;
 export type InferProvider<T extends CapabilityDefinition> = {
-    readonly [K in keyof T['methods']]: T['methods'][K] extends CapabilityMethodSchema<infer TIn, infer TOut> ? T['methods'][K]['kind'] extends 'subscription' ? (input: z.infer<TIn>, push: (value: z.infer<TOut>) => void) => (() => void) | void : (input: ProviderMethodInput<T['methods'][K], TIn>) => Promise<z.infer<TOut>> : never;
+    readonly [K in keyof T['methods'] as T['methods'][K] extends {
+        providerOptional: true;
+    } ? never : K]: ProviderMethodFn<T['methods'][K]>;
+} & {
+    readonly [K in keyof T['methods'] as T['methods'][K] extends {
+        providerOptional: true;
+    } ? K : never]?: ProviderMethodFn<T['methods'][K]>;
 } & (T['exposesDeviceSettings'] extends true ? DeviceSettingsContribution : Record<never, never>) & (T extends {
     status: CapabilityStatusSchema;
 } ? DeviceStatusContribution<InferStatus<T>> : Record<never, never>);
@@ -935,6 +966,15 @@ export declare function method<TIn extends z.ZodType, TOut extends z.ZodType, TK
 export declare function systemMethod<TIn extends z.ZodType, TOut extends z.ZodType, TKind extends CapabilityMethodKind = 'query'>(input: TIn, output: TOut, options?: CapabilityMethodOptions<TKind>): CapabilityMethodSchema<TIn, TOut, TKind> & {
     readonly 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.
+ */
+export declare function optionalMethod<TIn extends z.ZodType, TOut extends z.ZodType, TKind extends CapabilityMethodKind = 'query'>(input: TIn, output: TOut, options?: CapabilityMethodOptions<TKind>): CapabilityMethodSchema<TIn, TOut, TKind> & {
+    readonly providerOptional: true;
+};
 /** Shorthand to define an event schema */
 export declare function event<TData extends z.ZodType>(data: TData): CapabilityEventSchema<TData>;
 /** Type guard: does this cap declare the D14 device-config archetype? */

package/dist/capabilities/index.d.ts

@@ -38,7 +38,7 @@ export { streamSignalsCapability, type IStreamSignalsProvider, type StreamSignal
 export { cameraStreamsCapability, type ICameraStreamsProvider, type PickedCamStream, PickedCamStreamSchema, type PickStreamPreferences, PickStreamPreferencesSchema, type PickStreamRequirements, PickStreamRequirementsSchema, type StreamCodec, StreamCodecSchema, } from './camera-streams.cap.js';
 export { emitsCollectionSelector, extractNestedAddonId, isArrayOutputSchema, isCollectionArrayMethod, isObjectInput, isVoidInput, kebabToCamel, looseSchema, objectInputDeclaresAddonId, objectInputDeclaresRequiredDeviceId, procedureAuthKey, resolveMethodAuth, } from './cap-router-predicates.js';
 export type { CapabilityDefinition, CapabilityEventSchema, CapabilityMethodAuth, CapabilityMethodCaller, CapabilityMethodKind, CapabilityMethodOptions, CapabilityMethodSchema, CapabilityMountHint, CapabilityMountKind, CapabilityStatusItemArray, CapabilityStatusKind, CapabilityStatusSchema, CapCaller, DeviceConfigDerivedFormUi, DeviceConfigSpec, DeviceConfigUiSpec, DeviceConfigWidgetUi, DeviceSettingsContribution, InferDeviceProxyCap, InferEvents, InferName, InferNativeProvider, InferProvider, InferRuntimeState, ProviderKind, RuntimeStateDurability, UiContribution, UiContributionKind, UiContributionRemote, } from './capability-definition.js';
-export { DEFAULT_RUNTIME_STATE_DURABILITY, DEVICE_SETTINGS_CONTRIBUTION_METHODS, DEVICE_STATUS_METHOD, event, expandCapMethods, isDeviceConfigCap, method, resolveCapMount, } from './capability-definition.js';
+export { DEFAULT_RUNTIME_STATE_DURABILITY, DEVICE_SETTINGS_CONTRIBUTION_METHODS, DEVICE_STATUS_METHOD, event, expandCapMethods, isDeviceConfigCap, method, optionalMethod, resolveCapMount, } from './capability-definition.js';
 export { CORE_BLOCK_ADDON_PREFIX, CORE_BLOCKS_ADDON_ID, type CoreBlock, type CoreBlockCompileResult, CoreBlockCompileResultSchema, type CoreBlockInput, CoreBlockInputSchema, type CoreBlockPlacement, CoreBlockPlacementSchema, CoreBlockSchema, type CoreBlockStatus, CoreBlockStatusSchema, coreBlockAddonId, coreBlockIdFromAddonId, coreBlocksCapability, type ICoreBlocksProvider, } from './core-blocks.cap.js';
 export * from './custom-actions.js';
 export type { CustomModelDescriptor, ICustomModelRegistryProvider, } from './custom-model-registry.cap.js';
@@ -116,8 +116,8 @@ export type { IUserPasskeysProvider, PasskeySummary } from './user-passkeys.cap.
 export { PasskeySummarySchema, userPasskeysCapability } from './user-passkeys.cap.js';
 export type { IVectorStoreProvider } from './vector-store.cap.js';
 export { VectorDeclareIndexInputSchema, VectorDeleteByFilterInputSchema, VectorDeleteInputSchema, VectorDeleteResultSchema, type VectorFilter, VectorFilterSchema, VectorGetInputSchema, VectorGetResultSchema, type VectorItem, VectorItemSchema, type VectorMatch, VectorMatchSchema, type VectorMetadata, VectorMetadataSchema, type VectorMetric, VectorMetricSchema, VectorQueryInputSchema, VectorQueryResultSchema, VectorStatsInputSchema, VectorStatsResultSchema, VectorUpsertInputSchema, VectorUpsertResultSchema, vectorStoreCapability, } from './vector-store.cap.js';
-export type { Clip, ClipPlayback, ClipSource, ClipSourceAvailability, ClipStillDisposition, ClipStillRefusalCode, IVideoclipsProvider, } from './videoclips.cap.js';
-export { CLIP_STILL_DISPOSITION_HEADER, CLIP_STILL_REASON_CODE_HEADER, CLIP_STILL_REASON_HEADER, ClipPlaybackSchema, ClipSchema, ClipSourceAvailabilitySchema, ClipSourceSchema, ClipStillDispositionSchema, ClipStillRefusalCodeSchema, MAX_CLIP_EVENT_IDS, MAX_CLIP_LABELS, videoclipsCapability, } from './videoclips.cap.js';
+export type { Clip, ClipBytes, ClipPlayback, ClipSource, ClipSourceAvailability, ClipStillDisposition, ClipStillRefusalCode, ClipWake, IVideoclipsProvider, } from './videoclips.cap.js';
+export { CLIP_STILL_DISPOSITION_HEADER, CLIP_STILL_REASON_CODE_HEADER, CLIP_STILL_REASON_HEADER, ClipBytesSchema, ClipPlaybackSchema, ClipSchema, ClipSourceAvailabilitySchema, ClipSourceSchema, ClipStillDispositionSchema, ClipStillRefusalCodeSchema, ClipWakeSchema, MAX_CLIP_EVENT_IDS, MAX_CLIP_LABELS, VIDEOCLIPS_MAX_READ_BYTES, videoclipsCapability, } from './videoclips.cap.js';
 export type { IViewerUiProvider } from './viewer-ui.cap.js';
 export { viewerUiCapability } from './viewer-ui.cap.js';
 export { type IWebrtcSessionProvider, type WebrtcClientHints, type WebrtcLadderDecision, WebrtcLadderDecisionSchema, type WebrtcSessionDebug, WebrtcSessionDebugSchema, type WebrtcStreamChoice, WebrtcStreamChoiceSchema, type WebrtcStreamTarget, WebrtcStreamTargetSchema, type WebrtcTierFailure, WebrtcTierFailureSchema, webrtcClientHintsSchema, webrtcSessionCapability, } from './webrtc-session.cap.js';
@@ -191,7 +191,7 @@ export { type IPtzProvider, type PtzHomePreset, PtzHomePresetSchema, type PtzHom
 export { type IPtzAutotrackProvider, type PtzAutotrackRuntimeState, PtzAutotrackRuntimeStateSchema, type PtzAutotrackSettings, PtzAutotrackSettingsSchema, type PtzAutotrackStatus, PtzAutotrackStatusSchema, type PtzAutotrackTargetOption, PtzAutotrackTargetOptionSchema, ptzAutotrackCapability, } from './ptz-autotrack.cap.js';
 export { type IRebootProvider, rebootCapability } from './reboot.cap.js';
 export { type IRecordingProvider, type LocateSegmentResult, LocateSegmentResultSchema, RECORDING_TIMELINE_BATCH_MAX, type ReadGopBytesResult, ReadGopBytesResultSchema, type ReadSegmentBytesResult, ReadSegmentBytesResultSchema, type ReadWindowBytesResult, ReadWindowBytesResultSchema, type RecordingAvailability, type RecordingAvailabilityForDevice, RecordingAvailabilityForDeviceSchema, RecordingAvailabilitySchema, type RecordingDays, type RecordingDaysForDevice, RecordingDaysForDeviceSchema, RecordingDaysSchema, type RecordingDeviceUsage, RecordingDeviceUsageSchema, type RecordingLocationUsage, RecordingLocationUsageSchema, type RecordingManifest, RecordingManifestSchema, RecordingRangeSchema, type RecordingRebalanceInput, RecordingRebalanceInputSchema, type RecordingRebalanceMove, RecordingRebalanceMoveSchema, type RecordingRebalancePlan, RecordingRebalancePlanSchema, type RecordingRebalanceSkip, type RecordingRebalanceSkipReason, RecordingRebalanceSkipReasonSchema, RecordingRebalanceSkipSchema, type RecordingStatus, RecordingStatusSchema, type RecordingStorageUsage, RecordingStorageUsageSchema, recordingCapability, } from './recording.cap.js';
-export { EXPORT_DENSE_MAX_RANGES, type ExportBytes, ExportBytesSchema, type ExportDense, type ExportDenseRange, ExportDenseRangeSchema, ExportDenseSchema, type ExportDownload, ExportDownloadSchema, type ExportOptions, ExportOptionsSchema, type ExportRecord, ExportRecordSchema, ExportSpeedSchema, type ExportState, ExportStateSchema, ExportTimelapseSchema, type IRecordingExportProvider, RECORDING_EXPORT_MAX_READ_BYTES, recordingExportCapability, } from './recording-export.cap.js';
+export { clipExportFailure, type ClipExportFailure, ClipExportFailureSchema, clipExportFailureOf, EXPORT_DENSE_MAX_RANGES, type ExportBytes, ExportBytesSchema, type ExportClipSubject, ExportClipSubjectSchema, type ExportDense, type ExportDenseRange, ExportDenseRangeSchema, ExportDenseSchema, type ExportDownload, ExportDownloadSchema, type ExportFootageSubject, ExportFootageSubjectSchema, type ExportOptions, ExportOptionsSchema, type ExportRecord, ExportRecordSchema, ExportSpeedSchema, type ExportState, ExportStateSchema, type ExportSubject, ExportSubjectSchema, exportSubjectOf, ExportTimelapseSchema, type IRecordingExportProvider, RECORDING_EXPORT_MAX_READ_BYTES, recordingExportCapability, resolveCreateExportSubject, resolveExportProfiles, } from './recording-export.cap.js';
 export { type IRecordingSignalProvider, type RecordingSignalRuntimeState, RecordingSignalRuntimeStateSchema, type RecordingSignalStatus, RecordingSignalStatusSchema, recordingSignalCapability, } from './recording-signal.cap.js';
 export { type ISceneMonitorProvider, SCENE_CONDITIONS, SCENE_CONFIRM_DEFAULT_MAX_IMAGE_PX, SCENE_CONFIRM_DEFAULT_TIMEOUT_MS, SCENE_DEFAULT_ANCHOR_THRESHOLD, SCENE_DEFAULT_CHECK_INTERVAL_SEC, SCENE_DEFAULT_OBSERVATION_SPACING_SEC, SCENE_DEFAULT_QUIET_SECONDS, SCENE_DEFAULT_UNCOVERED_POLICY, SCENE_DIVERGED, SCENE_RESET_RECAPTURES, type SceneCheck, SceneCheckSchema, type SceneCondition, SceneConditionSchema, type SceneConfirm, SceneConfirmSchema, type SceneMonitor, SceneMonitorSchema, type SceneMonitorState, SceneMonitorStateSchema, type SceneMonitorStatus, type SceneMonitorStatusForDevice, SceneMonitorStatusForDeviceSchema, SceneMonitorStatusSchema, type SceneReference, SceneReferenceSchema, type SceneUnavailable, SceneUnavailableSchema, type SceneUncoveredPolicy, SceneUncoveredPolicySchema, type SceneVerdict, SceneVerdictSchema, sceneMonitorCapability, } from './scene-monitor.cap.js';
 export { type ZoneRule, type ZoneRuleMode, ZoneRuleModeEnum, ZoneRuleSchema, type ZoneRules, ZoneRulesArraySchema, } from './schemas/zone-rule.js';

package/dist/capabilities/recording-export.cap.d.ts

@@ -113,13 +113,156 @@ export declare const ExportStateSchema: z.ZodEnum<{
     expired: "expired";
 }>;
 export type ExportState = z.infer<typeof ExportStateSchema>;
-/** 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.
+ */
+export declare const ExportFootageSubjectSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"footage">;
+    deviceId: z.ZodNumber;
+    profiles: z.ZodArray<z.ZodString>;
+    fromMs: z.ZodNumber;
+    toMs: z.ZodNumber;
+}, z.core.$strip>;
+export type ExportFootageSubject = z.infer<typeof ExportFootageSubjectSchema>;
+/**
+ * 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.
+ */
+export declare const ExportClipSubjectSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"clip">;
+    deviceId: z.ZodNumber;
+    provider: z.ZodString;
+    source: z.ZodString;
+    sourceLabel: z.ZodString;
+    clipId: z.ZodString;
+    catalogWindow: z.ZodObject<{
+        sinceMs: z.ZodNumber;
+        untilMs: z.ZodNumber;
+    }, z.core.$strip>;
+    profile: z.ZodEnum<{
+        high: "high";
+        mid: "mid";
+        low: "low";
+    }>;
+    wake: z.ZodOptional<z.ZodEnum<{
+        authorised: "authorised";
+    }>>;
+}, z.core.$strip>;
+export type ExportClipSubject = z.infer<typeof ExportClipSubjectSchema>;
+/**
+ * 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.
+ */
+export declare const ExportSubjectSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"footage">;
+    deviceId: z.ZodNumber;
+    profiles: z.ZodArray<z.ZodString>;
+    fromMs: z.ZodNumber;
+    toMs: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"clip">;
+    deviceId: z.ZodNumber;
+    provider: z.ZodString;
+    source: z.ZodString;
+    sourceLabel: z.ZodString;
+    clipId: z.ZodString;
+    catalogWindow: z.ZodObject<{
+        sinceMs: z.ZodNumber;
+        untilMs: z.ZodNumber;
+    }, z.core.$strip>;
+    profile: z.ZodEnum<{
+        high: "high";
+        mid: "mid";
+        low: "low";
+    }>;
+    wake: z.ZodOptional<z.ZodEnum<{
+        authorised: "authorised";
+    }>>;
+}, z.core.$strip>], "kind">;
+export type ExportSubject = z.infer<typeof ExportSubjectSchema>;
+/**
+ * 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).
+ */
 export declare const ExportRecordSchema: z.ZodObject<{
     id: z.ZodString;
     deviceId: z.ZodNumber;
     profile: z.ZodString;
     fromMs: z.ZodNumber;
     toMs: z.ZodNumber;
+    subject: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"footage">;
+        deviceId: z.ZodNumber;
+        profiles: z.ZodArray<z.ZodString>;
+        fromMs: z.ZodNumber;
+        toMs: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"clip">;
+        deviceId: z.ZodNumber;
+        provider: z.ZodString;
+        source: z.ZodString;
+        sourceLabel: z.ZodString;
+        clipId: z.ZodString;
+        catalogWindow: z.ZodObject<{
+            sinceMs: z.ZodNumber;
+            untilMs: z.ZodNumber;
+        }, z.core.$strip>;
+        profile: z.ZodEnum<{
+            high: "high";
+            mid: "mid";
+            low: "low";
+        }>;
+        wake: z.ZodOptional<z.ZodEnum<{
+            authorised: "authorised";
+        }>>;
+    }, z.core.$strip>], "kind">>;
     options: z.ZodObject<{
         speed: z.ZodOptional<z.ZodNumber>;
         timelapse: z.ZodOptional<z.ZodObject<{
@@ -157,6 +300,43 @@ export declare const ExportRecordSchema: z.ZodObject<{
     error: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
 export type ExportRecord = z.infer<typeof ExportRecordSchema>;
+/**
+ * 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.
+ */
+export declare const ClipExportFailureSchema: z.ZodEnum<{
+    sleeping: "sleeping";
+    "camera-refused": "camera-refused";
+    "catalog-miss": "catalog-miss";
+    "catalog-unreachable": "catalog-unreachable";
+    "no-file-for-window": "no-file-for-window";
+    "clip-in-progress": "clip-in-progress";
+    "unsupported-option": "unsupported-option";
+    "fetch-failed": "fetch-failed";
+    "too-large-to-transfer": "too-large-to-transfer";
+    "wake-expired": "wake-expired";
+}>;
+export type ClipExportFailure = z.infer<typeof ClipExportFailureSchema>;
+/** `<token>: <prose>` — the ONE composition of a clip export's failure string. */
+export declare function clipExportFailure(code: ClipExportFailure, detail: string): string;
+/**
+ * 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).
+ */
+export declare function clipExportFailureOf(error: string | null): ClipExportFailure | null;
 /** Candidate download URLs (LAN first, then operator extra hosts). */
 export declare const ExportDownloadSchema: z.ZodObject<{
     url: z.ZodString;
@@ -195,28 +375,68 @@ export declare const ExportBytesSchema: z.ZodObject<{
     bytes: z.ZodNumber;
 }, z.core.$strip>;
 export type ExportBytes = z.infer<typeof ExportBytesSchema>;
+/** Canonical `profiles[]`, falling back to the legacy singular `profile`. */
+export declare function resolveExportProfiles(input: {
+    readonly profile?: string;
+    readonly profiles?: readonly string[];
+}): string[];
 /**
- * Rewrite a legacy `{ profile }` into `{ profiles: [profile] }` so one parse
- * path serves both the multi-stream picker and the timelapse scheduler.
+ * `createExport` input — ONE object carrying an optional {@link ExportSubject},
+ * never a union of two inputs.
  *
- * Kept as a named function (not `z.preprocess` wrapping the method input)
- * because generated routers call `.input.loose()` — a ZodObject method that a
- * preprocess/pipe schema does not have. The object schema still *accepts* the
- * singular field; this helper is the explicit rewrite the tests pin.
- */
-export declare function preprocessCreateExportInput(raw: unknown): unknown;
-/**
- * `createExport` input. `profiles` is the canonical field (min 1). A legacy
- * singular `profile` is still accepted so existing callers do not break.
+ * 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.
  *
- * Must remain a ZodObject (`.loose()` for out-of-band `nodeId`).
+ * **`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.
  */
 export declare const CreateExportInputSchema: z.ZodObject<{
     deviceId: z.ZodNumber;
     profile: z.ZodOptional<z.ZodString>;
     profiles: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    fromMs: z.ZodNumber;
-    toMs: z.ZodNumber;
+    fromMs: z.ZodOptional<z.ZodNumber>;
+    toMs: z.ZodOptional<z.ZodNumber>;
+    subject: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"footage">;
+        deviceId: z.ZodNumber;
+        profiles: z.ZodArray<z.ZodString>;
+        fromMs: z.ZodNumber;
+        toMs: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"clip">;
+        deviceId: z.ZodNumber;
+        provider: z.ZodString;
+        source: z.ZodString;
+        sourceLabel: z.ZodString;
+        clipId: z.ZodString;
+        catalogWindow: z.ZodObject<{
+            sinceMs: z.ZodNumber;
+            untilMs: z.ZodNumber;
+        }, z.core.$strip>;
+        profile: z.ZodEnum<{
+            high: "high";
+            mid: "mid";
+            low: "low";
+        }>;
+        wake: z.ZodOptional<z.ZodEnum<{
+            authorised: "authorised";
+        }>>;
+    }, z.core.$strip>], "kind">>;
     options: z.ZodObject<{
         speed: z.ZodOptional<z.ZodNumber>;
         timelapse: z.ZodOptional<z.ZodObject<{
@@ -238,20 +458,87 @@ export declare const CreateExportInputSchema: z.ZodObject<{
     }, z.core.$strip>;
 }, z.core.$strip>;
 export type CreateExportInput = z.infer<typeof CreateExportInputSchema>;
+/**
+ * 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.
+ */
+export declare function resolveCreateExportSubject(input: CreateExportInput): ExportSubject;
+/**
+ * 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.
+ */
+export declare function exportSubjectOf(rec: ExportRecord): ExportSubject;
 export declare const recordingExportCapability: {
     readonly name: "recording-export";
     readonly scope: "system";
     readonly mode: "singleton";
     readonly 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.
+         */
         readonly createExport: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
             deviceId: z.ZodNumber;
             profile: z.ZodOptional<z.ZodString>;
             profiles: z.ZodOptional<z.ZodArray<z.ZodString>>;
-            fromMs: z.ZodNumber;
-            toMs: z.ZodNumber;
+            fromMs: z.ZodOptional<z.ZodNumber>;
+            toMs: z.ZodOptional<z.ZodNumber>;
+            subject: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"footage">;
+                deviceId: z.ZodNumber;
+                profiles: z.ZodArray<z.ZodString>;
+                fromMs: z.ZodNumber;
+                toMs: z.ZodNumber;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"clip">;
+                deviceId: z.ZodNumber;
+                provider: z.ZodString;
+                source: z.ZodString;
+                sourceLabel: z.ZodString;
+                clipId: z.ZodString;
+                catalogWindow: z.ZodObject<{
+                    sinceMs: z.ZodNumber;
+                    untilMs: z.ZodNumber;
+                }, z.core.$strip>;
+                profile: z.ZodEnum<{
+                    high: "high";
+                    mid: "mid";
+                    low: "low";
+                }>;
+                wake: z.ZodOptional<z.ZodEnum<{
+                    authorised: "authorised";
+                }>>;
+            }, z.core.$strip>], "kind">>;
             options: z.ZodObject<{
                 speed: z.ZodOptional<z.ZodNumber>;
                 timelapse: z.ZodOptional<z.ZodObject<{
@@ -277,6 +564,32 @@ export declare const recordingExportCapability: {
             profile: z.ZodString;
             fromMs: z.ZodNumber;
             toMs: z.ZodNumber;
+            subject: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"footage">;
+                deviceId: z.ZodNumber;
+                profiles: z.ZodArray<z.ZodString>;
+                fromMs: z.ZodNumber;
+                toMs: z.ZodNumber;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"clip">;
+                deviceId: z.ZodNumber;
+                provider: z.ZodString;
+                source: z.ZodString;
+                sourceLabel: z.ZodString;
+                clipId: z.ZodString;
+                catalogWindow: z.ZodObject<{
+                    sinceMs: z.ZodNumber;
+                    untilMs: z.ZodNumber;
+                }, z.core.$strip>;
+                profile: z.ZodEnum<{
+                    high: "high";
+                    mid: "mid";
+                    low: "low";
+                }>;
+                wake: z.ZodOptional<z.ZodEnum<{
+                    authorised: "authorised";
+                }>>;
+            }, z.core.$strip>], "kind">>;
             options: z.ZodObject<{
                 speed: z.ZodOptional<z.ZodNumber>;
                 timelapse: z.ZodOptional<z.ZodObject<{
@@ -322,6 +635,32 @@ export declare const recordingExportCapability: {
             profile: z.ZodString;
             fromMs: z.ZodNumber;
             toMs: z.ZodNumber;
+            subject: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"footage">;
+                deviceId: z.ZodNumber;
+                profiles: z.ZodArray<z.ZodString>;
+                fromMs: z.ZodNumber;
+                toMs: z.ZodNumber;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"clip">;
+                deviceId: z.ZodNumber;
+                provider: z.ZodString;
+                source: z.ZodString;
+                sourceLabel: z.ZodString;
+                clipId: z.ZodString;
+                catalogWindow: z.ZodObject<{
+                    sinceMs: z.ZodNumber;
+                    untilMs: z.ZodNumber;
+                }, z.core.$strip>;
+                profile: z.ZodEnum<{
+                    high: "high";
+                    mid: "mid";
+                    low: "low";
+                }>;
+                wake: z.ZodOptional<z.ZodEnum<{
+                    authorised: "authorised";
+                }>>;
+            }, z.core.$strip>], "kind">>;
             options: z.ZodObject<{
                 speed: z.ZodOptional<z.ZodNumber>;
                 timelapse: z.ZodOptional<z.ZodObject<{
@@ -366,6 +705,32 @@ export declare const recordingExportCapability: {
             profile: z.ZodString;
             fromMs: z.ZodNumber;
             toMs: z.ZodNumber;
+            subject: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"footage">;
+                deviceId: z.ZodNumber;
+                profiles: z.ZodArray<z.ZodString>;
+                fromMs: z.ZodNumber;
+                toMs: z.ZodNumber;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"clip">;
+                deviceId: z.ZodNumber;
+                provider: z.ZodString;
+                source: z.ZodString;
+                sourceLabel: z.ZodString;
+                clipId: z.ZodString;
+                catalogWindow: z.ZodObject<{
+                    sinceMs: z.ZodNumber;
+                    untilMs: z.ZodNumber;
+                }, z.core.$strip>;
+                profile: z.ZodEnum<{
+                    high: "high";
+                    mid: "mid";
+                    low: "low";
+                }>;
+                wake: z.ZodOptional<z.ZodEnum<{
+                    authorised: "authorised";
+                }>>;
+            }, z.core.$strip>], "kind">>;
             options: z.ZodObject<{
                 speed: z.ZodOptional<z.ZodNumber>;
                 timelapse: z.ZodOptional<z.ZodObject<{
@@ -411,6 +776,32 @@ export declare const recordingExportCapability: {
             profile: z.ZodString;
             fromMs: z.ZodNumber;
             toMs: z.ZodNumber;
+            subject: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"footage">;
+                deviceId: z.ZodNumber;
+                profiles: z.ZodArray<z.ZodString>;
+                fromMs: z.ZodNumber;
+                toMs: z.ZodNumber;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"clip">;
+                deviceId: z.ZodNumber;
+                provider: z.ZodString;
+                source: z.ZodString;
+                sourceLabel: z.ZodString;
+                clipId: z.ZodString;
+                catalogWindow: z.ZodObject<{
+                    sinceMs: z.ZodNumber;
+                    untilMs: z.ZodNumber;
+                }, z.core.$strip>;
+                profile: z.ZodEnum<{
+                    high: "high";
+                    mid: "mid";
+                    low: "low";
+                }>;
+                wake: z.ZodOptional<z.ZodEnum<{
+                    authorised: "authorised";
+                }>>;
+            }, z.core.$strip>], "kind">>;
             options: z.ZodObject<{
                 speed: z.ZodOptional<z.ZodNumber>;
                 timelapse: z.ZodOptional<z.ZodObject<{
@@ -456,6 +847,32 @@ export declare const recordingExportCapability: {
             profile: z.ZodString;
             fromMs: z.ZodNumber;
             toMs: z.ZodNumber;
+            subject: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"footage">;
+                deviceId: z.ZodNumber;
+                profiles: z.ZodArray<z.ZodString>;
+                fromMs: z.ZodNumber;
+                toMs: z.ZodNumber;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"clip">;
+                deviceId: z.ZodNumber;
+                provider: z.ZodString;
+                source: z.ZodString;
+                sourceLabel: z.ZodString;
+                clipId: z.ZodString;
+                catalogWindow: z.ZodObject<{
+                    sinceMs: z.ZodNumber;
+                    untilMs: z.ZodNumber;
+                }, z.core.$strip>;
+                profile: z.ZodEnum<{
+                    high: "high";
+                    mid: "mid";
+                    low: "low";
+                }>;
+                wake: z.ZodOptional<z.ZodEnum<{
+                    authorised: "authorised";
+                }>>;
+            }, z.core.$strip>], "kind">>;
             options: z.ZodObject<{
                 speed: z.ZodOptional<z.ZodNumber>;
                 timelapse: z.ZodOptional<z.ZodObject<{