@aigne/aos 0.2.0-beta

package/dist/mount/index.d.cts

@@ -0,0 +1,3 @@
+import { MaterializedMount, ProviderDefinition, ProviderFactory, ResourceContribution, ResourceProjector } from "./types.cjs";
+import { MaterializeOptions, MaterializeOverlay, MaterializeResult, materializeProviderMount, redactError } from "./materializer.cjs";
+export { type MaterializeOptions, type MaterializeOverlay, type MaterializeResult, type MaterializedMount, type ProviderDefinition, type ProviderFactory, type ResourceContribution, type ResourceProjector, materializeProviderMount, redactError };

package/dist/mount/index.d.mts

@@ -0,0 +1,3 @@
+import { MaterializedMount, ProviderDefinition, ProviderFactory, ResourceContribution, ResourceProjector } from "./types.mjs";
+import { MaterializeOptions, MaterializeOverlay, MaterializeResult, materializeProviderMount, redactError } from "./materializer.mjs";
+export { type MaterializeOptions, type MaterializeOverlay, type MaterializeResult, type MaterializedMount, type ProviderDefinition, type ProviderFactory, type ResourceContribution, type ResourceProjector, materializeProviderMount, redactError };

package/dist/mount/index.mjs

@@ -0,0 +1,3 @@
+import { materializeProviderMount, redactError } from "./materializer.mjs";
+
+export { materializeProviderMount, redactError };

package/dist/mount/materializer.cjs

@@ -0,0 +1,167 @@
+let _aigne_afs = require("@aigne/afs");
+
+//#region src/mount/materializer.ts
+const log = (0, _aigne_afs.makeNsLog)("aos");
+/**
+* @internal
+*
+* Materialize a provider at `mountPath`:
+*   1. ask the factory to build `{ provider, resources?, contributions? }`
+*   2. mount the data provider
+*   3. dispatch every projector against `resources` (projectors decide
+*      whether they have anything to project — AUP projector reads `/aup`)
+*   4. dispatch overlays to projectors that match each overlay's `kind`
+*   5. on any failure, unmount everything that was mounted in this call
+*
+* Contributions are validated (size cap) and recorded as warnings — they
+* are NOT projected in the first stage. See planning doc Phase 6.
+*/
+async function materializeProviderMount(options) {
+	validateMountPath(options.mountPath);
+	validateProviderDefinition(options.definition);
+	validateProjectionFailure(options.projectionFailure);
+	const projectionFailure = options.projectionFailure ?? "rollback";
+	const materialized = await options.factory.create(options.definition);
+	if (!materialized?.provider) throw new _aigne_afs.AFSValidationError(`Provider factory returned no provider for ${options.definition.uri}`);
+	if (options.wrapProvider) materialized.provider = options.wrapProvider(materialized.provider);
+	if (options.mountOptions?.replace) cascadeUnmountUnder(options.afs, options.mountPath);
+	const baseline = snapshotMountPaths(options.afs);
+	let dataMounted = false;
+	try {
+		await options.afs.mount(materialized.provider, options.mountPath, options.mountOptions);
+		dataMounted = true;
+		if (materialized.resources) for (const projector of options.projectors) {
+			const beforeProjection = snapshotMountPaths(options.afs);
+			try {
+				await projector.project({
+					afs: options.afs,
+					mountPath: options.mountPath,
+					resources: materialized.resources,
+					scope: options.scope
+				});
+			} catch (err) {
+				if (projectionFailure === "warn") {
+					rollbackSupplementsSince(options.afs, beforeProjection, options.mountPath);
+					log.warn(`[aos/mount] resources projection failed for ${options.mountPath} (projector=${projector.kind}): ${redactError(err)}`);
+					continue;
+				}
+				throw err;
+			}
+		}
+		for (const overlay of options.overlays ?? []) for (const projector of options.projectors) {
+			if (projector.kind !== overlay.kind) continue;
+			const beforeOverlayProjection = snapshotMountPaths(options.afs);
+			try {
+				await projector.project({
+					afs: options.afs,
+					mountPath: options.mountPath,
+					resources: overlay.resources,
+					scope: options.scope
+				});
+			} catch (err) {
+				if (projectionFailure === "warn") {
+					rollbackSupplementsSince(options.afs, beforeOverlayProjection, options.mountPath);
+					log.warn(`[aos/mount] overlay projection failed for ${options.mountPath} (projector=${projector.kind}, overlay=${overlay.kind}): ${redactError(err)}`);
+					continue;
+				}
+				throw err;
+			}
+		}
+		warnUnsupportedContributions(materialized.contributions, options.mountPath);
+		return {
+			provider: materialized.provider,
+			mountedResourceMounts: supplementsSince(options.afs, baseline, options.mountPath)
+		};
+	} catch (error) {
+		rollback(options.afs, baseline, dataMounted ? options.mountPath : null);
+		throw error;
+	}
+}
+function validateMountPath(mountPath) {
+	if (typeof mountPath !== "string" || mountPath.length === 0) throw new _aigne_afs.AFSValidationError("mountPath must be a non-empty string");
+	if (mountPath === "/") throw new _aigne_afs.AFSValidationError("mountPath cannot be '/' — root is reserved");
+	if (!mountPath.startsWith("/")) throw new _aigne_afs.AFSValidationError(`mountPath must start with '/' (got '${mountPath}')`);
+	if (mountPath.split("/").some((segment) => segment === "..")) throw new _aigne_afs.AFSValidationError(`mountPath cannot contain '..' segments (got '${mountPath}')`);
+}
+function validateProviderDefinition(definition) {
+	if (!definition || typeof definition !== "object") throw new _aigne_afs.AFSValidationError("definition must be an object");
+	if (typeof definition.uri !== "string" || definition.uri.length === 0) throw new _aigne_afs.AFSValidationError("definition.uri must be a non-empty string");
+	if (typeof definition.type !== "string" || definition.type.length === 0) throw new _aigne_afs.AFSValidationError("definition.type must be a non-empty string");
+}
+function validateProjectionFailure(value) {
+	if (value === void 0 || value === "rollback" || value === "warn") return;
+	throw new _aigne_afs.AFSValidationError(`projectionFailure must be "rollback" or "warn" (got ${JSON.stringify(value)})`);
+}
+function snapshotMountPaths(afs) {
+	const paths = /* @__PURE__ */ new Set();
+	for (const mount of afs.getMounts(null)) paths.add(mount.path);
+	return paths;
+}
+function supplementsSince(afs, baseline, dataPath) {
+	const added = [];
+	for (const mount of afs.getMounts(null)) if (!baseline.has(mount.path) && mount.path !== dataPath) added.push(mount.path);
+	return added;
+}
+function rollback(afs, baseline, dataPath) {
+	const supplements = supplementsSince(afs, baseline, dataPath);
+	supplements.sort((a, b) => b.length - a.length);
+	for (const path of supplements) safeUnmount(afs, path);
+	if (dataPath) safeUnmount(afs, dataPath);
+}
+/**
+* Roll back only the supplements created since `baseline` (i.e. by the
+* single failing projector). Used by `projectionFailure: "warn"` so the
+* data mount and previously-succeeded projector outputs survive.
+*/
+function rollbackSupplementsSince(afs, baseline, dataPath) {
+	const supplements = supplementsSince(afs, baseline, dataPath);
+	supplements.sort((a, b) => b.length - a.length);
+	for (const path of supplements) safeUnmount(afs, path);
+}
+/**
+* Produce a short, redacted error description suitable for log lines.
+* Truncates message to ~200 chars and drops stack/url so token-bearing
+* URLs and full SDK stack frames cannot leak into shared logs.
+*/
+function redactError(err) {
+	if (err instanceof Error) {
+		const msg = err.message ?? "";
+		const truncated = msg.length > 200 ? `${msg.slice(0, 200)}…` : msg;
+		return `${err.name}: ${truncated}`;
+	}
+	const s = typeof err === "string" ? err : JSON.stringify(err);
+	return s.length > 200 ? `${s.slice(0, 200)}…` : s;
+}
+/**
+* Cascade-unmount every mount at or under `parentPath`. Used when a
+* caller passes `mountOptions.replace: true` — without this, supplement
+* mounts projected by a previous materialize call survive the exact-path
+* replace inside `afs.mount` and the new mount trips the AFS parent-child
+* conflict guard.
+*
+* Order matters: longest paths first so children unmount before parents,
+* keeping each individual `afs.unmount` call within an internally
+* consistent mount tree.
+*/
+function cascadeUnmountUnder(afs, parentPath) {
+	const prefix = parentPath.endsWith("/") ? parentPath : `${parentPath}/`;
+	const descendants = [];
+	for (const mount of afs.getMounts(null)) if (mount.path === parentPath || mount.path.startsWith(prefix)) descendants.push(mount.path);
+	descendants.sort((a, b) => b.length - a.length);
+	for (const path of descendants) safeUnmount(afs, path);
+}
+function safeUnmount(afs, path) {
+	try {
+		afs.unmount(path);
+	} catch (error) {
+		log.warn(`[aos/mount] rollback unmount failed for ${path}:`, error);
+	}
+}
+function warnUnsupportedContributions(contributions, mountPath) {
+	if (!contributions?.length) return;
+	log.warn(`[aos/mount] ignoring ${contributions.length} contribution(s) declared by provider at ${mountPath} — first-stage materializer does not project contributions; see planning/afs-ui/aup-mount-materialization Phase 6`);
+}
+
+//#endregion
+exports.materializeProviderMount = materializeProviderMount;
+exports.redactError = redactError;

