@aigne/aos 0.2.0-beta

package/dist/system-mounts/installers.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"installers.mjs","names":[],"sources":["../../src/system-mounts/installers.ts"],"sourcesContent":["/**\n * Runtime-neutral `install` escape-hatch implementations for the composite\n * entries in {@link SYSTEM_MOUNTS} (design.md §4.1). These orchestrate\n * multi-step mounts that a single `path`+`providerKey` can't express:\n *\n *  - {@link aiInstall}            — `/dev/ai` device + legacy/compat projections\n *  - {@link chainInstall}         — `/dev/chain/<network>` per builtin/config network + AUP\n *  - {@link deviceInstall}        — `/dev/ui`, `/dev/web` projections (conditional on source)\n *  - {@link observabilityInstall} — `/dev/observability` (+ optional host-inbox)\n *  - {@link messagingInstall}     — `/proc/messaging/agents` + `/proc/messaging/tools`\n *\n * Crucial invariant: NONE of these import a runtime-specific module. All\n * provider *construction* is delegated to the `registry` factories the\n * runtime supplies (Node builds disk-backed providers + loads AUP from the\n * package dir; CF builds bundled providers + loads AUP over HTTP). Projection\n * uses `ProjectionProvider` from `@aigne/afs` (runtime-neutral) and AUP\n * companion resources flow through the factory's `resources` field + the\n * materializer's `aupResourceProjector`. So these hatches bundle cleanly into\n * the Cloudflare Worker even when CF's registry omits the keys (the hatch\n * skips that sub-mount).\n */\n\nimport { type AFS, type AFSRoot, ProjectionProvider } from \"@aigne/afs\";\nimport { time } from \"@aigne/afs-timing\";\nimport { joinURL } from \"ufo\";\nimport {\n  BUILTIN_CHAIN_NETWORKS,\n  type ChainNetworkConfig,\n  chainNetworkToMountEntry,\n  validateChainNetworks,\n} from \"../devices/chain.js\";\nimport { materializeProviderMount, type ProviderFactory, redactError } from \"../mount/index.js\";\nimport { aupResourceProjector } from \"../projectors/index.js\";\nimport type { InstallOutcome, SystemMountContext } from \"./types.js\";\n\nconst PROJECTION_OVERLAY = { allowOverlay: true } as const;\n\nfunction getMounts(afs: AFSRoot): { path: string }[] {\n  const fn = (afs as unknown as AFS).getMounts;\n  return typeof fn === \"function\" ? fn.call(afs) : [];\n}\n\nfunction hasMount(afs: AFSRoot, path: string): boolean {\n  return getMounts(afs).some((m) => m.path === path);\n}\n\n/** Mount a `ProjectionProvider` alias `target → source`, idempotent + tolerant. */\nasync function mountProjection(\n  afs: AFSRoot,\n  target: string,\n  source: string,\n  name: string,\n  out: InstallOutcome,\n): Promise<void> {\n  if (hasMount(afs, target)) return;\n  try {\n    await (afs as unknown as AFS).mount(\n      new ProjectionProvider({ name, globalAFS: afs as unknown as AFS, sourcePath: source }),\n      target,\n      PROJECTION_OVERLAY,\n    );\n    out.mounted.push(target);\n  } catch (err) {\n    out.warnings.push(`${target}: projection failed — ${redactError(err)}`);\n  }\n}\n\n// ── AI ──────────────────────────────────────────────────────────────────────\n// Port of runtimes/node/src/config/system-ai-mounts.ts, with the device\n// constructed via registry[\"ai-device\"] instead of a direct `new AFSAIDevice`.\n\nconst AI_DEVICE = \"/dev/ai\";\nconst AI_HUBS_AIGNEHUB = \"/dev/ai/hubs/aignehub\";\nconst AI_LOCAL_EMBEDDING = \"/dev/ai/local/embedding\";\nconst LEGACY_AIGNEHUB = \"/modules/aignehub\";\nconst LEGACY_EMBEDDING = \"/modules/embedding\";\nconst COMPAT_HUB = \"/dev/ai/hub\";\nconst COMPAT_DEFAULTS = \"/dev/ai/defaults\";\nconst COMPAT_EMBEDDING = \"/dev/ai/embedding\";\n\nexport async function aiInstall(\n  afs: AFSRoot,\n  _ctx: SystemMountContext,\n  registry: Record<string, ProviderFactory>,\n): Promise<InstallOutcome> {\n  const out: InstallOutcome = { mounted: [], warnings: [] };\n\n  // Step 1: legacy AIGNE Hub → canonical /dev/ai/hubs/aignehub.\n  if (!hasMount(afs, AI_HUBS_AIGNEHUB)) {\n    const legacy = hasMount(afs, LEGACY_AIGNEHUB)\n      ? LEGACY_AIGNEHUB\n      : hasMount(afs, COMPAT_HUB)\n        ? COMPAT_HUB\n        : null;\n    if (legacy) await mountProjection(afs, AI_HUBS_AIGNEHUB, legacy, \"dev-ai-hubs-aignehub\", out);\n  }\n\n  // Step 2: legacy embedding → canonical /dev/ai/local/embedding.\n  if (!hasMount(afs, AI_LOCAL_EMBEDDING) && hasMount(afs, LEGACY_EMBEDDING)) {\n    await mountProjection(afs, AI_LOCAL_EMBEDDING, LEGACY_EMBEDDING, \"dev-ai-local-embedding\", out);\n  }\n\n  // Step 3: backward-compat aliases.\n  if (hasMount(afs, AI_HUBS_AIGNEHUB)) {\n    await mountProjection(afs, COMPAT_HUB, AI_HUBS_AIGNEHUB, \"dev-ai-hub-compat\", out);\n    await mountProjection(\n      afs,\n      COMPAT_DEFAULTS,\n      joinURL(AI_HUBS_AIGNEHUB, \"defaults\"),\n      \"dev-ai-defaults-compat\",\n      out,\n    );\n  }\n  if (hasMount(afs, AI_LOCAL_EMBEDDING)) {\n    await mountProjection(\n      afs,\n      COMPAT_EMBEDDING,\n      AI_LOCAL_EMBEDDING,\n      \"dev-ai-embedding-compat\",\n      out,\n    );\n  }\n\n  // Step 4: device parent at /dev/ai (after hub/local children), via registry.\n  // A runtime that doesn't register `ai-device` simply skips this mount — that\n  // is intentional subset behaviour (matches the driver's default-path\n  // skip-silently), NOT a warning-worthy failure.\n  if (!hasMount(afs, AI_DEVICE)) {\n    const factory = registry[\"ai-device\"];\n    if (factory) {\n      try {\n        const options: Record<string, unknown> = { globalAFS: afs };\n        if (hasMount(afs, \"/user\")) options.userSpaceRoot = \"/user\";\n        const { provider } = await factory.create({\n          uri: `ai-device://system${AI_DEVICE}`,\n          type: \"ai-device\",\n          options,\n        });\n        await (afs as unknown as AFS).mount(provider, AI_DEVICE, PROJECTION_OVERLAY);\n        out.mounted.push(AI_DEVICE);\n      } catch (err) {\n        out.warnings.push(`${AI_DEVICE}: mount failed — ${redactError(err)}`);\n      }\n    }\n  }\n\n  return out;\n}\n\n// ── chain ─────────────────────────────────────────────────────────────────\n// Port of runtimes/node/src/config/system-chain-mounts.ts through the\n// materializer. `validateChainNetworks` THROWS on bad config — that throw\n// propagates out of the driver, keeping chain config errors fatal (the Node\n// daemon refuses to start rather than half-applying), matching legacy.\n\nexport async function chainInstall(\n  afs: AFSRoot,\n  ctx: SystemMountContext,\n  registry: Record<string, ProviderFactory>,\n): Promise<InstallOutcome> {\n  const out: InstallOutcome = { mounted: [], warnings: [] };\n\n  const configs = ctx.chainConfigs as readonly ChainNetworkConfig[] | undefined;\n  const source = configs && configs.length > 0 ? configs : BUILTIN_CHAIN_NETWORKS;\n  const cfgs: ChainNetworkConfig[] = [...source];\n\n  // Fatal on bad config (throws) — do NOT catch.\n  validateChainNetworks(cfgs);\n\n  // No `ocap` factory → this runtime can't build chain mounts; skip silently\n  // (intentional subset, not a failure). validateChainNetworks above still runs\n  // so bad config stays fatal regardless of whether the factory is present.\n  const factory = registry[\"ocap\"];\n  if (!factory) return out;\n\n  for (const cfg of cfgs) {\n    const path = chainNetworkToMountEntry(cfg).path;\n    if (hasMount(afs, path)) continue;\n    try {\n      // Per-network span (`mnt.dev.chain.main` / `.beta`) so the two builtin\n      // networks are individually attributable in cold-start Server-Timing.\n      await time(`mnt.dev.chain.${cfg.network}`, () =>\n        materializeProviderMount({\n          afs: afs as unknown as AFS,\n          mountPath: path,\n          definition: {\n            uri: `ocap://system${path}`,\n            type: \"ocap\",\n            options: {\n              endpoint: cfg.endpoint,\n              description: `Chain network ${cfg.network} via ${safeEndpointLabel(cfg.endpoint)}`,\n            },\n          },\n          factory,\n          projectors: [aupResourceProjector],\n          scope: \"host\",\n          mountOptions: PROJECTION_OVERLAY,\n          // Host scope: the chain mount is useful without AUP supplements, so a\n          // recipe-projection failure must not unmount the data tree.\n          projectionFailure: \"warn\",\n        }),\n      );\n      out.mounted.push(path);\n    } catch (err) {\n      out.warnings.push(`${path}: mount failed — ${redactError(err)}`);\n    }\n  }\n\n  return out;\n}\n\nfunction safeEndpointLabel(endpoint: string): string {\n  try {\n    const url = new URL(endpoint);\n    return `${url.protocol}//${url.host}`;\n  } catch {\n    return \"<endpoint>\";\n  }\n}\n\n// ── device (ui/web) ─────────────────────────────────────────────────────────\n// Port of runtimes/node/src/config/system-device-mounts.ts. Pure projections,\n// conditional on the source mounts existing.\n\nexport async function deviceInstall(afs: AFSRoot): Promise<InstallOutcome> {\n  const out: InstallOutcome = { mounted: [], warnings: [] };\n  const pairs: Array<[string, string, string]> = [\n    [\"/dev/ui\", \"/ui\", \"dev-ui\"],\n    [\"/dev/web\", \"/web\", \"dev-web\"],\n  ];\n  for (const [target, source, name] of pairs) {\n    if (hasMount(afs, target)) continue;\n    if (!hasMount(afs, source)) continue;\n    await mountProjection(afs, target, source, name, out);\n  }\n  return out;\n}\n\n// ── observability ─────────────────────────────────────────────────────────\n// Port of runtimes/node/src/config/system-observability-mounts.ts. The\n// host-inbox (a node-only AFSFS) is built via registry[\"observability-host-inbox\"];\n// CF omits that key → no host-inbox, viewer still mounts. All failures degrade\n// to warnings (observability is supplementary — never abort startup).\n\nconst OBS_PATH = \"/dev/observability\";\nconst OBS_HOST_INBOX = \"/dev/observability/.host-inbox\";\n\nexport async function observabilityInstall(\n  afs: AFSRoot,\n  _ctx: SystemMountContext,\n  registry: Record<string, ProviderFactory>,\n): Promise<InstallOutcome> {\n  const out: InstallOutcome = { mounted: [], warnings: [] };\n\n  if (hasMount(afs, OBS_PATH)) {\n    out.warnings.push(`${OBS_PATH}: already mounted — skipped`);\n    return out;\n  }\n\n  // Host-inbox: hidden FS where CLI/system runs land jsonl traces. Node-only.\n  let hostInboxMounted = false;\n  const hostInboxFactory = registry[\"observability-host-inbox\"];\n  if (hostInboxFactory) {\n    try {\n      const { provider } = await hostInboxFactory.create({\n        uri: `fs://system${OBS_HOST_INBOX}`,\n        type: \"fs\",\n      });\n      await (afs as unknown as AFS).mount(provider, OBS_HOST_INBOX, { hidden: true });\n      hostInboxMounted = true;\n      out.mounted.push(OBS_HOST_INBOX);\n    } catch (err) {\n      out.warnings.push(`${OBS_HOST_INBOX}: mount failed — ${redactError(err)}`);\n    }\n  }\n\n  // No `observability` factory → this runtime doesn't ship the viewer (e.g. CF\n  // today; it's a P5 item). Skip silently — intentional subset, not a failure.\n  // Logging a warning here on every createAfsFromEnv was pure noise.\n  const factory = registry[\"observability\"];\n  if (!factory) return out;\n  try {\n    await materializeProviderMount({\n      afs: afs as unknown as AFS,\n      mountPath: OBS_PATH,\n      definition: {\n        uri: `observability://system${OBS_PATH}`,\n        type: \"observability\",\n        options: {\n          upstream: afs,\n          description: \"AI agent observability — jsonl event log viewer\",\n          ...(hostInboxMounted ? { hostInboxPath: OBS_HOST_INBOX } : {}),\n        },\n      },\n      factory,\n      projectors: [aupResourceProjector],\n      scope: \"host\",\n      mountOptions: PROJECTION_OVERLAY,\n      projectionFailure: \"warn\",\n    });\n    out.mounted.push(OBS_PATH);\n  } catch (err) {\n    out.warnings.push(`${OBS_PATH}: mount failed — ${redactError(err)}`);\n  }\n\n  return out;\n}\n\n// ── messaging ─────────────────────────────────────────────────────────────\n// Two subtrees mirroring daemon.ts:3954/3966. Both providers are node-only\n// (FS inbox + the messaging builtin), so the Node daemon mounts them directly\n// in its own context (it owns `userDataRoot`); this hatch is the shared\n// contract + the path CF would take once it registers messaging keys. When the\n// registry lacks the keys (afs-loader, CF today) it no-ops.\n\nconst MSG_AGENTS = \"/proc/messaging/agents\";\nconst MSG_TOOLS = \"/proc/messaging/tools\";\n\nexport async function messagingInstall(\n  afs: AFSRoot,\n  _ctx: SystemMountContext,\n  registry: Record<string, ProviderFactory>,\n): Promise<InstallOutcome> {\n  const out: InstallOutcome = { mounted: [], warnings: [] };\n\n  const agentsFactory = registry[\"messaging-agents\"];\n  if (agentsFactory && !hasMount(afs, MSG_AGENTS)) {\n    try {\n      const { provider } = await agentsFactory.create({\n        uri: `fs://system${MSG_AGENTS}`,\n        type: \"fs\",\n      });\n      await (afs as unknown as AFS).mount(provider, MSG_AGENTS, PROJECTION_OVERLAY);\n      out.mounted.push(MSG_AGENTS);\n    } catch (err) {\n      out.warnings.push(`${MSG_AGENTS}: mount failed — ${redactError(err)}`);\n    }\n  }\n\n  const toolsFactory = registry[\"messaging-tools\"];\n  if (toolsFactory && !hasMount(afs, MSG_TOOLS)) {\n    try {\n      const { provider } = await toolsFactory.create({\n        uri: `messaging-tools://system${MSG_TOOLS}`,\n        type: \"messaging-tools\",\n      });\n      await (afs as unknown as AFS).mount(provider, MSG_TOOLS, PROJECTION_OVERLAY);\n      out.mounted.push(MSG_TOOLS);\n    } catch (err) {\n      out.warnings.push(`${MSG_TOOLS}: mount failed — ${redactError(err)}`);\n    }\n  }\n\n  return out;\n}\n"],"mappings":"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"}

