@bleedingdev/modern-js-ultramodern-create 3.9.0-ultramodern.2 → 3.9.0-ultramodern.21

package/templates/workspace-scripts/{proof-workerd-ssr.mts → proof-workerd-ssr.mjs}

@@ -3,14 +3,12 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import http from "node:http";
 import path from "node:path";
-import { Log, LogLevel, Miniflare } from "miniflare";
+import { parseEnv } from "node:util";
+import { convertV4MiniflareOptions, Log, LogLevel, Miniflare } from "miniflare";
 
-const workspaceRoot = process.cwd();
-const defaultProofRoutes = ["/en"];
-const reportPath = path.join(
-  workspaceRoot,
-  ".codex/reports/cloudflare-workerd-ssr/composition-proof.json",
-);
+const reportRelativePath = ".codex/reports/cloudflare-workerd-ssr/composition-proof.json";
+// Mirrors the public website quality gate default for server-rendered HTML.
+const defaultSsrHtmlMaxBytes = 250_000;
 
 const assert = (condition, message) => {
   if (!condition) {
@@ -120,69 +118,164 @@ const bindExecutedModule = (app, envelope, module) => {
   };
 };
 
-const compactConfig = readJson(path.join(workspaceRoot, ".modernjs/ultramodern.json"));
-const apps = (compactConfig.topology?.apps ?? []).map((rawApp) => {
-  const kind = rawApp.kind === "vertical" ? "vertical" : "shell";
-  const appPath =
-    typeof rawApp.path === "string"
-      ? normalizePath(rawApp.path)
-      : kind === "shell"
-        ? "apps/shell-super-app"
-        : `verticals/${rawApp.id}`;
-  const moduleFederation =
-    rawApp.moduleFederation && typeof rawApp.moduleFederation === "object"
-      ? rawApp.moduleFederation
-      : {};
-  const configuredProofRoutes = rawApp.deploy?.cloudflare?.distributedSsrProofRoutes;
-  const proofRoutes = Array.isArray(configuredProofRoutes)
-    ? [...new Set(configuredProofRoutes.filter(
-        (route) => typeof route === "string" && route.startsWith("/"),
-      ))]
-    : [];
-  const outputRoot = path.join(workspaceRoot, appPath, ".output");
-  const wranglerPath = path.join(outputRoot, "wrangler.json");
+const normalizeRoutes = (routes) => [
+  ...new Set(
+    (Array.isArray(routes) ? routes : []).filter(
+      (route) => typeof route === "string" && route.startsWith("/"),
+    ),
+  ),
+];
+
+// The generator's distributed SSR contract: every expose except the page
+// route is a fragment a host can server-render (see distributedSsrExposes).
+const declaresDistributedSsrExpose = (rawApp) =>
+  Array.isArray(rawApp?.moduleFederation?.exposes) &&
+  rawApp.moduleFederation.exposes.some(
+    (expose) => typeof expose === "string" && expose !== "./Route",
+  );
+
+/**
+ * Derive what the proof must execute from topology/reference-topology.json.
+ *
+ * - `ssrRoutes`: every route the app itself must server-render on its own
+ *   Worker (`cloudflare.routes.ssr` plus `cloudflare.distributedSsrProofRoutes`).
+ * - `serverRenderedRoutes`: shell routes that must compose distributed SSR
+ *   boundaries. `cloudflare.distributedSsrProofRoutes` declares them; without
+ *   it the shell's `cloudflare.routes.ssr` is the composition route. An empty
+ *   array declares a shell whose MicroVerticals load on the client only.
+ * - `serverRenderedRemoteIds`: shell `verticalRefs` whose topology declares a
+ *   distributed SSR expose, i.e. the boundaries the shell must server-render.
+ */
+export const planWorkerdSsrProof = (topology) => {
   assert(
-    fs.existsSync(wranglerPath),
-    `${rawApp.id} Cloudflare output is missing; run pnpm cloudflare:build first`,
-  );
-  const wrangler = readJson(wranglerPath);
-  const executedEnvelope =
-    kind === "vertical"
-      ? readExecutionEnvelope(
-          String(rawApp.id),
-          outputRoot,
-          rawApp.deliveryUnit?.unitId,
-        )
-      : {};
+    topology?.schemaVersion === 1 && topology.shell && Array.isArray(topology.verticals),
+    "Invalid topology/reference-topology.json",
+  );
+  const rawApps = [topology.shell, ...topology.verticals, ...(topology.shells ?? [])];
+  const rawAppsById = new Map(rawApps.map((rawApp) => [String(rawApp.id), rawApp]));
+  const plans = rawApps.map((rawApp) => {
+    const id = String(rawApp.id);
+    const kind = rawApp.kind === "vertical" ? "vertical" : "shell";
+    const cloudflare = rawApp.cloudflare ?? {};
+    const declaredServerRenderedRoutes = cloudflare.distributedSsrProofRoutes;
+    const rawVerticalRefs = rawApp.verticalRefs ?? rawApp.moduleFederation?.verticalRefs;
+    const verticalRefs = Array.isArray(rawVerticalRefs)
+      ? rawVerticalRefs.filter((ref) => typeof ref === "string")
+      : [];
+    for (const ref of verticalRefs) {
+      assert(rawAppsById.has(ref), `${id} references missing MicroVertical ${ref}`);
+    }
+    const serverRenderedRemoteIds =
+      kind === "shell"
+        ? verticalRefs.filter((ref) => declaresDistributedSsrExpose(rawAppsById.get(ref)))
+        : [];
+    assert(
+      declaredServerRenderedRoutes === undefined ||
+        (Array.isArray(declaredServerRenderedRoutes) &&
+          normalizeRoutes(declaredServerRenderedRoutes).length ===
+            declaredServerRenderedRoutes.length),
+      `${id} cloudflare.distributedSsrProofRoutes must list unique absolute routes`,
+    );
+    const serverRenderedRoutes =
+      kind !== "shell"
+        ? []
+        : Array.isArray(declaredServerRenderedRoutes)
+          ? normalizeRoutes(declaredServerRenderedRoutes)
+          : normalizeRoutes([cloudflare.routes?.ssr]);
+    const ssrRoutes = normalizeRoutes([
+      ...(Array.isArray(declaredServerRenderedRoutes) ? declaredServerRenderedRoutes : []),
+      cloudflare.routes?.ssr,
+    ]);
+    const apiOnly = rawApp.surfaceProfile === "api-only";
+    assert(
+      apiOnly || normalizeRoutes([cloudflare.routes?.ssr]).length === 1,
+      `${id} declares no cloudflare.routes.ssr to prove on its own Worker`,
+    );
+    return {
+      apiOnly,
+      id,
+      kind,
+      serverRenderedRemoteIds:
+        serverRenderedRoutes.length > 0 ? serverRenderedRemoteIds : [],
+      serverRenderedRoutes,
+      ssrRoutes,
+      verticalRefs,
+    };
+  });
+  assert(
+    plans.some((plan) => plan.kind === "shell"),
+    "Workerd SSR proof requires at least one shell",
+  );
+  assert(
+    plans.some((plan) => plan.kind === "vertical"),
+    "Workerd SSR proof requires at least one MicroVertical or headless API",
+  );
+  return { plans, rawApps };
+};
 
-  return {
-    id: String(rawApp.id),
-    kind,
-    path: appPath,
-    mfName: typeof moduleFederation.name === "string" ? moduleFederation.name : String(rawApp.id),
-    verticalRefs: Array.isArray(moduleFederation.verticalRefs)
-      ? moduleFederation.verticalRefs.filter((ref) => typeof ref === "string")
-      : [],
-    apiPrefix:
-      typeof rawApp.api?.prefix === "string"
-        ? rawApp.api.prefix.replace(/\/+$/u, "")
-        : undefined,
-    proofRoutes: proofRoutes.length > 0 ? proofRoutes : defaultProofRoutes,
-    jsonSmokeChecks: Array.isArray(rawApp.deploy?.cloudflare?.jsonSmokeChecks)
-      ? rawApp.deploy.cloudflare.jsonSmokeChecks
-      : [],
-    ...executedEnvelope,
-    outputRoot,
-    port: Number(rawApp.port),
-    wrangler,
-  };
-});
+const readDevVars = (outputRoot) => {
+  // Wrangler's local-secret convention: `.dev.vars` beside the executed config.
+  const devVarsPath = path.join(outputRoot, ".dev.vars");
+  return fs.existsSync(devVarsPath) ? parseEnv(fs.readFileSync(devVarsPath, "utf8")) : {};
+};
 
