@camstack/addon-provider-reolink 1.2.162 → 1.2.163

package/dist/addon.js

@@ -5391,7 +5391,7 @@ var ZodIssueCode = {
 var ZodFirstPartyTypeKind;
 ZodFirstPartyTypeKind || (ZodFirstPartyTypeKind = {});
 //#endregion
-//#region ../types/dist/sleep-i3eUVc-d.mjs
+//#region ../types/dist/sleep-COWaSCAi.mjs
 /**
 * The audio chunk plane's byte format, and the ONE expansion from a coded
 * window to float samples (D455).
@@ -7607,6 +7607,24 @@ object({
 		unreachable: number()
 	})
 });
+/** The wire shape of {@link PeerBytesTicket} — see the type for what it is. */
+var PeerBytesTicketSchema = object({
+	/** `http://127.0.0.1:<port>/<token>`. One `GET` takes it. */
+	url: string().min(1),
+	/**
+	* The HOST node this URL means something on — the hub or a named agent,
+	* never a runner. {@link AddonPeerBytes.open} compares it to its own and
+	* refuses `cross-node` by name when they differ, without dialling.
+	*/
+	hostNodeId: string().min(1),
+	expiresAtMs: number().int().nonnegative(),
+	/**
+	* What the producer DECLARED the body to be, when it knows — `null` when it
+	* does not. Never `0` for unknown (D393): a consumer sizing a bound off this
+	* must be able to tell "the producer did not say" from "the body is empty".
+	*/
+	declaredBytes: number().int().nonnegative().nullable()
+});
 /**
 * Adoption job — the background form of `device-adoption.adopt`.
 *
@@ -25352,6 +25370,7 @@ _enum([
 	"sleeping",
 	"camera-refused",
 	"no-keyframe",
+	"decode-failed",
 	"no-catalog-row",
 	"unsupported",
 	"unknown-device",
@@ -25655,12 +25674,37 @@ var ClipWakeSchema = _enum(["authorised"]);
 * 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.
 */
 var VIDEOCLIPS_MAX_READ_BYTES = 50 * 1024 * 1024;
 /**
+* 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.
+*/
+var VIDEOCLIPS_MAX_OFFER_BYTES = 500 * 1024 * 1024;
+/**
 * A clip's finished bytes, inline — the twin of `recordingExport.readExportBytes`.
 *
 * `bytes` is the DECODED length, so nobody infers it from the base64 length,
@@ -25692,6 +25736,32 @@ var ClipBytesSchema = object({
 	durationMs: number().positive().optional()
 });
 /**
+* 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.
+*/
+var ClipBytesOfferSchema = object({
+	/**
+	* One shot, seconds-long, loopback, on the PROVIDER's own host. Open it with
+	* `ctx.peerBytes.open(...)`, which refuses a ticket from another node by
+	* name rather than dialling a port that means something else here.
+	*/
+	ticket: PeerBytesTicketSchema,
+	contentType: string(),
+	/** Suggested filename, extension included. */
+	name: string(),
+	/** Which twin was actually served — see {@link ClipBytesSchema.served}. */
+	served: CamProfileSchema,
+	/** See {@link ClipBytesSchema.durationMs}. Absent when nothing measured it. */
+	durationMs: number().positive().optional()
+});
+/**
 * Where a clip's STREAM can be dialled (D597) — the answer to
 * {@link videoclipsCapability.methods.dialClipStream}.
 *
@@ -25767,6 +25837,105 @@ var ClipStreamDialSchema = object({
 	/** Why `servedAudio` is `none` although sound was asked for. */
 	audioReason: ClipStreamAudioReasonSchema.optional()
 });
