@camstack/types 1.2.245 → 1.2.247

package/dist/capabilities/reserved-collection-sources.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Source ids of a device COLLECTION that exactly one addon may mint (D625).
+ *
+ * A collection cap's picker treats its rows as peers, and that is right almost
+ * everywhere. It is wrong for exactly one thing: a DEFAULT that must be
+ * impossible to express otherwise.
+ *
+ * `recording`'s default is ours, always (the operator's ruling, 2026-09-24).
+ * The way that is made structural rather than a sort order is a RESERVED id:
+ * the absence of an operator choice MEANS `camstack`, so a surface never needs
+ * a "first row" fallback and there is nowhere to put one. `clip-sources.ts`
+ * ends with `?? sources[0]`, and `videoclips.listSources` on 592 answers the
+ * ONBOARD row first — for clips that fallback was argued for, for a timeline it
+ * would silently swap an 85 362 s bar for a 21 388 s one.
+ *
+ * A reserved id is only worth anything if nothing else can spell it, so it is
+ * enforced twice and neither is a paragraph:
+ *
+ *  1. `device-collection-dispatch.ts` DROPS a `listSources` row carrying a
+ *     reserved id from any addon but its owner, naming the impostor in a log
+ *     line with `tags: { deviceId }`. It drops the row rather than throwing:
+ *     one lying provider must not empty a camera's picker.
+ *  2. `scripts/check-reserved-collection-sources.ts` fails CI on any package
+ *     but the owner's that spells the id at all. It reads THIS table, so a new
+ *     reservation is guarded the moment it is added here.
+ */
+/** One reservation: `sourceId` on `capName` may be served only by `addonId`. */
+export interface ReservedCollectionSource {
+    readonly capName: string;
+    readonly sourceId: string;
+    readonly addonId: string;
+}
+/**
+ * Every reserved (cap, source) pair in the system.
+ *
+ * KEEP THE LITERALS INLINE. The CI guard parses this array textually — it
+ * cannot execute TypeScript — so an entry built from an imported constant
+ * would be invisible to it, and a guard that reads the wrong surface is worse
+ * than none.
+ */
+export declare const RESERVED_COLLECTION_SOURCES: readonly ReservedCollectionSource[];
+/**
+ * The addon allowed to serve `sourceId` on `capName`, or `null` when the id is
+ * not reserved at all (which is the common case — most sources are peers).
+ */
+export declare function reservedSourceOwner(capName: string, sourceId: string): string | null;

package/dist/capabilities/videoclips.cap.d.ts

