@aigne/aos 0.2.0-beta

package/dist/mount/types.d.cts

@@ -0,0 +1,90 @@
+import { AFS, AFSModule } from "@aigne/afs";
+
+//#region src/mount/types.d.ts
+/**
+ * @internal
+ * Provider creation intent — runtime-neutral description of "what to mount
+ * at this path". Adapter layers (Node `createNodeProviderFactory`,
+ * Cloudflare worker factories) translate this into concrete provider
+ * instances and companion resources.
+ */
+interface ProviderDefinition {
+  /** Provider URI, e.g. `ocap://main.abtnetwork.io/api`, `fs:///path`. */
+  uri: string;
+  /**
+   * Provider scheme name (e.g. `ocap`, `fs`, `json`).
+   *
+   * Source: usually parsed from `uri` via `new URL(uri).protocol.slice(0, -1)`,
+   * or supplied by the caller when scheme is already known (e.g. daemon
+   * config has an explicit `scheme` field).
+   *
+   * Use: a hint for registry / factory selection. The adapter that converts
+   * `ProviderDefinition` to a `MountConfig` does NOT write `type` into
+   * `MountConfig.path`.
+   *
+   * Required (not `string | undefined`) to keep call sites unambiguous —
+   * callers can pass `new URL(uri).protocol.slice(0, -1)` when they have no
+   * better hint.
+   */
+  type: string;
+  /** Provider-specific options forwarded to the factory. */
+  options?: Record<string, unknown>;
+}
+/**
+ * @internal
+ * A resource bundle that one provider explicitly contributes to another
+ * provider's mount. First-stage materializer reserves the type but does not
+ * project contributions — see Phase 6 of the materialization plan.
+ */
+interface ResourceContribution {
+  kind: "aup";
+  target: string;
+  resources: AFSModule;
+  scope: "blocklet" | "instance";
+  policy?: {
+    allowDefaultOverride?: boolean;
+  };
+}
+/**
+ * @internal
+ * The full result of materializing a provider mount: its data tree, any
+ * companion resources owned by the provider package, and any contributions
+ * the provider wants to inject elsewhere.
+ */
+interface MaterializedMount {
+  /** The data provider — the thing that gets mounted at the target path. */
+  provider: AFSModule;
+  /** Read-only companion resources (e.g. AUP recipes) owned by the provider. */
+  resources?: AFSModule;
+  /** Explicit contributions to other mounts. Reserved for Phase 6. */
+  contributions?: ResourceContribution[];
+}
+/**
+ * @internal
+ * Extension point for projecting `resources` (and overlays) onto a target
+ * mount. Resource projectors run inside the materializer and only use AFS
+ * APIs — they never touch Node fs, Cloudflare bindings, or other runtime
+ * specifics.
+ */
+interface ResourceProjector {
+  /** Projector kind discriminator (e.g. `"aup"`). */
+  kind: string;
+  project(options: {
+    afs: AFS;
+    mountPath: string;
+    resources: AFSModule;
+    scope: "host" | "blocklet" | "instance";
+  }): Promise<void>;
+}
+/**
+ * @internal
+ * Runtime-specific factory that creates a `MaterializedMount` from a
+ * `ProviderDefinition`. Node's factory adapts `createRuntimeAwareProviderWithMetadata`;
+ * Cloudflare's factory returns bundled assets.
+ */
+interface ProviderFactory {
+  create(definition: ProviderDefinition): Promise<MaterializedMount>;
+}
+//#endregion
+export { MaterializedMount, ProviderDefinition, ProviderFactory, ResourceContribution, ResourceProjector };
+//# sourceMappingURL=types.d.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.cts","names":[],"sources":["../../src/mount/types.ts"],"mappings":";;;;AAoDA;;;;;;UA/BiB,kBAAA;EAkCJ;EAhCX,GAAA;EAkCA;;;;AASF;;;;;;;;;;;EA1BE,IAAA;EAgCA;EA7BA,OAAA,GAAU,MAAA;AAAA;;AAuCZ;;;;;UA9BiB,oBAAA;EACf,IAAA;EACA,MAAA;EACA,SAAA,EAAW,SAAA;EACX,KAAA;EACA,MAAA;IAAW,oBAAA;EAAA;AAAA;;;;;;;UASI,iBAAA;EAiCe;EA/B9B,QAAA,EAAU,SAAA;EAgCS;EA9BnB,SAAA,GAAY,SAAA;EA8B4B;EA5BxC,aAAA,GAAgB,oBAAA;AAAA;;;;;;;;UAUD,iBAAA;;EAEf,IAAA;EACA,OAAA,CAAQ,OAAA;IACN,GAAA,EAAK,GAAA;IACL,SAAA;IACA,SAAA,EAAW,SAAA;IACX,KAAA;EAAA,IACE,OAAA;AAAA;;;;;;;UASW,eAAA;EACf,MAAA,CAAO,UAAA,EAAY,kBAAA,GAAqB,OAAA,CAAQ,iBAAA;AAAA"}

