@camstack/types 1.2.141 → 1.2.143

package/dist/index.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_canonical_hash = require("./canonical-hash-DNV8S5ET.js");
 const require_enums = require("./enums.js");
 const require_err_msg = require("./err-msg-COpsHMw2.js");
@@ -6616,6 +6616,89 @@ var LocationStatSchema = zod.z.object({
 	fileCount: zod.z.number(),
 	present: zod.z.boolean()
 });
+/** Lifecycle of a backup run. Terminal states: succeeded / failed / cancelled. */
+var BackupRunStateSchema = zod.z.enum([
+	"queued",
+	"running",
+	"succeeded",
+	"failed",
+	"cancelled"
+]);
+/**
+* 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.
+*/
+var BackupRunPhaseSchema = zod.z.enum([
+	"queued",
+	"building",
+	"uploading",
+	"done"
+]);
+/**
+* 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.
+*/
+var BackupRunSchema = zod.z.object({
+	/** Stable run id — the handle `backup.cancel` takes. */
+	id: zod.z.string(),
+	state: BackupRunStateSchema,
+	phase: BackupRunPhaseSchema,
+	/**
+	* Resolved destination location ids. Empty while queued (targets are
+	* resolved when the run starts, against the then-current policies).
+	*/
+	destinationIds: zod.z.array(zod.z.string()).readonly(),
+	label: zod.z.string().optional(),
+	/** ms-epoch when the run was submitted (trigger call / schedule fire). */
+	requestedAt: zod.z.number(),
+	/** ms-epoch when the run left the queue and started building. */
+	startedAt: zod.z.number().optional(),
+	/** ms-epoch when the run reached a terminal state. */
+	finishedAt: zod.z.number().optional(),
+	/** Compressed bytes of the staging archive written so far. */
+	stagedBytes: zod.z.number(),
+	/** Final staged archive size, once the build phase completes. */
+	archiveSizeBytes: zod.z.number().optional(),
+	/** Bytes pushed to the destination currently uploading. */
+	uploadedBytes: zod.z.number(),
+	/** Destinations where the archive fully landed (uploaded + indexed). */
+	completedDestinationIds: zod.z.array(zod.z.string()).readonly(),
+	/** Destinations that failed during the fan-out. */
+	failedDestinationIds: zod.z.array(zod.z.string()).readonly(),
+	/** Failure message when `state === 'failed'`. */
+	error: zod.z.string().optional(),
+	/**
+	* 1-based place in the execution queue — 1 = runs next. Present only
+	* while `state === 'queued'`. Stamped by the orchestrator from the
+	* queue's OWN pending order, never derived from timestamps, so the
+	* UI cannot show an order the executor will not honour.
+	*/
+	queuePosition: zod.z.number().int().min(1).optional()
+});
+/**
+* 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.
+*/
+var BackupTriggerResultSchema = zod.z.object({
+	/** The run this trigger mapped to — poll it via `listRuns`, stop it via `cancel`. */
+	runId: zod.z.string(),
+	/** True when the run waited behind an in-flight run instead of starting immediately. */
+	queued: zod.z.boolean(),
+	/** True when this trigger was coalesced onto an identical already-queued run. */
+	joined: zod.z.boolean(),
+	/** True when the run was cancelled before completing every destination. */
+	cancelled: zod.z.boolean(),
+	/** One entry per destination the archive landed at (partial on cancel). */
+	entries: zod.z.array(BackupEntrySchema).readonly()
+});
 /**
 * A backup schedule — the N:M "entry" that binds one cron cadence to a
 * SET of destination locations. Supersedes the per-location cron on
@@ -6673,6 +6756,11 @@ var 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.
 		*/
 		trigger: require_sleep.method(zod.z.object({
 			/** Subset of registered `backup-destination` addon ids to write to. */
@@ -6686,7 +6774,30 @@ var backupCapability = {
 			* retention (manual runs).
 			*/
 			retentionCount: zod.z.number().int().min(1).max(1e3).optional()
-		}).optional(), zod.z.array(BackupEntrySchema).readonly(), {
+		}).optional(), BackupTriggerResultSchema, {
+			kind: "mutation",
+			auth: "admin"
+		}),
+		/**
+		* 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`.
+		*/
+		listRuns: require_sleep.method(zod.z.void(), zod.z.array(BackupRunSchema).readonly(), { auth: "admin" }),
+		/**
+		* 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.
+		*/
+		cancel: require_sleep.method(zod.z.object({ runId: zod.z.string() }), zod.z.object({ cancelled: zod.z.boolean() }), {
 			kind: "mutation",
 			auth: "admin"
 		}),
