@ultimat3/cli 23.0.0 → 25.0.0

package/src/runtime-render.ts

@@ -1,46 +1,31 @@
-// Projecting the route table onto HTTP routes `x dev` can serve. Every mode goes through
+// Projecting the route table onto HTTP routes both boots serve. Every mode goes through
 // `@ultimat3/render`'s own function for that mode — the CLI picks the mode and supplies the
-// document, it never decides what a mode means or what headers it earns.
-//
-// The document is head + the route's own component, rendered by `@ultimat3/render`'s server JSX
-// writer, with the surface's compiled CSS LINKED — one content-hashed file per surface
-// (`style-bundle.ts`), served `immutable`.
-//
-// It was inlined until 2026-09-06, on the argument that a `site/` page is a 0kb-JS artifact a CDN
-// serves as one file and a link would add a round trip. The round trip is real and it is paid
-// once: measured against ai-maxxing, every `app/` document carried the SAME 156,738-byte `<style>`
-// block — 92% of the dashboard document — inside a response the pipeline sends
-// `Cache-Control: private, no-store`, so the trip that argument saved was re-paid in full on every
-// navigation, with a re-parse on top. The static export writes the file (`writeStyles`), so the
-// "second file" cost is one `Bun.write`.
+// document (head + the route's component, the surface's CSS LINKED, `style-bundle.ts`), it never
+// decides what a mode means or what headers it earns.
 
-// why: Bun ships no path API; an island's file is its route file's directory joined to its `src`.
-import { posix } from 'node:path';
 import { actionPathStyle } from '@ultimat3/action';
 import { clientScopeOf } from '@ultimat3/auth';
-import type { Ctx } from '@ultimat3/core';
-import { CLIENT_SCOPE_HEADER } from '@ultimat3/core';
+import type { Actor, Ctx } from '@ultimat3/core';
+import { CLIENT_SCOPE_HEADER, singleFlight } from '@ultimat3/core';
 import type {
   RouteMeta as HttpRouteMeta,
   RedirectIntent,
+  RequestContext,
   Route,
   RouteParams,
+  UltimateRequest,
 } from '@ultimat3/http';
 import { asCtx, html, NO_STORE, redirect, stream, takeRedirect } from '@ultimat3/http';
