@ultimat3/render 27.7.0 → 27.8.1

package/CLAUDE.md

@@ -77,7 +77,7 @@ axiom 6). Never `cli` (upward).
 | "Is this a TTL?" has one reader | `parseTtlMs` in `duration.ts`, below `modes.ts` and `render-isr.ts`. |
 | A build-time frame reads a throw with `renderThrowable` | `render-html.ts`, `render-static.ts`, `css-modules.ts`, `module-loader.ts`, `route-data.ts`. `bun run error-render` cannot see a value laundered through a local helper. |
 | `X_ROUTE_LOAD_FAILED` computes its pathname BEFORE the try | `pathnameOf` never throws on a relative `ctx.url`. |
-| The ISR key | `isrKey(url, locale)` — pathname, the negotiated locale in the reserved `__x_locale` parameter, then the sorted query. The locale is REQUIRED. The time zone is deliberately not a dimension. `toResult` emits `vary: accept-language`, and `surrogate-key`/`cache-tag` from `@ultimat3/cache`'s `surrogateKeys()` over the route's `revalidateTags` — kept only while the response stays shared: http's `applyCacheHeaders` strips both on a rewrite to `private`/`no-store`. `registry.ts`'s `assertPurgeableTags` screens the tags at registration (`X_ROUTE_MODE_INVALID`); the rest of the shared key is `@ultimat3/http`'s `cache-headers` stage. The one shipped emitter of purge keys; file and mounted routes are both screened, so `toResult` never refuses on the request path |
+| The ISR key | `isrKey(url, locale)` — the path in http's `canonicalPath` spelling (no base path), the locale in the reserved `__x_locale` parameter, the sorted query. A key no route owns is never stored. The locale is REQUIRED. The time zone is deliberately not a dimension. `toResult` emits `vary: accept-language`, and `surrogate-key`/`cache-tag` from `@ultimat3/cache`'s `surrogateKeys()` over the route's `revalidateTags` — kept only while the response stays shared: http's `applyCacheHeaders` strips both on a rewrite to `private`/`no-store`. `registry.ts`'s `assertPurgeableTags` screens the tags at registration (`X_ROUTE_MODE_INVALID`); the rest of the shared key is `@ultimat3/http`'s `cache-headers` stage. File and mounted routes are both screened |
 | A bust that lands MID-render | fenced with `@ultimat3/cache`'s `sampleFence({ key, tags })`, taken before `render()` and asked before `store.set`. `registerPath` runs BEFORE the render. |
 | ISR regeneration | `@ultimat3/core`'s `singleFlight`, `deadlineMs` = `regenerateDeadlineMs` (`DEFAULT_ISR_REGENERATE_DEADLINE_MS`, 30 s; `finiteCount` ≥ 1, no opt-out), `schedule` injectable. Past it the PATH is free; the hung render runs on, and `latest` (by identity) drops its result once a newer run started. `render-isr-flight.test.ts`, on a hand-fired scheduler. |
 | Which route a stored ISR path is | exact path first, else the MOST SPECIFIC pattern: `route-pattern.ts`'s `compilePattern` (never a second compiler), sorted on `CompiledPattern.specificity`. Never table order: `describePages()` sorts `*` before `:`. |

package/README.md

@@ -557,6 +557,8 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | `checkSurfaceBoundary`, `assertSurfaceBoundary`, `surfaceOf` | the hard boundary |
 | `renderStatic`†, `enumeratePrerender`† | build-time render, content hashing |
 | `isrController`†, `invalidateAndRevalidate`† | SWR + single-flight + tag triggers |
+| `isrKey`†, `isrRequestUrl`†, `undeclaredQuery`†, `isrRouteFor`† | the one derivation of an `isr` store key — the path in `@ultimat3/http`'s `canonicalPath` spelling, so every spelling the router answers with a page is that page's one entry — the request URL narrowed to `revalidate.query`, and the route a key reads back as (a key no route owns is never stored) |
+| `noStore`, `routeNoStoreOf` | a loader's "do not keep this answer" — a mark on the data, like `withStatus`; read by `isr` |
 | `renderSsr`†, `streamResult`† | the per-request modes |
 | `renderToHtml`†, `renderComponent`†, `stylesFor`† | the server JSX writer and the surface's css |
 | `claimStylesheets`† | a package claims its own directory's stylesheets for ONE surface, so the other surface's documents never carry them |
