@camstack/system 1.2.179 → 1.2.181

package/dist/builtins/backup-orchestrator/run-queue.d.ts

@@ -0,0 +1,103 @@
+export type BackupRunState = 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled';
+export type BackupRunPhase = 'queued' | 'building' | 'uploading' | 'done';
+/** What a trigger asks for — the queue keys joining on this. */
+export interface BackupRunRequest {
+    readonly destinations?: readonly string[];
+    readonly locations?: readonly string[];
+    readonly label?: string;
+    readonly retentionCount?: number;
+}
+/** Immutable snapshot of one run — the wire shape of `backup.listRuns`. */
+export interface BackupRunSnapshot {
+    readonly id: string;
+    readonly state: BackupRunState;
+    readonly phase: BackupRunPhase;
+    readonly destinationIds: readonly string[];
+    readonly label?: string;
+    readonly requestedAt: number;
+    readonly startedAt?: number;
+    readonly finishedAt?: number;
+    readonly stagedBytes: number;
+    readonly archiveSizeBytes?: number;
+    readonly uploadedBytes: number;
+    readonly completedDestinationIds: readonly string[];
+    readonly failedDestinationIds: readonly string[];
+    readonly error?: string;
+    /**
+     * 1-based place in the execution queue — 1 = runs next. Present only
+     * while `state === 'queued'`, and derived from the queue's OWN
+     * pending order at read time (never from timestamps), so a consumer
+     * can only ever show the order the executor will actually honour.
+     */
+    readonly queuePosition?: number;
+}
+/**
+ * Progress sink handed to the executor. Every update replaces the
+ * stored snapshot (no shared mutable state leaks out of the queue).
+ */
+export interface BackupRunProgress {
+    setPhase(phase: BackupRunPhase): void;
+    /** Resolved destination targets — known only once the run starts. */
+    setDestinations(ids: readonly string[]): void;
+    setStagedBytes(bytes: number): void;
+    setArchiveSize(bytes: number): void;
+    setUploadedBytes(bytes: number): void;
+    destinationCompleted(id: string): void;
+    destinationFailed(id: string): void;
+}
+export interface SubmitResult<T> {
+    readonly runId: string;
+    /** True when the run had to wait behind an in-flight run. */
+    readonly queued: boolean;
+    /** True when this submit was coalesced onto an identical queued run. */
+    readonly joined: boolean;
+    /** Settles when the run terminates. Rejects `BackupCancelledError` on cancel-before-any-result. */
+    readonly result: Promise<T>;
+}
+export type BackupRunExecutor<T> = (request: BackupRunRequest, signal: AbortSignal, progress: BackupRunProgress) => Promise<T>;
+export interface BackupRunQueueOptions {
+    readonly maxFinished?: number;
+    readonly now?: () => number;
+}
+/**
+ * FIFO queue with concurrency 1. `submit` never starts a second
+ * executor while one is in flight; an identical request already
+ * WAITING (same destinations/locations/label/retention) is joined
+ * instead of queued twice — two schedule ticks due on the same minute
+ * produce one run, not two.
+ */
+export declare class BackupRunQueue<T> {
+    private readonly executor;
+    private readonly runs;
+    private readonly pending;
+    private readonly finished;
+    private activeId;
+    private readonly maxFinished;
+    private readonly now;
+    constructor(executor: BackupRunExecutor<T>, opts?: BackupRunQueueOptions);
+    submit(request: BackupRunRequest): SubmitResult<T>;
+    /**
+     * Cancel a run. Queued: removed before it ever starts (its result
+     * rejects `BackupCancelledError`). Running: the abort signal fires —
+     * the executor's tar/upload streams stop and its cleanup runs.
+     * Unknown or already terminal: `false`.
+     */
+    cancel(runId: string): boolean;
+    /**
+     * EXECUTION order, not timestamp order: the running run first, then
+     * every queued run in the exact order the pump will start them (each
+     * stamped with `queuePosition`, 1 = next), then the bounded finished
+     * history newest-first. The queued section is read straight off
+     * `this.pending` — a consumer sorting by `requestedAt` descending
+     * would put the run that starts NEXT at the BOTTOM, which is
+     * backwards exactly when the queue matters (more than one waiter).
+     */
+    listRuns(): readonly BackupRunSnapshot[];
+    getRun(runId: string): BackupRunSnapshot | undefined;
+    private createRecord;
+    private pump;
+    private execute;
+    private progressFor;
+    private patch;
+    private finish;
+}

