@camstack/system 1.2.313 → 1.2.315

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

@@ -2,8 +2,12 @@ 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 { FieldClaimsIndex } from './field-claims-index.js';
+import { OwnedCaps } from './field-ownership.js';
 import { MigrationGuard } from './migrate-guard.js';
 import { RemovalFence } from './removal-fence.js';
+import { SeedMode } from './device-state-mirror.js';
+import { MirrorWriteHold } from './mirror-row-writer.js';
 type IDeviceProviderCap = InferProvider<typeof deviceProviderCapability>;
 /**
  * The addon-instance surface the extracted provider functions need. Exposed by
@@ -18,10 +22,28 @@ export interface ProviderHost {
         addonId: string;
         nodeId: string;
     }>>;
-    /** Seed the runtime-state mirror for a device (boot path, no events). */
-    seedMirror(deviceId: number, blob: Record<string, unknown>): void;
+    /**
+     * Seed the runtime-state mirror for a device (no events). `fill` (the boot
+     * path) only fills caps memory lacks; `replace` (the migration reseed) makes
+     * the mirror answer exactly this blob — the row now belongs to different
+     * hardware, so whatever memory held is the wrong device's state (D663).
+     */
+    seedMirror(deviceId: number, blob: Record<string, unknown>, mode?: SeedMode): void;
+    /**
+     * Drain the mirror's debounced writer on these devices and hold it off their
+     * rows until `release` — a migration swapping the rows must not race a write
+     * that read the pre-swap hardware's blob (D663).
+     */
+    holdMirrorWrites(deviceIds: readonly number[], settings: DeviceManagerSettings): Promise<MirrorWriteHold>;
+    /**
+     * The claims the mirror holds for a device — accepted ones included, whose
+     * write-through may not have landed yet. A migration's second look (D663).
+     */
+    mirrorOwnedCaps(deviceId: number): OwnedCaps;
     /** Reset a stale per-session `feature-probe` timestamp before mirror seeding. */
     withResetSessionProbe(blob: Record<string, unknown>): Record<string, unknown>;
+    /** The per-field claims index (D663) — `removeDevice` prunes a removed device from it. */
+    readonly fieldClaims: FieldClaimsIndex;
     /** Resolve a device's real `online` flag from the mirrored device-status slice. */
     resolveDeviceOnline(deviceId: number, fallbackOnline: boolean): boolean;
     /** Resolve a device's `probed` flag from the mirrored feature-probe slice. */

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