package/dist/system-mounts/lists.cjs

@@ -0,0 +1,122 @@
+const require_installers = require('./installers.cjs');
+
+//#region src/system-mounts/lists.ts
+/**
+* The two single-source-of-truth lists this design produces (design.md §4):
+*
+*  - {@link SYSTEM_MOUNTS}        — axis A, host-install descriptors.
+*  - {@link SMALL_WORLD_PROJECTION} — axis B, which host system mounts each
+*    blocklet's small-world session AFS may project.
+*
+* Both are frozen so a downstream consumer that mutates one (push/splice/
+* index-assign) can't corrupt the other runtime's view — the lists are
+* shared module singletons.
+*
+* Phase 0 ships `SMALL_WORLD_PROJECTION` fully populated (pure string data,
+* no logic) and `SYSTEM_MOUNTS` as a frozen empty array. Phase 1 replaces
+* the `SYSTEM_MOUNTS` body with the full descriptor list once the `install`
+* escape-hatch logic exists.
+*/
+/**
+* Axis A — the host-install single source of truth. Each runtime materializes
+* the entries whose `providerKey` its registry can build (or whose `install`
+* hatch's dependencies it can satisfy); the rest are skipped silently.
+*
+* Order bands (design.md §4): ash(10) → agent(20) → index(30) → ai(40) →
+* ai-agent(41) → chain(50) → device(60) → observability(70) → messaging(80).
+* `/ash` precedes `/dev/agent` (agent's lazy `runAsh` dep); AI device parent
+* is installed after its hub/local children inside the hatch; the `/dev/ai/agent`
+* exec adapter overlays the `/dev/ai` device (so it is ordered right after it).
+*
+* `/modules/memory` is intentionally absent — it is NOT a host-install (§2.1).
+*
+* Frozen so a downstream consumer can't corrupt the shared list.
+*/
+const SYSTEM_MOUNTS = Object.freeze([
+	{
+		path: "/ash",
+		providerKey: "ash",
+		order: 10,
+		mountOptions: { allowOverlay: true }
+	},
+	{
+		path: "/dev/agent",
+		providerKey: "agent",
+		order: 20,
+		dependsOn: ["/ash"],
+		mountOptions: { allowOverlay: true }
+	},
+	{
+		path: "/modules/index",
+		providerKey: "index",
+		order: 30,
+		mountOptions: { allowOverlay: true }
+	},
+	{
+		path: "/modules/embedding",
+		providerKey: "embedding",
+		order: 35,
+		mountOptions: { allowOverlay: true }
+	},
+	{
+		path: "/dev/ai",
+		order: 40,
+		install: require_installers.aiInstall
+	},
+	{
+		path: "/dev/ai/agent",
+		providerKey: "ai-agent",
+		order: 41,
+		dependsOn: ["/dev/ai", "/dev/agent"],
+		mountOptions: { allowOverlay: true }
+	},
+	{
+		path: "/dev/chain",
+		order: 50,
+		install: require_installers.chainInstall,
+		dependsOn: ["/dev/ai"]
+	},
+	{
+		path: "/dev/ui",
+		order: 60,
+		install: require_installers.deviceInstall
+	},
+	{
+		path: "/dev/observability",
+		order: 70,
+		install: require_installers.observabilityInstall
+	},
+	{
+		path: "/proc/messaging",
+		order: 80,
+		install: require_installers.messagingInstall
+	}
+]);
+/**
+* Axis B — the small-world projection allow-list (design.md §2.1 / §4).
+* Mirrors the Node daemon's `systemMounts` array (daemon.ts:3812). Each
+* runtime projects only the entries it actually has on its host AFS; missing
+* ones are skipped without error (CF, today, only has `/dev/ai` + `/dev/chain`).
+*
+* `/modules/memory` is **legacy-only**: it is NOT a host-install (see §2.1 —
+* it's the `MEMORY_SCRATCH_ROOT` constant wired by `setAgentMemoryRoot`, not
+* an `afs.mount`), but it stays in the projection so older blocklets can keep
+* reading legacy scratch until a dedicated cleanup.
+*/
+const SMALL_WORLD_PROJECTION = Object.freeze([
+	"/ash",
+	"/dev/ai",
+	"/dev/agent",
+	"/dev/ui",
+	"/dev/web",
+	"/dev/chain",
+	"/dev/observability",
+	"/modules/index",
+	"/modules/embedding",
+	"/proc/messaging",
+	"/modules/memory"
+]);
+
+//#endregion
+exports.SMALL_WORLD_PROJECTION = SMALL_WORLD_PROJECTION;
+exports.SYSTEM_MOUNTS = SYSTEM_MOUNTS;