@@ -591,6 +593,20 @@ a job boundary the class is gone and the `code` is what survives — match on th
   `*catch-all`, per segment), never the first in table order. The route is matched on the path
   with its query and its routed locale prefix removed (`unlocalizedPath`), as the router matches
   it — the key keeps both, so `/en/blog/a` is its own entry under `/blog/:slug`'s TTL and tags.
+- **`revalidate` decides three more things** (`As of 2026-10-10`; the tables are the wiki's
+  Routes page). `onInvalidate: 'purge'` (needs `tags` and `ttl`) deletes a route's stored pages on
+  a tag bust and evicts their renders in flight, where the default `'stale'` answers the old copy
+  once more: the next request on this replica and on each one the broadcast reaches; a replica
+  that misses it serves its copy until `ttl`. `maxStale` bounds how long past its `ttl` a copy is
+  served (`0`: never; the default under `'purge'`). `query: ['page']` (or `[]`) is the only part
+  of the query string in the key and in the URL `load` is given (`isrRequestUrl`†); a route that
+  declares none still keys on the whole query string, and `x verify` says so. **Never stored:** a
+  5xx (the last good page keeps answering, stale; a 1 s cooldown stops a render per request), a
+  render whose `load` returned `noStore(data)`, one invalidated while it ran, a throw, a redirect.
+- **A store two processes write needs `IsrStore.tagFence`**† — `sample` / `bump` / an atomic
+  `setIfCurrent` over a generation per tag entity — or a replica whose render began before a
+  purge writes the page back. `memoryIsrStore` has it; a bust also asks the store which keys it
+  holds under the tags, so a page another controller wrote is reached too.
 - **A tag-revalidated ISR document carries its purge keys while it is shared-cacheable**,
   `As of 2026-10-02` — `@ultimat3/http`'s `cache-headers` stage rewrites the response to `private`
   for a signed-in visitor and strips both headers: `Surrogate-Key`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/render",
-  "version": "27.7.0",
+  "version": "27.8.1",
   "description": "The route primitive and the five render modes: static, isr, ssr, stream, spa.",
   "license": "MIT",
   "type": "module",
@@ -40,11 +40,11 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "27.7.0",
-    "@ultimat3/core": "27.7.0",
-    "@ultimat3/http": "27.7.0",
-    "@ultimat3/i18n": "27.7.0",
-    "@ultimat3/seo": "27.7.0",
+    "@ultimat3/cache": "27.8.1",
+    "@ultimat3/core": "27.8.1",
+    "@ultimat3/http": "27.8.1",
+    "@ultimat3/i18n": "27.8.1",
+    "@ultimat3/seo": "27.8.1",
     "sass": "1.105.1"
   }
 }

package/src/duration.ts

@@ -29,6 +29,20 @@ export function parseTtlMs(ttl: string | number | null | undefined): number | nu
   return factor === undefined ? null : positiveMs(Number(amount) * factor);
 }
 
