@camstack/system 1.2.313 → 1.2.315

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

@@ -1,4 +1,6 @@
 import { DeviceManagerSettings } from './device-meta-store.js';
+import { 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 interface SwappedHardwareState {
@@ -14,6 +16,59 @@ export interface SwappedHardwareState {
     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[];
+}
+/** A device whose row carries claims, and what they are. */
+export interface ClaimBlockedDevice {
+    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.
+ */
+export declare class FieldClaimsBlockMigrationError extends Error {
+    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.
+ */
+export declare class ClaimLandedDuringMigrationError extends MigrationRefusedError {
+    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.
+ */
+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>;
 /**
  * Swap the hardware-scoped halves of two devices' persisted state. Runs right
  * after `swapIds`, under the same meta write lock. THROWS on failure: a

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

@@ -0,0 +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.
+ */
+export declare class MigrationRefusedError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}

package/dist/builtins/device-manager/mirror-row-writer.d.ts

@@ -0,0 +1,138 @@
+import { IScopedLogger } from '@camstack/types';
+import { DeviceManagerSettings } from './device-meta-store.js';
+import { MigrationRefusedError } from './migration-refused.js';
+import { RuntimeStatePolicyLookup } from './runtime-state-persist-gate.js';
+/** A device's row as it may reach disk: cap name → persistable slice (plus `$owned`). */
+export type PersistableRow = Record<string, Record<string, unknown>>;
+/**
+ * The drain before a migration could not vouch for a device's row. Nothing has
+ * moved yet, so it is a {@link MigrationRefusedError}: the migration refuses
+ * and restores both cameras' switches.
+ */
+export declare class RuntimeStateDrainError extends MigrationRefusedError {
+    readonly deviceId: number;
+    constructor(deviceId: number, reason: string, options?: ErrorOptions);
+}
+/** A migration's hold on the debounced writer (`holdDiskWrites`). */
+export interface MirrorWriteHold {
+    /** Let the writer back onto the rows; re-arms it so the row converges to memory. */
+    readonly release: () => void;
+}
+/** What the writer needs from the mirror that owns it. */
+export interface MirrorRowWriterDeps {
+    readonly logger: IScopedLogger;
+    /** Per-cap durability + volatile-field policy (D4). */
+    readonly policyFor: RuntimeStatePolicyLookup;
+    /** The device's row as memory holds it NOW — taken when a write RUNS. */
+    readonly persistableFor: (deviceId: number) => PersistableRow;
+}
+export declare class MirrorRowWriter {
+    private readonly deps;
+    static readonly RUNTIME_STATE_DEBOUNCE_MS = 1000;
+    /**
+     * Per-device disk-write debouncer for runtime-state. `setCapSlice`
+     * updates the in-memory mirror synchronously and emits the change
+     * event immediately, but the disk write is coalesced.
+     */
+    private readonly runtimeStateDebounce;
+    /**
+     * Devices whose debounced writer is HELD off the row — a migration is
+     * swapping it (`holdDiskWrites`). A change while held stays in memory only.
+     */
+    private readonly writesHeld;
+    /** Held devices a durable change was scheduled for — what `release` re-arms. */
+    private readonly heldDirty;
+    /**
+     * What is believed to be ON DISK for each device — the persistable projection
+     * of the last blob actually written (or read at seed time). The
+     * effective-change gate compares against THIS, not against the previous
+     * mirror state: two clock-only ticks in a row must not add up to a write just
+     * because each was compared with its immediate predecessor.
+     */
+    private readonly lastPersisted;
+    /**
+     * Per-device count of writes the effective-change gate skipped since the last
+     * real one. Reported on the next write that DOES happen, so the log says how
+     * much churn the gate absorbed instead of saying nothing at all — a branch
+     * that drops work silently reads as "never happened".
+     */
+    private readonly skippedSinceWrite;
+    constructor(deps: MirrorRowWriterDeps);
+    /** What is believed to be on the device's row; undefined before any read or write. */
+    persisted(deviceId: number): PersistableRow | undefined;
+    /** Record what the row now holds — a write that landed, or a row just read. */
+    markPersisted(deviceId: number, row: PersistableRow): void;
+    /** A migration holds the writer off this device's row right now. */
+    isHeld(deviceId: number): boolean;
+    /**
+     * Chain a row write behind whatever is in flight for the device. Returns the
+     * write's own promise (it may reject, to its caller); the queue tail never
+     * rejects and clears itself once it is the last one out.
+     */
+    serialiseWrite<T>(deviceId: number, task: () => Promise<T>): Promise<T>;
+    private slotFor;
+    /** Arm the writer for a durable change, or remember it for `release` while a migration holds the device. */
+    armOrHold(deviceId: number, settings: DeviceManagerSettings): void;
+    /**
+     * Debounced disk writer, behind two gates.
+     *
+     * GATE — DURABILITY: a change to a `durability: 'session'` cap never even
+     * arms the timer. That is where the fleet's write rate goes: `audio-metrics`
+     * and `zone-analytics` are ~90 % of the offered 12–19 writes/s, they change
+     * genuinely every second, and their restored value is worthless.
+     *
+     * GATE — EFFECTIVE CHANGE (at flush): the persistable blob is compared with
+     * what is believed to be on disk, ignoring the clock fields each cap declared
+     * volatile. `battery` wrote its blob 526 times in 25 minutes without one
+     * percentage moving; this is the gate that turns those into one write.
+     *
+     * The blob is read from the live mirror at flush time, so the disk picture is
+     * always the latest state — no risk of writing a stale snapshot.
+     */
+    schedule(deviceId: number, settings: DeviceManagerSettings, changedCap: string): void;
+    /** Arm the debounce timer; at fire, queue a write of the live blob unless disk already has it. */
+    private armDiskWrite;
+    /** The debounced write itself: the blob as memory holds it NOW, behind the effective-change gate. Never rejects. */
+    private writeLiveBlob;
+    /**
+     * Hold the debounced writer off these devices' rows while a migration swaps
+     * them (D663 re-review N-6). Resolves once each device is DRAINED: a write
+     * still in its debounce window is written now (it is this hardware's latest
+     * state, and the swap then carries it to the right number), and a write
+     * already in flight has landed. Until `release`, nothing the writer does
+     * reaches these rows — a blob read before the swap and written after it would
+     * put the other box's state back under the number, and make it the baseline.
+     *
+     * Only what the writer already had pending is written — never memory
+     * wholesale, which for a row nobody read would overwrite it with a partial
+     * picture. `release` re-arms the writer for a device changed while held:
+     * after the migration's `replace` reseed memory equals the row and nothing
+     * is written; after a failed swap the row converges to memory.
+     *
+     * The migration must not proceed over a row that is not what memory says it
+     * is. So a drain write that FAILS, and equally a write that was in flight and
+     * FAILED (ruling I-2 — awaiting it is not the same as it landing), release
+     * the hold, log the device and reject with a {@link RuntimeStateDrainError};
+     * the owed write is re-armed on release.
+     *
+     * One hold per device at a time: `writesHeld` is a set, not a refcount, so a
+     * second overlapping hold would be released by the first. Safe because the
+     * only caller is `migrateDevice`, serialised by `migrationGuard` and the meta
+     * write lock; a new caller needs a refcount first.
+     */
+    holdDiskWrites(deviceIds: readonly number[], settings: DeviceManagerSettings): Promise<MirrorWriteHold>;
+    /** Cancel the timer, await the write in flight, then write (queued) what is not yet on disk. */
+    private drainDiskWrite;
+    /** A drain that cannot vouch for the row: still owed (re-armed on release), logged, refused. */
+    private refuseDrain;
+    /**
+     * True when `blob` differs from what is believed to be on disk only in fields
+     * the owning caps declared volatile. Counts the skip so the next real write
+     * can report how much churn was absorbed.
+     */
+    private isAlreadyPersisted;
+    /** Flush every pending debounced disk write (graceful shutdown). Clears the
+     *  debounce slots after awaiting in-flight + scheduled writes so shutdown is
+     *  lossless. */
+    flushPendingWrites(settings: DeviceManagerSettings | undefined): Promise<void>;
+}

package/dist/builtins/device-manager/runtime-state-persist-gate.d.ts

@@ -11,6 +11,10 @@ export type RuntimeStateBlob = Readonly<Record<string, Readonly<Record<string, u
  * direction is deliberate: the cost of losing a session value is a cold window
  * until the provider republishes; the cost of persisting an unasked-for one is
  * a commit per second on the fleet's busiest write path.
+ *
+ * `$owned` is not a cap: it is the device's claims record (D663) and is kept
+ * whatever the lookup says — a restart that forgot who owns a field would hand
+ * it back to the native provider.
  */
 export declare function persistableBlob(blob: RuntimeStateBlob, policyFor: RuntimeStatePolicyLookup): Record<string, Record<string, unknown>>;
 /**

package/dist/builtins/doorbell/binding-mirror.d.ts

@@ -84,6 +84,7 @@ export interface BindingEntryView {
     readonly capName: string;
     readonly kind: string;
     readonly providerAddonId: string;
+    readonly nativeAddonId?: string;
 }
 /**
  * Does this list of binding entries name `ownAddonId` as the ACTIVE WRAPPER

package/dist/builtins/doorbell/doorbell-composition-migration.d.ts

@@ -0,0 +1,59 @@
+import { CompositionFieldsFeature, CompositionSourceRef, DeviceType, ICoreBlocksProvider, IScopedLogger } from '@camstack/types';
+import { BindingEntryView } from './binding-mirror.js';
+import { DoorbellSource } from './doorbell-settings.js';
+export declare const DOORBELL_COMPOSITION_MIGRATION_STATE_KEY = "doorbell-source-composition-migration-v1";
+export declare const DOORBELL_COMPOSITION_MIGRATION_CALLER: {
+    readonly userId: "system:doorbell-source-migration";
+    readonly isAdmin: true;
+};
+export interface DoorbellMigrationDevice {
+    readonly id: number;
+    readonly addonId: string;
+    readonly stableId: string;
+    readonly type: DeviceType;
+}
+export interface DoorbellMigrationBindingRow {
+    readonly deviceId: number;
+    readonly entries: readonly BindingEntryView[];
+}
+export interface DoorbellCompositionMigrationDeps {
+    readonly logger: IScopedLogger;
+    readonly listCameras: () => Promise<readonly DoorbellMigrationDevice[]>;
+    readonly listSourceDevices: (deviceIds: readonly number[]) => Promise<readonly DoorbellMigrationDevice[]>;
+    readonly readSources: (cameraId: number) => Promise<readonly DoorbellSource[]>;
+    readonly getBindingsBatch: (deviceIds: readonly number[]) => Promise<readonly DoorbellMigrationBindingRow[]>;
+    readonly coreBlocks: () => ICoreBlocksProvider | null;
+    readonly setWrapperActive: (input: {
+        readonly deviceId: number;
+        readonly capName: 'doorbell';
+        readonly wrapperAddonId: 'virtual-doorbell';
+        readonly active: false;
+    }) => Promise<void>;
+    readonly isComplete: () => Promise<boolean>;
+    readonly markComplete: () => Promise<void>;
+}
+interface DoorbellFeatureSource {
+    readonly source: CompositionSourceRef;
+    readonly cap: string;
+    readonly activeField: string;
+    readonly changedAtField: string;
+}
+export declare function buildDoorbellCompositionFeature(input: {
+    readonly camera: CompositionSourceRef;
+    readonly sources: readonly DoorbellFeatureSource[];
+    readonly enabled: boolean;
+}): CompositionFieldsFeature;
+export declare class DoorbellCompositionMigration {
+    private readonly deps;
+    private rerunRequested;
+    private inFlight;
+    private stopped;
+    constructor(deps: DoorbellCompositionMigrationDeps);
+    request(reason: string): void;
+    waitForIdle(): Promise<void>;
+    shutdown(): void;
+    private runUntilQuiet;
+    private runAttempt;
+    private warnCamera;
+}
+export {};

package/dist/builtins/doorbell/virtual-doorbell.addon.d.ts

@@ -42,6 +42,8 @@ interface VirtualDoorbellAddonConfig {
  */
 export declare class VirtualDoorbellAddon extends BaseAddon<VirtualDoorbellAddonConfig> {
     private engine;
+    private compositionMigration;
+    private providerRegisteredUnsubscribe;
     /** Monotonic guard: assignments are reloaded lazily on trigger traffic. */
     private assignmentsLoadedAt;
     private assignmentsLoading;
@@ -53,6 +55,7 @@ export declare class VirtualDoorbellAddon extends BaseAddon<VirtualDoorbellAddon
     private readonly bindingMirror;
     constructor();
     protected onInitialize(): Promise<ProviderRegistration[]>;
+    protected onShutdown(): Promise<void>;
     /**
      * The `device-extension` provider: the only editor of a camera's trigger
      * devices since D655 (see `doorbell-extension-slot.ts`).