@camstack/types 1.2.141 → 1.2.143

package/dist/addon.js

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_event_category = require("./event-category-BaEgqJNv.js");
-const require_sleep = require("./sleep-BwGJ_wL_.js");
+const require_sleep = require("./sleep-jdpPltQH.js");
 const require_err_msg = require("./err-msg-COpsHMw2.js");
 //#region src/generated/cap-input-defaults.ts
 /**

package/dist/addon.mjs

@@ -1,5 +1,5 @@
 import { t as EventCategory } from "./event-category-BZL-fdNj.mjs";
-import { B as ReadinessRegistry, E as adminUiCapability, L as nodePin, R as readNodePin, St as emitReadiness, T as DeviceType, V as ReadinessTimeoutError, W as scopeKey, _t as DisposerChain, a as asJsonObject, b as deviceOpsCapability, d as BOOT_RECOVERY_BACKOFF_MS, f as DEVICE_SCOPED_CAPS, gt as DATAPLANE_SECRET_HEADER, h as createEventBusSliceSource, j as expandCapMethods, m as createDeviceProxy, p as isDeviceScopedCap, s as asString, t as sleep, u as parseJsonUnknown, vt as BaseAddon, x as viewerUiCapability, yt as normalizeAddonInitResult } from "./sleep-C1mz-ocE.mjs";
+import { B as ReadinessRegistry, E as adminUiCapability, L as nodePin, R as readNodePin, St as emitReadiness, T as DeviceType, V as ReadinessTimeoutError, W as scopeKey, _t as DisposerChain, a as asJsonObject, b as deviceOpsCapability, d as BOOT_RECOVERY_BACKOFF_MS, f as DEVICE_SCOPED_CAPS, gt as DATAPLANE_SECRET_HEADER, h as createEventBusSliceSource, j as expandCapMethods, m as createDeviceProxy, p as isDeviceScopedCap, s as asString, t as sleep, u as parseJsonUnknown, vt as BaseAddon, x as viewerUiCapability, yt as normalizeAddonInitResult } from "./sleep-B195W080.mjs";
 import { t as errMsg } from "./err-msg-IQTHeDzc.mjs";
 //#region src/generated/cap-input-defaults.ts
 /**

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

@@ -111,6 +111,82 @@ declare const LocationStatSchema: z.ZodObject<{
     fileCount: z.ZodNumber;
     present: z.ZodBoolean;
 }, z.core.$strip>;
+/** Lifecycle of a backup run. Terminal states: succeeded / failed / cancelled. */
+declare const BackupRunStateSchema: z.ZodEnum<{
+    failed: "failed";
+    running: "running";
+    queued: "queued";
+    cancelled: "cancelled";
+    succeeded: "succeeded";
+}>;
+/**
+ * Where a running backup currently is. `queued` before it starts,
+ * `building` while the tar.gz is being staged, `uploading` during the
+ * per-destination fan-out, `done` once terminal.
+ */
+declare const BackupRunPhaseSchema: z.ZodEnum<{
+    queued: "queued";
+    done: "done";
+    building: "building";
+    uploading: "uploading";
+}>;
+/**
+ * Observable state of one backup run — readable WHILE it runs via
+ * `backup.listRuns`. This is what makes the execution queue and
+ * `backup.cancel` usable: the 2026-09-04 incident (two concurrent
+ * multi-GB builds, staging 5.1 GB → 18 GB, load 62) was only
+ * diagnosable with `du` because nothing reported that runs existed or
+ * how large the staged archive had grown.
+ */
+declare const BackupRunSchema: z.ZodObject<{
+    id: z.ZodString;
+    state: z.ZodEnum<{
+        failed: "failed";
+        running: "running";
+        queued: "queued";
+        cancelled: "cancelled";
+        succeeded: "succeeded";
+    }>;
+    phase: z.ZodEnum<{
+        queued: "queued";
+        done: "done";
+        building: "building";
+        uploading: "uploading";
+    }>;
+    destinationIds: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+    label: z.ZodOptional<z.ZodString>;
+    requestedAt: z.ZodNumber;
+    startedAt: z.ZodOptional<z.ZodNumber>;
+    finishedAt: z.ZodOptional<z.ZodNumber>;
+    stagedBytes: z.ZodNumber;
+    archiveSizeBytes: z.ZodOptional<z.ZodNumber>;
+    uploadedBytes: z.ZodNumber;
+    completedDestinationIds: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+    failedDestinationIds: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+    error: z.ZodOptional<z.ZodString>;
+    queuePosition: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * Result of `backup.trigger`. The call still resolves when the run
+ * terminates (compat with schedule-driven runs and the admin UI), but
+ * it now names the run and says whether it had to WAIT: a trigger that
+ * arrives while another run is in flight is enqueued (or joined onto
+ * an identical already-queued run), never started concurrently.
+ */
+declare const BackupTriggerResultSchema: z.ZodObject<{
+    runId: z.ZodString;
+    queued: z.ZodBoolean;
+    joined: z.ZodBoolean;
+    cancelled: z.ZodBoolean;
+    entries: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        destinationId: z.ZodOptional<z.ZodString>;
+        label: z.ZodOptional<z.ZodString>;
+        createdAt: z.ZodNumber;
+        sizeBytes: z.ZodNumber;
+        locations: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
 /**
  * A backup schedule — the N:M "entry" that binds one cron cadence to a
  * SET of destination locations. Supersedes the per-location cron on
@@ -176,20 +252,82 @@ export declare const backupCapability: {
          * Trigger a backup. Without `destinations` the orchestrator fans
          * out to every destination flagged as enabled in the routing
          * config; with it, only the listed addons receive the archive.
+         *
+         * At most ONE backup run executes at a time — the source tree and
+         * the staging disk are shared by every run, so a second trigger
+         * while one is in flight is enqueued (or joined onto an identical
+         * queued run) and the result says so. See D342.
          */
         readonly trigger: import("./capability-definition.js").CapabilityMethodSchema<z.ZodOptional<z.ZodObject<{
             destinations: z.ZodOptional<z.ZodArray<z.ZodString>>;
             locations: z.ZodOptional<z.ZodArray<z.ZodString>>;
             label: z.ZodOptional<z.ZodString>;
             retentionCount: z.ZodOptional<z.ZodNumber>;
-        }, z.core.$strip>>, z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        }, z.core.$strip>>, z.ZodObject<{
+            runId: z.ZodString;
+            queued: z.ZodBoolean;
+            joined: z.ZodBoolean;
+            cancelled: z.ZodBoolean;
+            entries: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                destinationId: z.ZodOptional<z.ZodString>;
+                label: z.ZodOptional<z.ZodString>;
+                createdAt: z.ZodNumber;
+                sizeBytes: z.ZodNumber;
+                locations: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>, "mutation">;
+        /**
+         * Every run the orchestrator knows about, in EXECUTION order: the
+         * running run first, then queued runs in the exact order they will
+         * execute (each with `queuePosition`, 1 = next), then the bounded
+         * finished history newest-first. Only one run executes at a time
+         * (D342) — the queued section IS the line. Each run carries live
+         * phase + byte counters so a runaway build is visible in seconds,
+         * not via `du`.
+         */
+        readonly listRuns: import("./capability-definition.js").CapabilityMethodSchema<z.ZodVoid, z.ZodReadonly<z.ZodArray<z.ZodObject<{
             id: z.ZodString;
-            destinationId: z.ZodOptional<z.ZodString>;
+            state: z.ZodEnum<{
+                failed: "failed";
+                running: "running";
+                queued: "queued";
+                cancelled: "cancelled";
+                succeeded: "succeeded";
+            }>;
+            phase: z.ZodEnum<{
+                queued: "queued";
+                done: "done";
+                building: "building";
+                uploading: "uploading";
+            }>;
+            destinationIds: z.ZodReadonly<z.ZodArray<z.ZodString>>;
             label: z.ZodOptional<z.ZodString>;
-            createdAt: z.ZodNumber;
-            sizeBytes: z.ZodNumber;
-            locations: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        }, z.core.$strip>>>, "mutation">;
+            requestedAt: z.ZodNumber;
+            startedAt: z.ZodOptional<z.ZodNumber>;
+            finishedAt: z.ZodOptional<z.ZodNumber>;
+            stagedBytes: z.ZodNumber;
+            archiveSizeBytes: z.ZodOptional<z.ZodNumber>;
+            uploadedBytes: z.ZodNumber;
+            completedDestinationIds: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+            failedDestinationIds: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+            error: z.ZodOptional<z.ZodString>;
+            queuePosition: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>>, import("./capability-definition.js").CapabilityMethodKind>;
+        /**
+         * Stop a backup run. Mirrors `storage-migration.cancel` semantics:
+         * id in, `{ cancelled }` out — `false` when the run is unknown or
+         * already terminal. A QUEUED run is removed before it ever starts;
+         * the RUNNING run has its tar/upload stream actually aborted, the
+         * half-written staging archive is deleted, and the in-flight
+         * destination upload is aborted server-side (partial discarded).
+         * Destinations that already completed keep their archive.
+         */
+        readonly cancel: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            runId: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            cancelled: z.ZodBoolean;
+        }, z.core.$strip>, "mutation">;
         /** Union of every destination's archives, each tagged with `destinationId`. */
         readonly list: import("./capability-definition.js").CapabilityMethodSchema<z.ZodVoid, z.ZodReadonly<z.ZodArray<z.ZodObject<{
             id: z.ZodString;
@@ -337,4 +475,8 @@ export declare const backupCapability: {
     };
 };
 export type IBackupProvider = InferProvider<typeof backupCapability>;
-export { ArchiveEntrySchema, ArchiveManifestSchema, BackupArchiveEntrySchema, BackupDestinationInfoSchema, BackupEntrySchema, BackupScheduleSchema, BackupSubDestinationInfoSchema, LocationStatSchema, };
+export { ArchiveEntrySchema, ArchiveManifestSchema, BackupArchiveEntrySchema, BackupDestinationInfoSchema, BackupEntrySchema, BackupRunPhaseSchema, BackupRunSchema, BackupRunStateSchema, BackupScheduleSchema, BackupSubDestinationInfoSchema, BackupTriggerResultSchema, LocationStatSchema, };
+export type BackupRunState = z.infer<typeof BackupRunStateSchema>;
+export type BackupRunPhase = z.infer<typeof BackupRunPhaseSchema>;
+export type BackupRun = z.infer<typeof BackupRunSchema>;
+export type BackupTriggerResult = z.infer<typeof BackupTriggerResultSchema>;

package/dist/capabilities/device-manager.cap.d.ts

@@ -349,6 +349,13 @@ export declare const deviceManagerCapability: {
          * `sourceStillLive` names what stayed live; empty is the only value that
          * means the old hardware is quiet. The migration proceeds either way —
          * refusing would refuse the case this exists for.
+         *
+         * **Safe to retry.** A duplicate call while a migration involving either
+         * device is in flight is REFUSED, never queued; a repeat of a swap that
+         * already completed (matched against the `addonId`/`stableId` fingerprint
+         * the swap left on the rows, within 15 min) is a no-op returning the
+         * original report. A blind re-run can no longer silently undo the
+         * migration it retried.
          */
         readonly migrateDevice: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
             sourceId: z.ZodNumber;

package/dist/capabilities/device-provider.cap.d.ts

@@ -82,6 +82,36 @@ export declare const deviceProviderCapability: {
             name: z.ZodString;
             type: z.ZodString;
         }, z.core.$strip>>, import("./capability-definition.js").CapabilityMethodKind>;
+        /**
+         * Tear down and reconstruct ONE device in place from its persisted rows —
+         * touching no other device this provider owns.
+         *
+         * The primitive `deviceManager.migrateDevice` uses to flush the two
+         * migrated numbers: after `swapIds` the runner's live instance still
+         * carries the PRE-swap numeric id (baked into the object, its native-cap
+         * registrations and its log tags), and a live object cannot be renumbered.
+         * Before this method the only flush was restarting the whole owning addon
+         * — which took every camera the provider owns down with it (28 devices
+         * for one migrated camera, measured 2026-09-04, and the morning of the
+         * same day ~27 devices' native caps did not come back on their own).
+         *
+         * Keyed by `stableId`, deliberately: the numeric id is exactly the thing
+         * that changes. The reply carries the id the device answers on NOW.
+         * Implemented once in `BaseDeviceProvider` — decommission the live
+         * instance (if any), then re-create from the persisted row: the same
+         * teardown/rehydrate pair every graceful shutdown + boot already uses.
+         * An RPC, never an event: a dropped event would leave the runner writing
+         * against the wrong camera (D8).
+         *
+         * Construction can dial hardware, and the migrated source is
+         * characteristically dead — the timeout covers a full activate window
+         * rather than the 60 s default.
+         */
+        readonly reloadDevice: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            stableId: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            deviceId: z.ZodNumber;
+        }, z.core.$strip>, "mutation">;
         readonly supportsDiscovery: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{}, z.core.$strip>, z.ZodBoolean, import("./capability-definition.js").CapabilityMethodKind>;
         /**
          * Run a network scan. `params` carries optional provider-specific scan

package/dist/capabilities/index.d.ts

@@ -31,7 +31,7 @@ export type { AudioAnalyzerGlobalConfig, AudioBackendChoice, IAudioAnalyzerProvi
 export { AUDIO_BACKEND_CHOICES, AudioAnalysisResultSchema, AudioAnalysisSettingsSchema, AudioClassificationResultSchema, audioAnalyzerCapability, DEFAULT_AUDIO_ANALYZER_CONFIG, } from './audio-analyzer.cap.js';
 export { AudioCodecInfoSchema, AudioDecodeSessionConfigSchema, AudioEncodedChunkSchema, AudioEncodeSessionConfigSchema, AudioPcmChunkSchema, audioCodecCapability, type IAudioCodecCapProvider, PcmSampleFormatSchema, } from './audio-codec.cap.js';
 export { AuthResultSchema, authProviderCapability } from './auth-provider.cap.js';
-export { ArchiveEntrySchema, ArchiveManifestSchema, BackupDestinationInfoSchema, BackupEntrySchema, backupCapability, type IBackupProvider, LocationStatSchema, } from './backup.cap.js';
+export { ArchiveEntrySchema, ArchiveManifestSchema, BackupDestinationInfoSchema, BackupEntrySchema, type BackupRun, type BackupRunPhase, BackupRunPhaseSchema, BackupRunSchema, type BackupRunState, BackupRunStateSchema, type BackupTriggerResult, BackupTriggerResultSchema, backupCapability, type IBackupProvider, LocationStatSchema, } from './backup.cap.js';
 export { BrokerAddInputSchema, BrokerGetStateInputSchema, type BrokerInfo as UnifiedBrokerInfo, BrokerInfoSchema as UnifiedBrokerInfoSchema, type BrokerProviderInfo, BrokerProviderInfoSchema, BrokerPublishInputSchema, BrokerRegistryStatusSchema, type BrokerStatus as UnifiedBrokerStatus, BrokerStatusEnum, BrokerSubscribeInputSchema, BrokerSubscribeResultSchema, BrokerTestConnectionResultSchema, BrokerUnsubscribeInputSchema, brokerCapability, type IBrokerProvider, } from './broker.cap.js';
 export { cameraPipelineConfigCapability, type ICameraPipelineConfigProvider, } from './camera-pipeline-config.cap.js';
 export { cameraStreamsCapability, type ICameraStreamsProvider, type PickedCamStream, PickedCamStreamSchema, PickStreamPreferencesSchema, PickStreamRequirementsSchema, type StreamCodec, StreamCodecSchema, } from './camera-streams.cap.js';

package/dist/capabilities/stream-broker.cap.d.ts

@@ -643,6 +643,37 @@ export declare const streamBrokerCapability: {
         }, z.core.$strip>, z.ZodObject<{
             success: z.ZodLiteral<true>;
         }, z.core.$strip>, "mutation">;
+        /**
+         * The HARDWARE behind a device number was replaced
+         * (`deviceManager.migrateDevice`). Forget every piece of broker state that
+         * described the old box, so the next catalog pull derives everything from
+         * the camera that is actually there:
+         *
+         *  - every `derived:*` stream definition — a derived is authored against a
+         *    specific profile layout, and against the wrong hardware its feeder
+         *    respawns forever (observed at attempt 2732 on the live hub,
+         *    2026-09-01);
+         *  - the profile-slot assignment entry, PURGED (not unassigned — unassign
+         *    marks the slot manual, which would pin the stale choice instead of
+         *    letting `computeInitialAssignment` re-derive it);
+         *  - the probe snapshots (`<deviceId>/…` — probed codec/resolution of the
+         *    old hardware);
+         *  - the persisted RTSP token rows for the device's brokers (keyed
+         *    `<deviceId>/<camStreamId>`; the stream ids change with the hardware,
+         *    so the rows are dead URLs).
+         *
+         * An RPC, deliberately — an event is telemetry and may be dropped (D8),
+         * and a dropped forget leaves a feeder respawning against a stream that
+         * does not exist.
+         */
+        readonly forgetDeviceHardware: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            derivedStreamsDeleted: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+            assignmentsPurged: z.ZodBoolean;
+            probeSnapshotsDropped: z.ZodNumber;
+            rtspTokenRowsDeleted: z.ZodNumber;
+        }, z.core.$strip>, "mutation">;
         /**
          * Render a short GIF or MP4 from the broker's PRE-BUFFER around an instant.
          *

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

@@ -4,6 +4,7 @@ import type { ConfigUISchema } from '../interfaces/config-ui.js';
 import type { IDevice } from './device.js';
 import type { DeviceConstructor } from './device-context.js';
 import type { CreateDeviceSpec, SavedDevice } from './device-management.js';
+import type { PermanentRestoreFailure } from './device-restore-retry.js';
 import { DeviceType } from './device-type.js';
 import type { SourceInfo } from './source-info.js';
 export interface DiscoveryCandidate {
@@ -38,6 +39,19 @@ export interface ProviderStatus {
     readonly deviceCount: number;
     readonly error?: string;
 }
+/**
+ * Outcome of an `onRestoreDevices` pass. Optional for back-compat:
+ * providers with custom overrides may keep returning `void` — they
+ * just don't get the accurate summary log (or the bounded retry the
+ * default implementation wires up, see D347).
+ */
+export interface DeviceRestoreReport {
+    /** Rows registered during the initial pass. */
+    readonly restoredCount: number;
+    /** Rows that failed the initial pass and were handed to the bounded
+     *  background retry. */
+    readonly failedCount: number;
+}
 export interface FieldProbeResult {
     readonly status: 'ok' | 'error';
     readonly labels?: readonly string[];
@@ -147,6 +161,52 @@ export declare abstract class BaseDeviceProvider<TConfig extends object = Record
         formValues?: Record<string, unknown>;
     }): Promise<FieldProbeResult>;
     restoreDevices(savedDevices: readonly SavedDevice[]): Promise<void>;