-import { currentLocale, localeConfig } from '@ultimat3/i18n';
+import { currentLocale } from '@ultimat3/i18n';
 import type { IslandCollector, RenderResult, RouteData, RouteEntry } from '@ultimat3/render';
 import {
-  clientBootTags,
   clientPathStyleTags,
   clientPersistTags,
   clientScopeTag,
   clientSyncTags,
-  createIslandCollector,
   documentCarriesScope,
   headFromMeta,
   hydrateRuntime,
-  islandModuleId,
-  islandModuleIds,
   metaContextFor,
   renderHead,
   routeDataFor,
@@ -52,8 +37,6 @@ import {
 import type { IsrController } from '@ultimat3/render/server';
 import {
   contentHash,
-  createIsrController,
-  isrKey,
   ROOT_ELEMENT_ID,
   renderComponent,
   renderSsr,
@@ -62,13 +45,15 @@ import {
   streamResult,
 } from '@ultimat3/render/server';
 import type { DocumentOptions } from './document-options';
-import { realtimeIslandFiles } from './island-realtime';
 import {
   type NavigationDocumentHead,
   navigationMetaOf,
   navigationTagsOf,
   principalRelocation,
 } from './page-navigation';
+import { bootScript, collectorFor } from './route-islands';
+import { attachedIsr } from './runtime-isr';
+import { isrOutcome } from './runtime-isr-outcome';
 import type { StaticResult } from './static-document';
 import { createStaticMemo, staticMemoKey, staticResponse } from './static-document';
 import { styleBundle } from './style-bundle';
@@ -77,7 +62,11 @@ export type { DocumentOptions, IslandResolver } from './document-options';
 
 export interface DevRenderOptions extends DocumentOptions {
   readonly buildId: string;
-  /** Injected so a test can drive the ISR store without a timer. */
+  /**
+   * The boot's own controller, attached and released by it (`runtime-isr.ts`). Omitted, one is
+   * built AND attached here, never released — a caller with no stop list (a contract test) still
+   * gets pages a tag bust reaches; the revalidator slot is the latest attach's.
+   */
   readonly isr?: IsrController;
   /**
    * Keep each `static` document after its first render (`static-document.ts`). The container sets
@@ -124,9 +113,11 @@ const headFor = async (
         seoRenderers({
           path: url.pathname,
           baseUrl: options.origin ?? url.origin,
+          // The default is the cluster's own head (`alternates` is default-first by contract), so
+          // `x-default` comes from the list the hreflang tags do — never a second locale read.
           localization: {
             locale: meta.locale,
-            defaultLocale: localeConfig().fallback,
+            defaultLocale: meta.alternates[0]?.locale ?? meta.locale,
             alternates: meta.alternates,
           },
         }),
@@ -156,7 +147,8 @@ const headFor = async (
 
 /**
  * `<link rel="stylesheet">` for the surface's own stylesheets, or nothing at all when the surface
- * imports none.
+ * imports none. Inlined until 2026-09-06: every `app/` document of ai-maxxing then carried the same
+ * 156,738-byte `<style>` (92% of it) under `no-store`, re-paid on every navigation.
  *
  * In `<head>`, which is what keeps this a swap and not a regression: a `<link rel="stylesheet">`
  * there is render-blocking in every browser, exactly as the inline block was, so there is no
@@ -174,6 +166,10 @@ const styleTag = (entry: RouteEntry): string => {
   return href === undefined ? '' : `<link rel="stylesheet" href="${href}">`;
 };
 
+/** The surface stylesheet, then the app's brand — the order that lets the brand win the cascade. */
+const stylesFor = (entry: RouteEntry, options: DocumentOptions): string =>
+  styleTag(entry) + (options.brandHead ?? '');
+
 /**
  * The route's rendered body, inside the hydration root. Every mode goes through here — an empty
  * root is what a module exporting no component renders, and nothing else: `spa` was the one mode
@@ -205,46 +201,6 @@ export async function routeBody(
   return `<div id="${ROOT_ELEMENT_ID}">${html}</div>`;
 }
 
-/**
- * One collector per RENDER, never module-global: two requests render different params, and a
- * shared collector would bill one page for the other's islands. `hydrate` comes off the route, so
- * an island never declares its own timing, and `resolve` is the build's — identity when nothing
- * built any, which fails at the first island by name rather than emitting an unusable entry.
- */
-/**
- * Realtime's page boot, as one deferred script — or nothing. Two conditions, both exact: the
- * document carries a principal scope (restoring persisted records and replaying queued writes are
- * per principal; a shareable document has neither), AND one of the islands this render emitted
- * reaches `@ultimat3/realtime` (a page whose islands never touch a record has nothing to restore
- * into and no write to replay). After the body, because which islands rendered is a fact the walk
- * just recorded; still before the hydration runtime, so it runs first among the deferred scripts.
- */
-function bootScript(
-  entry: RouteEntry,
-  islands: IslandCollector,
-  options: DocumentOptions,
-  scope: string | undefined,
-): string {
-  if (scope === undefined || options.sync === undefined) return '';
-  const rendered = new Set(islandModuleIds(islands.directives));
-  if (rendered.size === 0) return '';
-  // An island's module id is derived from its `src`, written relative to the page that renders it:
-  // each realtime island file, spelled from THIS page, is the id its directive would carry.
-  const pageDir = posix.dirname(entry.file);
-  const reaches = [...realtimeIslandFiles()].some((file) => {
-    const src = posix.relative(pageDir, file);
-    return rendered.has(islandModuleId(src.startsWith('.') ? src : `./${src}`));
-  });
-  return reaches ? renderHead(clientBootTags(options.sync)) : '';
-}
-
-const collectorFor = (entry: RouteEntry, options: DocumentOptions): IslandCollector =>
-  createIslandCollector({
-    file: entry.file,
-    hydrate: entry.config.hydrate,
-    ...(options.resolveIsland === undefined ? {} : { resolve: options.resolveIsland(entry.file) }),
-  });
-
 /**
  * Head + body for one route render. Exported because the build's prerenderer must emit the same
  * document `x dev` serves — two document builders is how a page that works in dev ships broken.
@@ -257,6 +213,42 @@ export async function routeDocument(
   return documentFrom(entry, ctx, await routeDataFor(entry.config, ctx), options);
 }
 
+/**
+ * The document a request by `actor` is SERVED: `routeDocument` plus the scope the response would
+ * carry, which is what earns the page boot. The build weighs an app/ page through this, because a
+ * budget is a promise about what that page's browser downloads — and an unscoped render of a
+ * scoped page weighed a runtime chunk it never fetches and no boot it always does (#505).
+ */
+export async function servedDocument(
+  entry: RouteEntry,
+  ctx: DevRouteData,
+  actor: Actor,
+  options: DocumentOptions & { readonly buildId: string },
+): Promise<string> {
+  const data = await routeDataFor(entry.config, ctx);
+  return documentFrom(entry, ctx, data, options, documentScope(entry, options.buildId, actor));
+}
+
+/**
+ * Whether, and as whom, a mode's response is scoped — ONE decision for the request path and for
+ * `servedDocument`. A stream is always `private, no-store`; an ssr page carries the scope exactly
+ * when the headers `renderSsr` sends are private (an ungated page is `public, s-maxage`, and a CDN
+ * may hand it to anyone); a static or isr document is shareable by construction.
+ */
+function documentScope(entry: RouteEntry, buildId: string, actor: Actor): string | undefined {
+  switch (entry.config.render) {
+    case 'static':
+    case 'isr':
+      return undefined;
+    case 'stream':
+      return clientScopeOf(actor);
+    default:
+      return documentCarriesScope(ssrHeaders(entry, { buildId }))
+        ? clientScopeOf(actor)
+        : undefined;
+  }
+}
+
 /**
  * The document from data ALREADY resolved. Split from `routeDocument` so one request resolves
  * `load` exactly once: `stream` renders head and body separately, and resolving in each would let
@@ -273,23 +265,23 @@ async function documentFrom(
   options: DocumentOptions,
   scope?: string,
 ): Promise<string> {
-  const islands = collectorFor(entry, options);
+  const islands = collectorFor(entry, options, scope);
   const [head, body] = await Promise.all([
     headFor(entry, ctx, data, options, scope),
     routeBody(entry, ctx, data, islands),
   ]);
   return (
-    `<!doctype html><html lang="${lang()}"><head>${head}${styleTag(entry)}</head>` +
+    `<!doctype html><html lang="${lang()}"><head>${head}${stylesFor(entry, options)}</head>` +
     `<body>${body}${bootScript(entry, islands, options, scope)}${hydrateRuntime(islands.directives)}</body></html>`
   );
 }
 
+/** Every mode but `isr`, which `renderIsr` answers: its `load` runs only when the store misses. */
 async function resultFor(
   entry: RouteEntry,
   request: DevRouteData,
   data: RouteData,
   options: DevRenderOptions,
-  isr: IsrController,
   ctx: Ctx,
 ): Promise<RenderResult> {
   const url = new URL(request.url);
@@ -303,57 +295,40 @@ async function resultFor(
       const body = await documentFrom(entry, request, data, options);
       return { status, headers: staticHeaders(contentHash(body), options.buildId), body };
     }
-    case 'isr': {
-      // `isrKey(url, locale)`, never `url.pathname`: the query is part of what was rendered — this
-      // route's own `meta` reads `data.url` — so two URLs differing only in their query are two
-      // documents. Keyed on the pathname alone, the first render answered every later query
-      // string (#171). Render owns the derivation so no second caller can invent another.
-      // The locale is the second dimension and it is `ctx.locale`, the answer the `locale` stage
-      // already negotiated for THIS request — never `currentLocale()`, which would read the same
-      // value through an ambient store the key does not need.
-      // `{ html, status }`, never the bare string: the entry stores the status beside the HTML
-      // and serves it on every hit, so a 404 under `isr` is a 404 for its whole TTL.
-      const served = await isr.serve(isrKey(url, ctx.locale), async () => ({
-        html: await documentFrom(entry, request, data, options),
-        status,
-      }));
-      return served.result;
-    }
     case 'stream': {
       // The shell IS the component: nothing can yet mark a subtree as a hole. Solid's `Suspense`
       // is not the missing piece and never will be here — it calls `getContextId()`, which throws
       // outside a Solid renderer, and this package's JSX factory is inert by design. A hole marker
       // has to be the framework's own. Until it exists the first flush carries the whole body —
       // correct output, no streaming benefit.
-      const islands = collectorFor(entry, options);
+      // A stream is always `private, no-store` (`streamResult`), so it always carries the scope.
+      const scope = documentScope(entry, options.buildId, ctx.actor);
+      const islands = collectorFor(entry, options, scope);
       const [head, shell] = await Promise.all([
-        // A stream is always `private, no-store` (`streamResult`), so it always carries the scope.
-        headFor(entry, request, data, options, clientScopeOf(ctx.actor)),
+        headFor(entry, request, data, options, scope),
         routeBody(entry, request, data, islands),
       ]);
       return withScope(
         streamResult(
           {
-            head: `<!doctype html><html lang="${lang()}"><head>${head}${styleTag(entry)}</head><body>`,
+            head: `<!doctype html><html lang="${lang()}"><head>${head}${stylesFor(entry, options)}</head><body>`,
             // The runtime rides the first flush, with the shell it boots. A later chunk would leave
             // the window between flush one and the close with inert islands and no listeners on
             // them — which is exactly the first-click-lost failure `interaction` replay exists for.
-            shell: `${shell}${bootScript(entry, islands, options, clientScopeOf(ctx.actor))}${hydrateRuntime(islands.directives)}`,
+            shell: `${shell}${bootScript(entry, islands, options, scope)}${hydrateRuntime(islands.directives)}`,
             holes: [],
           },
           { buildId: options.buildId },
           status,
         ),
-        clientScopeOf(ctx.actor),
+        scope,
       );
     }
     default: {
       // Asked of the headers `renderSsr` is about to send: a gated page is private and carries the
       // scope; an ungated one is `public, s-maxage` and a CDN may hand it to anyone, so it carries
       // none — absent, which core reads as "not rendered for anyone", never as anonymous.
-      const scope = documentCarriesScope(ssrHeaders(entry, { buildId: options.buildId }))
-        ? clientScopeOf(ctx.actor)
-        : undefined;
+      const scope = documentScope(entry, options.buildId, ctx.actor);
       return withScope(
         await renderSsr(
           { entry, params: request.params, url, ctx },
@@ -429,8 +404,11 @@ const metaOf = (entry: RouteEntry, head?: NavigationDocumentHead): HttpRouteMeta
  * only a test does — and then guard and page fall back together.
  */
 export function appRoutes(options: DevRenderOptions): readonly Route[] {
-  const isr = options.isr ?? createIsrController({ buildId: options.buildId });
+  const isr = options.isr ?? attachedIsr({ buildId: options.buildId }).isr;
   const memo = createStaticMemo();
+  // A cold static key is ONE render however many requests arrive during it: the memo alone was
+  // check-then-act, so a burst at boot ran `load` and the render once per request.
+  const firstRender = singleFlight();
   return routeEntries().map((registered) => ({
     method: 'GET' as const,
     path: registered.path,
@@ -450,23 +428,67 @@ export function appRoutes(options: DevRenderOptions): readonly Route[] {
           : undefined;
       const kept = key === undefined ? undefined : memo.get(key);
       if (kept !== undefined) return staticResponse(request, kept);
-      const data: DevRouteData = { url: request.url.href, params: ctx.params };
-      // ONCE per request, before the mode is chosen: every branch of `resultFor` reads this same
-      // object, so a route's `load` runs exactly once however its mode splits head from body.
-      const loaded = await routeDataFor(entry.config, data);
-      // `setRedirect()` inside `load` — the same slot an action's handler fills — answers here,
-      // before a document is rendered for a page the visitor is leaving. `withStatus` refuses a
-      // 3xx because a rendered document has no `Location`; this is the path that has one.
-      const to = takeRedirect(ctx);
-      if (to !== undefined) return loadRedirect(entry, to);
-      const result = await resultFor(entry, data, loaded, options, isr, asCtx(ctx));
-      if (entry.config.render !== 'static' || typeof result.body !== 'string') {
-        return responseOf(result);
-      }
-      const document: StaticResult = { ...result, body: result.body };
-      if (key !== undefined) memo.set(key, document);
+      let led = false;
+      const render = async (): Promise<Rendered> => {
+        led = true;
+        const rendered = await renderEntry(entry, request, ctx, options, isr);
+        if (key !== undefined && rendered.document !== undefined) memo.set(key, rendered.document);
+        return rendered;
+      };
+      const shared = key === undefined ? await render() : await firstRender.run(key, render);
+      // Only a DOCUMENT is shared. A redirect `load` decided was its request's own, so a request
+      // that joined one renders for itself rather than answer with another request's `Location`.
+      const rendered = shared.document !== undefined || led ? shared : await render();
       // The ETag was only ever a header: a matching `If-None-Match` is a 304, not the page again.
-      return staticResponse(request, document);
+      return rendered.document === undefined
+        ? rendered.respond()
+        : staticResponse(request, rendered.document);
     },
   }));
 }
+
+/** A static document a joined request can share, or how to answer when there is none. */
+interface Rendered {
+  readonly document?: StaticResult;
+  readonly respond: () => Response;
+}
+
+async function renderEntry(
+  entry: RouteEntry,
+  request: UltimateRequest,
+  ctx: RequestContext,
+  options: DevRenderOptions,
+  isr: IsrController,
+): Promise<Rendered> {
+  const data: DevRouteData = { url: request.url.href, params: ctx.params };
+  if (entry.config.render === 'isr') return renderIsr(entry, data, ctx, options, isr);
+  // ONCE per request, before the mode is chosen: every branch of `resultFor` reads this same
+  // object, so a route's `load` runs exactly once however its mode splits head from body.
+  const loaded = await routeDataFor(entry.config, data);
+  // `setRedirect()` inside `load` — the same slot an action's handler fills — answers here,
+  // before a document is rendered for a page the visitor is leaving. `withStatus` refuses a
+  // 3xx because a rendered document has no `Location`; this is the path that has one.
+  const to = takeRedirect(ctx);
+  if (to !== undefined) return { respond: () => loadRedirect(entry, to) };
+  const result = await resultFor(entry, data, loaded, options, asCtx(ctx));
+  if (entry.config.render !== 'static' || typeof result.body !== 'string') {
+    return { respond: () => responseOf(result) };
+  }
+  const document: StaticResult = { ...result, body: result.body };
+  return { document, respond: () => responseOf(document) };
+}
+
+/** `isr`'s outcome (`runtime-isr-outcome.ts`) as this file's answer: a page, or the redirect. */
+async function renderIsr(
+  entry: RouteEntry,
+  data: DevRouteData,
+  ctx: RequestContext,
+  options: DevRenderOptions,
+  isr: IsrController,
+): Promise<Rendered> {
+  const document = (loaded: RouteData): Promise<string> =>
+    documentFrom(entry, data, loaded, options);
+  const outcome = await isrOutcome({ entry, data, ctx, isr, document });
+  if (outcome.kind === 'redirect') return { respond: () => loadRedirect(entry, outcome.to) };
+  return { respond: () => responseOf(outcome.result) };
+}

package/src/runtime-replica.ts

@@ -7,7 +7,7 @@
 // 1. `defaultClient()` is the one place db composes `replicatedClient(primary, replica)` from
 //    `DATABASE_REPLICA_URL`, and it runs only from `baseClient()` — "the client an app installed
 //    none for". Every process the framework boots installs one: `runtime-queue.ts` calls
-//    `setDbClient(createPgliteClient(…) | createPostgresClient({ url }))`, so `defaultClient()` was
+//    `setDbClient(pgliteClient(…) | postgresClient({ url }))`, so `defaultClient()` was
 //    unreachable from `x dev`, from `apps/web/server.ts` and from every container role.
 // 2. Routing needs an OPEN scope as well as a configured replica, and nothing opened one.
 //
@@ -17,12 +17,7 @@
 // what a database is.
 
 import type { DbClient, PostgresClient } from '@ultimat3/db';
-import {
-  createPostgresClient,
-  REPLICA_URL_ENV,
-  replicatedClient,
-  withReplicaReads,
-} from '@ultimat3/db';
+import { postgresClient, REPLICA_URL_ENV, replicatedClient, withReplicaReads } from '@ultimat3/db';
 import type { Middleware } from '@ultimat3/http';
 import type { ServiceBinding } from './runtime-bindings';
 import type { RuntimeOverrides } from './runtime-overrides';
@@ -61,7 +56,7 @@ export function attachReplica(
   replicaUrl: string | undefined,
 ): ReplicaAttachment {
   if (replicaUrl === undefined) return { client: primary, replica: undefined };
-  const replica = createPostgresClient({ url: replicaUrl, applicationName: 'ultimate-replica' });
+  const replica = postgresClient({ url: replicaUrl, applicationName: 'ultimate-replica' });
   return { client: replicatedClient(primary, replica), replica };
 }
 

package/src/runtime-services.ts

@@ -4,7 +4,6 @@
 // boot installs, only backed by embedded drivers.
 
 import { mkdirSync } from 'node:fs';
-import { dirname } from 'node:path';
 import { configureAuthLimiters, postgresAuthLimiter, resetAuthLimiters } from '@ultimat3/auth';
 import type { PurgeDriver } from '@ultimat3/cache';
 import { isNoopPurgeDriver, selectPurgeDriver } from '@ultimat3/cache';
@@ -17,31 +16,32 @@ import {
   systemClock,
 } from '@ultimat3/core';
 import type { RateLimitStore } from '@ultimat3/http';
-import { postgresRateLimitStore } from '@ultimat3/http';
+import { adoptRateLimitStore, postgresRateLimitStore } from '@ultimat3/http';
 import type { EventBus, JobDriver, OutboxStore } from '@ultimat3/jobs';
 import type { MailDriver } from '@ultimat3/mail';
 import {
   isMemoryDriver,
   isUnconfiguredDriver,
   resetMailDriver,
-  selectMailDriver,
   setMailDriver,
 } from '@ultimat3/mail';
 import type { Transport, TransportSelection } from '@ultimat3/realtime/server';
 import { selectTransport } from '@ultimat3/realtime/server';
 import type { Storage } from '@ultimat3/storage';
 import { defineStorage, localDriver, s3Driver, usesDevStorageSecret } from '@ultimat3/storage';
+import { loadAppConfig } from './app-config-load';
 import { LocalDiskUnsafeError, StorageUnwritableError } from './errors';
 import { msg } from './messages';
 import type { DevServices, Env } from './runtime-bindings';
-import { loadCacheTiers, startCacheTiers } from './runtime-cache';
-import { loadWorkerConfig, type WorkerConfig } from './runtime-jobs';
-import { loadInboxRetention } from './runtime-notify-retention';
+import { cacheTiersOf, startCacheTiers } from './runtime-cache';
+import { type WorkerConfig, workerConfigOf } from './runtime-jobs';
+import { selectAppMailDriver } from './runtime-mail';
+import { inboxRetentionOf } from './runtime-notify-retention';
 import type { RuntimeOverrides } from './runtime-overrides';
 import { installRetentionSweep } from './runtime-purge';
-import type { DevDbClient } from './runtime-queue';
+import type { DevDbClient, SchemaMode } from './runtime-queue';
 import { pgExecutorFor, startQueue } from './runtime-queue';
-import { loadRealtimeConfig } from './runtime-realtime';
+import { realtimeConfigOf } from './runtime-realtime';
 
 export interface RunningServices {
   readonly services: DevServices;
@@ -57,7 +57,8 @@ export interface RunningServices {
    */
   readonly realtime: RealtimeConfig;
   /**
-   * `app.config.ts`'s `jobs.queues` / `concurrency` / `visibilityTimeoutMs`, for the `worker` role.
+   * `app.config.ts`'s `jobs.queues` / `concurrency` / `visibilityTimeoutMs`, for the `worker` role —
+   * the queues replaced by the boot env's `WORKER_QUEUES` when it is set (`runtime-jobs.ts`).
    * Optional because a `RunningServices` can be hand-built, and a test runtime with none keeps the
    * worker's own defaults — the answer it always got. `startServices` always sets it.
    */
@@ -87,7 +88,7 @@ export interface RunningServices {
    * `roles.web.replicas: 3` and `x new` scaffolds two.
    *
    * OPTIONAL because a `RunningServices` can be hand-built: a test's fixture runtime has a stub
-   * client and no shared store, which is `createServer`'s memory store and `scope: 'process'` —
+   * client and no shared store, which is `httpServer`'s memory store and `scope: 'process'` —
    * the honest answer for it, and the one `startWeb` derives.
    */
   readonly rateLimitStore?: RateLimitStore;
@@ -301,15 +302,35 @@ async function release(steps: readonly (() => void | Promise<void>)[]): Promise<
   return failures;
 }
 
+/**
+ * Every STOP path's form of `release`: every step runs, newest first, and the FIRST failure is
+ * rethrown — it is the cause, the rest its consequences. The one helper for this process's stops
+ * (`startServices`, `startRoles`, `bootServing`, `x dev`): a chain of `await`s with no `try`
+ * skipped every step after one rejection, and the replicator rejects a refused close on purpose.
+ * Steps are listed in BOOT order, as an unwind list is.
+ */
+export async function releaseOrThrow(
+  steps: readonly (() => void | Promise<void>)[],
+): Promise<void> {
+  const failures = await release(steps);
+  if (failures.length > 0) throw failures[0];
+}
+
 export async function startServices(
   services: DevServices,
   env: Env,
   overrides?: RuntimeOverrides,
+  /** `'verify'` for a serving role on an external database — `runtime-queue.ts`'s `SchemaMode`. */
+  schema: SchemaMode = 'apply',
 ): Promise<RunningServices> {
+  // The app's config is loaded ONCE, here, first, and every section below is read out of that one
+  // validated object — mail's `retainMime` is the first reader, so it is loaded before mail.
+  const config = await loadAppConfig(services.root);
   // Before the queue: selection is pure — it parses `SMTP_URL` and builds a transport, it does
   // not dial. A typo'd credential must fail on the spot rather than after PGlite has started and
   // been unwound again, and it must fail at boot rather than on the first mail nobody receives.
-  const selection = selectMailDriver(env);
+  // `mail.retainMime` rides along (`runtime-mail.ts`), refused here the same way.
+  const selection = selectAppMailDriver(env, config);
   // Same reason, same place: building a purge driver reads env and dials nothing, so a half-set
   // `FASTLY_API_TOKEN` without its service id fails here rather than on the first stale page.
   const cdn = selectPurgeDriver(env);
@@ -318,14 +339,14 @@ export async function startServices(
   // service starts, rather than quietly keeping the in-process bus. Which transport, which KV
   // bucket and which presence TTL is `@ultimat3/realtime`'s decision, and it is the same call a
   // `ROLE=sync` container makes, so this process cannot resolve the bus differently from the
-  // container it stands in for. The root is `dirname(stateDir)`, as `loadCacheTiers` reads it.
-  const realtime = await loadRealtimeConfig(dirname(services.stateDir));
-  const workerConfig = await loadWorkerConfig(dirname(services.stateDir));
+  // container it stands in for.
+  const realtime = realtimeConfigOf(config);
+  const workerConfig = workerConfigOf(config, env);
   const bus: TransportSelection = selectTransport(env, realtime);
   // `env`, not the ambient one: this function is HANDED the boot's environment and every other
   // reader here already uses it, so a queue that asked `process.env` would decide the standby from
   // a different answer than the middleware that routes to it.
-  const queue = await startQueue(services, overrides, env);
+  const queue = await startQueue(services, overrides, env, schema);
   const { db, jobs, outbox, events } = queue;
   // The same executor the jobs driver, the outbox, the event bus and the idempotency store run
   // on — one pool, one `Bun.sql` that does NOT satisfy `PgExecutor` (`Bun.sql.query` is
@@ -354,18 +375,23 @@ export async function startServices(
       postgresAuthLimiter({ executor, clock: systemClock, policy }),
     );
     started.push(() => resetAuthLimiters());
+    // Where an action's or a query's declared `rateLimit:` is counted — on every surface, so a
+    // task or a one-off command spends from the fleet's table too, not one process' memory. Before
+    // `loadApp` for the auth limiters' reason; `startRoles` stacks a deployment's override over it.
+    started.push(adoptRateLimitStore(rateLimitStore));
     // The hourly sweep over the framework tables this boot is responsible for. Every one of them
     // ships a `purgeExpired()` that nothing called, so every row written was a row kept —
     // `x_rate_limit` takes one upsert per request the web role serves, assets included.
     //
     // `inboxRetention` is READ HERE and not defaulted in `runtime-purge.ts`: the two windows are the
-    // app's, `startServices` holds no `AppConfig`, and a loader that silently answered "never
-    // sweep" from inside the sweep would be indistinguishable from an app that chose it.
+    // app's, and a loader that silently answered "never sweep" from inside the sweep would be
+    // indistinguishable from an app that chose it.
     started.push(
       installRetentionSweep({
         idempotency: queue.idempotency,
         rateLimit: rateLimitStore,
-        inboxRetention: await loadInboxRetention(services.root),
+        events,
+        inboxRetention: inboxRetentionOf(config),
       }),
     );
     // One readiness check per resource this boot OWNS, released with it. Nothing in the tree
@@ -402,17 +428,15 @@ export async function startServices(
     started.push(() => resetMailDriver());
     const purge = overrides?.purge ?? cdn.driver;
     // Every tier this process reads through, plus the cross-instance invalidation hop, in one
-    // call. The CDN tier used to be the only one registered here — so `createRedisTier`,
-    // `createLruTier` and `createMemoTier` shipped with no caller at all and every replica
+    // call. The CDN tier used to be the only one registered here — so `redisTier`,
+    // `lruTier` and `memoTier` shipped with no caller at all and every replica
     // recomputed every cached read. Released with `resetTiers()`, which drops the whole registry:
     // this boot is the only thing that registers one, and a tier left behind would purge for a
     // process that has stopped.
     // The ladder is the app's declaration, never the environment's. `cache.tiers` was declared,
     // validated and documented while NOTHING read it — so an app asking for one rung got four,
-    // and one asking for a shared tier got whatever `REDIS_URL` happened to say. `.x` is
-    // `resolveServices`' own join, so its parent is the app root: the one fact this function needs
-    // and does not already carry.
-    const tiers = await loadCacheTiers(dirname(services.stateDir));
+    // and one asking for a shared tier got whatever `REDIS_URL` happened to say.
+    const tiers = cacheTiersOf(config);
     started.push(startCacheTiers({ env, purge, transport, tiers }));
 
     return {
@@ -443,8 +467,7 @@ export async function startServices(
       // the FIRST failure is rethrown because it is the cause and the rest are its consequences,
       // and every step still runs, so a refused shutdown never leaks into the next boot.
       async stop() {
-        const failures = await release(started);
-        if (failures.length > 0) throw failures[0];
+        await releaseOrThrow(started);
       },
     };
   } catch (error) {

package/src/runtime-storage-upload.ts

@@ -5,7 +5,7 @@
 
 import { finiteCount, readWithinLimit } from '@ultimat3/core';
 import type { RequestContext, Route, UltimateRequest } from '@ultimat3/http';
-import { json, NO_STORE } from '@ultimat3/http';
+import { jsonResponse, NO_STORE } from '@ultimat3/http';
 import type { Storage } from '@ultimat3/storage';
 import {
   acceptSignedUpload,
@@ -74,7 +74,7 @@ async function acceptUpload(
         : { allowedContentTypes: [constraints.contentType] }),
     }),
   });
-  return json({ key: stored.key }, { status: 201 });
+  return jsonResponse({ key: stored.key }, { status: 201 });
 }
 
 /**