@camstack/system 1.2.390 → 1.2.392

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

@@ -1,79 +1,79 @@
-import { DeviceManagerSettings } from './device-meta-store.js';
-import { OwnedCaps } from './field-ownership.js';
-import { MigrationRefusedError } from './migration-refused.js';
+import type { DeviceManagerSettings } from "./device-meta-store.js";
+import { type OwnedCaps } from "./field-ownership.js";
+import { MigrationRefusedError } from "./migration-refused.js";
 /** The narrow settings slice the swap needs — the seam the spec fakes. */
-export type HardwareStateStore = Pick<DeviceManagerSettings, 'readDeviceStore' | 'writeDeviceStore' | 'clearDeviceStore' | 'readDeviceRuntimeState' | 'writeDeviceRuntimeState'>;
+export type HardwareStateStore = Pick<DeviceManagerSettings, "readDeviceStore" | "writeDeviceStore" | "clearDeviceStore" | "readDeviceRuntimeState" | "writeDeviceRuntimeState">;
 export interface SwappedHardwareState {
-    /** Runtime-state blob now persisted at `sourceId` (was the target's). */
-    readonly runtimeStateNowAtSource: Record<string, unknown>;
-    /** Runtime-state blob now persisted at `targetId` (was the source's). */
-    readonly runtimeStateNowAtTarget: Record<string, unknown>;
-    /** Hardware config keys that moved target → source. */
-    readonly hardwareKeysToSource: readonly string[];
-    /** Hardware config keys that moved source → target. */
-    readonly hardwareKeysToTarget: readonly string[];
-    /** Role config keys that stayed on each number. */
-    readonly roleKeysKeptAtSource: readonly string[];
-    readonly roleKeysKeptAtTarget: readonly string[];
+	/** Runtime-state blob now persisted at `sourceId` (was the target's). */
+	readonly runtimeStateNowAtSource: Record<string, unknown>;
+	/** Runtime-state blob now persisted at `targetId` (was the source's). */
+	readonly runtimeStateNowAtTarget: Record<string, unknown>;
+	/** Hardware config keys that moved target → source. */
+	readonly hardwareKeysToSource: readonly string[];
+	/** Hardware config keys that moved source → target. */
+	readonly hardwareKeysToTarget: readonly string[];
+	/** Role config keys that stayed on each number. */
+	readonly roleKeysKeptAtSource: readonly string[];
+	readonly roleKeysKeptAtTarget: readonly string[];
 }
 /** One claimed cap on a device that blocks its migration. */
 export interface BlockingClaim {
-    readonly cap: string;
-    readonly owner: string;
-    readonly fields: readonly string[];
+	readonly cap: string;
+	readonly owner: string;
+	readonly fields: readonly string[];
 }
 /** A device whose row carries claims, and what they are. */
 export interface ClaimBlockedDevice {
-    readonly deviceId: number;
-    readonly claims: readonly BlockingClaim[];
+	readonly deviceId: number;
+	readonly claims: readonly BlockingClaim[];
 }
 /**
- * The refusal of a migration over a device under customization. `blocked`
- * carries the same facts as the message, per device, so the caller can log
- * one line per device tagged with its id.
- */
+* The refusal of a migration over a device under customization. `blocked`
+* carries the same facts as the message, per device, so the caller can log
+* one line per device tagged with its id.
+*/
 export declare class FieldClaimsBlockMigrationError extends Error {
-    readonly sourceId: number;
-    readonly targetId: number;
-    readonly blocked: readonly ClaimBlockedDevice[];
-    constructor(sourceId: number, targetId: number, blocked: readonly ClaimBlockedDevice[]);
+	readonly sourceId: number;
+	readonly targetId: number;
+	readonly blocked: readonly ClaimBlockedDevice[];
+	constructor(sourceId: number, targetId: number, blocked: readonly ClaimBlockedDevice[]);
 }
 /**
- * A claim that landed while the migration was already running (D663 final
- * review I-1). It passed the claim methods' migration gate just before the
- * migration began, and its write-through had not reached the row when
- * {@link assertNoFieldClaims} read it. Found after the drain, before any row
- * moved — so it is a {@link MigrationRefusedError}: both cameras' switches are
- * restored, and the claim stays on the number it names.
- */
+* A claim that landed while the migration was already running (D663 final
+* review I-1). It passed the claim methods' migration gate just before the
+* migration began, and its write-through had not reached the row when
+* {@link assertNoFieldClaims} read it. Found after the drain, before any row
+* moved — so it is a {@link MigrationRefusedError}: both cameras' switches are
+* restored, and the claim stays on the number it names.
+*/
 export declare class ClaimLandedDuringMigrationError extends MigrationRefusedError {
-    readonly sourceId: number;
-    readonly targetId: number;
-    readonly blocked: readonly ClaimBlockedDevice[];
-    constructor(sourceId: number, targetId: number, blocked: readonly ClaimBlockedDevice[]);
+	readonly sourceId: number;
+	readonly targetId: number;
+	readonly blocked: readonly ClaimBlockedDevice[];
+	constructor(sourceId: number, targetId: number, blocked: readonly ClaimBlockedDevice[]);
 }
 /**
- * The second look, from MEMORY, once the mirror's writer is held and drained
- * (I-1). A claim is in the mirror from the moment it is accepted, before its
- * write-through lands, and the hold refuses any claim that reaches the mirror
- * after it — so an empty answer here means no claim can land on either row
- * until the swap is done.
- */
+* The second look, from MEMORY, once the mirror's writer is held and drained
+* (I-1). A claim is in the mirror from the moment it is accepted, before its
+* write-through lands, and the hold refuses any claim that reaches the mirror
+* after it — so an empty answer here means no claim can land on either row
+* until the swap is done.
+*/
 export declare function assertNoClaimLandedDuringMigration(ownedCapsOf: (deviceId: number) => OwnedCaps, sourceId: number, targetId: number): void;
 /**
- * A claim names a NUMBER (`$owned` sits in `__device-state:<id>`); the block
- * that owns it names a STABLE ID; `swapIds` moves the stable id to the other
- * number. No swap of `$owned` keeps both keys right, so a device under
- * customization is not migratable (D663). Read from the ROW — claims are
- * written through, so the row is where one exists. A row that cannot be read
- * THROWS: an unknown answer must refuse, never read as "no claim" (D49).
- */
-export declare function assertNoFieldClaims(settings: Pick<HardwareStateStore, 'readDeviceRuntimeState'>, sourceId: number, targetId: number): Promise<void>;
+* A claim names a NUMBER (`$owned` sits in `__device-state:<id>`); the block
+* that owns it names a STABLE ID; `swapIds` moves the stable id to the other
+* number. No swap of `$owned` keeps both keys right, so a device under
+* customization is not migratable (D663). Read from the ROW — claims are
+* written through, so the row is where one exists. A row that cannot be read
+* THROWS: an unknown answer must refuse, never read as "no claim" (D49).
+*/
+export declare function assertNoFieldClaims(settings: Pick<HardwareStateStore, "readDeviceRuntimeState">, sourceId: number, targetId: number): Promise<void>;
 /**
- * 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.
- */
+* 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.
+*/
 export declare function swapHardwareState(settings: HardwareStateStore, sourceId: number, targetId: number): Promise<SwappedHardwareState>;

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