+/**
+* The playback rates a clip can be DELIVERED at, ascending, always with `1`.
+*
+* 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 — so the domain is the recorded one, {0} ∪ [0.25, 4],
+* and this is the discrete ladder drawn from it. `1.5` is in it because a
+* re-pacer has no reason to refuse it.
+*
+* `8` and `16` are deliberately NOT here. They are the CAMERA's own
+* `<playSpeed>` (Reolink cmd-5 replay), a different mechanism, still unwired
+* (D597, D600) — a rate change there costs a new dial and a new stream, and
+* the camera's 8x would need a resample the clip audio path has no decoder
+* for. Offering them today accepts a rate and delivers 1x, which is the whole
+* defect this list exists to end (D612). When `playSpeed` IS wired its rates
+* join THIS array — a second list elsewhere is the second authority D62
+* forbids.
+*
+* Every entry must survive the broker's `clampPlaybackRate` unchanged: a set
+* that offers what the clamp then moves is the same lie one step later.
+*/
+var CLIP_BROKER_PACED_RATES = [
+	.25,
+	.5,
+	1,
+	1.5,
+	2,
+	4
+];
+/**
+* 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.
+*/
+var CLIP_REALTIME_SOURCE_RATES = [
+	.25,
+	.5,
+	1
+];
+/**
+* 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).
+*/
+var ClipPlaybackOptionsSchema = object({
+	/**
+	* How this provider's clips reach the player. `stream` is the provider's
+	* forward-only fMP4 (D597); `file` is one bounded by-handle fetch of the
+	* whole clip, `stbl` indexed (D575).
+	*/
+	transport: _enum(["stream", "file"]),
+	/** `forward` = only ahead of the playhead. `free` = anywhere. */
+	seek: _enum(["forward", "free"]),
+	/** Frame-step BACKWARD is meaningful. Forward always is. */
+	stepBack: boolean(),
+	/** Whether the scrub gesture is served, as opposed to refused by name. */
+	scrub: boolean(),
+	/**
+	* The rates that can be delivered, ascending, always containing `1`. The
+	* viewer draws its picker from this and from nothing else — a constant it
+	* keeps instead is the second authority that produced the defect: `8` and
+	* `16` were offered, the broker clamped them to `4`, and no line anywhere
+	* said so. `0` is not a member: pause is the absence of a rate.
+	*/
+	rates: array(number().positive()).min(1).readonly()
+});
 var ClipSourceAvailabilitySchema = object({
 	state: _enum([
 		"ok",
@@ -25945,14 +26114,18 @@ var 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
@@ -26019,6 +26192,65 @@ var videoclipsCapability = {
 			auth: "protected"
 		}),
 		/**
+		* 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.
+		*/
+		offerClipBytes: optionalMethod(object({
+			deviceId: number(),
+			clipId: string().min(1),
+			/** WHICH provider holds the bytes — see `readClipBytes.provider`. */
+			provider: string().min(1),
+			/** Which twin — `low | mid` → the sub file, `high` → the main twin. */
+			profile: CamProfileSchema.optional(),
+			/**
+			* The CALLER's byte bound, so an over-size clip is refused before the
+			* camera is touched rather than after. Capped by
+			* {@link VIDEOCLIPS_MAX_OFFER_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()
+		}), ClipBytesOfferSchema, {
+			kind: "query",
+			auth: "protected"
+		}),
+		/**
 		* 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
 		* play through the same WebRTC session as recorded footage, with the
@@ -26055,10 +26287,88 @@ var videoclipsCapability = {
 		}), ClipStreamDialSchema, {
 			kind: "query",
 			auth: "protected"
+		}),
+		/**
+		* 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.
+		*/
+		getPlaybackOptions: optionalMethod(object({
+			deviceId: number(),
+			/** WHICH provider to ask — the `addonId` a {@link ClipSourceSchema}
+			*  row carries. Required for the same reason `listClips` requires it:
+			*  a collection cap has no "the bound one" to resolve to (D554). */
+			provider: string().min(1)
+		}), ClipPlaybackOptionsSchema, {
+			kind: "query",
+			auth: "protected"
 		})
 	}
 };
 /**
+* 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.
+*/
+var CLIP_PLAYBACK_OPTIONS = {
+	stream: {
+		transport: "stream",
+		seek: "forward",
+		stepBack: false,
+		scrub: false,
+		rates: CLIP_BROKER_PACED_RATES
+	},
+	/**
+	* 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.
+	*/
+	realtimeStream: {
+		transport: "stream",
+		seek: "forward",
+		stepBack: false,
+		scrub: false,
+		rates: CLIP_REALTIME_SOURCE_RATES
+	},
+	file: {
+		transport: "file",
+		seek: "free",
+		stepBack: true,
+		scrub: true,
+		rates: CLIP_BROKER_PACED_RATES
+	}
+};
+/**
 * Optional client-side hints sent at session creation to help the provider
 * pick the best native source. All fields optional — a viewer that knows
 * nothing still gets a sane default. (Relocated from the retired `webrtc`
@@ -47203,6 +47513,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"videoclips.getPlaybackOptions": {
+		capName: "videoclips",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"videoclips.listClips": {
 		capName: "videoclips",
 		capScope: "device",
@@ -47215,6 +47531,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"videoclips.offerClipBytes": {
+		capName: "videoclips",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"videoclips.readClipBytes": {
 		capName: "videoclips",
 		capScope: "device",
@@ -49261,6 +49583,11 @@ Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"videoclips.getPlaybackOptions": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"videoclips.listClips": [{
 		name: "deviceId",
 		form: "single",
@@ -49271,6 +49598,11 @@ Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"videoclips.offerClipBytes": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"videoclips.readClipBytes": [{
 		name: "deviceId",
 		form: "single",
@@ -79070,7 +79402,7 @@ var require_lz4 = /* @__PURE__ */ require_chunk.__commonJSMin(((exports) => {
 	};
 }));
 //#endregion
-//#region node_modules/@apocaliss92/nodelink-js/dist/chunk-IPKY5AWA.js
+//#region node_modules/@apocaliss92/nodelink-js/dist/chunk-7B2Z5FIA.js
 var import_fxp = require_fxp();
 var import_lz4 = /* @__PURE__ */ require_chunk.__toESM(require_lz4(), 1);
 function encodeHeader(h) {
@@ -82579,6 +82911,7 @@ var BaichuanClient = class _BaichuanClient extends events.EventEmitter {
 			if (prev.superseded) continue;
 			prev.superseded = true;
 			this.logger?.warn?.(`[BaichuanClient] cmd 5 replay session #${prev.id} (channelId=${prev.discriminator.channelId}, ${prev.discriminator.kind}) superseded by #${this.replaySessionSeq + 1} after ${prev.acceptedFrames} accepted frame(s). Frames still in flight for #${prev.id} will be dropped, not handed to its successor.`);
+			prev.onSuperseded?.(/* @__PURE__ */ new Error(`cmd 5 replay session #${prev.id} was superseded by a later transfer on this socket after ${prev.acceptedFrames} accepted frame(s)`));
 		}
 		const session = {
 			id: ++this.replaySessionSeq,
@@ -83301,6 +83634,10 @@ var BaichuanClient = class _BaichuanClient extends events.EventEmitter {
 				cleanup();
 				reject(e instanceof Error ? e : new Error(String(e)));
 			};
+			session.onSuperseded = (reason) => {
+				if (chunks.length > 0) finish(Buffer.concat(chunks));
+				else fail(reason);
+			};
 			const armIdleFinish = () => {
 				if (idleTimer) clearTimeout(idleTimer);
 				idleTimer = setTimeout(() => {
@@ -154602,6 +154939,118 @@ function createReolinkVideoclipsProvider(deps) {
 			};
 		},
 		/**
+		* The same clip, over the addon→addon byte transport (D613).
+		*
+		* Every gate {@link readClipBytes} runs, in the same order and with the
+		* same vocabulary — the id, the row, a clip still being written, the twin,
+		* the size the ROW declares, and the sleep gate, which the producer
+		* decides before `getApi()` because on UDP the login IS the wake. The one
+		* difference is the envelope: the bytes leave over a one-shot loopback
+		* socket instead of inside a base64 field, so the caller holds nothing and
+		* this process holds the one copy the cmd-5 transfer already produced.
+		*
+		* The bound is {@link VIDEOCLIPS_MAX_OFFER_BYTES}: ten times the inline
+		* one, because the inline one was paying for two inflated copies and this
+		* pays for one plain one.
+		*/
+		offerClipBytes: async ({ deviceId, clipId, profile, maxBytes, wake }) => {
+			const tags = { deviceId };
+			const refuse = (code, detail, meta) => {
+				deps.logger.warn("videoclips: refusing a clip byte offer", {
+					tags,
+					meta: {
+						clipId,
+						branch: code,
+						...meta
+					}
+				});
+				throw new Error(clipExportFailure(code, detail));
+			};
+			const parsed = parseClipId(clipId);
+			if (parsed === null) return refuse("catalog-miss", `clip id "${clipId}" was not minted by the Reolink provider`, {});
+			const clipKey = clipKeyFor(parsed.channel, parsed.fileName);
+			const row = rowsByKey.get(`${deviceId}|${clipKey}`);
+			if (row === void 0) return refuse("catalog-miss", `clip "${clipId}" is not in this node's catalog for device ${deviceId} — list the day that holds it first`, { clipKey });
+			if (row.inProgress === true) return refuse("clip-in-progress", `clip "${clipId}" is still being written, so it has no end to export`, { clipKey });
+			const chosen = chooseClipTwin(profile, row);
+			if (chosen.downgraded) deps.logger.warn("videoclips: no main twin for this clip — serving the sub copy", {
+				tags,
+				meta: {
+					clipId,
+					clipKey,
+					branch: "no-main-twin",
+					asked: profile
+				}
+			});
+			const twin = chosen.twin;
+			const fileName = chosen.fileName;
+			if (fileName === "") return refuse("no-file-for-window", `clip "${clipId}" is listed with no byte handle behind it`, {
+				clipKey,
+				twin
+			});
+			const served = chosen.served;
+			const bound = Math.min(maxBytes ?? 524288e3, VIDEOCLIPS_MAX_OFFER_BYTES);
+			const declaredBytes = twin === "main" ? row.mainBytes : row.subBytes;
+			if (declaredBytes !== void 0 && declaredBytes > bound) return refuse("too-large-to-transfer", `the camera lists the ${twin} file of clip "${clipId}" as ${declaredBytes} bytes, over the ${bound}-byte bound for one transfer`, {
+				clipKey,
+				twin,
+				declaredBytes,
+				bound
+			});
+			const outcome = await deps.prepareOffer({
+				deviceId,
+				row,
+				fileName,
+				twin,
+				...wake !== void 0 ? { wake } : {}
+			});
+			if (outcome.kind === "refused") throw new Error(clipExportFailure(outcome.code, outcome.detail));
+			if (outcome.bytes > bound) return refuse("too-large-to-transfer", `clip "${clipId}" muxed to ${outcome.bytes} bytes, over the ${bound}-byte bound for one transfer`, {
+				clipKey,
+				twin,
+				bytes: outcome.bytes,
+				bound
+			});
+			deps.logger.info("videoclips: offered a Reolink clip by handle", {
+				tags,
+				meta: {
+					clipId,
+					clipKey,
+					twin,
+					served,
+					asked: profile ?? null,
+					bytes: outcome.bytes,
+					durationMs: outcome.durationMs,
+					wake: wake ?? "none"
+				}
+			});
+			return {
+				ticket: outcome.ticket,
+				contentType: "video/mp4",
+				name: clipFileLabel(fileName),
+				served,
+				...outcome.durationMs !== null ? { durationMs: outcome.durationMs } : {}
+			};
+		},
+		/**
+		* What a surface may DRAW for this camera's clips (D612).
+		*
+		* A CONSTANT, and it has to be: this method is asked per camera, and the
+		* answer is a fact about which accessors this provider wires, not about
+		* the camera. Every clip here reaches the player over
+		* {@link dialClipStream}'s forward-only stream, so every clip gets the
+		* `stream` envelope — measured, not assumed: the broker's `chooseClipPath`
+		* reads only whether the dial and the file read are wired, and never the
+		* clip or the profile.
+		*
+		* The rates are the BROKER's re-pacing ladder. The camera's own
+		* `<playSpeed>` (8, 16) is real and still unwired (D597, D600): it would
+		* ride on the dial and cost a new stream per change, and its audio has no
+		* resampler on this path. When it is wired its rates join
+		* `CLIP_BROKER_PACED_RATES` — not a second list here.
+		*/
+		getPlaybackOptions: async () => CLIP_PLAYBACK_OPTIONS.stream,
+		/**
 		* Where this clip's STREAM is dialled (D597) — the same questions
 		* `readClipBytes` asks before the camera is touched (the id, the row, a
 		* file still being written), the same vocabulary, and NO fetch: the URL
@@ -155572,6 +156021,62 @@ function createClipService(deps) {
 		return outcome;
 	};
 	/**
+	* The same clip, offered over the addon→addon byte transport (D613).
+	*
+	* It reuses {@link prepareBytes} whole — one fetch path, one set of
+	* completion rules, one scratch. A second producer here would be the second
+	* authority D558 refuses to create. What changes is only how the result
+	* LEAVES: `offerBuffer` writes it to a one-shot loopback socket in bounded
+	* chunks, honouring `write()`'s return (D447), instead of base64-ing it into
+	* a cap envelope that the caller then copies again.
+	*/
+	const prepareOffer = async (input) => {
+		const peerBytes = deps.peerBytes;
+		if (peerBytes === void 0) {
+			deps.logger.warn("videoclips: no peer-bytes transport on this node", {
+				tags: { deviceId: input.deviceId },
+				meta: {
+					clipKey: input.row.clipKey,
+					branch: "no-peer-bytes"
+				}
+			});
+			return {
+				kind: "refused",
+				code: "fetch-failed",
+				detail: "this node has no addon-to-addon byte transport wired"
+			};
+		}
+		const outcome = await prepareBytes(input);
+		if (outcome.kind === "refused") return outcome;
+		const offered = await peerBytes.offerBuffer({
+			bytes: outcome.bytes,
+			contentType: "video/mp4",
+			label: "reolink-clip",
+			deviceId: input.deviceId
+		});
+		if (offered.kind === "refused") {
+			deps.logger.warn("videoclips: the clip byte offer could not be minted", {
+				tags: { deviceId: input.deviceId },
+				meta: {
+					clipKey: input.row.clipKey,
+					branch: offered.code,
+					detail: offered.detail
+				}
+			});
+			return {
+				kind: "refused",
+				code: "fetch-failed",
+				detail: `${offered.code}: ${offered.detail}`
+			};
+		}
+		return {
+			kind: "ok",
+			ticket: offered.ticket,
+			durationMs: outcome.durationMs,
+			bytes: outcome.bytes.byteLength
+		};
+	};
+	/**
 	* The STREAM's path (`clip-stream-route.ts`): the same gates, the same row,
 	* nothing written. Beside the file path, not in its place.
 	*/
@@ -155611,6 +156116,7 @@ function createClipService(deps) {
 			served: profile === "high" ? "high" : "low"
 		}),
 		prepareBytes,
+		prepareOffer,
 		prepareStreamDial: async ({ deviceId, row, twin, audio }) => {
 			const gate = await gateClipDevice({
 				deviceId,
@@ -170289,6 +170795,7 @@ var ReolinkProviderAddon = class extends BaseDeviceProvider {
 		this.clipService = createClipService({
 			dataDir: this.ctx.dataDir,
 			logger: this.ctx.logger,
+			...this.ctx.peerBytes !== void 0 ? { peerBytes: this.ctx.peerBytes } : {},
 			resolveDevice: async (deviceId) => {
 				const device = this.ctx.kernel.deviceRegistry?.getById(deviceId);
 				return device instanceof ReolinkCamera ? device.getClipDeviceRef() : null;

package/dist/addon.mjs

@@ -5386,7 +5386,7 @@ var ZodIssueCode = {
 var ZodFirstPartyTypeKind;
 ZodFirstPartyTypeKind || (ZodFirstPartyTypeKind = {});
 //#endregion
-//#region ../types/dist/sleep-i3eUVc-d.mjs
+//#region ../types/dist/sleep-COWaSCAi.mjs
 /**
 * The audio chunk plane's byte format, and the ONE expansion from a coded
 * window to float samples (D455).
@@ -7602,6 +7602,24 @@ object({
 		unreachable: number()
 	})
 });
+/** The wire shape of {@link PeerBytesTicket} — see the type for what it is. */
+var PeerBytesTicketSchema = object({
+	/** `http://127.0.0.1:<port>/<token>`. One `GET` takes it. */
+	url: string().min(1),
+	/**
+	* The HOST node this URL means something on — the hub or a named agent,
+	* never a runner. {@link AddonPeerBytes.open} compares it to its own and
+	* refuses `cross-node` by name when they differ, without dialling.
+	*/
+	hostNodeId: string().min(1),
+	expiresAtMs: number().int().nonnegative(),
+	/**
+	* What the producer DECLARED the body to be, when it knows — `null` when it
+	* does not. Never `0` for unknown (D393): a consumer sizing a bound off this
+	* must be able to tell "the producer did not say" from "the body is empty".
+	*/
+	declaredBytes: number().int().nonnegative().nullable()
+});
 /**
 * Adoption job — the background form of `device-adoption.adopt`.
 *
@@ -25347,6 +25365,7 @@ _enum([
 	"sleeping",
 	"camera-refused",
 	"no-keyframe",
+	"decode-failed",
 	"no-catalog-row",
 	"unsupported",
 	"unknown-device",
@@ -25650,12 +25669,37 @@ var ClipWakeSchema = _enum(["authorised"]);
 * 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.
 */
 var VIDEOCLIPS_MAX_READ_BYTES = 50 * 1024 * 1024;
 /**
+* 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.
+*/
+var VIDEOCLIPS_MAX_OFFER_BYTES = 500 * 1024 * 1024;
+/**
 * A clip's finished bytes, inline — the twin of `recordingExport.readExportBytes`.
 *
 * `bytes` is the DECODED length, so nobody infers it from the base64 length,
@@ -25687,6 +25731,32 @@ var ClipBytesSchema = object({
 	durationMs: number().positive().optional()
 });
 /**
+* 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.
+*/
+var ClipBytesOfferSchema = object({
+	/**
+	* One shot, seconds-long, loopback, on the PROVIDER's own host. Open it with
+	* `ctx.peerBytes.open(...)`, which refuses a ticket from another node by
+	* name rather than dialling a port that means something else here.
+	*/
+	ticket: PeerBytesTicketSchema,
+	contentType: string(),
+	/** Suggested filename, extension included. */
+	name: string(),
+	/** Which twin was actually served — see {@link ClipBytesSchema.served}. */
+	served: CamProfileSchema,
+	/** See {@link ClipBytesSchema.durationMs}. Absent when nothing measured it. */
+	durationMs: number().positive().optional()
+});
+/**
 * Where a clip's STREAM can be dialled (D597) — the answer to
 * {@link videoclipsCapability.methods.dialClipStream}.
 *
@@ -25762,6 +25832,105 @@ var ClipStreamDialSchema = object({
 	/** Why `servedAudio` is `none` although sound was asked for. */
 	audioReason: ClipStreamAudioReasonSchema.optional()
 });
+/**
+* The playback rates a clip can be DELIVERED at, ascending, always with `1`.
+*
+* 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 — so the domain is the recorded one, {0} ∪ [0.25, 4],
+* and this is the discrete ladder drawn from it. `1.5` is in it because a
+* re-pacer has no reason to refuse it.
+*
+* `8` and `16` are deliberately NOT here. They are the CAMERA's own
+* `<playSpeed>` (Reolink cmd-5 replay), a different mechanism, still unwired
+* (D597, D600) — a rate change there costs a new dial and a new stream, and
+* the camera's 8x would need a resample the clip audio path has no decoder
+* for. Offering them today accepts a rate and delivers 1x, which is the whole
+* defect this list exists to end (D612). When `playSpeed` IS wired its rates
+* join THIS array — a second list elsewhere is the second authority D62
+* forbids.
+*
+* Every entry must survive the broker's `clampPlaybackRate` unchanged: a set
+* that offers what the clamp then moves is the same lie one step later.
+*/
+var CLIP_BROKER_PACED_RATES = [
+	.25,
+	.5,
+	1,
+	1.5,
+	2,
+	4
+];
+/**
+* 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.
+*/
+var CLIP_REALTIME_SOURCE_RATES = [
+	.25,
+	.5,
+	1
+];
+/**
+* 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).
+*/
+var ClipPlaybackOptionsSchema = object({
+	/**
+	* How this provider's clips reach the player. `stream` is the provider's
+	* forward-only fMP4 (D597); `file` is one bounded by-handle fetch of the
+	* whole clip, `stbl` indexed (D575).
+	*/
+	transport: _enum(["stream", "file"]),
+	/** `forward` = only ahead of the playhead. `free` = anywhere. */
+	seek: _enum(["forward", "free"]),
+	/** Frame-step BACKWARD is meaningful. Forward always is. */
+	stepBack: boolean(),
+	/** Whether the scrub gesture is served, as opposed to refused by name. */
+	scrub: boolean(),
+	/**
+	* The rates that can be delivered, ascending, always containing `1`. The
+	* viewer draws its picker from this and from nothing else — a constant it
+	* keeps instead is the second authority that produced the defect: `8` and
+	* `16` were offered, the broker clamped them to `4`, and no line anywhere
+	* said so. `0` is not a member: pause is the absence of a rate.
+	*/
+	rates: array(number().positive()).min(1).readonly()
+});
 var ClipSourceAvailabilitySchema = object({
 	state: _enum([
 		"ok",
@@ -25940,14 +26109,18 @@ var 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
@@ -26014,6 +26187,65 @@ var videoclipsCapability = {
 			auth: "protected"
 		}),
 		/**
+		* 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.
+		*/
+		offerClipBytes: optionalMethod(object({
+			deviceId: number(),
+			clipId: string().min(1),
+			/** WHICH provider holds the bytes — see `readClipBytes.provider`. */
+			provider: string().min(1),
+			/** Which twin — `low | mid` → the sub file, `high` → the main twin. */
+			profile: CamProfileSchema.optional(),
+			/**
+			* The CALLER's byte bound, so an over-size clip is refused before the
+			* camera is touched rather than after. Capped by
+			* {@link VIDEOCLIPS_MAX_OFFER_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()
+		}), ClipBytesOfferSchema, {
+			kind: "query",
+			auth: "protected"
+		}),
+		/**
 		* 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
 		* play through the same WebRTC session as recorded footage, with the
@@ -26050,10 +26282,88 @@ var videoclipsCapability = {
 		}), ClipStreamDialSchema, {
 			kind: "query",
 			auth: "protected"
+		}),
+		/**
+		* 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.
+		*/
+		getPlaybackOptions: optionalMethod(object({
+			deviceId: number(),
+			/** WHICH provider to ask — the `addonId` a {@link ClipSourceSchema}
+			*  row carries. Required for the same reason `listClips` requires it:
+			*  a collection cap has no "the bound one" to resolve to (D554). */
+			provider: string().min(1)
+		}), ClipPlaybackOptionsSchema, {
+			kind: "query",
+			auth: "protected"
 		})
 	}
 };
 /**
+* 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.
+*/
+var CLIP_PLAYBACK_OPTIONS = {
+	stream: {
+		transport: "stream",
+		seek: "forward",
+		stepBack: false,
+		scrub: false,
+		rates: CLIP_BROKER_PACED_RATES
+	},
+	/**
+	* 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.
+	*/
+	realtimeStream: {
+		transport: "stream",
+		seek: "forward",
+		stepBack: false,
+		scrub: false,
+		rates: CLIP_REALTIME_SOURCE_RATES
+	},
+	file: {
+		transport: "file",
+		seek: "free",
+		stepBack: true,
+		scrub: true,
+		rates: CLIP_BROKER_PACED_RATES
+	}
+};
+/**
 * Optional client-side hints sent at session creation to help the provider
 * pick the best native source. All fields optional — a viewer that knows
 * nothing still gets a sane default. (Relocated from the retired `webrtc`
@@ -47198,6 +47508,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"videoclips.getPlaybackOptions": {
+		capName: "videoclips",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"videoclips.listClips": {
 		capName: "videoclips",
 		capScope: "device",
@@ -47210,6 +47526,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"videoclips.offerClipBytes": {
+		capName: "videoclips",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"videoclips.readClipBytes": {
 		capName: "videoclips",
 		capScope: "device",
@@ -49256,6 +49578,11 @@ Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"videoclips.getPlaybackOptions": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"videoclips.listClips": [{
 		name: "deviceId",
 		form: "single",
@@ -49266,6 +49593,11 @@ Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"videoclips.offerClipBytes": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"videoclips.readClipBytes": [{
 		name: "deviceId",
 		form: "single",
@@ -79065,7 +79397,7 @@ var require_lz4 = /* @__PURE__ */ __commonJSMin(((exports) => {
 	};
 }));
 //#endregion
-//#region node_modules/@apocaliss92/nodelink-js/dist/chunk-IPKY5AWA.js
+//#region node_modules/@apocaliss92/nodelink-js/dist/chunk-7B2Z5FIA.js
 var import_fxp = require_fxp();
 var import_lz4 = /* @__PURE__ */ __toESM(require_lz4(), 1);
 function encodeHeader(h) {
@@ -82574,6 +82906,7 @@ var BaichuanClient = class _BaichuanClient extends EventEmitter {
 			if (prev.superseded) continue;
 			prev.superseded = true;
 			this.logger?.warn?.(`[BaichuanClient] cmd 5 replay session #${prev.id} (channelId=${prev.discriminator.channelId}, ${prev.discriminator.kind}) superseded by #${this.replaySessionSeq + 1} after ${prev.acceptedFrames} accepted frame(s). Frames still in flight for #${prev.id} will be dropped, not handed to its successor.`);
+			prev.onSuperseded?.(/* @__PURE__ */ new Error(`cmd 5 replay session #${prev.id} was superseded by a later transfer on this socket after ${prev.acceptedFrames} accepted frame(s)`));
 		}
 		const session = {
 			id: ++this.replaySessionSeq,
@@ -83296,6 +83629,10 @@ var BaichuanClient = class _BaichuanClient extends EventEmitter {
 				cleanup();
 				reject(e instanceof Error ? e : new Error(String(e)));
 			};
+			session.onSuperseded = (reason) => {
+				if (chunks.length > 0) finish(Buffer.concat(chunks));
+				else fail(reason);
+			};
 			const armIdleFinish = () => {
 				if (idleTimer) clearTimeout(idleTimer);
 				idleTimer = setTimeout(() => {
@@ -154597,6 +154934,118 @@ function createReolinkVideoclipsProvider(deps) {
 			};
 		},
 		/**
+		* The same clip, over the addon→addon byte transport (D613).
+		*
+		* Every gate {@link readClipBytes} runs, in the same order and with the
+		* same vocabulary — the id, the row, a clip still being written, the twin,
+		* the size the ROW declares, and the sleep gate, which the producer
+		* decides before `getApi()` because on UDP the login IS the wake. The one
+		* difference is the envelope: the bytes leave over a one-shot loopback
+		* socket instead of inside a base64 field, so the caller holds nothing and
+		* this process holds the one copy the cmd-5 transfer already produced.
+		*
+		* The bound is {@link VIDEOCLIPS_MAX_OFFER_BYTES}: ten times the inline
+		* one, because the inline one was paying for two inflated copies and this
+		* pays for one plain one.
+		*/
+		offerClipBytes: async ({ deviceId, clipId, profile, maxBytes, wake }) => {
+			const tags = { deviceId };
+			const refuse = (code, detail, meta) => {
+				deps.logger.warn("videoclips: refusing a clip byte offer", {
+					tags,
+					meta: {
+						clipId,
+						branch: code,
+						...meta
+					}
+				});
+				throw new Error(clipExportFailure(code, detail));
+			};
+			const parsed = parseClipId(clipId);
+			if (parsed === null) return refuse("catalog-miss", `clip id "${clipId}" was not minted by the Reolink provider`, {});
+			const clipKey = clipKeyFor(parsed.channel, parsed.fileName);
+			const row = rowsByKey.get(`${deviceId}|${clipKey}`);
+			if (row === void 0) return refuse("catalog-miss", `clip "${clipId}" is not in this node's catalog for device ${deviceId} — list the day that holds it first`, { clipKey });
+			if (row.inProgress === true) return refuse("clip-in-progress", `clip "${clipId}" is still being written, so it has no end to export`, { clipKey });
+			const chosen = chooseClipTwin(profile, row);
+			if (chosen.downgraded) deps.logger.warn("videoclips: no main twin for this clip — serving the sub copy", {
+				tags,
+				meta: {
+					clipId,
+					clipKey,
+					branch: "no-main-twin",
+					asked: profile
+				}
+			});
+			const twin = chosen.twin;
+			const fileName = chosen.fileName;
+			if (fileName === "") return refuse("no-file-for-window", `clip "${clipId}" is listed with no byte handle behind it`, {
+				clipKey,
+				twin
+			});
+			const served = chosen.served;
+			const bound = Math.min(maxBytes ?? 524288e3, VIDEOCLIPS_MAX_OFFER_BYTES);
+			const declaredBytes = twin === "main" ? row.mainBytes : row.subBytes;
+			if (declaredBytes !== void 0 && declaredBytes > bound) return refuse("too-large-to-transfer", `the camera lists the ${twin} file of clip "${clipId}" as ${declaredBytes} bytes, over the ${bound}-byte bound for one transfer`, {
+				clipKey,
+				twin,
+				declaredBytes,
+				bound
+			});
+			const outcome = await deps.prepareOffer({
+				deviceId,
+				row,
+				fileName,
+				twin,
+				...wake !== void 0 ? { wake } : {}
+			});
+			if (outcome.kind === "refused") throw new Error(clipExportFailure(outcome.code, outcome.detail));
+			if (outcome.bytes > bound) return refuse("too-large-to-transfer", `clip "${clipId}" muxed to ${outcome.bytes} bytes, over the ${bound}-byte bound for one transfer`, {
+				clipKey,
+				twin,
+				bytes: outcome.bytes,
+				bound
+			});
+			deps.logger.info("videoclips: offered a Reolink clip by handle", {
+				tags,
+				meta: {
+					clipId,
+					clipKey,
+					twin,
+					served,
+					asked: profile ?? null,
+					bytes: outcome.bytes,
+					durationMs: outcome.durationMs,
+					wake: wake ?? "none"
+				}
+			});
+			return {
+				ticket: outcome.ticket,
+				contentType: "video/mp4",
+				name: clipFileLabel(fileName),
+				served,
+				...outcome.durationMs !== null ? { durationMs: outcome.durationMs } : {}
+			};
+		},
+		/**
+		* What a surface may DRAW for this camera's clips (D612).
+		*
+		* A CONSTANT, and it has to be: this method is asked per camera, and the
+		* answer is a fact about which accessors this provider wires, not about
+		* the camera. Every clip here reaches the player over
+		* {@link dialClipStream}'s forward-only stream, so every clip gets the
+		* `stream` envelope — measured, not assumed: the broker's `chooseClipPath`
+		* reads only whether the dial and the file read are wired, and never the
+		* clip or the profile.
+		*
+		* The rates are the BROKER's re-pacing ladder. The camera's own
+		* `<playSpeed>` (8, 16) is real and still unwired (D597, D600): it would
+		* ride on the dial and cost a new stream per change, and its audio has no
+		* resampler on this path. When it is wired its rates join
+		* `CLIP_BROKER_PACED_RATES` — not a second list here.
+		*/
+		getPlaybackOptions: async () => CLIP_PLAYBACK_OPTIONS.stream,
+		/**
 		* Where this clip's STREAM is dialled (D597) — the same questions
 		* `readClipBytes` asks before the camera is touched (the id, the row, a
 		* file still being written), the same vocabulary, and NO fetch: the URL
@@ -155567,6 +156016,62 @@ function createClipService(deps) {
 		return outcome;
 	};
 	/**
+	* The same clip, offered over the addon→addon byte transport (D613).
+	*
+	* It reuses {@link prepareBytes} whole — one fetch path, one set of
+	* completion rules, one scratch. A second producer here would be the second
+	* authority D558 refuses to create. What changes is only how the result
+	* LEAVES: `offerBuffer` writes it to a one-shot loopback socket in bounded
+	* chunks, honouring `write()`'s return (D447), instead of base64-ing it into
+	* a cap envelope that the caller then copies again.
+	*/
+	const prepareOffer = async (input) => {
+		const peerBytes = deps.peerBytes;
+		if (peerBytes === void 0) {
+			deps.logger.warn("videoclips: no peer-bytes transport on this node", {
+				tags: { deviceId: input.deviceId },
+				meta: {
+					clipKey: input.row.clipKey,
+					branch: "no-peer-bytes"
+				}
+			});
+			return {
+				kind: "refused",
+				code: "fetch-failed",
+				detail: "this node has no addon-to-addon byte transport wired"
+			};
+		}
+		const outcome = await prepareBytes(input);
+		if (outcome.kind === "refused") return outcome;
+		const offered = await peerBytes.offerBuffer({
+			bytes: outcome.bytes,
+			contentType: "video/mp4",
+			label: "reolink-clip",
+			deviceId: input.deviceId
+		});
+		if (offered.kind === "refused") {
+			deps.logger.warn("videoclips: the clip byte offer could not be minted", {
+				tags: { deviceId: input.deviceId },
+				meta: {
+					clipKey: input.row.clipKey,
+					branch: offered.code,
+					detail: offered.detail
+				}
+			});
+			return {
+				kind: "refused",
+				code: "fetch-failed",
+				detail: `${offered.code}: ${offered.detail}`
+			};
+		}
+		return {
+			kind: "ok",
+			ticket: offered.ticket,
+			durationMs: outcome.durationMs,
+			bytes: outcome.bytes.byteLength
+		};
+	};
+	/**
 	* The STREAM's path (`clip-stream-route.ts`): the same gates, the same row,
 	* nothing written. Beside the file path, not in its place.
 	*/
@@ -155606,6 +156111,7 @@ function createClipService(deps) {
 			served: profile === "high" ? "high" : "low"
 		}),
 		prepareBytes,
+		prepareOffer,
 		prepareStreamDial: async ({ deviceId, row, twin, audio }) => {
 			const gate = await gateClipDevice({
 				deviceId,
@@ -170284,6 +170790,7 @@ var ReolinkProviderAddon = class extends BaseDeviceProvider {
 		this.clipService = createClipService({
 			dataDir: this.ctx.dataDir,
 			logger: this.ctx.logger,
+			...this.ctx.peerBytes !== void 0 ? { peerBytes: this.ctx.peerBytes } : {},
 			resolveDevice: async (deviceId) => {
 				const device = this.ctx.kernel.deviceRegistry?.getById(deviceId);
 				return device instanceof ReolinkCamera ? device.getClipDeviceRef() : null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/addon-provider-reolink",
-  "version": "1.2.162",
+  "version": "1.2.163",
   "description": "Reolink camera device provider addon for CamStack — native Baichuan protocol",
   "keywords": [
     "camstack",
@@ -94,7 +94,7 @@
     "publish:npm": "npm publish --access public"
   },
   "dependencies": {
-    "@apocaliss92/nodelink-js": "^0.10.0"
+    "@apocaliss92/nodelink-js": "^0.10.1"
   },
   "peerDependencies": {
     "@camstack/types": "*",