package/dist/system-mounts/lists.d.cts

@@ -0,0 +1,34 @@
+import { SmallWorldProjection, SystemMountDescriptor } from "./types.cjs";
+
+//#region src/system-mounts/lists.d.ts
+/**
+ * Axis A — the host-install single source of truth. Each runtime materializes
+ * the entries whose `providerKey` its registry can build (or whose `install`
+ * hatch's dependencies it can satisfy); the rest are skipped silently.
+ *
+ * Order bands (design.md §4): ash(10) → agent(20) → index(30) → ai(40) →
+ * ai-agent(41) → chain(50) → device(60) → observability(70) → messaging(80).
+ * `/ash` precedes `/dev/agent` (agent's lazy `runAsh` dep); AI device parent
+ * is installed after its hub/local children inside the hatch; the `/dev/ai/agent`
+ * exec adapter overlays the `/dev/ai` device (so it is ordered right after it).
+ *
+ * `/modules/memory` is intentionally absent — it is NOT a host-install (§2.1).
+ *
+ * Frozen so a downstream consumer can't corrupt the shared list.
+ */
+declare const SYSTEM_MOUNTS: readonly SystemMountDescriptor[];
+/**
+ * Axis B — the small-world projection allow-list (design.md §2.1 / §4).
+ * Mirrors the Node daemon's `systemMounts` array (daemon.ts:3812). Each
+ * runtime projects only the entries it actually has on its host AFS; missing
+ * ones are skipped without error (CF, today, only has `/dev/ai` + `/dev/chain`).
+ *
+ * `/modules/memory` is **legacy-only**: it is NOT a host-install (see §2.1 —
+ * it's the `MEMORY_SCRATCH_ROOT` constant wired by `setAgentMemoryRoot`, not
+ * an `afs.mount`), but it stays in the projection so older blocklets can keep
+ * reading legacy scratch until a dedicated cleanup.
+ */
+declare const SMALL_WORLD_PROJECTION: SmallWorldProjection;
+//#endregion
+export { SMALL_WORLD_PROJECTION, SYSTEM_MOUNTS };
+//# sourceMappingURL=lists.d.cts.map