package/dist/mount/materializer.d.cts

@@ -0,0 +1,97 @@
+import { ProviderDefinition, ProviderFactory, ResourceProjector } from "./types.cjs";
+import { AFS, AFSModule, MountOptions } from "@aigne/afs";
+
+//#region src/mount/materializer.d.ts
+/**
+ * @internal
+ * An overlay is an out-of-band resource bundle (typically blocklet-local)
+ * that the materializer dispatches to projectors with the matching `kind`.
+ */
+interface MaterializeOverlay {
+  kind: string;
+  resources: AFSModule;
+}
+/**
+ * @internal
+ * Inputs to {@link materializeProviderMount}.
+ */
+interface MaterializeOptions {
+  afs: AFS;
+  mountPath: string;
+  definition: ProviderDefinition;
+  factory: ProviderFactory;
+  projectors: ResourceProjector[];
+  overlays?: MaterializeOverlay[];
+  scope: "host" | "blocklet" | "instance";
+  /**
+   * Forwarded to `afs.mount()` for the data provider only.
+   *
+   * Phase 3 entry-point migrations pass through `replace`, `allowOverlay`,
+   * and `namespace` so the materializer is a drop-in replacement for the
+   * direct `afs.mount(...)` calls those entries use today.
+   *
+   * Supplement mounts (.aup/...) are managed by the projectors and never
+   * inherit these options — supplements are always hidden, namespace-less,
+   * non-overlapping mounts.
+   */
+  mountOptions?: MountOptions;
+  /**
+   * Optional post-factory provider transform. When supplied, the
+   * materializer applies it to the provider returned by
+   * `factory.create(definition)` before mounting. Used by callers that
+   * need to wrap the provider with cross-cutting concerns the factory
+   * itself can't observe — most notably the global-config mount loop's
+   * `maybeWrapWithCache` (provider manifest's cache declaration vs. the
+   * mount config's cache override).
+   *
+   * Returning the same provider unchanged is fine; returning a wrapping
+   * provider is fine; returning a completely different provider is
+   * fine — the materializer treats this hook as opaque.
+   */
+  wrapProvider?: (provider: AFSModule) => AFSModule;
+  /**
+   * Strategy when a projector throws:
+   * - "rollback" (default): unmount data + any partial supplements, rethrow.
+   *   Owned-mount semantics — appropriate for blocklets where the mount is
+   *   atomic with its supplements.
+   * - "warn": keep data mount + previously-succeeded projector supplements;
+   *   roll back only the failing projector's partial supplements; log a
+   *   warning; continue to the next projector. Host-scope semantics — data
+   *   is independently usable without supplements.
+   */
+  projectionFailure?: "rollback" | "warn";
+}
+/**
+ * @internal
+ * Result of {@link materializeProviderMount}. Includes the mounted
+ * provider plus any supplement paths added by projectors so callers can
+ * unmount them later (e.g., during reload).
+ */
+interface MaterializeResult {
+  provider: AFSModule;
+  mountedResourceMounts: string[];
+}
+/**
+ * @internal
+ *
+ * Materialize a provider at `mountPath`:
+ *   1. ask the factory to build `{ provider, resources?, contributions? }`
+ *   2. mount the data provider
+ *   3. dispatch every projector against `resources` (projectors decide
+ *      whether they have anything to project — AUP projector reads `/aup`)
+ *   4. dispatch overlays to projectors that match each overlay's `kind`
+ *   5. on any failure, unmount everything that was mounted in this call
+ *
+ * Contributions are validated (size cap) and recorded as warnings — they
+ * are NOT projected in the first stage. See planning doc Phase 6.
+ */
+declare function materializeProviderMount(options: MaterializeOptions): Promise<MaterializeResult>;
+/**
+ * Produce a short, redacted error description suitable for log lines.
+ * Truncates message to ~200 chars and drops stack/url so token-bearing
+ * URLs and full SDK stack frames cannot leak into shared logs.
+ */
+declare function redactError(err: unknown): string;
+//#endregion
+export { MaterializeOptions, MaterializeOverlay, MaterializeResult, materializeProviderMount, redactError };
+//# sourceMappingURL=materializer.d.cts.map