@@ -1,8 +1,46 @@
-import { ProviderContext } from './device-provider-context.js';
+/**
+* After a migration swap, flush every live copy of the TWO migrated numbers —
+* and nothing else.
+*
+* The requirement is real and inherited from the restart era: every in-memory
+* `id → addon` map and every live device instance holding one of these
+* numbers must be invalidated, and not by an event — telemetry may be dropped
+* (D8), and a dropped flush leaves a runner writing against the wrong camera.
+* What was NOT required was the blast radius: restarting the whole owning
+* addon took 28 devices down for one migrated camera (measured 2026-09-04),
+* and the same morning ~27 devices' native caps failed to come back after a
+* provider restart until the operator restarted both providers by hand,
+* twice. The restart was the flush of last resort pretending to be the
+* mechanism.
+*
+* What actually holds a migrated number, and how each copy is flushed:
+*
+*  1. **The owning runner's live `IDevice`** (id baked into the object, its
+*     native-cap registrations, its log tags) — `deviceProvider.reloadDevice`,
+*     an RPC into the owning addon that decommissions the one instance and
+*     re-creates it from the persisted rows (the same teardown/rehydrate pair
+*     graceful shutdown + boot restore already use). Children ride along:
+*     accessory children via `getAccessoryChildren()`, first-class children
+*     via the restore's pass 2 inside `reloadDevice`.
+*  2. **The hub's `idToAddonId` map** — patched here to the post-swap owners.
+*     `resolveDeviceOwnerSync` answers from this map alone; in the restart
+*     era it stayed stale until the provider re-registered.
+*  3. **The hub's push-fed `remoteNativeCaps` cache and hub-local native-cap
+*     registrations** for the two ids — dropped here; the runner's re-create
+*     pushes fresh registrations. (The handshake-fed `HubNodeRegistry`
+*     fallback can serve a stale entry until the next re-handshake — the
+*     same transient every worker-restart window has always had.)
+*
+* A runner that cannot reload (older deployed closure without the method, an
+* unreachable provider) falls back to the WHOLE-ADDON restart for that addon
+* only — reported with the same blast-radius line as before, because the
+* operator must still see `devicesTakenDown` when it happens.
+*/
+import type { ProviderContext } from "./device-provider-context.js";
 /** One migrated number and the identity that lives at it AFTER the swap. */
 export interface MigratedDeviceTarget {
-    readonly deviceId: number;
-    readonly addonId: string;
-    readonly stableId: string;
+	readonly deviceId: number;
+	readonly addonId: string;
+	readonly stableId: string;
 }
 export declare function reloadMigratedDevices(pctx: ProviderContext, targets: readonly MigratedDeviceTarget[]): Promise<void>;

