@camstack/types 1.2.156 → 1.2.158

package/dist/device/base-device-provider.d.ts

@@ -190,6 +190,28 @@ export declare abstract class BaseDeviceProvider<TConfig extends object = Record
     /** One-line operator-facing summary for `getStatus().error`, or
      *  `null` when every device restored. */
     protected restoreFailureSummary(): string | null;
+    /**
+     * A top-level persisted row with NO configuration is a leftover, not a
+     * device — quarantine it instead of dialling it.
+     *
+     * Device 614 was deleted, resurrected as a config-less shell by a write
+     * already in flight (D376), and then dialled at every single boot: eight
+     * `Failed to restore device — bounded retry scheduled` lines in one day,
+     * each one the same Zod refusal on `host` and `password`. The bound was
+     * real, but it is a bound PER PROCESS, and the runner restarts — so nothing
+     * about the row ever stopped costing attempts and log lines.
+     *
+     * No retry can add a configuration that is not there. The row is reported
+     * once, with its `deviceId`, and set aside.
+     *
+     * Top-level only: an accessory child legitimately carries an empty blob (it
+     * lives off its parent), and a hub-adopted child with an emptied blob is
+     * repaired by `healSavedConfig` from its parent instead. Providers that
+     * genuinely create configuration-free top-level devices turn this off.
+     */
+    protected readonly quarantineConfiglessTopLevelRestores: boolean;
+    private isUnrestorableShell;
+    private quarantineShell;
     private cancelRestoreRetries;
     private recordPermanentRestoreFailure;
     private scheduleRestoreRetries;

package/dist/index.js

@@ -37567,6 +37567,53 @@ var BaseDeviceProvider = class extends require_sleep.BaseAddon {
 		const ids = [...this._permanentRestoreFailures.keys()].join(", ");
 		return `${this._permanentRestoreFailures.size} device(s) permanently failed restore (deviceIds: ${ids}) — restart the ${this.providerName} provider to retry`;
 	}
+	/**
+	* A top-level persisted row with NO configuration is a leftover, not a
+	* device — quarantine it instead of dialling it.
+	*
+	* Device 614 was deleted, resurrected as a config-less shell by a write
+	* already in flight (D376), and then dialled at every single boot: eight
+	* `Failed to restore device — bounded retry scheduled` lines in one day,
+	* each one the same Zod refusal on `host` and `password`. The bound was
+	* real, but it is a bound PER PROCESS, and the runner restarts — so nothing
+	* about the row ever stopped costing attempts and log lines.
+	*
+	* No retry can add a configuration that is not there. The row is reported
+	* once, with its `deviceId`, and set aside.
+	*
+	* Top-level only: an accessory child legitimately carries an empty blob (it
+	* lives off its parent), and a hub-adopted child with an emptied blob is
+	* repaired by `healSavedConfig` from its parent instead. Providers that
+	* genuinely create configuration-free top-level devices turn this off.
+	*/
+	quarantineConfiglessTopLevelRestores = true;
+	isUnrestorableShell(saved) {
+		if (!this.quarantineConfiglessTopLevelRestores) return false;
+		if (saved.parentDeviceId !== null) return false;
+		const config = saved.config;
+		if (config === void 0) return false;
+		return Object.keys(config).length === 0;
+	}
+	quarantineShell(saved) {
+		this._permanentRestoreFailures.set(saved.id, {
+			deviceId: saved.id,
+			stableId: saved.stableId,
+			type: saved.type,
+			attempts: 0,
+			lastError: "persisted row has no configuration",
+			failedAt: Date.now()
+		});
+		this.ctx.logger.error("Persisted device row has NO configuration — quarantined: not restored, not retried. Remove it (deviceManager.removeDevice) or re-add the device.", {
+			tags: {
+				deviceId: saved.id,
+				stableId: saved.stableId
+			},
+			meta: {
+				type: saved.type,
+				provider: this.providerName
+			}
+		});
+	}
 	cancelRestoreRetries() {
 		this._restoreRetryScheduler?.cancel();
 		this._restoreRetryScheduler = null;
@@ -37751,6 +37798,10 @@ var BaseDeviceProvider = class extends require_sleep.BaseAddon {
 				});
 				return;
 			}
