@camstack/system 1.2.171 → 1.2.173

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

@@ -5151,6 +5151,86 @@ var DeviceRowStore = class {
 		});
 	}
 	/** Drop the device's row. Idempotent. */
+	/**
+	* Exchange the ids of two devices, carrying their children with them.
+	*
+	* ## Why this exists as a primitive
+	*
+	* Replacing a camera means the new hardware has to become the device the rest
+	* of the system already knows. Everything general about a camera is keyed on
+	* the NUMERIC id and on nothing else — the recording path on disk is
+	* `<deviceId>/profile/…`, the hour ledger, the media store and zone ownership
+	* carry `deviceId` and not one `stableId` between them, and all four
+	* ecosystem exports (Home Assistant, Alexa, HomeKit, Google) key on it too.
+	* Moving that work is the expensive, lossy operation. Moving the NUMBER is
+	* two rows.
+	*
+	* ## Children are re-pointed, not renumbered
+	*
+	* A child keeps its own id and follows its parent: every row whose
+	* `parentDeviceId` was `a` now names `b`, and the reverse. Renumbering the
+	* children as well would move THEIR general work for no reason — the
+	* accessory's own recordings and rules are keyed on the child id, which is
+	* not the id being inherited.
+	*
+	* ## There are no transactions here, so the ORDER is the safety
+	*
+	* The backing store is a collection API (`set` / `delete` / `updateWhere`);
+	* there is no rollback to lean on. So the sequence is chosen to make every
+	* crash point LOUD rather than plausible: `a` first moves to a freshly
+	* allocated id, which the monotonic counter guarantees was never used and
+	* will never be reused. A crash before the end therefore leaves a device
+	* missing from its number and a stray at an unfamiliar one — visible in the
+	* device list at a glance. What it can never leave is two rows on one number,
+	* or a row that looks correct while its children point elsewhere.
+	*
+	* The caller holds {@link DeviceMetaStore.withMetaWriteLock}. This method does
+	* not take it: taking it here would deadlock the migration that has to disable
+	* functions on both devices in the same critical section.
+	*/
+	async swapIds(a, b, tempId) {
+		if (a === b) throw new Error(`[device-manager] swapIds: ${a} and ${b} are the same device`);
+		await this.declare();
+		const rowA = await this.get(a);
+		const rowB = await this.get(b);
+		if (rowA === null) throw new Error(`[device-manager] swapIds: device ${a} does not exist`);
+		if (rowB === null) throw new Error(`[device-manager] swapIds: device ${b} does not exist`);
+		if (await this.get(tempId) !== null) throw new Error(`[device-manager] swapIds: temp id ${tempId} is taken`);
+		const childrenOfA = (await this.listByParent(a)).map((r) => r.meta.id);
+		const childrenOfB = (await this.listByParent(b)).map((r) => r.meta.id);
+		await this.moveRow(rowA, tempId);
+		await this.moveRow(rowB, a);
+		await this.moveRow({
+			...rowA,
+			meta: {
+				...rowA.meta,
+				id: tempId
+			}
+		}, b);
+		for (const childId of childrenOfA) await this.patch(childId, { parentDeviceId: b });
+		for (const childId of childrenOfB) await this.patch(childId, { parentDeviceId: a });
+		this.logger.info("device ids swapped", {
+			tags: { deviceId: a },
+			meta: {
+				a,
+				b,
+				childrenOfA,
+				childrenOfB
+			}
+		});
+	}
+	/** Rewrite a row under a new id and drop the old key. Not exported: the only
+	*  legitimate reason to move a row is {@link swapIds}. */
+	async moveRow(row, toId) {
+		await this.upsert({
+			...row.meta,
+			id: toId
+		}, {
+			registered: row.registered,
+			metadata: row.metadata
+		});
+		await this.remove(row.meta.id);
+	}
 	async remove(deviceId) {
 		await this.declare();
 		await this.backend.delete({

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

@@ -5146,6 +5146,86 @@ var DeviceRowStore = class {
 		});
 	}
 	/** Drop the device's row. Idempotent. */
+	/**
+	* Exchange the ids of two devices, carrying their children with them.
+	*
+	* ## Why this exists as a primitive
+	*
+	* Replacing a camera means the new hardware has to become the device the rest
+	* of the system already knows. Everything general about a camera is keyed on
+	* the NUMERIC id and on nothing else — the recording path on disk is
+	* `<deviceId>/profile/…`, the hour ledger, the media store and zone ownership
+	* carry `deviceId` and not one `stableId` between them, and all four
+	* ecosystem exports (Home Assistant, Alexa, HomeKit, Google) key on it too.
+	* Moving that work is the expensive, lossy operation. Moving the NUMBER is
+	* two rows.
+	*
+	* ## Children are re-pointed, not renumbered
+	*
+	* A child keeps its own id and follows its parent: every row whose
+	* `parentDeviceId` was `a` now names `b`, and the reverse. Renumbering the
+	* children as well would move THEIR general work for no reason — the
+	* accessory's own recordings and rules are keyed on the child id, which is
+	* not the id being inherited.
+	*
+	* ## There are no transactions here, so the ORDER is the safety
+	*
+	* The backing store is a collection API (`set` / `delete` / `updateWhere`);
+	* there is no rollback to lean on. So the sequence is chosen to make every
+	* crash point LOUD rather than plausible: `a` first moves to a freshly
+	* allocated id, which the monotonic counter guarantees was never used and
+	* will never be reused. A crash before the end therefore leaves a device
+	* missing from its number and a stray at an unfamiliar one — visible in the
+	* device list at a glance. What it can never leave is two rows on one number,
+	* or a row that looks correct while its children point elsewhere.
+	*
+	* The caller holds {@link DeviceMetaStore.withMetaWriteLock}. This method does
+	* not take it: taking it here would deadlock the migration that has to disable
+	* functions on both devices in the same critical section.
+	*/
+	async swapIds(a, b, tempId) {
+		if (a === b) throw new Error(`[device-manager] swapIds: ${a} and ${b} are the same device`);
+		await this.declare();
+		const rowA = await this.get(a);
+		const rowB = await this.get(b);
+		if (rowA === null) throw new Error(`[device-manager] swapIds: device ${a} does not exist`);
+		if (rowB === null) throw new Error(`[device-manager] swapIds: device ${b} does not exist`);
+		if (await this.get(tempId) !== null) throw new Error(`[device-manager] swapIds: temp id ${tempId} is taken`);
+		const childrenOfA = (await this.listByParent(a)).map((r) => r.meta.id);
+		const childrenOfB = (await this.listByParent(b)).map((r) => r.meta.id);
+		await this.moveRow(rowA, tempId);
+		await this.moveRow(rowB, a);
+		await this.moveRow({
+			...rowA,
+			meta: {
+				...rowA.meta,
+				id: tempId
+			}
+		}, b);
+		for (const childId of childrenOfA) await this.patch(childId, { parentDeviceId: b });
+		for (const childId of childrenOfB) await this.patch(childId, { parentDeviceId: a });
+		this.logger.info("device ids swapped", {
+			tags: { deviceId: a },
+			meta: {
+				a,
+				b,
+				childrenOfA,
+				childrenOfB
+			}
+		});
+	}
+	/** Rewrite a row under a new id and drop the old key. Not exported: the only
+	*  legitimate reason to move a row is {@link swapIds}. */
+	async moveRow(row, toId) {
+		await this.upsert({
+			...row.meta,
+			id: toId
+		}, {
+			registered: row.registered,
+			metadata: row.metadata
+		});
+		await this.remove(row.meta.id);
+	}
 	async remove(deviceId) {
 		await this.declare();
 		await this.backend.delete({

package/dist/builtins/device-manager/device-row-store.d.ts

@@ -340,6 +340,47 @@ export declare class DeviceRowStore {
      */
     upsertRegistration(row: DeviceRegistrationRow): Promise<void>;
     /** Drop the device's row. Idempotent. */
+    /**
+     * Exchange the ids of two devices, carrying their children with them.
+     *
+     * ## Why this exists as a primitive
+     *
+     * Replacing a camera means the new hardware has to become the device the rest
+     * of the system already knows. Everything general about a camera is keyed on
+     * the NUMERIC id and on nothing else — the recording path on disk is
+     * `<deviceId>/profile/…`, the hour ledger, the media store and zone ownership
+     * carry `deviceId` and not one `stableId` between them, and all four
+     * ecosystem exports (Home Assistant, Alexa, HomeKit, Google) key on it too.
+     * Moving that work is the expensive, lossy operation. Moving the NUMBER is
+     * two rows.
+     *
+     * ## Children are re-pointed, not renumbered
+     *
+     * A child keeps its own id and follows its parent: every row whose
+     * `parentDeviceId` was `a` now names `b`, and the reverse. Renumbering the
+     * children as well would move THEIR general work for no reason — the
+     * accessory's own recordings and rules are keyed on the child id, which is
+     * not the id being inherited.
+     *
+     * ## There are no transactions here, so the ORDER is the safety
+     *
+     * The backing store is a collection API (`set` / `delete` / `updateWhere`);
+     * there is no rollback to lean on. So the sequence is chosen to make every
+     * crash point LOUD rather than plausible: `a` first moves to a freshly
+     * allocated id, which the monotonic counter guarantees was never used and
+     * will never be reused. A crash before the end therefore leaves a device
+     * missing from its number and a stray at an unfamiliar one — visible in the
+     * device list at a glance. What it can never leave is two rows on one number,
+     * or a row that looks correct while its children point elsewhere.
+     *
+     * The caller holds {@link DeviceMetaStore.withMetaWriteLock}. This method does
+     * not take it: taking it here would deadlock the migration that has to disable
+     * functions on both devices in the same critical section.
+     */
+    swapIds(a: number, b: number, tempId: number): Promise<void>;
+    /** Rewrite a row under a new id and drop the old key. Not exported: the only
+     *  legitimate reason to move a row is {@link swapIds}. */
+    private moveRow;
     remove(deviceId: number): Promise<void>;
     /**
      * The retirement door for the three blobs this collection replaced.

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

@@ -0,0 +1,44 @@
+import { CameraSwitchId } from '@camstack/types';
+/** What actually happened to one switch on one device. */
+export type SwitchOutcome = 'off' | 'on' | 'not-offered' | 'unreachable';
+export interface SwitchReport {
+    readonly deviceId: number;
+    readonly switchId: CameraSwitchId;
+    readonly outcome: SwitchOutcome;
+    /** The refusal, verbatim, when the outcome is not the requested one. */
+    readonly detail?: string;
+}
+export interface MigrateDeviceResult {
+    readonly sourceId: number;
+    readonly targetId: number;
+    /** Every switch write attempted, in order, on both devices. */
+    readonly switches: readonly SwitchReport[];
+    /**
+     * Switches that could NOT be turned off on the source. Empty is the only
+     * value that means "the old camera is fully quiet"; a caller that renders
+     * only a success flag is not entitled to one.
+     */
+    readonly sourceStillLive: readonly CameraSwitchId[];
+    readonly swapped: boolean;
+}
+export interface MigrateDeviceDeps {
+    /** `pipelineOrchestrator.setCameraSwitch`, through `ctx.api`. */
+    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>;
+    readonly log: (message: string, meta: Record<string, unknown>) => void;
+}
+/**
+ * Put both cameras to sleep, exchange their identities, wake the target.
+ *
+ * Throws only if the swap itself fails — a switch that could not be written is
+ * reported, not raised, because refusing to migrate a camera whose old hardware
+ * is unreachable would refuse the exact case this exists for.
+ */
+export declare function migrateDevice(deps: MigrateDeviceDeps, input: {
+    readonly sourceId: number;
+    readonly targetId: number;
+}): Promise<MigrateDeviceResult>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/system",
-  "version": "1.2.171",
+  "version": "1.2.173",
   "description": "Core addon for CamStack — builtins, pipeline, process management, auth, logging, events",
   "keywords": [
     "camstack",