package/dist/mount/materializer.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"materializer.d.cts","names":[],"sources":["../../src/mount/materializer.ts"],"mappings":";;;;AAqCA;;;;;AAAA,UATiB,kBAAA;EACf,IAAA;EACA,SAAA,EAAW,SAAA;AAAA;;;;;UAOI,kBAAA;EACf,GAAA,EAAK,GAAA;EACL,SAAA;EACA,UAAA,EAAY,kBAAA;EACZ,OAAA,EAAS,eAAA;EACT,UAAA,EAAY,iBAAA;EACZ,QAAA,GAAW,kBAAA;EACX,KAAA;EAFY;;;;;;;;;;;EAcZ,YAAA,GAAe,YAAA;EAyBE;AASnB;;;;;;;;;AAmBA;;;EAvCE,YAAA,IAAgB,QAAA,EAAU,SAAA,KAAc,SAAA;EAyC/B;;;;;;;;;;EA9BT,iBAAA;AAAA;;;;;;;UASe,iBAAA;EACf,QAAA,EAAU,SAAA;EACV,qBAAA;AAAA;;;;;;;;;;;;;;;iBAiBoB,wBAAA,CACpB,OAAA,EAAS,kBAAA,GACR,OAAA,CAAQ,iBAAA;;;;;;iBAkLK,WAAA,CAAY,GAAA"}

package/dist/mount/materializer.d.mts

@@ -0,0 +1,97 @@
+import { ProviderDefinition, ProviderFactory, ResourceProjector } from "./types.mjs";
+import { AFS, AFSModule, MountOptions } from "@aigne/afs";
+
+//#region src/mount/materializer.d.ts
+/**
+ * @internal
+ * An overlay is an out-of-band resource bundle (typically blocklet-local)
+ * that the materializer dispatches to projectors with the matching `kind`.
+ */
+interface MaterializeOverlay {
+  kind: string;
+  resources: AFSModule;
+}
+/**
+ * @internal
+ * Inputs to {@link materializeProviderMount}.
+ */
+interface MaterializeOptions {
+  afs: AFS;
+  mountPath: string;
+  definition: ProviderDefinition;
+  factory: ProviderFactory;
+  projectors: ResourceProjector[];
+  overlays?: MaterializeOverlay[];
+  scope: "host" | "blocklet" | "instance";
+  /**
+   * Forwarded to `afs.mount()` for the data provider only.
+   *
+   * Phase 3 entry-point migrations pass through `replace`, `allowOverlay`,
+   * and `namespace` so the materializer is a drop-in replacement for the
+   * direct `afs.mount(...)` calls those entries use today.
+   *
+   * Supplement mounts (.aup/...) are managed by the projectors and never
+   * inherit these options — supplements are always hidden, namespace-less,
+   * non-overlapping mounts.
+   */
+  mountOptions?: MountOptions;
+  /**
+   * Optional post-factory provider transform. When supplied, the
+   * materializer applies it to the provider returned by
+   * `factory.create(definition)` before mounting. Used by callers that
+   * need to wrap the provider with cross-cutting concerns the factory
+   * itself can't observe — most notably the global-config mount loop's
+   * `maybeWrapWithCache` (provider manifest's cache declaration vs. the
+   * mount config's cache override).
+   *
+   * Returning the same provider unchanged is fine; returning a wrapping
+   * provider is fine; returning a completely different provider is
+   * fine — the materializer treats this hook as opaque.
+   */
+  wrapProvider?: (provider: AFSModule) => AFSModule;
+  /**
+   * Strategy when a projector throws:
+   * - "rollback" (default): unmount data + any partial supplements, rethrow.
+   *   Owned-mount semantics — appropriate for blocklets where the mount is
+   *   atomic with its supplements.
+   * - "warn": keep data mount + previously-succeeded projector supplements;
+   *   roll back only the failing projector's partial supplements; log a
+   *   warning; continue to the next projector. Host-scope semantics — data
+   *   is independently usable without supplements.
+   */
+  projectionFailure?: "rollback" | "warn";
+}
+/**
+ * @internal
+ * Result of {@link materializeProviderMount}. Includes the mounted
+ * provider plus any supplement paths added by projectors so callers can
+ * unmount them later (e.g., during reload).
+ */
+interface MaterializeResult {
+  provider: AFSModule;
+  mountedResourceMounts: string[];
+}
+/**
+ * @internal
+ *
+ * Materialize a provider at `mountPath`:
+ *   1. ask the factory to build `{ provider, resources?, contributions? }`
+ *   2. mount the data provider
+ *   3. dispatch every projector against `resources` (projectors decide
+ *      whether they have anything to project — AUP projector reads `/aup`)
+ *   4. dispatch overlays to projectors that match each overlay's `kind`
+ *   5. on any failure, unmount everything that was mounted in this call
+ *
+ * Contributions are validated (size cap) and recorded as warnings — they
+ * are NOT projected in the first stage. See planning doc Phase 6.
+ */
+declare function materializeProviderMount(options: MaterializeOptions): Promise<MaterializeResult>;
+/**
+ * Produce a short, redacted error description suitable for log lines.
+ * Truncates message to ~200 chars and drops stack/url so token-bearing
+ * URLs and full SDK stack frames cannot leak into shared logs.
+ */
+declare function redactError(err: unknown): string;
+//#endregion
+export { MaterializeOptions, MaterializeOverlay, MaterializeResult, materializeProviderMount, redactError };
+//# sourceMappingURL=materializer.d.mts.map

