@camstack/system 1.2.73 → 1.2.74

package/dist/builtins/snapshot/index.js

@@ -788,6 +788,8 @@ function parseVerifiedSnapshotLink(input) {
 * answers inside it, short enough that a dead camera cannot stall the batch.
 */
 var LINK_MINT_DEADLINE_MS = 2500;
+/** 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 +1035,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
@@ -1085,19 +1089,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 +1356,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 +1375,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 +1412,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,8 @@ function parseVerifiedSnapshotLink(input) {
 * answers inside it, short enough that a dead camera cannot stall the batch.
 */
 var LINK_MINT_DEADLINE_MS = 2500;
+/** 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 +1030,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
@@ -1080,19 +1084,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 +1351,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 +1370,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 +1407,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.74",
   "description": "Core addon for CamStack — builtins, pipeline, process management, auth, logging, events",
   "keywords": [
     "camstack",