@camstack/system 1.2.316 → 1.2.318

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

@@ -1,5 +1,5 @@
-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-BPvku43i.mjs";
-import { n as purgeRetiredSettingsRows } from "../../retired-settings-keys-DqVWSrVw.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-CQ9vXSUh.mjs";
+import { n as purgeRetiredSettingsRows } from "../../retired-settings-keys-DNIbyfTR.mjs";
 import { z } from "zod";
 import { randomUUID } from "node:crypto";
 import { canonicalDeviceFingerprint } from "@camstack/types/node";
@@ -4136,6 +4136,73 @@ async function setWrapperActive(deps, input) {
 		}
 	});
 }
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** The key of this addon's store that holds every wrapper activation. */
+var DEVICE_BINDINGS_KEY = "deviceBindings";
+/**
+* The STORED activation for one `(device, capName)` pair, three-way — the
+* provider behind `deviceManager.getWrapperActivation` (D675).
+*
+* Reads ONE row — this addon's `deviceBindings` key (~1.6 KB live) — through
+* the settings view's single-key three-way read, never the addon's whole store
+* (~625 KB) and never `readAddonStore()`, which folds a failed read into `{}`.
+*
+* Absence is graded by LEVEL:
+* - STORE level — the read failed, or the `deviceBindings` row does not exist,
+*   or it is not a map — is `failed`. Every hub that has ever bound anything
+*   holds that row, so its absence is the signature of a store answering from
+*   an empty or unready snapshot (D44), and it must never silence a press
+*   (D49). An install that has never bound anything lands here too; erring
+*   `failed` there costs nothing, because nothing is bound to silence.
+* - PAIR level — the row was read and has no entry for this device, or none
+*   for this cap, or none with `wrapperAddonId` — is `missing`: the operator
+*   never touched this pair.
+*/
+async function readWrapperActivation(deps, query) {
+	const settings = deps.ctx.settings;
+	if (settings?.readAddonStoreKeyResult === void 0) return {
+		kind: "failed",
+		error: "this settings view has no single-key three-way read"
+	};
+	const read = await settings.readAddonStoreKeyResult(DEVICE_BINDINGS_KEY);
+	if (read.kind === "unreadable") return {
+		kind: "failed",
+		error: read.error ?? read.reason
+	};
+	if (read.kind === "absent") return {
+		kind: "failed",
+		error: "the store holds no deviceBindings row — an empty snapshot is not evidence of an unbind"
+	};
+	const deviceBindings = read.value;
+	if (!isRecord(deviceBindings)) return {
+		kind: "failed",
+		error: "stored deviceBindings is not a map"
+	};
+	const perDevice = deviceBindings[String(query.deviceId)];
+	if (perDevice === void 0) return { kind: "missing" };
+	if (!isRecord(perDevice)) return {
+		kind: "failed",
+		error: `stored bindings of device ${query.deviceId} are not a map`
+	};
+	const activation = perDevice[query.capName];
+	if (activation === void 0) return { kind: "missing" };
+	if (!isRecord(activation)) return {
+		kind: "failed",
+		error: `stored "${query.capName}" activation is not a record`
+	};
+	const wrapperAddonId = activation["wrapperAddonId"];
+	if (wrapperAddonId === void 0) return { kind: "missing" };
+	if (wrapperAddonId === null || typeof wrapperAddonId === "string") return {
+		kind: "value",
+		wrapperAddonId
+	};
+	return {
+		kind: "failed",
+		error: `stored "${query.capName}" wrapperAddonId is not a string`
+	};
+}
 //#endregion
 //#region src/builtins/device-manager/device-event-propagator.ts
 /**
@@ -5540,6 +5607,7 @@ async function removeDevice(pctx, input) {
 		});
 	});
 	await pctx.settings.clearDeviceStore(deviceId);
+	await pctx.host.forgetMirrorDevice(deviceId);
 	await pctx.settings.clearDeviceRuntimeState(deviceId);
 	await pctx.host.fieldClaims.pruneDevice(deviceId, pctx.settings);
 	const bindingKey = String(deviceId);
@@ -8061,6 +8129,20 @@ function deepEqual(a, b) {
 }
 //#endregion
 //#region src/builtins/device-manager/mirror-row-writer.ts
+/**
+* A write-through refused because the device's row could not be read first
+* (D677). Nothing was written; the caller rolls its memory change back.
+*/
+var RuntimeStateRowUnreadError = class extends Error {
+	deviceId;
+	constructor(deviceId) {
+		super(`runtime-state row of device ${deviceId} could not be read — nothing written, a row this process has not read is never replaced (D677)`);
+		this.deviceId = deviceId;
+		this.name = "RuntimeStateRowUnreadError";
+	}
+};
+var ROW_UNREAD_REFUSAL_MESSAGE = "runtime-state row write refused — the row could not be read first, nothing written (D677)";
+var ROW_DROPS_CAPS_MESSAGE = "runtime-state row write DROPS caps the stored row holds (D677)";
 function errorMessage$2(err) {
 	return err instanceof Error ? err.message : String(err);
 }