package/dist/mount/materializer.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"materializer.d.mts","names":[],"sources":["../../src/mount/materializer.ts"],"mappings":";;;;AAqCA;;;;;AAAA,UATiB,kBAAA;EACf,IAAA;EACA,SAAA,EAAW,SAAA;AAAA;;;;;UAOI,kBAAA;EACf,GAAA,EAAK,GAAA;EACL,SAAA;EACA,UAAA,EAAY,kBAAA;EACZ,OAAA,EAAS,eAAA;EACT,UAAA,EAAY,iBAAA;EACZ,QAAA,GAAW,kBAAA;EACX,KAAA;EAFY;;;;;;;;;;;EAcZ,YAAA,GAAe,YAAA;EAyBE;AASnB;;;;;;;;;AAmBA;;;EAvCE,YAAA,IAAgB,QAAA,EAAU,SAAA,KAAc,SAAA;EAyC/B;;;;;;;;;;EA9BT,iBAAA;AAAA;;;;;;;UASe,iBAAA;EACf,QAAA,EAAU,SAAA;EACV,qBAAA;AAAA;;;;;;;;;;;;;;;iBAiBoB,wBAAA,CACpB,OAAA,EAAS,kBAAA,GACR,OAAA,CAAQ,iBAAA;;;;;;iBAkLK,WAAA,CAAY,GAAA"}

package/dist/mount/materializer.mjs

@@ -0,0 +1,167 @@
+import { AFSValidationError, makeNsLog } from "@aigne/afs";
+
+//#region src/mount/materializer.ts
+const log = makeNsLog("aos");
+/**
+* @internal
+*
+* Materialize a provider at `mountPath`:
+*   1. ask the factory to build `{ provider, resources?, contributions? }`
+*   2. mount the data provider
+*   3. dispatch every projector against `resources` (projectors decide
+*      whether they have anything to project — AUP projector reads `/aup`)
+*   4. dispatch overlays to projectors that match each overlay's `kind`
+*   5. on any failure, unmount everything that was mounted in this call
+*
+* Contributions are validated (size cap) and recorded as warnings — they
+* are NOT projected in the first stage. See planning doc Phase 6.
+*/
+async function materializeProviderMount(options) {
+	validateMountPath(options.mountPath);
+	validateProviderDefinition(options.definition);
+	validateProjectionFailure(options.projectionFailure);
+	const projectionFailure = options.projectionFailure ?? "rollback";
+	const materialized = await options.factory.create(options.definition);
+	if (!materialized?.provider) throw new AFSValidationError(`Provider factory returned no provider for ${options.definition.uri}`);
+	if (options.wrapProvider) materialized.provider = options.wrapProvider(materialized.provider);
+	if (options.mountOptions?.replace) cascadeUnmountUnder(options.afs, options.mountPath);
+	const baseline = snapshotMountPaths(options.afs);
+	let dataMounted = false;
+	try {
+		await options.afs.mount(materialized.provider, options.mountPath, options.mountOptions);
+		dataMounted = true;
+		if (materialized.resources) for (const projector of options.projectors) {
+			const beforeProjection = snapshotMountPaths(options.afs);
+			try {
+				await projector.project({
+					afs: options.afs,
+					mountPath: options.mountPath,
+					resources: materialized.resources,
+					scope: options.scope
+				});
+			} catch (err) {
+				if (projectionFailure === "warn") {
+					rollbackSupplementsSince(options.afs, beforeProjection, options.mountPath);
+					log.warn(`[aos/mount] resources projection failed for ${options.mountPath} (projector=${projector.kind}): ${redactError(err)}`);
+					continue;
+				}
+				throw err;
+			}
+		}
+		for (const overlay of options.overlays ?? []) for (const projector of options.projectors) {
+			if (projector.kind !== overlay.kind) continue;
+			const beforeOverlayProjection = snapshotMountPaths(options.afs);
+			try {
+				await projector.project({
+					afs: options.afs,
+					mountPath: options.mountPath,
+					resources: overlay.resources,
+					scope: options.scope
+				});
+			} catch (err) {
+				if (projectionFailure === "warn") {
+					rollbackSupplementsSince(options.afs, beforeOverlayProjection, options.mountPath);
+					log.warn(`[aos/mount] overlay projection failed for ${options.mountPath} (projector=${projector.kind}, overlay=${overlay.kind}): ${redactError(err)}`);
+					continue;
+				}
+				throw err;
+			}
+		}
+		warnUnsupportedContributions(materialized.contributions, options.mountPath);
+		return {
+			provider: materialized.provider,
+			mountedResourceMounts: supplementsSince(options.afs, baseline, options.mountPath)
+		};
+	} catch (error) {
+		rollback(options.afs, baseline, dataMounted ? options.mountPath : null);
+		throw error;
+	}
+}
+function validateMountPath(mountPath) {
+	if (typeof mountPath !== "string" || mountPath.length === 0) throw new AFSValidationError("mountPath must be a non-empty string");
+	if (mountPath === "/") throw new AFSValidationError("mountPath cannot be '/' — root is reserved");
+	if (!mountPath.startsWith("/")) throw new AFSValidationError(`mountPath must start with '/' (got '${mountPath}')`);
+	if (mountPath.split("/").some((segment) => segment === "..")) throw new AFSValidationError(`mountPath cannot contain '..' segments (got '${mountPath}')`);
+}
+function validateProviderDefinition(definition) {
+	if (!definition || typeof definition !== "object") throw new AFSValidationError("definition must be an object");
+	if (typeof definition.uri !== "string" || definition.uri.length === 0) throw new AFSValidationError("definition.uri must be a non-empty string");
+	if (typeof definition.type !== "string" || definition.type.length === 0) throw new AFSValidationError("definition.type must be a non-empty string");
+}
+function validateProjectionFailure(value) {
+	if (value === void 0 || value === "rollback" || value === "warn") return;
+	throw new AFSValidationError(`projectionFailure must be "rollback" or "warn" (got ${JSON.stringify(value)})`);
+}
+function snapshotMountPaths(afs) {
+	const paths = /* @__PURE__ */ new Set();
+	for (const mount of afs.getMounts(null)) paths.add(mount.path);
+	return paths;
+}
+function supplementsSince(afs, baseline, dataPath) {
+	const added = [];
+	for (const mount of afs.getMounts(null)) if (!baseline.has(mount.path) && mount.path !== dataPath) added.push(mount.path);
+	return added;
+}
+function rollback(afs, baseline, dataPath) {
+	const supplements = supplementsSince(afs, baseline, dataPath);
+	supplements.sort((a, b) => b.length - a.length);
+	for (const path of supplements) safeUnmount(afs, path);
+	if (dataPath) safeUnmount(afs, dataPath);
+}
+/**
+* Roll back only the supplements created since `baseline` (i.e. by the
+* single failing projector). Used by `projectionFailure: "warn"` so the
+* data mount and previously-succeeded projector outputs survive.
+*/
+function rollbackSupplementsSince(afs, baseline, dataPath) {
+	const supplements = supplementsSince(afs, baseline, dataPath);
+	supplements.sort((a, b) => b.length - a.length);
+	for (const path of supplements) safeUnmount(afs, path);
+}
+/**
+* Produce a short, redacted error description suitable for log lines.
+* Truncates message to ~200 chars and drops stack/url so token-bearing
+* URLs and full SDK stack frames cannot leak into shared logs.
+*/
+function redactError(err) {
+	if (err instanceof Error) {
+		const msg = err.message ?? "";
+		const truncated = msg.length > 200 ? `${msg.slice(0, 200)}…` : msg;
+		return `${err.name}: ${truncated}`;
+	}
+	const s = typeof err === "string" ? err : JSON.stringify(err);
+	return s.length > 200 ? `${s.slice(0, 200)}…` : s;
+}
+/**
+* Cascade-unmount every mount at or under `parentPath`. Used when a
+* caller passes `mountOptions.replace: true` — without this, supplement
+* mounts projected by a previous materialize call survive the exact-path
+* replace inside `afs.mount` and the new mount trips the AFS parent-child
+* conflict guard.
+*
+* Order matters: longest paths first so children unmount before parents,
+* keeping each individual `afs.unmount` call within an internally
+* consistent mount tree.
+*/
+function cascadeUnmountUnder(afs, parentPath) {
+	const prefix = parentPath.endsWith("/") ? parentPath : `${parentPath}/`;
+	const descendants = [];
+	for (const mount of afs.getMounts(null)) if (mount.path === parentPath || mount.path.startsWith(prefix)) descendants.push(mount.path);
+	descendants.sort((a, b) => b.length - a.length);
+	for (const path of descendants) safeUnmount(afs, path);
+}
+function safeUnmount(afs, path) {
+	try {
+		afs.unmount(path);
+	} catch (error) {
+		log.warn(`[aos/mount] rollback unmount failed for ${path}:`, error);
+	}
+}
+function warnUnsupportedContributions(contributions, mountPath) {
+	if (!contributions?.length) return;
+	log.warn(`[aos/mount] ignoring ${contributions.length} contribution(s) declared by provider at ${mountPath} — first-stage materializer does not project contributions; see planning/afs-ui/aup-mount-materialization Phase 6`);
+}
+
+//#endregion
+export { materializeProviderMount, redactError };
+//# sourceMappingURL=materializer.mjs.map