+/**
+ * `revalidate.maxStale`'s reader: the one duration that may be ZERO — "never answer a copy past
+ * its ttl" is a bound, where a zero-length TTL is no trigger at all. `null` is "not a duration".
+ */
+export function parseStaleMs(value: string | number | null | undefined): number | null {
+  if (
+    value === 0 ||
+    (typeof value === 'string' && /^0(?:\.0+)?(?:ms|s|m|h|d)$/.test(value.trim()))
+  ) {
+    return 0;
+  }
+  return parseTtlMs(value);
+}
+
 /**
  * Both arms end here, so `'0s'` and `0` cannot disagree: a zero-length TTL registered, and
  * `entryTtlMs` then read the stored `0` as tag-only — a page declared to expire never did.

package/src/index.ts

@@ -180,6 +180,7 @@ export {
   routePathFromFile,
 } from './registry';
 export type {
+  InvalidateMode,
   LoadRequirement,
   PrerenderFn,
   RenderResult,
@@ -211,7 +212,7 @@ export { pageComponentOf } from './route-component';
 export { metaContextFor, routeDataFor } from './route-data';
 export type { CompiledPattern } from './route-pattern';
 export { compilePattern } from './route-pattern';
-export { routeStatusOf, withStatus } from './route-status';
+export { noStore, routeNoStoreOf, routeStatusOf, withStatus } from './route-status';
 export type { SpeculationRules } from './speculation-rules';
 export {
   SPECULATION_RULES_TYPE,

package/src/modes.ts

@@ -9,6 +9,7 @@ import type { HydrateStrategy, RenderMode } from '@ultimat3/core';
 import { HYDRATE_STRATEGIES, RENDER_MODES, renderCauseValue } from '@ultimat3/core';
 import { parseTtlMs } from './duration';
 import { RouteModeInvalidError } from './errors';
+import { assertRevalidateShape } from './revalidate-shape';
 import type { RouteConfig } from './route';
 import type { RouteSurface, Surface } from './surfaces';
 import { SURFACE_SPECS, surfaceAllows } from './surfaces';
@@ -132,6 +133,9 @@ export function assertModeShape(config: RouteShape): void {
       "add revalidate: { tags: [tag.post] } or revalidate: { ttl: '5m' }",
     );
   }
+  if (config.render === 'isr' && config.revalidate !== undefined) {
+    assertRevalidateShape(config.revalidate);
+  }
 
   // cache: the `ssr` mode's key alone. `static` and `isr` are content-hashed / TTL'd documents
   // whose headers ARE the mode, and a `stream` is always `private, no-store` — a declaration on

package/src/registry.ts

@@ -5,15 +5,12 @@
  * from. Nothing downstream may keep its own list of routes.
  */
 
-import type { CacheTag } from '@ultimat3/cache';
-import { serializeTag, surrogateKeys } from '@ultimat3/cache';
 import type { HydrateStrategy, OfflineStrategy, RenderMode } from '@ultimat3/core';
-import { finiteCount, isUltimateError, renderFixLiteral } from '@ultimat3/core';
+import { finiteCount } from '@ultimat3/core';
 import { byCodeUnit } from './code-unit-order';
 import {
   RouteDuplicateError,
   RouteFileInvalidError,
-  RouteModeInvalidError,
   RouteUnnormalizedError,
   SurfaceBoundaryError,
 } from './errors';
@@ -27,7 +24,8 @@ import {
   mountedRoutes,
   setMountedRoutes,
 } from './mounted-routes';
-import type { RouteConfig, RouteData } from './route';
+import { assertPurgeableTags } from './revalidate-shape';
+import type { InvalidateMode, RouteConfig, RouteData } from './route';
 import { isRouteConfig, routeTagKeys } from './route';
 import type { RouteComponent } from './route-component';
 import type { CompiledPattern } from './route-pattern';
