@ultimat3/cli 24.0.0 → 25.0.0

package/src/runtime-jobs.ts

@@ -1,60 +1,120 @@
-// `jobs.queues`, `jobs.concurrency` and `jobs.visibilityTimeoutMs`, read out of the app's own
-// `app.config.ts` for the `worker` role, out of the config `startServices` loads once. Until 22.0.0
-// `createWorker` was called with none of them, so a `mail` queue ran nothing.
+// The queues a `worker` serves and the slots each gets: `jobs.queues`, `jobs.concurrency` and
+// `jobs.visibilityTimeoutMs` off the app's own `app.config.ts`, and `WORKER_QUEUES` off the
+// Deployment's env — the one per-Deployment answer, since every Deployment runs the same image and
+// the same config (issues #673, #676).
 
-import type { AppConfig } from '@ultimat3/core';
+import type { AppConfig, JobsConcurrency } from '@ultimat3/core';
+import { ConfigInvalidError, logger, renderCauseValue, renderFixShellArg } from '@ultimat3/core';
 import { registeredJobs, type WorkerOptions } from '@ultimat3/jobs';
+import type { Env } from './runtime-bindings';
+
+/** The env key a worker Deployment names its queues with: `WORKER_QUEUES=banks,banks-long`. */
+export const WORKER_QUEUES_ENV = 'WORKER_QUEUES';
 
 /** What the worker takes from the config. An absent number keeps the worker's own default. */
 export interface WorkerConfig {
   readonly queues: readonly string[];
-  readonly concurrency: number | undefined;
+  /**
+   * `true` when `WORKER_QUEUES` named `queues`: they are served EXACTLY, never widened by the
+   * queues registered jobs are enqueued on. `false` is the union `workerQueuesFor` explains.
+   */
+  readonly exact: boolean;
+  readonly concurrency: JobsConcurrency | undefined;
   readonly visibilityTimeoutMs: number | undefined;
 }
 
 /** A root with no `app.config.ts`: no queue of its own, and the worker's own timings. */
 const NO_WORKER_CONFIG: WorkerConfig = Object.freeze({
   queues: [],
+  exact: false,
   concurrency: undefined,
   visibilityTimeoutMs: undefined,
 });
 
