every-plugin 2.10.1 → 3.0.0-rc.3

package/src/types.ts

@@ -4,9 +4,10 @@ import type {
   InferSchemaInput,
   InferSchemaOutput,
 } from "@orpc/contract";
-import type { Router, RouterClient } from "@orpc/server";
-import type { Scope } from "effect";
+import type { ContractedRouter, RouterClient } from "@orpc/server";
+import type { Context, Scope } from "effect";
 import type { Plugin } from "./plugin";
+import type { PluginWarningInfo } from "./runtime/errors";
 
 /**
  * Registry bindings interface - populated via module augmentation
@@ -26,7 +27,7 @@ export interface RegisteredPlugins {}
 /**
  * Base type for any plugin instance.
  */
-export type AnyPlugin = Plugin<AnyContractRouter, AnySchema, AnySchema, AnySchema | undefined, any>;
+export type AnyPlugin = Plugin<AnyContractRouter, AnySchema, AnySchema, AnySchema | undefined>;
 
 /**
  * Loaded plugin constructor with binding information
@@ -100,13 +101,23 @@ export type PluginContext<T> = T extends {
  * Extract router type from plugin binding
  * Uses 'any' for context to support nested router compositions
  */
-export type PluginRouterType<T> = Router<PluginContract<T>, any>;
+export type PluginRouterType<T> = ContractedRouter<PluginContract<T>, any>;
 
 /**
  * Extract client type from plugin binding
  */
 export type PluginClientType<T> = RouterClient<PluginRouterType<T>>;
 
+/**
+ * Sibling plugin entry passed to `initialize` and `createRouter`.
+ * `client` creates a typed in-process client for the plugin's router;
+ * `router` is the raw implemented router for cross-plugin merging.
+ */
+export type PluginServicesEntry<T = any> = {
+  client: (context?: PluginContextInput<T>) => PluginClientType<T>;
+  router: PluginRouterType<T>;
+};
+
 /**
  * Extract plugin type from registered plugins by key
  * @param K - The plugin key
@@ -121,15 +132,10 @@ export type RegisteredPlugin<K extends keyof R, R = RegisteredPlugins> = R[K] ex
       secrets: infer S extends AnySchema;
       context: infer TRequestContext extends AnySchema | undefined;
     }
-    ? Plugin<C, V, S, TRequestContext, any>
+    ? Plugin<C, V, S, TRequestContext>
     : never
   : never;
 
-/**
- * Extract plugin constructor type from registry entry
- */
-export type PluginConstructor<K extends keyof R, R = RegisteredPlugins> = RegisteredPlugin<K, R>;
-
 /**
  * Extract context input type from plugin binding (for client creation)
  */
@@ -144,14 +150,6 @@ export type PluginConfigInput<T> = {
   secrets: InferSchemaInput<PluginSecrets<T>>;
 };
 
-/**
- * Extract deps context type from plugin instance (used for initialization)
- */
-export type ContextOf<T extends AnyPlugin> =
-  T extends Plugin<AnyContractRouter, AnySchema, AnySchema, AnySchema | undefined, infer TDeps>
-    ? TDeps
-    : never;
-
 /**
  * Plugin metadata for remote loading
  */
@@ -166,11 +164,6 @@ export type PluginMetadata = {
  */
 export type PluginRegistry = Record<string, PluginRegistryEntry>;
 
-/**
- * Legacy metadata-only registry (for backwards compatibility)
- */
-export type PluginMetadataRegistry = Record<string, PluginMetadata>;
-
 /**
  * Configuration for secrets injection.
  * Secrets are hydrated into plugin configs using template replacement.
@@ -205,8 +198,15 @@ export interface InitializedPlugin<T extends AnyPlugin = AnyPlugin> {
     variables: InferSchemaOutput<T["configSchema"]["variables"]>;
     secrets: InferSchemaOutput<T["configSchema"]["secrets"]>;
   };
-  readonly context: ContextOf<T>;
-  readonly scope: Scope.CloseableScope;
+  /**
+   * Built Effect context from the plugin's initialize Layer. Provided to
+   * handlers as `effect/context` — `.effect()` handlers `yield* Tag`,
+   * plain handlers use `Context.get(context["effect/context"], Tag)`.
+   */
+  readonly effectContext: Context.Context<any>;
+  readonly scope: Scope.Closeable;
+  /** Non-fatal config warnings collected during initialization (empty when none). */
+  readonly warnings: PluginWarningInfo[];
 }
 
 /**
@@ -240,18 +240,6 @@ export type UsePluginResult<K extends keyof R, R = RegisteredPlugins> =
       }
     : VerifyPluginBinding<K, R>;
 
-/**
- * Runtime options
- */
-export interface RuntimeOptions {
-  isolation?: "strict" | "shared" | "none";
-  memoryLimit?: string;
-  concurrency?: number;
-  resourceTimeout?: string;
-  debug?: boolean;
-  metrics?: boolean;
-}
-
 /**
  * Extract registry type from runtime instance or use type directly
  * This allows EveryPlugin.Infer to work with both:
@@ -295,15 +283,4 @@ export interface PluginRuntimeConfig<
 > {
   registry: R;
   secrets?: SecretsConfig;
-  options?: RuntimeOptions;
-}
-
-/**
- * Legacy plugin runtime configuration (metadata-only registry)
- * @deprecated Use PluginRuntimeConfig with module/remote entries instead
- */
-export interface LegacyPluginRuntimeConfig {
-  registry: PluginMetadataRegistry;
-  secrets?: SecretsConfig;
-  options?: RuntimeOptions;
 }