+    /** Retry schedule. Overridable (tests use millisecond delays). */
+    protected readonly restoreRetryDelaysMs: readonly number[];
+    /** Retry lane width. See `device-restore-retry.ts` for why retries
+     *  never re-stampede full-width while the initial pass does (D167). */
+    protected readonly restoreRetryConcurrency: number;
+    private _restoreRetryScheduler;
+    private _restoreRetryCompletion;
+    private readonly _permanentRestoreFailures;
+    /** Settles when the background retry rounds finish (or `null` when
+     *  nothing failed). Exposed for tests and subclass diagnostics —
+     *  boot NEVER awaits this: the runner's post-init handshake goes out
+     *  with the devices that restored, and a late success is announced
+     *  through the `native-cap-change` → `updateCaps` path. */
+    protected get restoreRetryCompletion(): Promise<void> | null;
+    /** Devices that exhausted the retry bound this process lifetime. */
+    protected get permanentRestoreFailures(): readonly PermanentRestoreFailure[];
+    /** One-line operator-facing summary for `getStatus().error`, or
+     *  `null` when every device restored. */
+    protected restoreFailureSummary(): string | null;
+    private cancelRestoreRetries;
+    private recordPermanentRestoreFailure;
+    private scheduleRestoreRetries;
+    /**
+     * Tear down and reconstruct ONE device from its persisted rows — the
+     * `deviceProvider.reloadDevice` cap method. Persistence is never touched,
+     * and no other device this provider owns is disturbed.
+     *
+     * Keyed by `stableId` because the caller's whole reason to be here is that
+     * the NUMERIC id changed (`deviceManager.migrateDevice` swapped it): the
+     * fresh instance resolves its id through `allocateDeviceId`, which returns
+     * whatever number the row carries NOW. The teardown is `decommission` —
+     * exactly what a graceful shutdown runs per device (fires `removeDevice()`,
+     * unregisters native caps, drops the registry entry) — and the rebuild is
+     * the boot restore's own `create()` path, including its pass 2: first-class
+     * children (hub-adopted cameras under an NVR) are decommissioned with the
+     * parent by the cascade and must be re-created explicitly, because only
+     * accessory children come back through `getAccessoryChildren()`.
+     *
+     * Reloading an accessory child directly is refused (no device class) —
+     * reload its parent instead.
+     */
+    reloadDevice(input: {
+        stableId: string;
+    }): Promise<{
+        deviceId: number;
+    }>;
     /**
      * Concrete device classes this provider can spawn, keyed by
      * `DeviceType`. Used by:
@@ -196,8 +256,14 @@ export declare abstract class BaseDeviceProvider<TConfig extends object = Record
      * accessory-spawn flow handles via the parent's
      * `getAccessoryChildren()`. Override only when the default doesn't
      * fit.
+     *
+     * A row that fails either pass is NOT terminal (D347): it is handed
+     * to a bounded background retry (`DeviceRestoreRetryScheduler`).
+     * Only after the bound is exhausted is the device marked permanently
+     * failed — logged at ERROR with `tags.deviceId` and surfaced via
+     * `getStatus().error`.
      */