@@ -7570,6 +7681,38 @@ var streamBrokerCapability = {
 			auth: "admin"
 		}),
 		/**
+		* 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.
+		*/
+		forgetDeviceHardware: require_sleep.method(zod.z.object({ deviceId: zod.z.number().int().nonnegative() }), zod.z.object({
+			derivedStreamsDeleted: zod.z.array(zod.z.string()).readonly(),
+			assignmentsPurged: zod.z.boolean(),
+			probeSnapshotsDropped: zod.z.number().int().nonnegative(),
+			rtspTokenRowsDeleted: zod.z.number().int().nonnegative()
+		}), {
+			kind: "mutation",
+			auth: "admin"
+		}),
+		/**
 		* Render a short GIF or MP4 from the broker's PRE-BUFFER around an instant.
 		*
 		* The pre-buffer is the only source that already holds the seconds BEFORE
@@ -9974,6 +10117,35 @@ var deviceProviderCapability = {
 			name: zod.z.string(),
 			type: zod.z.string()
 		}))),
+		/**
+		* 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.
+		*/
+		reloadDevice: require_sleep.method(zod.z.object({ stableId: zod.z.string() }), zod.z.object({ deviceId: zod.z.number() }), {
+			kind: "mutation",
+			timeoutMs: 3 * 6e4
+		}),
 		supportsDiscovery: require_sleep.method(zod.z.object({}), zod.z.boolean()),
 		/**
 		* Run a network scan. `params` carries optional provider-specific scan
@@ -10368,13 +10540,21 @@ var 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.
 		*/
 		migrateDevice: require_sleep.method(zod.z.object({
 			sourceId: zod.z.number(),
 			targetId: zod.z.number()
 		}), MigrateDeviceResultSchema, {
 			kind: "mutation",
-			auth: "admin"
+			auth: "admin",
+			timeoutMs: 12 * 6e4
 		}),
 		/** Register a device in the DB + in-memory registry. Called by DeviceManagerApi.register(). */
 		registerDevice: require_sleep.method(DeviceRegisterPayloadSchema, zod.z.void(), { kind: "mutation" }),
@@ -36248,6 +36428,152 @@ var BaseDevice = class {
 	}
 };
 //#endregion
