@camstack/system 1.2.179 → 1.2.181

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

@@ -1,5 +1,5 @@
-import { $t as isDeviceConfigCap, Bt as DeviceRole, Ft as BaseAddon, H as deviceManagerCapability, J as enumerateSchemaFields, P as buildStreamParamsConfigSchema, Pt as errMsg, U as deviceStateCapability, Vt as DeviceType, W as deviceStatusCapability, Wt as WELL_KNOWN_TAB_MAP, a as CAMERA_SWITCH_ORDER, b as STREAM_PROFILE_META, f as DeviceStatusSchema, ft as normalizeUnit, mt as parseStreamParamsFormPatch, o as CAP_NAMES_WITH_STATUS, on as sleep, q as enumerateItemArrayFields, sn as EventCategory, t as ALL_CAPABILITY_DEFINITIONS, xt as runtimeStatePolicyFor, yt as resolveContainerPrimaryChild, zt as DeviceFeature } from "../../dist-L_39vRmH.mjs";
-import { n as purgeRetiredSettingsRows } from "../../retired-settings-keys-CnbKAxmX.mjs";
+import { $t as isDeviceConfigCap, Bt as DeviceRole, Ft as BaseAddon, H as deviceManagerCapability, J as enumerateSchemaFields, P as buildStreamParamsConfigSchema, Pt as errMsg, U as deviceStateCapability, Vt as DeviceType, W as deviceStatusCapability, Wt as WELL_KNOWN_TAB_MAP, a as CAMERA_SWITCH_ORDER, b as STREAM_PROFILE_META, f as DeviceStatusSchema, ft as normalizeUnit, mt as parseStreamParamsFormPatch, o as CAP_NAMES_WITH_STATUS, on as sleep, q as enumerateItemArrayFields, sn as EventCategory, t as ALL_CAPABILITY_DEFINITIONS, xt as runtimeStatePolicyFor, yt as resolveContainerPrimaryChild, zt as DeviceFeature } from "../../dist-DbnNk4Lw.mjs";
+import { n as purgeRetiredSettingsRows } from "../../retired-settings-keys-CyQG8b-A.mjs";
 import { randomUUID } from "node:crypto";
 import { canonicalDeviceFingerprint } from "@camstack/types/node";
 //#region src/builtins/device-manager/adoption-job-engine.ts