-    protected onRestoreDevices(savedDevices: readonly SavedDevice[]): Promise<void>;
+    protected onRestoreDevices(savedDevices: readonly SavedDevice[]): Promise<DeviceRestoreReport | void>;
     /** Convert an IDevice to the flat DeviceSummary for the cap router. */
     protected toSummary(device: IDevice): DeviceSummary;
 }

package/dist/device/device-restore-retry.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Bounded retry for failed per-device boot restores (D347).
+ *
+ * WHY: a provider runner's boot restore is a full-width fan-out of
+ * independent `kernel.devices.create()` dials (D167). When the hub is
+ * briefly busy (a migration holding device-manager, a starved event
+ * loop) whole batches of those dials time out together at the UDS
+ * transport's 60 s default — and until D347 a failed restore was
+ * TERMINAL: the device's native caps never entered the worker map,
+ * `updateCaps` never announced them, and every route answered
+ * "binding not yet in LocalChildRegistry" for the life of the process.
+ * 27 cameras were off the air for 20 minutes on 2026-09-04 because of
+ * exactly this; the devices were healthy and merely lost a race.
+ *
+ * The scheduler distinguishes "not yet" from "never":
+ *   - **not yet** — a bounded number of retries with growing delays
+ *     (`DEVICE_RESTORE_RETRY_DELAYS_MS`). A retry that succeeds flows
+ *     through the runner's `native-cap-change` listener, so the
+ *     device's caps are announced via `updateCaps` even though the
+ *     post-init handshake has long passed.
+ *   - **never** — after the last round the device is handed to
+ *     `onPermanentFailure` with its attempt count and last error, and
+ *     nothing retries it again (CrashSupervisor's discipline, D6:
+ *     bounded, then terminally failed and VISIBLE — the provider
+ *     surfaces it via `getStatus().error` and an ERROR log tagged
+ *     `deviceId`).
+ *
+ * Retry width is bounded (`DEVICE_RESTORE_RETRY_CONCURRENCY`): the
+ * devices being retried already failed TOGETHER, which is evidence of
+ * hub congestion — re-stampeding the full set recreates the collision.
+ * The INITIAL fan-out stays full-width (D167 measured a lane cap
+ * costing 6.5 min on a healthy boot); only the retry lanes are capped,
+ * so a large fleet's happy-path boot is byte-for-byte unchanged.
+ *
+ * Cancellation (`cancel()`) is for shutdown: pending entries are NOT
+ * marked permanently failed — the process is going away and the next
+ * boot re-runs the restore from the persisted rows.
+ */
+import type { IScopedLogger } from '../interfaces/logging.js';
+import type { SavedDevice } from './device-management.js';
+/**
+ * Delays before retry rounds 1..N — the round count IS the bound.
+ * 10 s catches "the hub was busy for a moment"; the full schedule
+ * (10 + 30 + 90 s of waiting, plus up to one 60 s transport timeout
+ * per attempt) covers a device-manager lock held for minutes — the
+ * 2026-09-04 outage's migration hold was ~3.5 min.
+ */
+export declare const DEVICE_RESTORE_RETRY_DELAYS_MS: readonly number[];
+/** Lane width for retry rounds. See module docblock — retries are
+ *  evidence of congestion, so they never re-stampede full-width. */
+export declare const DEVICE_RESTORE_RETRY_CONCURRENCY = 4;
+/** One device that failed its initial restore attempt. */
+export interface InitialRestoreFailure {
+    readonly saved: SavedDevice;
+    readonly error: string;
+}
+/** A device that exhausted the retry bound. Kept by the provider for
+ *  the life of the process and surfaced via `getStatus().error`. */
+export interface PermanentRestoreFailure {
+    readonly deviceId: number;
+    readonly stableId: string;
+    readonly type: string;
+    /** Total attempts made, including the initial restore. */
+    readonly attempts: number;
+    readonly lastError: string;
+    /** Epoch ms of the final failed attempt. */
+    readonly failedAt: number;
+}
+/** Attempts one device restore. Throws on failure; resolving means the
+ *  device is registered (or already was). */
+export type RestoreAttemptFn = (saved: SavedDevice) => Promise<void>;
+export type PermanentRestoreFailureHandler = (failure: PermanentRestoreFailure) => void;
+export interface DeviceRestoreRetrySchedulerOptions {
+    readonly logger: IScopedLogger;
+    readonly attempt: RestoreAttemptFn;
+    readonly onPermanentFailure: PermanentRestoreFailureHandler;
+    readonly delaysMs?: readonly number[];
+    readonly concurrency?: number;
+    readonly now?: () => number;
+}
+export declare class DeviceRestoreRetryScheduler {
+    #private;
+    constructor(options: DeviceRestoreRetrySchedulerOptions);
+    /** Stop retrying (shutdown). Pending entries are NOT marked
+     *  permanently failed — the next boot restores them from disk. */
+    cancel(): void;
+    /**
+     * Run the bounded retry rounds. Resolves when every entry has either
+     * restored, been marked permanently failed, or the scheduler was
+     * cancelled. Never rejects.
+     */
+    run(initialFailures: readonly InitialRestoreFailure[]): Promise<readonly PermanentRestoreFailure[]>;
+}