-const shells = apps.filter((app) => app.kind === "shell");
-assert(shells.length > 0, "Workerd SSR proof requires at least one shell");
-if (process.env.ULTRAMODERN_KEEP_WORKERD === "1") {
-  assert(shells.length === 1, "Browser workerd proof requires exactly one shell");
-}
+const loadApps = (workspaceRoot, topology, overlay) => {
+  const { plans, rawApps } = planWorkerdSsrProof(topology);
+  return rawApps.map((rawApp, index) => {
+    const plan = plans[index];
+    const hasApiSurface = plan.kind === "vertical" && rawApp.surfaceProfile !== "ui-only";
+    const appPath = rawApp.path;
+    assert(typeof appPath === "string" && appPath.length > 0, `${plan.id} topology path is missing`);
+    const outputRoot = path.join(workspaceRoot, appPath, ".output");
+    const wranglerPath = path.join(outputRoot, "wrangler.json");
+    assert(
+      fs.existsSync(wranglerPath),
+      `${plan.id} Cloudflare output is missing; run pnpm cloudflare:build first`,
+    );
+    const wrangler = readJson(wranglerPath);
+    const executedEnvelope = hasApiSurface
+      ? readExecutionEnvelope(plan.id, outputRoot, rawApp.deliveryUnit?.unitId)
+      : {};
+    const domain = rawApp.domain ?? rawApp.id;
+    const portEnv = rawApp.portEnv ??
+      (plan.kind === "vertical"
+        ? `VERTICAL_${String(domain).replace(/[^a-zA-Z0-9]/gu, "_").toUpperCase()}_PORT`
+        : undefined);
+    assert(typeof portEnv === "string" && portEnv.length > 0, `${plan.id} has no declared port environment name`);
+    const configuredPort = process.env[portEnv];
+    const port = configuredPort === undefined
+      ? Number(overlay.ports?.[plan.id])
+      : Number(configuredPort);
+    assert(
+      Number.isInteger(port) && port > 0 && port <= 65535,
+      `${plan.id} has an invalid local proof port from ${portEnv}`,
+    );
+
+    return {
+      ...plan,
+      hasApiSurface,
+      path: appPath,
+      apiPrefix:
+        typeof rawApp.api?.bff?.prefix === "string"
+          ? rawApp.api.bff.prefix.replace(/\/+$/u, "")
+          : undefined,
+      apiProtocol: rawApp.api?.protocol ?? "rest",
+      rpcRoute: rawApp.api?.protocol === "rpc" ? rawApp.cloudflare?.routes?.rpc : undefined,
+      ssrHtmlMaxBytes: Number(
+        rawApp.cloudflare?.qualityGates?.budgets?.ssrHtmlMaxBytes ??
+          defaultSsrHtmlMaxBytes,
+      ),
+      jsonSmokeChecks: Array.isArray(rawApp.cloudflare?.jsonSmokeChecks)
+        ? rawApp.cloudflare.jsonSmokeChecks
+        : [],
+      ...executedEnvelope,
+      devVars: readDevVars(outputRoot),
+      outputRoot,
+      port,
+      wrangler,
+    };
+  });
+};
 
 const workerName = (app) => {
   assert(
@@ -192,7 +285,7 @@ const workerName = (app) => {
   return app.wrangler.name;
 };
 
-const createWorkerOptions = (app, extra = {}) => {
+const createWorkerOptions = (app, workspaceRoot, extra = {}) => {
   const main = typeof app.wrangler.main === "string" ? app.wrangler.main : "server/index.mjs";
   const assets =
     app.wrangler.assets && typeof app.wrangler.assets === "object" ? app.wrangler.assets : {};
@@ -222,7 +315,7 @@ const createWorkerOptions = (app, extra = {}) => {
   const apiBackend = app.envelope?.surfaces?.apiBackend;
   const ssr = app.envelope?.surfaces?.ssr;
   assert(
-    app.kind !== "vertical" ||
+    !app.hasApiSurface ||
       (Array.isArray(apiBackend) &&
         apiBackend.length > 0 &&
         apiBackend.every((logicalPath) =>
@@ -231,13 +324,16 @@ const createWorkerOptions = (app, extra = {}) => {
     `${app.id} BFF worker surface is not selected by Miniflare`,
   );
   assert(
-    app.kind !== "vertical" ||
+    !app.hasApiSurface ||
       (Array.isArray(ssr) &&
-        ssr.includes(mainLogicalPath) &&
+        (app.apiOnly
+          ? ssr.length === 0 && mainLogicalPath === "server/index.mjs"
+          : ssr.includes(mainLogicalPath)) &&
         boundModules.every((module) =>
-          [...ssr, ...(apiBackend ?? [])].includes(module.logicalPath),
+          [...ssr, ...(apiBackend ?? []), ...(app.apiOnly ? [mainLogicalPath] : [])]
+            .includes(module.logicalPath),
         )),
-    `${app.id} Miniflare main/SSR modules are not envelope-bound SSR surfaces`,
+    `${app.id} Miniflare main/SSR modules do not match its envelope surfaces`,
   );
 
   return {
@@ -259,8 +355,8 @@ const createWorkerOptions = (app, extra = {}) => {
     modulesRoot: app.outputRoot,
     compatibilityDate: app.wrangler.compatibility_date,
     compatibilityFlags: app.wrangler.compatibility_flags,
+    bindings: { ...app.wrangler.vars, ...app.devVars },
     assets: {
-      workerName: workerName(app),
       binding: typeof assets.binding === "string" ? assets.binding : "ASSETS",
       directory: path.resolve(app.outputRoot, directory),
       routerConfig: {
@@ -295,7 +391,10 @@ const findReleaseMarkers = (value, markers = []) => {
   return markers;
 };
 
-const responseEvidence = async (app, response) => {
+const jsonPathValue = (value, key) =>
+  String(key).split(".").reduce((current, segment) => current?.[segment], value);
+
+const responseEvidence = async (app, response, check) => {
   const bytes = Buffer.from(await response.arrayBuffer());
   let body;
   try {
@@ -303,19 +402,36 @@ const responseEvidence = async (app, response) => {
   } catch (error) {
     throw new Error(`${app.id} API response is not JSON: ${error.message}`);
   }
-  const markers = findReleaseMarkers(body);
-  const marker = markers.find(
-    (candidate) =>
-      candidate.appId === app.id &&
-      candidate.build === app.envelope.identity.buildMarker &&
-      candidate.version === app.envelope.identity.releaseVersion,
-  );
-  assert(marker, `${app.id} API response is not tied to its executed release identity`);
   assert(response.ok, `${app.id} API response returned HTTP ${response.status}`);
+  let marker;
+  if (app.apiProtocol === "rpc") {
+    assert(
+      typeof app.rpcRoute === "string" && app.rpcRoute.startsWith("/") &&
+        check.route === app.rpcRoute && String(check.method).toUpperCase() === "POST" &&
+        check.body?.jsonrpc === "2.0" && check.body?.id !== undefined &&
+        body?.jsonrpc === "2.0" && body.id === check.body.id,
+      `${app.id} RPC response does not match its declared POST request`,
+    );
+    assert(
+      check.expect && Object.keys(check.expect).length > 0 &&
+        Object.entries(check.expect).every(([key, expected]) =>
+          JSON.stringify(jsonPathValue(body, key)) === JSON.stringify(expected)),
+      `${app.id} RPC response does not satisfy its declared JSON smoke check`,
+    );
+  } else {
+    const markers = findReleaseMarkers(body);
+    marker = markers.find(
+      (candidate) =>
+        candidate.appId === app.id &&
+        candidate.build === app.envelope.identity.buildMarker &&
+        candidate.version === app.envelope.identity.releaseVersion,
+    );
+    assert(marker, `${app.id} API response is not tied to its executed release identity`);
+  }
   return {
     bodyBase64: bytes.toString("base64"),
     byteLength: bytes.byteLength,
-    releaseMarker: marker,
+    ...(marker ? { releaseMarker: marker } : {}),
     sha256: sha256(bytes),
     status: response.status,
   };
@@ -348,9 +464,9 @@ const resolveApiSmokeChecks = (app, shell) => {
   return [...uniqueChecks.values()];
 };
 
-const runApiProofs = async (miniflare, shell, executionByAppId) => {
+const runApiProofs = async (apps, miniflare, shell, executionByAppId) => {
   const results = [];
-  for (const app of apps.filter((candidate) => candidate.kind === "vertical")) {
+  for (const app of apps.filter((candidate) => candidate.hasApiSurface)) {
     const jsonSmokeChecks = resolveApiSmokeChecks(app, shell);
     assert(
       jsonSmokeChecks.length > 0,
@@ -359,7 +475,10 @@ const runApiProofs = async (miniflare, shell, executionByAppId) => {
     const binding = (shell.wrangler.services ?? []).find(
       (candidate) => candidate.service === workerName(app),
     );
-    assert(binding, `${shell.id} has no service binding for ${app.id}`);
+    assert(
+      binding || (app.apiOnly && !shell.verticalRefs.includes(app.id)),
+      `${shell.id} has no service binding for ${app.id}`,
+    );
     for (const check of jsonSmokeChecks) {
       const method = String(check.method ?? "GET").toUpperCase();
       const headers = {};
@@ -373,31 +492,39 @@ const runApiProofs = async (miniflare, shell, executionByAppId) => {
         await (
           await miniflare.getWorker(workerName(app))
         ).fetch(`https://${workerName(app)}.invalid${check.route}`, init),
+        check,
       );
-      const throughShell = await responseEvidence(
-        app,
-        await miniflare.dispatchFetch(
-          `https://${workerName(shell)}.invalid${check.route}`,
-          init,
-        ),
-      );
-      assert(
-        direct.sha256 === throughShell.sha256,
-        `${app.id} direct and service-binding API responses differ`,
-      );
+      const throughShell = binding
+        ? await responseEvidence(
+            app,
+            await miniflare.dispatchFetch(
+              `https://${workerName(shell)}.invalid${check.route}`,
+              init,
+            ),
+            check,
+          )
+        : undefined;
+      if (throughShell) {
+        assert(
+          direct.sha256 === throughShell.sha256,
+          `${app.id} direct and service-binding API responses differ`,
+        );
+      }
+      const target = {
+        appId: app.id,
+        envelopeDigest: executionByAppId.get(app.id).envelopeDigest,
+        worker: workerName(app),
+      };
       results.push({
         appId: app.id,
-        binding: binding.binding,
-        bindingTarget: {
-          appId: app.id,
-          envelopeDigest: executionByAppId.get(app.id).envelopeDigest,
-          worker: workerName(app),
-        },
+        shellId: shell.id,
+        ...(binding
+          ? { binding: binding.binding, bindingTarget: target, throughShell }
+          : { directTarget: target }),
         direct,
         id: check.id,
         method,
         route: check.route,
-        throughShell,
       });
     }
   }
@@ -427,6 +554,7 @@ const closeServer = (server) =>
   });
 
 const startWorkerdTargetServers = async (
+  apps,
   miniflare,
   failedServices,
   workerConfigurations,
@@ -440,16 +568,9 @@ const startWorkerdTargetServers = async (
         Number.isInteger(app.port) && app.port > 0,
         `${app.id} requires a configured local port for all-workerd browser proof`,
       );
-      // Miniflare 4 currently assigns one shared assets storage service inside
-      // a multi-worker instance. Keep the shell composition runtime intact,
-      // but give every directly browsed MicroVertical its own runtime so its
-      // static assets and MF manifest cannot resolve from a sibling Worker.
       const runtime =
         app.kind === "vertical"
-          ? new Miniflare({
-              log: new Log(LogLevel.ERROR),
-              workers: [workerConfigurations[index]],
-            })
+          ? createIsolatedRuntime(workerConfigurations[index])
           : miniflare;
       if (runtime !== miniflare) {
         isolatedVerticalRuntimes.push(runtime);
@@ -597,9 +718,22 @@ const decodeDistributedSsrFragmentRequest = (request) => {
   };
 };
 
+// Miniflare assigns one shared assets storage service inside a multi-worker
+// instance. Keep the shell composition runtime intact, but give every directly
+// requested MicroVertical its own runtime so its static assets and MF manifest
+// cannot resolve from a sibling Worker. Its service bindings still resolve
+// through the shared composition runtime.
+const createIsolatedRuntime = (workerOptions) =>
+  new Miniflare(
+    convertV4MiniflareOptions({
+      log: new Log(LogLevel.ERROR),
+      workers: [workerOptions],
+    }),
+  );
+
 const createServiceBindings = (
   caller,
-  { apiBindingRequests, failedServices, fragmentBindingRequests },
+  { apiBindingRequests, composition, failedServices, fragmentBindingRequests },
 ) => {
   const services = Array.isArray(caller.wrangler.services) ? caller.wrangler.services : [];
   return Object.fromEntries(
@@ -610,7 +744,7 @@ const createServiceBindings = (
       );
       return [
         service.binding,
-        async (request, miniflare) => {
+        async (request) => {
           if (failedServices.has(service.service)) {
             throw new Error(
               `Injected unavailable service binding ${service.binding} -> ${service.service}`,
@@ -647,7 +781,7 @@ const createServiceBindings = (
             };
             apiBindingRequests.push(apiBindingRequest);
           }
-          const target = await miniflare.getWorker(service.service);
+          const target = await composition.miniflare.getWorker(service.service);
           const response = await target.fetch(request);
           if (apiBindingRequest !== undefined) {
             apiBindingRequest.response = {
@@ -662,11 +796,96 @@ const createServiceBindings = (
   );
 };
 
-const proofs = [];
-const apiProofs = [];
-let executions = [];
+const proveRoute = async (app, route, fetchRoute, apps, recorders) => {
+  const apiBindingRequestStart = recorders.apiBindingRequests.length;
+  const fragmentBindingRequestStart = recorders.fragmentBindingRequests.length;
+  const outboundRequestStart = recorders.outboundRequests.length;
+  const response = await fetchRoute(`https://${workerName(app)}.invalid${route}`, {
+    headers: { accept: "text/html" },
+  });
+  const html = await response.text();
+  const htmlBytes = Buffer.byteLength(html);
+  const routeOutboundRequests = recorders.outboundRequests.slice(outboundRequestStart);
+  assert(
+    response.status === 200,
+    `${app.id} returned HTTP ${response.status} for ${route} in workerd; outbound requests: ${JSON.stringify(routeOutboundRequests)}; response: ${html.slice(0, 500)}`,
+  );
+  assert(
+    response.headers.get("content-type")?.includes("text/html") === true,
+    `${app.id} did not return HTML for ${route} in workerd`,
+  );
+  // Runaway server rendering (for example a worker re-rendering its own
+  // route data requests) can still end in an oversized document.
+  assert(
+    htmlBytes <= app.ssrHtmlMaxBytes,
+    `${app.id} rendered ${htmlBytes} bytes for ${route} in workerd, over the ${app.ssrHtmlMaxBytes} byte ssrHtmlMaxBytes budget`,
+  );
+  assert(
+    !html.includes('data-modern-distributed-ssr-status="degraded"'),
+    `${app.id} rendered a degraded MicroVertical fallback for ${route} in workerd`,
+  );
+
+  const boundaries = collectDistributedBoundaries(html);
+  const routeApiBindingRequests = recorders.apiBindingRequests.slice(apiBindingRequestStart);
+  const routeFragmentBindingRequests = recorders.fragmentBindingRequests.slice(
+    fragmentBindingRequestStart,
+  );
+  for (const boundary of boundaries) {
+    assert(
+      boundary.status === "ready",
+      `${app.id} did not mark ${boundary.key} as ready for ${route}`,
+    );
+    assert(
+      typeof boundary.buildMarker === "string" && boundary.buildMarker.length > 0,
+      `${app.id} ${boundary.key} is missing immutable build provenance`,
+    );
+    assert(
+      /^[a-f\d]{64}$/u.test(boundary.digest ?? ""),
+      `${app.id} ${boundary.key} is missing a verified SHA-256 digest`,
+    );
+    const remote = apps.find((candidate) => candidate.id === boundary.remote);
+    assert(remote, `${app.id} rendered unknown remote ${boundary.remote}`);
+    const requests = routeFragmentBindingRequests.filter(
+      (request) =>
+        request.service === workerName(remote) &&
+        request.remote === boundary.remote &&
+        request.expose === boundary.expose,
+    );
+    const renderedCount = boundaries.filter(
+      (candidate) => candidate.key === boundary.key,
+    ).length;
+    assert(
+      requests.length === renderedCount &&
+        requests.every((request) => request.pathname.includes("/_mf/fragment/")),
+      `${app.id} must compose each ${boundary.key} occurrence through its remote service binding`,
+    );
+  }
+
+  const stylesheetHrefs = collectStylesheetHrefs(html);
+  assert(
+    new Set(stylesheetHrefs).size === stylesheetHrefs.length,
+    `${app.id} rendered duplicate distributed SSR stylesheets for ${route}`,
+  );
+  assert(
+    !routeOutboundRequests.some(({ url }) => /(?:remoteEntry|\.m?js(?:\?|$))/u.test(url)),
+    `${app.id} attempted to fetch remote JavaScript during ${route} server rendering`,
+  );
 
-const writeReport = () => {
+  return {
+    worker: workerName(app),
+    route,
+    status: response.status,
+    htmlBytes,
+    boundaries,
+    fragmentBindingRequests: routeFragmentBindingRequests,
+    apiBindingRequests: routeApiBindingRequests,
+    outboundRequests: routeOutboundRequests,
+    stylesheetHrefs,
+    degradedBoundaryCount: count(html, 'data-modern-distributed-ssr-status="degraded"'),
+  };
+};
+
+const writeReport = (reportPath, report) => {
   fs.mkdirSync(path.dirname(reportPath), { recursive: true });
   fs.writeFileSync(
     reportPath,
@@ -674,10 +893,8 @@ const writeReport = () => {
       {
         schemaVersion: 3,
         runtime: "workerd",
-        routes: [...new Set(proofs.map((proof) => proof.route))],
-        executions,
-        apiProofs,
-        proofs,
+        routes: [...new Set(report.proofs.map((proof) => proof.route))],
+        ...report,
       },
       null,
       2,
@@ -685,150 +902,125 @@ const writeReport = () => {
   );
 };
 
-for (const shell of shells) {
-  const expectedRemotes = shell.verticalRefs.map((ref) => {
-    const remote = apps.find((app) => app.id === ref);
-    assert(remote, `${shell.id} references missing MicroVertical ${ref}`);
-    return remote;
-  });
-  assert(expectedRemotes.length > 0, `${shell.id} has no MicroVerticals to prove`);
+const main = async () => {
+  const workspaceRoot = path.resolve(process.env.ULTRAMODERN_WORKSPACE_ROOT ?? process.cwd());
+  const reportPath = path.join(workspaceRoot, reportRelativePath);
+  const keepWorkerd = process.env.ULTRAMODERN_KEEP_WORKERD === "1";
+  const apps = loadApps(
+    workspaceRoot,
+    readJson(path.join(workspaceRoot, "topology/reference-topology.json")),
+    readJson(path.join(workspaceRoot, "topology/local-overlays/development.json")),
+  );
+  const shells = apps.filter((app) => app.kind === "shell");
+  assert(!keepWorkerd || shells.length === 1, "Browser workerd proof requires exactly one shell");
 
-  const apiBindingRequests = [];
+  const recorders = {
+    apiBindingRequests: [],
+    fragmentBindingRequests: [],
+    outboundRequests: [],
+  };
   const failedServices = new Set();
-  const fragmentBindingRequests = [];
-  const outboundRequests = [];
+  const composition = {};
   const workerConfigurations = apps.map((app) =>
-    createWorkerOptions(app, {
-      serviceBindings: createServiceBindings(app, {
-        apiBindingRequests,
-        failedServices,
-        fragmentBindingRequests,
-      }),
+    createWorkerOptions(app, workspaceRoot, {
+      serviceBindings: createServiceBindings(app, { ...recorders, composition, failedServices }),
       async outboundService(request) {
         const requestUrl = new URL(request.url);
-        outboundRequests.push({ callerId: app.id, url: requestUrl.href });
+        recorders.outboundRequests.push({ callerId: app.id, url: requestUrl.href });
         return new Response("External network disabled by SSR proof", {
           status: 502,
         });
       },
     }),
   );
-  executions = workerConfigurations.map((configuration) => configuration.executionEvidence);
-  const executionByAppId = new Map(
-    apps.map((app, index) => [app.id, executions[index]]),
-  );
+  const executions = workerConfigurations.map((configuration) => configuration.executionEvidence);
+  const executionByAppId = new Map(apps.map((app, index) => [app.id, executions[index]]));
   const workers = workerConfigurations.map(
     ({ executionEvidence: _executionEvidence, ...configuration }) => configuration,
   );
-  const miniflare = new Miniflare({
-    log: new Log(LogLevel.ERROR),
-    workers,
-  });
-  const renderedRemoteIds = new Set();
+  const miniflare = new Miniflare(
+    convertV4MiniflareOptions({
+      log: new Log(LogLevel.ERROR),
+      workers,
+    }),
+  );
+  composition.miniflare = miniflare;
+  const report = { executions, apiProofs: [], proofs: [], verticalProofs: [] };
 
   try {
-    for (const route of shell.proofRoutes) {
-      const apiBindingRequestStart = apiBindingRequests.length;
-      const fragmentBindingRequestStart = fragmentBindingRequests.length;
-      const outboundRequestStart = outboundRequests.length;
-      const response = await miniflare.dispatchFetch(
-        `https://${workerName(shell)}.invalid${route}`,
-        { headers: { accept: "text/html" } },
-      );
-      const html = await response.text();
-      assert(
-        response.status === 200,
-        `${shell.id} returned HTTP ${response.status} for ${route} in workerd`,
-      );
-      assert(
-        !html.includes('data-modern-distributed-ssr-status="degraded"'),
-        `${shell.id} rendered a degraded MicroVertical fallback for ${route} in workerd`,
-      );
-
-      const boundaries = collectDistributedBoundaries(html);
-      assert(
-        boundaries.length > 0,
-        `${shell.id} rendered no distributed SSR boundaries for ${route}`,
-      );
-      const routeApiBindingRequests = apiBindingRequests.slice(
-        apiBindingRequestStart,
-      );
-      const routeFragmentBindingRequests = fragmentBindingRequests.slice(
-        fragmentBindingRequestStart,
-      );
-      const routeOutboundRequests = outboundRequests.slice(outboundRequestStart);
-      for (const boundary of boundaries) {
-        renderedRemoteIds.add(boundary.remote);
-        assert(
-          boundary.status === "ready",
-          `${shell.id} did not mark ${boundary.key} as ready for ${route}`,
+    for (const shell of shells) {
+      // Shell routes compose declared server-rendered boundaries through the
+      // shell's entry Worker exactly as a browser request would.
+      const renderedRemoteIds = new Set();
+      for (const route of shell.ssrRoutes) {
+        const proof = await proveRoute(
+          shell,
+          route,
+          (url, init) => miniflare.dispatchFetch(url, init),
+          apps,
+          recorders,
         );
         assert(
-          typeof boundary.buildMarker === "string" && boundary.buildMarker.length > 0,
-          `${shell.id} ${boundary.key} is missing immutable build provenance`,
+          shell.serverRenderedRoutes.length > 0 || proof.boundaries.length === 0,
+          `${shell.id} declares client composition but rendered distributed SSR boundaries for ${route}`,
         );
+        if (shell.serverRenderedRoutes.includes(route)) {
+          assert(
+            shell.serverRenderedRemoteIds.length === 0 || proof.boundaries.length > 0,
+            `${shell.id} rendered no distributed SSR boundaries for ${route}`,
+          );
+          for (const boundary of proof.boundaries) {
+            renderedRemoteIds.add(boundary.remote);
+          }
+        }
+        report.proofs.push({ shellId: shell.id, ...proof });
+      }
+      for (const remoteId of shell.serverRenderedRemoteIds) {
         assert(
-          /^[a-f\d]{64}$/u.test(boundary.digest ?? ""),
-          `${shell.id} ${boundary.key} is missing a verified SHA-256 digest`,
-        );
-        const remote = apps.find((app) => app.id === boundary.remote);
-        assert(remote, `${shell.id} rendered unknown remote ${boundary.remote}`);
-        const requests = routeFragmentBindingRequests.filter(
-          (request) =>
-            request.service === workerName(remote) &&
-            request.remote === boundary.remote &&
-            request.expose === boundary.expose,
-        );
-        const renderedCount = boundaries.filter(
-          (candidate) => candidate.key === boundary.key,
-        ).length;
-        assert(
-          requests.length === renderedCount &&
-            requests.every((request) => request.pathname.includes("/_mf/fragment/")),
-          `${shell.id} must compose each ${boundary.key} occurrence through its remote service binding`,
+          renderedRemoteIds.has(remoteId),
+          `${shell.id} proof routes are missing independently rendered ${remoteId} content`,
         );
       }
-
-      const stylesheetHrefs = collectStylesheetHrefs(html);
-      assert(
-        new Set(stylesheetHrefs).size === stylesheetHrefs.length,
-        `${shell.id} rendered duplicate distributed SSR stylesheets for ${route}`,
+      report.apiProofs.push(
+        ...(await runApiProofs(apps, miniflare, shell, executionByAppId)),
       );
-      assert(
-        !routeOutboundRequests.some(({ url }) => /(?:remoteEntry|\.m?js(?:\?|$))/u.test(url)),
-        `${shell.id} attempted to fetch remote JavaScript during ${route} server composition`,
-      );
-
-      proofs.push({
-        shellId: shell.id,
-        worker: workerName(shell),
-        route,
-        status: response.status,
-        boundaries,
-        fragmentBindingRequests: routeFragmentBindingRequests,
-        apiBindingRequests: routeApiBindingRequests,
-        outboundRequests: routeOutboundRequests,
-        stylesheetHrefs,
-        degradedBoundaryCount: count(html, 'data-modern-distributed-ssr-status="degraded"'),
-      });
     }
 
-    for (const remote of expectedRemotes) {
-      assert(
-        renderedRemoteIds.has(remote.id),
-        `${shell.id} proof routes are missing independently rendered ${remote.id} content`,
-      );
+    // Every UI MicroVertical proves its own Worker at its declared SSR routes,
+    // whether or not a shell also composes it on the server.
+    for (const [index, vertical] of apps.entries()) {
+      if (vertical.kind !== "vertical" || vertical.ssrRoutes.length === 0) {
+        continue;
+      }
+      const runtime = createIsolatedRuntime(workers[index]);
+      try {
+        for (const route of vertical.ssrRoutes) {
+          report.verticalProofs.push({
+            appId: vertical.id,
+            ...(await proveRoute(
+              vertical,
+              route,
+              (url, init) => runtime.dispatchFetch(url, init),
+              apps,
+              recorders,
+            )),
+          });
+        }
+      } finally {
+        await runtime.dispose();
+      }
     }
-    apiProofs.push(...(await runApiProofs(miniflare, shell, executionByAppId)));
-    if (process.env.ULTRAMODERN_KEEP_WORKERD === "1") {
-      writeReport();
+
+    writeReport(reportPath, report);
+    if (keepWorkerd) {
       const targetServers = await startWorkerdTargetServers(
+        apps,
         miniflare,
         failedServices,
         workers,
       );
       console.log(`WORKERD_TARGET_URLS=${JSON.stringify(targetServers.targetUrls)}`);
-      console.log(`WORKERD_URL=${targetServers.targetUrls[shell.id]}`);
+      console.log(`WORKERD_URL=${targetServers.targetUrls[shells[0].id]}`);
       try {
         await new Promise((resolve) => {
           process.once("SIGINT", resolve);
@@ -841,7 +1033,10 @@ for (const shell of shells) {
   } finally {
     await miniflare.dispose();
   }
-}
 
-writeReport();
-console.log(`Workerd SSR composition proof passed for ${shells.length} shell(s): ${reportPath}`);
+  console.log(`Workerd SSR composition proof passed for ${shells.length} shell(s): ${reportPath}`);
+};
+
+if (import.meta.main) {
+  await main();
+}