package/src/ui/manifest/construct.ts

@@ -0,0 +1,403 @@
+import type { AnyRoute } from "@tanstack/react-router";
+import { createRootRoute, createRoute, Outlet, redirect } from "@tanstack/react-router";
+import { digestOf } from "./descriptor";
+import type { PluginManifest, RouteRecord } from "./manifest-schema";
+import { MOUNT_REGISTRY, type MountDef, type MountId, resolveMountSegment } from "./mount-registry";
+import { compareNavItems, type NavDeclaration, type NavItem, type NavManifest } from "./nav";
+import { ROUTE_OPTION_KEYS, type RouteConfigModule, type RouteOptionsBundle } from "./route-config";
+
+/**
+ * Host-side route-graph construction (ADR 0008 §1): manifests + route
+ * configs in → host-built tree out. The host constructs ITS OWN Route
+ * objects from validated manifest data via public `createRoute` APIs; no
+ * foreign route object is ever mutated. Gates are attached HOST-side from
+ * the mount registry — plugins cannot ship a route that escapes its
+ * mount's gate because plugins never construct route objects.
+ *
+ * Mounts are the ONLY cross-source parenting points: a root-level
+ * pathless layout file (`_public.tsx`) declares the mount for the whole
+ * composition (exactly one declaring source per mount); every other
+ * source's routes live under the same `_mount/` directory prefix and
+ * parent onto the shared mount route. This module executes inside the
+ * core ui's module graph (production MF expose `./compose`, dev source
+ * import) so constructed routes are minted by the same react/router
+ * instance that renders them.
+ */
+
+/**
+ * TanStack's Route generics are intentionally invariant — routes built from
+ * manifest data can't satisfy them structurally. One named boundary for
+ * handing a constructed route to the tree-building APIs.
+ */
+function toAnyRoute(route: unknown): AnyRoute {
+  return route as AnyRoute;
+}
+
+export interface GateUser {
+  id: string;
+  name?: string;
+  /** Better Auth user role — "admin" gates the admin mount. */
+  role?: string;
+}
+
+export interface HostContext {
+  user?: GateUser;
+  session?: { user?: GateUser };
+}
+
+type GateFn = (args: {
+  context: HostContext;
+  location: { pathname: string; searchStr: string };
+}) => void;
+
+/**
+ * Gate redirects are absolute: gates attach to root-level mount routes, and
+ * relatives would silently shift if a mount ever moved deeper in the tree.
+ * The login surface is plugin-owned, never core-known.
+ */
+const LOGIN_TO: string = "/login";
+const HOME_TO: string = "/";
+
+/**
+ * Gate implementations by mount gate kind. Only `session` and `admin` are
+ * implemented (ADR 0008 §3); unimplemented mounts are rejected during mount
+ * declaration before any gate lookup, and gates are optional by type — a
+ * mount without an entry (or `none`) renders ungated.
+ */
+const GATES: Partial<Record<MountDef["gate"], GateFn>> = {
+  session: ({ context, location }) => {
+    const user = userOf(context);
+    if (!user) {
+      throw redirect({
+        to: LOGIN_TO,
+        search: { redirect: location.pathname + location.searchStr } as never,
+      });
+    }
+  },
+  admin: ({ context }) => {
+    const user = userOf(context);
+    if (!user) throw redirect({ to: LOGIN_TO });
+    if (user.role !== "admin") throw redirect({ to: HOME_TO });
+  },
+};
+
+const userOf = (context: HostContext | undefined): GateUser | undefined =>
+  context?.user ?? context?.session?.user;
+
+export interface ConstructPluginRef {
+  /** composition identity — plugin key; participates in the digest */
+  key: string;
+  /** deployment identity — the MF container name loadRemote targets */
+  mfName: string;
+}
+
+export interface ResolvedPlugin {
+  key: string;
+  manifest: PluginManifest;
+  routeConfig: RouteConfigModule;
+}
+
+export interface ConstructInput {
+  name: string;
+  plugins: ReadonlyArray<ConstructPluginRef>;
+  resolve: (ref: ConstructPluginRef) => Promise<ResolvedPlugin>;
+  /** core ui `__root` options — component/error/notFound + head baseline */
+  rootOptions?: RouteOptionsBundle;
+}
+
+export interface ConstructedTree {
+  rootRoute: AnyRoute;
+  routeTree: AnyRoute;
+  digest: string;
+  manifests: PluginManifest[];
+  nav: NavManifest;
+  /** constructed route count per mount id */
+  mountCounts: Record<string, number>;
+}
+
+interface MountDeclaration {
+  key: string;
+  record: RouteRecord;
+  options: RouteOptionsBundle;
+}
+
+function joinPath(a: string | undefined, b: string | undefined): string {
+  const left = a && a !== "/" ? a.replace(/\/+$/, "") : "";
+  const right = b && b !== "/" ? b.replace(/^\/+/, "") : "";
+  if (!left) return right ? `/${right}` : "/";
+  if (!right) return left;
+  return `${left}/${right}`;
+}
+
+const navOf = (options: RouteOptionsBundle): NavDeclaration | undefined => {
+  const nav = options.staticData?.nav;
+  if (nav && typeof nav === "object" && typeof (nav as NavDeclaration).label === "string") {
+    return nav as NavDeclaration;
+  }
+  return undefined;
+};
+
+/** Layout routes (mount or pathless) pass their authored options through,
+ * like every other route kind. On mount routes the registry gate composes
+ * BEFORE the declaration's own beforeLoad so a source can never escape its
+ * mount's gate (ADR 0008 §3), while the declaration's return value still
+ * flows to children as route context. */
+function layoutBeforeLoad(
+  gate: GateFn | undefined,
+  declared: RouteOptionsBundle["beforeLoad"],
+): RouteOptionsBundle["beforeLoad"] {
+  if (!gate) return declared;
+  return (args) => {
+    gate(args);
+    return declared?.(args);
+  };
+}
+
+const AUTHORED_OPTION_KEYS = ROUTE_OPTION_KEYS.filter(
+  (key) => key !== "beforeLoad" && key !== "component",
+);
+
+function authoredOptions(options: RouteOptionsBundle): Partial<RouteOptionsBundle> {
+  const authored: Partial<Record<keyof RouteOptionsBundle, unknown>> = {};
+  for (const key of AUTHORED_OPTION_KEYS) {
+    if (options[key] !== undefined) authored[key] = options[key];
+  }
+  return authored as Partial<RouteOptionsBundle>;
+}
+
+function rootAuthoredOptions(options: RouteOptionsBundle): Partial<RouteOptionsBundle> {
+  const { params: _params, ...authored } = authoredOptions(options);
+  return authored;
+}
+
+export async function constructTree(input: ConstructInput): Promise<ConstructedTree> {
+  const refs = [...input.plugins].sort((a, b) => a.key.localeCompare(b.key));
+  const resolved: ResolvedPlugin[] = [];
+  for (const ref of refs) {
+    resolved.push(await input.resolve(ref));
+  }
+
+  const optionsByPlugin = new Map<string, Map<string, RouteOptionsBundle>>();
+  for (const plugin of resolved) {
+    const optionsById = new Map<string, RouteOptionsBundle>();
+    await Promise.all(
+      plugin.manifest.routes.map(async (record) => {
+        const loader = plugin.routeConfig.routeConfigLoaders[record.id];
+        if (!loader) {
+          throw new Error(`routeConfig for "${plugin.key}" has no loader for route "${record.id}"`);
+        }
+        optionsById.set(record.id, await loader());
+      }),
+    );
+    optionsByPlugin.set(plugin.key, optionsById);
+  }
+
+  const declarations = new Map<MountId, MountDeclaration>();
+  for (const plugin of resolved) {
+    for (const record of plugin.manifest.routes) {
+      if (!record.mount) continue;
+      const mountId = record.mount as MountId;
+      const def = MOUNT_REGISTRY[mountId];
+      if (!def.implemented) {
+        throw new Error(
+          `mount "${record.mount}" is declared vocabulary but unimplemented (ADR 0008 §3) — declared by "${plugin.key}"`,
+        );
+      }
+      const existing = declarations.get(mountId);
+      if (existing) {
+        throw new Error(
+          `mount "${mountId}" declared by multiple sources: "${existing.key}" (${existing.record.file}) and "${plugin.key}" (${record.file})`,
+        );
+      }
+      declarations.set(mountId, {
+        key: plugin.key,
+        record,
+        options: optionsByPlugin.get(plugin.key)!.get(record.id)!,
+      });
+    }
+  }
+
+  const rootRoute = toAnyRoute(
+    createRootRoute({
+      ...(input.rootOptions ? rootAuthoredOptions(input.rootOptions) : {}),
+      component: input.rootOptions?.component ?? Outlet,
+      ...(input.rootOptions?.beforeLoad ? { beforeLoad: input.rootOptions.beforeLoad } : {}),
+    }),
+  );
+
+  const mountRoutes = new Map<MountId, AnyRoute>();
+  for (const mountId of Object.keys(MOUNT_REGISTRY) as MountId[]) {
+    const declaration = declarations.get(mountId);
+    if (!declaration) continue;
+    const def = MOUNT_REGISTRY[mountId]!;
+    const gate = GATES[def.gate];
+    const options = declaration.options;
+    const route = createRoute({
+      id: `__mount_${mountId}`,
+      getParentRoute: () => rootRoute,
+      ...(gate || options.beforeLoad
+        ? { beforeLoad: layoutBeforeLoad(gate, options.beforeLoad) }
+        : {}),
+      ...authoredOptions(options),
+      component: options.component ?? Outlet,
+    });
+    mountRoutes.set(mountId, toAnyRoute(route));
+  }
+
+  const mountByLayoutId = new Map<string, MountId>();
+  for (const [mountId, declaration] of declarations) {
+    mountByLayoutId.set(declaration.record.id, mountId);
+  }
+
+  const nav: NavItem[] = [];
+  const mountCounts: Record<string, number> = {};
+  const childrenByParent = new Map<AnyRoute, AnyRoute[]>();
+  /** cross-plugin path-collision guard: claimed paths per parent route */
+  const claimedPathsByParent = new Map<AnyRoute, Map<string, string>>();
+  const attach = (parent: AnyRoute, child: AnyRoute) => {
+    const list = childrenByParent.get(parent) ?? [];
+    list.push(child);
+    childrenByParent.set(parent, list);
+  };
+
+  for (const plugin of resolved) {
+    const optionsById = optionsByPlugin.get(plugin.key)!;
+    const fullPathById = new Map<string, string>();
+    const mountById = new Map<string, MountId>();
+    const byId = new Map<string, { record: RouteRecord; route: AnyRoute }>();
+
+    const parentFor = (
+      record: RouteRecord,
+    ): { route: AnyRoute; fullPath: string; mount: MountId } => {
+      if (record.parentId) {
+        const local = byId.get(record.parentId);
+        if (local) {
+          return {
+            route: local.route,
+            fullPath: fullPathById.get(record.parentId)!,
+            mount: mountById.get(record.parentId)!,
+          };
+        }
+        const mount = mountByLayoutId.get(record.parentId);
+        if (mount) return { route: mountRoutes.get(mount)!, fullPath: "", mount };
+        throw new Error(
+          `unresolvable parent "${record.parentId}" for "${record.id}" in "${plugin.key}" — mounts are the only cross-source parenting points`,
+        );
+      }
+      const firstSegment = record.id.split("/")[0] ?? "";
+      if (firstSegment.startsWith("_")) {
+        const mount = resolveMountSegment(firstSegment.slice(1));
+        if (mount && mountRoutes.has(mount))
+          return { route: mountRoutes.get(mount)!, fullPath: "", mount };
+        if (mount) {
+          throw new Error(
+            `mount "${mount}" is not declared by any source (route "${record.id}" in "${plugin.key}")`,
+          );
+        }
+        throw new Error(
+          `unknown mount "_${firstSegment.slice(1)}" (route "${record.id}" in "${plugin.key}")`,
+        );
+      }
+      throw new Error(`route "${record.id}" in "${plugin.key}" must live under a mount`);
+    };
+
+    const pending = plugin.manifest.routes.filter((record) => !record.mount);
+    let progressed = true;
+    while (pending.length > 0 && progressed) {
+      progressed = false;
+      for (let i = 0; i < pending.length; i += 1) {
+        const record = pending[i]!;
+        if (
+          record.parentId &&
+          !byId.has(record.parentId) &&
+          !mountByLayoutId.has(record.parentId)
+        ) {
+          continue;
+        }
+        pending.splice(i, 1);
+        progressed = true;
+
+        const options = optionsById.get(record.id)!;
+        const parent = parentFor(record);
+        const routePath = record.path;
+        const isLayoutRoute = record.type === "layout" || routePath === undefined;
+        if (!isLayoutRoute) {
+          const siblings = claimedPathsByParent.get(parent.route) ?? new Map<string, string>();
+          const claimant = siblings.get(routePath);
+          if (claimant) {
+            throw new Error(
+              `path collision: "${plugin.key}" route "${record.id}" declares "${routePath}" which is already claimed by "${claimant}" under the same parent`,
+            );
+          }
+          siblings.set(routePath, `${plugin.key}:${record.id}`);
+          claimedPathsByParent.set(parent.route, siblings);
+        }
+        const fullPath = joinPath(parent.fullPath, routePath);
+        let route: AnyRoute;
+        if (isLayoutRoute) {
+          route = createRoute({
+            id: `${plugin.key}__${record.id}`,
+            getParentRoute: () => parent.route,
+            ...authoredOptions(options),
+            ...(options.beforeLoad ? { beforeLoad: options.beforeLoad } : {}),
+            component: options.component ?? Outlet,
+          });
+        } else {
+          route = createRoute({
+            path: routePath,
+            getParentRoute: () => parent.route,
+            ...authoredOptions(options),
+            ...(options.beforeLoad ? { beforeLoad: options.beforeLoad } : {}),
+            component: options.component ?? Outlet,
+          });
+        }
+
+        byId.set(record.id, { record, route: toAnyRoute(route) });
+        fullPathById.set(record.id, fullPath);
+        mountById.set(record.id, parent.mount);
+        attach(parent.route, toAnyRoute(route));
+        mountCounts[parent.mount] = (mountCounts[parent.mount] ?? 0) + 1;
+
+        const navDeclaration = navOf(options);
+        if (navDeclaration && navDeclaration.hidden !== true) {
+          nav.push({
+            id: `${plugin.key}:${record.id}`,
+            label: navDeclaration.label,
+            ...(typeof navDeclaration.icon === "string" ? { icon: navDeclaration.icon } : {}),
+            ...(typeof navDeclaration.group === "string" ? { group: navDeclaration.group } : {}),
+            ...(typeof navDeclaration.order === "number" ? { order: navDeclaration.order } : {}),
+            to: navDeclaration.to ?? fullPath,
+            plugin: plugin.key,
+            mount: parent.mount,
+          });
+        }
+        break;
+      }
+    }
+    if (pending.length > 0) {
+      throw new Error(
+        `unresolvable parentage in "${plugin.key}": ${pending.map((record) => record.id).join(", ")}`,
+      );
+    }
+  }
+
+  for (const [parent, children] of childrenByParent) {
+    (parent as { addChildren: (children: AnyRoute[]) => void }).addChildren(children);
+  }
+  rootRoute.addChildren([...mountRoutes.values()] as AnyRoute[]);
+  nav.sort(compareNavItems);
+
+  const digest = await digestOf({
+    plugins: refs.map((ref) => ({ key: ref.key, mfName: ref.mfName })),
+    manifests: resolved.map((plugin) => plugin.manifest),
+  });
+
+  return {
+    rootRoute,
+    routeTree: rootRoute,
+    digest,
+    manifests: resolved.map((plugin) => plugin.manifest),
+    nav: { items: nav },
+    mountCounts,
+  };
+}

