@ultimat3/cli 24.0.0 → 25.0.0

package/src/root-env.ts

@@ -1,9 +1,9 @@
 // The `.env*` files of the APP ROOT, whatever directory `x` was started from. Bun auto-loads them
 // from the process cwd only, while every command finds its root by walking up — so `x db migrate`
 // run from `apps/web` found the app and none of its `.env`, and silently used the embedded
-// database. Loaded once, after the root is known, never overriding a variable already set.
+// database. Loaded once, after the root is known, never overriding a real environment variable.
 
-import { isAbsolute, join, resolve } from 'node:path'; // why: Bun ships no path join/resolve.
+import { isAbsolute, join, relative, resolve } from 'node:path'; // why: Bun ships no path join/resolve.
 import { findAppRoot } from './app-root';
 
 type Env = Readonly<Record<string, string | undefined>>;
@@ -25,43 +25,172 @@ export const rootEnvFiles = (envName: string): readonly string[] => [
   `.env.${envName}.local`,
 ];
 
+const QUOTES = new Set(['"', "'", '`']);
+
+/**
+ * The quoted value opening at `text[open]`, read the way Bun reads it: across lines until the first
+ * unescaped closing quote, a backslash keeping the character after it (so `\"` never closes), and
+ * only double quotes turning `\n` and `\r` into the characters. `undefined` when the quote never
+ * closes — Bun then keeps the line as written, opening quote and all.
+ */
+function quoted(text: string, open: number): { value: string; end: number } | undefined {
+  const quote = text[open];
+  let value = '';
+  for (let at = open + 1; at < text.length; at += 1) {
+    const char = text[at];
+    if (char === quote) return { value, end: at + 1 };
+    if (char === '\\' && at + 1 < text.length) {
+      const next = text[at + 1];
+      value +=
+        quote !== '"'
+          ? `${char}${next}`
+          : next === 'n'
+            ? '\n'
+            : next === 'r'
+              ? '\r'
+              : `${char}${next}`;
+      at += 1;
+      continue;
+    }
+    value += char;
+  }
+  return undefined;
+}
+
 /**
- * One dotenv line: `KEY=value`, an optional `export `, a `#` comment, a value in single or double
- * quotes (double quotes read `\n`). No `${VAR}` expansion — a root-level default that needs one
- * belongs in the process environment, which always wins here anyway.
+ * Bun's expansion pass, the one part of it reproduced: `\$` is a literal `$` in every kind of
+ * value, quoted or not. Run after the quote pass, which is why `"a\\$x"` reads `a\$x` in Bun too.
  */
-export function parseDotenv(text: string): ReadonlyMap<string, string> {
+const literalDollars = (value: string): string => value.replaceAll('\\$', '$');
+
+/**
+ * A dotenv file, parsed to agree with Bun's own loader on the same bytes — a root `.env` must mean
+ * the same thing whether Bun read it (the process started in the root) or this did (it started
+ * below it). `KEY=value`, an optional `export `, `#` comments (an unquoted value ends at the first
+ * `#`), values quoted with `"`, `'` or a backtick and free to span lines, so a PEM key parses. A
+ * bare `\r` separates lines as `\n` does, inside a quoted value too.
+ * Bun's `$VAR` expansion is NOT reproduced: it resolves lazily across every loaded file and the
+ * process env, so a root default that needs one belongs in the process environment.
+ */
+export function parseDotenv(source: string): ReadonlyMap<string, string> {
+  const text = source.replace(/\r\n?/g, '\n');
   const out = new Map<string, string>();
-  for (const raw of text.split(/\r?\n/)) {
-    const line = raw.trim();
-    if (line === '' || line.startsWith('#')) continue;
-    const match = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_.]*)\s*=\s*(.*)$/.exec(line);
+  let start = 0;
+  while (start < text.length) {
+    const newline = text.indexOf('\n', start);
+    const eol = newline === -1 ? text.length : newline;
+    const line = text.slice(start, eol);
+    const match = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_.]*)\s*=\s*/.exec(line);
+    const open = start + (match?.[0].length ?? 0);
+    start = eol + 1;
     if (match === null) continue;
