@camstack/types 1.2.59 → 1.2.60

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

@@ -90,24 +90,28 @@ export declare const snapshotCapability: {
          *
          * `getSnapshotOverview` is cache-only by contract: it answers from whatever
          * the wrapper happens to hold and never captures. Under D93 the client
-         * versions its image URL on that answer, and an image REQUEST is what enrols
-         * a camera in the keep-warm loop. Both of those are satisfiable by the
-         * client's own image cache — `expo-image` is URL-keyed and never revalidates
-         * — so a URL painted in a previous session comes off disk with no network,
-         * no enrolment, and nothing warming. Measured on the live hub: reopening
-         * after two minutes idle painted 15 of 16 tiles at **168 s old** with zero
-         * HTTP requests, and the fleet only recovered because a later poll happened
-         * to observe a different identity.
+         * versions its image URL on that answer, and an image REQUEST was the only
+         * demand signal. Both of those are satisfiable by the client's own image
+         * cache — `expo-image` is URL-keyed and never revalidates — so a URL painted
+         * in a previous session comes off disk with no network, no demand, and no
+         * capture. Measured on the live hub: reopening after two minutes idle
+         * painted 15 of 16 tiles at **168 s old** with zero HTTP requests, and the
+         * fleet only recovered because a later poll happened to observe a different
+         * identity.
          *
          * ## The two properties that fix it
          *
          * **It is an RPC, so no client cache can answer it.** The demand signal
-         * always reaches the wrapper. This method therefore MAY create keep-warm
-         * subscriptions, where `getSnapshotOverview` must never (D93) — the
-         * distinction is not "one is newer" but that the overview poll is app-wide
-         * (a creating overview would warm every camera on the install) while this is
-         * called by a rendered surface naming the tiles it is actually painting, at
-         * the width it is painting them.
+         * always reaches the wrapper. This method therefore CAPTURES, where
+         * `getSnapshotOverview` must never (D93) — the distinction is not "one is
+         * newer" but that the overview poll is app-wide (a capturing overview would
+         * dial every camera on the install) while this is called by a rendered
+         * surface naming the tiles it is actually painting, at the width it is
+         * painting them.
+         *
+         * Since 2026-08-11 this is the ONLY thing that refreshes a snapshot: the
+         * server-side keep-warm loop was removed (operator directive — on-demand,
+         * always), so a camera nobody is looking at costs nothing at all.
          *
          * **It waits, briefly and boundedly, for the capture it triggered.** The
          * returned `capturedAt` is the frame the link will serve, not the frame the

package/dist/device/declared-device.d.ts

