@camstack/addon-provider-reolink 1.2.147 → 1.2.148

package/dist/addon.js

@@ -25447,22 +25447,40 @@ var videoclipsCapability = {
 			limit: number().int().positive().optional(),
 			/**
 			* WHICH provider to ask — the `addonId` a {@link ClipSourceSchema} row
-			* carries, never a source id and never a list.
+			* carries, never a source id and never a list. **Required** (D554 amended).
 			*
-			* Absent means the device's BOUND provider, which is CamStack on every
-			* camera today because that is what `deviceManager.getBindings`
-			* answers with. A provider the device is not bound to is refused by
-			* name rather than answered by another one (D552's
-			* `rejectUnresolvedAddonPin` rule).
+			* A provider the device is not bound to is refused by name rather than
+			* answered by another one (D552's `rejectUnresolvedAddonPin` rule).
+			*
+			* It was optional, documented as "absent means the device's BOUND
+			* provider, which is CamStack on every camera". No code implemented
+			* that. Measured on the live hub 2026-09-20 — device 592, bound to
+			* `recorder` AND `provider-reolink` — a bare call with `limit: 3`
+			* answered SIX rows, three from each source, merged newest-first:
+			* `device-collection-dispatch.ts` simply left the fan-out un-narrowed,
+			* so absence bought the union this method exists not to be, and
+			* `limit` meant `limit × sources`.
+			*
+			* There is nothing to restore the default to. `getBindings` answers a
+			* collection cap with a DERIVED, PLURAL set (D554 amended, step 0);
+			* `setWrapperActive` — the singleton authority that could name one —
+			* throws for a collection cap by design. Naming CamStack here instead
+			* would privilege one addon by id inside a surface whose premise is
+			* that sources are peers, and would be wrong on the first camera with
+			* no recorder binding. So absence is REFUSED, in the schema, where the
+			* generated types make it unomittable rather than merely discouraged.
+			*
+			* The default belongs to the SURFACE, which has the `listSources` rows
+			* and can say which one it picked (D569 § 1–3; the viewer already
+			* always sends this).
 			*
 			* It replaced `sources?: string[]`, a VIEW filter over source ids that
 			* assumed the answer was a fan-out over everything a camera has. The
-			* operator settled otherwise on 2026-09-20 — *"il get videoclips
-			* prendere un provider opzionale, di default va su camstack"*,
-			* *"l'utilizzatore è uno solo"* — so the list is asked of one provider
-			* at a time and there is nothing to filter out of it.
+			* operator settled otherwise on 2026-09-20 — *"l'utilizzatore è uno
+			* solo"* — so the list is asked of one provider at a time and there is
+			* nothing to filter out of it.
 			*/
-			provider: string().optional()
+			provider: string().min(1)
 		}), array(ClipSchema).readonly(), {
 			kind: "query",
 			auth: "protected"
@@ -148234,6 +148252,51 @@ function describeMuxFailure(run) {
 	return null;
 }
 //#endregion
+//#region src/clips/clip-truncation.ts
+/**
+* The window a TRUNCATED fetch is retried on: the library's own default, the
+* one this repo shipped for its whole life. A retry exists to answer "was that
+* the window or the camera?", so it must be the conservative number and not a
+* second short one.
+*/
+var CLIP_IDLE_WINDOW_RETRY_MS = 2e3;
+/**
+* Did this pass deliver the clip the row describes?
+*
+* Only a SHORTFALL is a defect. A decode that runs longer than the row is
+* routine — the row's stamps are whole seconds and its twins differ by up to
+* four — and calling it truncated would refuse a clip that is more complete
+* than the catalog knew.
+*/
+function judgeClipDuration(input) {
+	if (input.inProgress === true) return {
+		kind: "unknown",
+		reason: "clip-open"
+	};
+	if (input.decodedSeconds === null || !Number.isFinite(input.decodedSeconds)) return {
+		kind: "unknown",
+		reason: "duration-unmeasured"
+	};
+	if (!Number.isFinite(input.expectedMs) || input.expectedMs <= 0) return {
+		kind: "unknown",
+		reason: "row-window-unknown"
+	};
+	const expectedSeconds = input.expectedMs / 1e3;
+	const decodedSeconds = input.decodedSeconds;
+	const shortfallSeconds = expectedSeconds - decodedSeconds;
+	if (shortfallSeconds > 1.5) return {
+		kind: "short",
+		expectedSeconds,
+		decodedSeconds,
+		shortfallSeconds
+	};
+	return {
+		kind: "complete",
+		expectedSeconds,
+		decodedSeconds
+	};
+}
+//#endregion
 //#region src/clips/clip-thumb-queue.ts
 /**
 * The provider's OWN CoverPreview lane — two queues, one in flight per host.
@@ -149718,6 +149781,95 @@ function createClipService(deps) {
 			return refuseStill("camera-refused", reason);
 		}
 	};
+	/**
+	* ONE clip's bytes, on the short window, with the fetch PROVED (D568).
+	*
+	* Completion is an idle window because nothing on the wire ends a cmd 5
+	* transfer, and that window is short. What makes it safe is not the window,
+	* it is the decoded duration judged against the row that asked for it.
+	*/
+	const fetchVerifiedClipBytes = async (device, row, clipKey) => {
+		const deviceId = device.deviceId;
+		const api = await device.getApi();
+		const fetchPass = (idleTimeoutMs) => fetchClipBytes({
+			download: () => api.downloadRecordingDemuxed({
+				channel: device.channel,
+				...device.uid !== void 0 ? { uid: device.uid } : {},
+				fileName: row.subFileName,
+				idleTimeoutMs
+			}),
+			sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+		});
+		const judge = (pass) => judgeClipDuration({
+			expectedMs: row.endMs - row.startMs,
+			decodedSeconds: pass.stats.durationSeconds,
+			...row.inProgress === true ? { inProgress: true } : {}
+		});
+		const first = await fetchPass(300);
+		const firstVerdict = judge(first);
+		if (firstVerdict.kind === "unknown") {
+			const line = {
+				tags: { deviceId },
+				meta: {
+					clipKey,
+					branch: "completeness-unverified",
+					reason: firstVerdict.reason,
+					idleTimeoutMs: 300,
+					expectedMs: row.endMs - row.startMs,
+					decodedSeconds: first.stats.durationSeconds
+				}
+			};
+			if (firstVerdict.reason === "clip-open") deps.logger.debug("videoclips: an open clip cannot be checked for truncation", line);
+			else deps.logger.warn("videoclips: a clip fetch could not be checked for truncation", line);
+			return first;
+		}
+		if (firstVerdict.kind === "complete") return first;
+		deps.logger.warn("videoclips: a clip fetch came back truncated", {
+			tags: { deviceId },
+			meta: {
+				clipKey,
+				branch: "truncated-fetch",
+				idleTimeoutMs: 300,
+				expectedSeconds: firstVerdict.expectedSeconds,
+				decodedSeconds: firstVerdict.decodedSeconds,
+				shortfallSeconds: firstVerdict.shortfallSeconds,
+				bytes: first.annexB.byteLength,
+				keyframes: first.stats.keyframes
+			}
+		});
+		const retry = await fetchPass(CLIP_IDLE_WINDOW_RETRY_MS);
+		const keepRetry = (retry.stats.durationSeconds ?? 0) >= (first.stats.durationSeconds ?? 0);
+		const kept = keepRetry ? retry : first;
+		const verdict = keepRetry ? judge(retry) : firstVerdict;
+		const keptWindowMs = keepRetry ? CLIP_IDLE_WINDOW_RETRY_MS : 300;
+		if (verdict.kind === "short") {
+			deps.logger.warn("videoclips: a clip is still short after the long window", {
+				tags: { deviceId },
+				meta: {
+					clipKey,
+					branch: "truncated-after-retry",
+					idleTimeoutMs: keptWindowMs,
+					retriedOnMs: CLIP_IDLE_WINDOW_RETRY_MS,
+					expectedSeconds: verdict.expectedSeconds,
+					decodedSeconds: verdict.decodedSeconds,
+					shortfallSeconds: verdict.shortfallSeconds,
+					bytes: kept.annexB.byteLength
+				}
+			});
+			return kept;
+		}
+		deps.logger.info("videoclips: a truncated clip fetch landed whole on the long window", {
+			tags: { deviceId },
+			meta: {
+				clipKey,
+				branch: "truncation-recovered",
+				idleTimeoutMs: keptWindowMs,
+				decodedSeconds: verdict.kind === "complete" ? verdict.decodedSeconds : null,
+				bytes: kept.annexB.byteLength
+			}
+		});
+		return kept;
+	};
 	const prepareClip = async (deviceId, clipKey) => {
 		const ready = await media.pathIfPresent(deviceId, clipKey);
 		if (ready !== null) return ready;
@@ -149754,16 +149906,7 @@ function createClipService(deps) {
 			});
 			return null;
 		}