package/dist/system-mounts/lists.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lists.d.cts","names":[],"sources":["../../src/system-mounts/lists.ts"],"mappings":";;;;;;;;;;;;;;;;;;cAyCa,aAAA,WAAwB,qBAAA;;;;;;;;;;;;cA0DxB,sBAAA,EAAwB,oBAAA"}

package/dist/system-mounts/lists.d.mts

@@ -0,0 +1,34 @@
+import { SmallWorldProjection, SystemMountDescriptor } from "./types.mjs";
+
+//#region src/system-mounts/lists.d.ts
+/**
+ * Axis A — the host-install single source of truth. Each runtime materializes
+ * the entries whose `providerKey` its registry can build (or whose `install`
+ * hatch's dependencies it can satisfy); the rest are skipped silently.
+ *
+ * Order bands (design.md §4): ash(10) → agent(20) → index(30) → ai(40) →
+ * ai-agent(41) → chain(50) → device(60) → observability(70) → messaging(80).
+ * `/ash` precedes `/dev/agent` (agent's lazy `runAsh` dep); AI device parent
+ * is installed after its hub/local children inside the hatch; the `/dev/ai/agent`
+ * exec adapter overlays the `/dev/ai` device (so it is ordered right after it).
+ *
+ * `/modules/memory` is intentionally absent — it is NOT a host-install (§2.1).
+ *
+ * Frozen so a downstream consumer can't corrupt the shared list.
+ */
+declare const SYSTEM_MOUNTS: readonly SystemMountDescriptor[];
+/**
+ * Axis B — the small-world projection allow-list (design.md §2.1 / §4).
+ * Mirrors the Node daemon's `systemMounts` array (daemon.ts:3812). Each
+ * runtime projects only the entries it actually has on its host AFS; missing
+ * ones are skipped without error (CF, today, only has `/dev/ai` + `/dev/chain`).
+ *
+ * `/modules/memory` is **legacy-only**: it is NOT a host-install (see §2.1 —
+ * it's the `MEMORY_SCRATCH_ROOT` constant wired by `setAgentMemoryRoot`, not
+ * an `afs.mount`), but it stays in the projection so older blocklets can keep
+ * reading legacy scratch until a dedicated cleanup.
+ */
+declare const SMALL_WORLD_PROJECTION: SmallWorldProjection;
+//#endregion
+export { SMALL_WORLD_PROJECTION, SYSTEM_MOUNTS };
+//# sourceMappingURL=lists.d.mts.map

package/dist/system-mounts/lists.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lists.d.mts","names":[],"sources":["../../src/system-mounts/lists.ts"],"mappings":";;;;;;;;;;;;;;;;;;cAyCa,aAAA,WAAwB,qBAAA;;;;;;;;;;;;cA0DxB,sBAAA,EAAwB,oBAAA"}

package/dist/system-mounts/lists.mjs