@@ -193,6 +193,18 @@ export declare class DeclaredDevices {
      */
     private ensureIntegration;
     private readIndex;
+    /**
+     * Devices this kernel already has CONSTRUCTED, by stableId.
+     *
+     * Distinct from {@link readIndex}, and the distinction is the bug: the index
+     * is persisted rows, this is live objects. A row without an object must be
+     * adopted; an object must be left exactly as it is.
+     *
+     * Failure is non-fatal and deliberately so — an empty map degrades to the
+     * previous behaviour (attempt the adopt) rather than skipping a device that
+     * genuinely needs bringing up.
+     */
+    private readLiveByStableId;
     /**
      * One declaration: adopt what exists, create what does not.
      *

package/dist/index.js

@@ -17815,24 +17815,28 @@ var snapshotCapability = {
 		*
 		* `getSnapshotOverview` is cache-only by contract: it answers from whatever
 		* the wrapper happens to hold and never captures. Under D93 the client
-		* versions its image URL on that answer, and an image REQUEST is what enrols
-		* a camera in the keep-warm loop. Both of those are satisfiable by the
-		* client's own image cache — `expo-image` is URL-keyed and never revalidates
-		* — so a URL painted in a previous session comes off disk with no network,
-		* no enrolment, and nothing warming. Measured on the live hub: reopening
-		* after two minutes idle painted 15 of 16 tiles at **168 s old** with zero
-		* HTTP requests, and the fleet only recovered because a later poll happened
-		* to observe a different identity.
+		* versions its image URL on that answer, and an image REQUEST was the only
+		* demand signal. Both of those are satisfiable by the client's own image
+		* cache — `expo-image` is URL-keyed and never revalidates — so a URL painted
+		* in a previous session comes off disk with no network, no demand, and no
+		* capture. Measured on the live hub: reopening after two minutes idle
+		* painted 15 of 16 tiles at **168 s old** with zero HTTP requests, and the
+		* fleet only recovered because a later poll happened to observe a different
+		* identity.
 		*
 		* ## The two properties that fix it
 		*
 		* **It is an RPC, so no client cache can answer it.** The demand signal
-		* always reaches the wrapper. This method therefore MAY create keep-warm
-		* subscriptions, where `getSnapshotOverview` must never (D93) — the
-		* distinction is not "one is newer" but that the overview poll is app-wide
-		* (a creating overview would warm every camera on the install) while this is
-		* called by a rendered surface naming the tiles it is actually painting, at
-		* the width it is painting them.
+		* always reaches the wrapper. This method therefore CAPTURES, where
+		* `getSnapshotOverview` must never (D93) — the distinction is not "one is
+		* newer" but that the overview poll is app-wide (a capturing overview would
+		* dial every camera on the install) while this is called by a rendered
+		* surface naming the tiles it is actually painting, at the width it is
+		* painting them.
+		*
+		* Since 2026-08-11 this is the ONLY thing that refreshes a snapshot: the
+		* server-side keep-warm loop was removed (operator directive — on-demand,
+		* always), so a camera nobody is looking at costs nothing at all.
 		*
 		* **It waits, briefly and boundedly, for the capture it triggered.** The
 		* returned `capturedAt` is the frame the link will serve, not the frame the
@@ -29148,9 +29152,10 @@ var DeclaredDevices = class {
 		}
 		const integrationId = spec.integrationId ?? await this.ensureIntegration(spec.integrationName);
 		const index = await this.readIndex();
+		const live = await this.readLiveByStableId();
 		const outcomes = [];
 		for (const declaration of spec.devices) {
-			const outcome = await this.applyDeclaration(declaration, integrationId, index);
+			const outcome = await this.applyDeclaration(declaration, integrationId, index, live);
 			if (outcome !== null) outcomes.push(outcome);
 		}
 		return {
@@ -29196,6 +29201,26 @@ var DeclaredDevices = class {
 		return new Map(rows.map((row) => [row.stableId, row]));
 	}
 	/**
+	* Devices this kernel already has CONSTRUCTED, by stableId.
+	*
+	* Distinct from {@link readIndex}, and the distinction is the bug: the index
+	* is persisted rows, this is live objects. A row without an object must be
+	* adopted; an object must be left exactly as it is.
+	*
+	* Failure is non-fatal and deliberately so — an empty map degrades to the
+	* previous behaviour (attempt the adopt) rather than skipping a device that
+	* genuinely needs bringing up.
+	*/
+	async readLiveByStableId() {
+		try {
+			const devices = await this.ports.devices.getAll();
+			return new Map(devices.map((device) => [device.stableId, device]));
+		} catch (err) {
+			this.ports.logger.warn("could not read live devices — falling back to adopt-by-row", { meta: { error: err instanceof Error ? err.message : String(err) } });
+			return /* @__PURE__ */ new Map();
+		}
+	}
+	/**
 	* One declaration: adopt what exists, create what does not.
 	*
 	* The create branch is the destructive one — it seeds `initialMeta`, and
@@ -29204,8 +29229,15 @@ var DeclaredDevices = class {
 	* the declared name over the operator's rename. D49: that branch needs a
 	* second read to agree.
 	*/
-	async applyDeclaration(declaration, integrationId, index) {
+	async applyDeclaration(declaration, integrationId, index, live) {
 		try {
+			const alreadyLive = live.get(declaration.stableId);
+			if (alreadyLive !== void 0) return {
+				stableId: declaration.stableId,
+				deviceId: alreadyLive.id,
+				device: alreadyLive,
+				created: false
+			};
 			let existing = index.get(declaration.stableId);
 			if (existing === void 0) {
 				existing = (await this.readIndex()).get(declaration.stableId);

package/dist/index.mjs

@@ -17814,24 +17814,28 @@ var snapshotCapability = {
 		*
 		* `getSnapshotOverview` is cache-only by contract: it answers from whatever
 		* the wrapper happens to hold and never captures. Under D93 the client
-		* versions its image URL on that answer, and an image REQUEST is what enrols
-		* a camera in the keep-warm loop. Both of those are satisfiable by the
-		* client's own image cache — `expo-image` is URL-keyed and never revalidates
-		* — so a URL painted in a previous session comes off disk with no network,
-		* no enrolment, and nothing warming. Measured on the live hub: reopening
-		* after two minutes idle painted 15 of 16 tiles at **168 s old** with zero
-		* HTTP requests, and the fleet only recovered because a later poll happened
-		* to observe a different identity.
+		* versions its image URL on that answer, and an image REQUEST was the only
+		* demand signal. Both of those are satisfiable by the client's own image
+		* cache — `expo-image` is URL-keyed and never revalidates — so a URL painted
+		* in a previous session comes off disk with no network, no demand, and no
+		* capture. Measured on the live hub: reopening after two minutes idle
+		* painted 15 of 16 tiles at **168 s old** with zero HTTP requests, and the
+		* fleet only recovered because a later poll happened to observe a different
+		* identity.
 		*
 		* ## The two properties that fix it
 		*
 		* **It is an RPC, so no client cache can answer it.** The demand signal
-		* always reaches the wrapper. This method therefore MAY create keep-warm
-		* subscriptions, where `getSnapshotOverview` must never (D93) — the
-		* distinction is not "one is newer" but that the overview poll is app-wide
-		* (a creating overview would warm every camera on the install) while this is
-		* called by a rendered surface naming the tiles it is actually painting, at
-		* the width it is painting them.
+		* always reaches the wrapper. This method therefore CAPTURES, where
+		* `getSnapshotOverview` must never (D93) — the distinction is not "one is
+		* newer" but that the overview poll is app-wide (a capturing overview would
+		* dial every camera on the install) while this is called by a rendered
+		* surface naming the tiles it is actually painting, at the width it is
+		* painting them.
+		*
+		* Since 2026-08-11 this is the ONLY thing that refreshes a snapshot: the
+		* server-side keep-warm loop was removed (operator directive — on-demand,
+		* always), so a camera nobody is looking at costs nothing at all.
 		*
 		* **It waits, briefly and boundedly, for the capture it triggered.** The
 		* returned `capturedAt` is the frame the link will serve, not the frame the
@@ -29147,9 +29151,10 @@ var DeclaredDevices = class {
 		}
 		const integrationId = spec.integrationId ?? await this.ensureIntegration(spec.integrationName);
 		const index = await this.readIndex();
+		const live = await this.readLiveByStableId();
 		const outcomes = [];
 		for (const declaration of spec.devices) {
-			const outcome = await this.applyDeclaration(declaration, integrationId, index);
+			const outcome = await this.applyDeclaration(declaration, integrationId, index, live);
 			if (outcome !== null) outcomes.push(outcome);
 		}
 		return {
@@ -29195,6 +29200,26 @@ var DeclaredDevices = class {
 		return new Map(rows.map((row) => [row.stableId, row]));
 	}
 	/**
+	* Devices this kernel already has CONSTRUCTED, by stableId.
+	*
+	* Distinct from {@link readIndex}, and the distinction is the bug: the index
+	* is persisted rows, this is live objects. A row without an object must be
+	* adopted; an object must be left exactly as it is.
+	*
+	* Failure is non-fatal and deliberately so — an empty map degrades to the
+	* previous behaviour (attempt the adopt) rather than skipping a device that
+	* genuinely needs bringing up.
+	*/
+	async readLiveByStableId() {
+		try {
+			const devices = await this.ports.devices.getAll();
+			return new Map(devices.map((device) => [device.stableId, device]));
+		} catch (err) {
+			this.ports.logger.warn("could not read live devices — falling back to adopt-by-row", { meta: { error: err instanceof Error ? err.message : String(err) } });
+			return /* @__PURE__ */ new Map();
+		}
+	}
+	/**
 	* One declaration: adopt what exists, create what does not.
 	*
 	* The create branch is the destructive one — it seeds `initialMeta`, and
@@ -29203,8 +29228,15 @@ var DeclaredDevices = class {
 	* the declared name over the operator's rename. D49: that branch needs a
 	* second read to agree.
 	*/
-	async applyDeclaration(declaration, integrationId, index) {
+	async applyDeclaration(declaration, integrationId, index, live) {
 		try {
+			const alreadyLive = live.get(declaration.stableId);
+			if (alreadyLive !== void 0) return {
+				stableId: declaration.stableId,
+				deviceId: alreadyLive.id,
+				device: alreadyLive,
+				created: false
+			};
 			let existing = index.get(declaration.stableId);
 			if (existing === void 0) {
 				existing = (await this.readIndex()).get(declaration.stableId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/types",
-  "version": "1.2.59",
+  "version": "1.2.60",
   "description": "Shared types, interfaces, and model catalogs for the CamStack detection ecosystem",
   "keywords": [
     "camstack",