+//#region src/device/device-restore-retry.ts
+/**
+* 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.
+*/
+var DEVICE_RESTORE_RETRY_DELAYS_MS = [
+	1e4,
+	3e4,
+	9e4
+];
+/** Lane width for retry rounds. See module docblock — retries are
+*  evidence of congestion, so they never re-stampede full-width. */
+var DEVICE_RESTORE_RETRY_CONCURRENCY = 4;
+/** Abortable sleep — resolves early (never rejects) on abort. */
+function sleep$1(ms, signal) {
+	return new Promise((resolve) => {
+		if (signal.aborted) {
+			resolve();
+			return;
+		}
+		const onAbort = () => {
+			clearTimeout(timer);
+			resolve();
+		};
+		const timer = setTimeout(() => {
+			signal.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		timer.unref?.();
+		signal.addEventListener("abort", onAbort, { once: true });
+	});
+}
+/** Drain `items` through at most `width` concurrent lanes. `fn` must
+*  not reject (callers wrap their own try/catch). */
+async function runWithConcurrency(items, width, fn) {
+	const queue = [...items];
+	const laneCount = Math.max(1, Math.min(width, queue.length));
+	const lane = async () => {
+		for (;;) {
+			const item = queue.shift();
+			if (item === void 0) return;
+			await fn(item);
+		}
+	};
+	await Promise.all(Array.from({ length: laneCount }, lane));
+}
+var DeviceRestoreRetryScheduler = class {
+	#logger;
+	#attempt;
+	#onPermanentFailure;
+	#delaysMs;
+	#concurrency;
+	#now;
+	#abort = new AbortController();
+	constructor(options) {
+		this.#logger = options.logger;
+		this.#attempt = options.attempt;
+		this.#onPermanentFailure = options.onPermanentFailure;
+		this.#delaysMs = options.delaysMs ?? DEVICE_RESTORE_RETRY_DELAYS_MS;
+		this.#concurrency = options.concurrency ?? 4;
+		this.#now = options.now ?? Date.now;
+	}
+	/** Stop retrying (shutdown). Pending entries are NOT marked
+	*  permanently failed — the next boot restores them from disk. */
+	cancel() {
+		this.#abort.abort();
+	}
+	/**
+	* Run the bounded retry rounds. Resolves when every entry has either
+	* restored, been marked permanently failed, or the scheduler was
+	* cancelled. Never rejects.
+	*/
+	async run(initialFailures) {
+		let pending = initialFailures.map((failure) => ({
+			saved: failure.saved,
+			lastError: failure.error,
+			attempts: 1
+		}));
+		for (let round = 0; round < this.#delaysMs.length; round += 1) {
+			if (pending.length === 0 || this.#abort.signal.aborted) break;
+			await sleep$1(this.#delaysMs[round] ?? 0, this.#abort.signal);
+			if (this.#abort.signal.aborted) break;
+			pending = await this.#runRound(pending, round);
+		}
+		if (this.#abort.signal.aborted) return [];
+		const terminal = pending.map((entry) => ({
+			deviceId: entry.saved.id,
+			stableId: entry.saved.stableId,
+			type: String(entry.saved.type),
+			attempts: entry.attempts,
+			lastError: entry.lastError,
+			failedAt: this.#now()
+		}));
+		for (const failure of terminal) this.#onPermanentFailure(failure);
+		return terminal;
+	}
+	/** One retry round: parents first (phase 0), then hub-adopted
+	*  children (phase 1) — a child's attempt depends on its parent
+	*  having landed, exactly like the initial two-pass restore. */
+	async #runRound(pending, round) {
+		const next = [];
+		const parents = pending.filter((entry) => entry.saved.parentDeviceId === null);
+		const children = pending.filter((entry) => entry.saved.parentDeviceId !== null);
+		for (const phase of [parents, children]) await runWithConcurrency(phase, this.#concurrency, async (entry) => {
+			if (this.#abort.signal.aborted) {
+				next.push(entry);
+				return;
+			}
+			const attemptNo = entry.attempts + 1;
+			try {
+				await this.#attempt(entry.saved);
+				this.#logger.info("Device restored on retry", {
+					tags: {
+						deviceId: entry.saved.id,
+						stableId: entry.saved.stableId
+					},
+					meta: { attempt: attemptNo }
+				});
+			} catch (err) {
+				const lastError = err instanceof Error ? err.message : String(err);
+				const remainingRetries = this.#delaysMs.length - (round + 1);
+				this.#logger.warn("Device restore retry failed", {
+					tags: {
+						deviceId: entry.saved.id,
+						stableId: entry.saved.stableId
+					},
+					meta: {
+						attempt: attemptNo,
+						remainingRetries,
+						error: lastError
+					}
+				});
+				next.push({
+					saved: entry.saved,
+					lastError,
+					attempts: attemptNo
+				});
+			}
+		});
+		return next;
+	}
+};
+//#endregion
 //#region src/device/base-device-provider.ts
 /**
 * Convert an IDevice to the flat DeviceSummary shape expected by the
@@ -36298,6 +36624,7 @@ var BaseDeviceProvider = class extends require_sleep.BaseAddon {
 		}];
 	}
 	async onShutdown() {
+		this.cancelRestoreRetries();
 		const devices = await this.ctx.kernel.devices?.getAll() ?? [];
 		for (const device of devices) try {
 			await this.ctx.kernel.devices?.decommission(device.id);
@@ -36315,9 +36642,16 @@ var BaseDeviceProvider = class extends require_sleep.BaseAddon {
 	async start() {}
 	async stop() {}
 	async getStatus() {
+		const all = await this.ctx.kernel.devices?.getAll() ?? [];
+		const summary = this.restoreFailureSummary();
+		if (summary === null) return {
+			connected: true,
+			deviceCount: all.length
+		};
 		return {
 			connected: true,
-			deviceCount: (await this.ctx.kernel.devices?.getAll() ?? []).length
+			deviceCount: all.length,
+			error: summary
 		};
 	}
 	async getDevices() {
@@ -36407,8 +36741,137 @@ var BaseDeviceProvider = class extends require_sleep.BaseAddon {
 		};
 	}
 	async restoreDevices(savedDevices) {
-		await this.onRestoreDevices(savedDevices);
-		if (savedDevices.length > 0) this.ctx.logger.info(`Restored ${savedDevices.length} ${this.providerName} device(s)`);
+		const report = await this.onRestoreDevices(savedDevices);
+		if (savedDevices.length === 0) return;
+		if (report && report.failedCount > 0) {
+			this.ctx.logger.warn(`Restored ${report.restoredCount}/${savedDevices.length} ${this.providerName} device(s) — ${report.failedCount} failed, bounded retry scheduled`);
+			return;
+		}
+		const restoredCount = report ? report.restoredCount : savedDevices.length;
+		this.ctx.logger.info(`Restored ${restoredCount} ${this.providerName} device(s)`);
+	}
+	/** Retry schedule. Overridable (tests use millisecond delays). */
+	restoreRetryDelaysMs = DEVICE_RESTORE_RETRY_DELAYS_MS;
+	/** Retry lane width. See `device-restore-retry.ts` for why retries
+	*  never re-stampede full-width while the initial pass does (D167). */
+	restoreRetryConcurrency = 4;
+	_restoreRetryScheduler = null;
+	_restoreRetryCompletion = null;
+	_permanentRestoreFailures = /* @__PURE__ */ new Map();
+	/** 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. */
+	get restoreRetryCompletion() {
+		return this._restoreRetryCompletion;
+	}
+	/** Devices that exhausted the retry bound this process lifetime. */
+	get permanentRestoreFailures() {
+		return [...this._permanentRestoreFailures.values()];
+	}
+	/** One-line operator-facing summary for `getStatus().error`, or
+	*  `null` when every device restored. */
+	restoreFailureSummary() {
+		if (this._permanentRestoreFailures.size === 0) return null;
+		const ids = [...this._permanentRestoreFailures.keys()].join(", ");
+		return `${this._permanentRestoreFailures.size} device(s) permanently failed restore (deviceIds: ${ids}) — restart the ${this.providerName} provider to retry`;
+	}
+	cancelRestoreRetries() {
+		this._restoreRetryScheduler?.cancel();
+		this._restoreRetryScheduler = null;
+	}
+	recordPermanentRestoreFailure(failure) {
+		this._permanentRestoreFailures.set(failure.deviceId, failure);
+		this.ctx.logger.error("Device restore permanently failed — its capabilities will not register until the provider restarts", {
+			tags: {
+				deviceId: failure.deviceId,
+				stableId: failure.stableId
+			},
+			meta: {
+				type: failure.type,
+				attempts: failure.attempts,
+				error: failure.lastError
+			}
+		});
+	}
+	scheduleRestoreRetries(failures, attempt) {
+		const scheduler = new DeviceRestoreRetryScheduler({
+			logger: this.ctx.logger,
+			delaysMs: this.restoreRetryDelaysMs,
+			concurrency: this.restoreRetryConcurrency,
+			attempt,
+			onPermanentFailure: (failure) => this.recordPermanentRestoreFailure(failure)
+		});
+		this._restoreRetryScheduler = scheduler;
+		this._restoreRetryCompletion = scheduler.run(failures).then(() => void 0).catch((err) => {
+			this.ctx.logger.error("Restore retry scheduler crashed", { meta: { error: err instanceof Error ? err.message : String(err) } });
+		});
+	}
+	/**
+	* 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.
+	*/
+	async reloadDevice(input) {
+		const { stableId } = input;
+		const devices = this.ctx.kernel.devices;
+		if (!devices) throw new Error(`${this.providerName}: kernel.devices unavailable — cannot reload`);
+		const live = (await devices.getAll()).find((d) => d.stableId === stableId);
+		if (live) await devices.decommission(live.id);
+		const { id } = await this.ctx.api.deviceManager.allocateDeviceId.mutate({
+			addonId: this.addonId,
+			stableId
+		});
+		const meta = await this.ctx.api.deviceManager.loadMeta.query({ deviceId: id });
+		if (meta === null) throw new Error(`${this.providerName}: no persisted meta for "${stableId}" (id ${id}) — cannot reload`);
+		const deviceType = Object.values(require_sleep.DeviceType).find((t) => t === meta.type);
+		const Class = deviceType !== void 0 ? this.deviceClasses[deviceType] : void 0;
+		if (!Class) throw new Error(`${this.providerName}: no device class for type "${meta.type}" — "${stableId}" is an accessory child; reload its parent instead`);
+		await devices.create(stableId, Class, {}, meta.parentDeviceId ?? null);
+		const rows = await this.ctx.api.deviceManager.listPersistedByAddon.query({ addonId: this.addonId });
+		for (const row of rows) {
+			if (row.parentDeviceId !== id) continue;
+			const childType = Object.values(require_sleep.DeviceType).find((t) => t === row.type);
+			const ChildClass = childType !== void 0 ? this.deviceClasses[childType] : void 0;
+			if (!ChildClass) continue;
+			try {
+				await devices.create(row.stableId, ChildClass, {}, id);
+			} catch (err) {
+				this.ctx.logger.warn("reloadDevice: failed to re-create first-class child", {
+					tags: {
+						deviceId: row.id,
+						stableId: row.stableId
+					},
+					meta: {
+						parentDeviceId: id,
+						error: err instanceof Error ? err.message : String(err)
+					}
+				});
+			}
+		}
+		this.ctx.logger.info("device reloaded in place from persisted rows", {
+			tags: { deviceId: id },
+			meta: {
+				stableId,
+				type: meta.type
+			}
+		});
+		return { deviceId: id };
 	}
 	/**
 	* Restore devices from persisted state. Two-pass:
@@ -36434,55 +36897,108 @@ var BaseDeviceProvider = class extends require_sleep.BaseAddon {
 	* 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`.
 	*/
 	async onRestoreDevices(savedDevices) {
 		const restored = /* @__PURE__ */ new Set();
+		const failures = [];
+		const attemptRestore = async (saved) => {
+			if (restored.has(saved.id)) return;
+			const Class = this.deviceClasses[saved.type];
+			if (!Class) throw new Error(`no device class registered for type "${saved.type}"`);
+			if (saved.parentDeviceId !== null && !restored.has(saved.parentDeviceId)) throw new Error(`parent device ${saved.parentDeviceId} not restored`);
+			await this.ctx.kernel.devices.create(saved.stableId, Class, {}, saved.parentDeviceId);
+			restored.add(saved.id);
+		};
 		const topLevel = savedDevices.filter((saved) => saved.parentDeviceId === null);
 		const restoreOne = async (saved) => {
-			const Class = this.deviceClasses[saved.type];
-			if (!Class) {
+			if (!this.deviceClasses[saved.type]) {
 				this.ctx.logger.warn("No device class registered for restored type — skipping", {
-					tags: { stableId: saved.stableId },
+					tags: {
+						deviceId: saved.id,
+						stableId: saved.stableId
+					},
 					meta: { type: saved.type }
 				});
 				return;
 			}
 			try {
-				await this.ctx.kernel.devices.create(saved.stableId, Class, {});
-				restored.add(saved.id);
+				await attemptRestore(saved);
 			} catch (err) {
-				this.ctx.logger.warn("Failed to restore device", {
-					tags: { stableId: saved.stableId },
+				const error = err instanceof Error ? err.message : String(err);
+				this.ctx.logger.warn("Failed to restore device — bounded retry scheduled", {
+					tags: {
+						deviceId: saved.id,
+						stableId: saved.stableId
+					},
 					meta: {
 						type: saved.type,
-						error: err instanceof Error ? err.message : String(err)
+						attempt: 1,
+						error
 					}
 				});
+				failures.push({
+					saved,
+					error
+				});
 			}
 		};
 		await Promise.all(topLevel.map((saved) => restoreOne(saved)));
+		const failedTopLevelIds = new Set(failures.map((failure) => failure.saved.id));
 		const childRows = savedDevices.filter((s) => s.parentDeviceId !== null);
 		for (const saved of childRows) {
-			const Class = this.deviceClasses[saved.type];
-			if (!Class) continue;
+			if (!this.deviceClasses[saved.type]) continue;
 			if (saved.parentDeviceId === null) continue;
-			if (!restored.has(saved.parentDeviceId)) continue;
-			try {
-				await this.ctx.kernel.devices.create(saved.stableId, Class, {}, saved.parentDeviceId);
-				restored.add(saved.id);
-			} catch (err) {
-				this.ctx.logger.warn("Failed to restore hub-adopted child", {
+			if (restored.has(saved.parentDeviceId)) {
+				try {
+					await attemptRestore(saved);
+				} catch (err) {
+					const error = err instanceof Error ? err.message : String(err);
+					this.ctx.logger.warn("Failed to restore hub-adopted child — bounded retry scheduled", {
+						tags: {
+							deviceId: saved.id,
+							stableId: saved.stableId,
+							parentDeviceId: saved.parentDeviceId
+						},
+						meta: {
+							type: saved.type,
+							attempt: 1,
+							error
+						}
+					});
+					failures.push({
+						saved,
+						error
+					});
+				}
+				continue;
+			}
+			if (failedTopLevelIds.has(saved.parentDeviceId)) {
+				this.ctx.logger.warn("Hub-adopted child deferred — parent failed initial restore", {
 					tags: {
+						deviceId: saved.id,
 						stableId: saved.stableId,
 						parentDeviceId: saved.parentDeviceId
 					},
-					meta: {
-						type: saved.type,
-						error: err instanceof Error ? err.message : String(err)
-					}
+					meta: { type: saved.type }
+				});
+				failures.push({
+					saved,
+					error: `parent device ${saved.parentDeviceId} not restored`
 				});
+				continue;
 			}
 		}
+		if (failures.length > 0) this.scheduleRestoreRetries(failures, attemptRestore);
+		return {
+			restoredCount: restored.size,
+			failedCount: failures.length
+		};
 	}
 	/** Convert an IDevice to the flat DeviceSummary for the cap router. */
 	toSummary(device) {
@@ -39636,6 +40152,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"backup.cancel": {
+		capName: "backup",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"backup.delete": {
 		capName: "backup",
 		capScope: "system",
@@ -39678,6 +40200,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"backup.listRuns": {
+		capName: "backup",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"backup.listSchedules": {
 		capName: "backup",
 		capScope: "system",
@@ -40878,6 +41406,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"deviceProvider.reloadDevice": {
+		capName: "device-provider",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"deviceProvider.start": {
 		capName: "device-provider",
 		capScope: "system",
@@ -44244,6 +44778,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"streamBroker.forgetDeviceHardware": {
+		capName: "stream-broker",
+		capScope: "system",
+		addonId: null,
+		access: "delete"
+	},
 	"streamBroker.getAllRtspEntries": {
 		capName: "stream-broker",
 		capScope: "system",
@@ -46965,6 +47505,11 @@ var METHOD_DEVICE_SELECTORS = Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"streamBroker.forgetDeviceHardware": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"streamBroker.getDeviceAudioMute": [{
 		name: "deviceId",
 		form: "single",
@@ -47338,6 +47883,7 @@ var SYSTEM_SCOPE_DEVICE_METHODS = [
 	"recordingExport.listExports",
 	"streamBroker.acquireEgressTranscode",
 	"streamBroker.assignProfile",
+	"streamBroker.forgetDeviceHardware",
 	"streamBroker.getDeviceAudioMute",
 	"streamBroker.getStreamWithCodec",
 	"streamBroker.produceEventMedia",
@@ -47881,6 +48427,8 @@ function createSystemProxy(api) {
 		backup: {
 			listDestinations: (input) => dispatch("backup", "listDestinations", "query", input),
 			trigger: (input) => dispatch("backup", "trigger", "mutation", input),
+			listRuns: (input) => dispatch("backup", "listRuns", "query", input),
+			cancel: (input) => dispatch("backup", "cancel", "mutation", input),
 			list: (input) => dispatch("backup", "list", "query", input),
 			listLocations: (input) => dispatch("backup", "listLocations", "query", input),
 			getEntries: (input) => dispatch("backup", "getEntries", "query", input),
@@ -52450,6 +52998,10 @@ exports.BOOT_RECOVERY_BACKOFF_MS = require_sleep.BOOT_RECOVERY_BACKOFF_MS;
 exports.BacklightModeSchema = BacklightModeSchema;
 exports.BackupDestinationInfoSchema = BackupDestinationInfoSchema;
 exports.BackupEntrySchema = BackupEntrySchema;
+exports.BackupRunPhaseSchema = BackupRunPhaseSchema;
+exports.BackupRunSchema = BackupRunSchema;
+exports.BackupRunStateSchema = BackupRunStateSchema;
+exports.BackupTriggerResultSchema = BackupTriggerResultSchema;
 exports.BaseAddon = require_sleep.BaseAddon;
 exports.BaseDevice = BaseDevice;
 exports.BaseDeviceProvider = BaseDeviceProvider;
@@ -52606,6 +53158,8 @@ exports.DEVICE_BACKEND_TO_FORMAT = DEVICE_BACKEND_TO_FORMAT;
 exports.DEVICE_CAP_NAMES = DEVICE_CAP_NAMES;
 exports.DEVICE_CHILDREN_BATCH_MAX = DEVICE_CHILDREN_BATCH_MAX;
 exports.DEVICE_PROFILES = DEVICE_PROFILES;
+exports.DEVICE_RESTORE_RETRY_CONCURRENCY = DEVICE_RESTORE_RETRY_CONCURRENCY;
+exports.DEVICE_RESTORE_RETRY_DELAYS_MS = DEVICE_RESTORE_RETRY_DELAYS_MS;
 exports.DEVICE_SCOPED_CAPS = require_sleep.DEVICE_SCOPED_CAPS;
 exports.DEVICE_SETTINGS_CONTRIBUTION_METHODS = require_sleep.DEVICE_SETTINGS_CONTRIBUTION_METHODS;
 exports.DEVICE_STATE_READERS = DEVICE_STATE_READERS;
@@ -52635,6 +53189,7 @@ exports.DeviceExportUnexposeInputSchema = UnexposeInputSchema;
 exports.DeviceFeature = require_sleep.DeviceFeature;
 exports.DeviceInfoSchema = DeviceInfoSchema;
 exports.DeviceNetworkStatsSchema = DeviceNetworkStatsSchema;
+exports.DeviceRestoreRetryScheduler = DeviceRestoreRetryScheduler;
 exports.DeviceRole = require_sleep.DeviceRole;
 exports.DeviceRuntimeState = DeviceRuntimeState;
 exports.DeviceSelectorSchema = DeviceSelectorSchema;