@ultimat3/cli 22.14.0 → 23.0.0

package/src/serve-boot.ts

@@ -1,45 +1,69 @@
-// The web and background roles' boot, after the services are up: the app loaded, its route table
-// built, the roles started. Split from `serve.ts` (the entry points) at its line ceiling; the rules
-// that file's header states — the SAME boot `x dev` runs, minus the watcher, `/_x` and `dev: true`
-// — are this file's.
+// The serving roles' boot: the services started, the app loaded, its route table built, the roles
+// started. Behind ONE `await import()` in `serve.ts` (the entry points), so `ROLE=migrate` loads
+// none of it; the rules that file's header states — the SAME boot `x dev` runs, minus the watcher,
+// `/_x` and `dev: true` — are this file's. A role imports what it runs: the web surface
+// (`serve-web.ts`) and the manifest projection are behind `await import()` in turn, so a worker's
+// module graph holds neither.
 
 import type { Role } from '@ultimat3/core';
-import { configureLifecycle } from '@ultimat3/core';
-import type { Route } from '@ultimat3/http';
-import { describeRoutes } from '@ultimat3/render';
-import { createIsrController } from '@ultimat3/render/server';
-import { apiMountRoutes, apiRoutes, pagePostRoutes } from './api-routes';
-import { loadSignInPath } from './app-auth';
-import { loadApp } from './app-load';
-import { appManifest } from './app-manifest';
-import { mountAppMcp } from './app-mcp';
-import { errorPageStyleSources } from './error-page-csp';
-import { islandRoutes } from './island-routes';
-import { loadOrBuildIslands } from './island-store';
+import { configureLifecycle, logger } from '@ultimat3/core';
 import type { MetricsEndpoint } from './metrics-endpoint';
 import { startOtlpExport } from './otlp-export';
-import { loadNavigation, pageNavigation } from './page-navigation';
-import { pageSync } from './page-sync';
-import { loadPwaArtifacts } from './pwa-artifacts';
+import { loadAppForRole, roleLoadFor } from './role-load';
 import { startRoles } from './role-start';
-import { assetRoutes } from './runtime-assets';
-import { appRoutes } from './runtime-render';
+import { resolveServices } from './runtime-bindings';
 import { replicaOverrides } from './runtime-replica';
 import type { RunningServices } from './runtime-services';
-import { servedStorage, storageRoutes } from './runtime-storage';
-import { seoRoutes } from './seo-routes';
+import { startServices } from './runtime-services';
 import { loadDrainConfig, loadHealthConfig } from './serve-drain';
 import { configureReporting, containerBinding, metricsPortFor, portFromEnv } from './serve-env';
+import { adoptPrebuiltStyles, reportBootBuilds, watchBootBuilds } from './serve-prebuilt';
 import type { ServedApp, ServeOptions } from './serve-types';
-import { loadSiteSettings, publicOrigin } from './site-config';
-import { styleBundle } from './style-bundle';
-import { styleRoutes } from './style-routes';
-import { serviceWorkerArtifacts } from './sw-artifacts';
-import { serviceWorkerRoutes } from './sw-routes';
-import { loadThemeMode, themeBoot } from './theme-boot';
+
+/**
+ * The build stamps `BUILD_ID` into the image; unstamped, the manifest's content hash is the same
+ * answer computed here, so `x-ultimate-build` is never absent and never a lie. Projected only when
+ * unstamped, because a stamped image already paid for it at build time and a replica's boot should
+ * not repeat it. The projection describes the WHOLE app — routes included — so an unstamped worker
+ * imports everything its own load left out, and says so.
+ */
+async function buildIdFor(options: ServeOptions, role: Role): Promise<string> {
+  const stamped = options.env['BUILD_ID'];
+  if (stamped !== undefined && stamped.length > 0) return stamped;
+  if (roleLoadFor(role) === 'background') {
+    logger.warn('ultimate build id unstamped', {
+      role,
+      cause:
+        'BUILD_ID is unset, so this role imported every page of the app to compute the build id the web role serves',
+      fix: 'x build --target docker',
+    });
+  }
+  const { appManifest } = await import('./app-manifest');
+  return (await appManifest(options.root)).manifest.buildId;
+}
+
+/**
+ * Everything `serveApp` does after the scrape listener is open: the services, then the roles over
+ * them. One export, so `serve.ts` reaches the whole serving graph through ONE `await import()`.
+ */
+export async function bootServing(boot: {
+  readonly options: ServeOptions;
+  readonly role: Role;
+  readonly acquired: (() => void | Promise<void>)[];
+  readonly metrics: MetricsEndpoint;
+}): Promise<ServedApp> {
+  const { options } = boot;
+  const runtime = await startServices(
+    resolveServices(options.root, options.env),
+    options.env,
+    options.runtime,
+  );
+  boot.acquired.push(() => runtime.stop());
+  return bootRoles({ ...boot, runtime });
+}
 
 /** The half of `serveApp` whose every acquisition is registered for rollback. */
