every-plugin 2.10.0 → 3.0.0-rc.0

package/src/ui/manifest/generator.ts

@@ -0,0 +1,238 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { Generator, getConfig } from "@tanstack/router-generator";
+import {
+  MANIFEST_FILENAME,
+  MANIFEST_VERSION,
+  type PluginManifest,
+  PluginManifestSchema,
+  ROUTE_CONFIG_FILENAME,
+  type RouteRecord,
+  resolveMountSegment,
+} from "./index";
+import { MOUNT_REGISTRY } from "./mount-registry";
+import { ROUTE_OPTION_KEYS } from "./route-config";
+
+/**
+ * The load-bearing generator step (ADR 0008 §2). Rides
+ * `@tanstack/router-generator`'s scan (Generator.run + getCrawlingResult)
+ * and emits, per ui source workspace:
+ *
+ *   - src/routeTree.gen.ts   via the stock generator run (plugin-local
+ *                            standalone DX — never consumed by the host)
+ *   - src/manifest.gen.json  pure data: ids, paths, nesting, mounts, files
+ *   - src/routeConfig.gen.ts generated import map of per-route option
+ *                            bundles + lifted `__root` meta
+ *
+ * Nothing hand-maintained: the only inputs are the route files. Root-level
+ * pathless layouts derive mounts via the registry; unknown mounts, routes
+ * under a missing mount layout, and duplicate sibling paths are hard errors
+ * here (cross-plugin path collisions are enforced at construction time —
+ * see `constructTree`).
+ */
+
+export interface ManifestGeneratorOptions {
+  /** ui source workspace root (ui/ or plugins/<id>/ui/) */
+  workspaceRoot: string;
+  /** composition-identity plugin key written into the manifest */
+  pluginName: string;
+  routesDirectory?: string;
+  generatedRouteTree?: string;
+  srcDir?: string;
+  /** module specifier the generated routeConfig imports its types from */
+  typeImport?: string;
+  /**
+   * When false, the stock routeTree write is redirected to a scratch path —
+   * for builds where TanStackRouterRspack owns src/routeTree.gen.ts (its
+   * autoCodeSplitting options differ); only manifest + routeConfig persist.
+   */
+  emitRouteTree?: boolean;
+}
+
+interface ScanNode {
+  routePath?: string;
+  cleanedPath?: string;
+  filePath?: string;
+  parent?: ScanNode | undefined;
+  _fsRouteType?: string;
+}
+
+const idOf = (node: { routePath?: string }): string => (node.routePath ?? "").replace(/^\//, "");
+
+function importPathOf(file: string): string {
+  return `./routes/${file.replace(/\.tsx$/, "").replace(/\.ts$/, "")}`;
+}
+
+export async function generateUiManifest(
+  options: ManifestGeneratorOptions,
+): Promise<PluginManifest> {
+  const {
+    workspaceRoot,
+    pluginName,
+    routesDirectory = "./src/routes",
+    generatedRouteTree = "./src/routeTree.gen.ts",
+    srcDir = "./src",
+    typeImport = "everything-dev/ui/manifest",
+    emitRouteTree = true,
+  } = options;
+
+  const routeTreeTarget = emitRouteTree
+    ? generatedRouteTree
+    : "./node_modules/.cache/manifest-compose/routeTree.gen.ts";
+
+  const generator = new Generator({
+    config: getConfig(
+      {
+        target: "react",
+        routesDirectory,
+        generatedRouteTree: routeTreeTarget,
+        routeFileIgnorePrefix: "-",
+        routeFileIgnorePattern: "\\.(test|spec)\\.(ts|tsx)$",
+        disableLogging: true,
+      },
+      workspaceRoot,
+    ),
+    root: workspaceRoot,
+  });
+  await generator.run();
+  const crawling = await generator.getCrawlingResult();
+  if (!crawling) throw new Error(`scan produced no result for ${pluginName}`);
+
+  const { rootRouteNode, routeFileResult } = crawling;
+  if (!rootRouteNode) throw new Error(`no __root found for ${pluginName}`);
+
+  const routes: RouteRecord[] = [];
+  const errors: string[] = [];
+
+  for (const node of routeFileResult as ScanNode[]) {
+    const isRootLevel = node.parent === undefined || node.parent === rootRouteNode;
+
+    if (node._fsRouteType === "__root") {
+      continue;
+    }
+
+    if (
+      isRootLevel &&
+      (node._fsRouteType === "pathless_layout" || node._fsRouteType === "layout")
+    ) {
+      const id = idOf(node);
+      const segment = id.split("/").at(-1) ?? "";
+      if (!segment.startsWith("_")) continue;
+      const mount = resolveMountSegment(segment.slice(1));
+      if (!mount) {
+        errors.push(
+          `unknown mount "_${segment.slice(1)}" (${node.filePath}); known: ${Object.keys(MOUNT_REGISTRY).join(", ")}`,
+        );
+        continue;
+      }
+      routes.push({ id, type: "layout", mount, file: node.filePath });
+      continue;
+    }
+
+    const isIndex = node._fsRouteType === "static" && node.cleanedPath === "/";
+    routes.push({
+      id: idOf(node),
+      type: isIndex
+        ? "index"
+        : node._fsRouteType === "pathless_layout" || node._fsRouteType === "layout"
+          ? "layout"
+          : "route",
+      path: isIndex
+        ? "/"
+        : node.cleanedPath === "/" || node.cleanedPath === ""
+          ? undefined
+          : node.cleanedPath,
+      file: node.filePath,
+      parentId: node.parent && node.parent !== rootRouteNode ? idOf(node.parent) : undefined,
+    });
+  }
+
+  for (const record of routes) {
+    if (record.type === "layout" && record.mount) continue;
+    if (record.parentId) continue;
+    const firstSegment = record.id.split("/")[0] ?? "";
+    if (firstSegment.startsWith("_")) {
+      const mount = resolveMountSegment(firstSegment.slice(1));
+      if (!mount) {
+        errors.push(
+          `unknown mount "_${firstSegment.slice(1)}" (${record.file}); known: ${Object.keys(MOUNT_REGISTRY).join(", ")}`,
+        );
+      }
+    } else {
+      errors.push(
+        `route "${record.id}" (${record.file}) must live under a mount — root-level pathed routes have no gate`,
+      );
+    }
+  }
+
+  const siblingPathClaims = new Map<string, string>();
+  for (const record of routes) {
+    if (record.type === "layout" || record.path === undefined) continue;
+    const claimKey = `${record.parentId ?? ""}::${record.path}`;
+    const claimant = siblingPathClaims.get(claimKey);
+    if (claimant) {
+      errors.push(
+        `duplicate path "${record.path}" under "${record.parentId ?? "mount root"}": "${claimant}" and "${record.id}" (${record.file})`,
+      );
+      continue;
+    }
+    siblingPathClaims.set(claimKey, record.id);
+  }
+
+  if (errors.length > 0) {
+    throw new Error(`manifest generation failed for ${pluginName}:\n  ${errors.join("\n  ")}`);
+  }
+
+  const manifest: PluginManifest = PluginManifestSchema.parse({
+    name: pluginName,
+    manifestVersion: MANIFEST_VERSION,
+    routes,
+  });
+
+  const resolvedSrc = path.resolve(workspaceRoot, srcDir);
+  await mkdir(resolvedSrc, { recursive: true });
+  await writeIfChanged(
+    path.join(resolvedSrc, MANIFEST_FILENAME),
+    `${JSON.stringify(manifest, null, 2)}\n`,
+  );
+
+  const loaderLines = routes
+    .filter((r) => r.file)
+    .map(
+      (r) =>
+        `  ${JSON.stringify(r.id)}: () => import(${JSON.stringify(importPathOf(r.file!))}).then((m) => pick(m.Route.options)),`,
+    );
+  const rootImport = `import { Route as __rootRoute } from ${JSON.stringify(importPathOf(rootRouteNode.filePath ?? "__root"))};`;
+
+  const routeConfigSource = `// Generated by manifest-gen. DO NOT EDIT.
+// Inputs: src/routes/** only.
+import type { RouteConfigModule, RouteOptionsBundle } from ${JSON.stringify(typeImport)};
+
+const pick = (o: any): RouteOptionsBundle => ({
+${ROUTE_OPTION_KEYS.map((key) => `  ${key}: o?.${key},`).join("\n")}
+});
+
+${rootImport}
+
+export const routeConfigLoaders: RouteConfigModule["routeConfigLoaders"] = {
+${loaderLines.join("\n")}
+};
+
+export const rootMeta = pick(__rootRoute.options);
+`;
+
+  await writeIfChanged(path.join(resolvedSrc, ROUTE_CONFIG_FILENAME), routeConfigSource);
+
+  return manifest;
+}
+
+/**
+ * Identical content is never re-written: the dev watcher is timestamp-based,
+ * so an unconditional write re-triggers compilation — which runs this
+ * generator again — an infinite regen loop.
+ */
+async function writeIfChanged(file: string, contents: string): Promise<void> {
+  const existing = await readFile(file, "utf8").catch(() => undefined);
+  if (existing === contents) return;
+  await writeFile(file, contents);
+}

package/src/ui/manifest/index.ts

@@ -0,0 +1,55 @@
+/**
+ * Browser-safe composition surface — everything here loads in the web
+ * bundle (hydrate) and the host server. The GENERATOR is deliberately NOT
+ * re-exported here: it rides @tanstack/router-generator (node fs + babel)
+ * and is consumed only by build tooling via `./ui/manifest-generator`.
+ */
+
+export {
+  type ConstructedTree,
+  type ConstructInput,
+  type ConstructPluginRef,
+  constructTree,
+  type GateUser,
+  type HostContext,
+  type ResolvedPlugin,
+} from "./construct";
+export * from "./contract";
+export {
+  App,
+  type AppInput,
+  type CompositionDigestInput,
+  digestOf,
+  type KnownPlugins,
+  Plugin,
+  type PluginRef,
+  type PluginRefInput,
+  type RemoteSource,
+  type ResolvedApp,
+  resolveApp,
+} from "./descriptor";
+export {
+  type ComposePayload,
+  ComposePayloadSchema,
+  type ComposeRemote,
+  MANIFEST_VERSION,
+  ManifestSchema,
+  type PluginManifest,
+  PluginManifestSchema,
+  parsePluginManifest,
+  type RouteRecord,
+  RouteRecordSchema,
+  SUPPORTED_MANIFEST_VERSION,
+} from "./manifest-schema";
+export {
+  MOUNT_ALIASES,
+  MOUNT_REGISTRY,
+  MOUNT_REGISTRY_VERSION,
+  MOUNTS,
+  type MountDef,
+  type MountId,
+  resolveMountSegment,
+} from "./mount-registry";
+export type { NavDeclaration, NavItem, NavManifest } from "./nav";
+export { compareNavItems } from "./nav";
+export type { RouteConfigModule, RouteConfigRef, RouteOptionsBundle } from "./route-config";

package/src/ui/manifest/manifest-schema.ts

@@ -0,0 +1,107 @@
+import { z } from "zod";
+import { MOUNTS } from "./mount-registry";
+
+/**
+ * manifest.gen.json — pure data emitted by the generator from route files
+ * only (ADR 0008 §2). Nothing here is hand-maintained; this schema is the
+ * composition contract and the audit/marketplace surface. The host refuses
+ * unknown `manifestVersion` majors.
+ */
+
+/**
+ * The manifest contract major this code speaks. Emitted by the generator and
+ * enforced at every load (the host parses through `parsePluginManifest`; the
+ * client parse of the compose payload checks it — a skewed major degrades to
+ * the core-only tree instead of silently mis-constructing).
+ */
+export const MANIFEST_VERSION = 2;
+export const SUPPORTED_MANIFEST_VERSION = MANIFEST_VERSION;
+
+export const RouteRecordSchema = z.object({
+  /** Full route id, root-relative, no leading slash. e.g. "_public/login" */
+  id: z.string(),
+  /** Node kind — the @tanstack/virtual-file-routes vocabulary. */
+  type: z.enum(["route", "layout", "index"]),
+  /** URL path relative to the parent; absent for pathless layouts. */
+  path: z.string().optional(),
+  /** id of the parent record within the same plugin; absent = mount-level. */
+  parentId: z.string().optional(),
+  /** Set on ROOT-level pathless layouts: the mount this subtree declares. */
+  mount: z.enum(MOUNTS as [string, ...string[]]).optional(),
+  /** Route file relative to the routes directory (options source). */
+  file: z.string().optional(),
+});
+
+export const PluginManifestSchema = z.object({
+  /** Plugin key — derived from the workspace/config key by the emitter. */
+  name: z.string(),
+  /** Contract version — enforced by `parsePluginManifest` / the payload check. */
+  manifestVersion: z.number().int(),
+  /** Lifted from the plugin's `__root` route options, if any. */
+  rootMeta: z
+    .object({
+      hasHead: z.boolean().optional(),
+      hasStaticData: z.boolean().optional(),
+    })
+    .optional(),
+  routes: z.array(RouteRecordSchema),
+});
+
+/**
+ * The load-time contract check — one diagnostic for a manifest from a
+ * different framework major. Every manifest load goes through this.
+ */
+export function parsePluginManifest(data: unknown): PluginManifest {
+  const parsed = PluginManifestSchema.parse(data);
+  if (parsed.manifestVersion !== SUPPORTED_MANIFEST_VERSION) {
+    throw new Error(manifestVersionIssue(parsed.name, parsed.manifestVersion));
+  }
+  return parsed;
+}
+
+const manifestVersionIssue = (name: string, found: number): string =>
+  `unsupported manifest version ${found} in "${name}" — this build speaks ${SUPPORTED_MANIFEST_VERSION}; regenerate manifest.gen.json with the installed framework`;
+
+export const ManifestSchema = z.object({
+  manifestVersion: z.number().int(),
+  plugins: z.array(PluginManifestSchema),
+});
+
+export type RouteRecord = z.infer<typeof RouteRecordSchema>;
+export type PluginManifest = z.infer<typeof PluginManifestSchema>;
+export type Manifest = z.infer<typeof ManifestSchema>;
+
+/**
+ * The client compose payload — the runtime-config `ui.compose` block the
+ * server embeds and the client reconstructs the tree from. Single home:
+ * everything-dev's client-config schema, the hydrate client, and the host's
+ * ui-compose all derive from this schema.
+ */
+export const ComposeRemoteSchema = z.object({
+  key: z.string(),
+  name: z.string(),
+  entry: z.string(),
+  /** the remote's (hashed) browser-manifest URL — preferred over deriving
+   * one from `entry` by stripping the legacy fixed entry name */
+  manifestUrl: z.string().optional(),
+});
+
+export const ComposePayloadSchema = z
+  .object({
+    digest: z.string(),
+    remotes: z.array(ComposeRemoteSchema),
+    manifests: z.array(PluginManifestSchema),
+  })
+  .superRefine((payload, ctx) => {
+    for (const manifest of payload.manifests) {
+      if (manifest.manifestVersion !== SUPPORTED_MANIFEST_VERSION) {
+        ctx.addIssue({
+          code: "custom",
+          message: manifestVersionIssue(manifest.name, manifest.manifestVersion),
+        });
+      }
+    }
+  });
+
+export type ComposeRemote = z.infer<typeof ComposeRemoteSchema>;
+export type ComposePayload = z.infer<typeof ComposePayloadSchema>;

package/src/ui/manifest/mount-registry.ts

@@ -0,0 +1,50 @@
+/**
+ * Mount registry v2 — gates only, shape-free (ADR 0008 §3).
+ *
+ * A mount is a gate + a host-owned pathless layout position. It carries no
+ * product semantics (no "dashboard", no shell, no chrome) — plugins bring
+ * their own layouts and route freely inside their subtree. A mount is
+ * declared by a ROOT-level pathless layout file whose `_`-prefixed segment
+ * names the mount (`_public.tsx` → `public`); the generator derives it and
+ * validates it against this registry; gates are attached HOST-side at
+ * construction, so a plugin cannot ship a route that escapes its mount's
+ * gate (plugins never construct route objects).
+ *
+ * `org`/`team` are declared vocabulary (parameterized membership gates) but
+ * unimplemented — construction rejects them until they land.
+ */
+
+export interface MountDef {
+  label: string;
+  gate: "none" | "session" | "admin" | "organization" | "team";
+  parameterized?: boolean;
+  implemented: boolean;
+}
+
+export const MOUNT_REGISTRY = {
+  public: { label: "public", gate: "none", implemented: true },
+  authenticated: { label: "authenticated", gate: "session", implemented: true },
+  admin: { label: "admin", gate: "admin", implemented: true },
+  org: { label: "org", gate: "organization", parameterized: true, implemented: false },
+  team: { label: "team", gate: "team", parameterized: true, implemented: false },
+} satisfies Record<string, MountDef>;
+
+export type MountId = Extract<keyof typeof MOUNT_REGISTRY, string>;
+
+export const MOUNTS = Object.keys(MOUNT_REGISTRY) as MountId[];
+
+/** Bump when the registry shape changes — invalidates all compose digests. */
+export const MOUNT_REGISTRY_VERSION = 5;
+
+/** Migration aliases: legacy `_`-segment names → canonical mounts. */
+export const MOUNT_ALIASES: Record<string, MountId> = {
+  auth: "authenticated",
+  authed: "authenticated",
+  dashboard: "authenticated",
+  organization: "org",
+};
+
+export function resolveMountSegment(segment: string): MountId | undefined {
+  if (segment in MOUNT_REGISTRY) return segment as MountId;
+  return MOUNT_ALIASES[segment];
+}

package/src/ui/manifest/nav.ts

@@ -0,0 +1,43 @@
+/**
+ * Nav manifest derived at construction from composed routes' `staticData.nav`
+ * declarations (ADR 0008). Shape-compatible with the sidebar consumption
+ * surface (`ui/src/components/layout/nav-items.ts`).
+ */
+
+export interface NavItem {
+  /** unique item id: `${pluginKey}:${routeId}` */
+  id: string;
+  label: string;
+  icon?: string;
+  group?: string;
+  order?: number;
+  /** absolute URL path — literal `$param` segments preserved */
+  to: string;
+  plugin: string;
+  mount: string;
+}
+
+export interface NavManifest {
+  items: NavItem[];
+}
+
+export interface NavDeclaration {
+  label: string;
+  icon?: string;
+  group?: string;
+  order?: number;
+  to?: string;
+  /** set true to expose the route as a page but omit it from the sidebar */
+  hidden?: boolean;
+}
+
+export function compareNavItems(a: NavItem, b: NavItem): number {
+  const groupOrder = (a.group ?? "").localeCompare(b.group ?? "");
+  if (groupOrder !== 0) return groupOrder;
+  if (a.order !== undefined || b.order !== undefined) {
+    return (a.order ?? Number.MAX_SAFE_INTEGER) - (b.order ?? Number.MAX_SAFE_INTEGER);
+  }
+  const labelOrder = a.label.localeCompare(b.label);
+  if (labelOrder !== 0) return labelOrder;
+  return a.id.localeCompare(b.id);
+}

package/src/ui/manifest/route-config.ts

@@ -0,0 +1,82 @@
+/**
+ * routeConfig.gen.ts contract — the generated import map (ADR 0008 §2).
+ *
+ * The generator emits one module per ui source exposing a loader per route
+ * record: a dynamic import of that route's file, destructured to the option
+ * bundle construction needs. Options and component live in the same route
+ * file (standard authoring), so both arrive via the same per-route chunk.
+ * The host consumes this module — source-resolved from disk in dev,
+ * MF-exposed (`./routeConfig`) in production.
+ */
+
+import type { ReactNode } from "react";
+
+export interface RouteHeadData {
+  meta?: Array<Record<string, unknown>>;
+  links?: Array<Record<string, unknown>>;
+  scripts?: Array<Record<string, unknown>>;
+}
+
+export interface RouteOptionsBundle {
+  validateSearch?: any;
+  search?: { middlewares?: Array<(...args: Array<any>) => any> };
+  params?: any;
+  loaderDeps?: (...args: Array<any>) => any;
+  context?: (...args: Array<any>) => any;
+  ssr?: any;
+  staleTime?: number;
+  gcTime?: number;
+  preloadStaleTime?: number;
+  pendingMs?: number;
+  pendingMinMs?: number;
+  shouldReload?: boolean | ((...args: Array<any>) => any);
+  loader?: (...args: Array<any>) => any;
+  beforeLoad?: (...args: Array<any>) => any;
+  head?: (...args: Array<any>) => RouteHeadData;
+  staticData?: Record<string, unknown>;
+  component?: (props: any) => ReactNode;
+  errorComponent?: (props: any) => ReactNode;
+  pendingComponent?: (props: any) => ReactNode;
+  notFoundComponent?: (props: any) => ReactNode;
+}
+
+export type RouteConfigRef = () => Promise<RouteOptionsBundle>;
+
+export type RouteConfigModule = {
+  routeConfigLoaders: Record<string, RouteConfigRef>;
+  /** Lifted `__root` meta, when the source declares it. */
+  rootMeta?: RouteOptionsBundle;
+};
+
+/**
+ * Every authored route option carried from a route file onto its constructed
+ * route. The generated `pick` and `constructTree` both read this list, and
+ * the type check below fails when `RouteOptionsBundle` gains a key that is
+ * not listed here.
+ */
+export const ROUTE_OPTION_KEYS = [
+  "validateSearch",
+  "search",
+  "params",
+  "loaderDeps",
+  "context",
+  "ssr",
+  "staleTime",
+  "gcTime",
+  "preloadStaleTime",
+  "pendingMs",
+  "pendingMinMs",
+  "shouldReload",
+  "loader",
+  "beforeLoad",
+  "head",
+  "staticData",
+  "component",
+  "errorComponent",
+  "pendingComponent",
+  "notFoundComponent",
+] as const satisfies ReadonlyArray<keyof RouteOptionsBundle>;
+
+type UnlistedRouteOptionKey = Exclude<keyof RouteOptionsBundle, (typeof ROUTE_OPTION_KEYS)[number]>;
+const everyRouteOptionKeyListed: [UnlistedRouteOptionKey] extends [never] ? true : never = true;
+void everyRouteOptionKeyListed;

package/src/version-manifest.ts

@@ -0,0 +1,88 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+
+/**
+ * WorkspaceVersionManifest — the immutable per-deploy document at
+ * `bundles/<account>/<gateway>/<workspace>/versions/<version>.json`
+ * (ADR 0020, as amended; atomic-deploys MAP decision 1). The published
+ * config's slot pins this document via its `pin` (`manifest` + the
+ * manifest's own SRI); every artifact coordinate lives here, so the config
+ * stops growing with artifact kinds and old versions stay fully servable.
+ */
+
+const SRI = z.string().regex(/^sha384-[A-Za-z0-9+/=]+$/);
+
+export const WorkspaceVersionManifestSchema = z.object({
+  version: z.string().regex(/^[0-9a-f]{16}$/),
+  builtAt: z.string().optional(),
+  gitSha: z.string().optional(),
+  entry: z.string().min(1),
+  entryIntegrity: SRI,
+  ssr: z
+    .object({
+      entry: z.string().min(1),
+      integrity: SRI,
+    })
+    .optional(),
+  browserManifest: z
+    .object({
+      file: z.string().min(1),
+      integrity: SRI,
+    })
+    .optional(),
+  /** extra assets (css, icons) — logical name → served-object SRI */
+  assets: z.record(z.string(), SRI).optional(),
+  /** shared-dependency versions this build was built against */
+  shared: z.record(z.string(), z.string()).optional(),
+  /**
+   * Full per-file digest map of the dist (object path → served-object SRI).
+   * Written by `every-plugin`-based deploys so the next deploy can diff against
+   * it and skip re-uploading unchanged files; readers that predate the field
+   * ignore it (zod strips unknown keys). Participates in the version hash.
+   */
+  files: z.record(z.string(), SRI).optional(),
+});
+export type WorkspaceVersionManifest = z.infer<typeof WorkspaceVersionManifestSchema>;
+
+export interface VersionManifestInput {
+  /** Omit: a per-build timestamp makes the same version id map to different
+   * manifest bytes per machine, breaking the pin's SRI against the image's
+   * staged copy and the CDN's immutability for republished versions. */
+  builtAt?: string;
+  gitSha?: string;
+  entry: string;
+  entryIntegrity: string;
+  ssr?: { entry: string; integrity: string };
+  browserManifest?: { file: string; integrity: string };
+  assets?: Record<string, string>;
+  shared?: Record<string, string>;
+  files?: Record<string, string>;
+}
+
+/**
+ * Compose the manifest with its `version` derived from the canonical content
+ * of the artifact coordinates alone (key-sorted, `builtAt` excluded) —
+ * identical bytes → identical version id regardless of when they were built,
+ * so republishing unchanged content is a pointer no-op. Any changed
+ * coordinate → a new version (and a new file).
+ */
+export function composeVersionManifest(input: VersionManifestInput): WorkspaceVersionManifest {
+  const { builtAt, ...hashedInputs } = input;
+  const version = createHash("sha256")
+    .update(stableStringify(hashedInputs))
+    .digest("hex")
+    .slice(0, 16);
+  return WorkspaceVersionManifestSchema.parse({ ...input, version });
+}
+
+function stableStringify(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.entries(value)
+      .filter(([, v]) => v !== undefined)
+      .map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`)
+      .sort()
+      .join(",")}}`;
+  }
+  return JSON.stringify(value) ?? "null";
+}