package/dist/device/index.d.ts

@@ -1,8 +1,10 @@
 export { ACCESSORY_LABEL, AccessoryKind, type AccessoryKindValue, accessoryStableId, } from './accessory.js';
 export type { AccessoryChildSpec } from './base-device.js';
 export { BaseDevice } from './base-device.js';
-export type { DeviceSummary, DiscoveryCandidate, FieldProbeResult, ProviderStatus, } from './base-device-provider.js';
+export type { DeviceRestoreReport, DeviceSummary, DiscoveryCandidate, FieldProbeResult, ProviderStatus, } from './base-device-provider.js';
 export { BaseDeviceProvider, toDeviceSummary } from './base-device-provider.js';
+export type { DeviceRestoreRetrySchedulerOptions, InitialRestoreFailure, PermanentRestoreFailure, PermanentRestoreFailureHandler, RestoreAttemptFn, } from './device-restore-retry.js';
+export { DEVICE_RESTORE_RETRY_CONCURRENCY, DEVICE_RESTORE_RETRY_DELAYS_MS, DeviceRestoreRetryScheduler, } from './device-restore-retry.js';
 export type { ICameraDevice, StreamSourceEntry } from './camera-device.js';
 export type { DeclarationPlacement, DeclaredDeviceOutcome, DeclaredDevicePorts, DeclaredDeviceRow, DeclaredDevicesResult, DeclaredDevicesSpec, DeclaredIntegrationRow, DeviceDeclaration, } from './declared-device.js';
 export { DECLARED_DEVICE_SWEEP_LIMIT, DECLARED_INTEGRATION_FIXED_KEY, DeclaredDevices, declarationOwnerNodeId, } from './declared-device.js';