@@ -0,0 +1,122 @@
+import { aiInstall, chainInstall, deviceInstall, messagingInstall, observabilityInstall } from "./installers.mjs";
+
+//#region src/system-mounts/lists.ts
+/**
+* The two single-source-of-truth lists this design produces (design.md §4):
+*
+*  - {@link SYSTEM_MOUNTS}        — axis A, host-install descriptors.
+*  - {@link SMALL_WORLD_PROJECTION} — axis B, which host system mounts each
+*    blocklet's small-world session AFS may project.
+*
+* Both are frozen so a downstream consumer that mutates one (push/splice/
+* index-assign) can't corrupt the other runtime's view — the lists are
+* shared module singletons.
+*
+* Phase 0 ships `SMALL_WORLD_PROJECTION` fully populated (pure string data,
+* no logic) and `SYSTEM_MOUNTS` as a frozen empty array. Phase 1 replaces
+* the `SYSTEM_MOUNTS` body with the full descriptor list once the `install`
+* escape-hatch logic exists.
+*/
+/**
+* Axis A — the host-install single source of truth. Each runtime materializes
+* the entries whose `providerKey` its registry can build (or whose `install`
+* hatch's dependencies it can satisfy); the rest are skipped silently.
+*
+* Order bands (design.md §4): ash(10) → agent(20) → index(30) → ai(40) →
+* ai-agent(41) → chain(50) → device(60) → observability(70) → messaging(80).
+* `/ash` precedes `/dev/agent` (agent's lazy `runAsh` dep); AI device parent
+* is installed after its hub/local children inside the hatch; the `/dev/ai/agent`
+* exec adapter overlays the `/dev/ai` device (so it is ordered right after it).
+*
+* `/modules/memory` is intentionally absent — it is NOT a host-install (§2.1).
+*
+* Frozen so a downstream consumer can't corrupt the shared list.
+*/
+const SYSTEM_MOUNTS = Object.freeze([
+	{
+		path: "/ash",
+		providerKey: "ash",
+		order: 10,
+		mountOptions: { allowOverlay: true }
+	},
+	{
+		path: "/dev/agent",
+		providerKey: "agent",
+		order: 20,
+		dependsOn: ["/ash"],
+		mountOptions: { allowOverlay: true }
+	},
+	{
+		path: "/modules/index",
+		providerKey: "index",
+		order: 30,
+		mountOptions: { allowOverlay: true }
+	},
+	{
+		path: "/modules/embedding",
+		providerKey: "embedding",
+		order: 35,
+		mountOptions: { allowOverlay: true }
+	},
+	{
+		path: "/dev/ai",
+		order: 40,
+		install: aiInstall
+	},
+	{
+		path: "/dev/ai/agent",
+		providerKey: "ai-agent",
+		order: 41,
+		dependsOn: ["/dev/ai", "/dev/agent"],
+		mountOptions: { allowOverlay: true }
+	},
+	{
+		path: "/dev/chain",
+		order: 50,
+		install: chainInstall,
+		dependsOn: ["/dev/ai"]
+	},
+	{
+		path: "/dev/ui",
+		order: 60,
+		install: deviceInstall
+	},
+	{
+		path: "/dev/observability",
+		order: 70,
+		install: observabilityInstall
+	},
+	{
+		path: "/proc/messaging",
+		order: 80,
+		install: messagingInstall
+	}
+]);
+/**
+* Axis B — the small-world projection allow-list (design.md §2.1 / §4).
+* Mirrors the Node daemon's `systemMounts` array (daemon.ts:3812). Each
+* runtime projects only the entries it actually has on its host AFS; missing
+* ones are skipped without error (CF, today, only has `/dev/ai` + `/dev/chain`).
+*
+* `/modules/memory` is **legacy-only**: it is NOT a host-install (see §2.1 —
+* it's the `MEMORY_SCRATCH_ROOT` constant wired by `setAgentMemoryRoot`, not
+* an `afs.mount`), but it stays in the projection so older blocklets can keep
+* reading legacy scratch until a dedicated cleanup.
+*/
+const SMALL_WORLD_PROJECTION = Object.freeze([
+	"/ash",
+	"/dev/ai",
+	"/dev/agent",
+	"/dev/ui",
+	"/dev/web",
+	"/dev/chain",
+	"/dev/observability",
+	"/modules/index",
+	"/modules/embedding",
+	"/proc/messaging",
+	"/modules/memory"
+]);
+
+//#endregion
+export { SMALL_WORLD_PROJECTION, SYSTEM_MOUNTS };
+//# sourceMappingURL=lists.mjs.map