package/dist/mount/types.d.mts

@@ -0,0 +1,90 @@
+import { AFS, AFSModule } from "@aigne/afs";
+
+//#region src/mount/types.d.ts
+/**
+ * @internal
+ * Provider creation intent — runtime-neutral description of "what to mount
+ * at this path". Adapter layers (Node `createNodeProviderFactory`,
+ * Cloudflare worker factories) translate this into concrete provider
+ * instances and companion resources.
+ */
+interface ProviderDefinition {
+  /** Provider URI, e.g. `ocap://main.abtnetwork.io/api`, `fs:///path`. */
+  uri: string;
+  /**
+   * Provider scheme name (e.g. `ocap`, `fs`, `json`).
+   *
+   * Source: usually parsed from `uri` via `new URL(uri).protocol.slice(0, -1)`,
+   * or supplied by the caller when scheme is already known (e.g. daemon
+   * config has an explicit `scheme` field).
+   *
+   * Use: a hint for registry / factory selection. The adapter that converts
+   * `ProviderDefinition` to a `MountConfig` does NOT write `type` into
+   * `MountConfig.path`.
+   *
+   * Required (not `string | undefined`) to keep call sites unambiguous —
+   * callers can pass `new URL(uri).protocol.slice(0, -1)` when they have no
+   * better hint.
+   */
+  type: string;
+  /** Provider-specific options forwarded to the factory. */
+  options?: Record<string, unknown>;
+}
+/**
+ * @internal
+ * A resource bundle that one provider explicitly contributes to another
+ * provider's mount. First-stage materializer reserves the type but does not
+ * project contributions — see Phase 6 of the materialization plan.
+ */
+interface ResourceContribution {
+  kind: "aup";
+  target: string;
+  resources: AFSModule;
+  scope: "blocklet" | "instance";
+  policy?: {
+    allowDefaultOverride?: boolean;
+  };
+}
+/**
+ * @internal
+ * The full result of materializing a provider mount: its data tree, any
+ * companion resources owned by the provider package, and any contributions
+ * the provider wants to inject elsewhere.
+ */
+interface MaterializedMount {
+  /** The data provider — the thing that gets mounted at the target path. */
+  provider: AFSModule;
+  /** Read-only companion resources (e.g. AUP recipes) owned by the provider. */
+  resources?: AFSModule;
+  /** Explicit contributions to other mounts. Reserved for Phase 6. */
+  contributions?: ResourceContribution[];
+}
+/**
+ * @internal
+ * Extension point for projecting `resources` (and overlays) onto a target
+ * mount. Resource projectors run inside the materializer and only use AFS
+ * APIs — they never touch Node fs, Cloudflare bindings, or other runtime
+ * specifics.
+ */
+interface ResourceProjector {
+  /** Projector kind discriminator (e.g. `"aup"`). */
+  kind: string;
+  project(options: {
+    afs: AFS;
+    mountPath: string;
+    resources: AFSModule;
+    scope: "host" | "blocklet" | "instance";
+  }): Promise<void>;
+}
+/**
+ * @internal
+ * Runtime-specific factory that creates a `MaterializedMount` from a
+ * `ProviderDefinition`. Node's factory adapts `createRuntimeAwareProviderWithMetadata`;
+ * Cloudflare's factory returns bundled assets.
+ */
+interface ProviderFactory {
+  create(definition: ProviderDefinition): Promise<MaterializedMount>;
+}
+//#endregion
+export { MaterializedMount, ProviderDefinition, ProviderFactory, ResourceContribution, ResourceProjector };
+//# sourceMappingURL=types.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../src/mount/types.ts"],"mappings":";;;;AAoDA;;;;;;UA/BiB,kBAAA;EAkCJ;EAhCX,GAAA;EAkCA;;;;AASF;;;;;;;;;;;EA1BE,IAAA;EAgCA;EA7BA,OAAA,GAAU,MAAA;AAAA;;AAuCZ;;;;;UA9BiB,oBAAA;EACf,IAAA;EACA,MAAA;EACA,SAAA,EAAW,SAAA;EACX,KAAA;EACA,MAAA;IAAW,oBAAA;EAAA;AAAA;;;;;;;UASI,iBAAA;EAiCe;EA/B9B,QAAA,EAAU,SAAA;EAgCS;EA9BnB,SAAA,GAAY,SAAA;EA8B4B;EA5BxC,aAAA,GAAgB,oBAAA;AAAA;;;;;;;;UAUD,iBAAA;;EAEf,IAAA;EACA,OAAA,CAAQ,OAAA;IACN,GAAA,EAAK,GAAA;IACL,SAAA;IACA,SAAA,EAAW,SAAA;IACX,KAAA;EAAA,IACE,OAAA;AAAA;;;;;;;UASW,eAAA;EACf,MAAA,CAAO,UAAA,EAAY,kBAAA,GAAqB,OAAA,CAAQ,iBAAA;AAAA"}