@@ -8080,6 +8162,13 @@ var RuntimeStateDrainError = class extends MigrationRefusedError {
 var MirrorRowWriter = class MirrorRowWriter {
 	deps;
 	static RUNTIME_STATE_DEBOUNCE_MS = 1e3;
+	/** Ceiling of the re-arm backoff while a device's row cannot be read (D677, D3). */
+	static UNREAD_REARM_MAX_MS = 6e4;
+	/** The re-arm delay after `refusals` consecutive unread refusals: 1 s, 2 s, 4 s … capped at 60 s. */
+	static unreadRearmDelayMs(refusals) {
+		const exponent = Math.max(0, refusals - 1);
+		return Math.min(MirrorRowWriter.RUNTIME_STATE_DEBOUNCE_MS * 2 ** exponent, MirrorRowWriter.UNREAD_REARM_MAX_MS);
+	}
 	/**
 	* Per-device disk-write debouncer for runtime-state. `setCapSlice`
 	* updates the in-memory mirror synchronously and emits the change
@@ -8108,6 +8197,8 @@ var MirrorRowWriter = class MirrorRowWriter {
 	* that drops work silently reads as "never happened".
 	*/
 	skippedSinceWrite = /* @__PURE__ */ new Map();
+	/** Devices whose unreadable-row refusal is already logged — once per episode. */
+	rowUnreadLogged = /* @__PURE__ */ new Set();
 	constructor(deps) {
 		this.deps = deps;
 	}
@@ -8144,7 +8235,8 @@ var MirrorRowWriter = class MirrorRowWriter {
 			slot = {
 				timer: null,
 				inFlight: null,
-				lastWriteFailed: false
+				lastWriteFailed: false,
+				unreadRefusals: 0
 			};
 			this.runtimeStateDebounce.set(deviceId, slot);
 		}
@@ -8179,23 +8271,116 @@ var MirrorRowWriter = class MirrorRowWriter {
 		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) {
+	armDiskWrite(deviceId, settings, delayMs = MirrorRowWriter.RUNTIME_STATE_DEBOUNCE_MS) {
 		const slot = this.slotFor(deviceId);
 		if (slot.timer) return;
 		slot.timer = setTimeout(() => {
 			slot.timer = null;
-			this.serialiseWrite(deviceId, () => this.writeLiveBlob(deviceId, settings, slot));
-		}, MirrorRowWriter.RUNTIME_STATE_DEBOUNCE_MS);
+			this.serialiseWrite(deviceId, () => this.writeLiveBlob(deviceId, settings, slot, "debounced"));
+		}, delayMs);
+	}
+	/**
+	* Forget a removed device: cancel its armed write, await one in flight, and
+	* drop its baseline and counters — nothing writes its row after this.
+	*/
+	async forget(deviceId) {
+		const slot = this.runtimeStateDebounce.get(deviceId);
+		if (slot?.timer) {
+			clearTimeout(slot.timer);
+			slot.timer = null;
+		}
+		if (slot?.inFlight) await slot.inFlight;
+		this.runtimeStateDebounce.delete(deviceId);
+		this.lastPersisted.delete(deviceId);
+		this.skippedSinceWrite.delete(deviceId);
+		this.rowUnreadLogged.delete(deviceId);
+		this.heldDirty.delete(deviceId);
+	}
+	/**
+	* The row is in memory, or is read now (D677). False when the read failed:
+	* the caller writes nothing. Logged once per episode, tagged; the episode
+	* ends at the next successful read.
+	*/
+	async rowReadOrRefuse(deviceId, settings, path) {
+		if (!this.deps.isRowRead(deviceId)) try {
+			await this.deps.readRowFirst(deviceId, settings);
+		} catch (err) {
+			if (!this.rowUnreadLogged.has(deviceId)) {
+				this.rowUnreadLogged.add(deviceId);
+				this.deps.logger.warn(ROW_UNREAD_REFUSAL_MESSAGE, {
+					tags: { deviceId },
+					meta: {
+						path,
+						error: errorMessage$2(err)
+					}
+				});
+			}
+			return false;
+		}
+		this.rowUnreadLogged.delete(deviceId);
+		return true;
 	}
-	/** The debounced write itself: the blob as memory holds it NOW, behind the effective-change gate. Never rejects. */
-	async writeLiveBlob(deviceId, settings, slot) {
+	/**
+	* The ONE call of `writeDeviceRuntimeState`. A blob that lacks a cap the
+	* stored row holds is written (memory is the authority once the row was
+	* read) but never silently: the dropped caps are named at warn (D677).
+	* `$owned` is excluded — a release that empties it is the claim path's own
+	* logged business.
+	*/
+	async writeRow(deviceId, settings, blob, path) {
+		const onDisk = this.lastPersisted.get(deviceId);
+		if (onDisk) {
+			const dropped = Object.keys(onDisk).filter((cap) => cap !== "$owned" && !Object.hasOwn(blob, cap));
+			if (dropped.length > 0) this.deps.logger.warn(ROW_DROPS_CAPS_MESSAGE, {
+				tags: { deviceId },
+				meta: {
+					path,
+					dropped,
+					storedCaps: Object.keys(onDisk).length,
+					writtenCaps: Object.keys(blob).length
+				}
+			});
+		}
+		await settings.writeDeviceRuntimeState(deviceId, blob);
+		this.lastPersisted.set(deviceId, blob);
+	}
+	/**
+	* A claim's write-through (D663): queued behind the device's writes, the row
+	* read first, the blob taken when it runs. Rejects with
+	* {@link RuntimeStateRowUnreadError} when the row cannot be read, or with the
+	* write's own error; resolves to what landed.
+	*/
+	writeThroughRow(deviceId, settings, path) {
+		return this.serialiseWrite(deviceId, async () => {
+			if (!await this.rowReadOrRefuse(deviceId, settings, path)) throw new RuntimeStateRowUnreadError(deviceId);
+			const live = this.deps.persistableFor(deviceId);
+			await this.writeRow(deviceId, settings, live, path);
+			return live;
+		});
+	}
+	/**
+	* The debounced write itself: the row read first (D677), then the blob as
+	* memory holds it NOW, behind the effective-change gate. Never rejects. An
+	* unreadable row writes nothing; the debounced path re-arms with a backoff
+	* (1 s doubling to 60 s — never a 1 Hz loop, D3), and the armed timer is
+	* what a migration drain sees as owed, so a row that has become readable
+	* drains normally. The shutdown flush does not re-arm.
+	*/
+	async writeLiveBlob(deviceId, settings, slot, path) {
+		if (!await this.rowReadOrRefuse(deviceId, settings, path)) {
+			if (path === "debounced") {
+				slot.unreadRefusals += 1;
+				this.rearmAfterUnread(deviceId, settings, slot);
+			}
+			return;
+		}
+		slot.unreadRefusals = 0;
 		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);
+			await this.writeRow(deviceId, settings, blob, path);
 			slot.lastWriteFailed = false;
 			if (skipped > 0) this.deps.logger.debug("runtime state persisted", {
 				tags: { deviceId },
@@ -8212,6 +8397,14 @@ var MirrorRowWriter = class MirrorRowWriter {
 			});
 		}
 	}
+	/** Re-arm an unread refusal with its backoff, or remember it for `release` while held. */
+	rearmAfterUnread(deviceId, settings, slot) {
+		if (this.writesHeld.has(deviceId)) {
+			this.heldDirty.add(deviceId);
+			return;
+		}
+		this.armDiskWrite(deviceId, settings, MirrorRowWriter.unreadRearmDelayMs(slot.unreadRefusals));
+	}
 	/**
 	* 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
@@ -8265,6 +8458,7 @@ var MirrorRowWriter = class MirrorRowWriter {
 		if (slot?.inFlight) await slot.inFlight;
 		const lastFailed = slot?.lastWriteFailed ?? false;
 		if (!pending && !lastFailed) return;
+		if (!await this.rowReadOrRefuse(deviceId, settings, "drain")) this.refuseDrain(deviceId, "its runtime-state row could not be read first", null);
 		const blob = this.deps.persistableFor(deviceId);
 		if (this.isAlreadyPersisted(deviceId, blob)) {
 			if (slot) slot.lastWriteFailed = false;
@@ -8272,11 +8466,10 @@ var MirrorRowWriter = class MirrorRowWriter {
 		}
 		if (lastFailed) this.refuseDrain(deviceId, "its last runtime-state write did not land", null);
 		try {
-			await this.serialiseWrite(deviceId, () => settings.writeDeviceRuntimeState(deviceId, blob));
+			await this.serialiseWrite(deviceId, () => this.writeRow(deviceId, settings, blob, "drain"));
 		} 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) {
@@ -8309,7 +8502,7 @@ var MirrorRowWriter = class MirrorRowWriter {
 				clearTimeout(slot.timer);
 				slot.timer = null;
 				if (settings) {
-					pending.push(this.serialiseWrite(deviceId, () => this.writeLiveBlob(deviceId, settings, slot)));
+					pending.push(this.serialiseWrite(deviceId, () => this.writeLiveBlob(deviceId, settings, slot, "shutdown-flush")));
 					continue;
 				}
 			}
@@ -8366,9 +8559,18 @@ var DeviceStateMirror = class {
 	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). */
+	/**
+	* Devices whose CLAIMS are known: the row was read, or a loaded claims index
+	* vouched that it names none (D447). This is a READ-path fact — what a
+	* status read may answer from. It never licenses a row write (D677).
+	*/
 	seeded = /* @__PURE__ */ new Set();
-	/** Devices whose row was actually READ into memory — a write-through needs this. */
+	/**
+	* Devices whose row was actually READ into memory in THIS process. Every row
+	* write of a device requires it (D677): the write replaces the whole row, so
+	* memory must hold what the row held — an index that vouches for the claims
+	* says nothing about the native slices beside them.
+	*/
 	rowRead = /* @__PURE__ */ new Set();
 	/** One row read per device, however many writes arrive during it. */
 	seeding = /* @__PURE__ */ new Map();
@@ -8387,7 +8589,9 @@ var DeviceStateMirror = class {
 		this.writer = new MirrorRowWriter({
 			logger: ctx.logger,
 			policyFor,
-			persistableFor: (deviceId) => this.persistableForDevice(deviceId)
+			persistableFor: (deviceId) => this.persistableForDevice(deviceId),
+			isRowRead: (deviceId) => this.rowRead.has(deviceId),
+			readRowFirst: (deviceId, settings) => this.ensureRowRead(deviceId, settings)
 		});
 	}
 	/**
@@ -8587,8 +8791,28 @@ var DeviceStateMirror = class {
 		return this.seeded.has(deviceId);
 	}
 	/**
+	* Forget a removed device (D677): its armed row write is cancelled and one
+	* in flight awaited BEFORE its memory goes, so nothing writes its row back
+	* after `removeDevice` clears it.
+	*/
+	async forgetDevice(deviceId) {
+		await this.seeding.get(deviceId)?.catch(() => void 0);
+		await this.writer.forget(deviceId);
+		this.stateMirror.delete(deviceId);
+		this.claims.clearDevice(deviceId);
+		this.seeded.delete(deviceId);
+		this.rowRead.delete(deviceId);
+		this.seedRefusalLogged.delete(deviceId);
+	}
+	/** The device's row was read in this process — the precondition of every row write (D677). */
+	isRowRead(deviceId) {
+		return this.rowRead.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.
+	* index that does not name the device vouches for its CLAIMS — seeded, no
+	* read. That is all it vouches for: the device is still not `rowRead`, and
+	* the writer reads the row before its first write (D677).
 	* 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
@@ -8603,14 +8827,21 @@ var DeviceStateMirror = class {
 		return true;
 	}
 	/**
-	* Make sure the device's claims are known before a native write is applied
-	* (D49). Index first, single-flight (ruling S6):
+	* Make sure the device's CLAIMS are known before a status read is answered
+	* or a native slice 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).
+	* A read that throws propagates and is logged once per device transition
+	* (D391).
+	*
+	* Also the native-write RPC's gate: a slice may be APPLIED once its claims
+	* are known. Never the ROW write's: branch (c) knows the claims and nothing
+	* about the native slices on the row; a writer that trusted it replaced a
+	* row it never read with the one slice it held, and every restored cap
+	* nobody re-wrote soon after boot was erased (D677, superseding S6(c) for
+	* writes). The writer calls {@link ensureRowRead}.
 	*/
 	async ensureSeeded(deviceId, settings, index) {
 		if (this.seeded.has(deviceId)) return;
@@ -8619,7 +8850,13 @@ var DeviceStateMirror = class {
 		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. */
+	/**
+	* A row write replaces the whole row: memory must hold what the row held
+	* (D677). Reads the row once, single-flight, and fills memory's gaps from it
+	* (`seedMirror('fill')`: a slice memory already holds is newer and wins).
+	* A read that throws propagates — nothing is written — and is logged once
+	* per device transition (D49, D391).
+	*/
 	async ensureRowRead(deviceId, settings) {
 		if (this.rowRead.has(deviceId)) return;
 		const inFlight = this.seeding.get(deviceId);
@@ -8673,13 +8910,8 @@ var DeviceStateMirror = class {
 	* `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;
-			});
+			await this.writer.writeThroughRow(deviceId, settings, op.op);
 		} catch (err) {
 			const extras = {
 				tags: { deviceId },
@@ -8698,7 +8930,6 @@ var DeviceStateMirror = class {
 			}
 			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) {
@@ -9326,6 +9557,7 @@ var DeviceManagerAddon = class extends BaseAddon {
 			},
 			holdMirrorWrites: (deviceIds, settings) => this.stateMirror.holdDiskWrites(deviceIds, settings),
 			mirrorOwnedCaps: (deviceId) => this.stateMirror.ownedCaps(deviceId),
+			forgetMirrorDevice: (deviceId) => this.stateMirror.forgetDevice(deviceId),
 			resolveDeviceOnline: (deviceId, fallbackOnline) => this.stateMirror.resolveDeviceOnline(deviceId, fallbackOnline),
 			resolveDeviceProbed: (deviceId) => this.stateMirror.resolveDeviceProbed(deviceId),
 			waitDeviceProvider: (addonId, timeoutMs) => this.waitDeviceProvider(addonId, timeoutMs),
@@ -9668,6 +9900,10 @@ var DeviceManagerAddon = class extends BaseAddon {
 					active: input.active
 				});
 			},
+			getWrapperActivation: (input) => readWrapperActivation(this.wrapperActivationDeps, {
+				deviceId: input.deviceId,
+				capName: input.capName
+			}),
 			listWrappersForCap: async (input) => this.listWrappersForCap(input),
 			listBindableCapsForDeviceType: async (input) => this.listBindableCapsForDeviceType(input),
 			getDeviceSettingsAggregate: async (input) => {

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

@@ -40,6 +40,12 @@ export interface ProviderHost {
      * write-through may not have landed yet. A migration's second look (D663).
      */
     mirrorOwnedCaps(deviceId: number): OwnedCaps;
+    /**
+     * Forget a REMOVED device in the mirror: cancel its armed row write, await
+     * one in flight, drop its slices, claims and baseline (D677). Called before
+     * the row is cleared, so no write lands an orphan row after it.
+     */
+    forgetMirrorDevice(deviceId: number): Promise<void>;
     /** Reset a stale per-session `feature-probe` timestamp before mirror seeding. */
     withResetSessionProbe(blob: Record<string, unknown>): Record<string, unknown>;
     /** The per-field claims index (D663) — `removeDevice` prunes a removed device from it. */

package/dist/builtins/device-manager/device-source-activation.d.ts

@@ -1,4 +1,4 @@
-import { AddonContext, ICapabilityRegistry } from '@camstack/types';
+import { AddonContext, ICapabilityRegistry, WrapperActivationRead } from '@camstack/types';
 import { WriteLock } from './write-lock.js';
 /**
  * What a wrapper-activation write needs, and nothing more.
@@ -34,3 +34,28 @@ export interface WrapperActivationInput {
  * this module shipped until 2026-09-20.
  */
 export declare function setWrapperActive(deps: WrapperActivationDeps, input: WrapperActivationInput): Promise<void>;
+/** Which activation `getWrapperActivation` is asked about. */
+export interface WrapperActivationQuery {
+    readonly deviceId: number;
+    readonly capName: string;
+}
+/**
+ * The STORED activation for one `(device, capName)` pair, three-way — the
+ * provider behind `deviceManager.getWrapperActivation` (D675).
+ *
+ * Reads ONE row — this addon's `deviceBindings` key (~1.6 KB live) — through
+ * the settings view's single-key three-way read, never the addon's whole store
+ * (~625 KB) and never `readAddonStore()`, which folds a failed read into `{}`.
+ *
+ * Absence is graded by LEVEL:
+ * - STORE level — the read failed, or the `deviceBindings` row does not exist,
+ *   or it is not a map — is `failed`. Every hub that has ever bound anything
+ *   holds that row, so its absence is the signature of a store answering from
+ *   an empty or unready snapshot (D44), and it must never silence a press
+ *   (D49). An install that has never bound anything lands here too; erring
+ *   `failed` there costs nothing, because nothing is bound to silence.
+ * - PAIR level — the row was read and has no entry for this device, or none
+ *   for this cap, or none with `wrapperAddonId` — is `missing`: the operator
+ *   never touched this pair.
+ */
+export declare function readWrapperActivation(deps: Pick<WrapperActivationDeps, 'ctx'>, query: WrapperActivationQuery): Promise<WrapperActivationRead>;

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

@@ -39,9 +39,18 @@ export declare class DeviceStateMirror {
     private readonly stateMirror;
     /** The claims and the merged view of every claimed cap (D663). */
     private readonly claims;
-    /** Devices whose row has been consulted (or ruled empty by the index). */
+    /**
+     * Devices whose CLAIMS are known: the row was read, or a loaded claims index
+     * vouched that it names none (D447). This is a READ-path fact — what a
+     * status read may answer from. It never licenses a row write (D677).
+     */
     private readonly seeded;
-    /** Devices whose row was actually READ into memory — a write-through needs this. */
+    /**
+     * Devices whose row was actually READ into memory in THIS process. Every row
+     * write of a device requires it (D677): the write replaces the whole row, so
+     * memory must hold what the row held — an index that vouches for the claims
+     * says nothing about the native slices beside them.
+     */
     private readonly rowRead;
     /** One row read per device, however many writes arrive during it. */
     private readonly seeding;
@@ -103,9 +112,19 @@ export declare class DeviceStateMirror {
     /** What the merge says for a claimed cap; null when the cap is not claimed. */
     effectiveIfClaimed(deviceId: number, cap: string): MergedSlice | null;
     isSeeded(deviceId: number): boolean;
+    /**
+     * Forget a removed device (D677): its armed row write is cancelled and one
+     * in flight awaited BEFORE its memory goes, so nothing writes its row back
+     * after `removeDevice` clears it.
+     */
+    forgetDevice(deviceId: number): Promise<void>;
+    /** The device's row was read in this process — the precondition of every row write (D677). */
+    isRowRead(deviceId: number): boolean;
     /**
      * The SYNCHRONOUS half of {@link ensureSeeded}, branch (c): a LOADED claims
-     * index that does not name the device vouches for it — seeded, no read.
+     * index that does not name the device vouches for its CLAIMS — seeded, no
+     * read. That is all it vouches for: the device is still not `rowRead`, and
+     * the writer reads the row before its first write (D677).
      * 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
@@ -114,18 +133,31 @@ export declare class DeviceStateMirror {
      */
     seedIfIndexClears(deviceId: number, index: ClaimsIndexView): boolean;
     /**
-     * Make sure the device's claims are known before a native write is applied
-     * (D49). Index first, single-flight (ruling S6):
+     * Make sure the device's CLAIMS are known before a status read is answered
+     * or a native slice 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).
+     * A read that throws propagates and is logged once per device transition
+     * (D391).
+     *
+     * Also the native-write RPC's gate: a slice may be APPLIED once its claims
+     * are known. Never the ROW write's: branch (c) knows the claims and nothing
+     * about the native slices on the row; a writer that trusted it replaced a
+     * row it never read with the one slice it held, and every restored cap
+     * nobody re-wrote soon after boot was erased (D677, superseding S6(c) for
+     * writes). The writer calls {@link ensureRowRead}.
      */
     ensureSeeded(deviceId: number, settings: DeviceManagerSettings, index: ClaimsIndexView): Promise<void>;
-    /** A write-through replaces the whole row: memory must hold what the row held. */
-    private ensureRowRead;
+    /**
+     * A row write replaces the whole row: memory must hold what the row held
+     * (D677). Reads the row once, single-flight, and fills memory's gaps from it
+     * (`seedMirror('fill')`: a slice memory already holds is newer and wins).
+     * A read that throws propagates — nothing is written — and is logged once
+     * per device transition (D49, D391).
+     */
+    ensureRowRead(deviceId: number, settings: DeviceManagerSettings): Promise<void>;
     /** An unreadable row is a NAMED refusal (D49): the answer is unknown — a
      *  throw could be read as "gone", `not-claimed` as "never was". Logged by `readRowOnce`. */
     private readRowOrRefuse;