package/dist/system-mounts/lists.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"lists.mjs","names":[],"sources":["../../src/system-mounts/lists.ts"],"sourcesContent":["/**\n * The two single-source-of-truth lists this design produces (design.md §4):\n *\n *  - {@link SYSTEM_MOUNTS}        — axis A, host-install descriptors.\n *  - {@link SMALL_WORLD_PROJECTION} — axis B, which host system mounts each\n *    blocklet's small-world session AFS may project.\n *\n * Both are frozen so a downstream consumer that mutates one (push/splice/\n * index-assign) can't corrupt the other runtime's view — the lists are\n * shared module singletons.\n *\n * Phase 0 ships `SMALL_WORLD_PROJECTION` fully populated (pure string data,\n * no logic) and `SYSTEM_MOUNTS` as a frozen empty array. Phase 1 replaces\n * the `SYSTEM_MOUNTS` body with the full descriptor list once the `install`\n * escape-hatch logic exists.\n */\n\nimport {\n  aiInstall,\n  chainInstall,\n  deviceInstall,\n  messagingInstall,\n  observabilityInstall,\n} from \"./installers.js\";\nimport type { SmallWorldProjection, SystemMountDescriptor } from \"./types.js\";\n\n/**\n * Axis A — the host-install single source of truth. Each runtime materializes\n * the entries whose `providerKey` its registry can build (or whose `install`\n * hatch's dependencies it can satisfy); the rest are skipped silently.\n *\n * Order bands (design.md §4): ash(10) → agent(20) → index(30) → ai(40) →\n * ai-agent(41) → chain(50) → device(60) → observability(70) → messaging(80).\n * `/ash` precedes `/dev/agent` (agent's lazy `runAsh` dep); AI device parent\n * is installed after its hub/local children inside the hatch; the `/dev/ai/agent`\n * exec adapter overlays the `/dev/ai` device (so it is ordered right after it).\n *\n * `/modules/memory` is intentionally absent — it is NOT a host-install (§2.1).\n *\n * Frozen so a downstream consumer can't corrupt the shared list.\n */\nexport const SYSTEM_MOUNTS: readonly SystemMountDescriptor[] = Object.freeze([\n  { path: \"/ash\", providerKey: \"ash\", order: 10, mountOptions: { allowOverlay: true } },\n  {\n    path: \"/dev/agent\",\n    providerKey: \"agent\",\n    order: 20,\n    dependsOn: [\"/ash\"],\n    mountOptions: { allowOverlay: true },\n  },\n  { path: \"/modules/index\", providerKey: \"index\", order: 30, mountOptions: { allowOverlay: true } },\n  // Local embedding provider — order 35 so it is mounted BEFORE the `/dev/ai`\n  // hatch (40), which projects `/modules/embedding` → `/dev/ai/local/embedding`.\n  // A runtime whose registry has no `embedding` factory (CF uses workers-ai)\n  // skips this silently, and the projection then no-ops.\n  {\n    path: \"/modules/embedding\",\n    providerKey: \"embedding\",\n    order: 35,\n    mountOptions: { allowOverlay: true },\n  },\n  // Composite: device parent + legacy/compat projections (design §4.1).\n  { path: \"/dev/ai\", order: 40, install: aiInstall },\n  // Agent-run exec adapter (@aigne/afs-ai-agent): exposes `.actions/run` +\n  // `.actions/run-code` that agent-handler.ts dispatches for the generic chat\n  // surface. It overlays the readonly `/dev/ai` device, so it MUST be ordered\n  // after it (41 > 40) and mounted with `allowOverlay`. Without this mount the\n  // handler's `/dev/ai/agent/.actions/run` exec falls through to the readonly\n  // `/dev/ai` device → \"Cannot exec on a readonly provider\" (issue #1390). A\n  // runtime whose registry lacks the `ai-agent` key skips it silently.\n  {\n    path: \"/dev/ai/agent\",\n    providerKey: \"ai-agent\",\n    order: 41,\n    dependsOn: [\"/dev/ai\", \"/dev/agent\"],\n    mountOptions: { allowOverlay: true },\n  },\n  // Composite: per-network OCAP mounts + AUP; chain config errors stay fatal.\n  { path: \"/dev/chain\", order: 50, install: chainInstall, dependsOn: [\"/dev/ai\"] },\n  // Composite: /dev/ui + /dev/web projections, conditional on /ui + /web.\n  { path: \"/dev/ui\", order: 60, install: deviceInstall },\n  // Composite: viewer (+ optional node-only host-inbox).\n  { path: \"/dev/observability\", order: 70, install: observabilityInstall },\n  // Composite: /proc/messaging/agents + /proc/messaging/tools (node-only; the\n  // Node daemon mounts these in its own context — this is the shared contract).\n  { path: \"/proc/messaging\", order: 80, install: messagingInstall },\n]);\n\n/**\n * Axis B — the small-world projection allow-list (design.md §2.1 / §4).\n * Mirrors the Node daemon's `systemMounts` array (daemon.ts:3812). Each\n * runtime projects only the entries it actually has on its host AFS; missing\n * ones are skipped without error (CF, today, only has `/dev/ai` + `/dev/chain`).\n *\n * `/modules/memory` is **legacy-only**: it is NOT a host-install (see §2.1 —\n * it's the `MEMORY_SCRATCH_ROOT` constant wired by `setAgentMemoryRoot`, not\n * an `afs.mount`), but it stays in the projection so older blocklets can keep\n * reading legacy scratch until a dedicated cleanup.\n */\nexport const SMALL_WORLD_PROJECTION: SmallWorldProjection = Object.freeze([\n  \"/ash\",\n  \"/dev/ai\",\n  \"/dev/agent\",\n  \"/dev/ui\",\n  \"/dev/web\",\n  \"/dev/chain\",\n  \"/dev/observability\",\n  \"/modules/index\",\n  \"/modules/embedding\",\n  \"/proc/messaging\",\n  \"/modules/memory\",\n]);\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyCA,MAAa,gBAAkD,OAAO,OAAO;CAC3E;EAAE,MAAM;EAAQ,aAAa;EAAO,OAAO;EAAI,cAAc,EAAE,cAAc,MAAM;EAAE;CACrF;EACE,MAAM;EACN,aAAa;EACb,OAAO;EACP,WAAW,CAAC,OAAO;EACnB,cAAc,EAAE,cAAc,MAAM;EACrC;CACD;EAAE,MAAM;EAAkB,aAAa;EAAS,OAAO;EAAI,cAAc,EAAE,cAAc,MAAM;EAAE;CAKjG;EACE,MAAM;EACN,aAAa;EACb,OAAO;EACP,cAAc,EAAE,cAAc,MAAM;EACrC;CAED;EAAE,MAAM;EAAW,OAAO;EAAI,SAAS;EAAW;CAQlD;EACE,MAAM;EACN,aAAa;EACb,OAAO;EACP,WAAW,CAAC,WAAW,aAAa;EACpC,cAAc,EAAE,cAAc,MAAM;EACrC;CAED;EAAE,MAAM;EAAc,OAAO;EAAI,SAAS;EAAc,WAAW,CAAC,UAAU;EAAE;CAEhF;EAAE,MAAM;EAAW,OAAO;EAAI,SAAS;EAAe;CAEtD;EAAE,MAAM;EAAsB,OAAO;EAAI,SAAS;EAAsB;CAGxE;EAAE,MAAM;EAAmB,OAAO;EAAI,SAAS;EAAkB;CAClE,CAAC;;;;;;;;;;;;AAaF,MAAa,yBAA+C,OAAO,OAAO;CACxE;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD,CAAC"}

package/dist/system-mounts/types.d.cts