-		const fileName = row.subFileName;
-		const api = await device.getApi();
-		const downloaded = await fetchClipBytes({
-			download: () => api.downloadRecordingDemuxed({
-				channel: device.channel,
-				...device.uid !== void 0 ? { uid: device.uid } : {},
-				fileName
-			}),
-			sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms))
-		});
+		const downloaded = await fetchVerifiedClipBytes(device, row, clipKey);
 		const audio = decideClipAudio(downloaded.audio);
 		if (audio.kind === "silent") deps.logger.warn("videoclips: serving a clip with no sound", {
 			tags: { deviceId },
@@ -149843,7 +149986,8 @@ function createClipService(deps) {
 			await provider.listClips({
 				deviceId,
 				since: until - CLIP_CATALOG_REFRESH_WINDOW_MS,
-				until
+				until,
+				provider: REOLINK_ADDON_ID
 			});
 		},
 		hostBusy: (hostKey) => queue.busy(hostKey),

package/dist/addon.mjs

@@ -25442,22 +25442,40 @@ var videoclipsCapability = {
 			limit: number().int().positive().optional(),
 			/**
 			* WHICH provider to ask — the `addonId` a {@link ClipSourceSchema} row
-			* carries, never a source id and never a list.
+			* carries, never a source id and never a list. **Required** (D554 amended).
 			*
-			* Absent means the device's BOUND provider, which is CamStack on every
-			* camera today because that is what `deviceManager.getBindings`
-			* answers with. A provider the device is not bound to is refused by
-			* name rather than answered by another one (D552's
-			* `rejectUnresolvedAddonPin` rule).
+			* A provider the device is not bound to is refused by name rather than
+			* answered by another one (D552's `rejectUnresolvedAddonPin` rule).
+			*
+			* It was optional, documented as "absent means the device's BOUND
+			* provider, which is CamStack on every camera". No code implemented
+			* that. Measured on the live hub 2026-09-20 — device 592, bound to
+			* `recorder` AND `provider-reolink` — a bare call with `limit: 3`
+			* answered SIX rows, three from each source, merged newest-first:
+			* `device-collection-dispatch.ts` simply left the fan-out un-narrowed,
+			* so absence bought the union this method exists not to be, and
+			* `limit` meant `limit × sources`.
+			*
+			* There is nothing to restore the default to. `getBindings` answers a
+			* collection cap with a DERIVED, PLURAL set (D554 amended, step 0);
+			* `setWrapperActive` — the singleton authority that could name one —
+			* throws for a collection cap by design. Naming CamStack here instead
+			* would privilege one addon by id inside a surface whose premise is
+			* that sources are peers, and would be wrong on the first camera with
+			* no recorder binding. So absence is REFUSED, in the schema, where the
+			* generated types make it unomittable rather than merely discouraged.
+			*
+			* The default belongs to the SURFACE, which has the `listSources` rows
+			* and can say which one it picked (D569 § 1–3; the viewer already
+			* always sends this).
 			*
 			* It replaced `sources?: string[]`, a VIEW filter over source ids that
 			* assumed the answer was a fan-out over everything a camera has. The
-			* operator settled otherwise on 2026-09-20 — *"il get videoclips
-			* prendere un provider opzionale, di default va su camstack"*,
-			* *"l'utilizzatore è uno solo"* — so the list is asked of one provider
-			* at a time and there is nothing to filter out of it.
+			* operator settled otherwise on 2026-09-20 — *"l'utilizzatore è uno
+			* solo"* — so the list is asked of one provider at a time and there is
+			* nothing to filter out of it.
 			*/
-			provider: string().optional()
+			provider: string().min(1)
 		}), array(ClipSchema).readonly(), {
 			kind: "query",
 			auth: "protected"
@@ -148229,6 +148247,51 @@ function describeMuxFailure(run) {
 	return null;
 }
 //#endregion
+//#region src/clips/clip-truncation.ts
+/**
+* The window a TRUNCATED fetch is retried on: the library's own default, the
+* one this repo shipped for its whole life. A retry exists to answer "was that
+* the window or the camera?", so it must be the conservative number and not a
+* second short one.
+*/
+var CLIP_IDLE_WINDOW_RETRY_MS = 2e3;
+/**
+* Did this pass deliver the clip the row describes?
+*
+* Only a SHORTFALL is a defect. A decode that runs longer than the row is
+* routine — the row's stamps are whole seconds and its twins differ by up to
+* four — and calling it truncated would refuse a clip that is more complete
+* than the catalog knew.
+*/
+function judgeClipDuration(input) {
+	if (input.inProgress === true) return {
+		kind: "unknown",
+		reason: "clip-open"
+	};
+	if (input.decodedSeconds === null || !Number.isFinite(input.decodedSeconds)) return {
+		kind: "unknown",
+		reason: "duration-unmeasured"
+	};
+	if (!Number.isFinite(input.expectedMs) || input.expectedMs <= 0) return {
+		kind: "unknown",
+		reason: "row-window-unknown"
+	};
+	const expectedSeconds = input.expectedMs / 1e3;
+	const decodedSeconds = input.decodedSeconds;
+	const shortfallSeconds = expectedSeconds - decodedSeconds;
+	if (shortfallSeconds > 1.5) return {
+		kind: "short",
+		expectedSeconds,
+		decodedSeconds,
+		shortfallSeconds
+	};
+	return {
+		kind: "complete",
+		expectedSeconds,
+		decodedSeconds
+	};
+}
+//#endregion
 //#region src/clips/clip-thumb-queue.ts
 /**
 * The provider's OWN CoverPreview lane — two queues, one in flight per host.
@@ -149713,6 +149776,95 @@ function createClipService(deps) {
 			return refuseStill("camera-refused", reason);
 		}
 	};
+	/**
+	* ONE clip's bytes, on the short window, with the fetch PROVED (D568).
+	*
+	* Completion is an idle window because nothing on the wire ends a cmd 5
+	* transfer, and that window is short. What makes it safe is not the window,
+	* it is the decoded duration judged against the row that asked for it.
+	*/
+	const fetchVerifiedClipBytes = async (device, row, clipKey) => {
+		const deviceId = device.deviceId;
+		const api = await device.getApi();
+		const fetchPass = (idleTimeoutMs) => fetchClipBytes({
+			download: () => api.downloadRecordingDemuxed({
+				channel: device.channel,
+				...device.uid !== void 0 ? { uid: device.uid } : {},
+				fileName: row.subFileName,
+				idleTimeoutMs
+			}),
+			sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+		});
+		const judge = (pass) => judgeClipDuration({
+			expectedMs: row.endMs - row.startMs,
+			decodedSeconds: pass.stats.durationSeconds,
+			...row.inProgress === true ? { inProgress: true } : {}
+		});
+		const first = await fetchPass(300);
+		const firstVerdict = judge(first);
+		if (firstVerdict.kind === "unknown") {
+			const line = {
+				tags: { deviceId },
+				meta: {
+					clipKey,
+					branch: "completeness-unverified",
+					reason: firstVerdict.reason,
+					idleTimeoutMs: 300,
+					expectedMs: row.endMs - row.startMs,
+					decodedSeconds: first.stats.durationSeconds
+				}
+			};
+			if (firstVerdict.reason === "clip-open") deps.logger.debug("videoclips: an open clip cannot be checked for truncation", line);
+			else deps.logger.warn("videoclips: a clip fetch could not be checked for truncation", line);
+			return first;
+		}
+		if (firstVerdict.kind === "complete") return first;
+		deps.logger.warn("videoclips: a clip fetch came back truncated", {
+			tags: { deviceId },
+			meta: {
+				clipKey,
+				branch: "truncated-fetch",
+				idleTimeoutMs: 300,
+				expectedSeconds: firstVerdict.expectedSeconds,
+				decodedSeconds: firstVerdict.decodedSeconds,
+				shortfallSeconds: firstVerdict.shortfallSeconds,
+				bytes: first.annexB.byteLength,
+				keyframes: first.stats.keyframes
+			}
+		});
+		const retry = await fetchPass(CLIP_IDLE_WINDOW_RETRY_MS);
+		const keepRetry = (retry.stats.durationSeconds ?? 0) >= (first.stats.durationSeconds ?? 0);
+		const kept = keepRetry ? retry : first;
+		const verdict = keepRetry ? judge(retry) : firstVerdict;
+		const keptWindowMs = keepRetry ? CLIP_IDLE_WINDOW_RETRY_MS : 300;
+		if (verdict.kind === "short") {
+			deps.logger.warn("videoclips: a clip is still short after the long window", {
+				tags: { deviceId },
+				meta: {
+					clipKey,
+					branch: "truncated-after-retry",
+					idleTimeoutMs: keptWindowMs,
+					retriedOnMs: CLIP_IDLE_WINDOW_RETRY_MS,
+					expectedSeconds: verdict.expectedSeconds,
+					decodedSeconds: verdict.decodedSeconds,
+					shortfallSeconds: verdict.shortfallSeconds,
+					bytes: kept.annexB.byteLength
+				}
+			});
+			return kept;
+		}
+		deps.logger.info("videoclips: a truncated clip fetch landed whole on the long window", {
+			tags: { deviceId },
+			meta: {
+				clipKey,
+				branch: "truncation-recovered",
+				idleTimeoutMs: keptWindowMs,
+				decodedSeconds: verdict.kind === "complete" ? verdict.decodedSeconds : null,
+				bytes: kept.annexB.byteLength
+			}
+		});
+		return kept;
+	};
 	const prepareClip = async (deviceId, clipKey) => {
 		const ready = await media.pathIfPresent(deviceId, clipKey);
 		if (ready !== null) return ready;
@@ -149749,16 +149901,7 @@ function createClipService(deps) {
 			});
 			return null;
 		}
-		const fileName = row.subFileName;
-		const api = await device.getApi();
-		const downloaded = await fetchClipBytes({
-			download: () => api.downloadRecordingDemuxed({
-				channel: device.channel,
-				...device.uid !== void 0 ? { uid: device.uid } : {},
-				fileName
-			}),
-			sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms))
-		});
+		const downloaded = await fetchVerifiedClipBytes(device, row, clipKey);
 		const audio = decideClipAudio(downloaded.audio);
 		if (audio.kind === "silent") deps.logger.warn("videoclips: serving a clip with no sound", {
 			tags: { deviceId },
@@ -149838,7 +149981,8 @@ function createClipService(deps) {
 			await provider.listClips({
 				deviceId,
 				since: until - CLIP_CATALOG_REFRESH_WINDOW_MS,
-				until
+				until,
+				provider: REOLINK_ADDON_ID
 			});
 		},
 		hostBusy: (hostKey) => queue.busy(hostKey),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/addon-provider-reolink",
-  "version": "1.2.147",
+  "version": "1.2.148",
   "description": "Reolink camera device provider addon for CamStack — native Baichuan protocol",
   "keywords": [
     "camstack",