-export function workerConfigOf(config: AppConfig | undefined): WorkerConfig {
-  if (config === undefined) return NO_WORKER_CONFIG;
-  const { queues, concurrency, visibilityTimeoutMs } = config.jobs;
-  return { queues, concurrency, visibilityTimeoutMs };
+/**
+ * `WORKER_QUEUES`, read: `undefined` when unset or blank (`ROLE`'s rule — an empty value is a
+ * template that said nothing), else its names trimmed and deduplicated in the order written. An
+ * empty entry (`banks,,long`) is REFUSED, not skipped: it is a queue somebody meant to name, and
+ * the worker that dropped it would leave that queue's jobs waiting with nothing in the log.
+ */
+export function workerQueuesFromEnv(env: Env): readonly string[] | undefined {
+  const raw = env[WORKER_QUEUES_ENV];
+  if (raw === undefined || raw.trim() === '') return undefined;
+  const names = raw.split(',').map((name) => name.trim());
+  const named = [...new Set(names.filter((name) => name !== ''))];
+  if (!names.includes('')) return named;
+  throw new ConfigInvalidError({
+    cause: `${WORKER_QUEUES_ENV} ${renderCauseValue(raw)} contains an empty queue name — every comma-separated entry must name a queue`,
+    fix: `WORKER_QUEUES=${renderFixShellArg(named.join(','), '<queue>,<queue>')} on this Deployment — or unset WORKER_QUEUES to serve jobs.queues and every registered job's queue`,
+    meta: { key: WORKER_QUEUES_ENV },
+  });
+}
+
+export function workerConfigOf(config: AppConfig | undefined, env: Env = {}): WorkerConfig {
+  const fromEnv = workerQueuesFromEnv(env);
+  const base =
+    config === undefined
+      ? NO_WORKER_CONFIG
+      : {
+          queues: config.jobs.queues,
+          exact: false,
+          concurrency: config.jobs.concurrency,
+          visibilityTimeoutMs: config.jobs.visibilityTimeoutMs,
+        };
+  return fromEnv === undefined ? base : { ...base, queues: fromEnv, exact: true };
 }
 
 /**
  * The queues a worker serves: the configured ones, then every queue a registered job is enqueued
  * on. The union and not the list, decided 2026-09-23: `x new` and the deployed demo configure
  * `['<app>-default']` while a `job()` naming no queue lands on `default`, so obeying the list alone
- * would leave every such job queued for ever — the silent direction. `undefined` when both are
- * empty, which is `createWorker`'s own `['default']`.
+ * would leave every such job queued for ever — the silent direction. `exact` (a Deployment that
+ * set `WORKER_QUEUES`) is the list alone: that operator split the queues across Deployments on
+ * purpose, and widening one to the rest is what made their grace periods mean nothing (#673).
+ * `undefined` when nothing is served, which is `jobWorker`'s own `['default']`.
  */
 export function workerQueuesFor(
   configured: readonly string[],
   registered: readonly string[],
+  exact = false,
 ): readonly string[] | undefined {
-  const served = [...new Set([...configured, ...registered])];
+  const served = [...new Set(exact ? configured : [...configured, ...registered])];
   return served.length === 0 ? undefined : served;
 }
 
+/**
+ * An exact worker's one boot line about what it leaves: the queues registered jobs are enqueued
+ * on that it will never claim. A warning and not a refusal — another Deployment serving them is
+ * the whole point of the split — but this process cannot see that one, so it says what to check.
+ */
+function reportUnserved(served: readonly string[], registered: readonly string[]): void {
+  const queues = [...new Set(registered)].filter((queue) => !served.includes(queue)).sort();
+  if (queues.length === 0) return;
+  logger.warn('jobs.worker.queue-unserved', {
+    queues,
+    served,
+    fix: `x jobs ls --json — every queue listed with no worker needs one: WORKER_QUEUES=<queue>,<queue> on another worker Deployment, or add it to this one's`,
+  });
+}
+
 type WorkerConfigOptions = Pick<WorkerOptions, 'queues' | 'concurrency' | 'visibilityTimeoutMs'>;
 
 /**
- * The `createWorker` options the config supplies, read at START so every job the app registered
+ * The `jobWorker` options the config supplies, read at START so every job the app registered
  * on import is counted. A key the config leaves unset is omitted, never passed as `undefined`, so
  * the worker's own default applies (`exactOptionalPropertyTypes`).
  */
 export function workerOptionsFor(config: WorkerConfig | undefined): WorkerConfigOptions {
-  const queues = workerQueuesFor(
-    config?.queues ?? [],
-    registeredJobs().map((handle) => handle.queue),
-  );
+  const registered = registeredJobs().map((handle) => handle.queue);
+  const exact = config?.exact === true;
+  const queues = workerQueuesFor(config?.queues ?? [], registered, exact);
+  if (exact) reportUnserved(queues ?? [], registered);
+  // Passed as written: `jobWorker` reads a table by own key and runs a queue it does not name at
+  // core's `JOBS_CONCURRENCY_DEFAULT` — the one slot default, so no second table is built here.
+  const concurrency = config?.concurrency;
   return {
     ...(queues === undefined ? {} : { queues }),
-    ...(config?.concurrency === undefined ? {} : { concurrency: config.concurrency }),
+    ...(concurrency === undefined ? {} : { concurrency }),
     ...(config?.visibilityTimeoutMs === undefined
       ? {}
       : { visibilityTimeoutMs: config.visibilityTimeoutMs }),

package/src/runtime-live-feed.ts

@@ -1,5 +1,5 @@
 // Where a `sync` node's changes come from when this process boots one. Production decodes the
-// write-ahead log (`x dev --role replicator`, `PgLogicalReplicationFeed`, a real `DATABASE_URL`).
+// write-ahead log (`x dev --role replicator`, `postgresChangeFeed()`, a real `DATABASE_URL`).
 // The embedded database has no walsender, and until 2026-09-05 nothing stood in for it: a live
 // subscription under `x dev` took its snapshot and then heard nothing, so every `--live` query in
 // every scaffolded app was dead in development — which is where an author first tries one.

package/src/runtime-mail.ts

@@ -0,0 +1,26 @@
+// The `mail` section of `app.config.ts` the boot obeys: `mail.retainMime`, handed to
+// `@ultimat3/mail`'s `selectMailDriver` — the one option an environment cannot carry. Selection
+// still reads env for WHICH transport; the config only says what the chosen one keeps.
+
+import type { AppConfig } from '@ultimat3/core';
+import type { MailEnvironment, MailSelection, MailSelectOptions } from '@ultimat3/mail';
+import { selectMailDriver } from '@ultimat3/mail';
+
+/** No config file, or `retainMime: false`, is no option at all — never `retainMime: undefined`. */
+export function mailSelectOptionsOf(config: AppConfig | undefined): MailSelectOptions {
+  const retain = config?.mail.retainMime ?? false;
+  if (retain === false) return {};
+  return { retainMime: retain.maxBytes === undefined ? {} : { maxBytes: retain.maxBytes } };
+}
+
+/**
+ * The boot's mail selection. Pure, as `selectMailDriver` is: it builds a transport and dials
+ * nothing, so a cap above mail's ceiling or retention asked of Resend refuses the boot here.
+ */
+export const selectAppMailDriver = (
+  env: MailEnvironment,
+  config: AppConfig | undefined,
+): MailSelection =>
+  // `retainMimeKey`: mail judges the cap before it picks a transport — the ceiling is its number —
+  // and names the `app.config.ts` key in the refusal, so the boot restates no check of its own.
+  selectMailDriver(env, { ...mailSelectOptionsOf(config), retainMimeKey: 'mail.retainMime' });

package/src/runtime-mfa-warning.ts

@@ -2,7 +2,7 @@
 // the operator step for sealed MFA secrets). `x doctor` asks the same question only when someone
 // runs it; an unsealed secret is a user refused at the second factor, so the boot says so too.
 
-import { BuiltinAdapter, countUnsealedMfaSecrets } from '@ultimat3/auth';
+import { countUnsealedMfaSecrets, postgresAuthAdapter } from '@ultimat3/auth';
 import { logger } from '@ultimat3/core';
 import type { DbClient } from '@ultimat3/db';
 
@@ -14,7 +14,7 @@ import type { DbClient } from '@ultimat3/db';
 export async function warnUnsealedMfaSecrets(client: DbClient): Promise<number> {
   let unsealed = 0;
   try {
-    unsealed = await countUnsealedMfaSecrets({ adapter: new BuiltinAdapter(client) });
+    unsealed = await countUnsealedMfaSecrets({ adapter: postgresAuthAdapter(client) });
   } catch {
     return 0;
   }

package/src/runtime-overrides.ts

@@ -35,7 +35,7 @@ export interface RuntimeOverrides {
   readonly mail?: MailDriver;
   /**
    * Replaces the `NATS_URL` selection. Already connected when it arrives, and NOT closed by
-   * `stop()`: whoever built it owns its socket, exactly as `createServer` does not close a
+   * `stop()`: whoever built it owns its socket, exactly as `httpServer` does not close a
    * `rateLimitStore` it was handed.
    */
   readonly transport?: Transport;
@@ -53,12 +53,12 @@ export interface RuntimeOverrides {
    */
   readonly rateLimitStore?: RateLimitStore;
   /**
-   * Where regenerated ISR pages live. Omitted, `createIsrController` keeps a per-process memory
+   * Where regenerated ISR pages live. Omitted, `isrController` keeps a per-process memory
    * store — twelve replicas then hold twelve of them, and a purge tag reaches one twelfth of the
    * fleet.
    */
   readonly isrStore?: IsrStore;
-  /** Prepended to the pipeline by `createServer`, which `startRoles` never passed one. */
+  /** Prepended to the pipeline by `httpServer`, which `startRoles` never passed one. */
   readonly middleware?: readonly Middleware[];
   /**
    * Plain HTTP routes at paths no primitive projects to — `/.well-known/oauth-authorization-server`,

package/src/runtime-purge.ts

@@ -96,7 +96,7 @@ function notifyTargets(retention: InboxRetention): readonly PurgeTarget[] {
     },
     {
       name: 'x_notify_digests',
-      // The job's clock, and the store's own window (`createPgDigestStore({ retentionMs })`, a week
+      // The job's clock, and the store's own window (`postgresDigestStore({ retentionMs })`, a week
       // by default) — a closed window only its dead-lettered flush would ever have drained.
       purgeExpired: (nowMs: number): Promise<number> => purgeNotifyDigests(nowMs),
     },

package/src/runtime-queue.ts

@@ -14,19 +14,19 @@ import {
 import type { DbClient, PgliteClient, PostgresClient, SqlFragment } from '@ultimat3/db';
 import {
   baseClient,
-  createPgliteClient,
-  createPostgresClient,
   currentTx,
+  pgliteClient,
   pgliteDataDir,
+  postgresClient,
   setDbClient,
 } from '@ultimat3/db';
 import type { Tx } from '@ultimat3/entity';
 import type { EventBus, JobDriver, OutboxStore, PgExecutor } from '@ultimat3/jobs';
 import {
-  createJobsFacade,
-  createPgDriver,
-  createPgEventBus,
-  createPgOutboxStore,
+  outboxJobsFacade,
+  postgresEventBus,
+  postgresJobDriver,
+  postgresOutboxStore,
   resetEventBus,
   resetJobDriver,
   resetJobsFacade,
@@ -99,11 +99,11 @@ export function startDb(services: DevServices, env: ReplicaEnv): StartedDb {
         // Linked at boot, from the app's own migrations: PGlite cannot `create extension` one it
         // was not handed, and the schema dump's scratch replay already asks this same reader — an
         // app that replayed in the gate and failed in `x dev` was the two disagreeing.
-        createPgliteClient({
+        pgliteClient({
           dataDir: pgliteDataDir(binding.url),
           extensions: () => appExtensions(services.root),
         })
-      : createPostgresClient({ url: binding.url });
+      : postgresClient({ url: binding.url });
   const attached = attachReplica(client, replicaUrlFor(binding, env));
   setDbClient(attached.client);
   return { client, replica: attached.replica };
@@ -184,17 +184,17 @@ async function startJobs(
 ): Promise<RunningQueue> {
   await applySchema(client, schema);
   const executor = pgExecutorFor(client);
-  const driver = overrides?.jobs ?? createPgDriver({ executor });
+  const driver = overrides?.jobs ?? postgresJobDriver({ executor });
   setJobDriver(driver);
-  const outbox = createPgOutboxStore({
+  const outbox = postgresOutboxStore({
     executor,
     // The open transaction is a client on its own connection; the `Tx` token is not that object.
     txExecutor: () => pgExecutorFor(currentTx() ?? client),
   });
   setJobsFacade(
-    createJobsFacade({ store: outbox, driver }, () => currentTx() as unknown as Tx | undefined),
+    outboxJobsFacade({ store: outbox, driver }, () => currentTx() as unknown as Tx | undefined),
   );
-  const events = createPgEventBus({ executor });
+  const events = postgresEventBus({ executor });
   setEventBus(events);
   const idempotency = postgresIdempotencyStore({
     executor,

package/src/runtime-realtime.ts

@@ -1,6 +1,6 @@
-// `realtime.enabled`, `realtime.transport` and `realtime.urlEnv` for the boot, out of the config
-// `startServices` loads once (`app-config-load.ts`). Until 22.0.0 no boot read any of the three
-// and `NATS_URL` alone decided the bus.
+// The `realtime` section for the boot, out of the config `startServices` loads once
+// (`app-config-load.ts`). Until 22.0.0 no boot read `enabled`, `transport` or `urlEnv` and
+// `NATS_URL` alone decided the bus; the two per-actor caps are read by the `sync` role.
 
 import type { AppConfig, RealtimeConfig } from '@ultimat3/core';
 
@@ -9,6 +9,8 @@ export const REALTIME_DEFAULTS: RealtimeConfig = Object.freeze({
   enabled: true,
   transport: 'memory',
   urlEnv: undefined,
+  maxSubscriptionsPerActor: undefined,
+  maxSocketsPerActor: undefined,
 });
 
 /**

package/src/runtime-render.ts

@@ -3,12 +3,10 @@
 // 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, createSingleFlight } from '@ultimat3/core';
+import type { Actor, Ctx } from '@ultimat3/core';
+import { CLIENT_SCOPE_HEADER, singleFlight } from '@ultimat3/core';
 import type {
   RouteMeta as HttpRouteMeta,
   RedirectIntent,
@@ -18,20 +16,16 @@ import type {
   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,
@@ -43,7 +37,6 @@ import {
 import type { IsrController } from '@ultimat3/render/server';
 import {
   contentHash,
-  isrKey,
   ROOT_ELEMENT_ID,
   renderComponent,
   renderSsr,
@@ -52,14 +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';
@@ -119,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,
           },
         }),
@@ -170,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
@@ -201,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.
@@ -253,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
@@ -269,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);
@@ -299,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,7 +408,7 @@ export function appRoutes(options: DevRenderOptions): readonly Route[] {
   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 = createSingleFlight();
+  const firstRender = singleFlight();
   return routeEntries().map((registered) => ({
     method: 'GET' as const,
     path: registered.path,
@@ -482,6 +461,7 @@ async function renderEntry(
   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);
@@ -490,10 +470,25 @@ async function renderEntry(
   // 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, isr, asCtx(ctx));
+  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 };
 }