-    const value = (match[2] ?? '').trim();
-    const quote = value[0];
-    if ((quote === '"' || quote === "'") && value.lastIndexOf(quote) > 0) {
-      const inner = value.slice(1, value.lastIndexOf(quote));
-      out.set(match[1] ?? '', quote === '"' ? inner.replaceAll('\\n', '\n') : inner);
-    } else {
-      out.set(match[1] ?? '', value.replace(/\s+#.*$/, ''));
+    const key = match[1] ?? '';
+    const read = QUOTES.has(text[open] ?? '') ? quoted(text, open) : undefined;
+    if (read !== undefined) {
+      out.set(key, literalDollars(read.value));
+      // Whatever follows the closing quote on its line is a comment to Bun.
+      const after = text.indexOf('\n', read.end);
+      start = after === -1 ? text.length : after + 1;
+      continue;
     }
+    const value = line.slice(match[0].length);
+    const hash = value.indexOf('#');
+    out.set(key, literalDollars((hash === -1 ? value : value.slice(0, hash)).trim()));
   }
   return out;
 }
 
-/**
- * The variables the root's `.env*` files add to `env`: only keys `env` does not already hold, so a
- * real environment variable — and anything Bun already loaded from the cwd — always wins. Empty
- * when there is no app root or the cwd IS the root (Bun loaded those files itself).
- */
-export async function rootEnvAdditions(cwd: string, env: Env): Promise<Record<string, string>> {
-  const root = findAppRoot(cwd);
-  if (root === undefined || resolve(root.dir) === resolve(cwd)) return {};
+/** Where the command runs, and where the PROCESS started — not the same once `--cwd` is passed. */
+export interface RootEnvInput {
+  /** The `--cwd`-resolved directory the command works in; its app root is the one loaded. */
+  readonly cwd: string;
+  /** The directory the process started in: the only one whose `.env*` Bun loaded itself. */
+  readonly processCwd: string;
+  readonly env: Env;
+}
+
+/** Every `.env*` file in `dir`, merged in Bun's precedence for `envName`. */
+async function envFilesIn(dir: string, names: readonly string[]): Promise<Map<string, string>> {
   const merged = new Map<string, string>();
-  for (const name of rootEnvFiles(env['NODE_ENV'] ?? 'development')) {
-    const file = Bun.file(join(root.dir, name));
+  for (const name of names) {
+    const file = Bun.file(join(dir, name));
     if (!(await file.exists())) continue;
     for (const [key, value] of parseDotenv(await file.text())) merged.set(key, value);
   }
-  return Object.fromEntries([...merged].filter(([key]) => env[key] === undefined));
+  return merged;
+}
+
+/** True when `dir` is `root` or below it. */
+const isWithin = (root: string, dir: string): boolean => {
+  const rel = relative(resolve(root), resolve(dir));
+  return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+};
+
+/** What one command's env owes the app root: keys to set, and another app's keys to remove. */
+export interface RootEnvChanges {
+  readonly set: Readonly<Record<string, string>>;
+  readonly unset: readonly string[];
+}
+
+/**
+ * What the root's `.env*` files change in `env`. A real environment variable always wins. Nothing
+ * when there is no app root or the process STARTED in the root (Bun loaded those files itself).
+ * Judged against `processCwd`, never `cwd`: `x --cwd <app>` run from elsewhere resolves `cwd` to
+ * the root, and Bun loaded the other directory's files, not the app's.
+ *
+ * What Bun loaded from the starting directory is not a real variable. Started below the root
+ * (`apps/web`), it is the same app's own, more specific file, and it wins. Started OUTSIDE the
+ * root — `x --cwd ../app-b db migrate` run in app-a — it is another app's: a key whose value is
+ * exactly what that directory's files say is overridden by the target's, and REMOVED when the
+ * target does not define it — left in place, app-a's DATABASE_URL migrated app-b, which relies on
+ * its default. A value that differs from the file is one Bun did not write (it never overrides a
+ * real variable), so it is real and stays.
+ */
+export async function rootEnvChanges(input: RootEnvInput): Promise<RootEnvChanges> {
+  const { env } = input;
+  const root = findAppRoot(input.cwd);
+  if (root === undefined || resolve(root.dir) === resolve(input.processCwd)) {
+    return { set: {}, unset: [] };
+  }
+  const outside = !isWithin(root.dir, input.processCwd);
+  // A superset of what Bun loads from a cwd, so a key from any of them is recognised as file-made.
+  const filesAt = (dir: string, name: string) =>
+    envFilesIn(dir, [...rootEnvFiles(name), '.env.local']);
+  let envName = env['NODE_ENV'] ?? 'development';
+  let foreign = outside ? await filesAt(input.processCwd, envName) : new Map<string, string>();
+  // A NODE_ENV another app's file wrote is not one the operator chose: Bun picked that directory's
+  // file set with no real NODE_ENV, so with its default — and the target's set is picked the same
+  // way, never from the foreign value (app-a's `NODE_ENV=test` loaded app-b's `.env.test`).
+  if (foreign.has('NODE_ENV') && env['NODE_ENV'] === foreign.get('NODE_ENV')) {
+    envName = 'development';
+    foreign = await filesAt(input.processCwd, envName);
+  }
+  const merged = await envFilesIn(root.dir, rootEnvFiles(envName));
+  const fromFile = (key: string): boolean => foreign.has(key) && env[key] === foreign.get(key);
+  return {
+    set: Object.fromEntries([...merged].filter(([key]) => env[key] === undefined || fromFile(key))),
+    unset: [...foreign.keys()].filter((key) => fromFile(key) && !merged.has(key)).sort(),
+  };
+}
+
+type MutableEnv = Record<string, string | undefined>;
+
+/**
+ * The env a command runs with. When `env` IS the process env, it is changed in place — a package
+ * reading `Bun.env` directly must see what the command sees, and an unset key must be GONE, not
+ * merely shadowed. An injected env is never mutated: the command gets a rebuilt copy.
+ */
+export function applyRootEnv(
+  env: Env,
+  changes: RootEnvChanges,
+  processEnv: MutableEnv = Bun.env,
+): Env {
+  if (env === processEnv) {
+    for (const key of changes.unset) delete processEnv[key];
+    Object.assign(processEnv, changes.set);
+    return processEnv;
+  }
+  const rebuilt: MutableEnv = { ...env, ...changes.set };
+  for (const key of changes.unset) delete rebuilt[key];
+  return rebuilt;
 }

package/src/route-islands.ts

@@ -0,0 +1,69 @@
+// Which islands one route render collects, and the realtime page boot that render earns. Split
+// from `runtime-render.ts` so the document builder stays one job; both `documentFrom` and the
+// `stream` branch read the same two answers.
+
+// 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 type { IslandCollector, RouteEntry } from '@ultimat3/render';
+import {
+  clientBootTags,
+  islandCollector,
+  islandModuleId,
+  islandModuleIds,
+  renderHead,
+} from '@ultimat3/render';
+import type { DocumentOptions } from './document-options';
+import { realtimeIslandFiles } from './island-realtime';
+
+/**
+ * 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.
+ */
+export const collectorFor = (
+  entry: RouteEntry,
+  options: DocumentOptions,
+  scope: string | undefined,
+): IslandCollector =>
+  islandCollector({
+    file: entry.file,
+    hydrate: entry.config.hydrate,
+    ...(options.resolveIsland === undefined ? {} : { resolve: options.resolveIsland(entry.file) }),
+    // #506: on a document that carries the page boot (the same two conditions as `bootScript`), a
+    // realtime island's server markup is held off screen until it mounts over the restored store.
+    ...(scope === undefined || options.sync === undefined
+      ? {}
+      : { hold: (src: string) => reachesRealtime(entry, src) }),
+  });
+
+/** Whether `src`, as the page at `entry` wrote it, is an island the last build found realtime. */
+const reachesRealtime = (entry: RouteEntry, src: string): boolean =>
+  realtimeIslandFiles().has(posix.join(posix.dirname(entry.file), src));
+
+/**
+ * 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.
+ */
+export 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)) : '';
+}