package/dist/builtins/backup-orchestrator/staging-paths.d.ts

@@ -0,0 +1,36 @@
+import { IScopedLogger } from '@camstack/types';
+/** Basename of the staging dir under the node data root. */
+export declare const STAGING_DIR_NAME = "backup-staging";
+/** Canonical staging dir for a node data root. */
+export declare function resolveStagingDir(nodeDataDir: string): string;
+export interface StagingSweepResult {
+    /** Top-level staging entries removed. */
+    readonly removedCount: number;
+    /** File bytes reclaimed (recursive for removed subdirectories). */
+    readonly freedBytes: number;
+    /** Entries spared because `keepPaths` named them. */
+    readonly keptCount: number;
+}
+export interface DirectoryFootprint {
+    readonly present: boolean;
+    readonly totalBytes: number;
+    readonly fileCount: number;
+}
+/**
+ * Delete every top-level entry of `stagingDir` except those whose
+ * resolved path appears in `keepPaths`. Per-entry failures are logged
+ * and skipped — a locked file must not abort the sweep. A missing
+ * staging dir is a clean no-op.
+ */
+export declare function sweepStagingDir(input: {
+    stagingDir: string;
+    keepPaths: readonly string[];
+    logger: IScopedLogger;
+}): Promise<StagingSweepResult>;
+/**
+ * Recursive size + file count of a path (file or directory). Absent
+ * path → `present: false` with zeros. Used by the sweep to report
+ * reclaimed bytes and by the orchestrator to surface the legacy
+ * staging dir's footprint without touching it.
+ */
+export declare function measureDirectoryFootprint(dir: string): Promise<DirectoryFootprint>;

package/dist/builtins/console-logging/index.js