@@ -0,0 +1,124 @@
+import { ProviderFactory } from "../mount/types.cjs";
+import { AFSRoot, MountOptions } from "@aigne/afs";
+
+//#region src/system-mounts/types.d.ts
+/**
+ * Runtime-supplied context threaded into descriptor callbacks (`options`,
+ * `conditional`, `install`). Lets a descriptor resolve provider options that
+ * depend on the live AFS (e.g. detect a `/user` mount) or runtime-specific
+ * roots without baking runtime assumptions into the shared list.
+ *
+ * The shape is intentionally open (`[key: string]: unknown`) — runtimes add
+ * their own fields (Node passes `configMountPaths`, a future CF context may
+ * pass D1 bindings) and descriptor callbacks read only what they need.
+ */
+interface SystemMountContext {
+  /**
+   * The global/host AFS the mounts are being installed onto. Same instance
+   * passed to {@link installSystemMounts}'s first argument; re-exposed here
+   * so `options`/`conditional`/`install` callbacks can inspect existing
+   * mounts (e.g. `conditional: (ctx) => hasMount(ctx.afs, "/ui")`).
+   */
+  afs: AFSRoot;
+  /**
+   * Config-declared mount paths already applied to `afs` before system
+   * mounts run. Node's `setupSystemAIMounts` uses this to detect legacy
+   * `/modules/aignehub` hub mounts; CF may pass `[]`.
+   */
+  configMountPaths?: string[];
+  /** Runtime-specific extensions (D1 bindings, user-space roots, …). */
+  [key: string]: unknown;
+}
+/**
+ * The result of installing one descriptor (or the whole list). `mounted`
+ * lists every path actually mounted (including supplement/companion mounts
+ * an `install` hatch adds); `warnings` collects non-fatal failures so the
+ * caller can log them without aborting siblings.
+ */
+interface InstallOutcome {
+  /** Paths newly mounted by this descriptor. */
+  mounted: string[];
+  /** Non-fatal failures (e.g. provider package missing). */
+  warnings: string[];
+}
+/**
+ * A single system-mount declaration. The common case is
+ * `{ path, providerKey, order }` — the driver looks `providerKey` up in the
+ * per-runtime registry and materializes it. Multi-step mounts (AI compat
+ * projections, chain builtins + AUP, observability host-inbox, messaging's
+ * two subtrees) use the {@link SystemMountDescriptor.install} escape hatch.
+ *
+ * @see design.md §4 / §4.1
+ */
+interface SystemMountDescriptor {
+  /** Absolute host-install path, e.g. `"/dev/agent"`. Must start with `/`. */
+  path: string;
+  /**
+   * Registry key the driver looks up to construct the provider, e.g.
+   * `"agent"`, `"ocap"`. Ignored when {@link install} is supplied.
+   * Optional only when `install` is present (a composite installer owns its
+   * own construction).
+   */
+  providerKey?: string;
+  /**
+   * Provider options. Either a literal object or a function of the
+   * {@link SystemMountContext} (for options that depend on the live AFS,
+   * e.g. wiring `userSpaceRoot: "/user"` only when `/user` is mounted).
+   */
+  options?: Record<string, unknown> | ((ctx: SystemMountContext) => Record<string, unknown>);
+  /**
+   * Install order. Lower runs first. Encodes the ordering constraints from
+   * the Node setup group — `/ash` before `/dev/agent`, AI hub children
+   * before the `/dev/ai` device parent, etc. See design.md §4 for the
+   * canonical order band assignments.
+   */
+  order: number;
+  /**
+   * Declarative dependency paths this mount needs in place first. Advisory
+   * metadata for documentation/diagnostics; the driver enforces actual
+   * ordering via {@link order}.
+   */
+  dependsOn?: string[];
+  /**
+   * Predicate gating whether this descriptor installs at all. Returning
+   * `false` skips the mount (not an error). Example: `/dev/ui` only when its
+   * source `/ui` mount exists.
+   */
+  conditional?: (ctx: SystemMountContext) => boolean;
+  /** Forwarded to `afs.mount()` for the data provider (allowOverlay/hidden). */
+  mountOptions?: MountOptions;
+  /**
+   * Strategy when AUP/companion-resource projection fails. `"warn"` keeps the
+   * data mount and logs (host-scope default); `"rollback"` unmounts. Mirrors
+   * the materializer's `projectionFailure`.
+   */
+  projectionFailure?: "warn" | "rollback";
+  /**
+   * Escape hatch for composite mounts that a single
+   * `path`+`providerKey`+`options` can't express (multi-mount subtrees,
+   * legacy-alias projections, validate-then-mount, …). When present the
+   * driver calls this INSTEAD of the default materialize path and ignores
+   * {@link providerKey}. The installer receives the host AFS, the context,
+   * and the runtime registry (so it can reuse registered factories), and
+   * returns what it mounted + any warnings.
+   *
+   * The escape hatch does not break "divergence = data": `install` is still
+   * one entry in the shared list. A runtime whose registry lacks the keys
+   * the installer needs simply has the installer skip those sub-mounts.
+   *
+   * @see design.md §4.1
+   */
+  install?: (afs: AFSRoot, ctx: SystemMountContext, registry: Record<string, ProviderFactory>) => Promise<InstallOutcome>;
+}
+/**
+ * Axis B: the set of host system-mount path prefixes each blocklet's
+ * small-world session AFS should project from the global AFS. A readonly
+ * string list — pure data, no executable callbacks, no injection surface.
+ *
+ * Each runtime projects only the entries that actually exist on its host
+ * AFS (missing ones are skipped, not errored). See design.md §2.1 / §4.
+ */
+type SmallWorldProjection = readonly string[];
+//#endregion
+export { InstallOutcome, SmallWorldProjection, SystemMountContext, SystemMountDescriptor };
+//# sourceMappingURL=types.d.cts.map

package/dist/system-mounts/types.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.cts","names":[],"sources":["../../src/system-mounts/types.ts"],"mappings":";;;;;;;;;;;;;;UAkCiB,kBAAA;EAgHH;;;;;;EAzGZ,GAAA,EAAK,OAAA;EAoDiC;;;;;EA7CtC,gBAAA;EAmEe;EAAA,CAhEd,GAAA;AAAA;;;;;;;UASc,cAAA;EAqFY;EAnF3B,OAAA;EAoFK;EAlFL,QAAA;AAAA;;AA6FF;;;;;;;;UAjFiB,qBAAA;;EAEf,IAAA;;;;;;;EAQA,WAAA;;;;;;EAOA,OAAA,GAAU,MAAA,sBAA4B,GAAA,EAAK,kBAAA,KAAuB,MAAA;;;;;;;EAQlE,KAAA;;;;;;EAOA,SAAA;;;;;;EAOA,WAAA,IAAe,GAAA,EAAK,kBAAA;;EAGpB,YAAA,GAAe,YAAA;;;;;;EAOf,iBAAA;;;;;;;;;;;;;;;;EAiBA,OAAA,IACE,GAAA,EAAK,OAAA,EACL,GAAA,EAAK,kBAAA,EACL,QAAA,EAAU,MAAA,SAAe,eAAA,MACtB,OAAA,CAAQ,cAAA;AAAA;;;;;;;;;KAWH,oBAAA"}

package/dist/system-mounts/types.d.mts

