@camstack/system 1.2.313 → 1.2.315

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

@@ -1,5 +1,6 @@
-import { Bn as WELL_KNOWN_TAB_MAP, C as MINUTES_PER_DAY, Fn as DeviceFeature, Ht as locationIconKey, In as DeviceRole, Ln as DeviceType, Ot as formatMinutes, Rt as legacyAutoLinkIds, Yn as isDeviceConfigCap, Zt as normalizeUnit, _ as DeviceStatusSchema, bt as enumerateSchemaFields, dt as defineExtensionSlotProvider, en as parseStreamParamsFormPatch, gt as deviceStatusCapability, ht as deviceStateCapability, ir as EventCategory, j as STREAM_PROFILE_META, jn as BaseAddon, kn as errMsg, ln as runtimeStatePolicyFor, mn as siteZoneKey, mt as deviceManagerCapability, o as CAMERA_SWITCH_ORDER, p as DAY_NAMES, pt as deviceExtensionCapability, q as buildStreamParamsConfigSchema, rr as sleep$1, s as CAP_NAMES_WITH_STATUS, st as createDeviceExtensionProvider, t as ALL_CAPABILITY_DEFINITIONS, wt as expandContainer, x as LocationIconIdSchema, yt as enumerateItemArrayFields } from "../../dist-Cj7pJmXq.mjs";
-import { n as purgeRetiredSettingsRows } from "../../retired-settings-keys-C1duPikd.mjs";
+import { Gn as BaseAddon, Hn as DeviceRole, Kt as normalizeUnit, Lt as locationIconKey, Nt as legacyAutoLinkIds, S as LocationIconIdSchema, Un as DeviceType, Vn as DeviceFeature, Wn as errMsg, Yt as parseStreamParamsFormPatch, Zn as WELL_KNOWN_TAB_MAP, _t as enumerateSchemaFields, an as runtimeStatePolicyFor, bt as expandContainer, ct as defineExtensionSlotProvider, dt as deviceManagerCapability, ft as deviceStateCapability, g as DeviceStatusSchema, gt as enumerateItemArrayFields, hr as EventCategory, it as createDeviceExtensionProvider, j as STREAM_PROFILE_META, mr as sleep$1, o as CAMERA_SWITCH_ORDER, or as isDeviceConfigCap, p as DAY_NAMES, pt as deviceStatusCapability, q as buildStreamParamsConfigSchema, s as CAP_NAMES_WITH_STATUS, t as ALL_CAPABILITY_DEFINITIONS, un as siteZoneKey, ut as deviceExtensionCapability, v as FieldClaimModeSchema, w as MINUTES_PER_DAY, wt as formatMinutes, y as FieldClaimSchema } from "../../dist-MzYJVCLE.mjs";
+import { n as purgeRetiredSettingsRows } from "../../retired-settings-keys-8yY2sTc-.mjs";
+import { z } from "zod";
 import { randomUUID } from "node:crypto";
 import { canonicalDeviceFingerprint } from "@camstack/types/node";
 //#region src/builtins/device-manager/adoption-job-engine.ts
@@ -292,6 +293,487 @@ var AdoptionJobEngine = class {
 	}
 };
 //#endregion
