@camstack/system 1.2.389 → 1.2.391

package/dist/builtins/device-manager/location-alignment.d.ts

@@ -1,61 +1,61 @@
-import { PersistedDeviceMeta } from './device-meta-types.js';
-import { ProviderContext } from './device-provider-context.js';
-import { DeviceRow } from './device-row-store.js';
+import type { PersistedDeviceMeta } from "./device-meta-types.js";
+import type { ProviderContext } from "./device-provider-context.js";
+import type { DeviceRow } from "./device-row-store.js";
 /** Addon-store key of the one-shot marker. A number: the highest backfill
- *  version that COMPLETED (every planned write landed). */
+*  version that COMPLETED (every planned write landed). */
 export declare const LOCATION_BACKFILL_MARKER_KEY = "locationBackfillVersion";
 export declare const LOCATION_BACKFILL_VERSION = 1;
 /** One planned repair: write `location` onto row `id`, inherited from the
- *  nearest located ancestor `ancestorId`. */
+*  nearest located ancestor `ancestorId`. */
 export interface NullLocationFill {
-    readonly id: number;
-    readonly location: string;
-    readonly ancestorId: number;
+	readonly id: number;
+	readonly location: string;
+	readonly ancestorId: number;
 }
 /**
- * Pure planning core of the backfill: every row whose own `location` is null
- * and whose parent chain reaches a located CONTAINER ancestor gets that
- * ancestor's location. Nearest located ancestor wins — and DECIDES: a located
- * non-container between the row and a located container blocks the fill.
- *
- * The container-only predicate is an operator decision (2026-09-05), the
- * automated mirror of the structural-children rule: a non-container parent's
- * subtree (a camera and its siren/floodlight) is already fully reachable
- * through `resolveLinkedDeviceIds`' children-of-self rule, so a location buys
- * its own camera nothing — and COSTS cross-camera noise, verified against the
- * real fleet shape with the real resolver: a camera child that gains the room
- * matches every OTHER camera in that room individually (`ids.add`; only a
- * Container parent routes through `expand`), so camera B lists camera A's
- * siren as a companion. A container's descendants, by contrast, are reachable
- * by location ONLY through their own columns — the container itself is never
- * a link — which is the whole reason the cascade writes them (D252). Note the
- * asymmetry with the OPERATOR's cascade, which has no type predicate (D329):
- * an operator re-saving a camera accepts that trade explicitly; an automated
- * pass must not manufacture it.
- */
+* Pure planning core of the backfill: every row whose own `location` is null
+* and whose parent chain reaches a located CONTAINER ancestor gets that
+* ancestor's location. Nearest located ancestor wins — and DECIDES: a located
+* non-container between the row and a located container blocks the fill.
+*
+* The container-only predicate is an operator decision (2026-09-05), the
+* automated mirror of the structural-children rule: a non-container parent's
+* subtree (a camera and its siren/floodlight) is already fully reachable
+* through `resolveLinkedDeviceIds`' children-of-self rule, so a location buys
+* its own camera nothing — and COSTS cross-camera noise, verified against the
+* real fleet shape with the real resolver: a camera child that gains the room
+* matches every OTHER camera in that room individually (`ids.add`; only a
+* Container parent routes through `expand`), so camera B lists camera A's
+* siren as a companion. A container's descendants, by contrast, are reachable
+* by location ONLY through their own columns — the container itself is never
+* a link — which is the whole reason the cascade writes them (D252). Note the
+* asymmetry with the OPERATOR's cascade, which has no type predicate (D329):
+* an operator re-saving a camera accepts that trade explicitly; an automated
+* pass must not manufacture it.
+*/
 export declare function planNullLocationFills(rows: readonly PersistedDeviceMeta[]): readonly NullLocationFill[];
 /** The one row-store method the async ancestor walk needs. */
 export interface RowReader {
-    get(deviceId: number): Promise<DeviceRow | null>;
+	get(deviceId: number): Promise<DeviceRow | null>;
 }
 /**
- * Async ancestor walk for `registerDevice`: the nearest located CONTAINER
- * ancestor's location, read row by row (registration has no fleet snapshot in
- * hand and must not pay for one). Same container-only predicate as
- * {@link planNullLocationFills}, and for the same reason — a child adopted
- * under a located CAMERA is already linked structurally to that camera, and a
- * location on its own column would make it a companion of every other camera
- * in the room. The nearest located ancestor decides: a located non-container
- * on the way up answers null. Cycle-guarded like the pure walk; a missing row
- * — a parent registered out of order — answers null, and the parent's own
- * later registration pulls the location down instead (see `registerDevice`).
- */
+* Async ancestor walk for `registerDevice`: the nearest located CONTAINER
+* ancestor's location, read row by row (registration has no fleet snapshot in
+* hand and must not pay for one). Same container-only predicate as
+* {@link planNullLocationFills}, and for the same reason — a child adopted
+* under a located CAMERA is already linked structurally to that camera, and a
+* location on its own column would make it a companion of every other camera
+* in the room. The nearest located ancestor decides: a located non-container
+* on the way up answers null. Cycle-guarded like the pure walk; a missing row
+* — a parent registered out of order — answers null, and the parent's own
+* later registration pulls the location down instead (see `registerDevice`).
+*/
 export declare function resolveInheritedLocation(rows: RowReader, parentDeviceId: number | null): Promise<string | null>;
 /**
- * Boot entrypoint: the one-shot repair (marker-guarded) plus the every-boot
- * detection. `bootRows` is the fleet listing the addon's warm-boot pass
- * already paid for — reused for the detection so a clean boot costs no extra
- * fleet read; ignored by the repair, which takes its own listing UNDER the
- * meta write lock (the snapshot must not predate the lock).
- */
+* Boot entrypoint: the one-shot repair (marker-guarded) plus the every-boot
+* detection. `bootRows` is the fleet listing the addon's warm-boot pass
+* already paid for — reused for the detection so a clean boot costs no extra
+* fleet read; ignored by the repair, which takes its own listing UNDER the
+* meta write lock (the snapshot must not predate the lock).
+*/
 export declare function runLocationBackfillAtBoot(pctx: ProviderContext, bootRows?: readonly DeviceRow[]): Promise<void>;

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