@@ -0,0 +1,125 @@
+import { ProviderFactory } from "../mount/types.mjs";
+import "../mount/index.mjs";
+import { AFSRoot, MountOptions } from "@aigne/afs";
+
+//#region src/system-mounts/types.d.ts
+/**
+ * Runtime-supplied context threaded into descriptor callbacks (`options`,
+ * `conditional`, `install`). Lets a descriptor resolve provider options that
+ * depend on the live AFS (e.g. detect a `/user` mount) or runtime-specific
+ * roots without baking runtime assumptions into the shared list.
+ *
+ * The shape is intentionally open (`[key: string]: unknown`) — runtimes add
+ * their own fields (Node passes `configMountPaths`, a future CF context may
+ * pass D1 bindings) and descriptor callbacks read only what they need.
+ */
+interface SystemMountContext {
+  /**
+   * The global/host AFS the mounts are being installed onto. Same instance
+   * passed to {@link installSystemMounts}'s first argument; re-exposed here
+   * so `options`/`conditional`/`install` callbacks can inspect existing
+   * mounts (e.g. `conditional: (ctx) => hasMount(ctx.afs, "/ui")`).
+   */
+  afs: AFSRoot;
+  /**
+   * Config-declared mount paths already applied to `afs` before system
+   * mounts run. Node's `setupSystemAIMounts` uses this to detect legacy
+   * `/modules/aignehub` hub mounts; CF may pass `[]`.
+   */
+  configMountPaths?: string[];
+  /** Runtime-specific extensions (D1 bindings, user-space roots, …). */
+  [key: string]: unknown;
+}
+/**
+ * The result of installing one descriptor (or the whole list). `mounted`
+ * lists every path actually mounted (including supplement/companion mounts
+ * an `install` hatch adds); `warnings` collects non-fatal failures so the
+ * caller can log them without aborting siblings.
+ */
+interface InstallOutcome {
+  /** Paths newly mounted by this descriptor. */
+  mounted: string[];
+  /** Non-fatal failures (e.g. provider package missing). */
+  warnings: string[];
+}
+/**
+ * A single system-mount declaration. The common case is
+ * `{ path, providerKey, order }` — the driver looks `providerKey` up in the
+ * per-runtime registry and materializes it. Multi-step mounts (AI compat
+ * projections, chain builtins + AUP, observability host-inbox, messaging's
+ * two subtrees) use the {@link SystemMountDescriptor.install} escape hatch.
+ *
+ * @see design.md §4 / §4.1
+ */
+interface SystemMountDescriptor {
+  /** Absolute host-install path, e.g. `"/dev/agent"`. Must start with `/`. */
+  path: string;
+  /**
+   * Registry key the driver looks up to construct the provider, e.g.
+   * `"agent"`, `"ocap"`. Ignored when {@link install} is supplied.
+   * Optional only when `install` is present (a composite installer owns its
+   * own construction).
+   */
+  providerKey?: string;
+  /**
+   * Provider options. Either a literal object or a function of the
+   * {@link SystemMountContext} (for options that depend on the live AFS,
+   * e.g. wiring `userSpaceRoot: "/user"` only when `/user` is mounted).
+   */
+  options?: Record<string, unknown> | ((ctx: SystemMountContext) => Record<string, unknown>);
+  /**
+   * Install order. Lower runs first. Encodes the ordering constraints from
+   * the Node setup group — `/ash` before `/dev/agent`, AI hub children
+   * before the `/dev/ai` device parent, etc. See design.md §4 for the
+   * canonical order band assignments.
+   */
+  order: number;
+  /**
+   * Declarative dependency paths this mount needs in place first. Advisory
+   * metadata for documentation/diagnostics; the driver enforces actual
+   * ordering via {@link order}.
+   */
+  dependsOn?: string[];
+  /**
+   * Predicate gating whether this descriptor installs at all. Returning
+   * `false` skips the mount (not an error). Example: `/dev/ui` only when its
+   * source `/ui` mount exists.
+   */
+  conditional?: (ctx: SystemMountContext) => boolean;
+  /** Forwarded to `afs.mount()` for the data provider (allowOverlay/hidden). */
+  mountOptions?: MountOptions;
+  /**
+   * Strategy when AUP/companion-resource projection fails. `"warn"` keeps the
+   * data mount and logs (host-scope default); `"rollback"` unmounts. Mirrors
+   * the materializer's `projectionFailure`.
+   */
+  projectionFailure?: "warn" | "rollback";
+  /**
+   * Escape hatch for composite mounts that a single
+   * `path`+`providerKey`+`options` can't express (multi-mount subtrees,
+   * legacy-alias projections, validate-then-mount, …). When present the
+   * driver calls this INSTEAD of the default materialize path and ignores
+   * {@link providerKey}. The installer receives the host AFS, the context,
+   * and the runtime registry (so it can reuse registered factories), and
+   * returns what it mounted + any warnings.
+   *
+   * The escape hatch does not break "divergence = data": `install` is still
+   * one entry in the shared list. A runtime whose registry lacks the keys
+   * the installer needs simply has the installer skip those sub-mounts.
+   *
+   * @see design.md §4.1
+   */
+  install?: (afs: AFSRoot, ctx: SystemMountContext, registry: Record<string, ProviderFactory>) => Promise<InstallOutcome>;
+}
+/**
+ * Axis B: the set of host system-mount path prefixes each blocklet's
+ * small-world session AFS should project from the global AFS. A readonly
+ * string list — pure data, no executable callbacks, no injection surface.
+ *
+ * Each runtime projects only the entries that actually exist on its host
+ * AFS (missing ones are skipped, not errored). See design.md §2.1 / §4.
+ */
+type SmallWorldProjection = readonly string[];
+//#endregion
+export { InstallOutcome, SmallWorldProjection, SystemMountContext, SystemMountDescriptor };
+//# sourceMappingURL=types.d.mts.map

package/dist/system-mounts/types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../src/system-mounts/types.ts"],"mappings":";;;;;;;;;;;;;;;UAkCiB,kBAAA;EAgHV;;;;;;EAzGL,GAAA,EAAK,OAAA;EAoDsC;;;;;EA7C3C,gBAAA;EAmEoB;EAAA,CAhEnB,GAAA;AAAA;;;;;;;UASc,cAAA;EAqFH;EAnFZ,OAAA;EAmFE;EAjFF,QAAA;AAAA;;;AA6FF;;;;;;;UAjFiB,qBAAA;;EAEf,IAAA;;;;;;;EAQA,WAAA;;;;;;EAOA,OAAA,GAAU,MAAA,sBAA4B,GAAA,EAAK,kBAAA,KAAuB,MAAA;;;;;;;EAQlE,KAAA;;;;;;EAOA,SAAA;;;;;;EAOA,WAAA,IAAe,GAAA,EAAK,kBAAA;;EAGpB,YAAA,GAAe,YAAA;;;;;;EAOf,iBAAA;;;;;;;;;;;;;;;;EAiBA,OAAA,IACE,GAAA,EAAK,OAAA,EACL,GAAA,EAAK,kBAAA,EACL,QAAA,EAAU,MAAA,SAAe,eAAA,MACtB,OAAA,CAAQ,cAAA;AAAA;;;;;;;;;KAWH,oBAAA"}