package/dist/mount-config.cjs

@@ -0,0 +1,61 @@
+
+//#region src/mount-config.ts
+function parseMountConfig(input) {
+	if (!input || input.trim() === "") return {
+		entries: [],
+		errors: []
+	};
+	let parsed;
+	try {
+		parsed = JSON.parse(input);
+	} catch (e) {
+		return {
+			entries: [],
+			errors: [`Invalid JSON: ${e instanceof Error ? e.message : String(e)}`]
+		};
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return {
+		entries: [],
+		errors: ["Mount config must be a JSON object with a 'mounts' array"]
+	};
+	const obj = parsed;
+	if (!Array.isArray(obj.mounts)) return {
+		entries: [],
+		errors: ["Mount config must have a 'mounts' array"]
+	};
+	const entries = [];
+	const errors = [];
+	for (let i = 0; i < obj.mounts.length; i++) {
+		const entry = obj.mounts[i];
+		if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+			errors.push(`mounts[${i}]: must be an object`);
+			continue;
+		}
+		const e = entry;
+		if (typeof e.path !== "string" || e.path.trim() === "") {
+			errors.push(`mounts[${i}]: 'path' must be a non-empty string`);
+			continue;
+		}
+		if (typeof e.provider !== "string" || e.provider.trim() === "") {
+			errors.push(`mounts[${i}]: 'provider' must be a non-empty string`);
+			continue;
+		}
+		if (e.path.includes("..")) {
+			errors.push(`mounts[${i}]: path must not contain '..'`);
+			continue;
+		}
+		const normalizedPath = e.path.startsWith("/") ? e.path : `/${e.path}`;
+		entries.push({
+			path: normalizedPath,
+			provider: e.provider.trim(),
+			options: typeof e.options === "object" && e.options !== null && !Array.isArray(e.options) ? e.options : {}
+		});
+	}
+	return {
+		entries,
+		errors
+	};
+}
+
+//#endregion
+exports.parseMountConfig = parseMountConfig;

package/dist/mount-config.d.cts

@@ -0,0 +1,19 @@
+import { AFSModule } from "@aigne/afs";
+
+//#region src/mount-config.d.ts
+interface MountEntry {
+  path: string;
+  provider: string;
+  options?: Record<string, unknown>;
+}
+interface MountConfig {
+  mounts: MountEntry[];
+}
+interface ParseMountConfigResult {
+  entries: MountEntry[];
+  errors: string[];
+}
+declare function parseMountConfig(input: string | undefined | null): ParseMountConfigResult;
+//#endregion
+export { MountConfig, MountEntry, ParseMountConfigResult, parseMountConfig };
+//# sourceMappingURL=mount-config.d.cts.map

package/dist/mount-config.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mount-config.d.cts","names":[],"sources":["../src/mount-config.ts"],"mappings":";;;UAEiB,UAAA;EACf,IAAA;EACA,QAAA;EACA,OAAA,GAAU,MAAA;AAAA;AAAA,UAEK,WAAA;EACf,MAAA,EAAQ,UAAA;AAAA;AAAA,UAGO,sBAAA;EACf,OAAA,EAAS,UAAA;EACT,MAAA;AAAA;AAAA,iBAGc,gBAAA,CAAiB,KAAA,8BAAmC,sBAAA"}

package/dist/mount-config.d.mts

