@ultimat3/cli 22.15.0 → 24.0.0

package/src/schema-drift.ts

@@ -15,10 +15,15 @@ import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { EntityDescriptionLike, UnrenderedDeclaration } from '@ultimat3/db';
-import { declaredSchema, snapshotOf, unrenderedOf } from '@ultimat3/db';
+import { declaredSchema, shellInertIdentifier, snapshotOf, unrenderedOf } from '@ultimat3/db';
 import { describeEntities } from '@ultimat3/entity';
 import { loadApp } from './app-load';
 import { checkSourceDrift, DB_PACKAGE } from './drift';
+import {
+  appReplicaIdentity,
+  type ReplicaIdentityWanted,
+  wantedReplicaIdentity,
+} from './drift-replica-identity';
 import { MIGRATIONS_DIR, readMigrations } from './migrations';
 import type { Finding } from './output';
 import { diffDeclaredSchema, type SchemaDifference } from './schema-diff';
@@ -50,10 +55,17 @@ const appEntities: DeclaredEntities = async (root) => {
  * silently and the result is green. In that state the unrendered entry's own `fix:` is the
  * instruction: `@ultimat3/db` owns that wording, and a second one here would drift from it.
  */
+interface Repair {
+  /** One runnable command or one edit — never a second option behind a shell comment. */
+  readonly fix: string;
+  /** Why this fix and not the obvious one, appended to the cause where the reader sees it. */
+  readonly why?: string;
+}
+
 function repairFix(
   unrendered: readonly UnrenderedDeclaration[],
   difference: SchemaDifference,
-): string {
+): Repair {
   // The entry ABOUT this difference first, then any entry at all. Reading `unrendered[0]`
   // unconditionally meant that in any app carrying an unrendered DEFAULT, every difference —
   // a dropped CHECK included — was answered with the default's edit, which is an instruction for
@@ -62,7 +74,7 @@ function repairFix(
     (entry) => entry.table === difference.table && entry.name === difference.name,
   );
   // The entry ABOUT this difference carries the edit that repairs it, so it is the whole answer.
-  if (named !== undefined) return named.fix;
+  if (named !== undefined) return { fix: named.fix };
   // Otherwise `x db gen` is still unsafe — it would drop what the other entries name — but the
   // reader must NOT be handed a different declaration's edit as the instruction for this one.
   // Reading `unrendered[0]` did exactly that: a column default and an index each got
@@ -72,16 +84,26 @@ function repairFix(
   // app — not only for the one the entry names.
   const blocker = unrendered[0];
   if (blocker !== undefined) {
-    return `${blocker.fix}   # ${blocker.table}.${blocker.name} reaches no SQL, so regenerating would drop it; repair that before recording ${difference.name}`;
+    return {
+      fix: blocker.fix,
+      why: `${blocker.table}.${blocker.name} reaches no SQL, so regenerating would drop it — repair that before recording ${difference.name}`,
+    };
   }
   // "record", not "add": one finding covers a declaration the migrations never carried AND one they
-  // carry differently, so `add` would be a wrong migration name for half of them. `undeclared` gets
-  // both branches, in the order they are safe — regenerating emits the DROP, and the declaration
-  // may have been LOST rather than removed, which is the whole reason this direction is its own
-  // finding.
-  return difference.direction === 'unmigrated'
-    ? `x db gen "record ${difference.name}"`
-    : `x db gen "drop ${difference.name}"   # or re-declare ${difference.name} on the entity`;
+  // carry differently, so `add` would be a wrong migration name for half of them. `undeclared` runs
+  // the DROP, and the other branch — the declaration may have been LOST rather than removed, which
+  // is the whole reason this direction is its own finding — rides in the cause: a `fix:` is one
+  // command, and a `# or …` after it was a shell comment nobody's paste would run.
+  if (difference.direction === 'unmigrated') return { fix: `x db gen "record ${difference.name}"` };
+  // The name was read off a sidecar on disk and lands inside double quotes, where `$(…)` and a
+  // backtick still run: one the shell would act on is named in the cause only, never the command.
+  const inert = shellInertIdentifier(difference.name) !== null;
+  return {
+    fix: inert
+      ? `x db gen "drop ${difference.name}"`
+      : 'x db gen "drop what the entities no longer declare"',
+    why: `if ${difference.name} was lost rather than removed, re-declare it on the entity instead — this command drops it`,
+  };
 }
 
 /**
@@ -95,8 +117,10 @@ export const schemaDifferenceCause = (difference: SchemaDifference): string =>
     ? `table "${difference.table}" ${difference.detail}`
     : `${difference.part} "${difference.name}" on table "${difference.table}" ${difference.detail}`;
 
-function findingFor(difference: SchemaDifference, fix: string): Finding {
-  const cause = schemaDifferenceCause(difference);
+function findingFor(difference: SchemaDifference, repair: Repair): Finding {
+  const { fix } = repair;
+  const stated = schemaDifferenceCause(difference);
+  const cause = repair.why === undefined ? stated : `${stated} — ${repair.why}`;
   return difference.direction === 'unmigrated'
     ? { code: 'X_DB_SCHEMA_UNMIGRATED', cause, fix, docs: ERROR_DOCS_URL, at: MIGRATIONS_DIR }
     : { code: 'X_DB_SCHEMA_UNDECLARED', cause, fix, docs: ERROR_DOCS_URL, at: MIGRATIONS_DIR };
@@ -114,6 +138,7 @@ function findingFor(difference: SchemaDifference, fix: string): Finding {
 export async function checkSnapshotDrift(
   root: string,
   declared: DeclaredEntities = appEntities,
+  identity: ReplicaIdentityWanted = appReplicaIdentity,
 ): Promise<readonly Finding[]> {
   if (!existsSync(join(root, DB_PACKAGE))) return [];
   const entities = await declared(root);
@@ -122,7 +147,11 @@ export async function checkSnapshotDrift(
   if (migrations.length === 0) return [];
   const recorded = declaredSchema(migrations);
   if (recorded === undefined) return [];
-  const differences = diffDeclaredSchema(snapshotOf(entities), recorded);
+  // Read only over a WHOLE registry (`entities` is `undefined` otherwise), the rule `x db gen`
+  // states for the same call: a short one makes every subscribed name in the missing module a typo.
+  const wanted = wantedReplicaIdentity(identity, new Set(entities.map((entity) => entity.table)));
+  if ('finding' in wanted) return [wanted.finding];
+  const differences = diffDeclaredSchema(snapshotOf(entities, wanted.tables), recorded);
   if (differences.length === 0) return [];
   // `recorded` and not the entities alone: whether an `assert` is a LOSS depends on whether a
   // migration recorded a CHECK for it, which only the sidecar knows.
@@ -145,8 +174,9 @@ export async function checkMigrationDrift(
   root: string,
   declared: DeclaredEntities = appEntities,
   hashDrift: (root: string) => Promise<readonly Finding[]> = checkSourceDrift,
+  identity: ReplicaIdentityWanted = appReplicaIdentity,
 ): Promise<readonly Finding[]> {
-  const snapshot = await checkSnapshotDrift(root, declared);
+  const snapshot = await checkSnapshotDrift(root, declared, identity);
   if (snapshot.length > 0) return snapshot;
   return hashDrift(root);
 }

package/src/schema-dump-drift.ts

@@ -0,0 +1,64 @@
+// The `drift` step's fourth rail: is the committed schema dump what the migrations produce, and
+// does a database loaded from it come back the same? The other three rails read files and open
+// nothing; this one replays the migrations on a scratch embedded database, because "what the
+// migrations produce" is a fact only a database can state.
+
+// why: Bun has no directory probe — `Bun.file().exists()` answers about a file.
+import { existsSync } from 'node:fs';
+// why: Bun ships no path joiner.
+import { join } from 'node:path';
+import { ERROR_DOCS_URL } from '@ultimat3/core';
+import type { Migration } from '@ultimat3/db';
+import type { SchemaDumpDifference } from '@ultimat3/db/schema-dump';
+import { compareSchemaDump, schemaDumpDrift } from '@ultimat3/db/schema-dump';
+import {
+  hasSchemaDump,
+  type ReplayedSchema,
+  readSchemaDump,
+  replayFor,
+  SCHEMA_DUMP_DIR,
+} from './db-schema-dump';
+import { dumpNeverGenerated, replayFailure } from './db-schema-refresh';
+import { DB_PACKAGE } from './drift';
+import { readMigrations } from './migrations';
+import type { Finding } from './output';
+import { findingFrom } from './output';
+
+/** Injected so this module's rules are testable without booting a database per case. */
+export type SchemaReplay = (migrations: readonly Migration[]) => Promise<ReplayedSchema>;
+
+const findingFor = (difference: SchemaDumpDifference): Finding => ({
+  ...findingFrom(schemaDumpDrift(difference)),
+  docs: ERROR_DOCS_URL,
+  at: `${SCHEMA_DUMP_DIR}/${difference.path}`,
+});
+
+/**
+ * Empty result = the dump is the migrations' own.
+ *
+ * An app with no migration and no dump owes none — zero recorded against zero dumped is agreement,
+ * the rule `checkSourceDrift` states for entities, and what keeps `x new --no-example` green. From
+ * the first migration on the dump is owed: a missing directory is one finding naming the command
+ * that writes it, reported without booting a database.
+ *
+ * Both halves are reported together. A stale file and a dump that does not round-trip are two
+ * repairs, and hiding the second behind the first hands out `x db gen` for a dump regenerating
+ * cannot fix.
+ */
+export async function checkSchemaDump(
+  root: string,
+  env: Readonly<Record<string, string | undefined>> = Bun.env,
+  replay: SchemaReplay = replayFor(root, env, true),
+): Promise<readonly Finding[]> {
+  if (!existsSync(join(root, DB_PACKAGE))) return [];
+  const migrations = await readMigrations(root);
+  if (!hasSchemaDump(root)) return migrations.length === 0 ? [] : [dumpNeverGenerated()];
+  const committed = await readSchemaDump(root);
+  let replayed: ReplayedSchema;
+  try {
+    replayed = await replay(migrations);
+  } catch (error) {
+    return [replayFailure(error)];
+  }
+  return [...compareSchemaDump(committed, replayed.files), ...replayed.reload].map(findingFor);
+}

package/src/seo-routes.ts

@@ -1,11 +1,14 @@
-// `GET /robots.txt` and `GET /sitemap.xml` from a running web role — the files the static export
-// writes, answered by the process for a deploy that serves its pages from a container. Mounted by
-// `x dev` and `runRole` alike, before the app's pages, for `style-routes.ts`' reason.
+// `GET /robots.txt`, `GET /sitemap.xml` and its parts (`/sitemaps/<n>.xml`) from a running web
+// role — the files the static export writes, for a deploy that serves its pages from a container.
+// Mounted by `x dev` and `runRole` alike, before the app's pages, for `style-routes.ts`' reason.
 
 import { DEFAULT_ENVIRONMENT, type Environment, tryResolveEnvironment } from '@ultimat3/core';
 import type { Route, UltimateRequest } from '@ultimat3/http';
-import { applyCacheHeaders } from '@ultimat3/http';
+import { applyCacheHeaders, json, NO_STORE } from '@ultimat3/http';
+import { SITEMAP_PARTS_DIR } from '@ultimat3/seo';
+import { quoteArg } from './shell-quote';
 import { NO_SITE_SETTINGS, publicOrigin, type SiteSettings } from './site-config';
+import type { SiteSeo } from './site-seo';
 import { ROBOTS_PATH, SITEMAP_PATH, siteSeo } from './site-seo';
 
 export interface SeoRoutesOptions {
@@ -26,22 +29,57 @@ function originOf(options: SeoRoutesOptions, request: UltimateRequest): string {
 }
 
 /**
- * Per request, never cached across one: `prerender()` may enumerate rows that change, and a
- * crawler asks for these a handful of times a day. An hour of shared cache is what a CDN keeps.
+ * An hour of shared cache is what a CDN keeps of either file, and what this process keeps of the
+ * answer behind both. `prerender()` may enumerate rows that change, so the memo is never longer
+ * than the response's own `max-age` — a crawler that bypasses the CDN sees what one behind it
+ * would. Before it, every `/robots.txt` hit recomputed the whole sitemap, each dynamic route's
+ * `prerender()` included.
  */
 const SEO_CACHE = { mode: 'public', maxAgeSeconds: 3600 } as const;
 
+/**
+ * Origins remembered at once. With no declared origin the request's own is the key, and a `Host`
+ * header is the caller's to choose — so the memo is bounded, oldest out first.
+ */
+const SEO_MEMO_ORIGINS = 8;
+
+interface Memo {
+  readonly at: number;
+  readonly answer: Promise<SiteSeo>;
+}
+
 export function seoRoutes(options: SeoRoutesOptions): readonly Route[] {
   const environment: Environment =
     tryResolveEnvironment({ env: options.env }) ?? DEFAULT_ENVIRONMENT;
-  const answer = async (request: UltimateRequest) =>
-    await siteSeo({
-      baseUrl: originOf(options, request),
+  const compute = (baseUrl: string): Promise<SiteSeo> =>
+    siteSeo({
+      baseUrl,
       environment,
       disallow: options.site?.disallow ?? [],
       ...(options.site === undefined ? {} : { sitemap: options.site.sitemap }),
       ...(options.root === undefined ? {} : { root: options.root }),
     });
+  // Single-flight per origin: concurrent requests share the one computation in progress. A failed
+  // one is dropped, so the next request asks again rather than serving the failure for an hour.
+  const memo = new Map<string, Memo>();
+  const answer = (request: UltimateRequest): Promise<SiteSeo> => {
+    const origin = originOf(options, request);
+    const now = Date.now();
+    const kept = memo.get(origin);
+    if (kept !== undefined && now - kept.at < SEO_CACHE.maxAgeSeconds * 1000) return kept.answer;
+    memo.delete(origin);
+    if (memo.size >= SEO_MEMO_ORIGINS) {
+      const oldest = memo.keys().next().value;
+      if (oldest !== undefined) memo.delete(oldest);
+    }
+    const computed = compute(origin);
+    memo.set(origin, { at: now, answer: computed });
+    // Voided: the request awaits `computed` itself and reports its failure; this branch only forgets it.
+    void computed.catch(() => {
+      if (memo.get(origin)?.answer === computed) memo.delete(origin);
+    });
+    return computed;
+  };
 
   return [
     {
@@ -69,5 +107,38 @@ export function seoRoutes(options: SeoRoutesOptions): readonly Route[] {
           SEO_CACHE,
         ),
     },
+    {
+      method: 'GET',
+      path: `${SITEMAP_PARTS_DIR}/:file`,
+      meta: { name: 'seo.sitemapPart', auth: 'public', tags: ['seo'] },
+      // A part of a split sitemap, from the same answer the index came from — so a part the index
+      // names always exists here, and the static export writes the same paths.
+      handler: async (request: UltimateRequest): Promise<Response> => {
+        const seo = await answer(request);
+        const part = seo.sitemaps.find((file) => file.path === request.pathname);
+        if (part !== undefined && part.path !== SITEMAP_PATH) {
+          return applyCacheHeaders(
+            new Response(part.xml, {
+              headers: { 'content-type': 'application/xml; charset=utf-8' },
+            }),
+            SEO_CACHE,
+          );
+        }
+        const index = new URL(SITEMAP_PATH, originOf(options, request)).href;
+        const missing = json(
+          {
+            ok: false,
+            error: {
+              code: 'X_ROUTE_NOT_FOUND',
+              cause: `${request.pathname} is no part of this site's sitemap: the index names ${String(Math.max(seo.sitemaps.length - 1, 0))} part(s)`,
+              fix: `curl -sS ${quoteArg(index)}`,
+            },
+          },
+          { status: 404 },
+        );
+        // `no-store`: the part may exist once the site grows, and a cached miss would hide it.
+        return applyCacheHeaders(missing, NO_STORE);
+      },
+    },
   ];
 }

package/src/serve-boot.ts

@@ -1,46 +1,89 @@
-// 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 type { DrainConfig, LifecycleOptions, Role } from '@ultimat3/core';
+import { configureLifecycle, logger } from '@ultimat3/core';
 import type { MetricsEndpoint } from './metrics-endpoint';
 import { startOtlpExport } from './otlp-export';
-import { loadNavigation, pageNavigation } from './page-navigation';
-import { loadSpeculation, pageSpeculation } from './page-speculation';
-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 { warnIfIdempotencyProcessScoped } from './runtime-idempotency-scope';
+import { warnUnsealedMfaSecrets } from './runtime-mfa-warning';
 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;
+}
+
+/** The roles that open an HTTP listener something routes to — the only ones a readiness grace serves. */
+const LISTENING_ROLES: readonly Role[] = ['web', 'sync'];
+
+/**
+ * `app.config.ts`'s `drain`, applied to the WHOLE process rather than only to the web server that
+ * `createServer` hands it to. A role nothing routes to gets no readiness grace at all: the grace
+ * holds `/readyz` at 503 with the listener open so the endpoints catch up, and a worker has neither
+ * — it only went on claiming jobs for those seconds, then aborted them at the drain (s1-con #7).
+ */
+export function lifecycleForRole(
+  role: Role,
+  drain: Partial<DrainConfig> | undefined,
+): LifecycleOptions {
+  if (!LISTENING_ROLES.includes(role)) return { readinessGraceMs: 0 };
+  return drain?.readinessGraceMs === undefined ? {} : { readinessGraceMs: drain.readinessGraceMs };
+}
+
+/**
+ * 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 services = resolveServices(options.root, options.env);
+  // A serving role on a real database runs no DDL: `ROLE=migrate` applied this build's framework
+  // tables first, and this boot only verifies the stamp it left (`framework-schema-apply.ts`).
+  // The embedded database has no migrate step to have run, so it applies its own.
+  const schema = services.db.mode === 'external' ? 'verify' : 'apply';
+  const runtime = await startServices(services, options.env, options.runtime, schema);
+  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;
@@ -49,18 +92,21 @@ 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 });
+  }
+  // After the app's modules: an app swaps the store at import time, after `startServices`.
+  warnIfIdempotencyProcessScoped();
+  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);
@@ -72,14 +118,26 @@ 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;
+  if (web !== undefined) acquired.push(web.release);
+  // The web role alone — it is where a second factor is asked for — and once per pod boot.
+  if (role === 'web') await warnUnsealedMfaSecrets(runtime.db);
+  // 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
   // still wins — that is the deploy talking.
   const metricsPort = metricsPortFor(options.env, port, options.metricsPort);
   const drain = await loadDrainConfig(options.root);
+  configureLifecycle(lifecycleForRole(role, drain));
   // Process-wide, so every role's `/readyz` — web, sync, worker — answers in the declared mode.
   const health = await loadHealthConfig(options.root);
   if (health?.readiness !== undefined) configureLifecycle({ readiness: health.readiness });
@@ -93,13 +151,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.inlineScripts,
+    // 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,
@@ -122,6 +182,8 @@ export async function bootRoles(boot: {
     runtime,
     async stop() {
       await running.stop();
+      // After the server drained: a bust landing mid-drain still marks the pages it is serving.
+      web?.release();
       await runtime.stop();
       // Last: the exporters outlive the roles they were recording, so the drain's own spans and
       // the final counter snapshot still have somewhere to go.
@@ -129,109 +191,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 inlineScripts: readonly 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 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(),
-    ...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,
-    // The theme boot and the speculation rules: the two inline bodies every document may carry.
-    inlineScripts: [theme.cspSource, ...(speculation === undefined ? [] : [speculation.cspSource])],
-  };
-}