package/src/ui/manifest/contract.ts

@@ -0,0 +1,33 @@
+/**
+ * Cross-workspace composition contract: file names, MF expose names, and the
+ * core's identity — the literals every consumer of the composed tree must
+ * agree on. Browser-safe, node-safe, zero imports.
+ */
+
+/** The core ui's composition key — `bos.config.json`'s `app.ui` identity. */
+export const CORE_UI_PLUGIN_KEY = "ui";
+
+export const UI_REMOTE_ENTRY_FILENAME = "remoteEntry.js";
+export const UI_REMOTE_SERVER_ENTRY_FILENAME = "remoteEntry.server.js";
+export const MANIFEST_FILENAME = "manifest.gen.json";
+export const ROUTE_CONFIG_FILENAME = "routeConfig.gen.ts";
+
+/** Canonical MF exposes every manifest-composed ui source ships. */
+export const UI_EXPOSES = {
+  routeConfig: "./routeConfig",
+  compose: "./compose",
+  router: "./Router",
+} as const;
+
+/** Exposes a PLUGIN ui source ships (the core additionally exposes compose/Router). */
+export const PLUGIN_UI_SHARED_EXPOSES = {
+  routeConfig: UI_EXPOSES.routeConfig,
+} as const;
+
+/**
+ * MF container naming rule shared by the build (rsbuild config) and runtime
+ * config resolution — the host must register remotes under exactly the name
+ * the built container declares. Delegates to the canonical identity module
+ * (`every-plugin/identity`), which owns the derivation.
+ */
+export { containerName as sanitizeContainerName } from "../../identity";