@@ -0,0 +1,19 @@
+import { AFSModule } from "@aigne/afs";
+
+//#region src/mount-config.d.ts
+interface MountEntry {
+  path: string;
+  provider: string;
+  options?: Record<string, unknown>;
+}
+interface MountConfig {
+  mounts: MountEntry[];
+}
+interface ParseMountConfigResult {
+  entries: MountEntry[];
+  errors: string[];
+}
+declare function parseMountConfig(input: string | undefined | null): ParseMountConfigResult;
+//#endregion
+export { MountConfig, MountEntry, ParseMountConfigResult, parseMountConfig };
+//# sourceMappingURL=mount-config.d.mts.map

package/dist/mount-config.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mount-config.d.mts","names":[],"sources":["../src/mount-config.ts"],"mappings":";;;UAEiB,UAAA;EACf,IAAA;EACA,QAAA;EACA,OAAA,GAAU,MAAA;AAAA;AAAA,UAEK,WAAA;EACf,MAAA,EAAQ,UAAA;AAAA;AAAA,UAGO,sBAAA;EACf,OAAA,EAAS,UAAA;EACT,MAAA;AAAA;AAAA,iBAGc,gBAAA,CAAiB,KAAA,8BAAmC,sBAAA"}

package/dist/mount-config.mjs

@@ -0,0 +1,61 @@
+//#region src/mount-config.ts
+function parseMountConfig(input) {
+	if (!input || input.trim() === "") return {
+		entries: [],
+		errors: []
+	};
+	let parsed;
+	try {
+		parsed = JSON.parse(input);
+	} catch (e) {
+		return {
+			entries: [],
+			errors: [`Invalid JSON: ${e instanceof Error ? e.message : String(e)}`]
+		};
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return {
+		entries: [],
+		errors: ["Mount config must be a JSON object with a 'mounts' array"]
+	};
+	const obj = parsed;
+	if (!Array.isArray(obj.mounts)) return {
+		entries: [],
+		errors: ["Mount config must have a 'mounts' array"]
+	};
+	const entries = [];
+	const errors = [];
+	for (let i = 0; i < obj.mounts.length; i++) {
+		const entry = obj.mounts[i];
+		if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+			errors.push(`mounts[${i}]: must be an object`);
+			continue;
+		}
+		const e = entry;
+		if (typeof e.path !== "string" || e.path.trim() === "") {
+			errors.push(`mounts[${i}]: 'path' must be a non-empty string`);
+			continue;
+		}
+		if (typeof e.provider !== "string" || e.provider.trim() === "") {
+			errors.push(`mounts[${i}]: 'provider' must be a non-empty string`);
+			continue;
+		}
+		if (e.path.includes("..")) {
+			errors.push(`mounts[${i}]: path must not contain '..'`);
+			continue;
+		}
+		const normalizedPath = e.path.startsWith("/") ? e.path : `/${e.path}`;
+		entries.push({
+			path: normalizedPath,
+			provider: e.provider.trim(),
+			options: typeof e.options === "object" && e.options !== null && !Array.isArray(e.options) ? e.options : {}
+		});
+	}
+	return {
+		entries,
+		errors
+	};
+}
+
+//#endregion
+export { parseMountConfig };
+//# sourceMappingURL=mount-config.mjs.map