@@ -1,115 +1,192 @@
-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;
+* Replacing a camera: the new hardware becomes the device the system knows.
+*
+* ## Why the NUMBER moves instead of the work
+*
+* Everything general about a camera is keyed on the numeric `deviceId` and on
+* nothing else. The recording path on disk is `<deviceId>/profile/…`; the hour
+* ledger, the media store and zone ownership carry `deviceId` without one
+* `stableId` between them; and all four ecosystem exports — Home Assistant,
+* Alexa, HomeKit, Google — key on it. Moving that work would mean renaming
+* directories, rewriting a durable ledger and re-establishing four external
+* integrations. Moving the number is two rows ({@link DeviceRowStore.swapIds}).
+*
+* ## The rule the swap must obey
+*
+* **Role-scoped state follows the NUMBER. Hardware-scoped state follows the
+* DEVICE.** Tracks, faces, scenes, recordings, notification mutes — the work —
+* key on the number and stay put. State that DESCRIBES the box — the driver
+* config (host/credentials/`deviceCache`), the runtime-state slices, the
+* broker's probed snapshots, profile assignment and derived streams — must
+* move with it or be re-derived from the hardware now wearing the number
+* (`swapHardwareState`, `forgetStreamState`). Getting this wrong put two live
+* cameras in each other's identity on 2026-09-01: the new camera was dialled
+* at the old one's dead address forever, and a derived feeder defined against
+* the old profile layout respawned every ten seconds.
+*
+* ## The one thing this must never do
+*
+* Report a function as switched off when it could not ask.
+*
+* The source camera in a replacement is, characteristically, BROKEN — that is
+* why it is being replaced. Two of the eight switches (`privacy-mask` and
+* `device-audio`) write the CAMERA rather than the server: the camera holds the
+* fact and every read is a read-through, so on a dead camera they cannot be
+* written at all. A step that swallowed those failures would announce a device
+* put safely to sleep while it was still able to produce data, and the caller
+* would have no way to tell.
+*
+* So every switch gets an outcome of its own — {@link SwitchOutcome} — and
+* `unreachable` is a first-class answer, distinct both from `off` and from
+* `not-offered` (a switch this camera never had). The migration proceeds; the
+* report says what was actually done.
+*
+* ## Every switch write is BOUNDED — and the bound is honest
+*
+* A write that does not answer within {@link SWITCH_WRITE_TIMEOUT_MS} is
+* reported `unreachable` and the migration moves on. Measured on 2026-09-01: a
+* single unanswered write burned the transport's 60 s default, three phases
+* burned three minutes, and the CALLER's own timeout expired first — which is
+* how one migration became two (see `migrate-guard.ts`). Two rules the bound
+* must not break: a timed-out write is NEVER folded into `off`/`on` (a camera
+* we could not ask was not silenced), and the underlying write may still land
+* after the bound — which is safe, because every switch authority is
+* idempotent under a duplicate write of the same value.
+*
+* ## Order
+*
+* Claims first (a device under customization is refused before anything is
+* touched — D663), then functions down on BOTH devices, then the swap, then
+* functions up on the target — the device now answering on the inherited
+* number. Down-first is not
+* cosmetic: between the two writes a runner still holding the old number would
+* otherwise write frames, events or notifications against the wrong camera.
+*
+* ## After the disable phase, a failure is one of two things
+*
+* - **Refused, nothing moved** ({@link MigrationRefusedError}: a `swapIds`
+*   precheck, a failed mirror drain, a claim that landed during the start).
+*   Both cameras are put back EXACTLY as they were — the switch states read
+*   before the disable phase — never left
+*   dark for a migration that did not happen.
+* - **Failed while moving** (any other throw from `swapIds`, any throw from
+*   `swapHardwareState`). The devices may wear each other's identity, so they
+*   stay OFF and each gets an ERROR line naming what moved and that an
+*   operator must intervene. Switching them on would run pipelines against
+*   crossed identities.
+*/
+import type { 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 = 15e3;
 /** What actually happened to one switch on one device. */
-export type SwitchOutcome = 'off' | 'on' | 'not-offered' | 'unreachable';
+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;
+	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;
+	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;
 }
 /**
- * A camera's switch states as read before the disable phase: every switch the
- * camera OFFERS, with its state. A switch it does not offer is absent.
- */
+* A camera's switch states as read before the disable phase: every switch the
+* camera OFFERS, with its state. A switch it does not offer is absent.
+*/
 export type SwitchStates = ReadonlyMap<CameraSwitchId, boolean>;
 /** Severity of a per-device migration line. */
