@aigne/aos 0.2.0-beta

package/dist/session/settings-resolver.mjs

@@ -0,0 +1,771 @@
+import { cascade } from "./settings-cascade.mjs";
+import { joinURL } from "ufo";
+import { AFSForbiddenError, AFSNotFoundError, makeNsLog } from "@aigne/afs";
+
+//#region src/session/settings-resolver.ts
+const log = makeNsLog("aos");
+/** Root of the instance-layer schema tree on the Small World base. */
+const INSTANCE_SETTINGS_ROOT = "/instance/settings";
+/** Root of the per-user override store on the caller's `/user` backing. */
+const USER_SETTINGS_ROOT = "/settings";
+/** Keys that must never be copied out of a parsed wrapper (prototype-pollution + control fields). */
+const DANGEROUS_KEYS = new Set([
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
+const CONTROL_KEYS = new Set([
+	"value",
+	"scope",
+	"source",
+	"overridden",
+	"inheritedValue",
+	"visible",
+	"editable"
+]);
+/** Strip dangerous keys from a parsed object (prototype pollution defense). */
+function sanitizeObject(obj) {
+	const out = {};
+	for (const [k, v] of Object.entries(obj)) {
+		if (DANGEROUS_KEYS.has(k)) continue;
+		out[k] = v;
+	}
+	return out;
+}
+/**
+* Parse an instance-layer wrapper. Defensive: malformed JSON degrades to a
+* bare `{ value: <raw> }` (scope absent → instance) rather than throwing — a
+* broken file must not take down the whole settings page.
+*/
+function parseWrapper(raw) {
+	let obj = raw;
+	if (typeof raw === "string") try {
+		obj = JSON.parse(raw);
+	} catch {
+		return { value: raw };
+	}
+	if (obj === null || typeof obj !== "object") return { value: obj };
+	return sanitizeObject(obj);
+}
+function sanitizeScope(s) {
+	return s === "user" || s === "shared" ? s : "instance";
+}
+/**
+* Coerce a bare user-override value (read back from the per-user fs backing,
+* which stringifies everything) to the type of the instance default. The schema
+* default is the type oracle: a boolean field's "false" → false, a number
+* field's "7" → 7. Strings and already-correct types pass through; an
+* un-coercible value is returned as-is rather than fabricating a wrong type.
+*/
+function coerceToSchemaType(raw, schemaValue) {
+	if (typeof schemaValue === "boolean") {
+		if (raw === true || raw === false) return raw;
+		if (raw === "true") return true;
+		if (raw === "false") return false;
+		return raw;
+	}
+	if (typeof schemaValue === "number") {
+		if (typeof raw === "number") return raw;
+		if (typeof raw === "string" && raw.trim() !== "") {
+			const n = Number(raw);
+			if (Number.isFinite(n)) return n;
+		}
+		return raw;
+	}
+	return raw;
+}
+function isNotFound(e) {
+	return e instanceof AFSNotFoundError || typeof e === "object" && e !== null && e.code === "AFS_NOT_FOUND";
+}
+function lastSegment(path) {
+	return path.split("/").filter(Boolean).pop() ?? "";
+}
+/**
+* Split a resolver-relative path into the wrapper file part and an optional
+* sub-key. Settings fields are always `<name>.json`; anything before the first
+* `.json` segment is the wrapper, anything after is a key inside it
+* (`value`, `label`, …). No `.json` segment → a structure directory.
+*
+* Segment-based, not raw string slicing (CLAUDE.md path rules).
+*/
+function splitWrapper(sub) {
+	const segs = sub.split("/").filter(Boolean);
+	const idx = segs.findIndex((s) => s.endsWith(".json"));
+	if (idx === -1) return { wrapperSub: null };
+	const wrapperSub = joinURL("/", ...segs.slice(0, idx + 1));
+	const rest = segs.slice(idx + 1);
+	return {
+		wrapperSub,
+		subKey: rest.length ? rest.join("/") : void 0
+	};
+}
+/**
+* Map a resolver-relative subscribe path to the two underlying layer paths a
+* propBind subscription must watch (§3.6 dual-layer subscribe). Pure — exported
+* for unit testing (T4.1).
+*
+* A field bind like `/cascade/theme.json/value` maps to:
+*   - instancePath: `/instance/settings/cascade/theme.json`  (base WRAPPER FILE —
+*     instance-layer writes land on the whole wrapper, never the `/value`
+*     sub-path, so we must watch the file, not the sub-key)
+*   - userPath:     `/settings/cascade/theme.json`            (user bare-value file)
+*
+* A directory / path-less subscribe (`/cascade`, `/`) has no `.json` segment, so
+* `wrapperSub` is null and we watch the directory itself on both layers. The
+* re-emit path is then derived per-event from the underlying path (see
+* `subscribe()`), not from a fixed field path.
+*/
+function mapSubscribePaths(relPath) {
+	const { wrapperSub } = splitWrapper(relPath);
+	const tail = wrapperSub ?? relPath;
+	return {
+		instancePath: joinURL(INSTANCE_SETTINGS_ROOT, tail),
+		userPath: joinURL(USER_SETTINGS_ROOT, tail),
+		isField: wrapperSub !== null
+	};
+}
+/**
+* On-disk key holding EXPLICIT admin schema-text overrides in a converged
+* (override-only) instance row: `{ value?, overrides?: { label: "...", … } }`.
+* The nesting is the legacy/explicit discriminator (settings-layering §2.D):
+* a LEGACY full wrapper carries its schema keys FLAT and is ignored on read
+* (package schema wins — legacy-no-shadow); keys under `overrides` were
+* deliberately written by an admin through `write()` and DO overlay the
+* package schema.
+*/
+const OVERRIDES_KEY = "overrides";
+var SettingsResolver = class {
+	name;
+	accessMode = "readwrite";
+	base;
+	userProvider;
+	role;
+	schema;
+	/** Memoized lazy ingest — at most one ensure() flight per session. */
+	schemaReady = null;
+	/**
+	* Outcome of the lazy ingest. `ready` = the package declares settings and
+	* the derived index is consumable (STORE MODE: existence/schema come from
+	* the package index). `empty` = package declares none; `failed` = store
+	* unavailable; `unwired` = no handle. All non-`ready` states resolve in
+	* LEGACY MODE (instance rows define existence + schema) — the pre-Phase-2
+	* behavior, so blocklets without package settings keep working.
+	*/
+	schemaState = "unwired";
+	/**
+	* Active render snapshots, insertion-ordered by `beginRender`. Ops resolve
+	* against the MOST RECENTLY begun snapshot (walks are sequential per
+	* render; concurrent renders each get their own immutable entry).
+	*/
+	snapshots = /* @__PURE__ */ new Map();
+	constructor(opts) {
+		this.base = opts.base;
+		this.userProvider = opts.userProvider;
+		this.role = opts.role;
+		this.schema = opts.schema ?? null;
+		this.name = `settings-resolver:${opts.sessionId}`;
+	}
+	/**
+	* Lazily materialize the package-schema scope (Phase 1c plumbing). Memoized
+	* per resolver (per session); the store's own single-flight + completion
+	* marker make cross-session work idempotent. BEST-EFFORT in Phase 1: a
+	* failed ingest logs and falls back to legacy resolution (Phase 2 will
+	* consume the scope for existence/schema and define the hard contract).
+	*/
+	ensureSchemaIngested() {
+		if (!this.schema) return Promise.resolve();
+		this.schemaReady ??= this.schema.ensure().then((result) => {
+			this.schemaState = result.fileCount > 0 ? "ready" : "empty";
+		}, (err) => {
+			this.schemaState = "failed";
+			log.warn(`[settings-resolver] schema ingest failed (legacy resolution continues): ${err instanceof Error ? err.message : err}`);
+		});
+		return this.schemaReady;
+	}
+	/** STORE MODE — existence/schema from the derived package index (§1.4). */
+	get storeMode() {
+		return this.schemaState === "ready";
+	}
+	/**
+	* Begin a render-scoped snapshot. Called by the auto-surface walk entry
+	* point (via `SessionUserAFS.beginRender` proxy) with a fresh `renderId`
+	* before walking; the resolver builds the WHOLE settings snapshot once
+	* (1× derived-index listEntries + instance/user override list + sparse
+	* reads) and serves every list/read of that render from memory.
+	*
+	* Phase 0: contract only — no-op. Phase 2 implements the snapshot builder.
+	* Idempotency contract: repeated `beginRender` with the same renderId and
+	* `endRender` without a matching begin are both safe no-ops.
+	*/
+	async beginRender(renderId) {
+		if (this.snapshots.has(renderId)) return;
+		await this.ensureSchemaIngested();
+		const [schemas, instance, user] = await Promise.all([
+			this.storeMode ? this.loadSchemaMap() : Promise.resolve(null),
+			this.loadLayerRows(this.base, INSTANCE_SETTINGS_ROOT, true),
+			this.userProvider ? this.loadLayerRows(this.userProvider, USER_SETTINGS_ROOT, false) : Promise.resolve(/* @__PURE__ */ new Map())
+		]);
+		this.snapshots.set(renderId, {
+			schemas,
+			instance,
+			user
+		});
+	}
+	/** Discard the render snapshot for `renderId`. See {@link beginRender}. */
+	endRender(renderId) {
+		this.snapshots.delete(renderId);
+	}
+	/** The snapshot ops resolve against: the most recently begun, still active. */
+	get activeSnapshot() {
+		let last = null;
+		for (const snap of this.snapshots.values()) last = snap;
+		return last;
+	}
+	/** Bulk-read + parse the derived package schemas (1 store query). */
+	async loadSchemaMap() {
+		const map = /* @__PURE__ */ new Map();
+		if (!this.schema) return map;
+		try {
+			for (const { path, content } of await this.schema.listSchemas()) map.set(joinURL("/", path), parseWrapper(content));
+		} catch (err) {
+			log.warn(`[settings-resolver] schema bulk read failed: ${err instanceof Error ? err.message : err}`);
+		}
+		return map;
+	}
+	/**
+	* Walk one override layer's tree and read every `.json` row. Sparse by
+	* design (converged rows: 0-5); legacy instances pay row-count reads ONCE
+	* per render — all in-process, replacing the per-field WS round-trips.
+	*/
+	async loadLayerRows(provider, root, parse) {
+		const map = /* @__PURE__ */ new Map();
+		if (!provider.list || !provider.read) return map;
+		const walk = async (dir) => {
+			let entries;
+			try {
+				entries = (await provider.list?.(dir))?.data ?? [];
+			} catch {
+				return;
+			}
+			for (const entry of entries) {
+				const name = entry.path.split("/").filter(Boolean).pop();
+				if (!name || name.startsWith(".")) continue;
+				const full = joinURL(dir, name);
+				if (name.endsWith(".json")) try {
+					const raw = (await provider.read?.(full))?.data?.content;
+					if (raw === void 0) continue;
+					map.set(full.slice(root.length), parse ? parseWrapper(raw) : raw);
+				} catch {}
+				else await walk(full);
+			}
+		};
+		await walk(root);
+		return map;
+	}
+	get isAuthed() {
+		return this.userProvider != null;
+	}
+	get isOwnerOrAdmin() {
+		return this.role === "owner" || this.role === "admin";
+	}
+	/** The physical layer this caller reads AND writes for the given scope. */
+	resolveWriteLayer(scope) {
+		if (scope === "instance") return "instance";
+		if (scope === "user") return "user";
+		return this.isOwnerOrAdmin ? "instance" : "user";
+	}
+	/** Presentation hint: should this caller's form render the field at all? */
+	visible(scope) {
+		if (scope === "instance") return this.isOwnerOrAdmin;
+		if (scope === "user") return this.isAuthed;
+		return true;
+	}
+	/** Capability hint + (P1) write-enforcement basis: may this caller edit it? */
+	editable(scope) {
+		if (scope === "instance") return this.isOwnerOrAdmin;
+		if (scope === "user") return this.isAuthed;
+		return this.isAuthed;
+	}
+	/** Normalize an incoming resolver-relative path; reject traversal outright. */
+	normalizeSub(path) {
+		const p = path.startsWith("/") ? path : `/${path}`;
+		if (p.split("/").some((seg) => seg === "..")) throw new AFSForbiddenError(path, "path traversal rejected");
+		return p;
+	}
+	/** Translate an underlying layer path back into the resolver-relative space. */
+	underlyingToRelative(fullPath, layer) {
+		const root = layer === "instance" ? INSTANCE_SETTINGS_ROOT : USER_SETTINGS_ROOT;
+		if (fullPath === root) return "/";
+		if (fullPath.startsWith(`${root}/`)) return fullPath.slice(root.length);
+		return fullPath;
+	}
+	baseRead(path, options) {
+		if (!this.base.read) throw new Error("base.read not supported");
+		return this.base.read(path, options);
+	}
+	baseStat(path, options) {
+		if (!this.base.stat) throw new Error("base.stat not supported");
+		return this.base.stat(path, options);
+	}
+	async loadInstanceWrapper(wrapperSub) {
+		const instancePath = joinURL(INSTANCE_SETTINGS_ROOT, wrapperSub);
+		let raw;
+		try {
+			raw = (await this.baseRead(instancePath)).data?.content;
+		} catch (e) {
+			if (isNotFound(e)) throw new AFSNotFoundError(wrapperSub);
+			throw e;
+		}
+		if (raw === void 0) throw new AFSNotFoundError(wrapperSub);
+		const inst = parseWrapper(raw);
+		return {
+			inst,
+			scope: sanitizeScope(inst.scope)
+		};
+	}
+	/** Read the caller's bare override value, or undefined when absent/anonymous. */
+	async readUserOverride(wrapperSub) {
+		const snap = this.activeSnapshot;
+		if (snap) return this.userProvider ? snap.user.get(wrapperSub) : void 0;
+		if (!this.userProvider?.read) return void 0;
+		try {
+			return (await this.userProvider.read(joinURL(USER_SETTINGS_ROOT, wrapperSub))).data?.content;
+		} catch (e) {
+			if (isNotFound(e)) return void 0;
+			throw e;
+		}
+	}
+	/** Parsed package schema for a field, or null (store mode only). */
+	async getSchemaWrapper(wrapperSub) {
+		const snap = this.activeSnapshot;
+		if (snap?.schemas) return snap.schemas.get(wrapperSub) ?? null;
+		if (!this.schema) return null;
+		const raw = await this.schema.getSchema(wrapperSub);
+		return raw === null ? null : parseWrapper(raw);
+	}
+	/** Parsed raw instance row, or null when absent (never throws not-found). */
+	async getInstanceRow(wrapperSub) {
+		const snap = this.activeSnapshot;
+		if (snap) return snap.instance.get(wrapperSub) ?? null;
+		try {
+			return (await this.loadInstanceWrapper(wrapperSub)).inst;
+		} catch (e) {
+			if (isNotFound(e)) return null;
+			throw e;
+		}
+	}
+	/**
+	* Reduce a raw instance row to its OVERRIDE-ONLY contribution (§2.D):
+	* `value` (when present) + keys explicitly written under `overrides`.
+	* A LEGACY full wrapper's flat schema keys are deliberately dropped —
+	* the package schema is authoritative (legacy-no-shadow).
+	*/
+	stripToOverrideOnly(row) {
+		const out = {};
+		if (!row) return out;
+		if (row.value !== void 0) out.value = row.value;
+		const ov = row[OVERRIDES_KEY];
+		if (ov && typeof ov === "object" && !Array.isArray(ov)) for (const [k, v] of Object.entries(ov)) {
+			if (DANGEROUS_KEYS.has(k) || CONTROL_KEYS.has(k) || k === OVERRIDES_KEY) continue;
+			out[k] = v;
+		}
+		return out;
+	}
+	/**
+	* Load one field through the cascade. Returns null when the field does not
+	* exist — store mode: not in the derived package index (orphan instance
+	* rows are IGNORED, §5.4.5); legacy mode: no instance row.
+	*/
+	async loadField(wrapperSub) {
+		let pkg;
+		let instOverride;
+		let instRow;
+		if (this.storeMode) {
+			const schemaWrapper = await this.getSchemaWrapper(wrapperSub);
+			if (!schemaWrapper) return null;
+			instRow = await this.getInstanceRow(wrapperSub);
+			pkg = schemaWrapper;
+			instOverride = this.stripToOverrideOnly(instRow);
+		} else {
+			instRow = await this.getInstanceRow(wrapperSub);
+			if (!instRow) return null;
+			pkg = instRow;
+			instOverride = {};
+		}
+		const scope = sanitizeScope(pkg.scope);
+		const rawUser = this.resolveWriteLayer(scope) === "user" ? await this.readUserOverride(wrapperSub) : void 0;
+		const inherited = instOverride.value !== void 0 ? instOverride.value : pkg.value;
+		const user = rawUser === void 0 ? void 0 : { value: coerceToSchemaType(rawUser, inherited) };
+		const eff = cascade(pkg, instOverride, user);
+		const overridden = eff.source === "user";
+		const editable = this.editable(scope);
+		const visible = this.visible(scope);
+		const synth = {
+			...eff.synth,
+			source: overridden ? "user" : "instance",
+			editable,
+			visible
+		};
+		return {
+			scope,
+			visible,
+			editable,
+			overridden,
+			eff: eff.value,
+			synth,
+			instRow,
+			fromPackage: this.storeMode
+		};
+	}
+	/** Opaque version of the layer this caller would write — §3.7. */
+	async writeTargetVersion(scope, wrapperSub) {
+		const layer = this.resolveWriteLayer(scope);
+		try {
+			if (layer === "instance") return (await this.baseStat(joinURL(INSTANCE_SETTINGS_ROOT, wrapperSub))).data?.meta?.version;
+			if (this.userProvider?.stat) return (await this.userProvider.stat(joinURL(USER_SETTINGS_ROOT, wrapperSub))).data?.meta?.version;
+		} catch (e) {
+			if (!isNotFound(e)) throw e;
+		}
+	}
+	async read(path, options) {
+		await this.ensureSchemaIngested();
+		const sub = this.normalizeSub(path);
+		const { wrapperSub, subKey } = splitWrapper(sub);
+		if (!wrapperSub) {
+			if (this.storeMode) {
+				if (!await this.dirExists(sub)) throw new AFSNotFoundError(sub);
+				return { data: {
+					id: lastSegment(sub) || "settings",
+					path: sub,
+					content: `Settings directory: ${sub}`,
+					meta: { kind: "directory" }
+				} };
+			}
+			const instancePath = joinURL(INSTANCE_SETTINGS_ROOT, sub);
+			let r;
+			try {
+				r = await this.baseRead(instancePath, options);
+			} catch (e) {
+				if (isNotFound(e)) throw new AFSNotFoundError(sub);
+				throw e;
+			}
+			if (!r.data) throw new AFSNotFoundError(sub);
+			return { data: {
+				...r.data,
+				path: sub,
+				meta: {
+					...r.data.meta,
+					kind: "directory"
+				}
+			} };
+		}
+		const field = await this.loadField(wrapperSub);
+		if (!field) throw new AFSNotFoundError(wrapperSub);
+		const version = this.activeSnapshot ? void 0 : await this.writeTargetVersion(field.scope, wrapperSub);
+		const meta = {
+			accessMode: field.editable ? "readwrite" : "readonly",
+			visible: field.visible,
+			editable: field.editable,
+			scope: field.scope,
+			version
+		};
+		if (subKey === void 0) return { data: {
+			id: lastSegment(wrapperSub),
+			path: wrapperSub,
+			content: JSON.stringify(field.synth),
+			meta
+		} };
+		const content = subKey === "value" ? field.eff : field.synth[subKey];
+		return { data: {
+			id: lastSegment(subKey),
+			path: joinURL(wrapperSub, subKey),
+			content,
+			meta
+		} };
+	}
+	/** Store-mode directory existence: any package field lives under `sub`. */
+	async dirExists(sub) {
+		if (sub === "/") return true;
+		const prefix = `${sub}/`;
+		for (const key of (await this.schemaMap()).keys()) if (key.startsWith(prefix)) return true;
+		return false;
+	}
+	/**
+	* The full schema map (store mode): from the active snapshot when present,
+	* else one bulk store query — replacing the legacy per-field N+1 scope peek.
+	*/
+	async schemaMap() {
+		const snap = this.activeSnapshot;
+		if (snap?.schemas) return snap.schemas;
+		return this.loadSchemaMap();
+	}
+	async list(path, options) {
+		await this.ensureSchemaIngested();
+		const sub = this.normalizeSub(path);
+		if (this.storeMode) {
+			const schemas = await this.schemaMap();
+			const prefix = sub === "/" ? "/" : `${sub}/`;
+			const children = /* @__PURE__ */ new Map();
+			for (const key of schemas.keys()) {
+				if (!key.startsWith(prefix)) continue;
+				const rest = key.slice(prefix.length);
+				const seg = rest.split("/")[0];
+				if (!seg) continue;
+				children.set(seg, children.get(seg) || rest.includes("/"));
+			}
+			if (children.size === 0 && sub !== "/") throw new AFSNotFoundError(sub);
+			const data$1 = [];
+			for (const [seg, isDir] of children) {
+				const childSub = joinURL(sub, seg);
+				if (isDir) {
+					data$1.push({
+						id: seg,
+						path: childSub,
+						meta: {
+							kind: "directory",
+							childrenCount: -1
+						}
+					});
+					continue;
+				}
+				const scope = sanitizeScope(schemas.get(childSub)?.scope);
+				const editable = this.editable(scope);
+				const visible = this.visible(scope);
+				data$1.push({
+					id: seg,
+					path: childSub,
+					meta: {
+						accessMode: editable ? "readwrite" : "readonly",
+						scope,
+						visible,
+						editable
+					}
+				});
+			}
+			return { data: data$1 };
+		}
+		const instanceDir = joinURL(INSTANCE_SETTINGS_ROOT, sub);
+		const result = await this.base.list(instanceDir, options);
+		const data = await Promise.all((result.data ?? []).map(async (e) => {
+			const relPath = this.underlyingToRelative(e.path, "instance");
+			if (!relPath.endsWith(".json")) return {
+				...e,
+				path: relPath,
+				meta: {
+					...e.meta,
+					kind: "directory",
+					childrenCount: e.meta?.childrenCount ?? -1
+				}
+			};
+			let scope = "instance";
+			try {
+				const row = await this.getInstanceRow(relPath);
+				if (row) scope = sanitizeScope(row.scope);
+			} catch {}
+			const editable = this.editable(scope);
+			const visible = this.visible(scope);
+			return {
+				...e,
+				path: relPath,
+				meta: {
+					...e.meta,
+					kind: void 0,
+					childrenCount: void 0,
+					accessMode: editable ? "readwrite" : "readonly",
+					scope,
+					visible,
+					editable
+				}
+			};
+		}));
+		return {
+			...result,
+			data
+		};
+	}
+	async stat(path, options) {
+		await this.ensureSchemaIngested();
+		const sub = this.normalizeSub(path);
+		const { wrapperSub, subKey } = splitWrapper(sub);
+		if (!wrapperSub) {
+			if (this.storeMode) {
+				if (!await this.dirExists(sub)) throw new AFSNotFoundError(sub);
+				return { data: {
+					id: lastSegment(sub) || "settings",
+					path: sub,
+					meta: {
+						kind: "directory",
+						childrenCount: -1
+					}
+				} };
+			}
+			const instancePath = joinURL(INSTANCE_SETTINGS_ROOT, sub);
+			let r;
+			try {
+				r = await this.baseStat(instancePath, options);
+			} catch (e) {
+				if (isNotFound(e)) throw new AFSNotFoundError(sub);
+				throw e;
+			}
+			if (!r.data) throw new AFSNotFoundError(sub);
+			return { data: {
+				...r.data,
+				path: sub,
+				meta: {
+					...r.data.meta,
+					kind: "directory"
+				}
+			} };
+		}
+		const field = await this.loadField(wrapperSub);
+		if (!field) throw new AFSNotFoundError(wrapperSub);
+		const version = await this.writeTargetVersion(field.scope, wrapperSub);
+		const statPath = subKey ? joinURL(wrapperSub, subKey) : wrapperSub;
+		return { data: {
+			id: lastSegment(statPath),
+			path: statPath,
+			meta: {
+				accessMode: field.editable ? "readwrite" : "readonly",
+				visible: field.visible,
+				editable: field.editable,
+				scope: field.scope,
+				version
+			}
+		} };
+	}
+	async write(path, content, options) {
+		await this.ensureSchemaIngested();
+		const { wrapperSub, subKey } = splitWrapper(this.normalizeSub(path));
+		if (!wrapperSub) throw new AFSForbiddenError(path, "settings writes must target a field, e.g. .../x.json/value");
+		if (subKey === void 0) throw new AFSForbiddenError(path, "settings writes must target a field sub-path (.../x.json/value)");
+		const field = await this.loadField(wrapperSub);
+		if (!field) throw new AFSNotFoundError(wrapperSub);
+		const ifMatch = options?.ifMatch;
+		const context = options?.context;
+		const instBase = this.storeMode ? this.overrideOnlyDiskShape(field.instRow) : field.instRow ?? {};
+		if (subKey !== "value") {
+			if (!this.isOwnerOrAdmin) throw new AFSForbiddenError(path, "editing settings schema requires owner/admin");
+			if (this.storeMode) {
+				const prior = instBase[OVERRIDES_KEY] ?? {};
+				return this.writeInstanceWrapper(wrapperSub, instBase, OVERRIDES_KEY, {
+					...prior,
+					[subKey]: content.content
+				}, {
+					ifMatch,
+					context
+				});
+			}
+			return this.writeInstanceWrapper(wrapperSub, instBase, subKey, content.content, {
+				ifMatch,
+				context
+			});
+		}
+		if (this.resolveWriteLayer(field.scope) === "instance") {
+			if (!this.isOwnerOrAdmin) throw new AFSForbiddenError(path, "instance-scope settings require owner/admin");
+			return this.writeInstanceWrapper(wrapperSub, instBase, "value", content.content, {
+				ifMatch,
+				context
+			});
+		}
+		if (!this.isAuthed || !this.userProvider?.write) throw new AFSForbiddenError(path, "sign in to personalize this setting");
+		return this.userProvider.write(joinURL(USER_SETTINGS_ROOT, wrapperSub), { content: content.content }, this.writeOptions(ifMatch, context));
+	}
+	/**
+	* The ON-DISK override-only shape of an instance row: `{ value?, overrides? }`.
+	* Distinct from {@link stripToOverrideOnly} (the flattened READ-side
+	* contribution) — this preserves the nested `overrides` object so a write
+	* RMW keeps prior explicit schema-text edits.
+	*/
+	overrideOnlyDiskShape(row) {
+		const out = {};
+		if (!row) return out;
+		if (row.value !== void 0) out.value = row.value;
+		const ov = row[OVERRIDES_KEY];
+		if (ov && typeof ov === "object" && !Array.isArray(ov)) out[OVERRIDES_KEY] = ov;
+		return out;
+	}
+	/** Assemble write options, omitting empties so providers see a clean shape. */
+	writeOptions(ifMatch, context) {
+		const out = {};
+		if (ifMatch != null) out.ifMatch = ifMatch;
+		if (context != null) out.context = context;
+		return out;
+	}
+	/**
+	* Read-modify-write the FULL instance wrapper so siblings
+	* (label/description/options/…) survive — the G0 regression guard. ifMatch
+	* (if supplied) is compared by the base provider against the wrapper version;
+	* context (if supplied) flows through so the emitted event carries origin.
+	*/
+	writeInstanceWrapper(wrapperSub, inst, key, value, opts) {
+		if (!this.base.write) throw new Error("base.write not supported");
+		const next = {
+			...inst,
+			[key]: value
+		};
+		return this.base.write(joinURL(INSTANCE_SETTINGS_ROOT, wrapperSub), { content: JSON.stringify(next) }, this.writeOptions(opts.ifMatch, opts.context));
+	}
+	async delete(path, options) {
+		await this.ensureSchemaIngested();
+		const { wrapperSub, subKey } = splitWrapper(this.normalizeSub(path));
+		if (!wrapperSub) throw new AFSForbiddenError(path, "not a settings field path");
+		if (subKey !== void 0 && subKey !== "value") throw new AFSForbiddenError(path, "only a field's value can be reset");
+		const field = await this.loadField(wrapperSub);
+		if (!field) throw new AFSNotFoundError(wrapperSub);
+		if (this.resolveWriteLayer(field.scope) === "instance") throw new AFSForbiddenError(path, "instance settings cannot be deleted; admin edits via write");
+		if (!this.isAuthed || !this.userProvider?.delete) throw new AFSForbiddenError(path, "sign in to reset this setting");
+		return this.userProvider.delete(joinURL(USER_SETTINGS_ROOT, wrapperSub), options);
+	}
+	/**
+	* Bridge instance-layer + user-layer change events into the
+	* `/instance/settings/...` namespace so propBind can react to a cascade write
+	* regardless of which physical layer it landed on.
+	*
+	* For a FIELD subscription (`/cascade/theme.json/value`):
+	*   - watch the instance WRAPPER FILE on `base` and the bare-value file on
+	*     `userProvider` (see `mapSubscribePaths`);
+	*   - re-emit at the EXACT filter path so the bridged event matches what the
+	*     subscriber (PropBindSubscriber) asked for — SessionUserAFS then
+	*     re-prefixes the resolver-relative path back to `/instance/settings/...`.
+	*
+	* Two invariants make echo suppression + reset work:
+	*   1. ORIGIN PASSTHROUGH — `{ ...evt }` preserves `origin.sessionId`, so the
+	*      writer's own session is filtered out by PropBindSubscriber and a
+	*      different session still receives the patch. (The underlying write
+	*      carries origin only because `write()` now forwards `options.context`.)
+	*   2. TYPE NORMALIZATION — a user-layer DELETE (reset, D-f) is re-emitted as
+	*      `afs:write` because, from the cascade's point of view, the effective
+	*      value changed (reverted to the instance default); subscribers re-read
+	*      either way. We therefore drop the type filter on the underlying
+	*      subscription so deletes are not missed.
+	*/
+	subscribe(filter, callback) {
+		const rawPath = typeof filter.path === "string" ? filter.path || "/" : "/";
+		const relPath = this.normalizeSub(rawPath);
+		const { instancePath, userPath, isField } = mapSubscribePaths(relPath);
+		const emit = (evt, layer) => {
+			const path = isField ? relPath : this.underlyingToRelative(evt.path, layer);
+			callback({
+				...evt,
+				type: "afs:write",
+				path
+			});
+		};
+		const unsubs = [];
+		if (this.base.subscribe) unsubs.push(this.base.subscribe({ path: instancePath }, (evt) => emit(evt, "instance")));
+		if (this.userProvider?.subscribe) unsubs.push(this.userProvider.subscribe({ path: userPath }, (evt) => emit(evt, "user")));
+		return () => {
+			for (const u of unsubs) try {
+				u();
+			} catch {}
+		};
+	}
+	setEventSink(sink) {
+		this.base.setEventSink?.(sink);
+		this.userProvider?.setEventSink?.(sink);
+	}
+};
+
+//#endregion
+export { SettingsResolver };
+//# sourceMappingURL=settings-resolver.mjs.map