@ultimat3/cli 27.7.0 → 27.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "27.7.0",
+  "version": "27.8.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -39,33 +39,33 @@
   },
   "dependencies": {
     "@babel/core": "^8.0.1",
-    "@ultimat3/action": "27.7.0",
-    "@ultimat3/admin": "27.7.0",
-    "@ultimat3/ai": "27.7.0",
-    "@ultimat3/auth": "27.7.0",
-    "@ultimat3/cache": "27.7.0",
-    "@ultimat3/core": "27.7.0",
-    "@ultimat3/db": "27.7.0",
-    "@ultimat3/entity": "27.7.0",
-    "@ultimat3/flags": "27.7.0",
-    "@ultimat3/http": "27.7.0",
-    "@ultimat3/i18n": "27.7.0",
-    "@ultimat3/jobs": "27.7.0",
-    "@ultimat3/mail": "27.7.0",
-    "@ultimat3/manifest": "27.7.0",
-    "@ultimat3/mcp": "27.7.0",
-    "@ultimat3/money": "27.7.0",
-    "@ultimat3/notify": "27.7.0",
-    "@ultimat3/policy": "27.7.0",
-    "@ultimat3/pwa": "27.7.0",
-    "@ultimat3/query": "27.7.0",
-    "@ultimat3/realtime": "27.7.0",
-    "@ultimat3/render": "27.7.0",
-    "@ultimat3/schema": "27.7.0",
-    "@ultimat3/seo": "27.7.0",
-    "@ultimat3/storage": "27.7.0",
-    "@ultimat3/testing": "27.7.0",
-    "@ultimat3/time": "27.7.0",
+    "@ultimat3/action": "27.8.0",
+    "@ultimat3/admin": "27.8.0",
+    "@ultimat3/ai": "27.8.0",
+    "@ultimat3/auth": "27.8.0",
+    "@ultimat3/cache": "27.8.0",
+    "@ultimat3/core": "27.8.0",
+    "@ultimat3/db": "27.8.0",
+    "@ultimat3/entity": "27.8.0",
+    "@ultimat3/flags": "27.8.0",
+    "@ultimat3/http": "27.8.0",
+    "@ultimat3/i18n": "27.8.0",
+    "@ultimat3/jobs": "27.8.0",
+    "@ultimat3/mail": "27.8.0",
+    "@ultimat3/manifest": "27.8.0",
+    "@ultimat3/mcp": "27.8.0",
+    "@ultimat3/money": "27.8.0",
+    "@ultimat3/notify": "27.8.0",
+    "@ultimat3/policy": "27.8.0",
+    "@ultimat3/pwa": "27.8.0",
+    "@ultimat3/query": "27.8.0",
+    "@ultimat3/realtime": "27.8.0",
+    "@ultimat3/render": "27.8.0",
+    "@ultimat3/schema": "27.8.0",
+    "@ultimat3/seo": "27.8.0",
+    "@ultimat3/storage": "27.8.0",
+    "@ultimat3/testing": "27.8.0",
+    "@ultimat3/time": "27.8.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/app-manifest.ts

@@ -113,10 +113,25 @@ const routeFacts = (): readonly RouteFact[] =>
       offline: route.offline,
       hydrate: route.hydrate,
       revalidateTags: route.revalidateTags,
+      ...revalidateOf(route),
       surface: route.surface,
       ...budgetOf(route),
     }));
 
+/** An `isr` route's invalidation and key facts — `onInvalidate` always, the other two as declared. */
+function revalidateOf(
+  route: RouteDescriptor,
+): Pick<RouteFact, 'onInvalidate' | 'maxStale' | 'query'> {
+  if (route.mode !== 'isr') return {};
+  const maxStale = route.revalidateMaxStale ?? null;
+  const query = route.revalidateQuery ?? null;
+  return {
+    onInvalidate: route.revalidateOnInvalidate ?? 'stale',
+    ...(maxStale === null ? {} : { maxStale }),
+    ...(query === null ? {} : { query }),
+  };
+}
+
 function budgetOf(route: RouteDescriptor): { budget?: { js: string } } {
   return route.budgetJs === null ? {} : { budget: { js: route.budgetJs } };
 }

package/src/dev-boot.ts

@@ -120,6 +120,8 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
     appRuntime,
     'apply',
     options.roles ?? DEV_ROLES,
+    // Every role in one process: a bus that is away must not take the pages down with it.
+    true,
   );
   // The events binding the boot line reports is the bus the runtime chose, read off it.
   const services = withRealtimeEvents(resolved, env, runtime.realtime);

package/src/isr-query-advice.ts