package/dist/mount/materializer.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"materializer.mjs","names":[],"sources":["../../src/mount/materializer.ts"],"sourcesContent":["/**\n * @internal\n *\n * Mount materialization entry point. Wires the data provider, owned\n * resources, and overlays through one consistent lifecycle so every\n * runtime entry that creates a provider mount produces the same\n * observable AFS shape.\n *\n * Subpath-only export: `@aigne/aos/mount`. Not part of the @aigne/aos\n * root contract.\n */\n\nimport type { AFS, AFSModule, MountOptions } from \"@aigne/afs\";\nimport { AFSValidationError, makeNsLog } from \"@aigne/afs\";\nimport type {\n  ProviderDefinition,\n  ProviderFactory,\n  ResourceContribution,\n  ResourceProjector,\n} from \"./types.js\";\n\nconst log = makeNsLog(\"aos\");\n\n/**\n * @internal\n * An overlay is an out-of-band resource bundle (typically blocklet-local)\n * that the materializer dispatches to projectors with the matching `kind`.\n */\nexport interface MaterializeOverlay {\n  kind: string;\n  resources: AFSModule;\n}\n\n/**\n * @internal\n * Inputs to {@link materializeProviderMount}.\n */\nexport interface MaterializeOptions {\n  afs: AFS;\n  mountPath: string;\n  definition: ProviderDefinition;\n  factory: ProviderFactory;\n  projectors: ResourceProjector[];\n  overlays?: MaterializeOverlay[];\n  scope: \"host\" | \"blocklet\" | \"instance\";\n  /**\n   * Forwarded to `afs.mount()` for the data provider only.\n   *\n   * Phase 3 entry-point migrations pass through `replace`, `allowOverlay`,\n   * and `namespace` so the materializer is a drop-in replacement for the\n   * direct `afs.mount(...)` calls those entries use today.\n   *\n   * Supplement mounts (.aup/...) are managed by the projectors and never\n   * inherit these options — supplements are always hidden, namespace-less,\n   * non-overlapping mounts.\n   */\n  mountOptions?: MountOptions;\n  /**\n   * Optional post-factory provider transform. When supplied, the\n   * materializer applies it to the provider returned by\n   * `factory.create(definition)` before mounting. Used by callers that\n   * need to wrap the provider with cross-cutting concerns the factory\n   * itself can't observe — most notably the global-config mount loop's\n   * `maybeWrapWithCache` (provider manifest's cache declaration vs. the\n   * mount config's cache override).\n   *\n   * Returning the same provider unchanged is fine; returning a wrapping\n   * provider is fine; returning a completely different provider is\n   * fine — the materializer treats this hook as opaque.\n   */\n  wrapProvider?: (provider: AFSModule) => AFSModule;\n  /**\n   * Strategy when a projector throws:\n   * - \"rollback\" (default): unmount data + any partial supplements, rethrow.\n   *   Owned-mount semantics — appropriate for blocklets where the mount is\n   *   atomic with its supplements.\n   * - \"warn\": keep data mount + previously-succeeded projector supplements;\n   *   roll back only the failing projector's partial supplements; log a\n   *   warning; continue to the next projector. Host-scope semantics — data\n   *   is independently usable without supplements.\n   */\n  projectionFailure?: \"rollback\" | \"warn\";\n}\n\n/**\n * @internal\n * Result of {@link materializeProviderMount}. Includes the mounted\n * provider plus any supplement paths added by projectors so callers can\n * unmount them later (e.g., during reload).\n */\nexport interface MaterializeResult {\n  provider: AFSModule;\n  mountedResourceMounts: string[];\n}\n\n/**\n * @internal\n *\n * Materialize a provider at `mountPath`:\n *   1. ask the factory to build `{ provider, resources?, contributions? }`\n *   2. mount the data provider\n *   3. dispatch every projector against `resources` (projectors decide\n *      whether they have anything to project — AUP projector reads `/aup`)\n *   4. dispatch overlays to projectors that match each overlay's `kind`\n *   5. on any failure, unmount everything that was mounted in this call\n *\n * Contributions are validated (size cap) and recorded as warnings — they\n * are NOT projected in the first stage. See planning doc Phase 6.\n */\nexport async function materializeProviderMount(\n  options: MaterializeOptions,\n): Promise<MaterializeResult> {\n  validateMountPath(options.mountPath);\n  validateProviderDefinition(options.definition);\n  validateProjectionFailure(options.projectionFailure);\n\n  const projectionFailure = options.projectionFailure ?? \"rollback\";\n\n  const materialized = await options.factory.create(options.definition);\n\n  if (!materialized?.provider) {\n    throw new AFSValidationError(\n      `Provider factory returned no provider for ${options.definition.uri}`,\n    );\n  }\n\n  // Apply the optional post-factory transform (e.g. cache wrapping). Mutate\n  // the materialized result in place so the rest of the flow — including\n  // rollback and the returned `provider` reference — sees the wrapped\n  // provider as the single source of truth.\n  if (options.wrapProvider) {\n    materialized.provider = options.wrapProvider(materialized.provider);\n  }\n\n  // When the caller asks for `replace: true`, pre-cascade-unmount any\n  // existing mounts under this path so the new mount doesn't trip the\n  // AFS parent-child conflict guard. Without this, a re-materialize on\n  // the same path with replace=true would fail because supplement mounts\n  // (e.g. `/chain/.aup/default`) projected by the previous call survive\n  // afs.mount's exact-path replace and look like child mounts to the\n  // conflict checker.\n  if (options.mountOptions?.replace) {\n    cascadeUnmountUnder(options.afs, options.mountPath);\n  }\n\n  const baseline = snapshotMountPaths(options.afs);\n  let dataMounted = false;\n\n  try {\n    await options.afs.mount(materialized.provider, options.mountPath, options.mountOptions);\n    dataMounted = true;\n\n    if (materialized.resources) {\n      for (const projector of options.projectors) {\n        const beforeProjection = snapshotMountPaths(options.afs);\n        try {\n          await projector.project({\n            afs: options.afs,\n            mountPath: options.mountPath,\n            resources: materialized.resources,\n            scope: options.scope,\n          });\n        } catch (err) {\n          if (projectionFailure === \"warn\") {\n            rollbackSupplementsSince(options.afs, beforeProjection, options.mountPath);\n            log.warn(\n              `[aos/mount] resources projection failed for ${options.mountPath} ` +\n                `(projector=${projector.kind}): ${redactError(err)}`,\n            );\n            continue;\n          }\n          throw err;\n        }\n      }\n    }\n\n    for (const overlay of options.overlays ?? []) {\n      for (const projector of options.projectors) {\n        if (projector.kind !== overlay.kind) continue;\n        const beforeOverlayProjection = snapshotMountPaths(options.afs);\n        try {\n          await projector.project({\n            afs: options.afs,\n            mountPath: options.mountPath,\n            resources: overlay.resources,\n            scope: options.scope,\n          });\n        } catch (err) {\n          if (projectionFailure === \"warn\") {\n            rollbackSupplementsSince(options.afs, beforeOverlayProjection, options.mountPath);\n            log.warn(\n              `[aos/mount] overlay projection failed for ${options.mountPath} ` +\n                `(projector=${projector.kind}, overlay=${overlay.kind}): ${redactError(err)}`,\n            );\n            continue;\n          }\n          throw err;\n        }\n      }\n    }\n\n    warnUnsupportedContributions(materialized.contributions, options.mountPath);\n\n    return {\n      provider: materialized.provider,\n      mountedResourceMounts: supplementsSince(options.afs, baseline, options.mountPath),\n    };\n  } catch (error) {\n    rollback(options.afs, baseline, dataMounted ? options.mountPath : null);\n    throw error;\n  }\n}\n\nfunction validateMountPath(mountPath: string): void {\n  if (typeof mountPath !== \"string\" || mountPath.length === 0) {\n    throw new AFSValidationError(\"mountPath must be a non-empty string\");\n  }\n  if (mountPath === \"/\") {\n    throw new AFSValidationError(\"mountPath cannot be '/' — root is reserved\");\n  }\n  if (!mountPath.startsWith(\"/\")) {\n    throw new AFSValidationError(`mountPath must start with '/' (got '${mountPath}')`);\n  }\n  if (mountPath.split(\"/\").some((segment) => segment === \"..\")) {\n    throw new AFSValidationError(`mountPath cannot contain '..' segments (got '${mountPath}')`);\n  }\n}\n\nfunction validateProviderDefinition(definition: ProviderDefinition): void {\n  if (!definition || typeof definition !== \"object\") {\n    throw new AFSValidationError(\"definition must be an object\");\n  }\n  if (typeof definition.uri !== \"string\" || definition.uri.length === 0) {\n    throw new AFSValidationError(\"definition.uri must be a non-empty string\");\n  }\n  if (typeof definition.type !== \"string\" || definition.type.length === 0) {\n    throw new AFSValidationError(\"definition.type must be a non-empty string\");\n  }\n}\n\nfunction validateProjectionFailure(value: unknown): void {\n  if (value === undefined || value === \"rollback\" || value === \"warn\") return;\n  throw new AFSValidationError(\n    `projectionFailure must be \"rollback\" or \"warn\" (got ${JSON.stringify(value)})`,\n  );\n}\n\nfunction snapshotMountPaths(afs: AFS): Set<string> {\n  const paths = new Set<string>();\n  for (const mount of afs.getMounts(null)) {\n    paths.add(mount.path);\n  }\n  return paths;\n}\n\nfunction supplementsSince(afs: AFS, baseline: Set<string>, dataPath: string | null): string[] {\n  const added: string[] = [];\n  for (const mount of afs.getMounts(null)) {\n    if (!baseline.has(mount.path) && mount.path !== dataPath) added.push(mount.path);\n  }\n  return added;\n}\n\nfunction rollback(afs: AFS, baseline: Set<string>, dataPath: string | null): void {\n  // Unmount supplements first (deepest first to honour parent/child\n  // unmount semantics), then the data provider itself. Each unmount is\n  // sync and wrapped in try/catch so one failure cannot block the rest.\n  const supplements = supplementsSince(afs, baseline, dataPath);\n  supplements.sort((a, b) => b.length - a.length);\n  for (const path of supplements) safeUnmount(afs, path);\n  if (dataPath) safeUnmount(afs, dataPath);\n}\n\n/**\n * Roll back only the supplements created since `baseline` (i.e. by the\n * single failing projector). Used by `projectionFailure: \"warn\"` so the\n * data mount and previously-succeeded projector outputs survive.\n */\nfunction rollbackSupplementsSince(afs: AFS, baseline: Set<string>, dataPath: string): void {\n  const supplements = supplementsSince(afs, baseline, dataPath);\n  supplements.sort((a, b) => b.length - a.length);\n  for (const path of supplements) safeUnmount(afs, path);\n}\n\n/**\n * Produce a short, redacted error description suitable for log lines.\n * Truncates message to ~200 chars and drops stack/url so token-bearing\n * URLs and full SDK stack frames cannot leak into shared logs.\n */\nexport function redactError(err: unknown): string {\n  if (err instanceof Error) {\n    const msg = err.message ?? \"\";\n    const truncated = msg.length > 200 ? `${msg.slice(0, 200)}…` : msg;\n    return `${err.name}: ${truncated}`;\n  }\n  const s = typeof err === \"string\" ? err : JSON.stringify(err);\n  return s.length > 200 ? `${s.slice(0, 200)}…` : s;\n}\n\n/**\n * Cascade-unmount every mount at or under `parentPath`. Used when a\n * caller passes `mountOptions.replace: true` — without this, supplement\n * mounts projected by a previous materialize call survive the exact-path\n * replace inside `afs.mount` and the new mount trips the AFS parent-child\n * conflict guard.\n *\n * Order matters: longest paths first so children unmount before parents,\n * keeping each individual `afs.unmount` call within an internally\n * consistent mount tree.\n */\nfunction cascadeUnmountUnder(afs: AFS, parentPath: string): void {\n  const prefix = parentPath.endsWith(\"/\") ? parentPath : `${parentPath}/`;\n  const descendants: string[] = [];\n  for (const mount of afs.getMounts(null)) {\n    if (mount.path === parentPath || mount.path.startsWith(prefix)) {\n      descendants.push(mount.path);\n    }\n  }\n  // Deepest first — children before parents.\n  descendants.sort((a, b) => b.length - a.length);\n  for (const path of descendants) {\n    safeUnmount(afs, path);\n  }\n}\n\nfunction safeUnmount(afs: AFS, path: string): void {\n  try {\n    afs.unmount(path);\n  } catch (error) {\n    log.warn(`[aos/mount] rollback unmount failed for ${path}:`, error);\n  }\n}\n\nfunction warnUnsupportedContributions(\n  contributions: ResourceContribution[] | undefined,\n  mountPath: string,\n): void {\n  if (!contributions?.length) return;\n  log.warn(\n    `[aos/mount] ignoring ${contributions.length} contribution(s) declared by provider at ${mountPath} — first-stage materializer does not project contributions; see planning/afs-ui/aup-mount-materialization Phase 6`,\n  );\n}\n"],"mappings":";;;AAqBA,MAAM,MAAM,UAAU,MAAM;;;;;;;;;;;;;;;AAwF5B,eAAsB,yBACpB,SAC4B;AAC5B,mBAAkB,QAAQ,UAAU;AACpC,4BAA2B,QAAQ,WAAW;AAC9C,2BAA0B,QAAQ,kBAAkB;CAEpD,MAAM,oBAAoB,QAAQ,qBAAqB;CAEvD,MAAM,eAAe,MAAM,QAAQ,QAAQ,OAAO,QAAQ,WAAW;AAErE,KAAI,CAAC,cAAc,SACjB,OAAM,IAAI,mBACR,6CAA6C,QAAQ,WAAW,MACjE;AAOH,KAAI,QAAQ,aACV,cAAa,WAAW,QAAQ,aAAa,aAAa,SAAS;AAUrE,KAAI,QAAQ,cAAc,QACxB,qBAAoB,QAAQ,KAAK,QAAQ,UAAU;CAGrD,MAAM,WAAW,mBAAmB,QAAQ,IAAI;CAChD,IAAI,cAAc;AAElB,KAAI;AACF,QAAM,QAAQ,IAAI,MAAM,aAAa,UAAU,QAAQ,WAAW,QAAQ,aAAa;AACvF,gBAAc;AAEd,MAAI,aAAa,UACf,MAAK,MAAM,aAAa,QAAQ,YAAY;GAC1C,MAAM,mBAAmB,mBAAmB,QAAQ,IAAI;AACxD,OAAI;AACF,UAAM,UAAU,QAAQ;KACtB,KAAK,QAAQ;KACb,WAAW,QAAQ;KACnB,WAAW,aAAa;KACxB,OAAO,QAAQ;KAChB,CAAC;YACK,KAAK;AACZ,QAAI,sBAAsB,QAAQ;AAChC,8BAAyB,QAAQ,KAAK,kBAAkB,QAAQ,UAAU;AAC1E,SAAI,KACF,+CAA+C,QAAQ,UAAU,cACjD,UAAU,KAAK,KAAK,YAAY,IAAI,GACrD;AACD;;AAEF,UAAM;;;AAKZ,OAAK,MAAM,WAAW,QAAQ,YAAY,EAAE,CAC1C,MAAK,MAAM,aAAa,QAAQ,YAAY;AAC1C,OAAI,UAAU,SAAS,QAAQ,KAAM;GACrC,MAAM,0BAA0B,mBAAmB,QAAQ,IAAI;AAC/D,OAAI;AACF,UAAM,UAAU,QAAQ;KACtB,KAAK,QAAQ;KACb,WAAW,QAAQ;KACnB,WAAW,QAAQ;KACnB,OAAO,QAAQ;KAChB,CAAC;YACK,KAAK;AACZ,QAAI,sBAAsB,QAAQ;AAChC,8BAAyB,QAAQ,KAAK,yBAAyB,QAAQ,UAAU;AACjF,SAAI,KACF,6CAA6C,QAAQ,UAAU,cAC/C,UAAU,KAAK,YAAY,QAAQ,KAAK,KAAK,YAAY,IAAI,GAC9E;AACD;;AAEF,UAAM;;;AAKZ,+BAA6B,aAAa,eAAe,QAAQ,UAAU;AAE3E,SAAO;GACL,UAAU,aAAa;GACvB,uBAAuB,iBAAiB,QAAQ,KAAK,UAAU,QAAQ,UAAU;GAClF;UACM,OAAO;AACd,WAAS,QAAQ,KAAK,UAAU,cAAc,QAAQ,YAAY,KAAK;AACvE,QAAM;;;AAIV,SAAS,kBAAkB,WAAyB;AAClD,KAAI,OAAO,cAAc,YAAY,UAAU,WAAW,EACxD,OAAM,IAAI,mBAAmB,uCAAuC;AAEtE,KAAI,cAAc,IAChB,OAAM,IAAI,mBAAmB,6CAA6C;AAE5E,KAAI,CAAC,UAAU,WAAW,IAAI,CAC5B,OAAM,IAAI,mBAAmB,uCAAuC,UAAU,IAAI;AAEpF,KAAI,UAAU,MAAM,IAAI,CAAC,MAAM,YAAY,YAAY,KAAK,CAC1D,OAAM,IAAI,mBAAmB,gDAAgD,UAAU,IAAI;;AAI/F,SAAS,2BAA2B,YAAsC;AACxE,KAAI,CAAC,cAAc,OAAO,eAAe,SACvC,OAAM,IAAI,mBAAmB,+BAA+B;AAE9D,KAAI,OAAO,WAAW,QAAQ,YAAY,WAAW,IAAI,WAAW,EAClE,OAAM,IAAI,mBAAmB,4CAA4C;AAE3E,KAAI,OAAO,WAAW,SAAS,YAAY,WAAW,KAAK,WAAW,EACpE,OAAM,IAAI,mBAAmB,6CAA6C;;AAI9E,SAAS,0BAA0B,OAAsB;AACvD,KAAI,UAAU,UAAa,UAAU,cAAc,UAAU,OAAQ;AACrE,OAAM,IAAI,mBACR,uDAAuD,KAAK,UAAU,MAAM,CAAC,GAC9E;;AAGH,SAAS,mBAAmB,KAAuB;CACjD,MAAM,wBAAQ,IAAI,KAAa;AAC/B,MAAK,MAAM,SAAS,IAAI,UAAU,KAAK,CACrC,OAAM,IAAI,MAAM,KAAK;AAEvB,QAAO;;AAGT,SAAS,iBAAiB,KAAU,UAAuB,UAAmC;CAC5F,MAAM,QAAkB,EAAE;AAC1B,MAAK,MAAM,SAAS,IAAI,UAAU,KAAK,CACrC,KAAI,CAAC,SAAS,IAAI,MAAM,KAAK,IAAI,MAAM,SAAS,SAAU,OAAM,KAAK,MAAM,KAAK;AAElF,QAAO;;AAGT,SAAS,SAAS,KAAU,UAAuB,UAA+B;CAIhF,MAAM,cAAc,iBAAiB,KAAK,UAAU,SAAS;AAC7D,aAAY,MAAM,GAAG,MAAM,EAAE,SAAS,EAAE,OAAO;AAC/C,MAAK,MAAM,QAAQ,YAAa,aAAY,KAAK,KAAK;AACtD,KAAI,SAAU,aAAY,KAAK,SAAS;;;;;;;AAQ1C,SAAS,yBAAyB,KAAU,UAAuB,UAAwB;CACzF,MAAM,cAAc,iBAAiB,KAAK,UAAU,SAAS;AAC7D,aAAY,MAAM,GAAG,MAAM,EAAE,SAAS,EAAE,OAAO;AAC/C,MAAK,MAAM,QAAQ,YAAa,aAAY,KAAK,KAAK;;;;;;;AAQxD,SAAgB,YAAY,KAAsB;AAChD,KAAI,eAAe,OAAO;EACxB,MAAM,MAAM,IAAI,WAAW;EAC3B,MAAM,YAAY,IAAI,SAAS,MAAM,GAAG,IAAI,MAAM,GAAG,IAAI,CAAC,KAAK;AAC/D,SAAO,GAAG,IAAI,KAAK,IAAI;;CAEzB,MAAM,IAAI,OAAO,QAAQ,WAAW,MAAM,KAAK,UAAU,IAAI;AAC7D,QAAO,EAAE,SAAS,MAAM,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC,KAAK;;;;;;;;;;;;;AAclD,SAAS,oBAAoB,KAAU,YAA0B;CAC/D,MAAM,SAAS,WAAW,SAAS,IAAI,GAAG,aAAa,GAAG,WAAW;CACrE,MAAM,cAAwB,EAAE;AAChC,MAAK,MAAM,SAAS,IAAI,UAAU,KAAK,CACrC,KAAI,MAAM,SAAS,cAAc,MAAM,KAAK,WAAW,OAAO,CAC5D,aAAY,KAAK,MAAM,KAAK;AAIhC,aAAY,MAAM,GAAG,MAAM,EAAE,SAAS,EAAE,OAAO;AAC/C,MAAK,MAAM,QAAQ,YACjB,aAAY,KAAK,KAAK;;AAI1B,SAAS,YAAY,KAAU,MAAoB;AACjD,KAAI;AACF,MAAI,QAAQ,KAAK;UACV,OAAO;AACd,MAAI,KAAK,2CAA2C,KAAK,IAAI,MAAM;;;AAIvE,SAAS,6BACP,eACA,WACM;AACN,KAAI,CAAC,eAAe,OAAQ;AAC5B,KAAI,KACF,wBAAwB,cAAc,OAAO,2CAA2C,UAAU,mHACnG"}