+			if (this.isUnrestorableShell(saved)) {
+				this.quarantineShell(saved);
+				return;
+			}
 			try {
 				await attemptRestore(saved);
 			} catch (err) {

package/dist/index.mjs

@@ -37559,6 +37559,53 @@ var BaseDeviceProvider = class extends BaseAddon {
 		const ids = [...this._permanentRestoreFailures.keys()].join(", ");
 		return `${this._permanentRestoreFailures.size} device(s) permanently failed restore (deviceIds: ${ids}) — restart the ${this.providerName} provider to retry`;
 	}
+	/**
+	* A top-level persisted row with NO configuration is a leftover, not a
+	* device — quarantine it instead of dialling it.
+	*
+	* Device 614 was deleted, resurrected as a config-less shell by a write
+	* already in flight (D376), and then dialled at every single boot: eight
+	* `Failed to restore device — bounded retry scheduled` lines in one day,
+	* each one the same Zod refusal on `host` and `password`. The bound was
+	* real, but it is a bound PER PROCESS, and the runner restarts — so nothing
+	* about the row ever stopped costing attempts and log lines.
+	*
+	* No retry can add a configuration that is not there. The row is reported
+	* once, with its `deviceId`, and set aside.
+	*
+	* Top-level only: an accessory child legitimately carries an empty blob (it
+	* lives off its parent), and a hub-adopted child with an emptied blob is
+	* repaired by `healSavedConfig` from its parent instead. Providers that
+	* genuinely create configuration-free top-level devices turn this off.
+	*/
+	quarantineConfiglessTopLevelRestores = true;
+	isUnrestorableShell(saved) {
+		if (!this.quarantineConfiglessTopLevelRestores) return false;
+		if (saved.parentDeviceId !== null) return false;
+		const config = saved.config;
+		if (config === void 0) return false;
+		return Object.keys(config).length === 0;
+	}
+	quarantineShell(saved) {
+		this._permanentRestoreFailures.set(saved.id, {
+			deviceId: saved.id,
+			stableId: saved.stableId,
+			type: saved.type,
+			attempts: 0,
+			lastError: "persisted row has no configuration",
+			failedAt: Date.now()
+		});
+		this.ctx.logger.error("Persisted device row has NO configuration — quarantined: not restored, not retried. Remove it (deviceManager.removeDevice) or re-add the device.", {
+			tags: {
+				deviceId: saved.id,
+				stableId: saved.stableId
+			},
+			meta: {
+				type: saved.type,
+				provider: this.providerName
+			}
+		});
+	}
 	cancelRestoreRetries() {
 		this._restoreRetryScheduler?.cancel();
 		this._restoreRetryScheduler = null;
@@ -37743,6 +37790,10 @@ var BaseDeviceProvider = class extends BaseAddon {
 				});
 				return;
 			}
+			if (this.isUnrestorableShell(saved)) {
+				this.quarantineShell(saved);
+				return;
+			}
 			try {
 				await attemptRestore(saved);
 			} catch (err) {

package/dist/types/detection.d.ts

@@ -9,6 +9,13 @@ export interface SpatialDetection {
     readonly mask?: Uint8Array;
     readonly maskWidth?: number;
     readonly maskHeight?: number;
+    /**
+     * Mirrored from {@link ObjectDetection.nativeRecovery} when this detection
+     * enters the tracker. The tracker's SPAWN gates (per-class score floor,
+     * person-over-animal dedup) are tuned for the coarse full-frame pass; a box
+     * measured at native resolution is not the thing they exist to kill.
+     */
+    readonly nativeRecovery?: NativeRecoveryEvidence;
 }
 export interface CropInput {
     readonly frame: FrameInput;
@@ -216,6 +223,37 @@ export interface DetectionBase {
     readonly labels: readonly ScoredLabel[];
     readonly track?: TrackInfo;
     readonly debug?: DetectionDebug;
+    /**
+     * Present when this box did NOT come from the full-frame pass but from a
+     * SECOND detector pass on a native-resolution crop of a motion region
+     * (`small-subject-recovery.ts` in the runner). See
+     * {@link NativeRecoveryEvidence}.
+     */
+    readonly nativeRecovery?: NativeRecoveryEvidence;
+}
+/**
+ * What a native-resolution second pass ALREADY measured about a box.
+ *
+ * The first-level detector sees a 4K frame at 320 px: a 100 px dog is 8 px and
+ * is not emitted. The runner's recovery pass re-runs THE SAME detector on a
+ * 640–800 px native square around the moving region and finds it at 0.82–0.91
+ * (`docs/benchmarks/pipeline-frame-model-eval.md`, case `miss-dog-615`). That
+ * pass is already a second look at better pixels — so every downstream gate
+ * whose job is to ask "did the coarse pass see a real thing?" has its answer,
+ * and re-deriving a THIRD, tighter crop of the same subject can only lose
+ * information (D377).
+ *
+ * Carried from the runner to post-analysis on the emitted frame result and
+ * mirrored onto the tracker's {@link SpatialDetection}. Plain data: no pixels,
+ * no handle — the crop it names is long gone, and its VERDICT is what travels.
+ */
+export interface NativeRecoveryEvidence {
+    /** Score the second pass measured, on the native crop, with the same model. */
+    readonly score: number;
+    /** Side of the native square the crop was cut from, in native pixels. */
+    readonly cropSidePx: number;
+    /** Side of the compressed view the model actually saw, in pixels. */
+    readonly viewPx: number;
 }
 /** Object detection (first-level person/vehicle/animal OR detail face/plate). */
 export interface ObjectDetection extends DetectionBase {

package/package.json

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