@aigne/aos 0.2.0-beta

package/dist/session/session-user-afs.mjs

@@ -0,0 +1,896 @@
+import { ReplicationResolver, computeReplicationMountPrefix } from "./replication-resolver.mjs";
+import { SettingsResolver } from "./settings-resolver.mjs";
+import { joinURL } from "ufo";
+import { AFSDependencyError, AFSForbiddenError, AFSNotFoundError, AFSUnsupportedError, AFSValidationError, enforceEffectGate, execReflexiveRootDataAction, isReflexiveRootDataAction, makeNsLog, rootActionEffect, toBatchEntryFailure } from "@aigne/afs";
+
+//#region src/session/session-user-afs.ts
+const log = makeNsLog("aos");
+/**
+* Concurrency cap for hydrating index-search results with their real
+* `read()`-backed content (P5 search→index forward). Mirrors the existing
+* `SEARCH_CONCURRENCY = 8` in `packages/core/src/afs.ts` — same fan-out
+* shape (N paths → N reads), same bound (avoid pathological fan-out against
+* the per-caller DID Space backend on a single search).
+*/
+const INDEX_SEARCH_HYDRATE_CONCURRENCY = 8;
+/**
+* Minimal concurrency-bounded map — same small helper duplicated at each of
+* its other call sites (`packages/core/src/afs.ts`, `provider/base.ts`,
+* `blocklet/data-seed.ts`, `aos/src/http/handlers.ts`); not exported from a
+* shared module today, so this follows the existing convention rather than
+* introducing a new one.
+*/
+async function mapWithConcurrency(items, concurrency, fn) {
+	const results = new Array(items.length);
+	let nextIndex = 0;
+	const workerCount = Math.min(Math.max(1, concurrency), items.length);
+	await Promise.all(Array.from({ length: workerCount }, async () => {
+		while (nextIndex < items.length) {
+			const index = nextIndex++;
+			results[index] = await fn(items[index], index);
+		}
+	}));
+	return results;
+}
+/**
+* STATIC full set of overlay prefixes a SessionUserAFS may mount — the
+* anonymous-bearer denylist for signed raw URLs (afs-preview design §3).
+*
+* Deliberately NOT derived from an instance's `overlays` array: `/space` and
+* `/instance/settings` are conditionally mounted, so per-instance derivation
+* would drift with wiring. Fail-closed: an anonymous raw URL is refused for
+* these prefixes even when the issuing session didn't mount them.
+*
+* KEEP IN SYNC with the constructor below — the unit test enumerates this
+* set against the constructor's possible mounts, table-driven.
+*/
+const SESSION_OVERLAY_PREFIXES = [
+	"/user/index",
+	"/user",
+	"/tmp",
+	"/space",
+	"/instance/settings"
+];
+/**
+* Whether a (sanitized) path falls under any session-private overlay prefix.
+* Used by the raw-URL primitives to refuse anonymous bearer URLs for
+* session-private content (issue-side denial + verify-side second defense).
+*/
+function isSessionPrivatePath(path) {
+	return SESSION_OVERLAY_PREFIXES.some((p) => path === p || path.startsWith(`${p}/`));
+}
+/**
+* Guard the first-match-by-prefix invariant: no overlay may be preceded by
+* another whose prefix is a proper prefix of it (which would swallow its
+* paths). `/instance/settings` MUST come before any future `/instance` or `/`
+* overlay. Extracted + exported so the ordering contract is unit-testable
+* without reaching into the class. Throws on violation (a wiring bug).
+*/
+function assertOverlayOrder(prefixes) {
+	for (let i = 0; i < prefixes.length; i++) {
+		const current = prefixes[i];
+		if (current === void 0) continue;
+		for (let j = 0; j < i; j++) {
+			const earlier = prefixes[j];
+			if (earlier === void 0) continue;
+			const earlierAsDir = earlier === "/" ? "/" : `${earlier}/`;
+			if (current === earlier || current.startsWith(earlierAsDir)) throw new Error(`SessionUserAFS overlay order bug: "${earlier}" precedes and shadows "${current}" (first-match routing)`);
+		}
+	}
+}
+/** Strip an overlay prefix → provider-relative path (always leading-slash). */
+function subPath(normalized, prefix) {
+	if (normalized === prefix) return "/";
+	const rest = normalized.slice(prefix.length);
+	return rest.startsWith("/") ? rest : `/${rest}`;
+}
+/**
+* Synthetic directory entry for an overlay root, mirroring a real mount root.
+* `childrenCount: -1` (unknown) + `accessMode` live under `meta`, matching the
+* shape a real mount returns in `list("/")` / `stat()`.
+*/
+function overlayRootEntry(overlay) {
+	return {
+		id: overlay.id,
+		path: overlay.prefix,
+		meta: {
+			childrenCount: -1,
+			accessMode: overlay.provider?.accessMode ?? "readwrite"
+		}
+	};
+}
+var SessionUserAFS = class {
+	name;
+	accessMode = "readwrite";
+	overlays;
+	/**
+	* Named reference to the settings resolver overlay (the overlay table only
+	* stores it anonymously) so `beginRender`/`endRender` can proxy to it —
+	* settings-layering §2.B render boundary.
+	*/
+	settingsResolver;
+	constructor(base, userProvider, tmpProvider, sessionId, settingsResolver = null, spaceProvider, indexProvider, replicationOverlays, indexSearchRequired = indexProvider != null) {
+		this.base = base;
+		this.indexSearchRequired = indexSearchRequired;
+		this.name = `session-user:${sessionId}`;
+		this.overlays = [];
+		if (indexProvider !== void 0) this.overlays.push({
+			prefix: "/user/index",
+			id: "user-index",
+			provider: indexProvider,
+			rootVisible: false
+		});
+		this.overlays.push({
+			prefix: "/user",
+			id: "user",
+			provider: userProvider,
+			rootVisible: true
+		}, {
+			prefix: "/tmp",
+			id: "tmp",
+			provider: tmpProvider,
+			rootVisible: true
+		});
+		if (spaceProvider !== void 0) this.overlays.push({
+			prefix: "/space",
+			id: "space",
+			provider: spaceProvider,
+			rootVisible: true
+		});
+		this.settingsResolver = settingsResolver;
+		if (settingsResolver) this.overlays.push({
+			prefix: "/instance/settings",
+			id: "instance-settings",
+			provider: settingsResolver,
+			rootVisible: false
+		});
+		for (const ro of replicationOverlays ?? []) this.overlays.push({
+			...ro,
+			rootVisible: false
+		});
+		assertOverlayOrder(this.overlays.map((o) => o.prefix));
+	}
+	/** Match a path against the overlay table. Returns the overlay + sub-path. */
+	matchOverlay(path) {
+		const normalized = path.startsWith("/") ? path : `/${path}`;
+		for (const overlay of this.overlays) if (normalized === overlay.prefix || normalized.startsWith(`${overlay.prefix}/`)) return {
+			overlay,
+			sub: subPath(normalized, overlay.prefix)
+		};
+		return null;
+	}
+	/** Overlays that are actually backed (provider present). */
+	get activeOverlays() {
+		return this.overlays.filter((o) => o.provider != null);
+	}
+	/** Backed AND root-level overlays — the ones surfaced at `/` / in getMounts. */
+	get rootOverlays() {
+		return this.overlays.filter((o) => o.provider != null && o.rootVisible);
+	}
+	rejectMissing(path) {
+		throw new AFSNotFoundError(path);
+	}
+	/**
+	* Whether a write context originates from an untrusted network client.
+	* `callerOrigin` is a host-stamped, unforgeable marker (strip + trusted reset,
+	* see FORGEABLE_CONTEXT_FIELDS); internal code (seeding / cron / agent /
+	* operator CLI) carries no `callerOrigin`. Mirrors the reflexive effect gate's
+	* network check (`exec-effect-gate.ts`).
+	*/
+	isNetworkOrigin(context) {
+		return context?.callerOrigin === "network";
+	}
+	/**
+	* Caller-origin base-write gate (instance-write-authz §5.1). A network client
+	* may never bare-write a BASE-fallthrough path — any path NOT matched by an
+	* overlay (`/instance/<non-mediated>`, `/packages`, `/dev`, `/registry`, `/`).
+	* Authorized `/instance` writes must go through a resolver overlay
+	* (`/instance/settings` → SettingsResolver, future `/instance/app` →
+	* ReplicationResolver — each carries its own role/minRole gate) or internal
+	* trusted code (`callerOrigin: undefined`).
+	*
+	* Called ONLY on the base-fallthrough branch (overlay-matched paths never
+	* reach here). STRICTER than the effect gate: it rejects AUTHENTICATED network
+	* callers too (the effect gate lets `caller.did` through) — that authed-but-
+	* network reflexive base write is exactly Finding 1's live path.
+	*/
+	forbiddenBaseWrite(path) {
+		return new AFSForbiddenError(path, "network clients cannot write base paths; use a resolver overlay or internal code");
+	}
+	enforceBaseWriteGate(path, context) {
+		if (this.isNetworkOrigin(context)) throw this.forbiddenBaseWrite(path);
+	}
+	/** Re-prefix a provider-relative path back into the overlay namespace. */
+	reprefix(prefix, childPath) {
+		return childPath === "/" ? prefix : joinURL(prefix, childPath);
+	}
+	async list(path, options) {
+		const match = this.matchOverlay(path);
+		if (match) {
+			const { overlay, sub } = match;
+			if (!overlay.provider?.list) this.rejectMissing(path);
+			const result$1 = await overlay.provider.list(sub, options);
+			return {
+				...result$1,
+				data: (result$1.data ?? []).map((e) => ({
+					...e,
+					path: this.reprefix(overlay.prefix, e.path)
+				}))
+			};
+		}
+		const result = await this.base.list(path, options);
+		if ((path.startsWith("/") ? path : `/${path}`) === "/") {
+			const existing = new Set((result.data ?? []).map((e) => e.path));
+			const injected = this.rootOverlays.filter((o) => !existing.has(o.prefix)).map((o) => overlayRootEntry(o));
+			if (injected.length) return {
+				...result,
+				data: [...result.data ?? [], ...injected]
+			};
+		}
+		return result;
+	}
+	async read(path, options) {
+		options = this.withSelfContext(options);
+		const match = this.matchOverlay(path);
+		if (match) {
+			if (!match.overlay.provider?.read) this.rejectMissing(path);
+			return match.overlay.provider.read(match.sub, options);
+		}
+		if (!this.base.read) throw new Error("base.read not supported");
+		return this.base.read(path, options);
+	}
+	/**
+	* Overlay-dispatch for `presignRead` (preview-r2-direct §5a.2 / T1.2). Same
+	* routing as `read`: a matched overlay whose provider implements `presignRead`
+	* gets the sub-path; a base-fallthrough path (or an overlay provider without
+	* the capability) → `null` (fail-soft → the raw handler serves bytes itself).
+	*
+	* The meta-only ACL and the `null`-on-everything fail-soft live DEEPER (the
+	* `/user` overlay provider is a `ProjectionProvider` → core `AFS` (globalAFS),
+	* where the authoritative meta guard runs — §5a.2 "routing to the root
+	* computation"); this layer only forwards.
+	*
+	* This is the HANDLER-FACING surface (`scoped.afs`), so it owns the §5a.5
+	* "NEVER throws to the handler" guarantee end-to-end: a deeper layer that
+	* throws (e.g. a read-disabled `ProjectionProvider.checkOp("read")` →
+	* `AFSAccessModeError`) is caught here → `null` → the raw handler serves bytes
+	* itself (and the worker-serve read then re-applies that same gate). No URL
+	* can leak past a read-disabled / failing projection.
+	*/
+	async presignRead(path, opts) {
+		try {
+			const match = this.matchOverlay(path);
+			if (match) {
+				const provider = match.overlay.provider;
+				if (typeof provider?.presignRead !== "function") return null;
+				return await provider.presignRead(match.sub, opts) ?? null;
+			}
+			if (typeof this.base.presignRead !== "function") return null;
+			return await this.base.presignRead(path, opts) ?? null;
+		} catch {
+			return null;
+		}
+	}
+	async write(path, content, options) {
+		options = this.withSelfContext(options);
+		const match = this.matchOverlay(path);
+		if (match) {
+			if (!match.overlay.provider?.write) this.rejectMissing(path);
+			return match.overlay.provider.write(match.sub, content, options);
+		}
+		this.enforceBaseWriteGate(path, options?.context);
+		if (!this.base.write) throw new Error("base.write not supported");
+		return this.base.write(path, content, options);
+	}
+	async delete(path, options) {
+		options = this.withSelfContext(options);
+		const match = this.matchOverlay(path);
+		if (match) {
+			if (!match.overlay.provider?.delete) this.rejectMissing(path);
+			return match.overlay.provider.delete(match.sub, options);
+		}
+		this.enforceBaseWriteGate(path, options?.context);
+		if (!this.base.delete) throw new Error("base.delete not supported");
+		return this.base.delete(path, options);
+	}
+	/** Plan contiguous runs of entry indices by overlay identity (null = base). */
+	planOverlayRuns(paths) {
+		const runs = [];
+		for (let i = 0; i < paths.length; i++) {
+			const overlay = this.matchOverlay(paths[i])?.overlay ?? null;
+			const last = runs[runs.length - 1];
+			if (last && last.overlay === overlay) last.indices.push(i);
+			else runs.push({
+				overlay,
+				indices: [i]
+			});
+		}
+		return runs;
+	}
+	async batchWrite(entries, options) {
+		const ctx = this.withSelfContext(options ?? {}).context;
+		const results = new Array(entries.length);
+		for (const run of this.planOverlayRuns(entries.map((e) => e.path))) {
+			const provider = run.overlay?.provider;
+			if (run.overlay && provider && typeof provider.batchWrite === "function") {
+				const subEntries = run.indices.map((i) => ({
+					...entries[i],
+					path: subPath(entries[i].path, run.overlay.prefix),
+					options: {
+						...entries[i].options,
+						context: ctx
+					}
+				}));
+				try {
+					const r = await provider.batchWrite(subEntries, { context: ctx });
+					if (!Array.isArray(r?.results) || r.results.length !== subEntries.length) throw new Error(`Provider '${provider.name}' batchWrite returned ${r?.results?.length ?? 0} results for ${subEntries.length} entries`);
+					run.indices.forEach((i, j) => {
+						const entryResult = r.results[j];
+						const data = entryResult.data ? {
+							...entryResult.data,
+							path: this.reprefix(run.overlay.prefix, entryResult.data.path)
+						} : entryResult.data;
+						results[i] = {
+							...entryResult,
+							path: entries[i].path,
+							data
+						};
+					});
+				} catch (err) {
+					for (const i of run.indices) results[i] = toBatchEntryFailure(entries[i].path, err);
+				}
+				continue;
+			}
+			if (!run.overlay && typeof this.base.batchWrite === "function") {
+				if (this.isNetworkOrigin(ctx)) {
+					for (const i of run.indices) results[i] = toBatchEntryFailure(entries[i].path, this.forbiddenBaseWrite(entries[i].path));
+					continue;
+				}
+				const baseEntries = run.indices.map((i) => entries[i]);
+				const r = await this.base.batchWrite(baseEntries, { context: ctx });
+				run.indices.forEach((i, j) => {
+					results[i] = r.results[j];
+				});
+				continue;
+			}
+			for (const i of run.indices) {
+				const entry = entries[i];
+				try {
+					const payload = entry.content ?? {};
+					if (entry.patches) payload.patches = entry.patches;
+					const res = await this.write(entry.path, payload, {
+						...entry.options,
+						mode: entry.mode ?? entry.options?.mode,
+						context: ctx
+					});
+					results[i] = {
+						path: entry.path,
+						success: true,
+						data: res.data
+					};
+				} catch (err) {
+					results[i] = toBatchEntryFailure(entry.path, err);
+				}
+			}
+		}
+		const succeeded = results.filter((r) => r?.success).length;
+		return {
+			results,
+			succeeded,
+			failed: results.length - succeeded
+		};
+	}
+	async batchDelete(entries, options) {
+		const ctx = this.withSelfContext(options ?? {}).context;
+		const results = new Array(entries.length);
+		for (const run of this.planOverlayRuns(entries.map((e) => e.path))) {
+			const provider = run.overlay?.provider;
+			if (run.overlay && provider && typeof provider.batchDelete === "function") {
+				const subEntries = run.indices.map((i) => ({
+					...entries[i],
+					path: subPath(entries[i].path, run.overlay.prefix),
+					options: {
+						...entries[i].options,
+						context: ctx
+					}
+				}));
+				try {
+					const r = await provider.batchDelete(subEntries, { context: ctx });
+					if (!Array.isArray(r?.results) || r.results.length !== subEntries.length) throw new Error(`Provider '${provider.name}' batchDelete returned ${r?.results?.length ?? 0} results for ${subEntries.length} entries`);
+					run.indices.forEach((i, j) => {
+						results[i] = {
+							...r.results[j],
+							path: entries[i].path
+						};
+					});
+				} catch (err) {
+					for (const i of run.indices) results[i] = toBatchEntryFailure(entries[i].path, err);
+				}
+				continue;
+			}
+			if (!run.overlay && typeof this.base.batchDelete === "function") {
+				if (this.isNetworkOrigin(ctx)) {
+					for (const i of run.indices) results[i] = toBatchEntryFailure(entries[i].path, this.forbiddenBaseWrite(entries[i].path));
+					continue;
+				}
+				const baseEntries = run.indices.map((i) => entries[i]);
+				const r = await this.base.batchDelete(baseEntries, { context: ctx });
+				run.indices.forEach((i, j) => {
+					results[i] = r.results[j];
+				});
+				continue;
+			}
+			for (const i of run.indices) {
+				const entry = entries[i];
+				try {
+					await this.delete(entry.path, {
+						...entry.options,
+						recursive: entry.recursive ?? entry.options?.recursive,
+						context: ctx
+					});
+					results[i] = {
+						path: entry.path,
+						success: true
+					};
+				} catch (err) {
+					results[i] = toBatchEntryFailure(entry.path, err);
+				}
+			}
+		}
+		const succeeded = results.filter((r) => r?.success).length;
+		return {
+			results,
+			succeeded,
+			failed: results.length - succeeded
+		};
+	}
+	async batchRead(entries, options) {
+		const ctx = this.withSelfContext(options ?? {}).context;
+		const results = [];
+		let succeeded = 0;
+		for (const entry of entries) try {
+			const res = await this.read(entry.path, {
+				...entry.options,
+				context: ctx
+			});
+			results.push({
+				path: entry.path,
+				success: true,
+				data: res.data
+			});
+			succeeded++;
+		} catch (err) {
+			results.push(toBatchEntryFailure(entry.path, err));
+		}
+		return {
+			results,
+			succeeded,
+			failed: results.length - succeeded
+		};
+	}
+	async query(path, spec, options) {
+		const match = this.matchOverlay(path);
+		if (match) {
+			const { overlay, sub } = match;
+			if (!overlay.provider) this.rejectMissing(path);
+			if (!overlay.provider.query) throw new AFSUnsupportedError("query", `Provider for ${overlay.prefix} does not declare the collection query capability`);
+			const result = await overlay.provider.query(sub, spec, options);
+			if (!result?.entries?.length) return result;
+			return {
+				...result,
+				entries: result.entries.map((e) => ({
+					...e,
+					path: this.reprefix(overlay.prefix, e.path)
+				}))
+			};
+		}
+		if (!this.base.query) throw new AFSUnsupportedError("query", "base.query not supported");
+		return this.base.query(path, spec, options);
+	}
+	async stat(path, options) {
+		options = this.withSelfContext(options);
+		const match = this.matchOverlay(path);
+		if (match) {
+			const { overlay, sub } = match;
+			if (!overlay.provider) this.rejectMissing(path);
+			if (sub === "/") return { data: overlayRootEntry(overlay) };
+			if (!overlay.provider.stat) this.rejectMissing(path);
+			return overlay.provider.stat(sub, options);
+		}
+		if (!this.base.stat) throw new Error("base.stat not supported");
+		return this.base.stat(path, options);
+	}
+	async explain(path, options) {
+		const match = this.matchOverlay(path);
+		if (match) {
+			if (!match.overlay.provider?.explain) this.rejectMissing(path);
+			return match.overlay.provider.explain(match.sub, options);
+		}
+		if (!this.base.explain) throw new Error("base.explain not supported");
+		return this.base.explain(path, options);
+	}
+	/**
+	* Find the `/user/index` overlay's backing provider, or undefined when
+	* unmounted (no `index:` manifest section) OR reserved-null (blocklet
+	* declares `index:` but this caller has no DID / no callerDid — see
+	* `createSessionView`'s `indexProvider` doc).
+	*/
+	findIndexOverlay() {
+		return this.overlays.find((o) => o.prefix === "/user/index" && o.provider != null);
+	}
+	isAfsValidationError(err) {
+		const error = err;
+		return error?.code === "AFS_VALIDATION_ERROR" || error?.name === "AFSValidationError";
+	}
+	isAfsDependencyError(err) {
+		const error = err;
+		return error?.code === "AFS_DEPENDENCY_MISSING" || error?.name === "AFSDependencyError";
+	}
+	searchDiagnostics(path, query, options) {
+		const context = options?.context;
+		const filters = Array.isArray(options?.filters) ? options.filters : [];
+		return {
+			path,
+			queryLength: query.length,
+			limit: options?.limit,
+			cursor: Boolean(options?.cursor),
+			filterCount: filters.length,
+			filterTypes: filters.map((f) => f.type),
+			requestId: context?.requestId,
+			callerDid: context?.caller?.did ?? context?.userId,
+			callerRole: context?.caller?.role ?? context?.caller?.roles,
+			instanceDid: context?.instanceDid
+		};
+	}
+	rejectIndexSearchFallback(path, detail, diagnostics) {
+		log.warn("[search] /user/index unavailable; refusing DID Space native fallback", {
+			...diagnostics,
+			path,
+			fallback: false,
+			detail
+		});
+		throw new AFSDependencyError("session-user-afs", "search", "/user/index", `${detail}; refusing DID Space native search fallback for indexed path ${path}`);
+	}
+	/**
+	* Parse a `read()`-returned raw content string as JSON, matching the exact
+	* fail-soft convention `IndexFollower.indexEntry` uses when hydrating
+	* changelog rows (`providers/basic/index/src/follower.ts`): non-string
+	* content is passed through untouched; a string that isn't valid JSON is
+	* kept as the raw string rather than dropped. afs-list's `performSearch`
+	* (P5 forward contract) expects a resolved `content` object for JSON
+	* entries — this is what makes that true without a second copy of the
+	* parse-or-passthrough logic living in the hydration loop below.
+	*/
+	parseEntryContent(raw) {
+		if (typeof raw !== "string") return raw;
+		try {
+			return JSON.parse(raw);
+		} catch {
+			return raw;
+		}
+	}
+	/**
+	* Hydrate index-query hits (`{ entryPath, score, matchType }` — path only,
+	* no content) into full `AFSEntry` objects by reading each `entryPath`
+	* through THIS session view (so the caller's own `/user` overlay + its
+	* per-caller isolation applies a second time, on top of the index query's
+	* own `boundDomains` isolation — belt-and-suspenders, not redundant: see
+	* design.md P5 section). A stale entry (index has it, storage doesn't —
+	* e.g. a delete that hasn't reached the follower yet) fails the `read()`
+	* and is skipped rather than surfaced as a broken result.
+	*/
+	async hydrateSearchEntries(results) {
+		if (results.length === 0) return [];
+		const build = (r, data) => ({
+			...data,
+			id: r.entryPath,
+			path: r.entryPath,
+			content: this.parseEntryContent(data.content),
+			meta: {
+				...data.meta ?? {},
+				score: r.score,
+				matchType: r.matchType,
+				...r.explanation !== void 0 ? { explanation: r.explanation } : {},
+				...r.anchors !== void 0 ? { anchors: r.anchors } : {}
+			}
+		});
+		const matches = results.map((r) => this.matchOverlay(r.entryPath));
+		const first = matches[0];
+		const provider = first?.overlay.provider;
+		if (first && provider?.batchRead && matches.every((m) => m?.overlay.prefix === first.overlay.prefix)) try {
+			const batch = await provider.batchRead(matches.map((m) => ({ path: m.sub })));
+			const out = [];
+			for (let i = 0; i < results.length; i++) {
+				const res = batch.results[i];
+				if (res?.success && res.data) out.push(build(results[i], res.data));
+			}
+			return out;
+		} catch (err) {
+			log.warn("[search] batch hydrate failed, falling back to per-entry read:", err);
+		}
+		return (await mapWithConcurrency(results, INDEX_SEARCH_HYDRATE_CONCURRENCY, async (r) => {
+			try {
+				const { data } = await this.read(r.entryPath);
+				if (!data) return null;
+				return build(r, data);
+			} catch (err) {
+				log.warn(`[search] index hit "${r.entryPath}" failed to read (stale?), skipping:`, err);
+				return null;
+			}
+		})).filter((e) => e != null);
+	}
+	/**
+	* Search-verb forward contract (P5, design.md "search verb forwarding"):
+	* a `/user/**` search first tries the caller's semantic `/user/index`
+	* (when mounted with a real provider), scoping hits to the requested
+	* subtree and hydrating them with real content via `read()`. For blocklets
+	* whose manifest declares `index:`, the index is authoritative: failures are
+	* surfaced and DID Space native search is refused because it is an O(N)
+	* content scan. Legacy/no-index blocklets keep the old direct overlay search
+	* behavior. A successful empty index result is authoritative and returns an
+	* empty array. Index results and fallback results are never unioned. Any other
+	* overlay (`/user/index` addressed directly, `/tmp`, `/space`,
+	* `/instance/settings`, replication overlays) keeps its pre-existing
+	* single-overlay-search behavior unchanged.
+	*/
+	async search(path, query, options) {
+		const match = this.matchOverlay(path);
+		if (!match) return this.base.search(path, query, options);
+		const { overlay, sub } = match;
+		if (overlay.prefix === "/user") {
+			const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+			const diagnostics = this.searchDiagnostics(normalizedPath, query, options);
+			const indexProvider = this.findIndexOverlay()?.provider;
+			if (indexProvider?.exec) try {
+				const limit = options?.limit ?? 50;
+				const prefix = normalizedPath.endsWith("/") ? normalizedPath : `${normalizedPath}/`;
+				const filters = options?.filters;
+				const hasFilters = Array.isArray(filters) && filters.length > 0;
+				const explain = options?.explain === true;
+				const execResult = await indexProvider.exec("/.actions/query", {
+					text: query,
+					...hasFilters ? { anchors: filters } : {},
+					...options?.mode ? { mode: options.mode } : {},
+					opts: {
+						limit,
+						...options?.cursor ? { cursor: options.cursor } : {},
+						pathPrefix: prefix,
+						...hasFilters ? { anchorFilter: true } : {},
+						...explain ? { explain: true } : {}
+					}
+				}, { context: options?.context });
+				if (execResult.success) {
+					const raw = execResult.data ?? {};
+					const scoped = (raw.results ?? []).filter((r) => r.entryPath === normalizedPath || r.entryPath.startsWith(prefix));
+					if (scoped.length > 0) {
+						const hydrated = await this.hydrateSearchEntries(scoped);
+						log.debug("[search] /user/index query served", {
+							...diagnostics,
+							rawResults: raw.results?.length ?? 0,
+							scopedResults: scoped.length,
+							hydratedResults: hydrated.length,
+							fallback: false
+						});
+						return {
+							data: hydrated,
+							...raw.meta ? { meta: raw.meta } : {}
+						};
+					}
+					log.debug("[search] /user/index query returned no scoped results", {
+						...diagnostics,
+						rawResults: raw.results?.length ?? 0,
+						scopedResults: 0,
+						fallback: false
+					});
+					return {
+						data: [],
+						...raw.meta ? { meta: raw.meta } : {}
+					};
+				}
+				const indexError = execResult.error;
+				const failedCode = typeof indexError === "object" && indexError ? indexError.code : void 0;
+				const failedMessage = typeof indexError === "object" && indexError ? indexError.message ?? "index query failed" : indexError ?? "index query failed";
+				if (failedCode === "VALIDATION_ERROR" || failedCode === "AFS_VALIDATION_ERROR") {
+					log.warn("[search] /user/index query validation failed", {
+						...diagnostics,
+						code: failedCode,
+						error: failedMessage,
+						fallback: false
+					});
+					throw new AFSValidationError(failedMessage);
+				}
+				if (options?.cursor) throw new AFSValidationError(failedMessage);
+				if (this.indexSearchRequired) this.rejectIndexSearchFallback(normalizedPath, `index query failed${failedCode ? ` (${failedCode})` : ""}: ${failedMessage}`, diagnostics);
+				log.warn("[search] /user/index query failed, falling back to native search", {
+					...diagnostics,
+					code: failedCode,
+					error: failedMessage,
+					fallback: true
+				});
+			} catch (err) {
+				if (options?.cursor) throw err;
+				if (this.isAfsValidationError(err) || this.isAfsDependencyError(err)) throw err;
+				const message = err instanceof Error ? err.message : String(err);
+				if (this.indexSearchRequired) this.rejectIndexSearchFallback(normalizedPath, `index query threw: ${message}`, diagnostics);
+				log.warn("[search] /user/index query threw, falling back to native search", {
+					...diagnostics,
+					error: message,
+					fallback: true
+				});
+			}
+			else if (this.indexSearchRequired) this.rejectIndexSearchFallback(normalizedPath, "index provider unavailable", diagnostics);
+		}
+		if (!overlay.provider?.search) return { data: [] };
+		return overlay.provider.search(sub, query, options);
+	}
+	async exec(path, args, options) {
+		options = this.withSelfContext(options);
+		const match = this.matchOverlay(path);
+		if (match) {
+			if (!match.overlay.provider?.exec) this.rejectMissing(path);
+			return match.overlay.provider.exec(match.sub, args, options);
+		}
+		if (isReflexiveRootDataAction(path)) {
+			const context = options?.context;
+			enforceEffectGate({
+				effect: rootActionEffect(path.slice(10)) ?? "write",
+				context,
+				face: "session-reflexive",
+				path
+			});
+			const reflexiveAction = path.slice(10);
+			if ((reflexiveAction === "write" || reflexiveAction === "delete") && typeof args.path === "string" && !this.matchOverlay(args.path)) this.enforceBaseWriteGate(args.path, context);
+			const ctxOpts = context ? { context } : void 0;
+			return execReflexiveRootDataAction(path, args, {
+				read: (p) => this.read(p, ctxOpts),
+				list: (p) => this.list(p, ctxOpts),
+				query: (p, spec, o) => this.query(p, spec, {
+					...o,
+					...ctxOpts ?? {}
+				}),
+				write: (p, c, o) => this.write(p, c, {
+					...o,
+					...ctxOpts ?? {}
+				}),
+				delete: (p, o) => this.delete(p, {
+					...o,
+					...ctxOpts ?? {}
+				})
+			});
+		}
+		if (!this.base.exec) throw new Error("base.exec not supported");
+		return this.base.exec(path, args, options);
+	}
+	/**
+	* Inject `context.afs = this` so downstream provider handlers that call
+	* back into AFS (`ctx.context.afs.read`/`.write`/`.exec`/...) hit this
+	* overlaid session view — not the bare runtime root the provider was
+	* mounted into. Without this, the `/user` overlay (and any other per-
+	* caller overlay) is invisible to handler-internal AFS calls, so writes
+	* silently land on the global `/user` fs mount instead of the caller's
+	* DID-Space-projected `/user`.
+	*/
+	withSelfContext(options) {
+		const ctx = options?.context ?? {};
+		return {
+			...options ?? {},
+			context: {
+				...ctx,
+				afs: this
+			}
+		};
+	}
+	subscribe(filter, callback) {
+		const rawPath = typeof filter.path === "string" ? filter.path : "";
+		const normalized = rawPath ? rawPath.startsWith("/") ? rawPath : `/${rawPath}` : "";
+		if (normalized && normalized !== "/") {
+			const match = this.matchOverlay(normalized);
+			if (match) return this.subscribeOverlay(match.overlay, {
+				...filter,
+				path: match.sub
+			}, callback);
+			if (!this.base.subscribe) return () => {};
+			return this.base.subscribe(filter, callback);
+		}
+		const unsubs = [];
+		if (this.base.subscribe) unsubs.push(this.base.subscribe(filter, callback));
+		for (const overlay of this.activeOverlays) unsubs.push(this.subscribeOverlay(overlay, {
+			...filter,
+			path: "/"
+		}, callback));
+		return () => {
+			for (const u of unsubs) try {
+				u();
+			} catch {}
+		};
+	}
+	/**
+	* Subscribe one overlay's backing provider, re-prefixing bridged event paths
+	* back into the overlay namespace. No-op when the overlay is unbacked
+	* (anonymous `/user`) or its provider lacks `subscribe`.
+	*/
+	subscribeOverlay(overlay, filter, callback) {
+		const subscribe = overlay.provider?.subscribe;
+		if (!subscribe) return () => {};
+		return subscribe.call(overlay.provider, filter, (evt) => {
+			callback({
+				...evt,
+				path: this.reprefix(overlay.prefix, evt.path)
+			});
+		});
+	}
+	async beginRender(renderId) {
+		await this.settingsResolver?.beginRender?.(renderId);
+	}
+	endRender(renderId) {
+		this.settingsResolver?.endRender?.(renderId);
+	}
+	getMounts(namespace) {
+		const baseGetMounts = this.base.getMounts;
+		const mounts = [...baseGetMounts ? baseGetMounts.call(this.base, namespace) : []];
+		for (const overlay of this.rootOverlays) mounts.push({
+			namespace: namespace ?? null,
+			path: overlay.prefix,
+			module: overlay.provider,
+			status: "ready"
+		});
+		return mounts;
+	}
+	initializePhysicalPath(...args) {
+		return this.base.initializePhysicalPath(...args);
+	}
+	cleanupPhysicalPath(...args) {
+		return this.base.cleanupPhysicalPath(...args);
+	}
+	setEventSink(...args) {
+		this.base.setEventSink?.(...args);
+	}
+	setSecretCapability(...args) {
+		this.base.setSecretCapability?.(...args);
+	}
+};
+/**
+* Assemble a caller's per-session view: a SettingsResolver (instance+user
+* settings cascade, role-aware) wrapped by a SessionUserAFS (`/user` +
+* optional `/space` + `/tmp` + `/instance/settings`). This is the construction the daemon's
+* `buildSessionView` chokepoint delegates to — extracted so the role→resolver
+* wiring is unit-testable in isolation (the daemon's only remaining job is to
+* RESOLVE `role` from the verified session before calling this).
+*
+* The resolver always exists (even for anonymous / no role) so
+* `/instance/settings` carries correct capability hints + enforcement for every
+* caller — there is no bypass path.
+*/
+function createSessionView(opts) {
+	const settingsResolver = new SettingsResolver({
+		base: opts.base,
+		userProvider: opts.userProvider,
+		role: opts.role,
+		sessionId: opts.sessionId,
+		schema: opts.settingsSchema
+	});
+	let replicationOverlays;
+	if (opts.replicated && Object.keys(opts.replicated).length > 0) {
+		const mountPrefix = computeReplicationMountPrefix(opts.replicated);
+		const resolver = new ReplicationResolver({
+			collections: opts.replicated,
+			instanceBackend: opts.base,
+			userBackend: opts.userProvider,
+			settingsResolver,
+			callerDid: opts.callerDid ?? void 0,
+			callerRole: opts.role,
+			sessionId: opts.sessionId,
+			mountPrefix
+		});
+		replicationOverlays = [{
+			prefix: `/${mountPrefix}`,
+			id: "replication",
+			provider: resolver
+		}];
+	}
+	return new SessionUserAFS(opts.base, opts.userProvider, opts.tmpProvider, opts.sessionId, settingsResolver, opts.spaceProvider, opts.indexProvider, replicationOverlays, opts.indexSearchRequired ?? opts.indexProvider != null);
+}
+
+//#endregion
+export { SESSION_OVERLAY_PREFIXES, SessionUserAFS, assertOverlayOrder, createSessionView, isSessionPrivatePath };
+//# sourceMappingURL=session-user-afs.mjs.map