package/dist/mount-config.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"mount-config.mjs","names":[],"sources":["../src/mount-config.ts"],"sourcesContent":["import type { AFSModule } from \"@aigne/afs\";\n\nexport interface MountEntry {\n  path: string;\n  provider: string;\n  options?: Record<string, unknown>;\n}\nexport interface MountConfig {\n  mounts: MountEntry[];\n}\nexport type ProviderFactory = (entry: MountEntry) => AFSModule | Promise<AFSModule>;\nexport interface ParseMountConfigResult {\n  entries: MountEntry[];\n  errors: string[];\n}\n\nexport function parseMountConfig(input: string | undefined | null): ParseMountConfigResult {\n  if (!input || input.trim() === \"\") return { entries: [], errors: [] };\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(input);\n  } catch (e) {\n    return { entries: [], errors: [`Invalid JSON: ${e instanceof Error ? e.message : String(e)}`] };\n  }\n  if (typeof parsed !== \"object\" || parsed === null || Array.isArray(parsed))\n    return { entries: [], errors: [\"Mount config must be a JSON object with a 'mounts' array\"] };\n  const obj = parsed as Record<string, unknown>;\n  if (!Array.isArray(obj.mounts))\n    return { entries: [], errors: [\"Mount config must have a 'mounts' array\"] };\n  const entries: MountEntry[] = [];\n  const errors: string[] = [];\n  for (let i = 0; i < obj.mounts.length; i++) {\n    const entry = obj.mounts[i];\n    if (typeof entry !== \"object\" || entry === null || Array.isArray(entry)) {\n      errors.push(`mounts[${i}]: must be an object`);\n      continue;\n    }\n    const e = entry as Record<string, unknown>;\n    if (typeof e.path !== \"string\" || (e.path as string).trim() === \"\") {\n      errors.push(`mounts[${i}]: 'path' must be a non-empty string`);\n      continue;\n    }\n    if (typeof e.provider !== \"string\" || (e.provider as string).trim() === \"\") {\n      errors.push(`mounts[${i}]: 'provider' must be a non-empty string`);\n      continue;\n    }\n    if ((e.path as string).includes(\"..\")) {\n      errors.push(`mounts[${i}]: path must not contain '..'`);\n      continue;\n    }\n    const normalizedPath = (e.path as string).startsWith(\"/\") ? (e.path as string) : `/${e.path}`;\n    entries.push({\n      path: normalizedPath,\n      provider: (e.provider as string).trim(),\n      options: (typeof e.options === \"object\" && e.options !== null && !Array.isArray(e.options)\n        ? e.options\n        : {}) as Record<string, unknown>,\n    });\n  }\n  return { entries, errors };\n}\n"],"mappings":";AAgBA,SAAgB,iBAAiB,OAA0D;AACzF,KAAI,CAAC,SAAS,MAAM,MAAM,KAAK,GAAI,QAAO;EAAE,SAAS,EAAE;EAAE,QAAQ,EAAE;EAAE;CACrE,IAAI;AACJ,KAAI;AACF,WAAS,KAAK,MAAM,MAAM;UACnB,GAAG;AACV,SAAO;GAAE,SAAS,EAAE;GAAE,QAAQ,CAAC,iBAAiB,aAAa,QAAQ,EAAE,UAAU,OAAO,EAAE,GAAG;GAAE;;AAEjG,KAAI,OAAO,WAAW,YAAY,WAAW,QAAQ,MAAM,QAAQ,OAAO,CACxE,QAAO;EAAE,SAAS,EAAE;EAAE,QAAQ,CAAC,2DAA2D;EAAE;CAC9F,MAAM,MAAM;AACZ,KAAI,CAAC,MAAM,QAAQ,IAAI,OAAO,CAC5B,QAAO;EAAE,SAAS,EAAE;EAAE,QAAQ,CAAC,0CAA0C;EAAE;CAC7E,MAAM,UAAwB,EAAE;CAChC,MAAM,SAAmB,EAAE;AAC3B,MAAK,IAAI,IAAI,GAAG,IAAI,IAAI,OAAO,QAAQ,KAAK;EAC1C,MAAM,QAAQ,IAAI,OAAO;AACzB,MAAI,OAAO,UAAU,YAAY,UAAU,QAAQ,MAAM,QAAQ,MAAM,EAAE;AACvE,UAAO,KAAK,UAAU,EAAE,sBAAsB;AAC9C;;EAEF,MAAM,IAAI;AACV,MAAI,OAAO,EAAE,SAAS,YAAa,EAAE,KAAgB,MAAM,KAAK,IAAI;AAClE,UAAO,KAAK,UAAU,EAAE,sCAAsC;AAC9D;;AAEF,MAAI,OAAO,EAAE,aAAa,YAAa,EAAE,SAAoB,MAAM,KAAK,IAAI;AAC1E,UAAO,KAAK,UAAU,EAAE,0CAA0C;AAClE;;AAEF,MAAK,EAAE,KAAgB,SAAS,KAAK,EAAE;AACrC,UAAO,KAAK,UAAU,EAAE,+BAA+B;AACvD;;EAEF,MAAM,iBAAkB,EAAE,KAAgB,WAAW,IAAI,GAAI,EAAE,OAAkB,IAAI,EAAE;AACvF,UAAQ,KAAK;GACX,MAAM;GACN,UAAW,EAAE,SAAoB,MAAM;GACvC,SAAU,OAAO,EAAE,YAAY,YAAY,EAAE,YAAY,QAAQ,CAAC,MAAM,QAAQ,EAAE,QAAQ,GACtF,EAAE,UACF,EAAE;GACP,CAAC;;AAEJ,QAAO;EAAE;EAAS;EAAQ"}