@@ -67,6 +67,7 @@ export declare const ClipStillRefusalCodeSchema: z.ZodEnum<{
     "no-keyframe": "no-keyframe";
     "queue-full": "queue-full";
     "camera-backoff": "camera-backoff";
+    "decode-failed": "decode-failed";
     "no-catalog-row": "no-catalog-row";
     "unknown-device": "unknown-device";
     "uid-missing": "uid-missing";
@@ -249,11 +250,36 @@ export type ClipWake = z.infer<typeof ClipWakeSchema>;
  * 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.
+ * **Superseded as the way a clip export gets its bytes** (D613). The bound is
+ * a property of the ENVELOPE, not of clips, so the cure was a transport with
+ * no envelope: {@link videoclipsCapability.methods.offerClipBytes} hands back
+ * a one-shot `peerBytes` ticket and the consumer streams it straight to disk,
+ * holding nothing. This method stays for a consumer that genuinely wants the
+ * bytes in hand, and for a provider not yet redeployed — with this bound,
+ * which for an inline read is not going to move.
  */
 export declare const VIDEOCLIPS_MAX_READ_BYTES: number;
+/**
+ * Hard ceiling on ONE {@link videoclipsCapability.methods.offerClipBytes}
+ * transfer — ten times {@link VIDEOCLIPS_MAX_READ_BYTES}, and the reasoning is
+ * not "ten times more comfortable".
+ *
+ * The inline bound is set by what is HELD: a base64 envelope is the payload at
+ * ~1.33× in the provider AND the same again in the caller, so 50 MiB of clip
+ * is ~133 MiB of heap across two processes. Over `peerBytes` the consumer
+ * holds one socket chunk at a time and writes straight through to the export
+ * file, so its contribution is flat whatever the clip weighs. What is left is
+ * the PRODUCER's own copy, and that is a property of how each provider makes a
+ * clip rather than of this transport: Hikvision's fetch writes to a scratch
+ * FILE and offers it (nothing is held), Reolink's cmd-5 transfer is collected
+ * in memory and offered from there (one copy, the one it already had).
+ *
+ * So this number bounds the worst provider, not the transport, and it is named
+ * separately so that lifting it is a statement about a provider rather than
+ * about clips. Above it the provider REFUSES with the size in the message and
+ * never truncates: half a video is worse than an honest refusal.
+ */
+export declare const VIDEOCLIPS_MAX_OFFER_BYTES: number;
 /**
  * A clip's finished bytes, inline — the twin of `recordingExport.readExportBytes`.
  *
@@ -273,6 +299,34 @@ export declare const ClipBytesSchema: z.ZodObject<{
     durationMs: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export type ClipBytes = z.infer<typeof ClipBytesSchema>;
+/**
+ * Where a clip's finished bytes can be TAKEN (D613) — the answer to
+ * {@link videoclipsCapability.methods.offerClipBytes}.
+ *
+ * Everything {@link ClipBytesSchema} carries except the bytes themselves, plus
+ * the one-shot ticket that leads to them. The metadata is answered BEFORE the
+ * transfer on purpose: a consumer learns which twin it got, what to call the
+ * file and how long the clip runs without having to read a byte, so a decision
+ * it would make on that metadata (a wrong twin, an implausible duration) costs
+ * no transfer at all.
+ */
+export declare const ClipBytesOfferSchema: z.ZodObject<{
+    ticket: z.ZodObject<{
+        url: z.ZodString;
+        hostNodeId: z.ZodString;
+        expiresAtMs: z.ZodNumber;
+        declaredBytes: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>;
+    contentType: z.ZodString;
+    name: z.ZodString;
+    served: z.ZodEnum<{
+        high: "high";
+        mid: "mid";
+        low: "low";
+    }>;
+    durationMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type ClipBytesOffer = z.infer<typeof ClipBytesOfferSchema>;
 /**
  * Where a clip's STREAM can be dialled (D597) — the answer to
  * {@link videoclipsCapability.methods.dialClipStream}.
@@ -338,6 +392,125 @@ export declare const ClipStreamDialSchema: z.ZodObject<{
     }>>;
 }, z.core.$strip>;
 export type ClipStreamDial = z.infer<typeof ClipStreamDialSchema>;
+/**
+ * The playback rates the broker can pace over media it HOLDS, ascending,
+ * always with `1` — and the WIDEST ladder there is. It is the domain the
+ * broker's `clampPlaybackRate` is derived from, at both ends.
+ *
+ * These are the BROKER's: it re-paces frames it has already demuxed — the
+ * `MonotonicClock` divides source elapsed time by the factor and the pacer
+ * pushes that much faster. `1.5` is in it because a re-pacer has no reason to
+ * refuse it.
+ *
+ * **`8` is here since D621, and it is the pacer's, not a camera's.** D620
+ * measured the thing that was assumed for a year and was never true: a
+ * Reolink `<playSpeed>` does not time-compress anything. At 1, 2, 4 and 8 the
+ * transfer is byte-identical — same 947 472 bytes, same 594 access units,
+ * same 39.855 s presentation span, same 624 AAC frames — and only the wall
+ * clock moves. It buys SUPPLY, never speed. So there was never a second
+ * mechanism to wire for 8×: there is one, this one, and what it needs is
+ * media in hand and a clamp that does not move the number.
+ *
+ * **`16` is deliberately NOT here, and will not join by widening this array.**
+ * The camera's `playSpeed 16` is not a rate at all but an I-frame-only MODE —
+ * measured on 592: 10 access units for a whole 36.3 s sub clip, 20 for the
+ * main twin at a 2 025 ms median spacing, and no audio track. That is
+ * different CONTENT, a stream of its own, and the honest broker-side twin of
+ * it would be a pacer that DROPS whole GOPs rather than one that pushes 16×
+ * the bitrate at a live WebRTC track. Neither exists. A `16` in this array
+ * today would be a rate accepted and delivered at 8 — D612's defect, which
+ * this list exists to end, one number further along.
+ *
+ * Every entry must survive the broker's `clampPlaybackRate` unchanged. Since
+ * D621 that is structural rather than a discipline: the clamp reads this
+ * array's own ends. What still has to be proved behaviourally — and is, in
+ * the broker's `clip-stream-feeder.spec` — is that the PACER really empties a
+ * clip `rate` times faster, because a clamp agreeing with a ladder is a
+ * constant compared against itself.
+ *
+ * Narrower ladders exist for transports whose SUPPLY is bounded; they are
+ * subsets of this one ({@link CLIP_STREAM_SOURCE_RATES},
+ * {@link CLIP_REALTIME_SOURCE_RATES}).
+ */
+export declare const CLIP_BROKER_PACED_RATES: readonly number[];
+/**
+ * The rates a provider-STREAMED clip can be delivered at — a subset of
+ * {@link CLIP_BROKER_PACED_RATES}, and frozen below it on purpose (D621).
+ *
+ * A `stream` clip's media does not exist yet: it arrives on a socket from the
+ * camera while the pacer consumes it. The pacer takes `rate` seconds of media
+ * per second of wall clock, so the ceiling is whatever the SOURCE supplies,
+ * and that is a measurement per vendor rather than a preference.
+ *
+ * Reolink, the one provider on this envelope, was measured on 592
+ * (2026-09-23, D620): with the `<ReplaySeek>` that 0.11.1 sends before every
+ * replay, a sub clip arrives at **1.2×** and a main twin at **1.37×**. The
+ * ladder below is therefore ALREADY beyond this transport above 1 — the D612
+ * defect returned through a door nobody opened — and D620 fixed the repair
+ * order: the supply first, the ladder after. So this array does not move with
+ * the broker's, and it does not gain `8`; what it gains, when the library
+ * forwards a `<playSpeed>` large enough to feed the rate being paced over it,
+ * is the right to be widened on a measurement rather than shortened on one.
+ */
+export declare const CLIP_STREAM_SOURCE_RATES: readonly number[];
+/**
+ * The rates a REALTIME-BOUND stream can be delivered at.
+ *
+ * **Measured, and it is the whole reason this second ladder exists.** A
+ * Hikvision RTSP replay is not a fast fetch: it delivers the recording at the
+ * speed it was recorded. On 1436, 2026-09-23, one stream carried 176 access
+ * units in 14 274 ms of wall clock at a measured 12.5 fps — 14.08 s of media
+ * in 14.27 s, **1.01× realtime** — and a whole 18 s clip took 22.3 s to fetch
+ * end to end. Reolink's cmd-5 transfer, which {@link CLIP_BROKER_PACED_RATES}
+ * was written for, lands the same bytes at 49–62× and therefore has the entire
+ * clip in hand within the first second.
+ *
+ * The broker's pacer consumes `rate` seconds of media per second of wall
+ * clock while the socket supplies one. So at any rate above 1 the buffer
+ * drains at `(rate − 1)×` and a stream that is only seconds old runs dry
+ * almost at once — the viewer stops, the queue empties, and the provider's
+ * own drain gate eventually reports `peer-stalled`. Nothing about that is a
+ * bug to be fixed with a bigger buffer: there is no buffer, because the bytes
+ * do not exist yet.
+ *
+ * So the honest answer is the DECLARATION (D612's own rule, applied to the
+ * case it did not yet have): a rate this transport cannot deliver is never
+ * offered. Below 1 is free — a slower pacer only lets the buffer grow.
+ *
+ * When a clip is served from a FILE the constraint is gone with the transport,
+ * which is why `file` keeps the full ladder.
+ */
+export declare const CLIP_REALTIME_SOURCE_RATES: readonly number[];
+/**
+ * What a surface may DRAW for this provider's clips — the answer to
+ * {@link videoclipsCapability.methods.getPlaybackOptions} (D612).
+ *
+ * The envelope is a PROVIDER fact, not a clip fact, and that is measured, not
+ * assumed: the broker's `chooseClipPath` reads exactly two inputs — whether
+ * `dialClipStream` and `readClipBytes` are wired — and both are constants of
+ * the broker's own closure over the provider's methods. The `profile` it is
+ * handed is explicitly not read. So every clip of a provider is served the
+ * same way, and a per-clip channel carried a value that could not vary. The
+ * per-clip `clipTransport` server message was removed for exactly that reason.
+ *
+ * Queried per camera, before a clip is picked, so a control is rendered or
+ * DISABLED rather than offered and refused at play time (D62: a disabled
+ * control reads as unavailable, one that undoes the gesture reads as broken).
+ */
+export declare const ClipPlaybackOptionsSchema: z.ZodObject<{
+    transport: z.ZodEnum<{
+        file: "file";
+        stream: "stream";
+    }>;
+    seek: z.ZodEnum<{
+        forward: "forward";
+        free: "free";
+    }>;
+    stepBack: z.ZodBoolean;
+    scrub: z.ZodBoolean;
+    rates: z.ZodReadonly<z.ZodArray<z.ZodNumber>>;
+}, z.core.$strip>;
+export type ClipPlaybackOptions = z.infer<typeof ClipPlaybackOptionsSchema>;
 export declare const ClipSourceAvailabilitySchema: z.ZodObject<{
     state: z.ZodEnum<{
         ok: "ok";
@@ -533,14 +706,18 @@ export declare const videoclipsCapability: {
          *
          * `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.
+         * viewer session satisfy. It is the wrong answer for another ADDON: the
+         * hub's proxy in front of that plane takes only a user credential, which
+         * an addon does not hold, so a recorder that wants a camera's clip cannot
+         * fetch that URL. This method is the shape that answer forced — the same
+         * one (and the same bound) as `recordingExport.readExportBytes`.
+         *
+         * **It is no longer the only seam.** Until D613 there was no addon→addon
+         * byte transport at all; there is now
+         * ({@link offerClipBytes}, over `ctx.peerBytes`), it holds nothing on
+         * either side, and it is what a clip EXPORT uses. This method remains for
+         * a consumer that genuinely wants the bytes in hand, and as the named
+         * fallback for a provider not yet redeployed.
          *
          * Routing needs no `provider` pin: the id is source-prefixed and
          * self-contained, so `device-collection-dispatch.ts` rule 3 hands the call
@@ -588,6 +765,72 @@ export declare const videoclipsCapability: {
         }, z.core.$strip>, "query"> & {
             readonly providerOptional: true;
         };
+        /**
+         * Where this clip's finished bytes can be TAKEN — the by-handle read a
+         * clip EXPORT pulls, over the addon→addon byte transport (D613).
+         *
+         * This is {@link readClipBytes} with the envelope removed. Same gates,
+         * same vocabulary, same completion rules, same `served` contract — the
+         * only difference is that the bytes travel over a one-shot loopback
+         * socket instead of inside a base64 field, so neither side holds the
+         * payload whole and the 50 MiB refusal on a long `high` twin stops
+         * existing. The bound that remains is
+         * {@link VIDEOCLIPS_MAX_OFFER_BYTES}, and it bounds the PRODUCER's own
+         * copy rather than the transport.
+         *
+         * **The ticket is loopback and same-host.** A provider on an agent mints a
+         * URL that means nothing on the hub, and `ctx.peerBytes.open` refuses it
+         * `cross-node` by name rather than dialling whatever else holds that port
+         * here. A consumer that can be on the other side of a node boundary from
+         * its provider must be able to read that refusal and say so; it must not
+         * treat it as "no bytes".
+         *
+         * **A ticket is a one-shot bearer credential with a seconds-long life.**
+         * Take it immediately, never persist it, never log its `url`. An untaken
+         * ticket costs the provider one map entry until its TTL, and outstanding
+         * tickets are bounded — which is also what makes a per-frame misuse of
+         * this method refuse by name rather than work slowly (D9/D18: this is a
+         * by-handle fetch of finished media, not a frame pipe).
+         *
+         * Optional on the provider for the same reason `readClipBytes` is: a
+         * source with no camera socket behind it has no bytes. A provider that
+         * predates this method answers `NOT_IMPLEMENTED`, and a consumer may fall
+         * back to `readClipBytes` — but it says so in the log, with the deploy
+         * hint, because that fallback re-imposes the 50 MiB refusal and an
+         * operator who sees `too-large-to-transfer` after this shipped is looking
+         * at a stale addon, not at a clip that cannot be exported.
+         */
+        readonly offerClipBytes: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+            clipId: z.ZodString;
+            provider: z.ZodString;
+            profile: z.ZodOptional<z.ZodEnum<{
+                high: "high";
+                mid: "mid";
+                low: "low";
+            }>>;
+            maxBytes: z.ZodOptional<z.ZodNumber>;
+            wake: z.ZodOptional<z.ZodEnum<{
+                authorised: "authorised";
+            }>>;
+        }, z.core.$strip>, z.ZodObject<{
+            ticket: z.ZodObject<{
+                url: z.ZodString;
+                hostNodeId: z.ZodString;
+                expiresAtMs: z.ZodNumber;
+                declaredBytes: z.ZodNullable<z.ZodNumber>;
+            }, z.core.$strip>;
+            contentType: z.ZodString;
+            name: z.ZodString;
+            served: z.ZodEnum<{
+                high: "high";
+                mid: "mid";
+                low: "low";
+            }>;
+            durationMs: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>, "query"> & {
+            readonly providerOptional: true;
+        };
         /**
          * Where this clip's STREAM can be dialled (D597) — the forward-only
          * fMP4 the provider writes from the first muxed byte, for the broker to
@@ -639,6 +882,92 @@ export declare const videoclipsCapability: {
         }, z.core.$strip>, "query"> & {
             readonly providerOptional: true;
         };
+        /**
+         * What a surface may DRAW for this provider's clips: the rates it can be
+         * played at, whether scrub is served, how far a position may be moved,
+         * and whether a backward frame-step means anything (D612).
+         *
+         * **The only authority.** The per-clip `clipTransport` server message
+         * that used to carry the same answer was removed: the broker's transport
+         * choice reads nothing that varies per clip, so the clip level had no
+         * information the provider does not already have, and two channels that
+         * can disagree are worse than one (D62).
+         *
+         * Asked per camera and per provider, so it must stay CHEAP — it is a
+         * statement about wiring, answered from a constant, never a call to the
+         * camera. A provider answers with one of {@link CLIP_PLAYBACK_OPTIONS}
+         * and never composes an envelope of its own.
+         *
+         * Optional, and absence is load-bearing: a provider that has not answered
+         * has not restricted anything, and a viewer reads it as the freedom it
+         * always had. See D612 on the rollout order that absence implies.
+         */
+        readonly getPlaybackOptions: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+            provider: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            transport: z.ZodEnum<{
+                file: "file";
+                stream: "stream";
+            }>;
+            seek: z.ZodEnum<{
+                forward: "forward";
+                free: "free";
+            }>;
+            stepBack: z.ZodBoolean;
+            scrub: z.ZodBoolean;
+            rates: z.ZodReadonly<z.ZodArray<z.ZodNumber>>;
+        }, z.core.$strip>, "query"> & {
+            readonly providerOptional: true;
+        };
     };
 };
 export type IVideoclipsProvider = InferProvider<typeof videoclipsCapability>;
+/**
+ * NOTE ON PLACEMENT: this block lives AFTER the capability definition on
+ * purpose. `scripts/lib/parse-cap.ts` finds a cap by the FIRST
+ * `export const <X> = {` in the file, so an object literal declared above
+ * `videoclipsCapability` is silently taken for the capability itself and
+ * codegen emits a `DeviceProxy` entry that does not type-check. Found the
+ * hard way, 2026-09-23.
+ */
+/**
+ * The two envelopes, spelled ONCE.
+ *
+ * A provider answers with the entry for the transport its own wiring buys —
+ * `stream` if it implements `dialClipStream`, `file` if it implements only
+ * `readClipBytes` — and never composes one of its own. One table is what
+ * makes "the provider may not promise what no clip can be given" structural
+ * instead of a discipline: there is nothing else to promise.
+ */
+export declare const CLIP_PLAYBACK_OPTIONS: {
+    readonly stream: {
+        readonly transport: "stream";
+        readonly seek: "forward";
+        readonly stepBack: false;
+        readonly scrub: false;
+        readonly rates: readonly number[];
+    };
+    /**
+     * A `stream` whose SOURCE runs at realtime — a Hikvision RTSP replay.
+     *
+     * Same verbs as `stream`, a shorter rate ladder, and the difference is a
+     * measurement rather than a preference: see
+     * {@link CLIP_REALTIME_SOURCE_RATES}. A third entry rather than a parameter,
+     * because a provider must still be able to do nothing but NAME one of these.
+     */
+    readonly realtimeStream: {
+        readonly transport: "stream";
+        readonly seek: "forward";
+        readonly stepBack: false;
+        readonly scrub: false;
+        readonly rates: readonly number[];
+    };
+    readonly file: {
+        readonly transport: "file";
+        readonly seek: "free";
+        readonly stepBack: true;
+        readonly scrub: true;
+        readonly rates: readonly number[];
+    };
+};