@camstack/types 1.2.142 → 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-BDmIj1HV.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-Cwo3fRlv.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/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/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

@@ -2695,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;

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'>;

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: 1005 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/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';