+//#region src/builtins/device-manager/device-projection.ts
+/**
+* Return true when `err` is a transient Moleculer error that is worth
+* retrying — specifically any `MoleculerRetryableError` subclass
+* (ServiceNotAvailableError, ServiceNotFoundError, BrokerDisconnectedError,
+* RequestTimeoutError, …). Moleculer sets `retryable: true` on all of them.
+*
+* Falls back to a message-substring check for serialised errors that arrive
+* across the Moleculer transport as plain objects rather than real instances.
+*/
+function isTransientMoleculerError(err) {
+	if (err !== null && typeof err === "object") {
+		const e = err;
+		if (e["retryable"] === true) return true;
+		const code = typeof e["code"] === "string" ? e["code"] : "";
+		if (code === "SERVICE_NOT_FOUND" || code === "SERVICE_NOT_AVAILABLE" || code === "REQUEST_TIMEOUT" || code === "BAD_GATEWAY") return true;
+	}
+	if (err instanceof Error) {
+		const msg = err.message;
+		if (msg.includes("is not available") || msg.includes("is not found") || msg.includes("transporter has disconnected") || msg.includes("Request timed out")) return true;
+	}
+	return false;
+}
+function shallowEqual(a, b) {
+	const ak = Object.keys(a);
+	const bk = Object.keys(b);
+	if (ak.length !== bk.length) return false;
+	for (const k of ak) if (a[k] !== b[k]) return false;
+	return true;
+}
+function isCameraDevice(device) {
+	return "getStreamSources" in device && typeof device.getStreamSources === "function";
+}
+var DEVICE_FEATURE_VALUES = new Set(Object.values(DeviceFeature));
+/**
+* Validate persisted feature strings against the `DeviceFeature` enum
+* — workers serialise the live `device.features` array (so every entry
+* is a valid enum value at write time) but the persisted blob is loose
+* `string[]` on the wire. The narrow keeps unknown values out of the
+* `getDevice` response without losing the enum-typed contract.
+*/
+function persistedFeatures(features) {
+	if (!features) return [];
+	const out = [];
+	for (const f of features) if (DEVICE_FEATURE_VALUES.has(f)) out.push(f);
+	return out;
+}
+/**
+* Infer `isCamera` from a persisted DeviceType.
+*
+* Live projection uses method presence (`getStreamSources` via
+* `isCameraDevice`). Forked-worker devices have no `IDevice` on the hub, so
+* the persisted fallbacks in `listAll` / `getDevice` / `getChildren` share
+* this one inference — they must not drift (the 4263 Campanello contradiction
+* of 2026-08-31: `listAll` said camera, `getDevice` said not).
+*/
+function persistedIsCamera(type) {
+	return type === DeviceType.Camera;
+}
+/**
+* Build an identity-only `SourceInfo` from the persisted device config blob.
+*
+* Forked-worker accessory children (e.g. HA sensor entities) persist
+* `entityId` and `system` in their config blob at spawn time. The hub has no
+* live `IDevice` instance for these devices, so the persisted-fallback paths
+* in `listAll` / `getDevice` / `getChildren` must reconstruct the identity
+* `SourceInfo` from the config so dispatch routing keeps working.
+*
+* Rendering metadata (unit, precision) flows live through the cap STATUS SLICE
+* and must NOT be derived here. Only `id` + `system` (+ `uniqueId` when
+* present) are projected — purely identity, never rendering hints.
+*
+* Returns `undefined` when no identity anchor is resolvable (pure identity
+* devices like cameras/hubs that don't carry `entityId`/`system` in their
+* config blob) — the hub synthetic fallback applies in that case.
+*/
+function buildSourceInfoFromConfig(persistedConfig, stableId, addonId) {
+	const id = typeof persistedConfig["entityId"] === "string" ? persistedConfig["entityId"] : void 0;
+	const system = typeof persistedConfig["system"] === "string" ? persistedConfig["system"] : void 0;
+	if (id === void 0 && system === void 0) return void 0;
+	const uniqueId = typeof persistedConfig["uniqueId"] === "string" ? persistedConfig["uniqueId"] : void 0;
+	return {
+		id: id ?? stableId,
+		system: system ?? addonId,
+		...uniqueId !== void 0 ? { uniqueId } : {}
+	};
+}
+var DEVICE_ROLE_VALUES = new Set(Object.values(DeviceRole));
+/** Type guard: a string is a known `DeviceRole` enum member. */
+function isDeviceRole(value) {
+	return DEVICE_ROLE_VALUES.has(value);
+}
+/** Narrow a persisted role string (sqlite TEXT column) to a `DeviceRole`.
+*  Unknown / null values resolve to `null` so a stale or unrecognised role
+*  never leaks an off-enum string onto the wire shape. */
+function toDeviceRole(value) {
+	return value != null && isDeviceRole(value) ? value : null;
+}
+function toDeviceInfo(addonId, device, metadata = null, metaRow = null) {
+	const configValues = {};
+	for (const entry of device.config.entries()) configValues[entry.key] = entry.value;
+	const name = metaRow?.name ?? device.name;
+	const location = metaRow?.location !== void 0 ? metaRow.location : device.location;
+	const disabled = metaRow?.disabled ?? device.disabled;
+	const probeSlice = device.runtimeState?.getCapState("feature-probe");
+	const probed = probeSlice === void 0 ? true : (probeSlice.lastProbedAt ?? 0) > 0;
+	return {
+		id: device.id,
+		stableId: device.stableId,
+		addonId,
+		type: device.type,
+		name,
+		location,
+		disabled,
+		parentDeviceId: device.parentDeviceId,
+		role: device.role ?? null,
+		online: device.online,
+		probed,
+		features: device.features.length > 0 ? [...device.features] : persistedFeatures(metaRow?.features),
+		isCamera: isCameraDevice(device),
+		config: configValues,
+		metadata,
+		...metaRow?.integrationId !== void 0 ? { integrationId: metaRow.integrationId } : {},
+		...metaRow?.linkDeviceId !== void 0 ? { linkDeviceId: metaRow.linkDeviceId } : {},
+		...metaRow?.primaryChildEntityId !== void 0 ? { primaryChildEntityId: metaRow.primaryChildEntityId } : {},
+		...metaRow?.childLayout !== void 0 ? { childLayout: metaRow.childLayout } : {},
+		...metaRow?.display !== void 0 ? { display: metaRow.display } : {}
+	};
+}
+function resolveDeviceById(registry, deviceId) {
+	const device = registry.getById(deviceId);
+	if (!device) return null;
+	const addonId = registry.getAddonId(deviceId);
+	if (!addonId) return null;
+	return {
+		addonId,
+		device
+	};
+}
+//#endregion
+//#region src/builtins/device-manager/field-ownership.ts
+/**
+* Per-field ownership of a runtime-state slice (D663) — the pure half.
+*
+* A composition may claim fields of a cap on an existing device. The native
+* provider keeps writing its slice (it never learns of the claim — D62: one
+* authority per field, and the authority for a claimed field is the owner),
+* the hub keeps that slice as a SHADOW, and what consumers read and receive is
+* the MERGE: the native slice with the owned fields replaced. The shadow is
+* readable only by the owner-side mechanism (D224), never served as a second
+* truth.
+*
+* Both halves live in the device's own runtime-state row: the native slices
+* under their cap names, the claims under `$owned`. One row, one write, so a
+* claim and the slice it governs can never disagree on disk.
+*
+* This module has no mirror, no settings store and no logger: it merges and
+* it (de)serialises. `DeviceStateMirror` owns the state and the log lines.
+*/
+/** The row key under which claims travel. Not a cap name: `$` is not legal in one. */
+var OWNED_FIELDS_KEY = "$owned";
+var OwnedCapSchema = z.object({
+	owner: z.string().min(1),
+	mode: FieldClaimModeSchema,
+	fields: z.array(z.string().min(1)).min(1),
+	values: z.record(z.string(), z.unknown())
+});
+function isPlainRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* 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.
+*/
+function splitRuntimeBlob(blob) {
+	const native = {};
+	const owned = /* @__PURE__ */ new Map();
+	const dropped = [];
+	for (const [key, raw] of Object.entries(blob)) {
+		if (key === "$owned") continue;
+		if (!isPlainRecord(raw)) continue;
+		native[key] = { ...raw };
+	}
+	const rawOwned = blob[OWNED_FIELDS_KEY];
+	if (isPlainRecord(rawOwned)) for (const [capName, entry] of Object.entries(rawOwned)) {
+		const parsed = OwnedCapSchema.safeParse(entry);
+		if (parsed.success) owned.set(capName, parsed.data);
+		else dropped.push(capName);
+	}
+	return {
+		native,
+		owned,
+		dropped
+	};
+}
+/**
+* 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.
+*/
+function joinRuntimeBlob(native, owned, policyFor) {
+	const out = {};
+	for (const [capName, slice] of Object.entries(native)) out[capName] = { ...slice };
+	if (owned.size === 0) return out;
+	const claims = {};
+	for (const [capName, cap] of owned) {
+		const restored = policyFor(capName).durability === "restored";
+		claims[capName] = {
+			owner: cap.owner,
+			mode: cap.mode,
+			fields: [...cap.fields],
+			values: restored ? { ...cap.values } : {}
+		};
+	}
+	out[OWNED_FIELDS_KEY] = claims;
+	return out;
+}
+/**
+* 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).
+*/
+function mergeOwned(native, owned, schema) {
+	const missing = owned.fields.filter((f) => !Object.hasOwn(owned.values, f));
+	if (missing.length > 0) return {
+		kind: "held",
+		reason: `claimed fields with no value yet: ${missing.join(", ")}`
+	};
+	if (owned.mode === "replace" && native === null) return {
+		kind: "held",
+		reason: "no native slice yet"
+	};
+	const merged = {
+		...native,
+		...owned.values
+	};
+	if (schema === null) return {
+		kind: "slice",
+		slice: merged
+	};
+	const parsed = schema.safeParse(merged);
+	if (parsed.success) return {
+		kind: "slice",
+		slice: parsed.data
+	};
+	return {
+		kind: "held",
+		reason: `merged slice fails the schema at ${parsed.error.issues.map((i) => i.path.join(".")).join(", ")}`
+	};
+}
+//#endregion
+//#region src/builtins/device-manager/device-state-claim-views.ts
+var defaultSchemaTable = null;
+/** Lazily indexes the codegen'd cap set — the hub already carries the barrel. */
+function defaultSchemaFor(capName) {
+	if (defaultSchemaTable === null) {
+		defaultSchemaTable = /* @__PURE__ */ new Map();
+		for (const def of ALL_CAPABILITY_DEFINITIONS) if (def.runtimeState) defaultSchemaTable.set(def.name, def.runtimeState);
+	}
+	return defaultSchemaTable.get(capName) ?? null;
+}
+function sameStringList(a, b) {
+	return a.length === b.length && a.every((v, i) => v === b[i]);
+}
+function sameOwnedCap(a, b) {
+	return a.owner === b.owner && a.mode === b.mode && sameStringList(a.fields, b.fields) && shallowEqual({ ...a.values }, { ...b.values });
+}
+function refused(code, message) {
+	return {
+		ok: false,
+		code,
+		message
+	};
+}
+var ClaimViews = class {
+	sink;
+	/** Claims by device, by cap. Absent for every device without one. */
+	owned = /* @__PURE__ */ new Map();
+	/** The merged view of each claimed cap; recomputed on every native or owned write. */
+	views = /* @__PURE__ */ new Map();
+	constructor(sink) {
+		this.sink = sink;
+	}
+	claim(deviceId, capName) {
+		return this.owned.get(deviceId)?.get(capName);
+	}
+	setClaim(deviceId, capName, claim) {
+		this.ownedFor(deviceId).set(capName, claim);
+	}
+	/** Removes the claim AND its view. */
+	deleteClaim(deviceId, capName) {
+		this.owned.get(deviceId)?.delete(capName);
+		this.views.get(deviceId)?.delete(capName);
+	}
+	/** Fill gaps only: a claim already in memory was written through and is newer than the row. */
+	seedClaims(deviceId, claims) {
+		if (claims.size === 0) return;
+		const mine = this.ownedFor(deviceId);
+		for (const [capName, cap] of claims) if (!mine.has(capName)) mine.set(capName, cap);
+	}
+	clearDevice(deviceId) {
+		this.owned.delete(deviceId);
+		this.views.delete(deviceId);
+	}
+	ownedCaps(deviceId) {
+		return new Map(this.owned.get(deviceId) ?? []);
+	}
+	claimsOf(deviceId) {
+		return this.owned.get(deviceId) ?? [];
+	}
+	/** Devices with at least one view — for the whole-system dump. */
+	deviceIds() {
+		return this.views.keys();
+	}
+	isClaimed(deviceId, capName) {
+		return this.views.get(deviceId)?.has(capName) ?? false;
+	}
+	/** `undefined` when the cap is not claimed; `null` when it is claimed and held with nothing to show. */
+	visible(deviceId, capName) {
+		const view = this.views.get(deviceId)?.get(capName);
+		return view === void 0 ? void 0 : view.visible;
+	}
+	/** Every claimed cap of a device that currently has something to show. */
+	*visibleCaps(deviceId) {
+		for (const [capName, view] of this.views.get(deviceId) ?? []) if (view.visible) yield [capName, view.visible];
+	}
+	/** What the merge says for a claimed cap; null when the cap is not claimed. */
+	effective(deviceId, capName) {
+		const view = this.views.get(deviceId)?.get(capName);
+		if (!view) return null;
+		return view.merged.kind === "slice" ? {
+			kind: "slice",
+			slice: { ...view.merged.slice }
+		} : {
+			kind: "held",
+			reason: view.merged.reason
+		};
+	}
+	view(deviceId, capName) {
+		return this.views.get(deviceId)?.get(capName);
+	}
+	/** Put a view back (rollback of a failed write-through); `undefined` removes it. */
+	restoreView(deviceId, capName, view) {
+		if (view) this.viewsFor(deviceId).set(capName, view);
+		else this.views.get(deviceId)?.delete(capName);
+	}
+	/**
+	* 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, capName, claim, native, emitUnchanged) {
+		const views = this.viewsFor(deviceId);
+		const prior = views.get(capName);
+		const { view, badOverlay } = this.derive(prior, capName, claim, native);
+		views.set(capName, view);
+		const merged = view.merged;
+		if (merged.kind === "slice") {
+			if (!prior?.visible || !shallowEqual({ ...prior.visible }, { ...merged.slice }) || emitUnchanged) this.sink.emitSlice(deviceId, capName, { ...merged.slice });
+			return;
+		}
+		if (prior?.merged.kind === "held" && prior.merged.reason === merged.reason) return;
+		const extras = {
+			tags: { deviceId },
+			meta: {
+				cap: capName,
+				owner: claim.owner,
+				reason: merged.reason
+			}
+		};
+		if (badOverlay) this.sink.logger.warn("claimed cap held — nothing emitted for it", extras);
+		else this.sink.logger.debug("claimed cap held — nothing emitted for it", extras);
+	}
+	/**
+	* 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, capName, claim, native) {
+		const views = this.viewsFor(deviceId);
+		views.set(capName, this.derive(views.get(capName), capName, claim, native).view);
+	}
+	/** 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. */
+	derive(prior, capName, claim, native) {
+		const merged = mergeOwned(native, claim, this.sink.schemaFor(capName));
+		if (merged.kind === "slice") return {
+			view: {
+				merged,
+				visible: merged.slice
+			},
+			badOverlay: false
+		};
+		const badOverlay = claim.fields.every((f) => Object.hasOwn(claim.values, f)) && (native !== null || claim.mode === "add");
+		return {
+			view: {
+				merged,
+				visible: badOverlay ? prior?.visible ?? null : null
+			},
+			badOverlay
+		};
+	}
+	/** The merged view for a claim that arrived by seed: computed, never emitted. */
+	seedView(deviceId, capName, claim, native) {
+		const views = this.viewsFor(deviceId);
+		if (views.has(capName)) return;
+		const merged = mergeOwned(native, claim, this.sink.schemaFor(capName));
+		views.set(capName, {
+			merged,
+			visible: merged.kind === "slice" ? merged.slice : null
+		});
+	}
+	ownedFor(deviceId) {
+		let perCap = this.owned.get(deviceId);
+		if (!perCap) {
+			perCap = /* @__PURE__ */ new Map();
+			this.owned.set(deviceId, perCap);
+		}
+		return perCap;
+	}
+	viewsFor(deviceId) {
+		let views = this.views.get(deviceId);
+		if (!views) {
+			views = /* @__PURE__ */ new Map();
+			this.views.set(deviceId, views);
+		}
+		return views;
+	}
+};
+//#endregion
+//#region src/builtins/device-manager/claimed-status-overlay.ts
+var UNCLAIMED = { kind: "unclaimed" };
+var UNKNOWN = { kind: "unknown" };
+function fromMerge(mirror, deviceId, capName) {
+	const merged = mirror.effectiveIfClaimed(deviceId, capName);
+	if (merged === null) return UNCLAIMED;
+	return {
+		kind: "claimed",
+		slice: merged.kind === "slice" ? merged.slice : null
+	};
+}
+function installClaimedStatusOverlay(registry, deps) {
+	const { mirror } = deps;
+	let rowResolutionNoted = false;
+	const noteRowResolution = (deviceId) => {
+		if (rowResolutionNoted || deps.claimsIndex().state === "loaded") return;
+		rowResolutionNoted = true;
+		deps.logger.info("claims index not loaded: unseeded devices resolve their claims from the row on first getStatus (single-flight per device)", { tags: { deviceId } });
+	};
+	registry.setStatusOverlay({
+		peek(capName, deviceId) {
+			if (defaultSchemaFor(capName) === null) return UNCLAIMED;
+			if (mirror.isSeeded(deviceId)) return fromMerge(mirror, deviceId, capName);
+			if (mirror.seedIfIndexClears(deviceId, deps.claimsIndex())) return UNCLAIMED;
+			return UNKNOWN;
+		},
+		async resolve(capName, deviceId) {
+			if (defaultSchemaFor(capName) === null) return UNCLAIMED;
+			if (!mirror.isSeeded(deviceId)) {
+				noteRowResolution(deviceId);
+				try {
+					await mirror.ensureSeeded(deviceId, deps.settings(), deps.claimsIndex());
+				} catch {
+					return UNKNOWN;
+				}
+			}
+			return fromMerge(mirror, deviceId, capName);
+		}
+	});
+	return () => registry.setStatusOverlay(null);
+}
+//#endregion
 //#region src/builtins/device-manager/contribution-cache.ts
 /**
 * The device-details fan-out, made survivable: budgeted, cached, single-flight.
@@ -565,6 +1047,18 @@ function wireRemoteNativeCapSync(ctx, remoteNativeCaps) {
 				perDevice = /* @__PURE__ */ new Map();
 				remoteNativeCaps.set(deviceId, perDevice);
 			}