@@ -70,6 +68,17 @@ export interface RouteDescriptor {
   readonly hydrate: HydrateStrategy;
   readonly revalidateTags: readonly string[];
   readonly revalidateTtl: string | number | null;
+  /**
+   * The three below are optional so a descriptor built by hand before they existed still
+   * typechecks; the registry always writes them. Absent reads as `'stale'`, unbounded, undeclared.
+   */
+  readonly revalidateOnInvalidate?: InvalidateMode;
+  readonly revalidateMaxStale?: string | number | null;
+  /**
+   * `revalidate.query`, sorted: the only query parameters an `isr` page of this route keys on.
+   * `null` when the route declared none — its pages then key on the WHOLE query string.
+   */
+  readonly revalidateQuery?: readonly string[] | null;
   readonly prerenderable: boolean;
   readonly dynamic: boolean;
   readonly hasPolicy: boolean;
@@ -237,27 +246,6 @@ export interface RegisterRouteInput<TData = RouteData> {
   readonly component?: RouteComponent;
 }
 
-/**
- * A `revalidate.tags` entry goes out as a purge key on every response of the route
- * (`render-isr.ts`), so one a CDN would split is refused HERE, naming the file. Asked of
- * `@ultimat3/cache`'s own screen rather than restated: found at serve time it is a 500 on a
- * public page, found at purge time it is a document nothing can clear.
- */
-function assertPurgeableTags(file: string, tags: readonly CacheTag[] | undefined): void {
-  for (const owned of tags ?? []) {
-    try {
-      surrogateKeys([owned], file);
-    } catch (error) {
-      if (!isUltimateError(error) || error.code !== 'X_CACHE_PURGE_FAILED') throw error;
-      const wire = renderFixLiteral(serializeTag(owned), '<the tag>');
-      throw new RouteModeInvalidError(
-        `${file} declares revalidate tag ${wire}, which cannot be a CDN purge key — a key is split on whitespace and commas and capped at 1024 bytes, so every response of the route would carry one no purge can name`,
-        `edit revalidate.tags in ${file}: replace ${wire} with a tag whose entity and id carry no whitespace or comma`,
-      );
-    }
-  }
-}
-
 /** Register a route and enforce every invariant that needs the surrounding module. */
 export function registerRoute<TData = RouteData>(
   input: RegisterRouteInput<TData>,
@@ -461,6 +449,10 @@ const descriptorOf = (
   hydrate: config.hydrate,
   revalidateTags: routeTagKeys(config.revalidate?.tags),
   revalidateTtl: config.revalidate?.ttl ?? null,
+  revalidateOnInvalidate: config.revalidate?.onInvalidate ?? 'stale',
+  revalidateMaxStale: config.revalidate?.maxStale ?? null,
+  revalidateQuery:
+    config.revalidate?.query === undefined ? null : [...new Set(config.revalidate.query)].sort(),
   prerenderable: config.prerender !== undefined,
   dynamic: params > 0,
   hasPolicy: config.policy !== undefined,

package/src/render-isr-cooldown.ts

@@ -0,0 +1,44 @@
+/**
+ * A short memory of the keys whose last render FAILED (a 5xx). `isr` never stores a failure, so
+ * without this every request for a page whose read is down is its own render: a crawler walking
+ * the route while the database is unreachable is one failing query per request, back to back.
+ * For the cooldown the same answer is repeated instead. Bounded, oldest out first.
+ */
+
+/** How long one failed render answers for. Short: it bounds retries, it is not a cache. */
+export const DEFAULT_ISR_FAILURE_COOLDOWN_MS = 1_000;
+
+const MAX_REMEMBERED = 1_000;
+
+export interface FailureCooldown<T> {
+  /** The failure still answering for `key`, or `undefined` once its cooldown has passed. */
+  get(key: string): T | undefined;
+  remember(key: string, failure: T): void;
+  clear(key: string): void;
+}
+
+export function failureCooldown<T>(cooldownMs: number, now: () => number): FailureCooldown<T> {
+  const held = new Map<string, { readonly until: number; readonly failure: T }>();
+  return {
+    get(key) {
+      const kept = held.get(key);
+      if (kept === undefined) return undefined;
+      if (now() < kept.until) return kept.failure;
+      held.delete(key);
+      return undefined;
+    },
+    remember(key, failure) {
+      if (cooldownMs <= 0) return;
+      held.delete(key);
+      held.set(key, { until: now() + cooldownMs, failure });
+      while (held.size > MAX_REMEMBERED) {
+        const oldest = held.keys().next();
+        if (oldest.done === true) break;
+        held.delete(oldest.value);
+      }
+    },
+    clear: (key) => {
+      held.delete(key);
+    },
+  };
+}

package/src/render-isr-key.ts

@@ -0,0 +1,103 @@
+/**
+ * What an `isr` entry is keyed by: the request URL narrowed to the query the route declared, the
+ * negotiated locale, and the way back from a key to the route table. Split from `render-isr.ts`,
+ * the controller, which only ever holds the key this file derived.
+ */
+
+import { canonicalPath } from '@ultimat3/http';
+import { unlocalizedPath } from '@ultimat3/i18n';
+
+/**
+ * The reserved query parameter the negotiated locale rides in. A parameter and not a prefix
+ * because `routePathOf` splits a key at its `?`: a `es:/blog` key would match no route, so
+ * `descriptorFor` would answer `undefined` and a declared `revalidate: { ttl }` would silently
+ * become tag-only. Reserved spelling, so an app's own `?locale=` stays its own dimension.
+ */
+export const ISR_LOCALE_PARAM = '__x_locale';
+
+/**
+ * The URL an `isr` route is rendered FOR: the request's, keeping only the query parameters the
+ * route declared in `revalidate.query`, one value each, in sorted order.
+ *
+ * Undeclared (`null`), the key carries the whole query, so `/blog?x=1`, `/blog?x=2`, … are each a
+ * miss, a render and a stored entry: any visitor can make an `isr` route render on demand and push
+ * real pages out of the bounded store, and `utm_*` / `fbclid` / `gclid` split one page into as
+ * many entries as there are campaigns — each of which a withdrawal then has to reach. An `isr`
+ * document is a shared artifact, so what it may vary on is the route's to declare, never the
+ * visitor's to choose. `null` is kept only because flipping it changes what a page that reads an
+ * undeclared parameter renders, and that waits for a major; `query: []` is the safe declaration.
+ *
+ * The SAME narrowed URL is what `load`, `meta` and the page are given (`data.url`, `props.query`),
+ * so a parameter that is not in the key cannot change the document stored under it. Nothing is
+ * redirected: `/blog?utm_source=x` is answered with the `/blog` entry, whose `canonical` is `/blog`.
+ * A repeated parameter keeps its FIRST value — `?p=1&p=2` and `?p=1&p=3` are one entry, not two.
+ */
+export function isrRequestUrl(url: URL, query: readonly string[] | null): URL {
+  if (query === null) return url;
+  const kept = new URLSearchParams();
+  for (const name of [...new Set(query)].sort()) {
+    const value = url.searchParams.get(name);
+    if (value !== null) kept.set(name, value);
+  }
+  const narrowed = new URL(url);
+  narrowed.search = kept.toString();
+  narrowed.hash = '';
+  return narrowed;
+}
+
+/**
+ * The request's parameter names the route did not declare: what `isrRequestUrl` drops — or, for a
+ * route that declared nothing (`null`), what a visitor just used to mint a stored page.
+ */
+export function undeclaredQuery(url: URL, query: readonly string[] | null): readonly string[] {
+  const declared = new Set(query ?? []);
+  return [...new Set(url.searchParams.keys())].filter((name) => !declared.has(name)).sort();
+}
+
+/**
+ * The ISR store key for one URL: pathname, the negotiated LOCALE, and the query, **params
+ * sorted**. The URL is `isrRequestUrl`'s — already narrowed to the route's declared parameters.
+ *
+ * The pathname is keyed in its ONE spelling — `@ultimat3/http`'s `canonicalPath`, built from the
+ * functions the router segments and decodes a request with, never a second normaliser. The router
+ * answers `/blog//a/`, `/blog/%61` and `/blog/a` with one page; keyed raw, each was an entry of
+ * its own (a 20-letter slug has a million percent-spellings, and the store holds 1,000), and one
+ * the route table could not read back (`/blog//a`) was stored with no ttl and no tags, which no
+ * bust reached: a withdrawn page stayed up at that spelling for the life of the process.
+ *
+ * Exported because deriving it is the caller's job and there may only be ONE derivation — a
+ * server that keyed on `url.pathname` while the store believed it held a whole URL is the shape
+ * of #171. Sorting makes `?a=1&b=2` and `?b=2&a=1` one entry rather than two renders of one page.
+ *
+ * The locale is REQUIRED, and required as an argument rather than read from the ambient context so
+ * that every call site has to answer: a document is rendered with `<html lang>` and every `t()` in
+ * the request's own locale, so one entry per path served visitor 2 the document negotiated for
+ * visitor 1 — for the whole TTL, and with `s-maxage` telling the CDN to do the same. The time zone
+ * is deliberately NOT a dimension: it is unbounded where a locale set is declared, and an `isr`
+ * page is a shared artifact, so a date on one belongs in an explicit zone the page itself names.
+ */
+export function isrKey(url: URL, locale: string): string {
+  const params = new URLSearchParams(url.search);
+  params.set(ISR_LOCALE_PARAM, locale);
+  params.sort();
+  return `${canonicalPath(url.pathname)}?${params.toString()}`;
+}
+
+/**
+ * The path the ROUTE TABLE knows a key by. Every lookup that asks the table a question — the
+ * descriptor, and therefore the TTL and the tags — has to undo what the key carries beyond the
+ * route, in the order the router does before it matches (`@ultimat3/http`'s `routing` stage):
+ *
+ * - the query: `descriptorFor('/blog?page=2')` matches no route;
+ * - the routed locale prefix: `/en/blog/a` is the `/blog/:slug` route in English. The key KEEPS the
+ *   prefix — it is the URL the document was rendered for, `canonical` and all — and the table has
+ *   never heard of it. Left on, a prefixed page matched no route: `ttlMs: null` and no tag edge, so
+ *   it was fresh forever while the default locale's copy of the same page went stale on schedule.
+ *
+ * `unlocalizedPath` is i18n's, the one the router's own split is built on: a segment that names no
+ * routed locale is left alone, so `/fr/blog` is still no route.
+ */
+export function routePathOf(key: string): string {
+  const query = key.indexOf('?');
+  return unlocalizedPath(query === -1 ? key : key.slice(0, query));
+}

package/src/render-isr-result.ts

@@ -0,0 +1,125 @@
+/**
+ * An `isr` entry as a response: its status, and the headers that tell a shared cache how long it
+ * may keep the document and which keys purge it. Split from `render-isr.ts`, the controller.
+ */
+
+import { surrogateKeys } from '@ultimat3/cache';
+import { logger } from '@ultimat3/core';
+import { isRenderStatus } from './finite-status';
+import type { IsrPolicy } from './render-isr-routes';
+import type { IsrEntry } from './render-isr-store';
+import { staticHeaders } from './render-static';
+import type { RenderResult } from './route';
+
+/** Tag-only routes have no clock of their own; a tag bust reaches the CDN through the fanout. */
+const TAG_ONLY_S_MAX_AGE_SECONDS = 60;
+
+/** What a shared cache may serve stale for when the route bounds nothing — a day, as before. */
+const DEFAULT_STALE_WHILE_REVALIDATE_SECONDS = 86_400;
+
+/**
+ * `IsrStore` is a driver seam, so an entry can come back from an app's own store — one backed by
+ * Redis round-trips it through JSON, where a `ttlMs` that was never written reads back as
+ * `undefined` and `entry.ttlMs === null` is then false. Two failures follow from that one value
+ * and neither raises: `now - generatedAt < NaN` is false, so the page is NEVER fresh and every
+ * request regenerates it, and the CDN is handed `s-maxage=NaN` — an unparseable directive a
+ * conforming cache IGNORES, dropping the page to heuristic caching rather than to the declared
+ * age. Read on the request path, so it is TOTAL rather than a throw: a ttl that is not a positive
+ * finite number of milliseconds is the tag-only `null` `parseTtlMs` would have answered for it.
+ */
+export function entryTtlMs(entry: IsrEntry): number | null {
+  const ttlMs = entry.ttlMs;
+  if (ttlMs === null || (Number.isFinite(ttlMs) && ttlMs > 0)) return ttlMs;
+  logger.warn('isr.entry_ttl_invalid', { path: entry.path, ttlMs: String(ttlMs) });
+  return null;
+}
+
+/**
+ * The declared TTL is the route's own contract with the CDN: a shared cache must not hold the
+ * page longer than the app said it stays true. A flat `s-maxage=60` made `revalidate: { ttl:
+ * '5m' }` a lie in one direction and `ttl: '30s'` a lie in the other.
+ *
+ * `stale-while-revalidate` is the same contract for the copy PAST its age, so it follows the
+ * route's own bound: none at all under `onInvalidate: 'purge'` (a document that must come down may
+ * not be answered stale by the edge for a day after the origin deleted it), `maxStale` when one is
+ * declared, a day otherwise.
+ */
+function cacheControl(ttlMs: number | null, policy: IsrPolicy, ageMs: number): string {
+  const sMaxAge = ttlMs === null ? TAG_ONLY_S_MAX_AGE_SECONDS : Math.round(ttlMs / 1_000);
+  if (policy.onInvalidate === 'purge') {
+    // What is LEFT of the ttl, not the whole of it: the ttl bounds a replica that missed a purge,
+    // and a hit answered at its last second with the full age would hand the edge a second ttl.
+    // TOTAL, like every reader here: an age that is not a number (a clock that answered `NaN`)
+    // is the whole ttl, never `s-maxage=NaN` — a directive a conforming cache ignores.
+    const left = ttlMs === null ? sMaxAge : Math.max(0, Math.ceil((ttlMs - ageMs) / 1_000));
+    return `public, max-age=0, s-maxage=${Number.isFinite(left) ? Math.min(sMaxAge, left) : sMaxAge}`;
+  }
+  const base = `public, max-age=0, s-maxage=${sMaxAge}`;
+  const stale =
+    policy.maxStaleMs === null
+      ? DEFAULT_STALE_WHILE_REVALIDATE_SECONDS
+      : Math.round(policy.maxStaleMs / 1_000);
+  return stale === 0 ? base : `${base}, stale-while-revalidate=${stale}`;
+}
+
+/**
+ * `entryTtlMs`'s reason, one field over: a store may hand back an entry with no `status`, or one
+ * that JSON turned into something else, on the request path. Absent is 200 — the only value any
+ * entry carried before the field existed — and anything the range refuses is 200 with a warning,
+ * because a stored number must not 500 the page for its whole TTL.
+ */
+function entryStatus(entry: IsrEntry): number {
+  const status = entry.status;
+  if (status === undefined) return 200;
+  if (isRenderStatus(status)) return status;
+  logger.warn('isr.entry_status_invalid', { path: entry.path, status: String(status) });
+  return 200;
+}
+
+export interface IsrResultOptions {
+  readonly buildId: string;
+  readonly policy: IsrPolicy;
+  readonly servedStale?: boolean;
+  /** How long ago the entry was generated, by the controller's clock; 0 for one just rendered. */
+  readonly ageMs: number;
+  /**
+   * False for a render the store did not keep — a 5xx, one whose `load` said `noStore()`, or one
+   * invalidated while it rendered. It is then `private, no-store` with no purge key: an answer
+   * nothing here kept must not be kept by the edge either, or one upstream blip is a 503 — and one
+   * purge raced by a render is the withdrawn page — for the route's whole `s-maxage`.
+   */
+  readonly cacheable?: boolean;
+}
+
+export function isrResult(entry: IsrEntry, options: IsrResultOptions): RenderResult {
+  const { buildId, policy } = options;
+  // The store keys on the locale; a shared cache in front of it has to as well, or the CDN
+  // repeats the bug this entry was split to fix. `ssrHeaders`' own line, for the same reason.
+  // The rest of the shared key — the cookie, the zone — is added by `@ultimat3/http`'s
+  // `cache-headers` stage, which sees the actor this function cannot.
+  const vary = 'accept-language';
+  if (options.cacheable === false) {
+    const { etag: _etag, ...rest } = staticHeaders(entry.hash, buildId);
+    return {
+      status: entryStatus(entry),
+      headers: { ...rest, 'cache-control': 'private, no-store', vary },
+      body: entry.html,
+    };
+  }
+  const headers: Record<string, string> = {
+    ...staticHeaders(entry.hash, buildId),
+    'cache-control': cacheControl(entryTtlMs(entry), policy, options.ageMs),
+    vary,
+  };
+  // The keys an edge purges this document by — `@ultimat3/cache`'s list, never a second one, so
+  // what a bust sends and what the page carries cannot drift. Absent, an `invalidates` cleared
+  // every tier but the CDN, which held the document for its whole `s-maxage`. The tags were
+  // screened when the route registered (`registry.ts`), so this cannot refuse on the request path.
+  const keys = surrogateKeys(policy.tags, 'isr');
+  if (keys.length > 0) {
+    headers['surrogate-key'] = keys.join(' ');
+    headers['cache-tag'] = keys.join(',');
+  }
+  if (options.servedStale === true) headers['x-ultimate-isr'] = 'stale';
+  return { status: entryStatus(entry), headers, body: entry.html };
+}

package/src/render-isr-routes.ts

@@ -0,0 +1,98 @@
+/**
+ * Which route a stored `isr` key belongs to, and what that route declared about it — its tags, its
+ * TTL, what an invalidation does and how long past its TTL a copy may still be served. Split from
+ * `render-isr.ts`: the controller asks, this file reads the route table.
+ */
+
+import type { CacheTag } from '@ultimat3/cache';
+import { parseTag } from '@ultimat3/cache';
+import { parseStaleMs, parseTtlMs } from './duration';
+import type { RouteDescriptor } from './registry';
+import { routePathOf } from './render-isr-key';
+import type { InvalidateMode } from './route';
+import { compilePattern } from './route-pattern';
+
+/** What a route declared for the entries stored under it; the defaults for a key no route owns. */
+export interface IsrPolicy {
+  readonly tags: readonly CacheTag[];
+  readonly ttlMs: number | null;
+  /** `'stale'`: a bust keeps the copy for one more serve. `'purge'`: a bust deletes it. */
+  readonly onInvalidate: InvalidateMode;
+  /**
+   * How long past its TTL an entry may still be served stale: `null` is unbounded, `0` never.
+   * A `'purge'` route that declares none gets `0` — its `ttl` is what bounds a replica that
+   * missed the purge, and a copy answered stale past it would move that bound by one request.
+   */
+  readonly maxStaleMs: number | null;
+}
+
+export function isrPolicyOf(descriptor: RouteDescriptor | undefined): IsrPolicy {
+  const onInvalidate = descriptor?.revalidateOnInvalidate ?? 'stale';
+  const declared = descriptor?.revalidateMaxStale ?? null;
+  return {
+    tags: (descriptor?.revalidateTags ?? []).map(parseTag),
+    ttlMs: parseTtlMs(descriptor?.revalidateTtl),
+    onInvalidate,
+    maxStaleMs: declared === null ? (onInvalidate === 'purge' ? 0 : null) : parseStaleMs(declared),
+  };
+}
+
+interface RouteMatcher {
+  readonly route: RouteDescriptor;
+  test(storedPath: string): boolean;
+}
+
+/** One compiled set per route TABLE — `describePages()` hands out one array per registry change. */
+const compiledTables = new WeakMap<readonly RouteDescriptor[], readonly RouteMatcher[]>();
+
+/**
+ * The route each key resolved to, per table. A bust asks this of EVERY stored key, and a pattern
+ * match per key per bust is the store's size in regex tests on the event loop. Bounded: emptied
+ * when it outgrows a store several times the default, never grown without limit by request keys.
+ */
+const resolvedKeys = new WeakMap<
+  readonly RouteDescriptor[],
+  Map<string, RouteDescriptor | undefined>
+>();
+const MAX_RESOLVED_KEYS = 8_192;
+
+/**
+ * A stored path belongs to a route when the route's pattern matches it — `route-pattern.ts`'s one
+ * pattern compiler, never a second. Ordered MOST SPECIFIC FIRST, as `@ultimat3/http`'s trie
+ * resolves a request: segment by segment, a static beats a `:param` beats a `*catch-all`. In table
+ * order `/docs/*path` sorts before `/docs/:id`, so the first match gave `/docs/7` the catch-all's
+ * TTL and tags — a page rendered by one route and expired by another's clock.
+ */
+function matchersOf(table: readonly RouteDescriptor[]): readonly RouteMatcher[] {
+  const cached = compiledTables.get(table);
+  if (cached !== undefined) return cached;
+  // Static routes too: `/precios-españa` is the route's path and `/precios-espa%C3%B1a` the key's,
+  // so only the pattern (raw or encoded, per character) finds it.
+  const compiled = table
+    .map((route): RouteMatcher & { readonly specificity: number } => {
+      const { regex, specificity } = compilePattern(route.path);
+      return { route, specificity, test: (stored) => regex.test(stored) };
+    })
+    .sort((a, b) => b.specificity - a.specificity);
+  compiledTables.set(table, compiled);
+  return compiled;
+}
+
+/** The route a store key was rendered by, or `undefined` for a key no route in `table` owns. */
+export function isrRouteFor(
+  table: readonly RouteDescriptor[],
+  key: string,
+): RouteDescriptor | undefined {
+  let resolved = resolvedKeys.get(table);
+  if (resolved === undefined) {
+    resolved = new Map();
+    resolvedKeys.set(table, resolved);
+  }
+  if (resolved.has(key)) return resolved.get(key);
+  const path = routePathOf(key);
+  const route =
+    table.find((r) => r.path === path) ?? matchersOf(table).find((m) => m.test(path))?.route;
+  if (resolved.size >= MAX_RESOLVED_KEYS) resolved.clear();
+  resolved.set(key, route);
+  return route;
+}