@@ -3,7 +3,7 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-C7qWwrK1.js");
+const require_dist = require("../../dist-whe0b4_3.js");
 const require_formatter = require("../../formatter-DqAKDlvN.js");
 //#region src/builtins/console-logging/console-destination.ts
 var LEVEL_RANK = {

package/dist/builtins/console-logging/index.mjs

@@ -1,4 +1,4 @@
-import { Ft as BaseAddon, ct as logDestinationCapability } from "../../dist-L_39vRmH.mjs";
+import { Ft as BaseAddon, ct as logDestinationCapability } from "../../dist-DbnNk4Lw.mjs";
 import { t as formatLogLine } from "../../formatter-B7qW8bPJ.mjs";
 //#region src/builtins/console-logging/console-destination.ts
 var LEVEL_RANK = {

package/dist/builtins/core-blocks/core-blocks.addon.js

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_chunk = require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-C7qWwrK1.js");
+const require_dist = require("../../dist-whe0b4_3.js");
 let node_crypto = require("node:crypto");
 let node_fs_promises = require("node:fs/promises");
 node_fs_promises = require_chunk.__toESM(node_fs_promises);

package/dist/builtins/core-blocks/core-blocks.addon.mjs

@@ -1,4 +1,4 @@
-import { Ft as BaseAddon, I as coreBlockAddonId, L as coreBlockIdFromAddonId, Pt as errMsg, R as coreBlocksCapability, c as CORE_BLOCK_ADDON_PREFIX, d as DeclaredDevices, l as CoreBlockSchema, s as CORE_BLOCKS_ADDON_ID } from "../../dist-L_39vRmH.mjs";
+import { Ft as BaseAddon, I as coreBlockAddonId, L as coreBlockIdFromAddonId, Pt as errMsg, R as coreBlocksCapability, c as CORE_BLOCK_ADDON_PREFIX, d as DeclaredDevices, l as CoreBlockSchema, s as CORE_BLOCKS_ADDON_ID } from "../../dist-DbnNk4Lw.mjs";
 import { randomUUID } from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as path$1 from "node:path";

package/dist/builtins/device-manager/device-manager.addon.js

@@ -3,8 +3,8 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-C7qWwrK1.js");
-const require_retired_settings_keys = require("../../retired-settings-keys-3soU9pfP.js");
+const require_dist = require("../../dist-whe0b4_3.js");
+const require_retired_settings_keys = require("../../retired-settings-keys-BdvmiaK7.js");
 let node_crypto = require("node:crypto");
 let _camstack_types_node = require("@camstack/types/node");
 //#region src/builtins/device-manager/adoption-job-engine.ts
@@ -2114,7 +2114,13 @@ function resolveLinkedDeviceIds(params) {
 	if (config.mode === "auto") {
 		if (selfLocation !== null && selfLocation.length > 0) for (const c of candidates) {
 			if (c.type === require_dist.DeviceType.Container) continue;
-			if (c.location === selfLocation) ids.add(c.id);
+			if (c.location !== selfLocation) continue;
+			const parent = c.parentDeviceId !== null ? byId.get(c.parentDeviceId) : void 0;
+			if (parent !== void 0 && parent.type === require_dist.DeviceType.Container) {
+				expand(parent.id);
+				continue;
+			}
+			ids.add(c.id);
 		}
 	} else for (const id of config.manualIds) if (byId.has(id)) expand(id);
 	ids.delete(selfId);
@@ -3274,8 +3280,6 @@ var DeviceEventPropagator = class {
 		return chain;
 	}
 };
-//#endregion
-//#region src/builtins/device-manager/migrate-device.ts
 /** A refusal that names a switch the camera does not offer, rather than one it
 *  could not be asked about. The cap documents rejecting the former; anything
 *  else is treated as the camera being out of reach, which is the safe reading:
@@ -3287,10 +3291,31 @@ function classify(err) {
 		detail
 	};
 }
+/**
+* One switch write under the bound. The race, not the write, is what fails on
+* timeout — the underlying promise is marked handled so a late rejection from
+* a camera that eventually answers "no" cannot surface as an unhandled
+* rejection after the migration already reported `unreachable`.
+*/
+async function setSwitchBounded(deps, deviceId, switchId, enabled) {
+	const budget = deps.switchTimeoutMs ?? 15e3;
+	const write = deps.setSwitch(deviceId, switchId, enabled);
+	write.catch(() => {});
+	let timer;
+	try {
+		await Promise.race([write, new Promise((_resolve, reject) => {
+			timer = setTimeout(() => {
+				reject(/* @__PURE__ */ new Error(`switch write did not answer within ${budget}ms — reported unreachable; if it lands late, a duplicate write of the same value is a no-op`));
+			}, budget);
+		})]);
+	} finally {
+		if (timer !== void 0) clearTimeout(timer);
+	}
+}
 async function applyAll(deps, deviceId, enabled) {
 	const out = [];
 	for (const switchId of require_dist.CAMERA_SWITCH_ORDER) try {
-		await deps.setSwitch(deviceId, switchId, enabled);
+		await setSwitchBounded(deps, deviceId, switchId, enabled);
 		out.push({
 			deviceId,
 			switchId,
@@ -3327,8 +3352,17 @@ async function migrateDevice$1(deps, input) {
 	const down = [...await applyAll(deps, sourceId, false), ...await applyAll(deps, targetId, false)];
 	const sourceStillLive = down.filter((r) => r.deviceId === sourceId && r.outcome === "unreachable").map((r) => r.switchId);
 	await deps.swapIds(sourceId, targetId);
+	await deps.swapHardwareState(sourceId, targetId);
+	for (const deviceId of [sourceId, targetId]) try {
+		await deps.forgetStreamState(deviceId);
+	} catch (err) {
+		deps.log("migration: broker hardware state NOT forgotten — stale stream state survives", {
+			deviceId,
+			error: err instanceof Error ? err.message : String(err),
+			remedy: "delete the device's derived streams and reassign its stream profiles, or update the stream-broker addon and re-run streamBroker.forgetDeviceHardware"
+		});
+	}
 	const up = await applyAll(deps, sourceId, true);
-	await deps.respawnRunners([sourceId, targetId]);
 	deps.log("camera migrated", {
 		sourceId,
 		targetId,
@@ -3344,6 +3378,148 @@ async function migrateDevice$1(deps, input) {
 	};
 }
 //#endregion
+//#region src/builtins/device-manager/migrate-reload.ts
+async function reloadMigratedDevices(pctx, targets) {
+	const ctx = pctx.host.ctx;
+	for (const target of targets) {
+		pctx.metaStore.idToAddonId.set(target.deviceId, target.addonId);
+		pctx.host.remoteNativeCaps.delete(target.deviceId);
+		pctx.host.capabilityRegistry?.unregisterAllNativeForDevice(target.deviceId);
+	}
+	const fallbackAddons = /* @__PURE__ */ new Map();
+	await Promise.all(targets.map(async (target) => {
+		try {
+			const reloaded = await (await pctx.host.requireDeviceProvider(target.addonId)).reloadDevice({ stableId: target.stableId });
+			ctx.logger.info("migration: device reloaded in place — no other device disturbed", {
+				tags: { deviceId: target.deviceId },
+				meta: {
+					addonId: target.addonId,
+					stableId: target.stableId,
+					reloadedAs: reloaded.deviceId
+				}
+			});
+		} catch (err) {
+			ctx.logger.error("migration: in-place reload FAILED — falling back to a provider restart", {
+				tags: { deviceId: target.deviceId },
+				meta: {
+					addonId: target.addonId,
+					stableId: target.stableId,
+					error: err instanceof Error ? err.message : String(err)
+				}
+			});
+			fallbackAddons.set(target.addonId, target.deviceId);
+		}
+	}));
+	if (fallbackAddons.size === 0) return;
+	await Promise.all([...fallbackAddons.entries()].map(async ([addonId, migratedDeviceId]) => {
+		const owned = [...pctx.metaStore.idToAddonId.entries()].filter(([, a]) => a === addonId).length;
+		ctx.logger.info("migration: restarting a whole provider to flush the id maps", {
+			tags: { deviceId: migratedDeviceId },
+			meta: {
+				addonId,
+				devicesTakenDown: owned
+			}
+		});
+		await ctx.api.addons.restartAddon.mutate({ addonId });
+	}));
+}
+//#endregion
+//#region src/builtins/device-manager/migrate-hardware-state.ts
+/**
+* The per-device state half of a migration (`deviceManager.migrateDevice`).
+*
+* ## The rule
+*
+* **Role-scoped state follows the NUMBER. Hardware-scoped state follows the
+* DEVICE.** `swapIds` moves the device ROWS — `addonId` and `stableId` follow
+* the hardware — but the per-device CONFIG blob and the runtime-state blob are
+* keyed by the number in a separate store, and until 2026-09-01 they simply
+* stayed put. Measured on the live hub after replacing a Hikvision (id 618)
+* with a Reolink: device 618 — Reolink hardware — was dialled at
+* `192.168.1.245:80` with `deviceCache.model="DS-2DE2A404IW-DE3/W"`, the
+* Hikvision's address, credentials and cached model, and never came online.
+* Device 4362 wore the Reolink's config on Hikvision hardware. The two devices
+* were wearing each other's identity.
+*
+* The proof the config belongs to the hardware, not the number: writing the
+* Hikvision blob onto the Reolink was REJECTED by the Reolink driver's own
+* zod schema (`motionSensitivity: 60` vs max 50). A config that fails the
+* other provider's schema is a config for different hardware.
+*
+* ## What swaps, what stays
+*
+*  - The DRIVER config keys (host, port, credentials, `deviceCache`, every
+*    schema field) SWAP — they describe the box.
+*  - The device-manager-owned section keys ({@link DEVICE_STORE_SECTIONS}:
+*    linked-devices mode/ids) STAY with the number — a sensor is linked to
+*    "the driveway camera", not to a serial number.
+*  - `_profileMap` is DROPPED from both. It is the legacy spelling of the
+*    stream-profile assignment (the live authority is the stream broker's own
+*    map — see `StreamsTab.tsx`, which stopped writing it), and either copy
+*    names stream ids of the wrong hardware after a swap.
+*  - The runtime-state blobs (`__device-state:<id>` — battery snapshot, sleep
+*    flag, feature probe) SWAP wholesale: every slice mirrors the box.
+*
+* ## Crash points are loud, same as `swapIds`
+*
+* There is no transaction: each blob is cleared and rewritten. A crash between
+* clear and write leaves a device with NO config — a provider that fails to
+* construct and says so — never two devices wearing each other's, which is the
+* state that reads as plausible and costs a day.
+*/
+/** Legacy stream-profile assignment key (cf. `device-queries.ts`). */
+var PROFILE_MAP_CONFIG_KEY = "_profileMap";
+/** Config keys that belong to the camera's ROLE and stay with the number. */
+var ROLE_SCOPED_CONFIG_KEYS = new Set(DEVICE_STORE_SECTIONS.flatMap((section) => [...section.keys]));
+function splitConfig(config) {
+	const hardware = {};
+	const role = {};
+	for (const [key, value] of Object.entries(config)) {
+		if (key === PROFILE_MAP_CONFIG_KEY) continue;
+		if (ROLE_SCOPED_CONFIG_KEYS.has(key)) role[key] = value;
+		else hardware[key] = value;
+	}
+	return {
+		hardware,
+		role
+	};
+}
+/**
+* Swap the hardware-scoped halves of two devices' persisted state. Runs right
+* after `swapIds`, under the same meta write lock. THROWS on failure: a
+* migration whose rows swapped but whose configs did not is exactly the
+* incident this module exists to prevent, and it must never be reported as a
+* success.
+*/
+async function swapHardwareState(settings, sourceId, targetId) {
+	const sourceConfig = await settings.readDeviceStore(sourceId);
+	const targetConfig = await settings.readDeviceStore(targetId);
+	const source = splitConfig(sourceConfig);
+	const target = splitConfig(targetConfig);
+	await settings.clearDeviceStore(sourceId);
+	await settings.writeDeviceStore(sourceId, {
+		...target.hardware,
+		...source.role
+	});
+	await settings.clearDeviceStore(targetId);
+	await settings.writeDeviceStore(targetId, {
+		...source.hardware,
+		...target.role
+	});
+	const sourceRuntimeState = await settings.readDeviceRuntimeState(sourceId);
+	const targetRuntimeState = await settings.readDeviceRuntimeState(targetId);
+	await settings.writeDeviceRuntimeState(sourceId, targetRuntimeState);
+	await settings.writeDeviceRuntimeState(targetId, sourceRuntimeState);
+	return {
+		runtimeStateNowAtSource: targetRuntimeState,
+		runtimeStateNowAtTarget: sourceRuntimeState,
+		hardwareKeysToSource: Object.keys(target.hardware).toSorted(),
+		hardwareKeysToTarget: Object.keys(source.hardware).toSorted(),
+		roleKeysKeptAtSource: Object.keys(source.role).toSorted(),
+		roleKeysKeptAtTarget: Object.keys(target.role).toSorted()
+	};
+}
+//#endregion
 //#region src/builtins/device-manager/device-meta-actions.ts
 /**
 * Device meta-mutation + persistence actions for the device-manager addon —
@@ -3423,48 +3599,126 @@ async function allocateDeviceId(pctx, input) {
 * The composition lives in `migrate-device.ts`, deliberately free of this
 * file's context so the decisions it carries — above all "never report a switch
 * as off when it could not be written" — are testable without a hub. This is
-* the wiring: the four real dependencies, and the write lock.
+* the wiring: the real dependencies, and the write lock.
 *
 * The temp id comes from `allocateNextDeviceId`, the monotonic counter, so the
 * value a crash could park a row on was never used and will never be reused.
 * `swapIds` therefore runs INSIDE the same lock the id was allocated under.
+*
+* Retry-safe since 2026-09-04 (`migrate-guard.ts`): a concurrent call touching
+* either device is REFUSED before it can queue on the lock, and a repeat of a
+* completed swap — matched against the `addonId`/`stableId` fingerprint the
+* swap left on the rows — is a no-op returning the original report. A client
+* retry ran a second full cycle on 2026-09-01 and swapped two cameras back;
+* neither path can re-run a swap any more.
 */
 async function migrateDevice(pctx, input) {
 	const { sourceId, targetId } = input;
 	const ctx = pctx.host.ctx;
-	return await pctx.metaStore.withMetaWriteLock(async () => {
-		for (const id of [sourceId, targetId]) if (await pctx.metaStore.rows.get(id) === null) throw new Error(`[device-manager] migrateDevice: device ${id} does not exist`);
-		const tempId = await pctx.metaStore.allocateNextDeviceId();
-		return await migrateDevice$1({
-			setSwitch: async (deviceId, switchId, enabled) => {
-				await ctx.api.pipelineOrchestrator.setCameraSwitch.mutate({
-					deviceId,
-					switchId,
-					enabled
-				});
-			},
-			swapIds: async (a, b) => {
-				await pctx.metaStore.rows.swapIds(a, b, tempId);
-			},
-			respawnRunners: async (deviceIds) => {
-				const owners = /* @__PURE__ */ new Set();
-				for (const deviceId of deviceIds) {
-					const addonId = pctx.metaStore.idToAddonId.get(deviceId);
-					if (addonId !== void 0) owners.add(addonId);
-				}
-				for (const addonId of owners) await ctx.api.addons.restartAddon.mutate({ addonId });
-			},
-			log: (message, meta) => {
-				ctx.logger.info(message, {
+	pctx.migrationGuard.begin(sourceId, targetId);
+	try {
+		const outcome = await pctx.metaStore.withMetaWriteLock(async () => {
+			const sourceRow = await pctx.metaStore.rows.get(sourceId);
+			if (sourceRow === null) throw new Error(`[device-manager] migrateDevice: device ${sourceId} does not exist`);
+			const targetRow = await pctx.metaStore.rows.get(targetId);
+			if (targetRow === null) throw new Error(`[device-manager] migrateDevice: device ${targetId} does not exist`);
+			const replay = pctx.migrationGuard.matchReplay(sourceId, targetId, {
+				addonId: sourceRow.meta.addonId,
+				stableId: sourceRow.meta.stableId
+			}, {
+				addonId: targetRow.meta.addonId,
+				stableId: targetRow.meta.stableId
+			});
+			if (replay !== null) {
+				ctx.logger.info("migrateDevice: this swap already completed — replaying the original report, NOTHING re-run", {
 					tags: { deviceId: sourceId },
-					meta
+					meta: {
+						sourceId,
+						targetId
+					}
 				});
+				return {
+					result: replay,
+					reloadTargets: null
+				};
 			}
-		}, {
-			sourceId,
-			targetId
+			const tempId = await pctx.metaStore.allocateNextDeviceId();
+			const result = await migrateDevice$1({
+				setSwitch: async (deviceId, switchId, enabled) => {
+					if (switchId === "stream-broker") {
+						const moved = await writeDisabledFlagUnderLock(pctx, deviceId, !enabled);
+						emitDisabledEvents(pctx, deviceId, !enabled, moved);
+						return;
+					}
+					await ctx.api.pipelineOrchestrator.setCameraSwitch.mutate({
+						deviceId,
+						switchId,
+						enabled
+					});
+				},
+				swapIds: async (a, b) => {
+					await pctx.metaStore.rows.swapIds(a, b, tempId);
+				},
+				swapHardwareState: async (a, b) => {
+					const swapped = await swapHardwareState(pctx.settings, a, b);
+					pctx.host.seedMirror(a, pctx.host.withResetSessionProbe(swapped.runtimeStateNowAtSource));
+					pctx.host.seedMirror(b, pctx.host.withResetSessionProbe(swapped.runtimeStateNowAtTarget));
+					ctx.logger.info("migration: hardware-scoped device state swapped", {
+						tags: { deviceId: a },
+						meta: {
+							sourceId: a,
+							targetId: b,
+							hardwareKeysToSource: swapped.hardwareKeysToSource,
+							hardwareKeysToTarget: swapped.hardwareKeysToTarget,
+							roleKeysKeptAtSource: swapped.roleKeysKeptAtSource,
+							roleKeysKeptAtTarget: swapped.roleKeysKeptAtTarget
+						}
+					});
+				},
+				forgetStreamState: async (deviceId) => {
+					await ctx.api.streamBroker.forgetDeviceHardware.mutate({ deviceId });
+				},
+				log: (message, meta) => {
+					ctx.logger.info(message, {
+						tags: { deviceId: sourceId },
+						meta
+					});
+				}
+			}, {
+				sourceId,
+				targetId
+			});
+			pctx.migrationGuard.recordCompleted({
+				sourceId,
+				targetId,
+				identityAtSource: {
+					addonId: targetRow.meta.addonId,
+					stableId: targetRow.meta.stableId
+				},
+				identityAtTarget: {
+					addonId: sourceRow.meta.addonId,
+					stableId: sourceRow.meta.stableId
+				},
+				result
+			});
+			return {
+				result,
+				reloadTargets: [{
+					deviceId: sourceId,
+					addonId: targetRow.meta.addonId,
+					stableId: targetRow.meta.stableId
+				}, {
+					deviceId: targetId,
+					addonId: sourceRow.meta.addonId,
+					stableId: sourceRow.meta.stableId
+				}]
+			};
 		});
-	});
+		if (outcome.reloadTargets !== null) await reloadMigratedDevices(pctx, outcome.reloadTargets);
+		return outcome.result;
+	} finally {
+		pctx.migrationGuard.end(sourceId, targetId);
+	}
 }
 async function registerDevice(pctx, input) {
 	const { addonId, stableId, id, type, name, parentDeviceId, features, config } = input;
@@ -4151,35 +4405,23 @@ async function setMetadata(pctx, input) {
 	});
 }
 /**
-* Soft-disable the device. Persisted on the meta row;
-* lifecycle gating is the driver's responsibility (BaseDevice
-* exposes `this.disabled` for the driver to consult at the top
-* of its lifecycle methods).
-*
-* TWO events leave here, and they are not the same message:
-*
-*  - `device.meta-changed` fires on EVERY call. It is the meta-surface echo
-*    every UI redraws on, and idempotence is not interesting to it.
-*  - `device.disabled` / `device.enabled` fire ONLY when the flag actually
-*    MOVES. They are the lifecycle announcement — the operator asked to be
-*    told when a camera is switched off, and a write that re-states a flag the
-*    device already had is not that. Telemetry semantics (D8) are fine here: a
-*    dropped announcement costs a notification, never durable state, and the
-*    meta row is the authority either way (D62 — this switch stores nothing of
-*    its own).
+* Read + patch the `disabled` flag. The caller HOLDS the meta write lock —
+* this is split out of {@link setDisabled} so `migrateDevice`, which holds the
+* lock for its whole run, can write the same authority without re-acquiring
+* it (the self-deadlock documented at its `setSwitch`).
 */
-async function setDisabled(pctx, input) {
-	const { deviceId, disabled } = input;
-	const moved = await pctx.metaStore.withMetaWriteLock(async () => {
-		const persisted = await pctx.metaStore.resolvePersistedById(deviceId);
-		if (!persisted) throw new Error(`[device-manager] setDisabled: unknown device id=${deviceId}`);
-		const { meta: m } = persisted;
-		await pctx.metaStore.rows.patch(deviceId, { disabled });
-		return {
-			changed: (m.disabled ?? false) !== disabled,
-			integrationId: m.integrationId ?? ""
-		};
-	});
+async function writeDisabledFlagUnderLock(pctx, deviceId, disabled) {
+	const persisted = await pctx.metaStore.resolvePersistedById(deviceId);
+	if (!persisted) throw new Error(`[device-manager] setDisabled: unknown device id=${deviceId}`);
+	const { meta: m } = persisted;
+	await pctx.metaStore.rows.patch(deviceId, { disabled });
+	return {
+		changed: (m.disabled ?? false) !== disabled,
+		integrationId: m.integrationId ?? ""
+	};
+}
+/** The two announcements — meta echo always, lifecycle only on a transition. */
+function emitDisabledEvents(pctx, deviceId, disabled, moved) {
 	pctx.host.ctx.eventBus.emit({
 		id: (0, node_crypto.randomUUID)(),
 		timestamp: /* @__PURE__ */ new Date(),
@@ -4209,6 +4451,10 @@ async function setDisabled(pctx, input) {
 		}
 	});
 }
+async function setDisabled(pctx, input) {
+	const { deviceId, disabled } = input;
+	emitDisabledEvents(pctx, deviceId, disabled, await pctx.metaStore.withMetaWriteLock(() => writeDisabledFlagUnderLock(pctx, deviceId, disabled)));
+}
 async function loadRuntimeState(pctx, input) {
 	const { deviceId } = input;
 	if (!await pctx.metaStore.resolvePersistedById(deviceId)) return {};
@@ -5823,6 +6069,43 @@ function resolveNativeCapOwnerSync(pctx, capName, deviceId) {
 	};
 	return resolveRemoteNativeCapFromRegistry(pctx.bindingsDeps, capName, deviceId);
 }
+function sameIdentity(a, b) {
+	return a.addonId === b.addonId && a.stableId === b.stableId;
+}
+/** One guard per device-manager instance. `now` is injectable for the specs. */
+function createMigrationGuard(now = Date.now) {
+	const inFlight = /* @__PURE__ */ new Set();
+	const completed = /* @__PURE__ */ new Map();
+	const pairKey = (sourceId, targetId) => `${sourceId}->${targetId}`;
+	return {
+		begin(sourceId, targetId) {
+			for (const id of [sourceId, targetId]) if (inFlight.has(id)) throw new Error(`[device-manager] migrateDevice: a migration involving device ${id} is already in flight — this call was refused, not queued. The running migration's report stands; re-read the device rows before retrying.`);
+			inFlight.add(sourceId);
+			inFlight.add(targetId);
+		},
+		end(sourceId, targetId) {
+			inFlight.delete(sourceId);
+			inFlight.delete(targetId);
+		},
+		recordCompleted(record) {
+			completed.set(pairKey(record.sourceId, record.targetId), {
+				...record,
+				completedAt: now()
+			});
+		},
+		matchReplay(sourceId, targetId, atSource, atTarget) {
+			const key = pairKey(sourceId, targetId);
+			const record = completed.get(key);
+			if (record === void 0) return null;
+			if (now() - record.completedAt > 9e5) {
+				completed.delete(key);
+				return null;
+			}
+			if (!sameIdentity(record.identityAtSource, atSource) || !sameIdentity(record.identityAtTarget, atTarget)) return null;
+			return record.result;
+		}
+	};
+}
 //#endregion
 //#region src/builtins/device-manager/device-manager.addon.ts
 var DeviceManagerAddon = class extends require_dist.BaseAddon {
@@ -6063,6 +6346,7 @@ var DeviceManagerAddon = class extends require_dist.BaseAddon {
 			settings,
 			registry,
 			bindingsDeps: this.bindingsDeps,
+			migrationGuard: createMigrationGuard(),
 			requireDeviceOps,
 			stampIntegrationId: stampIntegrationId$1,
 			get provider() {