@camstack/system 1.2.73 → 1.2.75

package/dist/builtins/snapshot/index.js

@@ -788,6 +788,15 @@ function parseVerifiedSnapshotLink(input) {
 * answers inside it, short enough that a dead camera cannot stall the batch.
 */
 var LINK_MINT_DEADLINE_MS = 2500;
+/**
+* A links RPC is one Viewer-wide batch. Never let one slow camera hold every
+* fast camera behind its individual capture deadline: wait briefly for the
+* common fast path, then mint from the cache as it stands. Slow captures keep
+* running and their new generation is returned by the next 5 s poll.
+*/
+var LINK_BATCH_WAIT_MS = 750;
+/** Frames older than this are never represented as current by the Viewer. */
+var LINK_CURRENT_MAX_AGE_MS = 15e3;
 /** Default cache window for non-battery cams (seconds). 10s feels live. */
 var NON_BATTERY_DEFAULT_MAX_AGE_S = 10;
 /** Default cache window for battery cams (seconds). 1h ≈ "don't wake the cam unless asked". */
@@ -1033,8 +1042,10 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 	*
 	* So: note every target (creating a subscription, which `getSnapshotOverview`
 	* deliberately cannot), then join the ordinary non-forced capture path and
-	* wait a BOUNDED time for it. What comes back is the identity of the frame the
-	* link will actually serve.
+	* wait a BOUNDED time for it. The Viewer never presents a frame older than
+	* 15 seconds as current, so this path tightens a looser per-device cache
+	* window to that contract without using `force` (and its battery-wake
+	* semantics). What comes back is the identity of the frame the link serves.
 	*
 	* The bound matters more than its exact value. A cold fleet is paced by
 	* `MAX_CONCURRENT_GRABS`, so sixteen cameras cannot all capture at once and
@@ -1049,12 +1060,18 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 		const expMs = snapshotLinkExpiry(now, SNAPSHOT_LINK_TTL_MS);
 		const served = this.linkDataPlane !== null && secret !== null;
 		const prefix = this.linkRoutePrefix();
-		const rows = await Promise.all(input.targets.map(async (target) => {
+		const sleepingByDevice = /* @__PURE__ */ new Map();
+		const refreshes = input.targets.map(async (target) => {
+			const width = target.width === void 0 ? void 0 : snapSnapshotWidth(target.width);
+			this.subscriptions.note(target.deviceId, void 0, width, now);
+			const sleeping = await this.isSleepingBatteryDevice(target.deviceId);
+			sleepingByDevice.set(target.deviceId, sleeping);
+			if (!sleeping) await this.awaitFreshEnough(target.deviceId);
+		});
+		await raceForResult(Promise.allSettled(refreshes), LINK_BATCH_WAIT_MS);
+		const rows = input.targets.map((target) => {
 			const { deviceId } = target;
 			const width = target.width === void 0 ? void 0 : snapSnapshotWidth(target.width);
-			this.subscriptions.note(deviceId, void 0, width, now);
-			const sleeping = await this.isSleepingBatteryDevice(deviceId);
-			if (!sleeping) await this.awaitFreshEnough(deviceId);
 			const capturedAt = this.cache.latest(deviceId)?.ts ?? null;
 			const answeredAt = Date.now();
 			return {
@@ -1072,9 +1089,9 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 				expiresAt: served ? expMs : null,
 				width: width ?? null,
 				neverCaptured: capturedAt === null,
-				sleeping
+				sleeping: sleepingByDevice.get(deviceId) ?? false
 			};
-		}));
+		});
 		this.ctx.logger.debug("snapshot: minted links", { meta: {
 			targets: input.targets.length,
 			served,
@@ -1085,19 +1102,25 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 	/**
 	* Join the ordinary capture path for one device and wait, bounded, for it.
 	*
-	* Deliberately `getSnapshot` with `force: false` and nothing else: every gate
-	* that already owns this decision — the per-device max-age, the single flight,
-	* the grab pool, the sleeping-battery refusal — applies unchanged. A fresh
-	* cache returns immediately; a stale one starts the refresh. There is no
-	* second freshness policy here, which is the mistake D93 called out.
+	* Deliberately `getSnapshot` with `force: false`: the single flight, grab
+	* pool, and sleeping-battery refusal apply unchanged. The only override is
+	* the Viewer's 15-second currency contract and the link-mint wait bound.
 	*/
 	async awaitFreshEnough(deviceId) {
-		if (!(await raceForResult(this.getSnapshot({
+		const before = this.cache.latest(deviceId)?.ts ?? null;
+		const alreadyCurrent = before !== null && Date.now() - before <= LINK_CURRENT_MAX_AGE_MS;
+		await this.getSnapshot({
 			deviceId,
 			force: false
-		}).catch(() => null), LINK_MINT_DEADLINE_MS)).settled) this.ctx.logger.debug("snapshot: link mint gave up waiting; serving the older frame", {
+		}, 0, LINK_MINT_DEADLINE_MS, LINK_CURRENT_MAX_AGE_MS).catch(() => null);
+		const current = this.cache.latest(deviceId)?.ts ?? null;
+		if (alreadyCurrent || current !== null && (before === null || current > before)) return;
+		this.ctx.logger.debug("snapshot: link mint gave up waiting; serving the older frame", {
 			tags: { deviceId },
-			meta: { deadlineMs: LINK_MINT_DEADLINE_MS }
+			meta: {
+				deadlineMs: LINK_MINT_DEADLINE_MS,
+				previousCapturedAt: before
+			}
 		});
 	}
 	/** True only for a BATTERY device that is currently asleep. Kept as one
@@ -1346,7 +1369,7 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 			})]
 		}] });
 	}
-	async getSnapshot(input, warmAheadMs = 0) {
+	async getSnapshot(input, warmAheadMs = 0, minimumCaptureWaitMs = 0, maximumCacheAgeMs = Number.POSITIVE_INFINITY) {
 		const { deviceId } = input;
 		const force = input.force === true;
 		const meta = await this.lookupDeviceMeta(deviceId);
@@ -1365,7 +1388,7 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 			meta: { stream: effectiveStreamId ?? "auto" }
 		});
 		const hit = this.cache.get(deviceId, effectiveStreamId);
-		const effectiveMaxAgeMs = Math.max(0, effectiveMaxAgeS(prefs, isBatteryDevice) * 1e3 - warmAheadMs);
+		const effectiveMaxAgeMs = Math.min(maximumCacheAgeMs, Math.max(0, effectiveMaxAgeS(prefs, isBatteryDevice) * 1e3 - warmAheadMs));
 		const decision = decideSnapshotServe({
 			now,
 			cachedAt: hit?.ts ?? null,
@@ -1402,7 +1425,7 @@ var SnapshotAddon = class SnapshotAddon extends require_dist.BaseAddon {
 			log
 		}));
 		flight.catch(() => void 0);
-		const raced = await raceForResult(flight, decision.waitMs);
+		const raced = await raceForResult(flight, Math.max(decision.waitMs, minimumCaptureWaitMs));
 		if (raced.settled) return this.resolveOutcome(raced.value, deviceId, hit, log);
 		if (decision.staleFallback && hit) {
 			if (prefs.snapshotDebug) log.debug("snapshot: SWR — returning stale frame; refresh continues in background", {

package/dist/builtins/snapshot/index.mjs

@@ -783,6 +783,15 @@ function parseVerifiedSnapshotLink(input) {
 * answers inside it, short enough that a dead camera cannot stall the batch.
 */
 var LINK_MINT_DEADLINE_MS = 2500;
+/**
+* A links RPC is one Viewer-wide batch. Never let one slow camera hold every
+* fast camera behind its individual capture deadline: wait briefly for the
+* common fast path, then mint from the cache as it stands. Slow captures keep
+* running and their new generation is returned by the next 5 s poll.
+*/
+var LINK_BATCH_WAIT_MS = 750;
+/** Frames older than this are never represented as current by the Viewer. */
+var LINK_CURRENT_MAX_AGE_MS = 15e3;
 /** Default cache window for non-battery cams (seconds). 10s feels live. */
 var NON_BATTERY_DEFAULT_MAX_AGE_S = 10;
 /** Default cache window for battery cams (seconds). 1h ≈ "don't wake the cam unless asked". */
@@ -1028,8 +1037,10 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 	*
 	* So: note every target (creating a subscription, which `getSnapshotOverview`
 	* deliberately cannot), then join the ordinary non-forced capture path and
-	* wait a BOUNDED time for it. What comes back is the identity of the frame the
-	* link will actually serve.
+	* wait a BOUNDED time for it. The Viewer never presents a frame older than
+	* 15 seconds as current, so this path tightens a looser per-device cache
+	* window to that contract without using `force` (and its battery-wake
+	* semantics). What comes back is the identity of the frame the link serves.
 	*
 	* The bound matters more than its exact value. A cold fleet is paced by
 	* `MAX_CONCURRENT_GRABS`, so sixteen cameras cannot all capture at once and
@@ -1044,12 +1055,18 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 		const expMs = snapshotLinkExpiry(now, SNAPSHOT_LINK_TTL_MS);
 		const served = this.linkDataPlane !== null && secret !== null;
 		const prefix = this.linkRoutePrefix();
-		const rows = await Promise.all(input.targets.map(async (target) => {
+		const sleepingByDevice = /* @__PURE__ */ new Map();
+		const refreshes = input.targets.map(async (target) => {
+			const width = target.width === void 0 ? void 0 : snapSnapshotWidth(target.width);
+			this.subscriptions.note(target.deviceId, void 0, width, now);
+			const sleeping = await this.isSleepingBatteryDevice(target.deviceId);
+			sleepingByDevice.set(target.deviceId, sleeping);
+			if (!sleeping) await this.awaitFreshEnough(target.deviceId);
+		});
+		await raceForResult(Promise.allSettled(refreshes), LINK_BATCH_WAIT_MS);
+		const rows = input.targets.map((target) => {
 			const { deviceId } = target;
 			const width = target.width === void 0 ? void 0 : snapSnapshotWidth(target.width);
-			this.subscriptions.note(deviceId, void 0, width, now);
-			const sleeping = await this.isSleepingBatteryDevice(deviceId);
-			if (!sleeping) await this.awaitFreshEnough(deviceId);
 			const capturedAt = this.cache.latest(deviceId)?.ts ?? null;
 			const answeredAt = Date.now();
 			return {
@@ -1067,9 +1084,9 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 				expiresAt: served ? expMs : null,
 				width: width ?? null,
 				neverCaptured: capturedAt === null,
-				sleeping
+				sleeping: sleepingByDevice.get(deviceId) ?? false
 			};
-		}));
+		});
 		this.ctx.logger.debug("snapshot: minted links", { meta: {
 			targets: input.targets.length,
 			served,
@@ -1080,19 +1097,25 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 	/**
 	* Join the ordinary capture path for one device and wait, bounded, for it.
 	*
-	* Deliberately `getSnapshot` with `force: false` and nothing else: every gate
-	* that already owns this decision — the per-device max-age, the single flight,
-	* the grab pool, the sleeping-battery refusal — applies unchanged. A fresh
-	* cache returns immediately; a stale one starts the refresh. There is no
-	* second freshness policy here, which is the mistake D93 called out.
+	* Deliberately `getSnapshot` with `force: false`: the single flight, grab
+	* pool, and sleeping-battery refusal apply unchanged. The only override is
+	* the Viewer's 15-second currency contract and the link-mint wait bound.
 	*/
 	async awaitFreshEnough(deviceId) {
-		if (!(await raceForResult(this.getSnapshot({
+		const before = this.cache.latest(deviceId)?.ts ?? null;
+		const alreadyCurrent = before !== null && Date.now() - before <= LINK_CURRENT_MAX_AGE_MS;
+		await this.getSnapshot({
 			deviceId,
 			force: false
-		}).catch(() => null), LINK_MINT_DEADLINE_MS)).settled) this.ctx.logger.debug("snapshot: link mint gave up waiting; serving the older frame", {
+		}, 0, LINK_MINT_DEADLINE_MS, LINK_CURRENT_MAX_AGE_MS).catch(() => null);
+		const current = this.cache.latest(deviceId)?.ts ?? null;
+		if (alreadyCurrent || current !== null && (before === null || current > before)) return;
+		this.ctx.logger.debug("snapshot: link mint gave up waiting; serving the older frame", {
 			tags: { deviceId },
-			meta: { deadlineMs: LINK_MINT_DEADLINE_MS }
+			meta: {
+				deadlineMs: LINK_MINT_DEADLINE_MS,
+				previousCapturedAt: before
+			}
 		});
 	}
 	/** True only for a BATTERY device that is currently asleep. Kept as one
@@ -1341,7 +1364,7 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 			})]
 		}] });
 	}
-	async getSnapshot(input, warmAheadMs = 0) {
+	async getSnapshot(input, warmAheadMs = 0, minimumCaptureWaitMs = 0, maximumCacheAgeMs = Number.POSITIVE_INFINITY) {
 		const { deviceId } = input;
 		const force = input.force === true;
 		const meta = await this.lookupDeviceMeta(deviceId);
@@ -1360,7 +1383,7 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 			meta: { stream: effectiveStreamId ?? "auto" }
 		});
 		const hit = this.cache.get(deviceId, effectiveStreamId);
-		const effectiveMaxAgeMs = Math.max(0, effectiveMaxAgeS(prefs, isBatteryDevice) * 1e3 - warmAheadMs);
+		const effectiveMaxAgeMs = Math.min(maximumCacheAgeMs, Math.max(0, effectiveMaxAgeS(prefs, isBatteryDevice) * 1e3 - warmAheadMs));
 		const decision = decideSnapshotServe({
 			now,
 			cachedAt: hit?.ts ?? null,
@@ -1397,7 +1420,7 @@ var SnapshotAddon = class SnapshotAddon extends BaseAddon {
 			log
 		}));
 		flight.catch(() => void 0);
-		const raced = await raceForResult(flight, decision.waitMs);
+		const raced = await raceForResult(flight, Math.max(decision.waitMs, minimumCaptureWaitMs));
 		if (raced.settled) return this.resolveOutcome(raced.value, deviceId, hit, log);
 		if (decision.staleFallback && hit) {
 			if (prefs.snapshotDebug) log.debug("snapshot: SWR — returning stale frame; refresh continues in background", {

package/dist/builtins/snapshot/snapshot.addon.d.ts

@@ -146,8 +146,10 @@ export declare class SnapshotAddon extends BaseAddon<SnapshotAddonConfig> {
      *
      * So: note every target (creating a subscription, which `getSnapshotOverview`
      * deliberately cannot), then join the ordinary non-forced capture path and
-     * wait a BOUNDED time for it. What comes back is the identity of the frame the
-     * link will actually serve.
+     * wait a BOUNDED time for it. The Viewer never presents a frame older than
+     * 15 seconds as current, so this path tightens a looser per-device cache
+     * window to that contract without using `force` (and its battery-wake
+     * semantics). What comes back is the identity of the frame the link serves.
      *
      * The bound matters more than its exact value. A cold fleet is paced by
      * `MAX_CONCURRENT_GRABS`, so sixteen cameras cannot all capture at once and
@@ -160,11 +162,9 @@ export declare class SnapshotAddon extends BaseAddon<SnapshotAddonConfig> {
     /**
      * Join the ordinary capture path for one device and wait, bounded, for it.
      *
-     * Deliberately `getSnapshot` with `force: false` and nothing else: every gate
-     * that already owns this decision — the per-device max-age, the single flight,
-     * the grab pool, the sleeping-battery refusal — applies unchanged. A fresh
-     * cache returns immediately; a stale one starts the refresh. There is no
-     * second freshness policy here, which is the mistake D93 called out.
+     * Deliberately `getSnapshot` with `force: false`: the single flight, grab
+     * pool, and sleeping-battery refusal apply unchanged. The only override is
+     * the Viewer's 15-second currency contract and the link-mint wait bound.
      */
     private awaitFreshEnough;
     /** True only for a BATTERY device that is currently asleep. Kept as one

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/system",
-  "version": "1.2.73",
+  "version": "1.2.75",
   "description": "Core addon for CamStack — builtins, pipeline, process management, auth, logging, events",
   "keywords": [
     "camstack",