-export type MigrationLogLevel = 'warn' | 'error';
+export type MigrationLogLevel = "warn" | "error";
 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>;
-    /**
-     * 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>;
-    /**
-     * Refuse a migration over a device under customization
-     * (`migrate-hardware-state.ts::assertNoFieldClaims`, D663): a field claim
-     * names the NUMBER while its owner names the STABLE ID the swap moves, so no
-     * order of operations keeps both right. THROWS to refuse. Asked FIRST —
-     * before any switch is flipped, so a refused migration leaves both cameras
-     * exactly as they were.
-     */
-    readonly assertNoFieldClaims: (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;
-    /**
-     * The state of every switch the camera offers, read BEFORE the disable
-     * phase, so a migration refused before any row moved can put each switch
-     * back exactly as it was (D663 5b ruling I-1) — never blanket-on, which
-     * would undo a function the operator had switched off (D62). Bounded like a
-     * switch write; a read that fails is reported and the rollback falls back to
-     * switching that camera on.
-     */
-    readonly readSwitches: (deviceId: number) => Promise<SwitchStates>;
-    /** One line about ONE device, tagged with its id (D391). */
-    readonly logDevice: (level: MigrationLogLevel, deviceId: number, 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;
+	/** `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>;
+	/**
+	* 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>;
+	/**
+	* Refuse a migration over a device under customization
+	* (`migrate-hardware-state.ts::assertNoFieldClaims`, D663): a field claim
+	* names the NUMBER while its owner names the STABLE ID the swap moves, so no
+	* order of operations keeps both right. THROWS to refuse. Asked FIRST —
+	* before any switch is flipped, so a refused migration leaves both cameras
+	* exactly as they were.
+	*/
+	readonly assertNoFieldClaims: (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;
+	/**
+	* The state of every switch the camera offers, read BEFORE the disable
+	* phase, so a migration refused before any row moved can put each switch
+	* back exactly as it was (D663 5b ruling I-1) — never blanket-on, which
+	* would undo a function the operator had switched off (D62). Bounded like a
+	* switch write; a read that fails is reported and the rollback falls back to
+	* switching that camera on.
+	*/
+	readonly readSwitches: (deviceId: number) => Promise<SwitchStates>;
+	/** One line about ONE device, tagged with its id (D391). */
+	readonly logDevice: (level: MigrationLogLevel, deviceId: number, 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.
- *
- * 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.
- */
+* 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;
+	readonly sourceId: number;
+	readonly targetId: number;
 }): Promise<MigrateDeviceResult>;

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

@@ -1,46 +1,78 @@
-import { MigrateDeviceResult } from './migrate-device.js';
+/**
+* A migration must survive its own retry.
+*
+* On 2026-09-01 `migrateDevice` ran for ~3.5 minutes under the transport's 60 s
+* default timeout. The caller died with `UND_ERR_HEADERS_TIMEOUT`, something
+* retried the call, and a SECOND full cycle ran. Two swaps cancel out — the
+* operator saw "nothing happened" with no error — and had the timing differed
+* by a lock's width, two live cameras would have kept each other's identity
+* with no way to tell. The cap now declares a timeout that covers the real
+* runtime (`device-manager.cap.ts`), but a bound alone only makes the retry
+* rarer; this guard makes it harmless. Two rules:
+*
+* 1. **While a migration involving a device is in flight, a second call
+*    touching that device is REFUSED — never queued.** The meta write lock is
+*    FIFO, so without this the retry parks politely behind the first run and
+*    then re-swaps the moment it finishes. The refusal is loud and names the
+*    device; the running migration's report stands.
+* 2. **A repeat of a COMPLETED swap is a no-op returning the original
+*    report.** "Did this already run" is answerable from the rows: the swap
+*    moves `addonId`/`stableId` between the two numbers, so a completed
+*    migration leaves a fingerprint this guard records and compares. Only an
+*    exact match replays — same pair, same post-swap identities, within
+*    {@link MIGRATION_REPLAY_WINDOW_MS} — anything else is a new operation and
+*    runs. The window is what separates a client's automated retry (arrives
+*    within the transport timeout envelope) from an operator deliberately
+*    swapping the same pair back later: the first must be absorbed, the second
+*    must run.
+*
+* In-memory on purpose. The retry that matters arrives at the same hub process
+* that ran the first cycle; a hub restart empties the guard AND ends every
+* client call that could still be retrying against it.
+*/
+import type { 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;
+	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;
+	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.
- */
+* 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;
-    /**
-     * Is a migration involving this device running right now? A per-field claim,
-     * patch or release asks before touching the device's row (D663): the row is
-     * about to be swapped with another device's, and a claim written into that
-     * window would travel with the wrong hardware.
-     */
-    isInFlight(deviceId: number): boolean;
-    /** 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;
+	/** 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;
+	/**
+	* Is a migration involving this device running right now? A per-field claim,
+	* patch or release asks before touching the device's row (D663): the row is
+	* about to be swapped with another device's, and a claim written into that
+	* window would travel with the wrong hardware.
+	*/
+	isInFlight(deviceId: number): boolean;
+	/** 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;