@@ -2109,7 +2109,13 @@ function resolveLinkedDeviceIds(params) {
 	if (config.mode === "auto") {
 		if (selfLocation !== null && selfLocation.length > 0) for (const c of candidates) {
 			if (c.type === 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 === 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);
@@ -3269,8 +3275,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:
@@ -3282,10 +3286,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 CAMERA_SWITCH_ORDER) try {
-		await deps.setSwitch(deviceId, switchId, enabled);
+		await setSwitchBounded(deps, deviceId, switchId, enabled);
 		out.push({
 			deviceId,
 			switchId,
@@ -3322,8 +3347,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,
@@ -3339,6 +3373,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 —
@@ -3418,48 +3594,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;
@@ -4146,35 +4400,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: randomUUID(),
 		timestamp: /* @__PURE__ */ new Date(),
@@ -4204,6 +4446,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 {};
@@ -5818,6 +6064,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 BaseAddon {
@@ -6058,6 +6341,7 @@ var DeviceManagerAddon = class extends BaseAddon {
 			settings,
 			registry,
 			bindingsDeps: this.bindingsDeps,
+			migrationGuard: createMigrationGuard(),
 			requireDeviceOps,
 			stampIntegrationId: stampIntegrationId$1,
 			get provider() {

package/dist/builtins/device-manager/device-meta-actions.d.ts

@@ -19,11 +19,18 @@ export declare function allocateDeviceId(pctx: ProviderContext, input: Parameter
  * 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.
  */
 export declare function migrateDevice(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['migrateDevice']>[0]): ReturnType<IDeviceManagerProvider['migrateDevice']>;
 export declare function registerDevice(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['registerDevice']>[0]): ReturnType<IDeviceManagerProvider['registerDevice']>;
@@ -188,24 +195,6 @@ export declare function applyInitialMeta(pctx: ProviderContext, input: Parameter
  * the meta-changed event.
  */
 export declare function setMetadata(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['setMetadata']>[0]): ReturnType<IDeviceManagerProvider['setMetadata']>;
-/**
- * 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).
- */
 export declare function setDisabled(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['setDisabled']>[0]): ReturnType<IDeviceManagerProvider['setDisabled']>;
 export declare function loadRuntimeState(pctx: ProviderContext, input: Parameters<IDeviceManagerProvider['loadRuntimeState']>[0]): ReturnType<IDeviceManagerProvider['loadRuntimeState']>;
 /**

package/dist/builtins/device-manager/device-provider-context.d.ts

@@ -2,6 +2,7 @@ import { AddonContext, ICapabilityRegistry, IDeviceAdoptionProvider, IDeviceMana
 import { AdoptionJobEngine } from './adoption-job-engine.js';
 import { BindingsDeps } from './device-bindings-store.js';
 import { DeviceManagerSettings, DeviceMetaStore } from './device-meta-store.js';
+import { MigrationGuard } from './migrate-guard.js';
 type IDeviceProviderCap = InferProvider<typeof deviceProviderCapability>;
 /**
  * The addon-instance surface the extracted provider functions need. Exposed by
@@ -47,6 +48,9 @@ export interface ProviderContext {
     /** Hub-process device registry (null when this node owns no registry). */
     readonly registry: IDeviceRegistry | null;
     readonly bindingsDeps: BindingsDeps;
+    /** In-flight refusal + completed-swap replay for `migrateDevice` — the
+     *  reason a retried migration can no longer undo the one that ran. */
+    readonly migrationGuard: MigrationGuard;
     /** Resolve the per-device `device-ops` native provider (throws when absent). */
     requireDeviceOps(deviceId: number): IDeviceOpsProvider;
     /** Stamp an integration id onto a device's meta row + emit DeviceMetaChanged. */

package/dist/builtins/device-manager/migrate-device.d.ts

@@ -1,4 +1,11 @@
 import { CameraSwitchId } from '@camstack/types';
+/**
+ * Upper bound for ONE switch write. Generous against a live camera (a real
+ * write is sub-second; the camera-plane pair is a few seconds of HTTP) and
+ * small against the alternative: the 60 s transport default that let three
+ * phases burn three minutes on 2026-09-01.
+ */
+export declare const SWITCH_WRITE_TIMEOUT_MS = 15000;
 /** What actually happened to one switch on one device. */
 export type SwitchOutcome = 'off' | 'on' | 'not-offered' | 'unreachable';
 export interface SwitchReport {
@@ -26,10 +33,47 @@ export interface MigrateDeviceDeps {
     readonly setSwitch: (deviceId: number, switchId: CameraSwitchId, enabled: boolean) => Promise<void>;
     /** `DeviceRowStore.swapIds`, already under the meta write lock. */
     readonly swapIds: (a: number, b: number) => Promise<void>;
-    /** Respawn the runners that hold either number in memory. Disabling stops
-     *  data PRODUCTION; it does not flush a cache that maps id → addon. */
-    readonly respawnRunners: (deviceIds: readonly number[]) => Promise<void>;
+    /**
+     * Swap the HARDWARE-scoped per-device state along with the rows: the driver
+     * config blob (host/port/credentials/`deviceCache` — everything the
+     * provider's schema owns) and the runtime-state blob. Role-scoped keys stay
+     * with the number. See `migrate-hardware-state.ts` for the rule, and for
+     * the incident where the rows swapped and the configs did not — the two
+     * devices came out wearing each other's identity.
+     *
+     * A failure here THROWS, and the migration throws with it: rows swapped
+     * with configs unswapped is exactly that incident, and it must never be
+     * reported as a success.
+     */
+    readonly swapHardwareState: (sourceId: number, targetId: number) => Promise<void>;
+    /**
+     * Tell the stream broker the hardware behind this number is gone
+     * (`streamBroker.forgetDeviceHardware`): every DERIVED stream definition is
+     * DELETED, the profile-slot assignment entry is purged, and the probed
+     * snapshots and RTSP token rows of the old streams go with it.
+     *
+     * Measured on the live hub after replacing a Hikvision with a Reolink on id
+     * 618: the assignment still said `mid → native:slot-3`, a raw slot only the
+     * Hikvision had, and the `derived:Mid to low` feeder — defined against the
+     * old profile layout — respawned every ten seconds forever (observed at
+     * attempt 2732). The recorder reported `no profile attached for device
+     * 618`, live view answered `No broker for stream "618/adaptive"`, and no
+     * line named the stale assignment as the cause.
+     *
+     * Forgetting is deliberately what this does, rather than guessing a
+     * mapping: the catalog is the authority on which stream is which, and it
+     * belongs to the camera that is now there. An RPC, never an event — a
+     * dropped event (D8) would leave the feeder respawning forever.
+     */
+    readonly forgetStreamState: (deviceId: number) => Promise<void>;
     readonly log: (message: string, meta: Record<string, unknown>) => void;
+    /**
+     * Override for {@link SWITCH_WRITE_TIMEOUT_MS}, for the specs. A write that
+     * outlives the bound is reported `unreachable` — never `off`/`on` — and may
+     * still land later, which every switch authority tolerates (a duplicate
+     * write of the same value is a no-op at all eight of them).
+     */
+    readonly switchTimeoutMs?: number;
 }
 /**
  * Put both cameras to sleep, exchange their identities, wake the target.

package/dist/builtins/device-manager/migrate-guard.d.ts

@@ -0,0 +1,39 @@
+import { MigrateDeviceResult } from './migrate-device.js';
+/** The addon-facing identity a device row carries — what `swapIds` moves. */
+export interface DeviceIdentity {
+    readonly addonId: string;
+    readonly stableId: string;
+}
+/** What a finished migration left behind, for replay matching. */
+export interface CompletedMigration {
+    readonly sourceId: number;
+    readonly targetId: number;
+    /** Identity the completed swap left at `sourceId` (the pre-swap target's). */
+    readonly identityAtSource: DeviceIdentity;
+    /** Identity the completed swap left at `targetId` (the pre-swap source's). */
+    readonly identityAtTarget: DeviceIdentity;
+    readonly result: MigrateDeviceResult;
+}
+/**
+ * How long a completed migration absorbs an identical repeat call. Sized to
+ * comfortably cover the cap's own `timeoutMs` (10 min): a retry fired by a
+ * client that gave up arrives inside that envelope; a call arriving later is
+ * an operator's deliberate new operation and runs.
+ */
+export declare const MIGRATION_REPLAY_WINDOW_MS: number;
+export interface MigrationGuard {
+    /** Claim both ids for a run. Throws when either is already in flight. */
+    begin(sourceId: number, targetId: number): void;
+    /** Release both ids. Always paired with {@link begin} via try/finally. */
+    end(sourceId: number, targetId: number): void;
+    /** Record a completed swap's fingerprint for replay matching. */
+    recordCompleted(record: CompletedMigration): void;
+    /**
+     * The original report, when the call is a repeat of a completed swap: same
+     * ordered pair, current row identities equal to the recorded post-swap
+     * identities, within the window. `null` means "this is a new operation".
+     */
+    matchReplay(sourceId: number, targetId: number, atSource: DeviceIdentity, atTarget: DeviceIdentity): MigrateDeviceResult | null;
+}
+/** One guard per device-manager instance. `now` is injectable for the specs. */
+export declare function createMigrationGuard(now?: () => number): MigrationGuard;