package/src/runtime-admin.ts

@@ -28,7 +28,8 @@ const declared = (): ReadonlyMap<string, AdminApp> => {
   return held instanceof Map ? (held as ReadonlyMap<string, AdminApp>) : new Map();
 };
 
-export interface AdminMountOptions extends Pick<DocumentOptions, 'themeHead' | 'origin'> {
+export interface AdminMountOptions
+  extends Pick<DocumentOptions, 'themeHead' | 'brandHead' | 'origin'> {
   readonly buildId: string;
 }
 
@@ -103,6 +104,8 @@ async function answer(
     () =>
       routeDocument(entry, data, {
         ...(options.themeHead === undefined ? {} : { themeHead: options.themeHead }),
+        // The app's brand restyles its admin too: a screen is a document of the `app/` surface.
+        ...(options.brandHead === undefined ? {} : { brandHead: options.brandHead }),
         ...(options.origin === undefined ? {} : { origin: options.origin }),
       }),
     { buildId: options.buildId, status: response.status },

package/src/runtime-assets.ts

@@ -11,7 +11,7 @@ import { applyCacheHeaders } from '@ultimat3/http';
 import type { ImageQuery, ImageTransformDriver } from '@ultimat3/seo';
 import { builtinImageDriver, DEFAULT_WIDTHS, parseImageQuery, usableWidths } from '@ultimat3/seo';
 import type { ImageTransform, Storage, VariantFormat } from '@ultimat3/storage';
-import { isTenantScoped, isVariantFormat, variantKey } from '@ultimat3/storage';
+import { DEFAULT_QUALITY, isTenantScoped, isVariantFormat, variantKey } from '@ultimat3/storage';
 import { faviconRoute } from './favicon';
 // The icon matrix's source, its base path and its renderer live in their own module so that
 // `pwa-artifacts.ts` — which this file imports for the manifest route — can reach them without
@@ -69,6 +69,15 @@ const IMMUTABLE_IMAGE: CacheHint = { mode: 'immutable' };
 const isMintableWidth = (width: number | undefined, intrinsic: number): boolean =>
   width === undefined || usableWidths(intrinsic, DEFAULT_WIDTHS).includes(width);
 
+/**
+ * The same question for `?q=`. `@ultimat3/seo` never writes a quality into a variant URL, so the
+ * framework mints exactly one — the default — and `variantKey` already spells the default and an
+ * absent one as the same key. Every other value from 1 to 100 was its own stored object per
+ * minted width per format: a hundred writes a caller drives with a loop. Served, never stored.
+ */
+const isMintableQuality = (quality: number | undefined): boolean =>
+  quality === undefined || quality === DEFAULT_QUALITY;
+
 const imageResponse = (bytes: Uint8Array, contentType: string, cache: CacheHint): Response =>
   applyCacheHeaders(
     // Copied, not passed through: a `Uint8Array<ArrayBufferLike>` may be backed by a
@@ -146,7 +155,11 @@ async function transformedVariant(
     ...(query.format === undefined ? {} : { format: query.format }),
     ...(query.quality === undefined ? {} : { quality: query.quality }),
   });
-  if (cached !== undefined && isMintableWidth(query.width, intrinsic)) {
+  if (
+    cached !== undefined &&
+    isMintableWidth(query.width, intrinsic) &&
+    isMintableQuality(query.quality)
+  ) {
     await disk.put(cached, variant.bytes, { contentType: variant.contentType });
   }
   return imageResponse(variant.bytes, variant.contentType, cache);

package/src/runtime-bindings.ts

@@ -34,9 +34,29 @@ export interface DevServices {
 
 export type Env = Readonly<Record<string, string | undefined>>;
 
+/**
+ * An embedded binding's `url`: `<scheme>://` and then the HOST path, verbatim — a scheme-tagged
+ * path, NOT a URL. `pglite://D:\\app\\.x\\pgdata` is what Windows gets, and no URL parser reads it
+ * back (a `\\` is not a separator to one, a space would need encoding). Nothing parses it: db's
+ * `pgliteDataDir` and `startStorage` strip the prefix, and the report goes through `safeUrlLabel`,
+ * which answers the binding's name for anything that is not a URL. `Bun.pathToFileURL` was the
+ * other option, and would have made both readers decode as well as strip.
+ */
+export const embeddedLocation = (scheme: 'pglite' | 'file', path: string): string =>
+  `${scheme}://${path}`;
+
 const nonEmpty = (value: string | undefined): string | undefined =>
   value === undefined || value.trim().length === 0 ? undefined : value;
 
+const s3EndpointOf = (env: Env): string | undefined => nonEmpty(env['S3_ENDPOINT']);
+
+/**
+ * THE storage choice: a non-empty `S3_ENDPOINT` is object storage, anything else the embedded disk
+ * — which alone mints its own signed URLs and so needs `STORAGE_SIGNING_SECRET`. Exported so the
+ * deploy contract (`framework-env.ts`) asks this function rather than restating the rule.
+ */
+export const storageIsExternal = (env: Env): boolean => s3EndpointOf(env) !== undefined;
+
 /**
  * Embedded Postgres is PGlite on disk under `.x/`, so a restart keeps the data and a `x db reset`
  * is a directory delete rather than a container dance.
@@ -51,7 +71,7 @@ export function resolveServices(
   // (`e2e-app.ts`) instead of resetting the developer's own, beside a running `x dev`.
   const stateDir = nonEmpty(env['ULTIMATE_STATE_DIR']) ?? join(root, '.x');
   const databaseUrl = nonEmpty(env['DATABASE_URL']);
-  const s3Endpoint = nonEmpty(env['S3_ENDPOINT']);
+  const s3Endpoint = s3EndpointOf(env);
   // Created only when something will actually live in it: the embedded database and the local disk
   // do, in-process events never touch the disk. A container whose bindings are external runs
   // non-root over a read-only app directory, and a mkdir there is an EACCES at boot for a directory
@@ -67,7 +87,7 @@ export function resolveServices(
         ? {
             name: 'db',
             mode: 'embedded',
-            url: `pglite://${join(stateDir, 'pgdata')}`,
+            url: embeddedLocation('pglite', join(stateDir, 'pgdata')),
             detail: 'PGlite in this process — set DATABASE_URL to use a real Postgres',
           }
         : { name: 'db', mode: 'external', url: databaseUrl, detail: 'DATABASE_URL' },
@@ -77,7 +97,7 @@ export function resolveServices(
         ? {
             name: 'storage',
             mode: 'embedded',
-            url: `file://${join(stateDir, 'storage')}`,
+            url: embeddedLocation('file', join(stateDir, 'storage')),
             detail: 'local directory — set S3_ENDPOINT to use S3',
           }
         : { name: 'storage', mode: 'external', url: s3Endpoint, detail: 'S3_ENDPOINT' },

package/src/runtime-cache.ts

@@ -7,12 +7,12 @@
 import type { CacheTier, PurgeDriver } from '@ultimat3/cache';
 import {
   CacheDriverUnavailableError,
-  createCdnTier,
-  createLruTier,
-  createMemoTier,
-  createRedisTier,
+  cdnTier,
   isNoopPurgeDriver,
+  lruTier,
+  memoTier,
   receiveInvalidationBroadcast,
+  redisTier,
   registerInvalidationBroadcast,
   registerTier,
   resetTiers,
@@ -85,9 +85,9 @@ function redisUrl(env: Env): string | undefined {
 function buildTier(name: CacheTierName, options: CacheTiersOptions): CacheTier {
   switch (name) {
     case 'request-memo':
-      return createMemoTier();
+      return memoTier();
     case 'lru':
-      return createLruTier();
+      return lruTier();
     case 'redis':
       if (redisUrl(options.env) === undefined) {
         throw new CacheDriverUnavailableError({
@@ -97,7 +97,7 @@ function buildTier(name: CacheTierName, options: CacheTiersOptions): CacheTier {
           fix: 'set REDIS_URL in .env, or drop the redis tier from cache.tiers in app.config.ts',
         });
       }
-      return createRedisTier();
+      return redisTier();
     case 'cdn':
       // A noop tier would put a `cdn` line in every invalidation report claiming keys an edge that
       // does not exist had accepted — and the `/_x` cache panel renders those reports, so the lie
@@ -110,7 +110,7 @@ function buildTier(name: CacheTierName, options: CacheTiersOptions): CacheTier {
           fix: 'set FASTLY_API_TOKEN and FASTLY_SERVICE_ID in .env, or CLOUDFLARE_API_TOKEN and CLOUDFLARE_ZONE_ID, or drop the cdn tier from cache.tiers in app.config.ts',
         });
       }
-      return createCdnTier({ purge: options.purge });
+      return cdnTier({ purge: options.purge });
   }
 }
 

package/src/runtime-hooks.ts

@@ -2,7 +2,8 @@
 // decides for pages only, from the SAME `Policy` object every other surface evaluates — the route
 // table's declared permission — so a denial in `x dev` is the one production produces.
 
-import { actorOf, explainActionPathMiss } from '@ultimat3/action';
+import { explainActionPathMiss } from '@ultimat3/action';
+import { actorOf } from '@ultimat3/core';
 import type { AuthzDecision, ServerHooks } from '@ultimat3/http';
 import { asCtx, configuredAuthenticator } from '@ultimat3/http';
 import type { KnownPermission, Policy } from '@ultimat3/policy';

package/src/runtime-isr-outcome.ts

@@ -0,0 +1,100 @@
+// What one `isr` request is answered with: a page from the store, or the redirect ITS OWN `load`
+// decided. A returned discriminated outcome, never a throw: the controller's regeneration treats
+// anything thrown as a failure and logs it, and a redirect is an ordinary answer, not a failure.
+
+import type { RedirectIntent, RequestContext, RouteParams } from '@ultimat3/http';
+import { asCtx, takeRedirect } from '@ultimat3/http';
+import type { RenderResult, RouteData, RouteEntry } from '@ultimat3/render';
+import { routeDataFor, routeStatusOf } from '@ultimat3/render';
+import type { IsrController, IsrEntry } from '@ultimat3/render/server';
+import { isrKey } from '@ultimat3/render/server';
+
+export type IsrOutcome =
+  | { readonly kind: 'page'; readonly result: RenderResult }
+  | { readonly kind: 'redirect'; readonly to: RedirectIntent };
+
+export interface IsrRequest {
+  readonly entry: RouteEntry;
+  /** What `load` and `meta` are given; `url` is a string because that is what `ld.*` embeds. */
+  readonly data: { readonly url: string; readonly params: RouteParams } & Record<string, unknown>;
+  readonly ctx: RequestContext;
+  readonly isr: IsrController;
+  /** The route's whole document for what `load` returned (`runtime-render.ts`'s `documentFrom`). */
+  readonly document: (loaded: RouteData) => Promise<string>;
+}
+
+/**
+ * The producer's answer when `load` redirected. A 3xx status is never a page — `withStatus` refuses
+ * one by name, because a document has no `Location` — so a 3xx entry can only be this marker, and a
+ * request that JOINED the flight reads it as "the leader's load redirected for the leader".
+ */
+const isRedirectMarker = (entry: IsrEntry): boolean => {
+  // An entry stored before statuses were (`status` absent) is a 200, and never this marker.
+  const { status } = entry;
+  return status !== undefined && status >= 300 && status < 400;
+};
+
+/**
+ * A redirect means the key holds no page. Deleting drops the stale copy, so the next request is a
+ * miss and decides again. `markStale` records an invalidation of the key AFTER the regeneration's
+ * fence was sampled, and the controller refuses to store a render its fence no longer covers — so
+ * the marker this producer returns is never published, and never served from the store.
+ */
+function dropPage(isr: IsrController, key: string): void {
+  isr.store().delete(key);
+  isr.markStale(key);
+}
+
+/**
+ * `isr`: a store hit is answered WITHOUT `load` — resolving it before the mode choice, as every
+ * other mode does, made each hit cost a full SSR's database work. So `load` and its redirect live
+ * inside the producer, which runs on a miss and on a stale page's regeneration.
+ *
+ * Concurrent misses on one key share ONE producer run, and only a PAGE may be shared. A redirect is
+ * the request's own (its `load` may have read a cookie), so a request that joined a run whose load
+ * redirected decides for itself, exactly as the static single-flight in `appRoutes` does.
+ */
+export async function isrOutcome(request: IsrRequest): Promise<IsrOutcome> {
+  const { entry, data, ctx, isr } = request;
+  // `isrKey(url, locale)`, never `url.pathname`: the query is part of what was rendered — `meta`
+  // reads `data.url` — so two URLs differing only in their query are two documents (#171). The
+  // locale is `ctx.locale`, the one the `locale` stage negotiated for THIS request.
+  const key = isrKey(new URL(data.url), asCtx(ctx).locale);
+  let decided: RedirectIntent | undefined;
+  // `{ 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(key, async () => {
+    const loaded = await routeDataFor(entry.config, data);
+    const to = takeRedirect(ctx);
+    if (to === undefined)
+      return { html: await request.document(loaded), status: routeStatusOf(loaded) };
+    // Set by THIS request's producer only. On a stale page it runs behind the answer, and when it
+    // has already decided by the time `serve` returns, the redirect is still this request's own.
+    decided = to;
+    dropPage(isr, key);
+    return { html: '', status: to.status };
+  });
+  if (decided !== undefined) return { kind: 'redirect', to: decided };
+  if (!isRedirectMarker(served.entry)) return { kind: 'page', result: served.result };
+  return ownOutcome(request);
+}
+
+/**
+ * A joiner whose leader's load redirected: its own `load`, answered for this request alone. A page
+ * here is NOT stored — the store was just told the key has none — so it is `private, no-store`;
+ * the next request to miss stores one.
+ */
+async function ownOutcome(request: IsrRequest): Promise<IsrOutcome> {
+  const loaded = await routeDataFor(request.entry.config, request.data);
+  const to = takeRedirect(request.ctx);
+  if (to !== undefined) return { kind: 'redirect', to };
+  const body = await request.document(loaded);
+  return {
+    kind: 'page',
+    result: {
+      status: routeStatusOf(loaded),
+      headers: { 'cache-control': 'private, no-store' },
+      body,
+    },
+  };
+}

package/src/runtime-isr.ts

@@ -3,7 +3,7 @@
 // container, so neither can build a controller `invalidateTags` never reaches (plan 101, s2-con #1).
 
 import type { IsrController, IsrStore } from '@ultimat3/render/server';
-import { createIsrController } from '@ultimat3/render/server';
+import { isrController } from '@ultimat3/render/server';
 
 export interface AttachedIsr {
   readonly isr: IsrController;
@@ -19,7 +19,7 @@ export function attachedIsr(options: {
   readonly buildId: string;
   readonly store?: IsrStore;
 }): AttachedIsr {
-  const isr = createIsrController({
+  const isr = isrController({
     buildId: options.buildId,
     ...(options.store === undefined ? {} : { store: options.store }),
   });