package/dist/projectors/aup-projector.cjs

@@ -0,0 +1,190 @@
+let ufo = require("ufo");
+let _aigne_afs = require("@aigne/afs");
+
+//#region src/projectors/aup-projector.ts
+/**
+* @internal
+*
+* AUP `ResourceProjector` — projects an opaque `AFSModule` of `aup/**.json`
+* recipes onto a target mount as hidden `AupRecipeProvider` supplements.
+*
+* Runtime-neutral: the projector only uses AFS APIs and knows nothing about
+* Node fs, Cloudflare bindings, or any other runtime-specific surface. The
+* `resources` module is opaque — Node's adapter wraps a packageDir via
+* `AFSFS`, Cloudflare's adapter wraps a build-time bundled asset map, and
+* tests can wrap any in-memory `AFSModule`.
+*
+* Subpath-only export: `@aigne/aos/projectors`. Not part of the @aigne/aos
+* root contract. Cross-plan contract: chain-as-device-placement Phase 4
+* imports `projectAupResources` directly.
+*/
+const randomUUID = () => globalThis.crypto.randomUUID();
+/**
+* 1 MiB safety cap for a single recipe file. Anything larger almost
+* certainly represents a misconfiguration (e.g. a bundled asset landed in
+* `aup/`) and would balloon every mount's memory footprint.
+*
+* **Failure semantics:** oversized files and malformed JSON are surfaced as
+* `AFSValidationError` (not silent skip). This matches the legacy
+* `autoSupplementAup` contract — fail-fast over partial recipes is the
+* right default because supplements that are missing in production are
+* confusing for users and noisy in logs. The planning doc tasks.md table
+* mentions "skip + log"; the legacy implementation has always thrown, all
+* pre-existing integration tests assert throwing, and this projector
+* preserves that behaviour. If a future phase wants per-file isolation
+* the policy can be lifted to a projector option.
+*/
+const MAX_RECIPE_BYTES = 1024 * 1024;
+/** Bounded recursion depth for listing aup/ — enough for any realistic layout. */
+const MAX_LIST_DEPTH = 100;
+/** Hidden temp mount root for opaque resources modules. Dot-less to remain
+*  compatible with any future blocklet rules that reject dot-prefixed segments. */
+const TMP_MOUNT_ROOT = "/materialize-tmp";
+/** Supplement sub-path under each target (e.g. `/fix` → `/fix/.aup/default`). */
+const AUP_SUBPATH = ".aup";
+/** Top-level directory inside the resources module that holds recipe JSON. */
+const AUP_RESOURCE_ROOT = "/aup";
+/**
+* @internal
+* AUP projector singleton — the first-class abstraction.
+*/
+const aupResourceProjector = {
+	kind: "aup",
+	async project({ afs, mountPath, resources, scope }) {
+		await projectAupResources({
+			afs,
+			mountPath,
+			resources,
+			scope
+		});
+	}
+};
+/**
+* @internal
+* Thin wrapper exposing the same behaviour as
+* {@link aupResourceProjector}.project — kept as a stable function reference
+* for the chain-as-device-placement plan, which imports this name directly.
+*/
+async function projectAupResources(opts) {
+	opts.scope;
+	const tempMountPath = (0, ufo.joinURL)(TMP_MOUNT_ROOT, randomUUID());
+	try {
+		await opts.afs.mount(opts.resources, tempMountPath, { hidden: true });
+	} catch (err) {
+		if (isNotFoundError(err)) return;
+		throw err;
+	}
+	try {
+		await projectAupFromAfsPath({
+			afs: opts.afs,
+			scanRoot: (0, ufo.joinURL)(tempMountPath, AUP_RESOURCE_ROOT),
+			mountTarget: opts.mountPath
+		});
+	} finally {
+		opts.afs.unmount(tempMountPath);
+	}
+}
+/**
+* @internal
+* Scan an existing AFS path for `*.json` recipe files and mount each one as
+* a hidden `AupRecipeProvider` supplement under `{mountTarget}`.
+*
+* Used both by `projectAupResources` (after temp-mounting an opaque
+* resources module) and by Node's `autoSupplementAup` virtual-path flow
+* (which already has a live AFS path to scan).
+*
+* Missing `scanRoot` → silent no-op, mirroring the original loader contract.
+*/
+async function projectAupFromAfsPath(opts) {
+	let listResult;
+	try {
+		listResult = await opts.afs.list(opts.scanRoot, { maxDepth: MAX_LIST_DEPTH });
+	} catch (err) {
+		if (isNotFoundError(err)) return;
+		throw err;
+	}
+	const jsonFiles = (listResult.data ?? []).filter(isJsonFileEntry).sort((a, b) => (a.path ?? "").localeCompare(b.path ?? ""));
+	for (const file of jsonFiles) {
+		const relPath = file.path.slice(opts.scanRoot.length);
+		const { prefix, viewName } = parseAupFilePath(relPath);
+		const declaredSize = file.meta?.size;
+		if (typeof declaredSize === "number" && declaredSize > MAX_RECIPE_BYTES) throw new _aigne_afs.AFSValidationError(`AUP recipe file too large (> ${MAX_RECIPE_BYTES} bytes): ${relPath}`);
+		const raw = (await opts.afs.read(file.path)).data?.content;
+		const text = typeof raw === "string" ? raw : new TextDecoder().decode(raw);
+		if (text.length > MAX_RECIPE_BYTES) throw new _aigne_afs.AFSValidationError(`AUP recipe file too large (> ${MAX_RECIPE_BYTES} bytes): ${relPath}`);
+		let recipe;
+		try {
+			recipe = JSON.parse(text);
+		} catch (err) {
+			throw new _aigne_afs.AFSValidationError(`Failed to parse AUP recipe ${relPath}: ${err instanceof Error ? err.message : String(err)}`);
+		}
+		const supplementPath = (0, ufo.joinURL)(opts.mountTarget, prefix, AUP_SUBPATH, viewName);
+		await opts.afs.mount(new _aigne_afs.AupRecipeProvider(recipe), supplementPath, { hidden: true });
+	}
+}
+/**
+* @internal
+* Translate `aup/` placeholder syntax to AFS mount `:param` syntax within a
+* single path segment. An `_<name>` token becomes `:<name>` ONLY when the `_`
+* sits at the start of the segment or directly after a non-alphanumeric
+* separator (e.g. `-`). An underscore surrounded by alphanumerics (`my_dir`)
+* is left literal, so ordinary directory names with underscores are safe.
+*
+* ```
+* _date     → :date       (segment-leading)
+* round-_n  → round-:n     (after a `-` separator — mixed segment)
+* my_dir    → my_dir       (alphanumeric-bounded `_` — unchanged)
+* ```
+*
+* Disambiguation convention (design.md §3.2): inside `aup/`, an `_<name>`
+* token in this position is a parameter segment.
+*/
+function translateParamSegment(segment) {
+	return segment.replace(/(^|[^a-zA-Z0-9])_([a-zA-Z][a-zA-Z0-9]*)/g, "$1:$2");
+}
+/**
+* @internal
+* Parse a relative path inside an `aup/` directory into the mount-path
+* components the supplement will occupy. Prefix segments are translated from
+* `_param` placeholder syntax to `:param` mount syntax (see
+* {@link translateParamSegment}); the view name is never translated.
+*
+* ```
+* /default.json                  → { prefix: "",                  viewName: "default" }
+* /transactions/item.json        → { prefix: "/transactions",     viewName: "item" }
+* /a/b/c/view.json               → { prefix: "/a/b/c",            viewName: "view" }
+* /bridges/_addr/blocks/item.json→ { prefix: "/bridges/:addr/blocks", viewName: "item" }
+* /traces/_date/_runId/item.json → { prefix: "/traces/:date/:runId",  viewName: "item" }
+* ```
+*/
+function parseAupFilePath(relPath) {
+	if (!relPath || relPath.trim() === "") throw new Error("parseAupFilePath: path is empty");
+	const normalized = (relPath.startsWith("/") ? relPath : `/${relPath}`).replace(/\/+/g, "/").replace(/\/+$/, "");
+	if (!normalized.endsWith(".json")) throw new Error(`parseAupFilePath: file must end with .json, got "${relPath}"`);
+	const segments = normalized.split("/").filter(Boolean);
+	if (segments.some((s) => s === "..")) throw new Error(`parseAupFilePath: path traversal not allowed: "${relPath}"`);
+	const viewName = segments.pop().slice(0, -5);
+	if (!viewName) throw new Error(`parseAupFilePath: view name is empty for "${relPath}"`);
+	return {
+		prefix: segments.length === 0 ? "" : `/${segments.map(translateParamSegment).join("/")}`,
+		viewName
+	};
+}
+function isJsonFileEntry(entry) {
+	if (!entry.path?.endsWith(".json")) return false;
+	return entry.meta?.kind !== "fs:directory";
+}
+function isNotFoundError(err) {
+	if (err instanceof _aigne_afs.AFSNotFoundError) return true;
+	if (err instanceof Error) {
+		if (err.code === "ENOENT") return true;
+		if (/ENOENT|no such file or directory|not found/i.test(err.message)) return true;
+	}
+	return false;
+}
+
+//#endregion
+exports.aupResourceProjector = aupResourceProjector;
+exports.parseAupFilePath = parseAupFilePath;
+exports.projectAupFromAfsPath = projectAupFromAfsPath;
+exports.projectAupResources = projectAupResources;