@@ -378,6 +378,8 @@ export declare class DeviceRowStore {
      * functions on both devices in the same critical section.
      */
     swapIds(a: number, b: number, tempId: number): Promise<void>;
+    /** The read-only half of {@link swapIds}: every refusal, every read, no write. */
+    private planSwap;
     /** 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;

package/dist/builtins/device-manager/device-state-claim-views.d.ts

@@ -0,0 +1,77 @@
+import { z } from 'zod';
+import { ClaimOutcome, IScopedLogger } from '@camstack/types';
+import { MergedSlice, OwnedCap, OwnedCaps } from './field-ownership.js';
+/** Resolves a cap's `runtimeState` schema by name; null when it declares none. */
+export type RuntimeStateSchemaLookup = (capName: string) => z.ZodType | null;
+/** Per (device, cap) state of a claimed cap: what the merge last said, and the
+ *  last GOOD merged slice — kept readable while a bad overlay holds the cap. */
+export interface ClaimedView {
+    readonly merged: MergedSlice;
+    readonly visible: Readonly<Record<string, unknown>> | null;
+}
+/** What the views need from their owner: the schema, the log and the public emit. */
+export interface ClaimViewSink {
+    readonly logger: IScopedLogger;
+    readonly schemaFor: RuntimeStateSchemaLookup;
+    emitSlice(deviceId: number, capName: string, slice: Record<string, unknown>): void;
+}
+/** Lazily indexes the codegen'd cap set — the hub already carries the barrel. */
+export declare function defaultSchemaFor(capName: string): z.ZodType | null;
+export declare function sameOwnedCap(a: OwnedCap, b: OwnedCap): boolean;
+type ClaimRefusal = Extract<ClaimOutcome, {
+    ok: false;
+}>;
+export declare function refused(code: ClaimRefusal['code'], message: string): ClaimOutcome;
+export declare class ClaimViews {
+    private readonly sink;
+    /** Claims by device, by cap. Absent for every device without one. */
+    private readonly owned;
+    /** The merged view of each claimed cap; recomputed on every native or owned write. */
+    private readonly views;
+    constructor(sink: ClaimViewSink);
+    claim(deviceId: number, capName: string): OwnedCap | undefined;
+    setClaim(deviceId: number, capName: string, claim: OwnedCap): void;
+    /** Removes the claim AND its view. */
+    deleteClaim(deviceId: number, capName: string): void;
+    /** Fill gaps only: a claim already in memory was written through and is newer than the row. */
+    seedClaims(deviceId: number, claims: OwnedCaps): void;
+    clearDevice(deviceId: number): void;
+    ownedCaps(deviceId: number): OwnedCaps;
+    claimsOf(deviceId: number): Iterable<[string, OwnedCap]>;
+    /** Devices with at least one view — for the whole-system dump. */
+    deviceIds(): Iterable<number>;
+    isClaimed(deviceId: number, capName: string): boolean;
+    /** `undefined` when the cap is not claimed; `null` when it is claimed and held with nothing to show. */
+    visible(deviceId: number, capName: string): Readonly<Record<string, unknown>> | null | undefined;
+    /** Every claimed cap of a device that currently has something to show. */
+    visibleCaps(deviceId: number): Iterable<[string, Readonly<Record<string, unknown>>]>;
+    /** What the merge says for a claimed cap; null when the cap is not claimed. */
+    effective(deviceId: number, capName: string): MergedSlice | null;
+    view(deviceId: number, capName: string): ClaimedView | undefined;
+    /** Put a view back (rollback of a failed write-through); `undefined` removes it. */
+    restoreView(deviceId: number, capName: string, view: ClaimedView | undefined): void;
+    /**
+     * Recompute a claimed cap's merged view and emit it when it is a slice and
+     * either changed or `emitUnchanged` (the native moved). A held view emits
+     * nothing and logs once per transition, naming the fields; a bad overlay
+     * keeps the last good slice readable, a missing value or native does not.
+     */
+    recompute(deviceId: number, capName: string, claim: OwnedCap, native: Readonly<Record<string, unknown>> | null, emitUnchanged: boolean): void;
+    /**
+     * The view a claim has NOW — set, never emitted, never logged. A claim is
+     * written through, and readers must see it from the moment it is accepted
+     * (S5): without this, `capSlice` answered the NATIVE for an already-claimed
+     * field for the whole row round-trip (D663 re-review N-5). The emit is judged
+     * later, by `recompute`, against what consumers last saw.
+     */
+    previewView(deviceId: number, capName: string, claim: OwnedCap, native: Readonly<Record<string, unknown>> | null): void;
+    /** The one rule for what a claimed cap shows: the merge when it is a slice; on
+     *  a bad overlay the last good slice stays readable; a value or native not yet
+     *  arrived shows nothing. */
+    private derive;
+    /** The merged view for a claim that arrived by seed: computed, never emitted. */
+    seedView(deviceId: number, capName: string, claim: OwnedCap, native: Readonly<Record<string, unknown>> | null): void;
+    private ownedFor;
+    private viewsFor;
+}
+export {};

package/dist/builtins/device-manager/device-state-claims.d.ts

@@ -0,0 +1,43 @@
+import { ClaimOutcome, ClaimsListing, FieldClaimMode, IScopedLogger } from '@camstack/types';
+import { DeviceManagerSettings } from './device-meta-store.js';
+import { DeviceStateMirror } from './device-state-mirror.js';
+import { FieldClaimsIndex } from './field-claims-index.js';
+export interface ClaimFieldsInput {
+    readonly deviceId: number;
+    readonly capName: string;
+    readonly owner: string;
+    readonly mode: FieldClaimMode;
+    readonly fields: readonly string[];
+    readonly values: Readonly<Record<string, unknown>>;
+}
+export interface PatchOwnedFieldsInput {
+    readonly deviceId: number;
+    readonly capName: string;
+    readonly owner: string;
+    readonly values: Readonly<Record<string, unknown>>;
+}
+export interface ReleaseClaimInput {
+    readonly deviceId: number;
+    readonly capName: string;
+    readonly owner: string;
+}
+export interface ListClaimsInput {
+    readonly ownerPrefix?: string;
+}
+export interface DeviceStateClaimMethods {
+    claimFields(input: ClaimFieldsInput): Promise<ClaimOutcome>;
+    patchOwnedFields(input: PatchOwnedFieldsInput): Promise<ClaimOutcome>;
+    releaseClaim(input: ReleaseClaimInput): Promise<ClaimOutcome>;
+    listClaims(input: ListClaimsInput): Promise<ClaimsListing>;
+}
+export interface DeviceStateClaimDeps {
+    readonly mirror: Pick<DeviceStateMirror, 'claim' | 'patchOwned' | 'release'>;
+    readonly index: FieldClaimsIndex;
+    readonly settings: DeviceManagerSettings;
+    readonly logger: IScopedLogger;
+    /** Is this a device the ledger knows? `resolvePersistedById(id) !== null`. */
+    deviceExists(deviceId: number): Promise<boolean>;
+    /** Is a migration involving this device running right now? */
+    migrationInFlight(deviceId: number): boolean;
+}
+export declare function createDeviceStateClaimMethods(deps: DeviceStateClaimDeps): DeviceStateClaimMethods;

package/dist/builtins/device-manager/device-state-mirror.d.ts

@@ -1,6 +1,28 @@
-import { AddonContext } from '@camstack/types';
+import { AddonContext, ClaimOutcome } from '@camstack/types';
 import { DeviceManagerSettings } from './device-meta-store.js';
+import { RuntimeStateSchemaLookup } from './device-state-claim-views.js';
+import { MergedSlice, OwnedCap, OwnedCaps } from './field-ownership.js';
+import { MirrorWriteHold } from './mirror-row-writer.js';
 import { RuntimeStatePolicyLookup } from './runtime-state-persist-gate.js';
+/**
+ * What the seed consults first: the claims index (Task 6). It is written
+ * BEFORE the row, so a loaded index is a superset of the rows' claims and a
+ * device it does not name has nothing to merge — no row read (D447).
+ */
+export type ClaimsIndexView = {
+    readonly state: 'loaded';
+    hasClaims(deviceId: number): boolean;
+} | {
+    readonly state: 'not-loaded';
+};
+/**
+ * How `seedMirror` treats what memory already holds. `fill` (boot, first
+ * write) only adds caps memory lacks — memory is never behind the row.
+ * `replace` (the migration reseed) drops the device's slices, claims and views
+ * first: the row now describes different hardware, so everything memory held
+ * under that number is the wrong device's state.
+ */
+export type SeedMode = 'fill' | 'replace';
 export declare class DeviceStateMirror {
     private readonly ctx;
     /**
@@ -10,46 +32,41 @@ export declare class DeviceStateMirror {
      */
     private readonly policyFor;
     /**
-     * Hub-side mirror of every device's cap-keyed runtime state.
-     * Key: deviceId. Value: per-cap slice map. Empty by default —
+     * Hub-side mirror of every device's cap-keyed NATIVE runtime state — what the
+     * provider wrote. Key: deviceId. Value: per-cap slice map. Empty by default —
      * slices show up as `setCapSlice` calls trickle in.
      */
     private readonly stateMirror;
-    /**
-     * 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;
-    private static readonly RUNTIME_STATE_DEBOUNCE_MS;
-    /**
-     * What is believed to be ON DISK for each device — the persistable projection
-     * of the last blob actually written (or seeded at boot). 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;
+    /** The claims and the merged view of every claimed cap (D663). */
+    private readonly claims;
+    /** Devices whose row has been consulted (or ruled empty by the index). */
+    private readonly seeded;
+    /** Devices whose row was actually READ into memory — a write-through needs this. */
+    private readonly rowRead;
+    /** One row read per device, however many writes arrive during it. */
+    private readonly seeding;
+    /** Devices whose seed refusal is already logged — once per transition. */
+    private readonly seedRefusalLogged;
+    /** Every write of a device's row, and what is believed to be on it. */
+    private readonly writer;
     constructor(ctx: AddonContext, 
     /**
      * Per-cap durability + volatile-field policy. Defaults to the codegen'd
      * projection of every `*.cap.ts` (D4: the cap declares, the kernel reads).
      * Injectable so a spec can exercise the gate without the real cap set.
      */
-    policyFor?: RuntimeStatePolicyLookup);
+    policyFor?: RuntimeStatePolicyLookup, 
+    /** The cap's `runtimeState` schema a merged slice is parsed with (D663). */
+    schemaFor?: RuntimeStateSchemaLookup);
     /**
      * Single-cap mirror update — diff against the current mirror,
      * persist the new slice in-memory, emit `DeviceStateChanged` for
      * this cap. No-op on identical writes (both same shape and same
      * values). Called by `setCapSlice` provider.
      *
+     * This is the NATIVE path, unchanged for every writer. Under a claim the
+     * native slice is stored as the shadow and what is emitted is the merge.
+     *
      * @returns whether the mirror actually changed. The caller uses this to
      *   decide whether the (synchronous, disk-blocking) runtime-state write is
      *   worth scheduling — see `scheduleRuntimeStateDiskWrite`. Returning void
@@ -58,41 +75,95 @@ export declare class DeviceStateMirror {
      */
     applySingleCapUpdate(deviceId: number, capName: string, slice: Record<string, unknown>): boolean;
     /**
-     * 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.
+     * Claim `cap.fields` of `capName` on `deviceId` for `cap.owner`. Written
+     * through: resolves after the row write. A re-claim by the same owner
+     * replaces `fields`; values of fields no longer claimed are dropped and the
+     * native shows for them (ruling S1b). An empty `fields` is what the composer
+     * never sends — it releases — and is refused.
      */
-    scheduleRuntimeStateDiskWrite(deviceId: number, settings: DeviceManagerSettings, changedCap: string): void;
+    claim(deviceId: number, capName: string, cap: OwnedCap, settings: DeviceManagerSettings): Promise<ClaimOutcome>;
+    /** Is this exact claim what the row carries, per `lastPersisted`? */
+    private isClaimPersisted;
     /**
-     * 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.
+     * Write owned values. Partial patches MERGE into `values` (ruling S5); a key
+     * outside `fields` is refused. Debounced like a native slice.
      */
-    private isAlreadyPersisted;
-    /** The device's mirror, restricted to the slices that may reach disk. */
+    patchOwned(deviceId: number, capName: string, owner: string, values: Readonly<Record<string, unknown>>, settings: DeviceManagerSettings): Promise<ClaimOutcome>;
+    /**
+     * Remove the claim. A `replace` hands the cap back: the native slice is
+     * emitted exactly as last written. An `add` had no native — the cap leaves
+     * the mirror and nothing is emitted (consumer mirrors keep the last value
+     * until they re-read; recorded for Task 15). Written through.
+     */
+    release(deviceId: number, capName: string, owner: string, settings: DeviceManagerSettings): Promise<ClaimOutcome>;
+    /** The claims on a device; empty for every device without one. */
+    ownedCaps(deviceId: number): OwnedCaps;
+    /** The NATIVE shadow of one cap — for the owner-side mechanism only (D224). */
+    nativeSlice(deviceId: number, cap: string): Record<string, unknown> | null;
+    /** What the merge says for a claimed cap; null when the cap is not claimed. */
+    effectiveIfClaimed(deviceId: number, cap: string): MergedSlice | null;
+    isSeeded(deviceId: number): boolean;
+    /**
+     * The SYNCHRONOUS half of {@link ensureSeeded}, branch (c): a LOADED claims
+     * index that does not name the device vouches for it — seeded, no read.
+     * Refused (false) while a read is in flight, because that read may be
+     * landing a claim the index does not know yet; refused when the index cannot
+     * vouch. The overlay's `peek` calls this instead of `ensureSeeded`: a sync
+     * path must never hold a promise that can reject (D391 — an unhandled
+     * rejection is an untagged line on hub-main).
+     */
+    seedIfIndexClears(deviceId: number, index: ClaimsIndexView): boolean;
+    /**
+     * Make sure the device's claims are known before a native write is applied
+     * (D49). Index first, single-flight (ruling S6):
+     *   (a) already seeded → nothing;
+     *   (b) a seed in flight → await it;
+     *   (c) a LOADED index that does not name the device → seeded, no read;
+     *   (d) otherwise read the row once and seed it.
+     * A read that throws propagates — the write is refused — and is logged once
+     * per device transition (D391).
+     */
+    ensureSeeded(deviceId: number, settings: DeviceManagerSettings, index: ClaimsIndexView): Promise<void>;
+    /** A write-through replaces the whole row: memory must hold what the row held. */
+    private ensureRowRead;
+    /** An unreadable row is a NAMED refusal (D49): the answer is unknown — a
+     *  throw could be read as "gone", `not-claimed` as "never was". Logged by `readRowOnce`. */
+    private readRowOrRefuse;
+    private readRowOnce;
+    private nativeOf;
+    /**
+     * Write the row now — a claim is atomic with the row — and refresh the
+     * baseline. Queued behind any write in flight for the device (one row write
+     * at a time, N-4), and the blob is taken when the write RUNS, so it carries
+     * whatever memory holds by then. A failed write is rolled back in memory IF
+     * what this op put there is still there (the two never disagree); when a
+     * newer same-owner state landed in the window it stands, and the debounced
+     * writer converges the row to it. Either way the failure is logged hub-side
+     * (D391) and rethrown; a repeat of the same claim is then a real write, never
+     * `changed: false`, and consumers are handed the truth that stands.
+     */
+    private writeThrough;
+    /** After a rollback, re-emit what is true now: the restored claim's merge, or the native. */
+    private reemitAfterRollback;
+    /** Arm the debounced writer for a change to `changedCap` — see `MirrorRowWriter.schedule`. */
+    scheduleRuntimeStateDiskWrite(deviceId: number, settings: DeviceManagerSettings, changedCap: string): void;
+    /** Hold the writer off these rows for a migration — see `MirrorRowWriter.holdDiskWrites`. */
+    holdDiskWrites(deviceIds: readonly number[], settings: DeviceManagerSettings): Promise<MirrorWriteHold>;
+    /** Flush every pending debounced disk write (graceful shutdown). */
+    flushPendingWrites(settings: DeviceManagerSettings | undefined): Promise<void>;
+    /** The device's row as it may reach disk: NATIVE slices plus `$owned`, restricted by durability. */
     private persistableForDevice;
     /**
-     * One-shot mirror seed used by `loadRuntimeState` at boot so the
-     * hub knows about every persisted slice without waiting for the
-     * first `setCapSlice` call. No events emitted — this is
-     * initial-state population, not a transition.
-     *
-     * Callers that must not carry a stale per-session probe across a
-     * restart pass the blob through `withResetSessionProbe` first (see
-     * `loadRuntimeState`).
+     * One-shot mirror seed used by `loadRuntimeState` at boot so the hub knows
+     * every persisted slice before the first `setCapSlice`. No events emitted —
+     * population, not a transition. `fill` (default) fills GAPS and never
+     * overwrites memory (ruling S6: a slice in memory is at least as new as the
+     * row, a claim in memory was written through); `replace` (the migration
+     * reseed) drops the device's memory first — the row now belongs to different
+     * hardware. Malformed `$owned` entries are dropped by name and logged once.
+     * Callers pass the blob through `withResetSessionProbe` first.
      */
-    seedMirror(deviceId: number, blob: Record<string, unknown>): void;
+    seedMirror(deviceId: number, blob: Record<string, unknown>, mode?: SeedMode): void;
     /**
      * The hub mirror's `feature-probe.lastProbedAt` is a PER-SESSION liveness
      * signal — it means "this worker process completed a probe THIS session".
@@ -140,16 +211,29 @@ export declare class DeviceStateMirror {
      * `true` — a brief transient window, same as `resolveDeviceOnline`.
      */
     resolveDeviceProbed(deviceId: number): boolean;
+    /** The EFFECTIVE slices of a device: native for an unclaimed cap, the merge
+     *  for a claimed one (a held cap is not reported). */
     snapshotForDevice(deviceId: number): Record<string, Record<string, unknown>>;
-    /** One cap's mirrored slice, cloned. Null when the device has never written
-     *  it — callers read that as "the cap has no state", never as an empty slice. */
+    /** One cap's EFFECTIVE slice, cloned. Null when the device has never written
+     *  it — callers read that as "the cap has no state", never as an empty slice —
+     *  and null while a claim holds it. */
     capSlice(deviceId: number, cap: string): Record<string, unknown> | null;
+    /** The device's NATIVE slices — what the row stores under the cap names. */
+    private nativeSnapshotForDevice;
     /** Whole-system mirror dump. Backs `deviceState.getAllSnapshots` — one
      *  round-trip for a warm boot instead of N per-device calls. */
     allSnapshots(): Record<string, Record<string, Record<string, unknown>>>;
+    /**
+     * The PUBLIC event: exactly `{ deviceId, capName, slice }` for every device,
+     * claimed or not. The native shadow never rides here (D224) — see
+     * `emitNativeShadow`.
+     */
     private emitStateChanged;
-    /** 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>;
+    /**
+     * The owner-only event (D224, D663): the native slice as the provider wrote
+     * it, for the composer's native self-reads. Its category is refused by the
+     * public event routers (`isOwnerOnlyEventCategory`), so no UI or share-scope
+     * subscriber ever sees a second truth beside the merged slice.
+     */
+    private emitNativeShadow;
 }