@@ -0,0 +1,63 @@
+// What `x verify` says about the query an `isr` route keys on. Advice and not a finding: the scan
+// reads source text, so it can miss a read made through a helper and can name one that is not a
+// query read at all — and a route that declared nothing works as it always did. Both are exactly
+// what a reader should hear about before a visitor finds it.
+
+// why: Bun exposes no path-join primitive; Bun.file takes one already joined.
+import { join } from 'node:path';
+import { stripComments } from '@ultimat3/core';
+import { describePages } from '@ultimat3/render';
+import { msg } from './messages';
+
+const MEMBER_READ = /\bquery\s*\??\.\s*([A-Za-z_$][\w$]*)\b(?!\s*\()/g;
+const BRACKET_READ = /\bquery\s*(?:\?\.)?\[\s*['"]([^'"]+)['"]\s*\]/g;
+const SEARCH_PARAM_READ = /\bsearchParams\s*\??\.\s*(?:get|getAll|has)\(\s*['"]([^'"]+)['"]/g;
+
+/**
+ * The query parameter names a route module reads, as far as its text says: `query.name`,
+ * `query?.name`, `query['name']` and `searchParams.get('name')` (also `getAll`, `has`). A call
+ * (`query.where(…)`) is a method, not a parameter. Sorted, each once.
+ */
+export function queryReads(source: string): readonly string[] {
+  const code = stripComments(source);
+  const names = new Set<string>();
+  for (const pattern of [MEMBER_READ, BRACKET_READ, SEARCH_PARAM_READ]) {
+    for (const match of code.matchAll(pattern)) {
+      if (match[1] !== undefined) names.add(match[1]);
+    }
+  }
+  return [...names].sort();
+}
+
+const listed = (names: readonly string[]): string => names.map((name) => `'${name}'`).join(', ');
+
+/**
+ * One line per `isr` route with no `revalidate.query` — it renders and stores a page for every
+ * distinct query string, so `?x=1`, `?x=2`, … evict its real pages and cost a render each — and
+ * one per parameter a route's module reads and its declaration omits: the page is stored under a
+ * key without it, so every visitor gets the document rendered for whichever value arrived first.
+ */
+export async function isrQueryAdvice(root: string): Promise<readonly string[]> {
+  const advice: string[] = [];
+  for (const route of describePages()) {
+    if (route.mode !== 'isr') continue;
+    const declared = route.revalidateQuery ?? null;
+    if (declared === null) {
+      advice.push(msg('cli.verify.isrQueryUndeclared', { file: route.file }));
+      continue;
+    }
+    const module = Bun.file(join(root, route.file));
+    if (!(await module.exists())) continue;
+    for (const name of queryReads(await module.text())) {
+      if (declared.includes(name)) continue;
+      advice.push(
+        msg('cli.verify.isrQueryOmitted', {
+          file: route.file,
+          name,
+          declared: listed([...declared, name].sort()),
+        }),
+      );
+    }
+  }
+  return advice;
+}

package/src/isr-query-guard.ts

@@ -0,0 +1,49 @@
+// The `query` object a page component is handed. For an `isr` route that declared
+// `revalidate.query` it holds the declared parameters only — and, outside production, it says so
+// once when the page reads any other one: that read is a document varying on something its stored
+// key does not carry, which is one visitor's page answered to every visitor after.
+
+import type { ResolveEnvironmentOptions } from '@ultimat3/core';
+import { logger, tryResolveEnvironment } from '@ultimat3/core';
+import type { RouteEntry } from '@ultimat3/render';
+
+type Query = Readonly<Record<string, string>>;
+
+/** `<route file>\u0000<parameter>` already told — bounded by what the app's source can read. */
+const told = new Set<string>();
+
+/** Names every object answers and a renderer or a serializer may ask for: never a parameter. */
+const isProbe = (name: string): boolean =>
+  name in Object.prototype || name === 'then' || name === 'toJSON';
+
+export function routeQuery(
+  entry: RouteEntry,
+  url: URL,
+  env?: ResolveEnvironmentOptions['env'],
+): Query {
+  const query: Query = Object.fromEntries(url.searchParams);
+  const declared = entry.config.render === 'isr' ? entry.config.revalidate?.query : undefined;
+  if (declared === undefined) return query;
+  // Production pays nothing: the plain object, no trap. (`undefined`: an unreadable environment,
+  // which is not a development one either.)
+  const environment = tryResolveEnvironment(env === undefined ? undefined : { env });
+  if (environment === 'production' || environment === undefined) return query;
+  return new Proxy(query, {
+    get(target, name, receiver) {
+      if (typeof name === 'string' && !declared.includes(name) && !isProbe(name)) {
+        const key = `${entry.file}\u0000${name}`;
+        if (!told.has(key)) {
+          told.add(key);
+          const widened = [...declared, name].sort().map((one) => `'${one}'`);
+          logger.warn('isr.query.unkeyed-read', {
+            route: entry.file,
+            param: name,
+            cause: `the page read query.${name}, and revalidate.query does not list it — the stored page is keyed without it, so every visitor gets the document rendered for whichever value arrived first`,
+            fix: `query: [${widened.join(', ')}]   // in revalidate, in ${entry.file}`,
+          });
+        }
+      }
+      return Reflect.get(target, name, receiver);
+    },
+  });
+}

package/src/messages.ts

@@ -328,6 +328,10 @@ const CATALOG = {
   // counts — so the line says how many and `x test <type>` prints the names.
   'cli.verify.allSkipped': 'found {skipped} test(s) and every one skipped itself',
   'cli.verify.warnings': '{count} warning(s) — --verbose or --json lists them',
+  'cli.verify.isrQueryUndeclared':
+    "{file}: render 'isr' with no revalidate.query — its stored pages are keyed on the whole query string, so any visitor can mint one per request. Declare revalidate: { query: [] } (or the parameters the page varies on)",
+  'cli.verify.isrQueryOmitted':
+    '{file}: reads the query parameter "{name}", which revalidate.query does not list — the page is stored under a key without it, so every visitor gets the document rendered for whichever value arrived first. Declare query: [{declared}], or stop reading it',
   // The other shape the same counts can take: a suite that reported no test at all, skipped ones
   // included. Its own line and not `allSkipped` with a zero, because the repair differs — there is
   // no skipped test to read a reason off, so the files the step selected hold no test.

package/src/role-sync-bus-wait.ts

@@ -0,0 +1,66 @@
+// Single responsibility: what the `sync` role does when its node cannot start because the bus is
+// away. A `ROLE=sync` container refuses its boot — it has nothing to serve without the bus.
+// `x dev` runs every role in one process, so there the node stays mounted and NOT ready, and is
+// started when the bus answers: the pages, the worker and the scheduler never went down with it.
+
+import { isUltimateError, logger } from '@ultimat3/core';
+import type { SyncNode, Transport } from '@ultimat3/realtime/server';
+
+export interface BusWaitRuntime {
+  readonly transport: Pick<Transport, 'onReconnect'>;
+  /** `RunningServices.busTolerated`: the boot is `x dev`, and a bus that is away is waited for. */
+  readonly busTolerated?: boolean | undefined;
+}
+
+/**
+ * Start the node, or — tolerated, with the bus away — leave it unstarted and start it on the
+ * transport's next recovery. Until then an upgrade is shed with a 503 and a retry delay
+ * (`sync-upgrade.ts`), so an open page keeps asking and goes live with no restart. Any other
+ * refusal, and every refusal outside `x dev`, is the boot's. Returns what stops the wait.
+ */
+export async function startOrWaitForBus(
+  node: Pick<SyncNode, 'start'>,
+  runtime: BusWaitRuntime,
+): Promise<() => void> {
+  const refused = await node.start().then(
+    () => undefined,
+    (error: unknown) => ({ error }),
+  );
+  if (refused === undefined) return () => undefined;
+  const { error } = refused;
+  if (
+    runtime.busTolerated !== true ||
+    !isUltimateError(error) ||
+    error.code !== 'X_TRANSPORT_UNAVAILABLE'
+  ) {
+    throw error;
+  }
+  // Once, with the refusal a container would have exited on.
+  logger.warn('sync node is waiting for the bus: sockets are refused until it answers', {
+    code: error.code,
+    cause: error.cause,
+    fix: error.fix,
+  });
+  let waiting = true;
+  let off = (): void => undefined;
+  const attempt = (): void => {
+    if (!waiting) return;
+    void node.start().then(
+      () => {
+        if (!waiting) return;
+        waiting = false;
+        off();
+        logger.info('sync node started: the bus answered');
+      },
+      // Still away, or away again: the next recovery asks once more.
+      () => undefined,
+    );
+  };
+  off = runtime.transport.onReconnect(attempt);
+  // The dial may have landed between the refusal and the line above; asking again costs nothing.
+  attempt();
+  return () => {
+    waiting = false;
+    off();
+  };
+}

package/src/role-sync.ts

@@ -26,6 +26,7 @@ import {
 import { neighbouringPort, PORT_RANGE, portPairAfter } from './flag-number';
 import { portFree } from './port-probe';
 import type { StartRolesOptions } from './role-start';
+import { startOrWaitForBus } from './role-sync-bus-wait';
 import type { Env } from './runtime-bindings';
 import { syncAuthenticator } from './sync-authenticator';
 import { syncOriginsFrom } from './sync-url';
@@ -327,14 +328,17 @@ export async function prepareSync(options: StartRolesOptions): Promise<PreparedS
       ttlMs: options.runtime.presenceTtlMs,
     }),
   });