package/dist/projectors/aup-projector.d.cts

@@ -0,0 +1,59 @@
+import { ResourceProjector } from "../mount/types.cjs";
+import { AFS, AFSModule } from "@aigne/afs";
+
+//#region src/projectors/aup-projector.d.ts
+/**
+ * @internal
+ * AUP projector singleton — the first-class abstraction.
+ */
+declare const aupResourceProjector: ResourceProjector;
+/**
+ * @internal
+ * Thin wrapper exposing the same behaviour as
+ * {@link aupResourceProjector}.project — kept as a stable function reference
+ * for the chain-as-device-placement plan, which imports this name directly.
+ */
+declare function projectAupResources(opts: {
+  afs: AFS;
+  mountPath: string;
+  resources: AFSModule;
+  scope?: "host" | "blocklet" | "instance";
+}): Promise<void>;
+/**
+ * @internal
+ * Scan an existing AFS path for `*.json` recipe files and mount each one as
+ * a hidden `AupRecipeProvider` supplement under `{mountTarget}`.
+ *
+ * Used both by `projectAupResources` (after temp-mounting an opaque
+ * resources module) and by Node's `autoSupplementAup` virtual-path flow
+ * (which already has a live AFS path to scan).
+ *
+ * Missing `scanRoot` → silent no-op, mirroring the original loader contract.
+ */
+declare function projectAupFromAfsPath(opts: {
+  afs: AFS;
+  scanRoot: string;
+  mountTarget: string;
+}): Promise<void>;
+/**
+ * @internal
+ * Parse a relative path inside an `aup/` directory into the mount-path
+ * components the supplement will occupy. Prefix segments are translated from
+ * `_param` placeholder syntax to `:param` mount syntax (see
+ * {@link translateParamSegment}); the view name is never translated.
+ *
+ * ```
+ * /default.json                  → { prefix: "",                  viewName: "default" }
+ * /transactions/item.json        → { prefix: "/transactions",     viewName: "item" }
+ * /a/b/c/view.json               → { prefix: "/a/b/c",            viewName: "view" }
+ * /bridges/_addr/blocks/item.json→ { prefix: "/bridges/:addr/blocks", viewName: "item" }
+ * /traces/_date/_runId/item.json → { prefix: "/traces/:date/:runId",  viewName: "item" }
+ * ```
+ */
+declare function parseAupFilePath(relPath: string): {
+  prefix: string;
+  viewName: string;
+};
+//#endregion
+export { aupResourceProjector, parseAupFilePath, projectAupFromAfsPath, projectAupResources };
+//# sourceMappingURL=aup-projector.d.cts.map

package/dist/projectors/aup-projector.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aup-projector.d.cts","names":[],"sources":["../../src/projectors/aup-projector.ts"],"mappings":";;;;;;;;cAqEa,oBAAA,EAAsB,iBAAA;;;;;AA4DnC;;iBA/CsB,mBAAA,CAAoB,IAAA;EACxC,GAAA,EAAK,GAAA;EACL,SAAA;EACA,SAAA,EAAW,SAAA;EACX,KAAA;AAAA,IACE,OAAA;;;;;AA0IJ;;;;;;;iBAhGsB,qBAAA,CAAsB,IAAA;EAC1C,GAAA,EAAK,GAAA;EACL,QAAA;EACA,WAAA;AAAA,IACE,OAAA;;;;;;;;;;;;;;;;iBA4FY,gBAAA,CAAiB,OAAA;EAAoB,MAAA;EAAgB,QAAA;AAAA"}