package/dist/builtins/device-manager/field-claims-index.d.ts

@@ -0,0 +1,69 @@
+import { ClaimsListing, FieldClaim, IScopedLogger } from '@camstack/types';
+import { DeviceManagerSettings } from './device-meta-store.js';
+import { ClaimsIndexView } from './device-state-mirror.js';
+import { WriteLock } from './write-lock.js';
+/** The addon-store key the index lives under. */
+export declare const FIELD_CLAIMS_INDEX_KEY = "field-claims-index";
+/** One claim's identity in the index: a cap on a device has at most one owner. */
+export interface ClaimKey {
+    readonly deviceId: number;
+    readonly capName: string;
+}
+/** A read-modify-write step over the loaded entries; null means nothing to write. */
+export type IndexTransform = (current: ReadonlyMap<string, FieldClaim>) => ReadonlyMap<string, FieldClaim> | null;
+export interface FieldClaimsIndexDeps {
+    readonly logger: IScopedLogger;
+    /**
+     * The addon's own settings row-set lock, shared with every other writer of
+     * it: `writeAddonStore` is a read-modify-write of the WHOLE key range on the
+     * store side, so unordered writers destroy each other's keys.
+     */
+    readonly withAddonStoreWriteLock: WriteLock;
+}
+export declare class FieldClaimsIndex {
+    private readonly deps;
+    /** The loaded entries by key, or null until a load has succeeded. */
+    private entries;
+    /** Devices with at least one entry — what the seed asks, per native write. */
+    private claimedDevices;
+    /** Why the last load did not succeed. */
+    private notLoadedReason;
+    /** One load in flight at a time; concurrent callers join it. */
+    private loading;
+    constructor(deps: FieldClaimsIndexDeps);
+    /**
+     * Load the blob. Resolves `true` once the index is loaded (now or already);
+     * `false` when the store could not answer — the reason is kept for `list`.
+     * Never throws: an index that cannot load is a state, not a failure.
+     */
+    load(settings: DeviceManagerSettings): Promise<boolean>;
+    /** What the seed consults: loaded with a device predicate, or not loaded. */
+    view(): ClaimsIndexView;
+    /** Every entry, optionally those whose owner starts with `ownerPrefix`; or why there is no answer. */
+    list(ownerPrefix?: string): ClaimsListing;
+    /** The entry for a key, when the index is loaded and has one. */
+    entry(key: ClaimKey): FieldClaim | undefined;
+    /** Add or replace one entry — written before the row it announces. Throws when the index cannot be loaded or written. */
+    upsert(claim: FieldClaim, settings: DeviceManagerSettings): Promise<void>;
+    /** Remove one entry — written after the row no longer carries the claim. No write when absent. */
+    remove(key: ClaimKey, settings: DeviceManagerSettings): Promise<void>;
+    /**
+     * Drop every entry of a removed device (condition i). Best effort: an index
+     * that cannot be loaded or written keeps a stale entry, which costs the next
+     * seed of that number one row read and is removed by the next release that
+     * answers `not-claimed` — so it is logged, never thrown, and the removal
+     * proceeds.
+     */
+    pruneDevice(deviceId: number, settings: DeviceManagerSettings): Promise<void>;
+    /**
+     * Read-modify-write of the whole blob under the addon-store lock, from the
+     * LOADED entries: the index is never written from a partial picture. `next`
+     * returning null means nothing to write.
+     */
+    private mutate;
+    private install;
+    /** The three-way read (D651): a failed read is a REASON, never an empty index. */
+    private readBlob;
+    /** Not loaded, by name: the index stays unknown and says why. */
+    private refuseMalformed;
+}