package/dist/generated/addon-api.d.ts

@@ -870,6 +870,20 @@ export type AppRouter = TrpcCoreRouter<{
             output: z.infer<typeof backupCapability.methods.trigger.output>;
             meta: object;
         }>;
+        listRuns: TRPCQueryProcedure<{
+            input: {
+                nodeId?: string | undefined;
+            } | undefined;
+            output: z.infer<typeof backupCapability.methods.listRuns.output>;
+            meta: object;
+        }>;
+        cancel: TRPCMutationProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof backupCapability.methods.cancel.input>;
+            output: z.infer<typeof backupCapability.methods.cancel.output>;
+            meta: object;
+        }>;
         list: TRPCQueryProcedure<{
             input: {
                 nodeId?: string | undefined;
@@ -2681,6 +2695,13 @@ export type AppRouter = TrpcCoreRouter<{
             output: z.infer<typeof deviceProviderCapability.methods.getDevices.output>;
             meta: object;
         }>;
+        reloadDevice: TRPCMutationProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof deviceProviderCapability.methods.reloadDevice.input>;
+            output: z.infer<typeof deviceProviderCapability.methods.reloadDevice.output>;
+            meta: object;
+        }>;
         supportsDiscovery: TRPCQueryProcedure<{
             input: {
                 [x: string]: unknown;
@@ -7568,6 +7589,13 @@ export type AppRouter = TrpcCoreRouter<{
             output: z.infer<typeof streamBrokerCapability.methods.unassignProfile.output>;
             meta: object;
         }>;
+        forgetDeviceHardware: TRPCMutationProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof streamBrokerCapability.methods.forgetDeviceHardware.input>;
+            output: z.infer<typeof streamBrokerCapability.methods.forgetDeviceHardware.output>;
+            meta: object;
+        }>;
         renderPreBufferClip: TRPCMutationProcedure<{
             input: {
                 [x: string]: unknown;

package/dist/generated/device-proxy.d.ts

@@ -87,6 +87,7 @@ import type { cameraPipelineConfigCapability } from '../capabilities/camera-pipe
 import type { deviceAdoptionCapability } from '../capabilities/device-adoption.cap.js';
 import type { deviceExportCapability } from '../capabilities/device-export.cap.js';
 import type { deviceManagerCapability } from '../capabilities/device-manager.cap.js';
+import type { deviceProviderCapability } from '../capabilities/device-provider.cap.js';
 import type { deviceStateCapability } from '../capabilities/device-state.cap.js';
 import type { faceGalleryCapability } from '../capabilities/face-gallery.cap.js';
 import type { networkQualityCapability } from '../capabilities/network-quality.cap.js';
@@ -272,6 +273,7 @@ export interface DeviceProxy {
     readonly deviceAdoption: Pick<InferDeviceProxyCap<typeof deviceAdoptionCapability>, 'getStatus'>;
     readonly deviceExport: Pick<InferDeviceProxyCap<typeof deviceExportCapability>, 'getDeviceSettingsContribution' | 'getDeviceLiveContribution' | 'applyDeviceSettingsPatch'>;
     readonly deviceManager: Pick<InferDeviceProxyCap<typeof deviceManagerCapability>, 'loadConfig' | 'loadRuntimeState' | 'loadMeta' | 'setName' | 'setLocation' | 'setType' | 'setIntegrationId' | 'setLinkDeviceId' | 'setPrimaryChildEntityId' | 'setChildLayout' | 'setDisplay' | 'getWireableFields' | 'setRole' | 'applyInitialMeta' | 'setMetadata' | 'setDisabled' | 'getDevice' | 'getLinkedDevices' | 'getStreamSources' | 'getConfigSchema' | 'getSettingsSchema' | 'updateConfig' | 'enable' | 'disable' | 'remove' | 'getStreamProfileMap' | 'setStreamProfileMap' | 'probeStreams' | 'getBindings' | 'setWrapperActive' | 'getDeviceSettingsAggregate' | 'getDeviceLiveInfoAggregate' | 'getDeviceAggregate' | 'runDeviceAction' | 'updateDeviceField' | 'updateDeviceFieldsBatch' | 'testField' | 'getDeviceStatusAggregate' | 'getDeviceSettingsContribution' | 'getDeviceLiveContribution' | 'applyDeviceSettingsPatch'>;
+    readonly deviceProvider: Pick<InferDeviceProxyCap<typeof deviceProviderCapability>, 'reloadDevice'>;
     readonly deviceState: Pick<InferDeviceProxyCap<typeof deviceStateCapability>, 'getSnapshot' | 'getCapSlice' | 'setCapSlice'>;
     readonly faceGallery: Pick<InferDeviceProxyCap<typeof faceGalleryCapability>, 'listRecentFaces' | 'getFaceByTrack'>;
     readonly networkQuality: Pick<InferDeviceProxyCap<typeof networkQualityCapability>, 'getDeviceStats' | 'reportClientStats'>;
@@ -282,7 +284,7 @@ export interface DeviceProxy {
     readonly plateGallery: Pick<InferDeviceProxyCap<typeof plateGalleryCapability>, 'listPlates' | 'getPlateByTrack'>;
     readonly recording: Pick<InferDeviceProxyCap<typeof recordingCapability>, 'getAvailability' | 'getDaysWithRecordings' | 'getPlaybackManifest' | 'getDeviceConfig' | 'locateSegment' | 'readSegmentBytes' | 'readGopBytes' | 'readWindowBytes' | 'setDeviceConfig' | 'rescanStorage' | 'pruneFootage' | 'deleteFootprint' | 'renderGif' | 'renderClip' | 'getStatus' | 'getDeviceSettingsContribution' | 'getDeviceLiveContribution' | 'applyDeviceSettingsPatch'>;
     readonly recordingExport: Pick<InferDeviceProxyCap<typeof recordingExportCapability>, 'listExports'>;
-    readonly streamBroker: Pick<InferDeviceProxyCap<typeof streamBrokerCapability>, 'publishCameraStream' | 'retractCameraStream' | 'assignProfile' | 'unassignProfile' | 'renderPreBufferClip' | 'produceEventMedia' | 'restartProfile' | 'getDeviceAudioMute' | 'setDeviceAudioMute' | 'getDeviceSettingsContribution' | 'getDeviceLiveContribution' | 'applyDeviceSettingsPatch'>;
+    readonly streamBroker: Pick<InferDeviceProxyCap<typeof streamBrokerCapability>, 'publishCameraStream' | 'retractCameraStream' | 'assignProfile' | 'unassignProfile' | 'forgetDeviceHardware' | 'renderPreBufferClip' | 'produceEventMedia' | 'restartProfile' | 'getDeviceAudioMute' | 'setDeviceAudioMute' | 'getDeviceSettingsContribution' | 'getDeviceLiveContribution' | 'applyDeviceSettingsPatch'>;
 }
 /**
  * Build a DeviceProxy that pre-binds deviceId + nodeId on every method call

package/dist/generated/method-access-map.d.ts

@@ -6,7 +6,7 @@
  * scope+access check inside `protectedProcedure` (see
  * `server/backend/src/api/trpc/trpc.middleware.ts`).
  *
- * Coverage: 1002 method paths across 126 capabilities.
+ * Coverage: 1006 method paths across 126 capabilities.
  */
 import type { CapabilityMethodAccess } from '../capabilities/capability-definition.js';
 export interface MethodAccessRecord {

package/dist/generated/method-device-selectors.d.ts

@@ -6,8 +6,8 @@
  * system-scope cap that takes a deviceId was previously never device-filtered
  * — see the generator header).
  *
- * Coverage: 354 methods carry a device reference, of which
- * 133 are on SYSTEM-scope caps.
+ * Coverage: 355 methods carry a device reference, of which
+ * 134 are on SYSTEM-scope caps.
  *
  * Top-level fields, number arrays, and one-level arrays of objects carrying
  * a numeric device field (targets[].deviceId) are all mapped; the matcher

package/dist/generated/system-proxy.d.ts

@@ -61,7 +61,7 @@ export interface SystemProxy {
     readonly alerts: Pick<InferProvider<typeof alertsCapability>, 'emit' | 'update' | 'list' | 'getUnreadCount' | 'markRead' | 'markAllRead' | 'dismiss'>;
     readonly audioAnalyzer: Pick<InferProvider<typeof audioAnalyzerCapability>, 'analyseChunk' | 'classify' | 'isReady' | 'dispose' | 'reprobeAudioEngine'>;
     readonly audioCodec: Pick<InferProvider<typeof audioCodecCapability>, 'listSupportedCodecs' | 'canHandle' | 'createDecodeSession' | 'createEncodeSession' | 'closeSession' | 'pushEncodedFrame' | 'pullPcm' | 'pushPcm' | 'pullEncoded' | 'flushEncode' | 'listActiveSessions'>;
-    readonly backup: Pick<InferProvider<typeof backupCapability>, 'listDestinations' | 'trigger' | 'list' | 'listLocations' | 'getEntries' | 'restore' | 'delete' | 'listArchives' | 'upsertDestinationPolicy' | 'previewSchedule' | 'listSchedules' | 'upsertSchedule' | 'deleteSchedule'>;
+    readonly backup: Pick<InferProvider<typeof backupCapability>, 'listDestinations' | 'trigger' | 'listRuns' | 'cancel' | 'list' | 'listLocations' | 'getEntries' | 'restore' | 'delete' | 'listArchives' | 'upsertDestinationPolicy' | 'previewSchedule' | 'listSchedules' | 'upsertSchedule' | 'deleteSchedule'>;
     readonly broker: Pick<InferProvider<typeof brokerCapability>, 'list' | 'get' | 'listProviders' | 'add' | 'remove' | 'testConnection' | 'getSettings' | 'setSettings' | 'getBrokerConfig' | 'getSettingsSchema' | 'testSettings' | 'publish' | 'subscribe' | 'unsubscribe' | 'getState' | 'getStatus'>;
     readonly connectionTest: Pick<InferProvider<typeof connectionTestCapability>, 'testSettings' | 'describeTest'>;
     readonly coreBlocks: Pick<InferProvider<typeof coreBlocksCapability>, 'list' | 'get' | 'create' | 'update' | 'delete' | 'setEnabled' | 'restart' | 'compile' | 'getTypeDefs'>;

package/dist/index.d.ts

@@ -141,8 +141,10 @@ export type { AccessoryKindValue } from './device/accessory.js';
 export { ACCESSORY_LABEL, AccessoryKind, accessoryStableId, } from './device/accessory.js';
 export type { AccessoryChildSpec } from './device/base-device.js';
 export { BaseDevice } from './device/base-device.js';
-export type { DeviceSummary, DiscoveryCandidate, FieldProbeResult, } from './device/base-device-provider.js';
+export type { DeviceRestoreReport, DeviceSummary, DiscoveryCandidate, FieldProbeResult, } from './device/base-device-provider.js';
 export { BaseDeviceProvider, toDeviceSummary } from './device/base-device-provider.js';
+export type { DeviceRestoreRetrySchedulerOptions, InitialRestoreFailure, PermanentRestoreFailure, PermanentRestoreFailureHandler, RestoreAttemptFn, } from './device/device-restore-retry.js';
+export { DEVICE_RESTORE_RETRY_CONCURRENCY, DEVICE_RESTORE_RETRY_DELAYS_MS, DeviceRestoreRetryScheduler, } from './device/device-restore-retry.js';
 export type { BatteryPresence, BatteryPresenceInput } from './device/battery-presence.js';
 export { BATTERY_UNREACHABLE_AFTER_MS, deriveBatteryPresence, isBatteryPresenceFault, } from './device/battery-presence.js';
 export type { ICameraDevice, StreamSourceEntry } from './device/camera-device.js';