-export async function bootRoles(boot: {
+async function bootRoles(boot: {
   readonly options: ServeOptions;
   readonly role: Role;
   readonly runtime: RunningServices;
@@ -48,18 +72,19 @@ export async function bootRoles(boot: {
   readonly metrics: MetricsEndpoint;
 }): Promise<ServedApp> {
   const { options, role, runtime, acquired, metrics } = boot;
+  // The image's compiled stylesheets, before the first page is imported — importing one IS
+  // compiling its sheet — and the count of what this boot compiles anyway.
+  adoptPrebuiltStyles(options.root);
+  const bootBuilds = watchBootBuilds();
   // Importing the app's modules IS the registration: every route, action and job below is
-  // whatever this call put in the registries.
-  await loadApp(options.root);
-  // The build stamps `BUILD_ID` into the image; unstamped, the manifest's content hash is the same
-  // answer computed here, so `x-ultimate-build` is never absent and never a lie. Projected only
-  // when unstamped, because a stamped image already paid for it at build time and a replica's boot
-  // should not repeat it — the load above is the part every boot needs either way.
-  const stamped = options.env['BUILD_ID'];
-  const buildId =
-    stamped !== undefined && stamped.length > 0
-      ? stamped
-      : (await appManifest(options.root)).manifest.buildId;
+  // whatever this call put in the registries — for THIS role (`role-load.ts`).
+  const loaded = await loadAppForRole(options.root, role);
+  // A module that would not import registered nothing, and a process that only logs the roles it
+  // started gives no sign of it: each one is a line an operator can act on.
+  for (const finding of loaded.findings) {
+    logger.error('ultimate app module failed to load', { role, ...finding });
+  }
+  const buildId = await buildIdFor(options, role);
   // Before the first socket opens: everything above this line fails loudly into the container's
   // own logs, everything below it is a served request, a claimed job or a routed frame.
   configureReporting(options.env, buildId);
@@ -71,8 +96,16 @@ export async function bootRoles(boot: {
   acquired.push(stopOtlp);
   // Only the web role serves pages, so only it builds islands and assembles a route table: a
   // worker, scheduler, sync or replicator pod compiled every island of the app on every boot for
-  // nothing it would ever serve (plan 101, slice 12 e).
-  const web = role === 'web' ? await webSurface(options, runtime, buildId) : undefined;
+  // nothing it would ever serve (plan 101, slice 12 e). The MODULE is the web role's as well —
+  // imported here, it is render, PWA, SEO and MCP code no other role evaluates.
+  const web =
+    role === 'web'
+      ? await (await import('./serve-web')).webSurface(options, runtime, buildId)
+      : undefined;
+  // Islands and stylesheets are the image build's to make (`x build --target prebuilt`). A role
+  // that made either here served correctly and paid for it — seconds of CPU and a compiler's
+  // memory, on every start of every replica — so it says so once, with the Dockerfile line.
+  reportBootBuilds(role, bootBuilds(web?.islandsBuilt));
   const port = options.port ?? portFromEnv(options.env);
   // An in-process caller asking for an ephemeral app port is a test, and a test that grabbed the
   // fixed 9090 would fail the next suite to boot beside it. An environment that names the port
@@ -92,13 +125,15 @@ export async function bootRoles(boot: {
     runtime,
     routes: web?.routes ?? [],
     env: options.env,
-    // Same declaration `x dev` reads. Without it a container answers a browser that opened a
-    // guarded page with the problem document, rendered as raw JSON in the viewport.
-    signInPath: await loadSignInPath(options.root),
-    // The enforced policy this process sends must admit the app's own error pages' `<style>` and
-    // the theme boot the documents carry; `x dev` is report-only, so only here was it a blank page.
-    inlineStyles: web === undefined ? [] : await errorPageStyleSources(options.root),
-    inlineScripts: web === undefined ? [] : [web.themeCsp],
+    // The three facts only a process serving documents has (`WebSurface`); `startWeb` is their
+    // one reader, so every other role hands none.
+    ...(web === undefined
+      ? {}
+      : {
+          signInPath: web.signInPath,
+          inlineStyles: web.inlineStyles,
+          inlineScripts: web.inlineScripts,
+        }),
     // The app's own `apps/web/site/errors/<status>.html`, resolved inside `startWeb` so this
     // process and `x dev` cannot answer a browser differently.
     root: options.root,
@@ -128,100 +163,3 @@ export async function bootRoles(boot: {
     },
   };
 }
-
-/** What only the web role serves: its islands, its documents and every route beside them. */
-async function webSurface(
-  options: ServeOptions,
-  runtime: RunningServices,
-  buildId: string,
-): Promise<{ readonly routes: readonly Route[]; readonly themeCsp: string }> {
-  // Read from the store `x build --target docker` wrote and VERIFIED against this app and this
-  // runtime (`island-store.ts`); built here only when there is no store to trust, which is correct
-  // and slower, and logged with its reason.
-  const islands = await loadOrBuildIslands(options.root);
-  // The same two strings `x dev` resolves, from the same reader: a `<link rel="manifest">` served
-  // on a laptop and absent in the image is exactly the dev/prod difference this file exists to
-  // prevent, and it is the one an operator cannot see without installing the app.
-  const pwa = await loadPwaArtifacts(options.root);
-  const theme = themeBoot(await loadThemeMode(options.root));
-  // `site.origin` and `seo.robots.disallow`: the absolute URLs every document and the sitemap carry.
-  const site = await loadSiteSettings(options.root);
-  const origin = publicOrigin(options.env, site);
-  // The page's sync target and its scripts — the same call `x dev` makes, so the two cannot differ.
-  // Before the service worker, which precaches those scripts.
-  const sync = await pageSync(options.root, options.env, buildId, runtime.realtime);
-  // The client router, when a surface opted in (`navigation.client`) — the same call in both boots.
-  const navigation = await pageNavigation(
-    options.root,
-    await loadNavigation(options.root),
-    buildId,
-  );
-  // The worker, from the SAME route table this process is about to serve — `describeRoutes()` is
-  // the one projection `x.manifest.json`, `/_x`, the sitemap and `sw.js` are all built from, so a
-  // route added here cannot be missing from the precache manifest.
-  const serviceWorker =
-    pwa === undefined
-      ? undefined
-      : serviceWorkerArtifacts({
-          pwa,
-          buildId,
-          routes: describeRoutes(),
-          islands,
-          styles: styleBundle(),
-          scripts: [
-            ...sync.scripts,
-            ...(navigation.script === undefined ? [] : [navigation.script]),
-          ],
-        });
-  // The app's own MCP endpoint, through the same call `x dev` makes — see `app-mcp.ts`.
-  const mcpMount = await mountAppMcp(options.root);
-  // The app's own disks when it declared any (`defineStorage` in an app module), else this boot's.
-  const served = servedStorage(runtime.storage);
-  const routes: readonly Route[] = [
-    ...apiRoutes(),
-    // The bearer doors onto a cut of the same routes (`defineApi({ http: { mounts } })`), counted
-    // on the store this boot's limiter uses, so one token's allowance is one number fleet-wide.
-    ...apiMountRoutes(options.runtime?.rateLimitStore ?? runtime.rateLimitStore),
-    ...mcpMount.routes,
-    // The app's own plain routes (`apps/<app>/runtime.ts` `routes`), before any page can shadow one.
-    ...(options.runtime?.routes ?? []),
-    ...(serviceWorker === undefined ? [] : serviceWorkerRoutes(serviceWorker)),
-    ...assetRoutes({
-      root: options.root,
-      storage: served,
-      ...(options.runtime?.images === undefined ? {} : { images: options.runtime.images }),
-      ...(pwa === undefined ? {} : { pwa }),
-    }),
-    ...storageRoutes({ storage: served }),
-    ...islandRoutes(() => islands),
-    // The surface stylesheets the documents link. Built from the registry the `loadApp` above
-    // filled, so this process serves exactly the CSS it renders against.
-    ...styleRoutes(() => styleBundle()),
-    // `robots.txt` and `sitemap.xml`, the same two files the static export writes (`site-seo.ts`).
-    ...seoRoutes({ env: options.env, site, root: options.root }),
-    // The page's one socket: its worker script, served beside the islands for their reason.
-    ...sync.routes,
-    ...navigation.routes,
-    // A page's `POST`, bound to an action (`defineRoute({ post })`) — beside the page's `GET`.
-    ...pagePostRoutes(),
-    ...appRoutes({
-      buildId,
-      resolveIsland: (file) => islands.resolverFor(file),
-      ...(sync.head === undefined ? {} : { sync: sync.head }),
-      persisted: sync.persisted,
-      ...(navigation.head === undefined ? {} : { navigation: navigation.head }),
-      themeHead: theme.head,
-      ...(origin === undefined ? {} : { origin }),
-      ...(pwa === undefined
-        ? {}
-        : { pwaHead: (locale: string) => pwa.headFor(locale) + (serviceWorker?.head ?? '') }),
-      // Only when a store was supplied. `createIsrController` defaults to a per-process memory
-      // store, so twelve replicas hold twelve of them and a purge tag regenerates one twelfth of
-      // the fleet while the other eleven keep serving the page it just invalidated.
-      ...(options.runtime?.isrStore === undefined
-        ? {}
-        : { isr: createIsrController({ buildId, store: options.runtime.isrStore }) }),
-    }),
-  ];
-  return { routes, themeCsp: theme.cspSource };
-}

package/src/serve-prebuilt-paths.ts

@@ -0,0 +1,19 @@
+// Where the image's prebuilt store lives and the one command that writes it. A leaf with no
+// import, so the Dockerfile template, the build command and the container boot all spell them
+// from here without loading each other.
+
+/**
+ * App-root-relative. NOT under `.x/`: that is the state directory, which the scaffolded compose
+ * topology mounts a tmpfs over and every ignore file drops, so a store written there never reached
+ * a running container. Under `node_modules` because that is the one directory every tool already
+ * leaves alone — git, the linter, every source walker and the image context — and the one the
+ * image build has just written, so it is in a layer and readable under a read-only root.
+ */
+export const PREBUILT_DIR = 'node_modules/.cache/ultimate';
+
+export const PREBUILT_ISLANDS_DIR = `${PREBUILT_DIR}/islands`;
+
+export const PREBUILT_SASS_DIR = `${PREBUILT_DIR}/sass`;
+
+/** The Dockerfile line that writes the store — one spelling, for the template and every `fix:`. */
+export const PREBUILT_COMMAND = 'bun node_modules/@ultimat3/cli/src/bin.ts build --target prebuilt';

package/src/serve-prebuilt.ts

@@ -0,0 +1,84 @@
+// The image's prebuilt store, as a container sees it: where `x build --target prebuilt` wrote the
+// island chunks and the compiled stylesheets during `docker build`, and the one log line a role
+// owes when it had to build either at boot instead. A leaf of the boot graph — the half that
+// WRITES the store (`image-prepare.ts`) carries the island builder and is never loaded here.
+
+// why: the store is adopted before the first app module is imported, and that import path is
+// synchronous end to end (`compileStylesheet` runs inside Bun's `onLoad`); Bun has no sync exists.
+import { existsSync } from 'node:fs';
+// why: Bun ships no path-join primitive.
+import { join } from 'node:path';
+import type { Role } from '@ultimat3/core';
+import { logger, UltimateError } from '@ultimat3/core';
+import { sassCompilations, setSassCacheDir } from '@ultimat3/render/server';
+import { PREBUILT_COMMAND, PREBUILT_SASS_DIR } from './serve-prebuilt-paths';
+
+/**
+ * Points the Sass cache at the image's own entries, when the image has any. Before the app is
+ * imported, because importing a page IS compiling its stylesheet. An entry is keyed by the
+ * sheet's absolute path, which is why the store is written inside the image build: same `WORKDIR`,
+ * same paths. Answers whether there was a store to adopt.
+ */
+export function adoptPrebuiltStyles(root: string): boolean {
+  const dir = join(root, PREBUILT_SASS_DIR);
+  if (!existsSync(dir)) return false;
+  setSassCacheDir(dir);
+  return true;
+}
+
+/** What a role built at boot that the image build exists to have built once. */
+export interface BootBuilds {
+  /** Island chunks built by this boot, and the one sentence saying why the store was not served. */
+  readonly islands?: { readonly chunks: number; readonly reason: string };
+  /** Stylesheets this boot ran Sass for. */
+  readonly stylesheets: number;
+  readonly elapsedMs: number;
+}
+
+/**
+ * Logged, never thrown: a build at boot is correct and only slow, so the role serves what it
+ * would have served — it pays seconds of CPU and a compiler's worth of memory on every start.
+ */
+export class ImageNotPrebuiltError extends UltimateError {
+  constructor(input: { readonly role: Role } & BootBuilds) {
+    const islands = input.islands;
+    const built = [
+      ...(islands === undefined
+        ? []
+        : [`built ${String(islands.chunks)} island chunk(s) because ${islands.reason}`]),
+      ...(input.stylesheets === 0
+        ? []
+        : [`compiled ${String(input.stylesheets)} stylesheet(s) the image holds no result for`]),
+    ];
+    super({
+      code: 'X_IMAGE_NOT_PREBUILT',
+      cause: `the ${input.role} role ${built.join(' and ')}, ${String(input.elapsedMs)} ms into its boot — work this image repeats on every start of every replica`,
+      fix: `edit docker/Dockerfile: add RUN ${PREBUILT_COMMAND} after COPY . . in the runtime stage, then rebuild the image`,
+      meta: {
+        role: input.role,
+        islands: islands?.chunks ?? 0,
+        stylesheets: input.stylesheets,
+        elapsedMs: input.elapsedMs,
+      },
+    });
+  }
+}
+
+/** Starts counting what a boot compiles; the answer is what `reportBootBuilds` is handed. */
+export function watchBootBuilds(): (islands?: BootBuilds['islands']) => BootBuilds {
+  const started = Bun.nanoseconds();
+  const compiled = sassCompilations();
+  return (islands) => ({
+    ...(islands === undefined || islands.chunks === 0 ? {} : { islands }),
+    stylesheets: sassCompilations() - compiled,
+    elapsedMs: Math.round((Bun.nanoseconds() - started) / 1e6),
+  });
+}
+
+/** One `error` line when the boot built anything, and nothing when it built nothing. */
+export function reportBootBuilds(role: Role, builds: BootBuilds): boolean {
+  if (builds.islands === undefined && builds.stylesheets === 0) return false;
+  const error = new ImageNotPrebuiltError({ role, ...builds });
+  logger.error(error.format(), { code: error.code, ...error.meta });
+  return true;
+}

package/src/serve-web.ts

@@ -0,0 +1,164 @@
+// What only the web role serves: its islands, its documents and every route beside them. A file
+// of its own so the roles that render nothing never import it — `serve-boot.ts` loads it with
+// `await import()` for `ROLE=web` alone, and `serve-graph.test.ts` pins what every other role is
+// spared: render's server half, the PWA, SEO, MCP and island subsystems.
+
+import type { Route } from '@ultimat3/http';
+import { describeRoutes } from '@ultimat3/render';
+import { createIsrController } from '@ultimat3/render/server';
+import { apiMountRoutes, apiRoutes, pagePostRoutes } from './api-routes';
+import { loadSignInPath } from './app-auth';
+import { mountAppMcp } from './app-mcp';
+import { errorPageStyleSources } from './error-page-csp';
+import { islandRoutes } from './island-routes';
+import type { LoadedIslands } from './island-store';
+import { loadOrBuildIslands } from './island-store';
+import { loadNavigation, pageNavigation } from './page-navigation';
+import { loadSpeculation, pageSpeculation } from './page-speculation';
+import { pageSync } from './page-sync';
+import { loadPwaArtifacts } from './pwa-artifacts';
+import { adminMountRoutes } from './runtime-admin';
+import { assetRoutes } from './runtime-assets';
+import { appRoutes } from './runtime-render';
+import type { RunningServices } from './runtime-services';
+import { servedStorage, storageRoutes } from './runtime-storage';
+import { seoRoutes } from './seo-routes';
+import type { ServeOptions } from './serve-types';
+import { loadSiteSettings, publicOrigin } from './site-config';
+import { styleBundle } from './style-bundle';
+import { styleRoutes } from './style-routes';
+import { serviceWorkerArtifacts } from './sw-artifacts';
+import { serviceWorkerRoutes } from './sw-routes';
+import { loadThemeMode, themeBoot } from './theme-boot';
+
+/** Everything `startRoles` is handed that only a process serving documents has. */
+export interface WebSurface {
+  readonly routes: readonly Route[];
+  /** The theme boot and the speculation rules: the two inline bodies every document may carry. */
+  readonly inlineScripts: readonly string[];
+  /** The app's own error pages' `<style>` bodies, which the enforced policy must admit. */
+  readonly inlineStyles: readonly string[];
+  /** Where a browser that opened a guarded page is sent — the declaration `x dev` reads. */
+  readonly signInPath: string | null;
+  /** Present when this boot built the islands itself: how many chunks, and why not the store. */
+  readonly islandsBuilt?: LoadedIslands['built'];
+}
+
+export async function webSurface(
+  options: ServeOptions,
+  runtime: RunningServices,
+  buildId: string,
+): Promise<WebSurface> {
+  // Read from the store the image build wrote and VERIFIED against this app and this runtime
+  // (`island-store.ts`); built here only when there is no store to trust, which is correct and
+  // slower — the reason travels back to the boot, which reports it.
+  const { bundle: islands, built: islandsBuilt } = await loadOrBuildIslands(options.root);
+  // The same two strings `x dev` resolves, from the same reader: a `<link rel="manifest">` served
+  // on a laptop and absent in the image is exactly the dev/prod difference this file exists to
+  // prevent, and it is the one an operator cannot see without installing the app.
+  const pwa = await loadPwaArtifacts(options.root);
+  const theme = themeBoot(await loadThemeMode(options.root));
+  // `site.origin` and `seo.robots.disallow`: the absolute URLs every document and the sitemap carry.
+  const site = await loadSiteSettings(options.root);
+  const origin = publicOrigin(options.env, site);
+  // The page's sync target and its scripts — the same call `x dev` makes, so the two cannot differ.
+  // Before the service worker, which precaches those scripts.
+  const sync = await pageSync(options.root, options.env, buildId, runtime.realtime);
+  // The client router, when a surface opted in (`navigation.client`) — the same call in both boots.
+  const declared = await loadNavigation(options.root);
+  const navigation = await pageNavigation(options.root, declared, buildId);
+  // The browser's own prefetch, for the documents that carry no router (`navigation.speculation`).
+  const speculation = pageSpeculation({
+    config: await loadSpeculation(options.root),
+    client: declared.surfaces,
+  });
+  // The worker, from the SAME route table this process is about to serve — `describeRoutes()` is
+  // the one projection `x.manifest.json`, `/_x`, the sitemap and `sw.js` are all built from, so a
+  // route added here cannot be missing from the precache manifest.
+  const serviceWorker =
+    pwa === undefined
+      ? undefined
+      : serviceWorkerArtifacts({
+          pwa,
+          buildId,
+          routes: describeRoutes(),
+          islands,
+          styles: styleBundle(),
+          scripts: [
+            ...sync.scripts,
+            ...(navigation.script === undefined ? [] : [navigation.script]),
+          ],
+        });
+  // The app's own MCP endpoint, through the same call `x dev` makes — see `app-mcp.ts`.
+  const mcpMount = await mountAppMcp(options.root);
+  // The app's own disks when it declared any (`defineStorage` in an app module), else this boot's.
+  const served = servedStorage(runtime.storage);
+  const routes: readonly Route[] = [
+    ...apiRoutes(),
+    // The bearer doors onto a cut of the same routes (`defineApi({ http: { mounts } })`), counted
+    // on the store this boot's limiter uses, so one token's allowance is one number fleet-wide.
+    ...apiMountRoutes(options.runtime?.rateLimitStore ?? runtime.rateLimitStore),
+    ...mcpMount.routes,
+    // The app's own plain routes (`apps/<app>/runtime.ts` `routes`), before any page can shadow one.
+    ...(options.runtime?.routes ?? []),
+    ...(serviceWorker === undefined ? [] : serviceWorkerRoutes(serviceWorker)),
+    ...assetRoutes({
+      root: options.root,
+      storage: served,
+      ...(options.runtime?.images === undefined ? {} : { images: options.runtime.images }),
+      ...(pwa === undefined ? {} : { pwa }),
+    }),
+    ...storageRoutes({ storage: served }),
+    ...islandRoutes(() => islands),
+    // The surface stylesheets the documents link. Built from the registry the `loadApp` above
+    // filled, so this process serves exactly the CSS it renders against.
+    ...styleRoutes(() => styleBundle()),
+    // `robots.txt` and `sitemap.xml`, the same two files the static export writes (`site-seo.ts`).
+    ...seoRoutes({ env: options.env, site, root: options.root }),
+    // The page's one socket: its worker script, served beside the islands for their reason.
+    ...sync.routes,
+    ...navigation.routes,
+    // A page's `POST`, bound to an action (`defineRoute({ post })`) — beside the page's `GET`.
+    ...pagePostRoutes(),
+    // The app's generated admin, when it declared one (`defineAdmin`): every screen under its base
+    // path, served through the same document builder as the pages below. Nothing for an app with
+    // no admin — the registry is asked, the package is not imported.
+    ...adminMountRoutes({
+      buildId: buildId,
+      themeHead: theme.head,
+      ...(origin === undefined ? {} : { origin }),
+    }),
+    ...appRoutes({
+      buildId,
+      resolveIsland: (file) => islands.resolverFor(file),
+      ...(sync.head === undefined ? {} : { sync: sync.head }),
+      persisted: sync.persisted,
+      ...(navigation.head === undefined ? {} : { navigation: navigation.head }),
+      themeHead: theme.head,
+      ...(speculation === undefined ? {} : { speculationHead: speculation.head }),
+      // A `static` page is the same bytes for every request of this process: rendered once.
+      memoStatic: true,
+      ...(origin === undefined ? {} : { origin }),
+      ...(pwa === undefined
+        ? {}
+        : { pwaHead: (locale: string) => pwa.headFor(locale) + (serviceWorker?.head ?? '') }),
+      // Only when a store was supplied. `createIsrController` defaults to a per-process memory
+      // store, so twelve replicas hold twelve of them and a purge tag regenerates one twelfth of
+      // the fleet while the other eleven keep serving the page it just invalidated.
+      ...(options.runtime?.isrStore === undefined
+        ? {}
+        : { isr: createIsrController({ buildId, store: options.runtime.isrStore }) }),
+    }),
+  ];
+  return {
+    routes,
+    inlineScripts: [theme.cspSource, ...(speculation === undefined ? [] : [speculation.cspSource])],
+    // The enforced policy this process sends must admit the app's own error pages' `<style>` and
+    // the theme boot the documents carry; `x dev` is report-only, so only here was it a blank page.
+    inlineStyles: await errorPageStyleSources(options.root),
+    // Same declaration `x dev` reads. Without it a container answers a browser that opened a
+    // guarded page with the problem document, rendered as raw JSON in the viewport.
+    signInPath: await loadSignInPath(options.root),
+    ...(islandsBuilt === undefined ? {} : { islandsBuilt }),
+  };
+}

package/src/serve.ts

@@ -13,8 +13,6 @@ import { startMetricsEndpoint } from './metrics-endpoint';
 import { readMigrations } from './migrations';
 import { resolveServices } from './runtime-bindings';
 import { startQueue } from './runtime-queue';
-import { startServices } from './runtime-services';
-import { bootRoles } from './serve-boot';
 import { containerBinding, metricsPortFor, portFromEnv, roleFromEnv } from './serve-env';
 import type { MigratedApp, ServedApp, ServeOptions, StartedApp } from './serve-types';
 
@@ -144,17 +142,16 @@ export async function serveApp(input: ServeOptions): Promise<ServedApp> {
   const metrics = startMetricsEndpoint({
     port: metricsPortFor(options.env, port, options.metricsPort),
     hostname: containerBinding(options.env, options.hostname).hostname,
+    role,
   });
   // Everything acquired from here down, in order, so a throw anywhere below gives it all back.
   const acquired: (() => void | Promise<void>)[] = [() => metrics.stop()];
   try {
-    const runtime = await startServices(
-      resolveServices(options.root, options.env),
-      options.env,
-      options.runtime,
-    );
-    acquired.push(() => runtime.stop());
-    return await bootRoles({ options, role, runtime, acquired, metrics });
+    // Behind `await import()`: `ROLE=migrate` runs in this module too, applies SQL files and
+    // exits, and the services and the role boot are ~240 modules it never calls
+    // (`serve-graph.test.ts` pins the count each role is left with).
+    const { bootServing } = await import('./serve-boot');
+    return await bootServing({ options, role, acquired, metrics });
   } catch (error) {
     await releaseBoot(acquired);
     throw error;

package/src/server-barrels.ts

@@ -0,0 +1,54 @@
+// A package barrel a browser must not import, and the entry it imports instead. `@ultimat3/entity`'s
+// barrel reaches the SQL renderer and `@ultimat3/db` — about a megabyte in an island — while
+// `@ultimat3/entity/record` is the browser half. DERIVED from each manifest's `exports`: a package
+// that publishes a `./record`, `./browser` or `./client` subpath has said its barrel is the server
+// half, so a new browser entry enters this rule by being published, never by being listed here.
+
+import { stripComments } from '@ultimat3/core';
+import { lineIndex } from './ts-scan';
+
+/** The subpath names that declare "this is the browser entry of the package". */
+export const BROWSER_ENTRY_SUBPATHS: ReadonlySet<string> = new Set(['record', 'browser', 'client']);
+
+/** Barrel specifier → the browser entry that replaces it, read off the published specifiers. */
+export function serverBarrels(specifiers: Iterable<string>): ReadonlyMap<string, string> {
+  const barrels = new Map<string, string>();
+  for (const spec of specifiers) {
+    const match = /^(@[\w-]+\/[\w-]+)\/([\w-]+)$/.exec(spec);
+    if (match?.[1] === undefined || !BROWSER_ENTRY_SUBPATHS.has(match[2] ?? '')) continue;
+    barrels.set(match[1], spec);
+  }
+  return barrels;
+}
+
+export interface BarrelImport {
+  readonly line: number;
+  readonly barrel: string;
+  readonly entry: string;
+}
+
+/** `import` / `export … from` / `import()` of a VALUE from the barrel. `import type` runs nothing. */
+const IMPORTS =
+  /\b(?:import|export)\s+(?!type\s)[^;'"]*?\bfrom\s*(['"])([^'"]+)\1|\bimport\s*\(\s*(['"])([^'"]+)\3\s*\)/g;
+
+export function barrelImports(
+  source: string,
+  barrels: ReadonlyMap<string, string>,
+): readonly BarrelImport[] {
+  // Most files import no barrel at all; say so before paying for a comment-stripped copy.
+  if (![...barrels.keys()].some((barrel) => source.includes(barrel))) return [];
+  const code = stripComments(source);
+  const lineAt = lineIndex(code);
+  const found: BarrelImport[] = [];
+  for (const match of code.matchAll(IMPORTS)) {
+    const spec = match[2] ?? match[4] ?? '';
+    const entry = barrels.get(spec);
+    if (entry === undefined) continue;
+    // `import { type A, type B } from …` binds nothing at runtime either.
+    const clause = /\{([^}]*)\}/.exec(match[0])?.[1];
+    const typesOnly = clause?.split(',').every((part) => /^\s*(?:type\s|$)/.test(part));
+    if (typesOnly === true) continue;
+    found.push({ line: lineAt(match.index), barrel: spec, entry });
+  }
+  return found;
+}