package/dist/builtins/device-manager/field-ownership.d.ts

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+import { FieldClaimMode } from '@camstack/types';
+import { RuntimeStatePolicyLookup } from './runtime-state-persist-gate.js';
+/** The row key under which claims travel. Not a cap name: `$` is not legal in one. */
+export declare const OWNED_FIELDS_KEY = "$owned";
+/**
+ * One claimed cap. `fields` is the claimed set, `values` what has been written
+ * so far — a claimed field with no value is HELD (ruling S5), never answered
+ * from the native slice.
+ */
+export interface OwnedCap {
+    readonly owner: string;
+    readonly mode: FieldClaimMode;
+    readonly fields: readonly string[];
+    readonly values: Readonly<Record<string, unknown>>;
+}
+export type OwnedCaps = ReadonlyMap<string, OwnedCap>;
+export interface SplitBlob {
+    readonly native: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+    readonly owned: OwnedCaps;
+    /** `$owned` entries that failed `OwnedCapSchema`, by cap name — logged once per device, never applied. */
+    readonly dropped: readonly string[];
+}
+export type MergedSlice = {
+    readonly kind: 'slice';
+    readonly slice: Readonly<Record<string, unknown>>;
+} | {
+    readonly kind: 'held';
+    readonly reason: string;
+};
+export declare function isPlainRecord(value: unknown): value is Readonly<Record<string, unknown>>;
+/**
+ * Split a runtime-state row into its native slices and its claims. A row with
+ * no `$owned` splits to its slices and an empty map — the shape every device
+ * without a claim has always had. Non-object entries are dropped, as the
+ * mirror seed and `DeviceRuntimeState.fromInitial` have always dropped them.
+ */
+export declare function splitRuntimeBlob(blob: Readonly<Record<string, unknown>>): SplitBlob;
+/**
+ * Join native slices and claims into one row. `values` are kept only for caps
+ * whose policy is `durability: 'restored'`; a session-only cap keeps its CLAIM
+ * (so a restart still knows who owns what) but not its values, and the claimed
+ * fields are held after boot until the owner writes again. A device with no
+ * claims gets no `$owned` key at all — its row is byte-identical to before.
+ */
+export declare function joinRuntimeBlob(native: SplitBlob['native'], owned: OwnedCaps, policyFor: RuntimeStatePolicyLookup): Record<string, Record<string, unknown>>;
+/**
+ * The one merge. Held when a claimed field has no value yet (S5: never
+ * answered from the native), when a `replace` has no native slice to overlay
+ * (a partial slice is never emitted), or when the merged slice fails the cap's
+ * `runtimeState` schema (the native value never leaks through a bad overlay).
+ */
+export declare function mergeOwned(native: Readonly<Record<string, unknown>> | null, owned: OwnedCap, schema: z.ZodType | null): MergedSlice;

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

@@ -28,6 +28,13 @@ export interface MigrateDeviceResult {
     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.
+ */
+export type SwitchStates = ReadonlyMap<CameraSwitchId, boolean>;
+/** Severity of a per-device migration line. */
+export type MigrationLogLevel = 'warn' | 'error';
 export interface MigrateDeviceDeps {
     /** `pipelineOrchestrator.setCameraSwitch`, through `ctx.api`. */
     readonly setSwitch: (deviceId: number, switchId: CameraSwitchId, enabled: boolean) => Promise<void>;
@@ -46,6 +53,15 @@ export interface MigrateDeviceDeps {
      * 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
@@ -67,6 +83,17 @@ export interface MigrateDeviceDeps {
      */
     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

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

@@ -26,6 +26,13 @@ export interface MigrationGuard {
     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;
     /**