+			const existing = perDevice.get(capName);
+			if (addonId === "composer" && existing !== void 0 && existing.addonId !== "composer") {
+				ctx.logger.warn("a graft did not replace a native binding — native always wins", {
+					tags: { deviceId },
+					meta: {
+						capName,
+						native: existing.addonId,
+						nodeId
+					}
+				});
+				return;
+			}
 			perDevice.set(capName, {
 				addonId,
 				nodeId
@@ -572,6 +1066,7 @@ function wireRemoteNativeCapSync(ctx, remoteNativeCaps) {
 		} else if (reason === "native-unregistered") {
 			const perDevice = remoteNativeCaps.get(deviceId);
 			if (!perDevice) return;
+			if (perDevice.get(capName)?.addonId !== addonId) return;
 			perDevice.delete(capName);
 			if (perDevice.size === 0) remoteNativeCaps.delete(deviceId);
 		}
@@ -1856,155 +2351,15 @@ function parseDerivedFormSettingsPatch(builderId, patch) {
 	return reducer.parsePatch(patch);
 }
 //#endregion
-//#region src/builtins/device-manager/device-projection.ts
+//#region src/builtins/device-manager/device-online-fallback.ts
 /**
-* Return true when `err` is a transient Moleculer error that is worth
-* retrying — specifically any `MoleculerRetryableError` subclass
-* (ServiceNotAvailableError, ServiceNotFoundError, BrokerDisconnectedError,
-* RequestTimeoutError, …). Moleculer sets `retryable: true` on all of them.
-*
-* Falls back to a message-substring check for serialised errors that arrive
-* across the Moleculer transport as plain objects rather than real instances.
+* The value to hand `resolveDeviceOnline` as its fallback. The mirrored
+* `device-status` slice, when one exists, still wins over this.
 */
-function isTransientMoleculerError(err) {
-	if (err !== null && typeof err === "object") {
-		const e = err;
-		if (e["retryable"] === true) return true;
-		const code = typeof e["code"] === "string" ? e["code"] : "";
-		if (code === "SERVICE_NOT_FOUND" || code === "SERVICE_NOT_AVAILABLE" || code === "REQUEST_TIMEOUT" || code === "BAD_GATEWAY") return true;
-	}
-	if (err instanceof Error) {
-		const msg = err.message;
-		if (msg.includes("is not available") || msg.includes("is not found") || msg.includes("transporter has disconnected") || msg.includes("Request timed out")) return true;
-	}
-	return false;
-}
-function shallowEqual(a, b) {
-	const ak = Object.keys(a);
-	const bk = Object.keys(b);
-	if (ak.length !== bk.length) return false;
-	for (const k of ak) if (a[k] !== b[k]) return false;
-	return true;
-}
-function isCameraDevice(device) {
-	return "getStreamSources" in device && typeof device.getStreamSources === "function";
-}
-var DEVICE_FEATURE_VALUES = new Set(Object.values(DeviceFeature));
-/**
-* Validate persisted feature strings against the `DeviceFeature` enum
-* — workers serialise the live `device.features` array (so every entry
-* is a valid enum value at write time) but the persisted blob is loose
-* `string[]` on the wire. The narrow keeps unknown values out of the
-* `getDevice` response without losing the enum-typed contract.
-*/
-function persistedFeatures(features) {
-	if (!features) return [];
-	const out = [];
-	for (const f of features) if (DEVICE_FEATURE_VALUES.has(f)) out.push(f);
-	return out;
-}
-/**
-* Infer `isCamera` from a persisted DeviceType.
-*
-* Live projection uses method presence (`getStreamSources` via
-* `isCameraDevice`). Forked-worker devices have no `IDevice` on the hub, so
-* the persisted fallbacks in `listAll` / `getDevice` / `getChildren` share
-* this one inference — they must not drift (the 4263 Campanello contradiction
-* of 2026-08-31: `listAll` said camera, `getDevice` said not).
-*/
-function persistedIsCamera(type) {
-	return type === DeviceType.Camera;
-}
-/**
-* Build an identity-only `SourceInfo` from the persisted device config blob.
-*
-* Forked-worker accessory children (e.g. HA sensor entities) persist
-* `entityId` and `system` in their config blob at spawn time. The hub has no
-* live `IDevice` instance for these devices, so the persisted-fallback paths
-* in `listAll` / `getDevice` / `getChildren` must reconstruct the identity
-* `SourceInfo` from the config so dispatch routing keeps working.
-*
-* Rendering metadata (unit, precision) flows live through the cap STATUS SLICE
-* and must NOT be derived here. Only `id` + `system` (+ `uniqueId` when
-* present) are projected — purely identity, never rendering hints.
-*
-* Returns `undefined` when no identity anchor is resolvable (pure identity
-* devices like cameras/hubs that don't carry `entityId`/`system` in their
-* config blob) — the hub synthetic fallback applies in that case.
-*/
-function buildSourceInfoFromConfig(persistedConfig, stableId, addonId) {
-	const id = typeof persistedConfig["entityId"] === "string" ? persistedConfig["entityId"] : void 0;
-	const system = typeof persistedConfig["system"] === "string" ? persistedConfig["system"] : void 0;
-	if (id === void 0 && system === void 0) return void 0;
-	const uniqueId = typeof persistedConfig["uniqueId"] === "string" ? persistedConfig["uniqueId"] : void 0;
-	return {
-		id: id ?? stableId,
-		system: system ?? addonId,
-		...uniqueId !== void 0 ? { uniqueId } : {}
-	};
-}
-var DEVICE_ROLE_VALUES = new Set(Object.values(DeviceRole));
-/** Type guard: a string is a known `DeviceRole` enum member. */
-function isDeviceRole(value) {
-	return DEVICE_ROLE_VALUES.has(value);
-}
-/** Narrow a persisted role string (sqlite TEXT column) to a `DeviceRole`.
-*  Unknown / null values resolve to `null` so a stale or unrecognised role
-*  never leaks an off-enum string onto the wire shape. */
-function toDeviceRole(value) {
-	return value != null && isDeviceRole(value) ? value : null;
-}
-function toDeviceInfo(addonId, device, metadata = null, metaRow = null) {
-	const configValues = {};
-	for (const entry of device.config.entries()) configValues[entry.key] = entry.value;
-	const name = metaRow?.name ?? device.name;
-	const location = metaRow?.location !== void 0 ? metaRow.location : device.location;
-	const disabled = metaRow?.disabled ?? device.disabled;
-	const probeSlice = device.runtimeState?.getCapState("feature-probe");
-	const probed = probeSlice === void 0 ? true : (probeSlice.lastProbedAt ?? 0) > 0;
-	return {
-		id: device.id,
-		stableId: device.stableId,
-		addonId,
-		type: device.type,
-		name,
-		location,
-		disabled,
-		parentDeviceId: device.parentDeviceId,
-		role: device.role ?? null,
-		online: device.online,
-		probed,
-		features: device.features.length > 0 ? [...device.features] : persistedFeatures(metaRow?.features),
-		isCamera: isCameraDevice(device),
-		config: configValues,
-		metadata,
-		...metaRow?.integrationId !== void 0 ? { integrationId: metaRow.integrationId } : {},
-		...metaRow?.linkDeviceId !== void 0 ? { linkDeviceId: metaRow.linkDeviceId } : {},
-		...metaRow?.primaryChildEntityId !== void 0 ? { primaryChildEntityId: metaRow.primaryChildEntityId } : {},
-		...metaRow?.childLayout !== void 0 ? { childLayout: metaRow.childLayout } : {},
-		...metaRow?.display !== void 0 ? { display: metaRow.display } : {}
-	};
-}
-function resolveDeviceById(registry, deviceId) {
-	const device = registry.getById(deviceId);
-	if (!device) return null;
-	const addonId = registry.getAddonId(deviceId);
-	if (!addonId) return null;
-	return {
-		addonId,
-		device
-	};
-}
-//#endregion
-//#region src/builtins/device-manager/device-online-fallback.ts
-/**
-* The value to hand `resolveDeviceOnline` as its fallback. The mirrored
-* `device-status` slice, when one exists, still wins over this.
-*/
-function persistedOnlineFallback(input) {
-	if (!input.registryPresent) return false;
-	if (input.parentDeviceId !== null) return true;
-	return Object.keys(input.config ?? {}).length > 0;
+function persistedOnlineFallback(input) {
+	if (!input.registryPresent) return false;
+	if (input.parentDeviceId !== null) return true;
+	return Object.keys(input.config ?? {}).length > 0;
 }
 //#endregion
 //#region src/builtins/device-manager/device-queries.ts
@@ -4046,7 +4401,6 @@ function createDeviceManagerExtensionProvider(pctx) {
 				const implied = await impliedLinks(pctx, deviceId, manualIds, pickedRows);
 				return {
 					authority: LINKED_DEVICES_AUTHORITY,
-					enabled: null,
 					activation: null,
 					value: {
 						slot: "linked-devices",
@@ -4110,6 +4464,34 @@ function createDeviceManagerExtensionProvider(pctx) {
 		logger: pctx.host.ctx.logger
 	});
 }
+//#endregion
+//#region src/builtins/device-manager/migration-refused.ts
+/**
+* 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.
+*/
+var MigrationRefusedError = class extends Error {
+	constructor(message, options) {
+		super(message, options);
+		this.name = "MigrationRefusedError";
+	}
+};
 /** A refusal that names a switch the camera does not offer, rather than one it
 *  could not be asked about. The cap documents rejecting the former; anything
 *  else is treated as the camera being out of reach, which is the safe reading:
@@ -4129,19 +4511,98 @@ function classify(err) {
 */
 async function setSwitchBounded(deps, deviceId, switchId, enabled) {
 	const budget = deps.switchTimeoutMs ?? 15e3;
-	const write = deps.setSwitch(deviceId, switchId, enabled);
-	write.catch(() => {});
+	await withinBudget(deps.setSwitch(deviceId, switchId, enabled), budget, `switch write did not answer within ${budget}ms — reported unreachable; if it lands late, a duplicate write of the same value is a no-op`);
+}
+/** A bounded call: the race fails at `budget`, the late loser is marked handled. */
+async function withinBudget(call, budget, timeoutMessage) {
+	call.catch(() => {});
 	let timer;
 	try {
-		await Promise.race([write, new Promise((_resolve, reject) => {
+		return await Promise.race([call, new Promise((_resolve, reject) => {
 			timer = setTimeout(() => {
-				reject(/* @__PURE__ */ new Error(`switch write did not answer within ${budget}ms — reported unreachable; if it lands late, a duplicate write of the same value is a no-op`));
+				reject(new Error(timeoutMessage));
 			}, budget);
 		})]);
 	} finally {
 		if (timer !== void 0) clearTimeout(timer);
 	}
 }
+/** The prior switch states, or `null` when they could not be read (reported). */
+async function readPriorSwitches(deps, deviceId) {
+	const budget = deps.switchTimeoutMs ?? 15e3;
+	try {
+		return await withinBudget(deps.readSwitches(deviceId), budget, `switch-state read did not answer within ${budget}ms`);
+	} catch (err) {
+		deps.logDevice("warn", deviceId, "migration: prior switch states unreadable", {
+			error: err instanceof Error ? err.message : String(err),
+			consequence: "a refusal before the swap would switch this camera fully back on"
+		});
+		return null;
+	}
+}
+/**
+* Put one camera's switches back to what they were before the disable phase.
+* A switch that was off stays off (it still is); one that was on is written
+* on; unknown priors fall back to on — a refusal must not leave a camera dark.
+*/
+async function restoreSwitches(deps, deviceId, prior) {
+	const out = [];
+	for (const switchId of CAMERA_SWITCH_ORDER) {
+		if (prior !== null && !prior.has(switchId)) continue;
+		if (prior !== null && prior.get(switchId) === false) {
+			out.push({
+				deviceId,
+				switchId,
+				outcome: "off"
+			});
+			continue;
+		}
+		try {
+			await setSwitchBounded(deps, deviceId, switchId, true);
+			out.push({
+				deviceId,
+				switchId,
+				outcome: "on"
+			});
+		} catch (err) {
+			out.push({
+				deviceId,
+				switchId,
+				...classify(err)
+			});
+		}
+	}
+	return out;
+}
+/** A refusal before any row moved: both cameras back as they were, then rethrow. */
+async function rollBackRefusal(deps, ids, prior, err) {
+	for (const deviceId of [ids.sourceId, ids.targetId]) {
+		const restored = await restoreSwitches(deps, deviceId, prior.get(deviceId) ?? null);
+		deps.logDevice("warn", deviceId, "migration refused before any row moved — switches restored to their prior state", {
+			...ids,
+			error: err.message,
+			priorKnown: (prior.get(deviceId) ?? null) !== null,
+			restored,
+			stillOff: restored.filter((r) => r.outcome !== "on").map((r) => r.switchId)
+		});
+	}
+	throw err;
+}
+/**
+* A failure once rows may have moved. The two devices may wear each other's
+* identity, so nothing is switched back on: both stay off and each device gets
+* an ERROR line saying what moved and that an operator must intervene (D391).
+*/
+function alarmPartialMigration(deps, ids, phase, err) {
+	const moved = phase === "swapIds" ? "device rows may be PARTIALLY swapped — look for a device at an unfamiliar id" : "device rows swapped; driver config / runtime state swap incomplete — the two devices may wear each other's identity";
+	for (const deviceId of [ids.sourceId, ids.targetId]) deps.logDevice("error", deviceId, "migration FAILED after rows began to move — both cameras left switched off; operator must intervene", {
+		...ids,
+		phase,
+		moved,
+		error: err instanceof Error ? err.message : String(err),
+		remedy: "inspect both devices (rows, driver config, runtime state) and repair by hand before switching them back on"
+	});
+}
 async function applyAll(deps, deviceId, enabled) {
 	const out = [];
 	for (const switchId of CAMERA_SWITCH_ORDER) try {
@@ -4179,10 +4640,27 @@ async function applyAll(deps, deviceId, enabled) {
 async function migrateDevice$1(deps, input) {
 	const { sourceId, targetId } = input;
 	if (sourceId === targetId) throw new Error(`[device-manager] migrateDevice: ${sourceId} is both source and target`);
+	await deps.assertNoFieldClaims(sourceId, targetId);
+	const ids = {
+		sourceId,
+		targetId
+	};
+	const prior = new Map([[sourceId, await readPriorSwitches(deps, sourceId)], [targetId, await readPriorSwitches(deps, targetId)]]);
 	const down = [...await applyAll(deps, sourceId, false), ...await applyAll(deps, targetId, false)];
 	const sourceStillLive = down.filter((r) => r.deviceId === sourceId && r.outcome === "unreachable").map((r) => r.switchId);
-	await deps.swapIds(sourceId, targetId);
-	await deps.swapHardwareState(sourceId, targetId);
+	try {
+		await deps.swapIds(sourceId, targetId);
+	} catch (err) {
+		if (err instanceof MigrationRefusedError) return rollBackRefusal(deps, ids, prior, err);
+		alarmPartialMigration(deps, ids, "swapIds", err);
+		throw err;
+	}
+	try {
+		await deps.swapHardwareState(sourceId, targetId);
+	} catch (err) {
+		alarmPartialMigration(deps, ids, "swapHardwareState", err);
+		throw err;
+	}
 	for (const deviceId of [sourceId, targetId]) try {
 		await deps.forgetStreamState(deviceId);
 	} catch (err) {
@@ -4288,7 +4766,12 @@ async function reloadMigratedDevices(pctx, targets) {
 *    map — see `StreamsTab.tsx`, which stopped writing it), and either copy
 *    names stream ids of the wrong hardware after a swap.
 *  - The runtime-state blobs (`__device-state:<id>` — battery snapshot, sleep
-*    flag, feature probe) SWAP wholesale: every slice mirrors the box.
+*    flag, feature probe) SWAP wholesale: every slice mirrors the box — never
+*    while either carries `$owned` (D663): the migration is refused first
+*    ({@link assertNoFieldClaims}). A claim names the NUMBER, the block that
+*    owns it names a STABLE ID, and the swap moves the stable id to the other
+*    number; whatever it did with `$owned`, one of the two keys would end up
+*    on the wrong device.
 *
 * ## Crash points are loud, same as `swapIds`
 *
@@ -4301,6 +4784,92 @@ async function reloadMigratedDevices(pctx, targets) {
 var PROFILE_MAP_CONFIG_KEY = "_profileMap";
 /** Config keys that belong to the camera's ROLE and stay with the number. */
 var ROLE_SCOPED_CONFIG_KEYS = LINKED_DEVICES_RESERVED_KEYS;
+/**
+* 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.
+*/
+var FieldClaimsBlockMigrationError = class extends Error {
+	sourceId;
+	targetId;
+	blocked;
+	constructor(sourceId, targetId, blocked) {
+		super(`migration ${sourceId} → ${targetId} refused: ${describeBlocked(blocked)} — delete the customization before migrating (the composer releases its claims; then retry)`);
+		this.sourceId = sourceId;
+		this.targetId = targetId;
+		this.blocked = blocked;
+		this.name = "FieldClaimsBlockMigrationError";
+	}
+};
+/**
+* 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.
+*/
+var ClaimLandedDuringMigrationError = class extends MigrationRefusedError {
+	sourceId;
+	targetId;
+	blocked;
+	constructor(sourceId, targetId, blocked) {
+		super(`migration ${sourceId} → ${targetId} refused: ${describeBlocked(blocked)}, landed while the migration was starting — nothing moved; delete the customization, then retry`);
+		this.sourceId = sourceId;
+		this.targetId = targetId;
+		this.blocked = blocked;
+		this.name = "ClaimLandedDuringMigrationError";
+	}
+};
+function describeBlocked(blocked) {
+	return blocked.map(({ deviceId, claims }) => {
+		return `device ${deviceId} has fields claimed by a customization (${claims.map((c) => `${c.cap} [${c.fields.join(", ")}]: ${c.owner}`).join(", ")})`;
+	}).join("; ");
+}
+function blockingClaims(owned) {
+	return [...owned].map(([cap, o]) => ({
+		cap,
+		owner: o.owner,
+		fields: [...o.fields]
+	}));
+}
+/**
+* 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.
+*/
+function assertNoClaimLandedDuringMigration(ownedCapsOf, sourceId, targetId) {
+	const blocked = [];
+	for (const deviceId of [sourceId, targetId]) {
+		const owned = ownedCapsOf(deviceId);
+		if (owned.size > 0) blocked.push({
+			deviceId,
+			claims: blockingClaims(owned)
+		});
+	}
+	if (blocked.length > 0) throw new ClaimLandedDuringMigrationError(sourceId, targetId, blocked);
+}
+/**
+* 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).
+*/
+async function assertNoFieldClaims(settings, sourceId, targetId) {
+	const blocked = [];
+	for (const deviceId of [sourceId, targetId]) {
+		const { owned } = splitRuntimeBlob(await settings.readDeviceRuntimeState(deviceId));
+		if (owned.size > 0) blocked.push({
+			deviceId,
+			claims: blockingClaims(owned)
+		});
+	}
+	if (blocked.length > 0) throw new FieldClaimsBlockMigrationError(sourceId, targetId, blocked);
+}
 function splitConfig(config) {
 	const hardware = {};
 	const role = {};
@@ -4694,6 +5263,7 @@ async function migrateDevice(pctx, input) {
 				};
 			}
 			const tempId = await pctx.metaStore.allocateNextDeviceId();
+			const held = { current: null };
 			const result = await migrateDevice$1({
 				setSwitch: async (deviceId, switchId, enabled) => {
 					if (switchId === "stream-broker") {
@@ -4708,12 +5278,41 @@ async function migrateDevice(pctx, input) {
 					});
 				},
 				swapIds: async (a, b) => {
+					held.current = await pctx.host.holdMirrorWrites([a, b], pctx.settings);
+					try {
+						assertNoClaimLandedDuringMigration((id) => pctx.host.mirrorOwnedCaps(id), a, b);
+					} catch (err) {
+						if (err instanceof ClaimLandedDuringMigrationError) for (const blocked of err.blocked) ctx.logger.warn("migrateDevice refused: a claim landed during the migration", {
+							tags: { deviceId: blocked.deviceId },
+							meta: {
+								sourceId: a,
+								targetId: b,
+								claims: blocked.claims
+							}
+						});
+						throw err;
+					}
 					await pctx.metaStore.rows.swapIds(a, b, tempId);
 				},
+				assertNoFieldClaims: async (a, b) => {
+					try {
+						await assertNoFieldClaims(pctx.settings, a, b);
+					} catch (err) {
+						if (err instanceof FieldClaimsBlockMigrationError) for (const blocked of err.blocked) ctx.logger.warn("migrateDevice refused: fields claimed by a customization", {
+							tags: { deviceId: blocked.deviceId },
+							meta: {
+								sourceId: a,
+								targetId: b,
+								claims: blocked.claims
+							}
+						});
+						throw err;
+					}
+				},
 				swapHardwareState: async (a, b) => {
 					const swapped = await swapHardwareState(pctx.settings, a, b);
-					pctx.host.seedMirror(a, pctx.host.withResetSessionProbe(swapped.runtimeStateNowAtSource));
-					pctx.host.seedMirror(b, pctx.host.withResetSessionProbe(swapped.runtimeStateNowAtTarget));
+					pctx.host.seedMirror(a, pctx.host.withResetSessionProbe(swapped.runtimeStateNowAtSource), "replace");
+					pctx.host.seedMirror(b, pctx.host.withResetSessionProbe(swapped.runtimeStateNowAtTarget), "replace");
 					ctx.logger.info("migration: hardware-scoped device state swapped", {
 						tags: { deviceId: a },
 						meta: {
@@ -4734,11 +5333,21 @@ async function migrateDevice(pctx, input) {
 						tags: { deviceId: sourceId },
 						meta
 					});
+				},
+				readSwitches: async (deviceId) => {
+					const group = await ctx.api.pipelineOrchestrator.getCameraSwitches.query({ deviceId });
+					return new Map(group.switches.filter((sw) => sw.available).map((sw) => [sw.id, sw.enabled]));
+				},
+				logDevice: (level, deviceId, message, meta) => {
+					ctx.logger[level](message, {
+						tags: { deviceId },
+						meta
+					});
 				}
 			}, {
 				sourceId,
 				targetId
-			});
+			}).finally(() => held.current?.release());
 			pctx.migrationGuard.recordCompleted({
 				sourceId,
 				targetId,
@@ -4932,6 +5541,7 @@ async function removeDevice(pctx, input) {
 	});
 	await pctx.settings.clearDeviceStore(deviceId);
 	await pctx.settings.clearDeviceRuntimeState(deviceId);
+	await pctx.host.fieldClaims.pruneDevice(deviceId, pctx.settings);
 	const bindingKey = String(deviceId);
 	await pctx.bindingsDeps.withAddonStoreWriteLock(async () => {
 		const bindingsStore = await readBindingsStore(pctx.bindingsDeps);
@@ -5588,7 +6198,7 @@ async function loadRuntimeState(pctx, input) {
 	if (!await pctx.metaStore.resolvePersistedById(deviceId)) return {};
 	const data = await pctx.settings.readDeviceRuntimeState(deviceId);
 	pctx.host.seedMirror(deviceId, pctx.host.withResetSessionProbe(data));
-	return data;
+	return splitRuntimeBlob(data).native;
 }
 /**
 * Union of (1) operator-curated location registry and (2) labels
@@ -7161,15 +7771,10 @@ var DeviceRowStore = class {
 	* functions on both devices in the same critical section.
 	*/
 	async swapIds(a, b, tempId) {
-		if (a === b) throw new Error(`[device-manager] swapIds: ${a} and ${b} are the same device`);
-		await this.declare();
-		const rowA = await this.get(a);
-		const rowB = await this.get(b);
-		if (rowA === null) throw new Error(`[device-manager] swapIds: device ${a} does not exist`);
-		if (rowB === null) throw new Error(`[device-manager] swapIds: device ${b} does not exist`);
-		if (await this.get(tempId) !== null) throw new Error(`[device-manager] swapIds: temp id ${tempId} is taken`);
-		const childrenOfA = (await this.listByParent(a)).map((r) => r.meta.id);
-		const childrenOfB = (await this.listByParent(b)).map((r) => r.meta.id);
+		const { rowA, rowB, childrenOfA, childrenOfB } = await this.planSwap(a, b, tempId).catch((err) => {
+			if (err instanceof MigrationRefusedError) throw err;
+			throw new MigrationRefusedError(`[device-manager] swapIds: precheck failed before any row moved — ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+		});
 		await this.moveRow(rowA, tempId);
 		await this.moveRow(rowB, a);
 		await this.moveRow({
@@ -7191,6 +7796,22 @@ var DeviceRowStore = class {
 			}
 		});
 	}
+	/** The read-only half of {@link swapIds}: every refusal, every read, no write. */
+	async planSwap(a, b, tempId) {
+		if (a === b) throw new MigrationRefusedError(`[device-manager] swapIds: ${a} and ${b} are the same device`);
+		await this.declare();
+		const rowA = await this.get(a);
+		const rowB = await this.get(b);
+		if (rowA === null) throw new MigrationRefusedError(`[device-manager] swapIds: device ${a} does not exist`);
+		if (rowB === null) throw new MigrationRefusedError(`[device-manager] swapIds: device ${b} does not exist`);
+		if (await this.get(tempId) !== null) throw new MigrationRefusedError(`[device-manager] swapIds: temp id ${tempId} is taken`);
+		return {
+			rowA,
+			rowB,
+			childrenOfA: (await this.listByParent(a)).map((r) => r.meta.id),
+			childrenOfB: (await this.listByParent(b)).map((r) => r.meta.id)
+		};
+	}
 	/** Rewrite a row under a new id and drop the old key. Not exported: the only
 	*  legitimate reason to move a row is {@link swapIds}. */
 	async moveRow(row, toId) {
@@ -7241,6 +7862,118 @@ var DeviceRowStore = class {
 	}
 };
 //#endregion
+//#region src/builtins/device-manager/device-state-claims.ts
+function createDeviceStateClaimMethods(deps) {
+	const { mirror, index, settings, logger } = deps;
+	function unknownDevice(deviceId) {
+		return refused("unknown-device", `device ${deviceId} is not registered`);
+	}
+	/** A device under migration takes no claim, patch or release — refused by name, before either store. */
+	function migrating(deviceId, op) {
+		if (!deps.migrationInFlight(deviceId)) return null;
+		logger.warn(`${op} refused — a migration of the device is in flight`, {
+			tags: { deviceId },
+			meta: { op }
+		});
+		return refused("migration-in-flight", `device ${deviceId} is being migrated — its row is about to be swapped; retry once the migration is over`);
+	}
+	function claimOnRow(input) {
+		return mirror.claim(input.deviceId, input.capName, {
+			owner: input.owner,
+			mode: input.mode,
+			fields: [...input.fields],
+			values: { ...input.values }
+		}, settings);
+	}
+	return {
+		async claimFields(input) {
+			const { deviceId, capName, owner, mode, fields } = input;
+			const outside = Object.keys(input.values).filter((k) => !fields.includes(k));
+			if (outside.length > 0) return refused("field-not-claimed", `values name fields outside the claim: ${outside.join(", ")}`);
+			if (!await deps.deviceExists(deviceId)) return unknownDevice(deviceId);
+			const gated = migrating(deviceId, "claim");
+			if (gated) return gated;
+			const key = {
+				deviceId,
+				capName
+			};
+			const entry = {
+				deviceId,
+				capName,
+				owner,
+				mode,
+				fields: [...fields]
+			};
+			if (index.entry(key) !== void 0) {
+				const outcome = await claimOnRow(input);
+				if (outcome.ok) await index.upsert(entry, settings);
+				return outcome;
+			}
+			await index.upsert(entry, settings);
+			let outcome;
+			try {
+				outcome = await claimOnRow(input);
+			} catch (err) {
+				logger.warn("claim row write failed — index entry kept; a release heals it", {
+					tags: { deviceId },
+					meta: {
+						cap: capName,
+						owner,
+						error: errorMessage$3(err)
+					}
+				});
+				throw err;
+			}
+			if (!outcome.ok) await dropRefusedEntry(key, outcome.code);
+			return outcome;
+		},
+		async patchOwnedFields(input) {
+			if (!await deps.deviceExists(input.deviceId)) return unknownDevice(input.deviceId);
+			const gated = migrating(input.deviceId, "patch");
+			if (gated) return gated;
+			return mirror.patchOwned(input.deviceId, input.capName, input.owner, { ...input.values }, settings);
+		},
+		async releaseClaim(input) {
+			const { deviceId, capName, owner } = input;
+			const key = {
+				deviceId,
+				capName
+			};
+			if (!await deps.deviceExists(deviceId)) {
+				await index.remove(key, settings);
+				return unknownDevice(deviceId);
+			}
+			const gated = migrating(deviceId, "release");
+			if (gated) return gated;
+			const outcome = await mirror.release(deviceId, capName, owner, settings);
+			if (outcome.ok || outcome.code === "not-claimed") await index.remove(key, settings);
+			return outcome;
+		},
+		async listClaims(input) {
+			await index.load(settings);
+			return index.list(input.ownerPrefix);
+		}
+	};
+	/** A first claim the row refused must not stay announced: drop the entry this call added. */
+	async function dropRefusedEntry(key, code) {
+		try {
+			await index.remove(key, settings);
+		} catch (err) {
+			logger.warn("claims index not restored after a refused claim — stale entry until the next release", {
+				tags: { deviceId: key.deviceId },
+				meta: {
+					cap: key.capName,
+					refusal: code,
+					error: errorMessage$3(err)
+				}
+			});
+		}
+	}
+}
+function errorMessage$3(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+//#endregion
 //#region src/builtins/device-manager/runtime-state-persist-gate.ts
 /**
 * The subset of `blob` that is allowed on disk: slices whose capability
@@ -7250,11 +7983,15 @@ var DeviceRowStore = class {
 * 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.
 */
 function persistableBlob(blob, policyFor) {
 	const out = {};
 	for (const [capName, slice] of Object.entries(blob)) {
-		if (policyFor(capName).durability !== "restored") continue;
+		if (capName !== "$owned" && policyFor(capName).durability !== "restored") continue;
 		out[capName] = { ...slice };
 	}
 	return out;
@@ -7323,44 +8060,45 @@ function deepEqual(a, b) {
 	return true;
 }
 //#endregion
-//#region src/builtins/device-manager/device-state-mirror.ts
+//#region src/builtins/device-manager/mirror-row-writer.ts
+function errorMessage$2(err) {
+	return err instanceof Error ? err.message : String(err);
+}
 /**
-* Hub-side runtime-state mirror for the device-manager addon.
-*
-* `DeviceStateMirror` owns the per-device cap-keyed slice mirror and the
-* debounced disk-write coalescer. It mirrors every `deviceState.setCapSlice`
-* write, emits `DeviceStateChanged`, and coalesces frequent writes into one
-* `writeDeviceRuntimeState` per debounce window.
-*
-* It used to do one more thing: overlay each emitted slice with cross-device
-* LINKED values, walk a `linkDependents` reverse-index and re-emit for every
-* dependent target, guarded by a `lastEmittedOverlay` churn map. Wiring was
-* deleted on 2026-08-08 (0 links across 302 devices), so the mirror emits what
-* the provider wrote — one writer per field, which is what D62 asks for
-* everywhere else.
+* 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.
 */
-var DeviceStateMirror = class DeviceStateMirror {
-	ctx;
-	policyFor;
-	/**
-	* Hub-side mirror of every device's cap-keyed runtime state.
-	* Key: deviceId. Value: per-cap slice map. Empty by default —
-	* slices show up as `setCapSlice` calls trickle in.
-	*/
-	stateMirror = /* @__PURE__ */ new Map();
+var RuntimeStateDrainError = class extends MigrationRefusedError {
+	deviceId;
+	constructor(deviceId, reason, options) {
+		super(`migration refused: the runtime state of device ${deviceId} could not be drained before the swap (${reason}) — nothing moved; retry the migration`, options);
+		this.deviceId = deviceId;
+		this.name = "RuntimeStateDrainError";
+	}
+};
+var MirrorRowWriter = class MirrorRowWriter {
+	deps;
+	static RUNTIME_STATE_DEBOUNCE_MS = 1e3;
 	/**
 	* 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.
 	*/
 	runtimeStateDebounce = /* @__PURE__ */ new Map();
-	static RUNTIME_STATE_DEBOUNCE_MS = 1e3;
+	/**
+	* Devices whose debounced writer is HELD off the row — a migration is
+	* swapping it (`holdDiskWrites`). A change while held stays in memory only.
+	*/
+	writesHeld = /* @__PURE__ */ new Set();
+	/** Held devices a durable change was scheduled for — what `release` re-arms. */
+	heldDirty = /* @__PURE__ */ new Set();
 	/**
 	* 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.
+	* 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.
 	*/
 	lastPersisted = /* @__PURE__ */ new Map();
 	/**
@@ -7370,33 +8108,55 @@ var DeviceStateMirror = class DeviceStateMirror {
 	* that drops work silently reads as "never happened".
 	*/
 	skippedSinceWrite = /* @__PURE__ */ new Map();
-	constructor(ctx, policyFor = runtimeStatePolicyFor) {
-		this.ctx = ctx;
-		this.policyFor = policyFor;
+	constructor(deps) {
+		this.deps = deps;
+	}
+	/** What is believed to be on the device's row; undefined before any read or write. */
+	persisted(deviceId) {
+		return this.lastPersisted.get(deviceId);
+	}
+	/** Record what the row now holds — a write that landed, or a row just read. */
+	markPersisted(deviceId, row) {
+		this.lastPersisted.set(deviceId, row);
+	}
+	/** A migration holds the writer off this device's row right now. */
+	isHeld(deviceId) {
+		return this.writesHeld.has(deviceId);
 	}
 	/**
-	* 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.
-	*
-	* @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
-	*   here and scheduling unconditionally is what made an unchanged poll cost
-	*   a SQLite commit.
+	* 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.
 	*/
-	applySingleCapUpdate(deviceId, capName, slice) {
-		let perCap = this.stateMirror.get(deviceId);
-		if (!perCap) {
-			perCap = /* @__PURE__ */ new Map();
-			this.stateMirror.set(deviceId, perCap);
+	serialiseWrite(deviceId, task) {
+		const slot = this.slotFor(deviceId);
+		const run = (slot.inFlight ?? Promise.resolve()).then(task);
+		const tail = run.then(() => void 0, () => void 0);
+		slot.inFlight = tail;
+		tail.then(() => {
+			if (slot.inFlight === tail) slot.inFlight = null;
+		});
+		return run;
+	}
+	slotFor(deviceId) {
+		let slot = this.runtimeStateDebounce.get(deviceId);
+		if (!slot) {
+			slot = {
+				timer: null,
+				inFlight: null,
+				lastWriteFailed: false
+			};
+			this.runtimeStateDebounce.set(deviceId, slot);
 		}
-		const prior = perCap.get(capName);
-		if (prior && shallowEqual(prior, slice)) return false;
-		perCap.set(capName, { ...slice });
-		this.emitStateChanged(deviceId, capName, { ...slice });
-		return true;
+		return slot;
+	}
+	/** Arm the writer for a durable change, or remember it for `release` while a migration holds the device. */
+	armOrHold(deviceId, settings) {
+		if (this.writesHeld.has(deviceId)) {
+			this.heldDirty.add(deviceId);
+			return;
+		}
+		this.armDiskWrite(deviceId, settings);
 	}
 	/**
 	* Debounced disk writer, behind two gates.
@@ -7414,45 +8174,118 @@ var DeviceStateMirror = class DeviceStateMirror {
 	* 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.
 	*/
-	scheduleRuntimeStateDiskWrite(deviceId, settings, changedCap) {
-		if (this.policyFor(changedCap).durability !== "restored") return;
-		let slot = this.runtimeStateDebounce.get(deviceId);
-		if (!slot) {
-			slot = {
-				timer: null,
-				inFlight: null
-			};
-			this.runtimeStateDebounce.set(deviceId, slot);
-		}
+	schedule(deviceId, settings, changedCap) {
+		if (this.deps.policyFor(changedCap).durability !== "restored") return;
+		this.armOrHold(deviceId, settings);
+	}
+	/** Arm the debounce timer; at fire, queue a write of the live blob unless disk already has it. */
+	armDiskWrite(deviceId, settings) {
+		const slot = this.slotFor(deviceId);
 		if (slot.timer) return;
 		slot.timer = setTimeout(() => {
 			slot.timer = null;
-			const blob = this.persistableForDevice(deviceId);
-			if (this.isAlreadyPersisted(deviceId, blob)) return;
-			const skipped = this.skippedSinceWrite.get(deviceId) ?? 0;
-			this.skippedSinceWrite.delete(deviceId);
-			const write = (async () => {
-				try {
-					await settings.writeDeviceRuntimeState(deviceId, blob);
-					this.lastPersisted.set(deviceId, blob);
-					if (skipped > 0) this.ctx.logger.debug("runtime state persisted", {
-						tags: { deviceId },
-						meta: {
-							caps: Object.keys(blob).length,
-							skippedSinceLastWrite: skipped
-						}
-					});
-				} catch (err) {
-					this.ctx.logger.warn("writeDeviceRuntimeState failed", {
-						tags: { deviceId },
-						meta: { error: err instanceof Error ? err.message : String(err) }
-					});
-				} finally {
-					slot.inFlight = null;
+			this.serialiseWrite(deviceId, () => this.writeLiveBlob(deviceId, settings, slot));
+		}, MirrorRowWriter.RUNTIME_STATE_DEBOUNCE_MS);
+	}
+	/** The debounced write itself: the blob as memory holds it NOW, behind the effective-change gate. Never rejects. */
+	async writeLiveBlob(deviceId, settings, slot) {
+		const blob = this.deps.persistableFor(deviceId);
+		if (this.isAlreadyPersisted(deviceId, blob)) return;
+		const skipped = this.skippedSinceWrite.get(deviceId) ?? 0;
+		this.skippedSinceWrite.delete(deviceId);
+		try {
+			await settings.writeDeviceRuntimeState(deviceId, blob);
+			this.lastPersisted.set(deviceId, blob);
+			slot.lastWriteFailed = false;
+			if (skipped > 0) this.deps.logger.debug("runtime state persisted", {
+				tags: { deviceId },
+				meta: {
+					caps: Object.keys(blob).length,
+					skippedSinceLastWrite: skipped
 				}
-			})();
-			slot.inFlight = write;
-		}, DeviceStateMirror.RUNTIME_STATE_DEBOUNCE_MS);
+			});
+		} catch (err) {
+			slot.lastWriteFailed = true;
+			this.deps.logger.warn("writeDeviceRuntimeState failed", {
+				tags: { deviceId },
+				meta: { error: errorMessage$2(err) }
+			});
+		}
+	}
+	/**
+	* 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.
+	*/
+	async holdDiskWrites(deviceIds, settings) {
+		for (const deviceId of deviceIds) this.writesHeld.add(deviceId);
+		const release = () => {
+			for (const deviceId of deviceIds) {
+				this.writesHeld.delete(deviceId);
+				if (this.heldDirty.delete(deviceId)) this.armDiskWrite(deviceId, settings);
+			}
+		};
+		try {
+			for (const deviceId of deviceIds) await this.drainDiskWrite(deviceId, settings);
+		} catch (err) {
+			release();
+			throw err;
+		}
+		return { release };
+	}
+	/** Cancel the timer, await the write in flight, then write (queued) what is not yet on disk. */
+	async drainDiskWrite(deviceId, settings) {
+		const slot = this.runtimeStateDebounce.get(deviceId);
+		const pending = slot?.timer ?? null;
+		if (slot && pending) {
+			clearTimeout(pending);
+			slot.timer = null;
+		}
+		if (slot?.inFlight) await slot.inFlight;
+		const lastFailed = slot?.lastWriteFailed ?? false;
+		if (!pending && !lastFailed) return;
+		const blob = this.deps.persistableFor(deviceId);
+		if (this.isAlreadyPersisted(deviceId, blob)) {
+			if (slot) slot.lastWriteFailed = false;
+			return;
+		}
+		if (lastFailed) this.refuseDrain(deviceId, "its last runtime-state write did not land", null);
+		try {
+			await this.serialiseWrite(deviceId, () => settings.writeDeviceRuntimeState(deviceId, blob));
+		} catch (err) {
+			this.refuseDrain(deviceId, `the pending runtime-state write failed: ${errorMessage$2(err)}`, err);
+		}
+		this.lastPersisted.set(deviceId, blob);
+	}
+	/** A drain that cannot vouch for the row: still owed (re-armed on release), logged, refused. */
+	refuseDrain(deviceId, reason, cause) {
+		this.heldDirty.add(deviceId);
+		this.deps.logger.warn("migration drain: runtime state not on the row — migration refused", {
+			tags: { deviceId },
+			meta: { reason }
+		});
+		throw new RuntimeStateDrainError(deviceId, reason, cause === null ? void 0 : { cause });
 	}
 	/**
 	* True when `blob` differs from what is believed to be on disk only in fields
@@ -7462,35 +8295,468 @@ var DeviceStateMirror = class DeviceStateMirror {
 	isAlreadyPersisted(deviceId, blob) {
 		const onDisk = this.lastPersisted.get(deviceId);
 		if (!onDisk) return false;
-		if (!effectivelyEqual(onDisk, blob, this.policyFor)) return false;
+		if (!effectivelyEqual(onDisk, blob, this.deps.policyFor)) return false;
 		this.skippedSinceWrite.set(deviceId, (this.skippedSinceWrite.get(deviceId) ?? 0) + 1);
 		return true;
 	}
-	/** The device's mirror, restricted to the slices that may reach disk. */
-	persistableForDevice(deviceId) {
-		return persistableBlob(this.snapshotForDevice(deviceId), this.policyFor);
+	/** Flush every pending debounced disk write (graceful shutdown). Clears the
+	*  debounce slots after awaiting in-flight + scheduled writes so shutdown is
+	*  lossless. */
+	async flushPendingWrites(settings) {
+		const pending = [];
+		for (const [deviceId, slot] of this.runtimeStateDebounce) {
+			if (slot.timer) {
+				clearTimeout(slot.timer);
+				slot.timer = null;
+				if (settings) {
+					pending.push(this.serialiseWrite(deviceId, () => this.writeLiveBlob(deviceId, settings, slot)));
+					continue;
+				}
+			}
+			if (slot.inFlight) pending.push(slot.inFlight);
+		}
+		await Promise.all(pending);
+		this.runtimeStateDebounce.clear();
+	}
+};
+//#endregion
+//#region src/builtins/device-manager/device-state-mirror.ts
+/**
+* Hub-side runtime-state mirror for the device-manager addon.
+*
+* `DeviceStateMirror` owns the per-device cap-keyed slice mirror and the
+* debounced disk-write coalescer. It mirrors every `deviceState.setCapSlice`
+* write, emits `DeviceStateChanged`, and coalesces frequent writes into one
+* `writeDeviceRuntimeState` per debounce window.
+*
+* It used to do one more thing: overlay each emitted slice with cross-device
+* LINKED values, walk a `linkDependents` reverse-index and re-emit for every
+* dependent target, guarded by a `lastEmittedOverlay` churn map. Wiring was
+* deleted on 2026-08-08 (0 links across 302 devices), so the mirror emits what
+* the provider wrote — one writer per field, which is what D62 asks for
+* everywhere else.
+*
+* ── Per-field claims (D663) ────────────────────────────────────────────────
+* A composition may CLAIM fields of a cap on an existing device. The provider
+* keeps writing; `stateMirror` keeps its slice as the NATIVE SHADOW, and what
+* is read and emitted for a claimed cap is the MERGE (`ClaimViews`). A device
+* with no claims never touches any of this: same slices, same events, same row.
+* Claims live in the device's own row under `$owned`, written THROUGH (rolled
+* back in memory when the write fails and nothing newer landed in its window);
+* owned values follow the native debounce and effective-change gate. Every row
+* write of a device — debounced, write-through, shutdown flush — goes through
+* ONE queue per device (`MirrorRowWriter`, `mirror-row-writer.ts`), so two
+* writes are never in flight at once and each carries the memory of the moment
+* it runs. The shadow reaches
+* the owner alone — `nativeSlice` and `DeviceNativeShadowChanged`, a category
+* the public routers refuse (D224).
+*/
+var SEED_REFUSAL_MESSAGE = "runtime-state row unreadable — native write refused until it reads (D49)";
+function errorMessage$1(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+var DeviceStateMirror = class {
+	ctx;
+	policyFor;
+	/**
+	* 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.
+	*/
+	stateMirror = /* @__PURE__ */ new Map();
+	/** The claims and the merged view of every claimed cap (D663). */
+	claims;
+	/** Devices whose row has been consulted (or ruled empty by the index). */
+	seeded = /* @__PURE__ */ new Set();
+	/** Devices whose row was actually READ into memory — a write-through needs this. */
+	rowRead = /* @__PURE__ */ new Set();
+	/** One row read per device, however many writes arrive during it. */
+	seeding = /* @__PURE__ */ new Map();
+	/** Devices whose seed refusal is already logged — once per transition. */
+	seedRefusalLogged = /* @__PURE__ */ new Set();
+	/** Every write of a device's row, and what is believed to be on it. */
+	writer;
+	constructor(ctx, policyFor = runtimeStatePolicyFor, schemaFor = defaultSchemaFor) {
+		this.ctx = ctx;
+		this.policyFor = policyFor;
+		this.claims = new ClaimViews({
+			logger: ctx.logger,
+			schemaFor,
+			emitSlice: (deviceId, capName, slice) => this.emitStateChanged(deviceId, capName, slice)
+		});
+		this.writer = new MirrorRowWriter({
+			logger: ctx.logger,
+			policyFor,
+			persistableFor: (deviceId) => this.persistableForDevice(deviceId)
+		});
 	}
 	/**
-	* 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.
+	* 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.
 	*
-	* Callers that must not carry a stale per-session probe across a
-	* restart pass the blob through `withResetSessionProbe` first (see
-	* `loadRuntimeState`).
+	* @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
+	*   here and scheduling unconditionally is what made an unchanged poll cost
+	*   a SQLite commit.
 	*/
-	seedMirror(deviceId, blob) {
+	applySingleCapUpdate(deviceId, capName, slice) {
 		let perCap = this.stateMirror.get(deviceId);
 		if (!perCap) {
 			perCap = /* @__PURE__ */ new Map();
 			this.stateMirror.set(deviceId, perCap);
 		}
-		for (const [capName, raw] of Object.entries(blob)) {
-			if (!raw || typeof raw !== "object" || Array.isArray(raw)) continue;
-			perCap.set(capName, { ...raw });
+		const prior = perCap.get(capName);
+		if (prior && shallowEqual(prior, slice)) return false;
+		perCap.set(capName, { ...slice });
+		const claim = this.claims.claim(deviceId, capName);
+		if (claim) {
+			if (claim.mode === "replace") this.emitNativeShadow(deviceId, capName, { ...slice });
+			this.claims.recompute(deviceId, capName, claim, { ...slice }, true);
+			return true;
+		}
+		this.emitStateChanged(deviceId, capName, { ...slice });
+		return true;
+	}
+	/**
+	* 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.
+	*/
+	async claim(deviceId, capName, cap, settings) {
+		if (cap.fields.length === 0) return refused("invalid-slice", "claim at least one field or release");
+		const outside = Object.keys(cap.values).filter((k) => !cap.fields.includes(k));
+		if (outside.length > 0) return refused("field-not-claimed", `values name fields outside the claim: ${outside.join(", ")}`);
+		const unreadable = await this.readRowOrRefuse(deviceId, settings);
+		if (unreadable) return unreadable;
+		if (this.writer.isHeld(deviceId)) {
+			this.ctx.logger.warn("claim refused — a migration holds the device row", {
+				tags: { deviceId },
+				meta: {
+					cap: capName,
+					owner: cap.owner
+				}
+			});
+			return refused("migration-in-flight", `device ${deviceId} is being migrated — its row is about to be swapped; retry once the migration is over`);
+		}
+		const existing = this.claims.claim(deviceId, capName);
+		if (existing && existing.owner !== cap.owner) return refused("owned-by-other", `${capName} on device ${deviceId} is claimed by ${existing.owner}`);
+		const kept = {};
+		if (existing) {
+			for (const f of cap.fields) if (Object.hasOwn(existing.values, f)) kept[f] = existing.values[f];
+		}
+		const next = {
+			owner: cap.owner,
+			mode: cap.mode,
+			fields: [...cap.fields],
+			values: {
+				...kept,
+				...cap.values
+			}
+		};
+		if (existing && sameOwnedCap(existing, next) && this.isClaimPersisted(deviceId, capName, next)) return {
+			ok: true,
+			changed: false
+		};
+		const prevView = this.claims.view(deviceId, capName);
+		this.claims.setClaim(deviceId, capName, next);
+		this.claims.previewView(deviceId, capName, next, this.nativeOf(deviceId, capName));
+		await this.writeThrough(deviceId, settings, {
+			op: "claim",
+			cap: capName,
+			owner: cap.owner
+		}, () => {
+			if (this.claims.claim(deviceId, capName) !== next) return false;
+			if (existing) {
+				this.claims.setClaim(deviceId, capName, existing);
+				this.claims.restoreView(deviceId, capName, prevView);
+			} else this.claims.deleteClaim(deviceId, capName);
+			return true;
+		});
+		const current = this.claims.claim(deviceId, capName);
+		if (current) {
+			this.claims.restoreView(deviceId, capName, prevView);
+			this.claims.recompute(deviceId, capName, current, this.nativeOf(deviceId, capName), false);
 		}
-		this.lastPersisted.set(deviceId, persistableBlob(this.snapshotForDevice(deviceId), this.policyFor));
+		return {
+			ok: true,
+			changed: true
+		};
+	}
+	/** Is this exact claim what the row carries, per `lastPersisted`? */
+	isClaimPersisted(deviceId, capName, claim) {
+		const onDisk = this.writer.persisted(deviceId)?.[OWNED_FIELDS_KEY]?.[capName];
+		const expected = joinRuntimeBlob({}, new Map([[capName, claim]]), this.policyFor)[OWNED_FIELDS_KEY]?.[capName];
+		if (!isPlainRecord(onDisk) || !isPlainRecord(expected)) return false;
+		return sliceEffectivelyEqual(onDisk, expected, []);
+	}
+	/**
+	* Write owned values. Partial patches MERGE into `values` (ruling S5); a key
+	* outside `fields` is refused. Debounced like a native slice.
+	*/
+	async patchOwned(deviceId, capName, owner, values, settings) {
+		const unreadable = await this.readRowOrRefuse(deviceId, settings);
+		if (unreadable) return unreadable;
+		const existing = this.claims.claim(deviceId, capName);
+		if (!existing) return refused("not-claimed", `${capName} on device ${deviceId} has no claim`);
+		if (existing.owner !== owner) return refused("owned-by-other", `${capName} on device ${deviceId} is claimed by ${existing.owner}`);
+		const outside = Object.keys(values).filter((k) => !existing.fields.includes(k));
+		if (outside.length > 0) return refused("field-not-claimed", `not in the claim on ${capName}: ${outside.join(", ")}`);
+		const next = {
+			...existing,
+			values: {
+				...existing.values,
+				...values
+			}
+		};
+		if (sameOwnedCap(existing, next)) return {
+			ok: true,
+			changed: false
+		};
+		this.claims.setClaim(deviceId, capName, next);
+		this.claims.recompute(deviceId, capName, next, this.nativeOf(deviceId, capName), false);
+		this.writer.schedule(deviceId, settings, capName);
+		return {
+			ok: true,
+			changed: true
+		};
+	}
+	/**
+	* 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.
+	*/
+	async release(deviceId, capName, owner, settings) {
+		const unreadable = await this.readRowOrRefuse(deviceId, settings);
+		if (unreadable) return unreadable;
+		const existing = this.claims.claim(deviceId, capName);
+		if (!existing) return refused("not-claimed", `${capName} on device ${deviceId} has no claim`);
+		if (existing.owner !== owner) return refused("owned-by-other", `${capName} on device ${deviceId} is claimed by ${existing.owner}`);
+		const prevView = this.claims.view(deviceId, capName);
+		this.claims.deleteClaim(deviceId, capName);
+		await this.writeThrough(deviceId, settings, {
+			op: "release",
+			cap: capName,
+			owner
+		}, () => {
+			if (this.claims.claim(deviceId, capName) !== void 0) return false;
+			this.claims.setClaim(deviceId, capName, existing);
+			this.claims.restoreView(deviceId, capName, prevView);
+			return true;
+		});
+		if (this.claims.claim(deviceId, capName) !== void 0) return {
+			ok: true,
+			changed: true
+		};
+		const native = this.nativeOf(deviceId, capName);
+		if (existing.mode === "replace" && native) this.emitStateChanged(deviceId, capName, { ...native });
+		else if (existing.mode === "replace") this.ctx.logger.debug("claim released before any native slice arrived — nothing to emit", {
+			tags: { deviceId },
+			meta: {
+				cap: capName,
+				owner
+			}
+		});
+		return {
+			ok: true,
+			changed: true
+		};
+	}
+	/** The claims on a device; empty for every device without one. */
+	ownedCaps(deviceId) {
+		return this.claims.ownedCaps(deviceId);
+	}
+	/** The NATIVE shadow of one cap — for the owner-side mechanism only (D224). */
+	nativeSlice(deviceId, cap) {
+		const raw = this.stateMirror.get(deviceId)?.get(cap);
+		return raw ? { ...raw } : null;
+	}
+	/** What the merge says for a claimed cap; null when the cap is not claimed. */
+	effectiveIfClaimed(deviceId, cap) {
+		return this.claims.effective(deviceId, cap);
+	}
+	isSeeded(deviceId) {
+		return this.seeded.has(deviceId);
+	}
+	/**
+	* 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, index) {
+		if (this.seeded.has(deviceId)) return true;
+		if (this.seeding.has(deviceId)) return false;
+		if (index.state !== "loaded" || index.hasClaims(deviceId)) return false;
+		this.seeded.add(deviceId);
+		return true;
+	}
+	/**
+	* 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).
+	*/
+	async ensureSeeded(deviceId, settings, index) {
+		if (this.seeded.has(deviceId)) return;
+		const inFlight = this.seeding.get(deviceId);
+		if (inFlight) return inFlight;
+		if (this.seedIfIndexClears(deviceId, index)) return;
+		return this.readRowOnce(deviceId, settings);
+	}
+	/** A write-through replaces the whole row: memory must hold what the row held. */
+	async ensureRowRead(deviceId, settings) {
+		if (this.rowRead.has(deviceId)) return;
+		const inFlight = this.seeding.get(deviceId);
+		if (inFlight) return inFlight;
+		return this.readRowOnce(deviceId, settings);
+	}
+	/** 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`. */
+	async readRowOrRefuse(deviceId, settings) {
+		try {
+			await this.ensureRowRead(deviceId, settings);
+			return null;
+		} catch (err) {
+			return refused("row-unreadable", `device ${deviceId}: ${errorMessage$1(err)}`);
+		}
+	}
+	readRowOnce(deviceId, settings) {
+		const read = (async () => {
+			try {
+				const row = await settings.readDeviceRuntimeState(deviceId);
+				this.seedMirror(deviceId, this.withResetSessionProbe(row));
+				this.seedRefusalLogged.delete(deviceId);
+			} catch (err) {
+				if (!this.seedRefusalLogged.has(deviceId)) {
+					this.seedRefusalLogged.add(deviceId);
+					this.ctx.logger.warn(SEED_REFUSAL_MESSAGE, {
+						tags: { deviceId },
+						meta: { error: errorMessage$1(err) }
+					});
+				}
+				throw err;
+			} finally {
+				this.seeding.delete(deviceId);
+			}
+		})();
+		this.seeding.set(deviceId, read);
+		return read;
+	}
+	nativeOf(deviceId, capName) {
+		return this.stateMirror.get(deviceId)?.get(capName) ?? null;
+	}
+	/**
+	* 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.
+	*/
+	async writeThrough(deviceId, settings, op, rollback) {
+		let blob;
+		try {
+			blob = await this.writer.serialiseWrite(deviceId, async () => {
+				const live = this.persistableForDevice(deviceId);
+				await settings.writeDeviceRuntimeState(deviceId, live);
+				return live;
+			});
+		} catch (err) {
+			const extras = {
+				tags: { deviceId },
+				meta: {
+					cap: op.cap,
+					owner: op.owner,
+					error: errorMessage$1(err)
+				}
+			};
+			if (rollback()) {
+				this.ctx.logger.warn(`${op.op} write-through failed — ${op.op} not recorded, memory rolled back`, extras);
+				this.reemitAfterRollback(deviceId, op.cap);
+			} else {
+				this.ctx.logger.warn(`${op.op} write-through failed — a newer state of the claim stands, memory kept; the row converges through the writer`, extras);
+				this.writer.armOrHold(deviceId, settings);
+			}
+			throw err;
+		}
+		this.writer.markPersisted(deviceId, blob);
+	}
+	/** After a rollback, re-emit what is true now: the restored claim's merge, or the native. */
+	reemitAfterRollback(deviceId, capName) {
+		const claim = this.claims.claim(deviceId, capName);
+		const native = this.nativeOf(deviceId, capName);
+		if (claim) {
+			this.claims.recompute(deviceId, capName, claim, native, true);
+			return;
+		}
+		if (native) this.emitStateChanged(deviceId, capName, { ...native });
+	}
+	/** Arm the debounced writer for a change to `changedCap` — see `MirrorRowWriter.schedule`. */
+	scheduleRuntimeStateDiskWrite(deviceId, settings, changedCap) {
+		this.writer.schedule(deviceId, settings, changedCap);
+	}
+	/** Hold the writer off these rows for a migration — see `MirrorRowWriter.holdDiskWrites`. */
+	holdDiskWrites(deviceIds, settings) {
+		return this.writer.holdDiskWrites(deviceIds, settings);
+	}
+	/** Flush every pending debounced disk write (graceful shutdown). */
+	flushPendingWrites(settings) {
+		return this.writer.flushPendingWrites(settings);
+	}
+	/** The device's row as it may reach disk: NATIVE slices plus `$owned`, restricted by durability. */
+	persistableForDevice(deviceId) {
+		return persistableBlob(joinRuntimeBlob(this.nativeSnapshotForDevice(deviceId), this.claims.ownedCaps(deviceId), this.policyFor), this.policyFor);
+	}
+	/**
+	* 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, blob, mode = "fill") {
+		const split = splitRuntimeBlob(blob);
+		if (mode === "replace") {
+			this.stateMirror.delete(deviceId);
+			this.claims.clearDevice(deviceId);
+		}
+		let perCap = this.stateMirror.get(deviceId);
+		if (!perCap) {
+			perCap = /* @__PURE__ */ new Map();
+			this.stateMirror.set(deviceId, perCap);
+		}
+		for (const [capName, raw] of Object.entries(split.native)) if (!perCap.has(capName)) perCap.set(capName, { ...raw });
+		this.claims.seedClaims(deviceId, split.owned);
+		if (split.dropped.length > 0) this.ctx.logger.warn("malformed $owned entries on the runtime-state row dropped by name", {
+			tags: { deviceId },
+			meta: { caps: split.dropped }
+		});
+		for (const [capName, cap] of this.claims.claimsOf(deviceId)) this.claims.seedView(deviceId, capName, cap, this.nativeOf(deviceId, capName));
+		this.seeded.add(deviceId);
+		this.rowRead.add(deviceId);
+		this.writer.markPersisted(deviceId, persistableBlob(joinRuntimeBlob(split.native, split.owned, this.policyFor), this.policyFor));
 	}
 	/**
 	* The hub mirror's `feature-probe.lastProbedAt` is a PER-SESSION liveness
@@ -7559,26 +8825,47 @@ var DeviceStateMirror = class DeviceStateMirror {
 		if (!raw) return true;
 		return (typeof raw.lastProbedAt === "number" ? raw.lastProbedAt : 0) > 0;
 	}
+	/** 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) {
-		const perCap = this.stateMirror.get(deviceId);
-		if (!perCap) return {};
 		const out = {};
-		for (const [k, v] of perCap) out[k] = { ...v };
+		for (const [k, v] of this.stateMirror.get(deviceId) ?? []) {
+			if (this.claims.isClaimed(deviceId, k)) continue;
+			out[k] = { ...v };
+		}
+		for (const [k, v] of this.claims.visibleCaps(deviceId)) out[k] = { ...v };
 		return out;
 	}
-	/** 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, cap) {
+		const visible = this.claims.visible(deviceId, cap);
+		if (visible !== void 0) return visible ? { ...visible } : null;
 		const raw = this.stateMirror.get(deviceId)?.get(cap);
 		return raw ? { ...raw } : null;
 	}
+	/** The device's NATIVE slices — what the row stores under the cap names. */
+	nativeSnapshotForDevice(deviceId) {
+		const perCap = this.stateMirror.get(deviceId);
+		if (!perCap) return {};
+		const out = {};
+		for (const [k, v] of perCap) out[k] = { ...v };
+		return out;
+	}
 	/** Whole-system mirror dump. Backs `deviceState.getAllSnapshots` — one
 	*  round-trip for a warm boot instead of N per-device calls. */
 	allSnapshots() {
 		const out = {};
-		for (const deviceId of this.stateMirror.keys()) out[String(deviceId)] = this.snapshotForDevice(deviceId);
+		const deviceIds = new Set([...this.stateMirror.keys(), ...this.claims.deviceIds()]);
+		for (const deviceId of deviceIds) out[String(deviceId)] = this.snapshotForDevice(deviceId);
 		return out;
 	}
+	/**
+	* The PUBLIC event: exactly `{ deviceId, capName, slice }` for every device,
+	* claimed or not. The native shadow never rides here (D224) — see
+	* `emitNativeShadow`.
+	*/
 	emitStateChanged(deviceId, capName, slice) {
 		this.ctx.eventBus.emit({
 			id: randomUUID(),
@@ -7595,29 +8882,194 @@ var DeviceStateMirror = class DeviceStateMirror {
 			}
 		});
 	}
-	/** Flush every pending debounced disk write (graceful shutdown). Clears the
-	*  debounce slots after awaiting in-flight + scheduled writes so shutdown is
-	*  lossless. */
-	async flushPendingWrites(settings) {
-		const pending = [];
-		for (const [deviceId, slot] of this.runtimeStateDebounce) {
-			if (slot.timer) {
-				clearTimeout(slot.timer);
-				slot.timer = null;
-				const blob = settings ? this.persistableForDevice(deviceId) : null;
-				if (settings && blob !== null && !this.isAlreadyPersisted(deviceId, blob)) pending.push(settings.writeDeviceRuntimeState(deviceId, blob).then(() => {
-					this.lastPersisted.set(deviceId, blob);
-				}).catch((err) => {
-					this.ctx.logger.warn("shutdown writeDeviceRuntimeState failed", {
-						tags: { deviceId },
-						meta: { error: err instanceof Error ? err.message : String(err) }
-					});
-				}));
+	/**
+	* 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.
+	*/
+	emitNativeShadow(deviceId, capName, native) {
+		this.ctx.eventBus.emit({
+			id: randomUUID(),
+			timestamp: /* @__PURE__ */ new Date(),
+			source: {
+				type: "device",
+				id: deviceId
+			},
+			category: EventCategory.DeviceNativeShadowChanged,
+			data: {
+				deviceId,
+				capName,
+				native
 			}
-			if (slot.inFlight) pending.push(slot.inFlight);
+		});
+	}
+};
+//#endregion
+//#region src/builtins/device-manager/field-claims-index.ts
+/** The addon-store key the index lives under. */
+var FIELD_CLAIMS_INDEX_KEY = "field-claims-index";
+function keyOf(key) {
+	return `${key.deviceId}/${key.capName}`;
+}
+function errorMessage(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+var FieldClaimsIndex = class {
+	deps;
+	/** The loaded entries by key, or null until a load has succeeded. */
+	entries = null;
+	/** Devices with at least one entry — what the seed asks, per native write. */
+	claimedDevices = /* @__PURE__ */ new Set();
+	/** Why the last load did not succeed. */
+	notLoadedReason = "not loaded yet";
+	/** One load in flight at a time; concurrent callers join it. */
+	loading = null;
+	constructor(deps) {
+		this.deps = deps;
+	}
+	/**
+	* 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) {
+		if (this.entries !== null) return Promise.resolve(true);
+		if (this.loading) return this.loading;
+		const run = this.readBlob(settings).finally(() => {
+			this.loading = null;
+		});
+		this.loading = run;
+		return run;
+	}
+	/** What the seed consults: loaded with a device predicate, or not loaded. */
+	view() {
+		if (this.entries === null) return { state: "not-loaded" };
+		const claimed = this.claimedDevices;
+		return {
+			state: "loaded",
+			hasClaims: (deviceId) => claimed.has(deviceId)
+		};
+	}
+	/** Every entry, optionally those whose owner starts with `ownerPrefix`; or why there is no answer. */
+	list(ownerPrefix) {
+		if (this.entries === null) return {
+			state: "not-loaded",
+			reason: this.notLoadedReason
+		};
+		return {
+			state: "loaded",
+			claims: [...this.entries.values()].filter((c) => ownerPrefix === void 0 || c.owner.startsWith(ownerPrefix))
+		};
+	}
+	/** The entry for a key, when the index is loaded and has one. */
+	entry(key) {
+		return this.entries?.get(keyOf(key));
+	}
+	/** Add or replace one entry — written before the row it announces. Throws when the index cannot be loaded or written. */
+	async upsert(claim, settings) {
+		await this.mutate(settings, claim.deviceId, (current) => {
+			const next = new Map(current);
+			next.set(keyOf(claim), {
+				...claim,
+				fields: [...claim.fields]
+			});
+			return next;
+		});
+	}
+	/** Remove one entry — written after the row no longer carries the claim. No write when absent. */
+	async remove(key, settings) {
+		await this.mutate(settings, key.deviceId, (current) => {
+			if (!current.has(keyOf(key))) return null;
+			const next = new Map(current);
+			next.delete(keyOf(key));
+			return next;
+		});
+	}
+	/**
+	* 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.
+	*/
+	async pruneDevice(deviceId, settings) {
+		try {
+			await this.mutate(settings, deviceId, (current) => {
+				const kept = [...current].filter(([, c]) => c.deviceId !== deviceId);
+				return kept.length === current.size ? null : new Map(kept);
+			});
+		} catch (err) {
+			this.deps.logger.warn("claims index not pruned for a removed device — a stale entry stays until the next release", {
+				tags: { deviceId },
+				meta: { error: errorMessage(err) }
+			});
 		}
-		await Promise.all(pending);
-		this.runtimeStateDebounce.clear();
+	}
+	/**
+	* 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.
+	*/
+	async mutate(settings, deviceId, next) {
+		await this.deps.withAddonStoreWriteLock(async () => {
+			if (!await this.load(settings)) throw new Error(`claims index not loaded (${this.notLoadedReason}) — refusing to write it blind`);
+			const updated = next(this.entries ?? /* @__PURE__ */ new Map());
+			if (updated === null) return;
+			try {
+				await settings.writeAddonStore({ [FIELD_CLAIMS_INDEX_KEY]: [...updated.values()] });
+			} catch (err) {
+				this.deps.logger.warn("claims index write failed — index unchanged", {
+					tags: { deviceId },
+					meta: { error: errorMessage(err) }
+				});
+				throw err;
+			}
+			this.install(updated);
+		});
+	}
+	install(entries) {
+		this.entries = entries;
+		this.claimedDevices = new Set([...entries.values()].map((c) => c.deviceId));
+	}
+	/** The three-way read (D651): a failed read is a REASON, never an empty index. */
+	async readBlob(settings) {
+		if (settings.readAddonStoreResult === void 0) {
+			this.notLoadedReason = "this settings view predates the three-way addon-store read (D651)";
+			return false;
+		}
+		let read;
+		try {
+			read = await settings.readAddonStoreResult();
+		} catch (err) {
+			read = {
+				kind: "failed",
+				error: errorMessage(err)
+			};
+		}
+		if (read.kind === "failed") {
+			this.notLoadedReason = `addon store unreadable: ${read.error}`;
+			this.deps.logger.warn("claims index not loaded — every seed reads its row until it is", { meta: { error: read.error } });
+			return false;
+		}
+		const raw = read.kind === "value" ? read.value[FIELD_CLAIMS_INDEX_KEY] : void 0;
+		if (raw !== void 0 && !Array.isArray(raw)) return this.refuseMalformed(`claims index blob malformed: not a list (${typeof raw})`);
+		const entries = /* @__PURE__ */ new Map();
+		const dropped = [];
+		for (const [i, item] of (raw ?? []).entries()) {
+			const parsed = FieldClaimSchema.safeParse(item);
+			if (parsed.success) entries.set(keyOf(parsed.data), parsed.data);
+			else dropped.push(i);
+		}
+		if (dropped.length > 0) return this.refuseMalformed(`claims index blob malformed at positions ${dropped.join(", ")} — repair the '${FIELD_CLAIMS_INDEX_KEY}' key of the device-manager store`);
+		this.install(entries);
+		return true;
+	}
+	/** Not loaded, by name: the index stays unknown and says why. */
+	refuseMalformed(reason) {
+		this.notLoadedReason = reason;
+		this.deps.logger.warn("claims index not loaded — every seed reads its row until it is", { meta: { reason } });
+		return false;
 	}
 };
 //#endregion
@@ -7691,6 +9143,9 @@ function createMigrationGuard(now = Date.now) {
 			inFlight.delete(sourceId);
 			inFlight.delete(targetId);
 		},
+		isInFlight(deviceId) {
+			return inFlight.has(deviceId);
+		},
 		recordCompleted(record) {
 			completed.set(pairKey(record.sourceId, record.targetId), {
 				...record,
@@ -7794,6 +9249,13 @@ var DeviceManagerAddon = class extends BaseAddon {
 	*/
 	stateMirrorImpl = null;
 	/**
+	* Removes the claimed-status overlay this addon installed on the capability
+	* registry (D663, S3): `getStatus` of a claimed cap answers the mirror for
+	* every caller while it is installed. Run in `onShutdown`; `null` before
+	* init or when the kernel handed the addon no registry.
+	*/
+	uninstallStatusOverlay = null;
+	/**
 	* Cross-process native-provider cache: deviceId (numeric) → capName → { addonId, nodeId }.
 	* Kept in sync with `DeviceBindingsChanged` push events emitted by forked
 	* workers on `ctx.registerNativeCap` / device removal. Union'd into
@@ -7830,6 +9292,18 @@ var DeviceManagerAddon = class extends BaseAddon {
 		if (!this.stateMirrorImpl) throw new Error("DeviceManagerAddon: state mirror accessed before onInitialize");
 		return this.stateMirrorImpl;
 	}
+	/**
+	* The per-field claims index (D663): which devices carry a claim, for the
+	* seed and for `listClaims`. Constructed at init and loaded before the first
+	* provider method can run; a load that fails leaves it `not-loaded`, and
+	* every seed reads its row until a later call loads it.
+	*/
+	fieldClaimsImpl = null;
+	/** The claims index, asserted present (constructed in onInitialize). */
+	get fieldClaims() {
+		if (!this.fieldClaimsImpl) throw new Error("DeviceManagerAddon: claims index accessed before onInitialize");
+		return this.fieldClaimsImpl;
+	}
 	/** Build the `ProviderHost` the extracted provider-method modules
 	*  (`device-meta-actions`, `device-queries`) reach — exposes the addon's
 	*  private state/methods they need without leaking the class internals.
@@ -7838,14 +9312,20 @@ var DeviceManagerAddon = class extends BaseAddon {
 	*  reference preserves the live semantics. */
 	get providerHost() {
 		const capabilityRegistry = () => this.capabilityRegistry;
+		const fieldClaims = () => this.fieldClaims;
 		return {
 			ctx: this.ctx,
 			get capabilityRegistry() {
 				return capabilityRegistry();
 			},
 			remoteNativeCaps: this.remoteNativeCaps,
-			seedMirror: (deviceId, blob) => this.stateMirror.seedMirror(deviceId, blob),
+			seedMirror: (deviceId, blob, mode) => this.stateMirror.seedMirror(deviceId, blob, mode),
 			withResetSessionProbe: (blob) => this.stateMirror.withResetSessionProbe(blob),
+			get fieldClaims() {
+				return fieldClaims();
+			},
+			holdMirrorWrites: (deviceIds, settings) => this.stateMirror.holdDiskWrites(deviceIds, settings),
+			mirrorOwnedCaps: (deviceId) => this.stateMirror.ownedCaps(deviceId),
 			resolveDeviceOnline: (deviceId, fallbackOnline) => this.stateMirror.resolveDeviceOnline(deviceId, fallbackOnline),
 			resolveDeviceProbed: (deviceId) => this.stateMirror.resolveDeviceProbed(deviceId),
 			waitDeviceProvider: (addonId, timeoutMs) => this.waitDeviceProvider(addonId, timeoutMs),
@@ -8013,6 +9493,19 @@ var DeviceManagerAddon = class extends BaseAddon {
 		const metaStore = new DeviceMetaStore(settings, registry, deviceRows, this.addonStoreWriteLock);
 		this.stateMirrorImpl = new DeviceStateMirror(this.ctx);
 		const stateMirror = this.stateMirrorImpl;
+		this.fieldClaimsImpl = new FieldClaimsIndex({
+			logger: this.ctx.logger.child("claims-index"),
+			withAddonStoreWriteLock: this.addonStoreWriteLock
+		});
+		const fieldClaims = this.fieldClaimsImpl;
+		await fieldClaims.load(settings);
+		const registryForOverlay = this.capabilityRegistry;
+		this.uninstallStatusOverlay = registryForOverlay !== void 0 ? installClaimedStatusOverlay(registryForOverlay, {
+			mirror: stateMirror,
+			claimsIndex: () => fieldClaims.view(),
+			settings: () => settings,
+			logger: this.ctx.logger.child("claimed-status")
+		}) : null;
 		const resolvePersistedById = metaStore.resolvePersistedById;
 		const idToAddonId = metaStore.idToAddonId;
 		const bootRows = await deviceRows.listAll();
@@ -8225,6 +9718,34 @@ var DeviceManagerAddon = class extends BaseAddon {
 			this.propagator.start();
 			this.ctx.logger.info("device-event-propagator started");
 		}
+		const deviceStateProvider = {
+			getSnapshot: async (input) => {
+				return stateMirror.snapshotForDevice(input.deviceId);
+			},
+			getCapSlice: async (input) => {
+				return stateMirror.capSlice(input.deviceId, input.capName);
+			},
+			getNativeCapSlice: async (input) => {
+				return stateMirror.nativeSlice(input.deviceId, input.capName);
+			},
+			getAllSnapshots: async () => {
+				return stateMirror.allSnapshots();
+			},
+			setCapSlice: async (input) => {
+				const { deviceId, capName, slice } = input;
+				if (!await resolvePersistedById(deviceId)) throw new Error(`[device-manager] setCapSlice: unknown device id=${deviceId}`);
+				if (!stateMirror.isSeeded(deviceId)) await stateMirror.ensureSeeded(deviceId, settings, fieldClaims.view());
+				if (stateMirror.applySingleCapUpdate(deviceId, capName, slice)) stateMirror.scheduleRuntimeStateDiskWrite(deviceId, settings, capName);
+			},
+			...createDeviceStateClaimMethods({
+				mirror: stateMirror,
+				index: fieldClaims,
+				settings,
+				logger: this.ctx.logger.child("claims"),
+				deviceExists: async (deviceId) => await resolvePersistedById(deviceId) !== null,
+				migrationInFlight: (deviceId) => pctx.migrationGuard.isInFlight(deviceId)
+			})
+		};
 		return [
 			{
 				capability: deviceManagerCapability,
@@ -8232,22 +9753,7 @@ var DeviceManagerAddon = class extends BaseAddon {
 			},
 			{
 				capability: deviceStateCapability,
-				provider: {
-					getSnapshot: async (input) => {
-						return stateMirror.snapshotForDevice(input.deviceId);
-					},
-					getCapSlice: async (input) => {
-						return stateMirror.capSlice(input.deviceId, input.capName);
-					},
-					getAllSnapshots: async () => {
-						return stateMirror.allSnapshots();
-					},
-					setCapSlice: async (input) => {
-						const { deviceId, capName, slice } = input;
-						if (!await resolvePersistedById(deviceId)) throw new Error(`[device-manager] setCapSlice: unknown device id=${deviceId}`);
-						if (stateMirror.applySingleCapUpdate(deviceId, capName, slice)) stateMirror.scheduleRuntimeStateDiskWrite(deviceId, settings, capName);
-					}
-				}
+				provider: deviceStateProvider
 			},
 			{
 				capability: deviceExtensionCapability,
@@ -8258,6 +9764,8 @@ var DeviceManagerAddon = class extends BaseAddon {
 	async onShutdown() {
 		this.propagator?.stop();
 		this.propagator = null;
+		this.uninstallStatusOverlay?.();
+		this.uninstallStatusOverlay = null;
 		await this.stateMirrorImpl?.flushPendingWrites(this.ctx.settings);
 	}
 };