package/src/ui/manifest/descriptor.ts

@@ -0,0 +1,96 @@
+import { MOUNT_REGISTRY_VERSION } from "./mount-registry";
+
+/**
+ * Shape-of-028 descriptor slice (ADR 0005 / plan 028) — composition-resolver
+ * surface only. Pure data: `App({...})` returns a typed object. `extends`
+ * resolves child-wins over the base app's plugins (publish-time flattening
+ * model of wayfinder ticket 08). Plan 028 will declaration-merge
+ * `KnownPlugins` from generated types; until then the interface is empty and
+ * `Plugin("bogus")` does not compile.
+ */
+
+export interface RemoteSource {
+  kind: "local" | "remote";
+  path?: string;
+  mfName?: string;
+  url?: string;
+}
+
+export interface PluginRef {
+  key: string;
+  source: RemoteSource;
+}
+
+export interface ResolvedApp {
+  name: string;
+  plugins: Record<string, PluginRef>;
+}
+
+export interface PluginRefInput {
+  name: string;
+  source: RemoteSource;
+}
+
+export interface AppInput {
+  name: string;
+  extends?: string;
+  plugins: Record<string, PluginRefInput>;
+}
+
+/** Declaration-merged from generated types by plan 028 — must stay an interface (types cannot merge). */
+// biome-ignore lint/suspicious/noEmptyInterface: declaration-merge surface
+export interface KnownPlugins {}
+
+export function App(input: AppInput): AppInput {
+  return input;
+}
+
+export function Plugin<K extends Extract<keyof KnownPlugins, string>>(
+  name: K,
+): {
+  local: (path: string) => PluginRefInput;
+  remote: (mfName: string, url: string) => PluginRefInput;
+} {
+  return {
+    local: (path) => ({ name, source: { kind: "local", path } }),
+    remote: (mfName, url) => ({ name, source: { kind: "remote", mfName, url } }),
+  };
+}
+
+/** Flatten an app against the registry of apps: `extends` inherits the base's plugins, child wins. */
+export function resolveApp(input: AppInput, apps: Record<string, AppInput>): ResolvedApp {
+  const base = input.extends ? apps[input.extends] : undefined;
+  if (input.extends && !base) throw new Error(`extends target "${input.extends}" not found`);
+  const plugins: Record<string, PluginRef> = {};
+  for (const [key, ref] of Object.entries(base?.plugins ?? {})) {
+    plugins[key] = { key, ...ref };
+  }
+  for (const [key, ref] of Object.entries(input.plugins)) {
+    plugins[key] = { key, ...ref };
+  }
+  return { name: input.name, plugins };
+}
+
+export interface CompositionDigestInput {
+  /** optional app label — deliberately NOT a tree-identity input; omit for server/client parity */
+  appName?: string;
+  plugins: Array<{ key: string; mfName: string }>;
+  manifests: Array<unknown>;
+}
+
+/**
+ * Composition digest — sha256 (WebCrypto) over everything that determines
+ * the tree: app name, plugin keys, MF names, manifests, and the imported
+ * `MOUNT_REGISTRY_VERSION`. Deployment URLs are deliberately excluded so
+ * disk and prod paths digest identically (hydration parity).
+ */
+export async function digestOf(input: CompositionDigestInput): Promise<string> {
+  const bytes = new TextEncoder().encode(
+    JSON.stringify({ ...input, mountRegistryVersion: MOUNT_REGISTRY_VERSION }),
+  );
+  const hash = await crypto.subtle.digest("SHA-256", bytes);
+  return Array.from(new Uint8Array(hash))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("")
+    .slice(0, 16);
+}