@camstack/types 1.2.331 → 1.2.333

package/dist/{sleep-DujUvOcb.mjs → sleep-r3RWkGVx.mjs}

@@ -162,7 +162,7 @@ function collectKeychainStoredKeys(schema) {
 	return keys;
 }
 function walkKeychainField(field, out) {
-	if (!isRecord$2(field)) return;
+	if (!isRecord$3(field)) return;
 	const type = field["type"];
 	const key = field["key"];
 	const isSecret = type === "password" || field["secret"] === true;
@@ -187,21 +187,21 @@ function schemaDeclaresAnyField(schema) {
 	for (const section of sectionsOf(schema)) if (fieldsOf(section).length > 0) return true;
 	return false;
 }
-function isRecord$2(value) {
+function isRecord$3(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function sectionsOf(schema) {
-	if (!isRecord$2(schema)) return [];
+	if (!isRecord$3(schema)) return [];
 	const sections = schema["sections"];
 	return Array.isArray(sections) ? sections : [];
 }
 function fieldsOf(node) {
-	if (!isRecord$2(node)) return [];
+	if (!isRecord$3(node)) return [];
 	const fields = node["fields"];
 	return Array.isArray(fields) ? fields : [];
 }
 function walkField(field, out) {
-	if (!isRecord$2(field)) return;
+	if (!isRecord$3(field)) return;
 	const type = field["type"];
 	const key = field["key"];
 	if ((type === "password" || field["secret"] === true) && typeof key === "string" && key.length > 0) out.add(key);
@@ -241,7 +241,7 @@ function walkField(field, out) {
 var SECRET_CLEAR = { $secretClear: true };
 /** The `'***'` token D634 redaction writes for non-admins. */
 var LEGACY_DEVICE_REDACTION = "***";
-function isRecord$1(value) {
+function isRecord$2(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function makeSecretMarker(ref) {
@@ -252,19 +252,19 @@ function makeSecretMarker(ref) {
 }
 /** A stored marker: an object whose `$secret` is a non-empty string. */
 function isSecretMarker(value) {
-	if (!isRecord$1(value)) return false;
+	if (!isRecord$2(value)) return false;
 	const ref = value["$secret"];
 	return typeof ref === "string" && ref.length > 0;
 }
 /** Anything carrying a `$secret` key — a stored marker or a UI view of one. */
 function isSecretMarkerLike(value) {
-	return isRecord$1(value) && Object.prototype.hasOwnProperty.call(value, "$secret");
+	return isRecord$2(value) && Object.prototype.hasOwnProperty.call(value, "$secret");
 }
 function isSecretClear(value) {
-	return isRecord$1(value) && value["$secretClear"] === true;
+	return isRecord$2(value) && value["$secretClear"] === true;
 }
 function isSecretFieldView(value) {
-	return isRecord$1(value) && value["set"] === true && isSecretMarkerLike(value);
+	return isRecord$2(value) && value["set"] === true && isSecretMarkerLike(value);
 }
 /**
 * The UI view of a stored secret field value: a marker becomes "set", inline
@@ -1018,7 +1018,7 @@ var KeychainWriteRefusedError = class extends Error {
 	}
 };
 var KEEP = { kind: "keep" };
-function isRecord(value) {
+function isRecord$1(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function defaultMintId() {
@@ -1031,7 +1031,7 @@ function collectSecretMarkerRefs(value, out = []) {
 		return out;
 	}
 	if (Array.isArray(value)) for (const item of value) collectSecretMarkerRefs(item, out);
-	else if (isRecord(value)) for (const child of Object.values(value)) collectSecretMarkerRefs(child, out);
+	else if (isRecord$1(value)) for (const child of Object.values(value)) collectSecretMarkerRefs(child, out);
 	return out;
 }
 async function storedValueEquals(secrets, marker, candidate) {
@@ -1086,7 +1086,7 @@ function rowId(row, idKey) {
 	return null;
 }
 async function writeArray(ctx, node, incoming, stored, fieldPath) {
-	const storedRows = Array.isArray(stored) ? stored.filter(isRecord) : [];
+	const storedRows = Array.isArray(stored) ? stored.filter(isRecord$1) : [];
 	if (!Array.isArray(incoming)) {
 		ctx.deletes.push(...collectSecretMarkerRefs(storedRows));
 		return {
@@ -1102,7 +1102,7 @@ async function writeArray(ctx, node, incoming, stored, fieldPath) {
 	const kept = /* @__PURE__ */ new Set();
 	const rows = [];
 	for (const row of incoming) {
-		if (!isRecord(row)) {
+		if (!isRecord$1(row)) {
 			rows.push(row);
 			continue;
 		}
@@ -1127,7 +1127,7 @@ async function writeNode(ctx, node, incoming, stored, fieldPath) {
 		case "leaf": return writeLeaf(ctx, incoming, stored, fieldPath);
 		case "array": return writeArray(ctx, node, incoming, stored, fieldPath);
 		case "object": {
-			if (!isRecord(incoming)) {
+			if (!isRecord$1(incoming)) {
 				if (incoming === void 0) return KEEP;
 				ctx.deletes.push(...collectSecretMarkerRefs(stored));
 				return {
@@ -1135,7 +1135,7 @@ async function writeNode(ctx, node, incoming, stored, fieldPath) {
 					value: incoming
 				};
 			}
-			const storedObj = isRecord(stored) ? stored : {};
+			const storedObj = isRecord$1(stored) ? stored : {};
 			return {
 				kind: "value",
 				value: await writeMembers(ctx, node.children, incoming, storedObj, (m) => `${fieldPath}.${m}`)
@@ -1194,12 +1194,19 @@ async function transformSecretWrite(input) {
 		}
 	};
 }
+/** Is `ref` one of `owner`'s refs? */
+function isSecretRefOwnedBy(ref, owner) {
+	return parseSecretRef(ref)?.owner === owner;
+}
 /**
 * Replace every marker in `value` with its keychain value. Returns the SAME
 * reference when there is no marker (no allocation, no keychain call).
 */
-async function resolveSecretMarkers(value, secrets) {
-	const refs = collectSecretMarkerRefs(value);
+async function resolveSecretMarkers(value, secrets, options = {}) {
+	const keepMarker = options.unresolved === "keep-marker";
+	const owner = options.ownedBy;
+	const inScope = (ref) => owner === void 0 || isSecretRefOwnedBy(ref, owner);
+	const refs = collectSecretMarkerRefs(value).filter(inScope);
 	if (refs.length === 0) return {
 		value,
 		unresolved: []
@@ -1223,10 +1230,18 @@ async function resolveSecretMarkers(value, secrets) {
 	}
 	const substitute = (v) => {
 		if (isSecretMarker(v)) {
+			if (!inScope(v.$secret)) return {
+				keep: true,
+				value: v
+			};
 			const answer = answers[v.$secret];
-			return answer?.kind === "value" ? {
+			if (answer?.kind === "value") return {
 				keep: true,
 				value: answer.value
+			};
+			return keepMarker ? {
+				keep: true,
+				value: v
 			} : {
 				keep: false,
 				value: void 0
@@ -1243,7 +1258,7 @@ async function resolveSecretMarkers(value, secrets) {
 				value: items
 			};
 		}
-		if (isRecord(v)) {
+		if (isRecord$1(v)) {
 			const out = {};
 			for (const [k, child] of Object.entries(v)) {
 				const s = substitute(child);
@@ -1265,15 +1280,155 @@ async function resolveSecretMarkers(value, secrets) {
 	};
 }
 //#endregion
-//#region src/addon/secret-aware-context.ts
-function touchesTree(tree, patch) {
-	if (tree.size === 0) return false;
-	for (const key of Object.keys(patch)) {
-		const at = key.indexOf("@");
-		if (tree.has(at > 0 ? key.slice(0, at) : key)) return true;
+//#region src/addon/secret-write-back.ts
+/** An addon tried to replace a stored secret it could not read. Nothing was written. */
+var SecretOverwriteRefusedError = class extends Error {
+	ref;
+	reason;
+	constructor(ref, reason) {
+		super(`secret ${ref} was not replaced: its stored value cannot be read right now (${reason}), and an addon may not overwrite a secret it cannot see. Nothing was written.`);
+		this.ref = ref;
+		this.reason = reason;
+		this.name = "SecretOverwriteRefusedError";
+	}
+};
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function resolvedValue(pass, marker) {
+	const answer = pass.answers[marker.$secret];
+	return answer?.kind === "value" ? answer.value : null;
+}
+async function atMarker(pass, incoming, stored) {
+	if (incoming === null) return stored;
+	if (typeof incoming !== "string") return incoming;
+	if (incoming === resolvedValue(pass, stored)) return stored;
+	const intent = classifySecretWrite(incoming);
+	if (intent.kind !== "set") return stored;
+	const ref = stored.$secret;
+	if (!isSecretRefOwnedBy(ref, pass.secrets.owner)) return incoming;
+	const answer = pass.answers[ref];
+	if ((answer === void 0 || answer.kind === "unavailable" || answer.kind === "forbidden") && !pass.operatorWrite) throw new SecretOverwriteRefusedError(ref, answer === void 0 ? "not-initialized" : answer.kind === "unavailable" ? answer.reason : answer.kind);
+	try {
+		await pass.secrets.put(ref, intent.value);
+	} catch (err) {
+		throw new KeychainWriteRefusedError(ref, err);
+	}
+	pass.changedRefs.push(ref);
+	return stored;
+}
+function inArray(pass, incoming, stored) {
+	return incoming.map((item, index) => {
+		const twin = stored[index];
+		if (isSecretMarker(twin)) return typeof item === "string" && item === resolvedValue(pass, twin) ? twin : item;
+		if (isRecord(item) && isRecord(twin)) return inArrayRow(pass, item, twin);
+		if (Array.isArray(item) && Array.isArray(twin)) return inArray(pass, item, twin);
+		return item;
+	});
+}
+function inArrayRow(pass, incoming, stored) {
+	const out = { ...incoming };
+	for (const [key, value] of Object.entries(incoming)) {
+		const twin = stored[key];
+		if (isSecretMarker(twin)) {
+			if (typeof value === "string" && value === resolvedValue(pass, twin)) out[key] = twin;
+		} else if (isRecord(value) && isRecord(twin)) out[key] = inArrayRow(pass, value, twin);
+		else if (Array.isArray(value) && Array.isArray(twin)) out[key] = inArray(pass, value, twin);
+	}
+	return out;
+}
+async function walk(pass, incoming, stored) {
+	if (isSecretMarker(stored)) return atMarker(pass, incoming, stored);
+	if (Array.isArray(incoming) && Array.isArray(stored)) return inArray(pass, incoming, stored);
+	if (!isRecord(incoming) || !isRecord(stored)) return incoming;
+	const out = { ...incoming };
+	for (const [key, value] of Object.entries(incoming)) out[key] = await walk(pass, value, stored[key]);
+	return out;
+}
+/** Restore markers a write-back carries as values. See the file doc. */
+async function restoreUnchangedSecrets(input) {
+	const refs = [];
+	for (const key of Object.keys(input.patch)) collectSecretMarkerRefs(input.stored[key], refs);
+	const owned = refs.filter((ref) => isSecretRefOwnedBy(ref, input.secrets.owner));
+	if (owned.length === 0) return {
+		patch: input.patch,
+		changedRefs: []
+	};
+	const pass = {
+		secrets: input.secrets,
+		answers: await input.secrets.resolve([...new Set(owned)]),
+		operatorWrite: input.operatorWrite,
+		changedRefs: []
+	};
+	const out = {};
+	for (const [key, value] of Object.entries(input.patch)) out[key] = await walk(pass, value, input.stored[key]);
+	return {
+		patch: out,
+		changedRefs: pass.changedRefs
+	};
+}
+/** Structural equality over JSON-shaped values (key order does not matter). */
+function isJsonEqual(a, b) {
+	if (Object.is(a, b)) return true;
+	if (Array.isArray(a)) return Array.isArray(b) && a.length === b.length && a.every((v, i) => isJsonEqual(v, b[i]));
+	if (isRecord(a) && isRecord(b)) {
+		const keys = Object.keys(a);
+		if (keys.length !== Object.keys(b).length) return false;
+		return keys.every((k) => Object.prototype.hasOwnProperty.call(b, k) && isJsonEqual(a[k], b[k]));
 	}
 	return false;
 }
+/** The patch without the keys whose value already equals the stored one. */
+function dropUnchangedKeys(patch, stored) {
+	const out = {};
+	for (const [key, value] of Object.entries(patch)) {
+		if (Object.prototype.hasOwnProperty.call(stored, key) && isJsonEqual(value, stored[key])) continue;
+		out[key] = value;
+	}
+	return out;
+}
+/** The top-level keys of a blob that hold at least one of `owner`'s markers. */
+function markerKeysOf(blob, owner) {
+	const keys = /* @__PURE__ */ new Set();
+	for (const [key, value] of Object.entries(blob)) if (collectSecretMarkerRefs(value).some((ref) => isSecretRefOwnedBy(ref, owner))) keys.add(key);
+	return keys;
+}
+function nodeFromStored(value, owner) {
+	if (isSecretMarker(value)) return isSecretRefOwnedBy(value.$secret, owner) ? { kind: "leaf" } : null;
+	if (!isRecord(value)) return null;
+	const children = /* @__PURE__ */ new Map();
+	for (const [key, child] of Object.entries(value)) {
+		const node = nodeFromStored(child, owner);
+		if (node !== null) children.set(key, node);
+	}
+	return children.size > 0 ? {
+		kind: "object",
+		children
+	} : null;
+}
+/**
+* The declared secret tree, widened by every place the STORED blob holds a
+* marker under one of `keys` — so a marker the schema no longer declares (or
+* never declared: Wyze before b4906cec6) still gets the save path's
+* KEEP / SET / CLEAR semantics instead of being overwritten by whatever the
+* addon writes. Markers inside arrays are not added: a row has no id field to
+* match by unless the schema declares one. Only `owner`'s markers count: a
+* builtin that keeps another addon's marker (device-manager) never takes it
+* over.
+*/
+function widenTreeWithStoredMarkers(declared, stored, keys, owner) {
+	const added = /* @__PURE__ */ new Map();
+	for (const key of keys) {
+		const at = key.indexOf("@");
+		const base = at > 0 ? key.slice(0, at) : key;
+		if (declared.has(base) || added.has(base)) continue;
+		const node = nodeFromStored(stored[key], owner);
+		if (node !== null) added.set(base, node);
+	}
+	return added.size === 0 ? declared : new Map([...declared, ...added]);
+}
+//#endregion
+//#region src/addon/secret-aware-context.ts
 /** The blob as stored now; a failed read REFUSES the write instead of guessing. */
 async function readStoredAddonBlob(raw) {
 	const threeWay = raw.readAddonStoreResult;
@@ -1282,7 +1437,41 @@ async function readStoredAddonBlob(raw) {
 	if (result.kind === "failed") throw new Error(`settings write refused: the stored blob could not be read (${result.error})`);
 	return result.kind === "missing" ? {} : result.value;
 }
-function createSecretAwareSettings(raw, opts) {
+function touchesTree(tree, patch) {
+	if (tree.size === 0) return false;
+	for (const key of Object.keys(patch)) {
+		const at = key.indexOf("@");
+		if (tree.has(at > 0 ? key.slice(0, at) : key)) return true;
+	}
+	return false;
+}
+/**
+* Which top-level keys of each store held markers when last seen. `undefined`
+* for a store not seen yet: its first write reads it, to be safe.
+*/
+var MarkerKeyIndex = class {
+	owner;
+	byStore = /* @__PURE__ */ new Map();
+	constructor(owner) {
+		this.owner = owner;
+	}
+	seen(store, blob) {
+		this.byStore.set(store, markerKeysOf(blob, this.owner));
+	}
+	wrote(store, patch) {
+		const keys = this.byStore.get(store);
+		if (keys === void 0) return;
+		const now = markerKeysOf(patch, this.owner);
+		for (const key of Object.keys(patch)) if (now.has(key)) keys.add(key);
+		else keys.delete(key);
+	}
+	mayHoldMarkers(store, patch) {
+		const keys = this.byStore.get(store);
+		if (keys === void 0) return true;
+		return Object.keys(patch).some((key) => keys.has(key));
+	}
+};
+function createHandle(raw, opts) {
 	const chains = /* @__PURE__ */ new Map();
 	const serialize = (key, fn) => {
 		const next = (chains.get(key) ?? Promise.resolve()).then(fn, fn);
@@ -1293,46 +1482,130 @@ function createSecretAwareSettings(raw, opts) {
 		});
 		return next;
 	};
-	const write = async (chainKey, tree, scope, patch, readStored, rawWrite) => {
-		if (!touchesTree(tree, patch)) return rawWrite(patch);
-		return serialize(chainKey, async () => {
+	const index = new MarkerKeyIndex(opts.secrets.owner);
+	const resolveRead = async (store, blob) => {
+		index.seen(store, blob);
+		const { value, unresolved } = await resolveSecretMarkers(blob, opts.secrets, {
+			unresolved: "keep-marker",
+			ownedBy: opts.secrets.owner
+		});
+		if (unresolved.length > 0) opts.onUnresolved?.(unresolved);
+		return value;
+	};
+	const write = async (store, declared, scope, patch, readStored, rawWrite) => {
+		if (!touchesTree(declared, patch) && !index.mayHoldMarkers(store, patch)) {
+			await rawWrite(patch);
+			index.wrote(store, patch);
+			return { changed: true };
+		}
+		return serialize(store, async () => {
 			const stored = await readStored();
+			index.seen(store, stored);
+			const operatorWrite = opts.isOperatorWrite?.() === true;
+			const restored = await restoreUnchangedSecrets({
+				patch,
+				stored,
+				secrets: opts.secrets,
+				operatorWrite
+			});
 			const result = await transformSecretWrite({
-				tree,
+				tree: widenTreeWithStoredMarkers(declared, stored, Object.keys(restored.patch), opts.secrets.owner),
 				secrets: opts.secrets,
-				patch,
+				patch: restored.patch,
 				stored,
 				...scope !== void 0 ? { scope } : {},
-				operatorWrite: opts.isOperatorWrite?.() === true
+				operatorWrite
 			});
-			if (Object.keys(result.patch).length > 0) await rawWrite(result.patch);
+			const effective = dropUnchangedKeys(result.patch, stored);
+			const wroteBlob = Object.keys(effective).length > 0;
+			if (wroteBlob) {
+				await rawWrite(effective);
+				index.wrote(store, effective);
+			}
 			const { orphaned } = await result.afterWrite();
 			if (orphaned.length > 0) opts.onOrphaned(orphaned);
+			return { changed: wroteBlob || restored.changedRefs.length > 0 };
 		});
 	};
-	const wrapped = {
-		writeAddonStore: (patch) => write("addon", opts.addonTree(), void 0, patch, () => readStoredAddonBlob(raw), (p) => raw.writeAddonStore(p)),
-		writeDeviceStore: (deviceId, patch) => write(`device:${deviceId}`, opts.deviceTree(), {
-			kind: "device",
-			deviceId
-		}, patch, () => raw.readDeviceStore(deviceId), (p) => raw.writeDeviceStore(deviceId, p))
-	};
-	return new Proxy(raw, { get(target, prop, receiver) {
-		if (prop === "writeAddonStore") return wrapped.writeAddonStore;
-		if (prop === "writeDeviceStore") return wrapped.writeDeviceStore;
-		const value = Reflect.get(target, prop, receiver);
-		return typeof value === "function" ? value.bind(target) : value;
-	} });
-}
-/** The context the addon sees: identical, except that its settings writes are secret-aware. */
-function withSecretAwareSettings(context, opts) {
+	const writeAddon = (patch) => write("addon", opts.addonTree(), void 0, patch, () => readStoredAddonBlob(raw), (p) => raw.writeAddonStore(p));
+	const readAddonStoreResult = raw.readAddonStoreResult;
+	const readAddonStoreKeyResult = raw.readAddonStoreKeyResult;
+	const readDeviceStoreBatch = raw.readDeviceStoreBatch;
+	const overrides = {
+		readAddonStore: async () => resolveRead("addon", await raw.readAddonStore()),
+		...readAddonStoreResult !== void 0 ? { readAddonStoreResult: async () => {
+			const result = await readAddonStoreResult.call(raw);
+			return result.kind === "value" ? {
+				kind: "value",
+				value: await resolveRead("addon", result.value)
+			} : result;
+		} } : {},
+		...readAddonStoreKeyResult !== void 0 ? { readAddonStoreKeyResult: async (key) => {
+			const result = await readAddonStoreKeyResult.call(raw, key);
+			if (result.kind !== "present") return result;
+			const { value, unresolved } = await resolveSecretMarkers({ [key]: result.value }, opts.secrets, {
+				unresolved: "keep-marker",
+				ownedBy: opts.secrets.owner
+			});
+			if (unresolved.length > 0) opts.onUnresolved?.(unresolved);
+			return {
+				kind: "present",
+				value: value[key]
+			};
+		} } : {},
+		readDeviceStore: async (deviceId) => resolveRead(`device:${deviceId}`, await raw.readDeviceStore(deviceId)),
+		...readDeviceStoreBatch !== void 0 ? { readDeviceStoreBatch: async (deviceIds) => {
+			const rows = await readDeviceStoreBatch.call(raw, deviceIds);
+			const out = /* @__PURE__ */ new Map();
+			for (const [deviceId, blob] of rows) out.set(deviceId, await resolveRead(`device:${deviceId}`, blob));
+			return out;
+		} } : {},
+		writeAddonStore: async (patch) => {
+			await writeAddon(patch);
+		},
+		writeDeviceStore: async (deviceId, patch) => {
+			await write(`device:${deviceId}`, opts.deviceTree(), {
+				kind: "device",
+				deviceId
+			}, patch, () => raw.readDeviceStore(deviceId), (p) => raw.writeDeviceStore(deviceId, p));
+		}
+	};
+	return {
+		settings: new Proxy(raw, { get(target, prop, receiver) {
+			if (typeof prop === "string" && Object.prototype.hasOwnProperty.call(overrides, prop)) return Reflect.get(overrides, prop);
+			const value = Reflect.get(target, prop, receiver);
+			return typeof value === "function" ? value.bind(target) : value;
+		} }),
+		raw: {
+			readAddonStore: async () => {
+				const blob = await raw.readAddonStore();
+				index.seen("addon", blob);
+				return blob;
+			},
+			readDeviceStore: async (deviceId) => {
+				const blob = await raw.readDeviceStore(deviceId);
+				index.seen(`device:${deviceId}`, blob);
+				return blob;
+			}
+		},
+		writeAddonStore: writeAddon
+	};
+}
+/** The context the addon sees, plus the private raw view and write outcome. */
+function createSecretAwareContext(context, opts) {
 	const raw = context.settings;
-	if (raw === void 0) return context;
-	const settings = createSecretAwareSettings(raw, opts);
-	return new Proxy(context, { get(target, prop, receiver) {
-		if (prop === "settings") return settings;
-		return Reflect.get(target, prop, receiver);
-	} });
+	if (raw === void 0) return {
+		context,
+		handle: null
+	};
+	const handle = createHandle(raw, opts);
+	return {
+		context: new Proxy(context, { get(target, prop, receiver) {
+			if (prop === "settings") return handle.settings;
+			return Reflect.get(target, prop, receiver);
+		} }),
+		handle
+	};
 }
 //#endregion
 //#region src/addon/secret-paths.ts
@@ -1524,6 +1797,14 @@ var BaseAddon = class {
 	_secretChangeUnsub = null;
 	/** >0 while an OPERATOR's settings write is being applied. */
 	_operatorWriteDepth = 0;
+	/**
+	* The keychain-aware settings handle (D798). Its `raw` view is the ONLY way
+	* to the marker-bearing blobs and stays private to this class: the form
+	* hydrate and config resolution need markers, addon code never does.
+	*/
+	_secretSettings = null;
+	/** Refs an addon-facing read could not resolve — each is logged once per process. */
+	_loggedUnresolvedReads = /* @__PURE__ */ new Set();
 	constructor(defaults) {
 		this.defaults = defaults;
 		this._config = { ...defaults };
@@ -1560,13 +1841,21 @@ var BaseAddon = class {
 	}
 	async initialize(context) {
 		const secrets = context.secrets;
-		this._ctx = secrets !== void 0 ? withSecretAwareSettings(context, {
-			secrets,
-			addonTree: () => this.addonSecretTree(),
-			deviceTree: () => this.deviceSecretTree(),
-			onOrphaned: (refs) => context.logger.warn("keychain refs dropped by a settings write could not be deleted", { meta: { refs: [...refs] } }),
-			isOperatorWrite: () => this._operatorWriteDepth > 0
-		}) : context;
+		if (secrets !== void 0) {
+			const { context: wrapped, handle } = createSecretAwareContext(context, {
+				secrets,
+				addonTree: () => this.addonSecretTree(),
+				deviceTree: () => this.deviceSecretTree(),
+				onOrphaned: (refs) => context.logger.warn("keychain refs dropped by a settings write could not be deleted", { meta: { refs: [...refs] } }),
+				isOperatorWrite: () => this._operatorWriteDepth > 0,
+				onUnresolved: (unresolved) => this.logUnresolvedRead(unresolved)
+			});
+			this._ctx = wrapped;
+			this._secretSettings = handle;
+		} else {
+			this._ctx = context;
+			this._secretSettings = null;
+		}
 		await this.resolveConfig();
 		if (secrets !== void 0) this._secretChangeUnsub = secrets.onChange((ref) => {
 			if (this._configSecretRefs.has(ref)) this.scheduleSecretReresolve(SECRET_CHANGE_DEBOUNCE_MS);
@@ -1683,11 +1972,8 @@ var BaseAddon = class {
 	async getGlobalSettings(overlay, cap, nodeId) {
 		const schema = this.globalSettingsSchema(cap);
 		if (!schema) return { sections: [] };
-		const projected = await this.resolveGlobalStore(nodeId, cap);
-		return hydrateSchema(schema, overlay ? {
-			...projected,
-			...overlay
-		} : projected, { inlineSecretsAsViews: true });
+		const projected = await this.readRawProjectedStore(nodeId, cap);
+		return hydrateSchema(schema, overlay ? await this.overlayKeepingMarkers(projected, overlay) : projected, { inlineSecretsAsViews: true });
 	}
 	/**
 	* The integration-level view of this addon's settings: exactly the sections
@@ -1732,7 +2018,7 @@ var BaseAddon = class {
 			});
 		}
 		if (sections.length === 0) return null;
-		const projected = await this.resolveGlobalStore(nodeId);
+		const projected = await this.readRawProjectedStore(nodeId);
 		return hydrateSchema({
 			...schema,
 			sections
@@ -1749,12 +2035,50 @@ var BaseAddon = class {
 	* the store for custom option logic (option narrowing, value snapping) to
 	* read it per-node — never `ctx.settings.readAddonStore()` directly.
 	* `nodeId` omitted ⇒ the local node (node-blind injection from ctx).
+	*
+	* Keychain values come back RESOLVED (D798): a secret reads as its value,
+	* never as a `{ $secret }` marker. One the keychain cannot serve right now
+	* stays a marker — "stored, unavailable" (`isSecretMarker()` is true, and it
+	* is listed in {@link unresolvedSecrets}) — never `''` and never absent, so
+	* it cannot be mistaken for "nothing stored, mint a new one". Writing the
+	* resolved blob back is a no-op for every unchanged secret.
 	*/
 	async resolveGlobalStore(nodeId, cap) {
 		const raw = await this._ctx?.settings?.readAddonStore() ?? {};
+		return this.projectForNode(raw, nodeId, cap);
+	}
+	projectForNode(store, nodeId, cap) {
 		const keys = this.perNodeKeys(cap);
 		const node = normalizeNodeId(nodeId ?? this._ctx?.kernel?.localNodeId);
-		return keys.size > 0 ? projectStore(raw, keys, node) : raw;
+		return keys.size > 0 ? projectStore(store, keys, node) : store;
+	}
+	/** The PROJECTED store with its markers — the form hydrate only (D798). */
+	async readRawProjectedStore(nodeId, cap) {
+		const raw = await this.rawSettings()?.readAddonStore() ?? {};
+		return this.projectForNode(raw, nodeId, cap);
+	}
+	/**
+	* `{ ...stored, ...overlay }`, except that an overlay member equal to the
+	* RESOLVED stored one keeps the stored (marker-bearing) member — so a form
+	* hydrated from a resolved overlay still shows a secret as "set", never as
+	* its value.
+	*/
+	async overlayKeepingMarkers(stored, overlay) {
+		const secrets = this._ctx?.secrets;
+		const merged = {
+			...stored,
+			...overlay
+		};
+		if (secrets === void 0 || collectSecretMarkerRefs(stored).length === 0) return merged;
+		const { value: resolved } = await resolveSecretMarkers(stored, secrets, {
+			unresolved: "keep-marker",
+			ownedBy: secrets.owner
+		});
+		for (const key of Object.keys(overlay)) {
+			if (collectSecretMarkerRefs(stored[key]).length === 0) continue;
+			if (isJsonEqual(overlay[key], resolved[key])) merged[key] = stored[key];
+		}
+		return merged;
 	}
 	/**
 	* Whether ONE global key of this addon's store was written, read three-way
@@ -1819,8 +2143,12 @@ var BaseAddon = class {
 	async clearSecrets(keys, nodeId) {
 		const tree = this.addonSecretTree();
 		const keychain = this._ctx?.secrets !== void 0;
+		const stored = keychain ? await this.readAddonStoreWithRetry() : {};
 		const patch = {};
-		for (const key of keys) patch[key] = keychain && tree.has(key) ? SECRET_CLEAR : "";
+		for (const key of keys) {
+			const keychainStored = tree.has(key) || collectSecretMarkerRefs(stored[key]).length > 0;
+			patch[key] = keychain && keychainStored ? SECRET_CLEAR : "";
+		}
 		await this.applyGlobalPatch(patch, nodeId);
 	}
 	async applyGlobalPatch(barePatch, nodeId) {
@@ -1828,7 +2156,11 @@ var BaseAddon = class {
 		const localNode = normalizeNodeId(this._ctx?.kernel?.localNodeId);
 		const target = normalizeNodeId(nodeId ?? this._ctx?.kernel?.localNodeId);
 		const scoped = keys.size > 0 ? scopePatch(barePatch, keys, target) : barePatch;
-		await this._ctx?.settings?.writeAddonStore(scoped);
+		const handle = this._secretSettings;
+		if (handle !== null) {
+			const { changed } = await handle.writeAddonStore(scoped);
+			if (!changed) return;
+		} else await this._ctx?.settings?.writeAddonStore(scoped);
 		if (target !== localNode) return;
 		await this.resolveConfig();
 		await this.onConfigChanged();
@@ -1881,7 +2213,7 @@ var BaseAddon = class {
 	async getDeviceSettings(deviceId) {
 		const schema = this.deviceSettingsSchema();
 		if (!schema) return { sections: [] };
-		return hydrateSchema(schema, await this._ctx?.settings?.readDeviceStore(deviceId) ?? {}, { inlineSecretsAsViews: true });
+		return hydrateSchema(schema, await this.rawSettings()?.readDeviceStore(deviceId) ?? {}, { inlineSecretsAsViews: true });
 	}
 	async updateDeviceSettings(deviceId, patch) {
 		await this._ctx?.settings?.writeDeviceStore(deviceId, patch);
@@ -2053,7 +2385,7 @@ var BaseAddon = class {
 			key,
 			schema,
 			fallback,
-			read: async () => this.resolveStoredSecrets(await this._ctx?.settings?.readDeviceStore(deviceId) ?? {}, false),
+			read: async () => this.resolveStoredSecrets(await this.rawSettings()?.readDeviceStore(deviceId) ?? {}, false),
 			write: async (patch) => {
 				await this._ctx?.settings?.writeDeviceStore(deviceId, patch);
 			},
@@ -2115,6 +2447,23 @@ var BaseAddon = class {
 		}
 		return value;
 	}
+	/**
+	* The marker-bearing settings reads (D798) — private on purpose. Without a
+	* keychain the context's own view is already raw.
+	*/
+	rawSettings() {
+		return this._secretSettings?.raw ?? this._ctx?.settings;
+	}
+	/** An addon-facing read met markers it could not resolve: say so once per ref. */
+	logUnresolvedRead(unresolved) {
+		const fresh = unresolved.filter((u) => !this._loggedUnresolvedReads.has(u.ref));
+		if (fresh.length === 0) return;
+		for (const u of fresh) this._loggedUnresolvedReads.add(u.ref);
+		this._ctx?.logger?.warn?.("settings read: a stored secret is unavailable — it reads as its marker, not as a value", { meta: { secrets: fresh.map((u) => ({
+			ref: u.ref,
+			reason: u.reason
+		})) } });
+	}
 	/** Re-resolve the config (a keychain-only change, or a retry) and apply it. */
 	scheduleSecretReresolve(delayMs) {
 		const timerOf = delayMs === SECRET_CHANGE_DEBOUNCE_MS ? "_secretChangeTimer" : "_secretRetryTimer";
@@ -2141,7 +2490,7 @@ var BaseAddon = class {
 	* `{}` (defaults) — the addon's first successful patch will rehydrate.
 	*/
 	async readAddonStoreWithRetry() {
-		const settings = this._ctx?.settings;
+		const settings = this.rawSettings();
 		if (!settings) return {};
 		const delaysMs = [
 			150,
@@ -4709,6 +5058,7 @@ function createDeviceProxy(api, binding, opts) {
 		getRetrainExportUrl: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "getRetrainExportUrl", "query", input),
 		setRetrainFrameComplete: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "setRetrainFrameComplete", "mutation", input),
 		writeRetrainArchive: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "writeRetrainArchive", "mutation", input),
+		offerRetrainArchive: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "offerRetrainArchive", "mutation", input),
 		previewRetrainDataset: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "previewRetrainDataset", "query", input),
 		createRetrainDatasetVersion: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "createRetrainDatasetVersion", "mutation", input),
 		listRetrainDatasetVersions: (input) => dispatch("pipeline-analytics", "pipelineAnalytics", "listRetrainDatasetVersions", "query", input),