@camstack/system 1.2.316 → 1.2.317

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

@@ -3,8 +3,8 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 require("../../chunk-Cek0wNdY.js");
-const require_dist = require("../../dist-RAl10EfG.js");
-const require_retired_settings_keys = require("../../retired-settings-keys-D3rGTGq5.js");
+const require_dist = require("../../dist-a6p0V-IL.js");
+const require_retired_settings_keys = require("../../retired-settings-keys-DC1uHWPZ.js");
 let zod = require("zod");
 let node_crypto = require("node:crypto");
 let _camstack_types_node = require("@camstack/types/node");
@@ -4141,6 +4141,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
 /**
@@ -5545,6 +5612,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);
@@ -8066,6 +8134,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);
 }
@@ -8085,6 +8167,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
@@ -8113,6 +8202,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;
 	}
@@ -8149,7 +8240,8 @@ var MirrorRowWriter = class MirrorRowWriter {
 			slot = {
 				timer: null,
 				inFlight: null,
-				lastWriteFailed: false
+				lastWriteFailed: false,
+				unreadRefusals: 0
 			};
 			this.runtimeStateDebounce.set(deviceId, slot);
 		}
@@ -8184,23 +8276,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 },
@@ -8217,6 +8402,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
@@ -8270,6 +8463,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;
@@ -8277,11 +8471,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) {
@@ -8314,7 +8507,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;
 				}
 			}
@@ -8371,9 +8564,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();
@@ -8392,7 +8594,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)
 		});
 	}
 	/**
@@ -8592,8 +8796,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
@@ -8608,14 +8832,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;
@@ -8624,7 +8855,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);
@@ -8678,13 +8915,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 },
@@ -8703,7 +8935,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) {
@@ -9331,6 +9562,7 @@ var DeviceManagerAddon = class extends require_dist.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),
@@ -9673,6 +9905,10 @@ var DeviceManagerAddon = class extends require_dist.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) => {