package/dist/builtins/device-manager/migration-refused.d.ts

@@ -1,23 +1,23 @@
 /**
- * A migration step that REFUSED with nothing moved.
- *
- * `migrateDevice` distinguishes two kinds of failure after the disable phase,
- * and they must never be confused (D663 task 5b ruling I-1):
- *
- *  - **refused, nothing moved** — a precheck of `swapIds` (a row missing, the
- *    temp id taken), the mirror drain that runs before the rows move, or a
- *    claim found in the mirror after that drain (it landed while the migration
- *    was starting). Both cameras are switched back to exactly what they were,
- *    because nothing about either device changed.
- *  - **failed while moving** — any other throw from `swapIds` (rows partially
- *    moved), or from `swapHardwareState` (rows swapped, state not). The two
- *    devices may wear each other's identity; switching them back on would run
- *    pipelines against crossed identities, so they stay off and the operator is
- *    told to intervene.
- *
- * Only a step that KNOWS it wrote nothing may throw this. An unknown error is
- * read as "may have moved" — the safe reading.
- */
+* A migration step that REFUSED with nothing moved.
+*
+* `migrateDevice` distinguishes two kinds of failure after the disable phase,
+* and they must never be confused (D663 task 5b ruling I-1):
+*
+*  - **refused, nothing moved** — a precheck of `swapIds` (a row missing, the
+*    temp id taken), the mirror drain that runs before the rows move, or a
+*    claim found in the mirror after that drain (it landed while the migration
+*    was starting). Both cameras are switched back to exactly what they were,
+*    because nothing about either device changed.
+*  - **failed while moving** — any other throw from `swapIds` (rows partially
+*    moved), or from `swapHardwareState` (rows swapped, state not). The two
+*    devices may wear each other's identity; switching them back on would run
+*    pipelines against crossed identities, so they stay off and the operator is
+*    told to intervene.
+*
+* Only a step that KNOWS it wrote nothing may throw this. An unknown error is
+* read as "may have moved" — the safe reading.
+*/
 export declare class MigrationRefusedError extends Error {
-    constructor(message: string, options?: ErrorOptions);
+	constructor(message: string, options?: ErrorOptions);
 }