-  await node.start();
+  const stopWaiting = await startOrWaitForBus(node, options.runtime);
   return {
     node,
     registry,
     // The node's OWN path, asked rather than restated: `SyncNodeOptions.path` is settable and a
     // second copy of `/_x/sync` here is the copy that stays behind when it moves.
     mount: { path: node.path, fetch: node.fetch, websocket: node.websocket },
-    stop: () => node.stop(),
+    stop: async () => {
+      stopWaiting();
+      await node.stop();
+    },
     listen: async (appUrl) => {
       origins.push(...devOrigins(options, origins, appUrl));
       return await listen(options, node, { registry, hub }, appUrl);

package/src/runtime-bus.ts

@@ -8,9 +8,15 @@
 // the background and a dead one is `degraded`: the pod still boots, serves and runs jobs. Until
 // 2026-10 every role awaited the dial and the JetStream bucket, so a web pod that restarted while
 // NATS was down took the app's pages, webhooks and send jobs down with a feature none of them use.
+//
+// `x dev` is the one boot that TOLERATES a missing bus for a role that serves from it: it runs
+// every role in one process, so the `sync` role's refusal took the pages, the worker and the
+// scheduler down with it — the same outage, on the developer's own machine. There the refusal is
+// logged once, coded, the dial goes on in the background, and the pages run without live until it
+// lands. A `ROLE=sync` container keeps the hard refusal: it has nothing else to serve.
 
 import type { RealtimeConfig, Role } from '@ultimat3/core';
-import { logger, registerReadinessCheck } from '@ultimat3/core';
+import { isUltimateError, logger, registerReadinessCheck } from '@ultimat3/core';
 import type { BusUse, SelectTransportOptions, Transport } from '@ultimat3/realtime/server';
 import { selectTransport, setChannelTransport } from '@ultimat3/realtime/server';
 import type { Env } from './runtime-bindings';
@@ -55,8 +61,20 @@ export interface RunningBus {
   stop(): Promise<void>;
 }
 
+/**
+ * How long `x dev` waits for a bus its realtime roles need before it boots without one. Short on
+ * purpose: a NATS started beside it is reachable by then, and one that is not is dialled in the
+ * background anyway.
+ */
+export const DEV_BUS_WAIT_MS = 3_000;
+
 export interface SelectedBus {
   readonly use: BusUse;
+  /**
+   * `x dev` with a role that serves from the bus: a bus that is away is waited for in the
+   * background rather than refused (`RunningServices.busTolerated`).
+   */
+  readonly tolerant: boolean;
   /** What the sync role must give `PresenceRegistry` (`RunningServices.presenceTtlMs`). */
   readonly presenceTtlMs: number;
   /**
@@ -76,6 +94,8 @@ export interface SelectBusInput {
   readonly override?: Transport | undefined;
   /** Injected by a test: a fake dial, a short wait. */
   readonly select?: SelectTransportOptions | undefined;
+  /** The boot is `x dev`: every role in one process, on the developer's machine. */
+  readonly dev?: boolean | undefined;
 }
 
 /**
@@ -84,9 +104,15 @@ export interface SelectBusInput {
  */
 export function selectBus(input: SelectBusInput): SelectedBus {
   const use = busUseFor(input.roles, input.realtime);
-  const selection = selectTransport(input.env, input.realtime, { ...input.select, use });
+  const tolerant = input.dev === true && use !== 'publish';
+  const selection = selectTransport(input.env, input.realtime, {
+    ...(tolerant ? { connectWithinMs: DEV_BUS_WAIT_MS } : {}),
+    ...input.select,
+    use,
+  });
   return {
     use,
+    tolerant,
     presenceTtlMs: selection.presenceTtlMs,
     async start(): Promise<RunningBus> {
       const started: (() => void | Promise<void>)[] = [];
@@ -109,7 +135,20 @@ export function selectBus(input: SelectBusInput): SelectedBus {
           // Before the dial, not after: a dial refused for being late is still in flight inside
           // the client library, and closing the transport is what releases whatever it lands as.
           started.push(() => selection.transport.close());
-          await selection.connect();
+          try {
+            await selection.connect();
+          } catch (error) {
+            if (!tolerant || !isUltimateError(error) || error.code !== 'X_TRANSPORT_UNAVAILABLE') {
+              throw error;
+            }
+            // Said ONCE, with the refusal a container would have exited on. The transport is not
+            // closed: its dial loop goes on, and `ultimate bus` is the line that says it landed.
+            logger.warn('ultimate bus is away: x dev serves without live until it answers', {
+              code: error.code,
+              cause: error.cause,
+              fix: error.fix,
+            });
+          }
           transport = selection.transport;
         }
         // The bus an app's own code publishes a channel event on (`publishChannelEvent`), in EVERY
@@ -129,7 +168,8 @@ export function selectBus(input: SelectBusInput): SelectedBus {
               () => connectable.connected,
               // A publisher serves without the bus, so losing it must not pull the pod from the
               // ingress — it is reported, and `/readyz?deep=1` is where a monitor reads it.
-              { onFailure: use === 'publish' ? 'degraded' : 'failing' },
+              // `x dev` serves its pages from the same process: its bus is a degradation too.
+              { onFailure: use === 'publish' || tolerant ? 'degraded' : 'failing' },
             ),
           );
           // Each time the bus comes (back) up, on one line: the boot line may have said

package/src/runtime-cache.ts

@@ -12,6 +12,7 @@ import {
   isNoopPurgeDriver,
   lruTier,
   memoTier,
+  purgeEdgeAgain,
   receiveInvalidationBroadcast,
   redisTier,
   registerInvalidationBroadcast,
@@ -19,7 +20,13 @@ import {
   resetTiers,
 } from '@ultimat3/cache';
 import type { AppConfig, CacheTierName } from '@ultimat3/core';
-import { backoffDelay, defineConfig, logger, renderThrowable } from '@ultimat3/core';
+import {
+  backoffDelay,
+  defineConfig,
+  isOutageMilestone,
+  logger,
+  renderThrowable,
+} from '@ultimat3/core';
 import type { Transport, TransportSubscription } from '@ultimat3/realtime/server';
 import type { Env } from './runtime-bindings';
 
@@ -206,6 +213,11 @@ export function startCacheTiers(options: CacheTiersOptions): () => Promise<void>
       defer(batch);
       throw error;
     }
+    // The edge AGAIN, now that the peers are finally being told. It was purged when the bust ran,
+    // but every peer still held its copy then, and each request one of them answered since handed
+    // the edge the old page back — with no purge left to come. (Each peer purges after its own
+    // delete too; this is the sender's half, and does not depend on hearing its own publish.)
+    await purgeEdgeAgain(batch);
   };
   // ONE settle at a time. It is asked for by every reconnect and after every accepted publish,
   // and two that overlapped both published the same batch (and the same flush-all). A call that
@@ -274,12 +286,16 @@ export function startCacheTiers(options: CacheTiersOptions): () => Promise<void>
           },
         );
         subscribed = true;
-        if (attempt > 1) flushDeaf('cache.bus-subscribed');
+        if (attempt > 1) {
+          // The outage's one closing line, beside the thinned warnings it ends.
+          logger.info('cache.broadcast.subscribe-failed recovered', { after: attempt - 1 });
+          flushDeaf('cache.bus-subscribed');
+        }
         return subscription;
       } catch (error) {
         // Attempts 1, 2, 4, 8, …: the dial's own thinning (`NatsTransport`), so an outage is not
         // one line per retry per pod for as long as it lasts.
-        if ((attempt & (attempt - 1)) === 0) {
+        if (isOutageMilestone(attempt)) {
           logger.warn('cache.broadcast.subscribe-failed', {
             error: broadcastErrorText(error),
             attempt,

package/src/runtime-isr-outcome.ts

@@ -2,25 +2,66 @@
 // 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 { logger } from '@ultimat3/core';
 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 { routeDataFor, routeNoStoreOf, routeStatusOf } from '@ultimat3/render';
 import type { IsrController, IsrEntry } from '@ultimat3/render/server';
-import { isrKey } from '@ultimat3/render/server';
+import { isrKey, isrRequestUrl, undeclaredQuery } from '@ultimat3/render/server';
 
 export type IsrOutcome =
   | { readonly kind: 'page'; readonly result: RenderResult }
   | { readonly kind: 'redirect'; readonly to: RedirectIntent };
 
+/** What `load` and `meta` are given; `url` is a string because that is what `ld.*` embeds. */
+type IsrData = { readonly url: string; readonly params: RouteParams } & Record<string, unknown>;
+
 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>;
+  /** The request as it arrived. `load`, `meta` and the page get `keyedData`'s narrowing of it. */
+  readonly data: IsrData;
   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 route's whole document for what `load` returned (`runtime-render.ts`'s `documentFrom`),
+   * rendered AT the data this file hands it — the narrowed URL, never the request's own.
+   */
+  readonly document: (loaded: RouteData, at: IsrData) => Promise<string>;
+}
+
+/** Route files already told, once, about a request whose query they never declared. */
+const toldUndeclared = new Set<string>();
+
+/** Names are the visitor's: a few, cut short, is all a log line needs to name the edit. */
+const NAMED_PARAMS = 5;
+const NAMED_PARAM_CHARS = 40;
+
+/**
+ * The request narrowed to what the route declared it varies on (`revalidate.query`). ONE narrowing
+ * feeds the store key, `load`, `meta` and the page, so a parameter outside the key cannot reach
+ * the document stored under it.
+ *
+ * A route that declared NOTHING still keys on the whole query, and is told so once, the first time
+ * a visitor uses that: every distinct query string is then a render and a stored page of its own.
+ */
+function keyedData(entry: RouteEntry, data: IsrData): IsrData {
+  const url = new URL(data.url);
+  const declared = entry.config.revalidate?.query ?? null;
+  if (declared === null && !toldUndeclared.has(entry.file)) {
+    const minted = undeclaredQuery(url, declared);
+    if (minted.length > 0) {
+      toldUndeclared.add(entry.file);
+      logger.warn('isr.query.undeclared', {
+        route: entry.file,
+        params: minted.slice(0, NAMED_PARAMS).map((name) => name.slice(0, NAMED_PARAM_CHARS)),
+        cause:
+          'the route declares no revalidate.query, so every distinct query string is rendered and stored as its own page',
+        fix: `revalidate: { query: [] }   // in ${entry.file}; or query: ['<name>'] for each parameter the page varies on`,
+      });
+    }
+  }
+  return { ...data, url: isrRequestUrl(url, declared).href };
 }
 
 /**
@@ -54,11 +95,12 @@ function dropPage(isr: IsrController, key: string): void {
  * 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> {
+export async function isrOutcome(arrived: IsrRequest): Promise<IsrOutcome> {
+  const request: IsrRequest = { ...arrived, data: keyedData(arrived.entry, arrived.data) };
   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.
+  // `isrKey(url, locale)`, never `url.pathname`: the DECLARED query is part of what was rendered —
+  // `meta` reads `data.url` — so two URLs differing in it 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
@@ -66,8 +108,13 @@ export async function isrOutcome(request: IsrRequest): Promise<IsrOutcome> {
   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) };
+    if (to === undefined) {
+      return {
+        html: await request.document(loaded, data),
+        status: routeStatusOf(loaded),
+        noStore: routeNoStoreOf(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;
@@ -88,7 +135,7 @@ 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);
+  const body = await request.document(loaded, request.data);
   return {
     kind: 'page',
     result: {

package/src/runtime-isr.ts

@@ -2,6 +2,7 @@
 // and handed back with the detach the boot puts on its stop list. One function for `x dev` and the
 // container, so neither can build a controller `invalidateTags` never reaches (plan 101, s2-con #1).
 
+import { describePages, RouteModeInvalidError } from '@ultimat3/render';
 import type { IsrController, IsrStore } from '@ultimat3/render/server';
 import { isrController } from '@ultimat3/render/server';
 
@@ -18,10 +19,16 @@ export interface AttachedIsr {
 export function attachedIsr(options: {
   readonly buildId: string;
   readonly store?: IsrStore;
+  /** `isrController`'s own; a test turns the cooldown off rather than waiting one out. */
+  readonly failureCooldownMs?: number;
 }): AttachedIsr {
+  if (options.store !== undefined) assertPurgeSafe(options.store);
   const isr = isrController({
     buildId: options.buildId,
     ...(options.store === undefined ? {} : { store: options.store }),
+    ...(options.failureCooldownMs === undefined
+      ? {}
+      : { failureCooldownMs: options.failureCooldownMs }),
   });
   const detach = isr.attach();
   let released = false;
@@ -34,3 +41,19 @@ export function attachedIsr(options: {
     },
   };
 }
+
+/**
+ * A store the deployment supplied is one other processes may write. Under `onInvalidate: 'purge'`
+ * a replica that began a render before the purge, and has not heard of it yet, writes the purged
+ * page back unless the STORE refuses the write (`IsrStore.tagFence`) — its own fence only knows
+ * the busts it was told about. Refused here, by route, rather than left to happen in production.
+ */
+function assertPurgeSafe(store: IsrStore): void {
+  if (store.tagFence !== undefined) return;
+  const purging = describePages().find((route) => route.revalidateOnInvalidate === 'purge');
+  if (purging === undefined) return;
+  throw new RouteModeInvalidError(
+    `${purging.file} declares revalidate.onInvalidate: 'purge', and the runtime's isrStore has no tagFence — a replica whose render began before a purge would write the purged page back into it`,
+    'tagFence: { sample, bump, setIfCurrent }   // implement IsrTagFence on the isrStore in apps/web/runtime.ts (setIfCurrent atomic in the store), or drop isrStore to keep one memory store per replica',
+  );
+}

package/src/runtime-render.ts

@@ -45,6 +45,7 @@ import {
   streamResult,
 } from '@ultimat3/render/server';
 import type { DocumentOptions } from './document-options';
+import { routeQuery } from './isr-query-guard';
 import {
   type NavigationDocumentHead,
   navigationMetaOf,
@@ -193,7 +194,7 @@ export async function routeBody(
       data,
       params: ctx.params,
       url: ctx.url,
-      query: Object.fromEntries(url.searchParams) as Readonly<Record<string, string>>,
+      query: routeQuery(entry, url),
     },
     entry.file,
     { islands },
@@ -486,8 +487,8 @@ async function renderIsr(
   options: DevRenderOptions,
   isr: IsrController,
 ): Promise<Rendered> {
-  const document = (loaded: RouteData): Promise<string> =>
-    documentFrom(entry, data, loaded, options);
+  const document = (loaded: RouteData, at: DevRouteData): Promise<string> =>
+    documentFrom(entry, at, 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-services.ts

@@ -80,6 +80,8 @@ export interface RunningServices {
    * (`runtime-bus.ts`). Optional for the reason `workerConfig` is: a hand-built runtime has none.
    */
   readonly busUse?: BusUse;
+  /** `x dev` booted without a bus its `sync` role needs: that role waits for it (`role-sync.ts`). */
+  readonly busTolerated?: boolean;
   /**
    * What the sync role must give `PresenceRegistry`. It travels with the transport because the KV
    * bucket's age limit was derived from it — a registry given a longer TTL than the bucket honours
@@ -327,6 +329,8 @@ export async function startServices(
    * `sync` node or a replicator does (`runtime-bus.ts`). Unset is the strictest reading.
    */
   roles?: readonly Role[],
+  /** `x dev`: a bus the realtime roles need is waited for in the background, never refused. */
+  dev = false,
 ): 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.
@@ -350,7 +354,7 @@ export async function startServices(
   // signs one probe — a deploy with no keys, or two halves of different pairs, refuses here.
   const push = await selectWebPush(config, env);
   const workerConfig = workerConfigOf(config, env);
-  const bus = selectBus({ env, realtime, roles, override: overrides?.transport });
+  const bus = selectBus({ env, realtime, roles, override: overrides?.transport, dev });
   // `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.
@@ -458,6 +462,7 @@ export async function startServices(
       rateLimitStore,
       transportDetail: running.detail,
       busUse: bus.use,
+      busTolerated: bus.tolerant,
       presenceTtlMs: bus.presenceTtlMs,
       purge,
       purgeDetail: cdn.detail,

package/src/seo-routes.ts

@@ -2,7 +2,14 @@
 // role — the files the static export writes, for a deploy that serves its pages from a container.
 // Mounted by `x dev` and `runRole` alike, before the app's pages, for `style-routes.ts`' reason.
 
-import { DEFAULT_ENVIRONMENT, type Environment, tryResolveEnvironment } from '@ultimat3/core';
+import {
+  DEFAULT_ENVIRONMENT,
+  type Environment,
+  finiteCount,
+  logger,
+  renderThrowable,
+  tryResolveEnvironment,
+} from '@ultimat3/core';
 import type { Route, UltimateRequest } from '@ultimat3/http';
 import { applyCacheHeaders, jsonResponse, NO_STORE } from '@ultimat3/http';
 import { SITEMAP_PARTS_DIR } from '@ultimat3/seo';
@@ -17,6 +24,10 @@ export interface SeoRoutesOptions {
   readonly site?: SiteSettings;
   /** The app root route files are relative to — `seo.sitemap.lastmod: 'git' | 'mtime'` reads them. */
   readonly root?: string;
+  /** The memo's clock, in ms. Injected so an hour's expiry is provable without waiting one out. */
+  readonly now?: () => number;
+  /** How long one enumeration may run, in ms. Injected so a hung one is provable in a test. */
+  readonly enumerationTimeoutMs?: number;
 }
 
 /**
@@ -43,11 +54,28 @@ const SEO_CACHE = { mode: 'public', maxAgeSeconds: 3600 } as const;
  */
 const SEO_MEMO_ORIGINS = 8;
 
+/** How soon a failed re-enumeration is asked again while the previous answer keeps being served. */
+const SEO_RETRY_MS = 60_000;
+
+/** How long one enumeration may run before its origin stops waiting on it. */
+const SEO_ENUMERATION_TIMEOUT_MS = 30_000;
+
+/** Consecutive failed refreshes after which `seo.enumeration.kept` is logged as an error. */
+const SEO_FAILURES_BEFORE_ERROR = 3;
+
 interface Memo {
-  readonly at: number;
-  readonly answer: Promise<SiteSeo>;
+  at: number;
+  answer: Promise<SiteSeo>;
+  /** A refresh is running behind `answer`. */
+  refreshing: boolean;
+  /** The first enumeration has answered — only then is there something to refresh BEHIND. */
+  settled: boolean;
+  failures: number;
 }
 
+/** A placeholder for the one statement between building a first memo and starting its enumeration. */
+const NO_ANSWER: SiteSeo = { robots: '', sitemaps: [] };
+
 export function seoRoutes(options: SeoRoutesOptions): readonly Route[] {
   const environment: Environment =
     tryResolveEnvironment({ env: options.env }) ?? DEFAULT_ENVIRONMENT;
@@ -59,26 +87,98 @@ export function seoRoutes(options: SeoRoutesOptions): readonly Route[] {
       ...(options.site === undefined ? {} : { sitemap: options.site.sitemap }),
       ...(options.root === undefined ? {} : { root: options.root }),
     });
-  // Single-flight per origin: concurrent requests share the one computation in progress. A failed
-  // one is dropped, so the next request asks again rather than serving the failure for an hour.
+  // One answer per origin. A FIRST enumeration is single-flight and awaited; failed, it is dropped,
+  // so the next request asks again rather than serving the failure for an hour.
+  //
+  // A LATER one — the hourly refresh — runs BEHIND the answer it would replace, and every request
+  // meanwhile is served that answer: `prerender()` reads rows, and a database blip at the hour
+  // mark otherwise answered a crawler a 500, while a read that HUNG held every sitemap request on
+  // its pending promise. A failed or timed-out refresh keeps the last good sitemap and is asked
+  // again a minute later. A `prerender()` that THROWS on a failed read is what makes this hold:
+  // one that catches its own error and returns `[]` is a successful enumeration of nothing.
   const memo = new Map<string, Memo>();
+  const clock = options.now ?? Date.now;
+  const timeoutMs = finiteCount(
+    'seoRoutes',
+    'enumerationTimeoutMs',
+    options.enumerationTimeoutMs ?? SEO_ENUMERATION_TIMEOUT_MS,
+    1,
+  );
+
+  /** `compute`, settled at most once: with the answer, or `undefined` for a failure or a timeout. */
+  const enumerate = (
+    origin: string,
+    settle: (answer: SiteSeo | undefined, why: string) => void,
+  ) => {
+    let settled = false;
+    const once = (answer: SiteSeo | undefined, why: string): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      settle(answer, why);
+    };
+    const timer = setTimeout(() => {
+      once(undefined, `no answer within ${String(timeoutMs)}ms`);
+    }, timeoutMs);
+    const computed = compute(origin);
+    computed.then(
+      (answer) => once(answer, ''),
+      (error: unknown) => once(undefined, renderThrowable(error)),
+    );
+    return computed;
+  };
+
+  const refresh = (origin: string, kept: Memo): void => {
+    kept.refreshing = true;
+    void enumerate(origin, (answer, why) => {
+      if (memo.get(origin) !== kept) return;
+      if (answer !== undefined) {
+        memo.set(origin, {
+          at: clock(),
+          answer: Promise.resolve(answer),
+          refreshing: false,
+          settled: true,
+          failures: 0,
+        });
+        return;
+      }
+      kept.refreshing = false;
+      kept.failures += 1;
+      kept.at = clock() - SEO_CACHE.maxAgeSeconds * 1000 + SEO_RETRY_MS;
+      // A blip is a warning; a sitemap that has not refreshed for several tries is going stale.
+      const fields = { origin, failures: kept.failures, error: why };
+      if (kept.failures >= SEO_FAILURES_BEFORE_ERROR) logger.error('seo.enumeration.kept', fields);
+      else logger.warn('seo.enumeration.kept', fields);
+    }).catch(() => undefined);
+  };
+
   const answer = (request: UltimateRequest): Promise<SiteSeo> => {
     const origin = originOf(options, request);
-    const now = Date.now();
     const kept = memo.get(origin);
-    if (kept !== undefined && now - kept.at < SEO_CACHE.maxAgeSeconds * 1000) return kept.answer;
-    memo.delete(origin);
+    if (kept !== undefined) {
+      const expired = clock() - kept.at >= SEO_CACHE.maxAgeSeconds * 1000;
+      if (expired && !kept.refreshing && kept.settled) refresh(origin, kept);
+      return kept.answer;
+    }
     if (memo.size >= SEO_MEMO_ORIGINS) {
       const oldest = memo.keys().next().value;
       if (oldest !== undefined) memo.delete(oldest);
     }
-    const computed = compute(origin);
-    memo.set(origin, { at: now, answer: computed });
-    // Voided: the request awaits `computed` itself and reports its failure; this branch only forgets it.
-    void computed.catch(() => {
-      if (memo.get(origin)?.answer === computed) memo.delete(origin);
+    const first: Memo = {
+      at: clock(),
+      answer: Promise.resolve(NO_ANSWER),
+      refreshing: false,
+      settled: false,
+      failures: 0,
+    };
+    // The request awaits the enumeration itself and reports its failure; a failed or hung one is
+    // only forgotten here, so the next request starts its own rather than joining it.
+    first.answer = enumerate(origin, (found) => {
+      first.settled = true;
+      if (found === undefined && memo.get(origin) === first) memo.delete(origin);
     });
-    return computed;
+    memo.set(origin, first);
+    return first.answer;
   };
 
   return [

package/src/verify-checks.ts

@@ -23,6 +23,7 @@ import { checkDocumentStyles, documentSurfaces } from './document-styles';
 import { checkErrorCodeResolution, checkErrorFixReport } from './error-contract';
 import { guardFindings } from './guards';
 import { catalogFindings } from './i18n-registration';
+import { isrQueryAdvice } from './isr-query-advice';
 import { unregisteredJobFindings } from './job-registration';
 import { liveRouteFindings } from './live-routes';
 import { withLoadFindings, withoutLoadFindings } from './load-findings';
@@ -292,9 +293,13 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
       // such key), so canonical checks are skipped rather than run against an origin this file
       // invented. `seo-meta.ts` spells out why that is the honest half.
       const report = validateMeta(scan.records);
+      // The scan filled the route table, so the advice costs no second load. Rides here because
+      // this is the step about public, shared-cache pages; it never fails it.
+      const warnings = await isrQueryAdvice(ctx.root);
       return {
         ok: scan.findings.length === 0 && report.ok,
         findings: [...scan.findings, ...report.issues.map(seoFinding)],
+        ...(warnings.length === 0 ? {} : { warnings }),
       };
     },
   },