@ultimat3/render 15.0.0 → 17.0.0

package/CLAUDE.md

@@ -79,10 +79,12 @@ for the mirror-image reason, keeping `render → pwa` refused. Never `cli` (upwa
 | A bust that lands MID-render | fenced with `@ultimat3/cache`'s `sampleFence({ key, tags })`, taken before `render()` and asked before `store.set` — the same mechanism `CacheStack`'s read-through fill uses, never a second one grown here. `regenerate` rendered and then wrote `{ stale: false }` unconditionally, so a `markStale` arriving in between was ERASED by HTML built from pre-write rows; for a tag-only route `isFresh` is then true forever and the process serves it for the rest of its life. `registerPath` runs BEFORE the render for the other half: `revalidateByTags` reads the graph, so a bust could not see a cold path whose first render was still in flight. |
 | Marking a page stale | `IsrStore.markStale(path)`, in place — never `set({ ...entry, stale: true })`. `set` means "this page was just generated" and the default store orders eviction by exactly that, so the read-modify-write made the STALEST page the newest: a tag bust protected the pages that most needed regenerating and evicted the freshest one instead. **Breaking**: `markStale` is a required member of `IsrStore`. |
 | ISR store bound | `memoryIsrStore()` caps at `DEFAULT_ISR_MAX_ENTRIES` (1,000), least recently generated first — a route table supports `:params` and `*`, so `/blog/:slug` retains one full HTML string per slug ever requested, 404-shaped ones included. |
+| A `RenderResult.status` | `finiteStatus(subject, status)` in `finite-status.ts`, at both sites that take one from a caller (`renderSsr`'s `options.status`, `streamResult`'s third argument) — 200–599, whole. It reaches `new Response(body, { status })`, which answers a bare `RangeError` for anything else: `NaN` arrives there as `The status provided (-9223372036854775808)`, no code, no fix, and the render fails two frames above the route that set it. The screen is NARROWER than the boundary on purpose — `new Response` also takes `101`, and no rendered document is a protocol switch. The name carries `finite` because `bun run finite-bounds` recognises a repair by the shape of the CALL; spelled `renderStatus` it read as no screen at all. |
+| `IsrEntry.ttlMs` off a store | normalised by `entryTtlMs`, TOTAL, never a throw — a ttl that is not a POSITIVE FINITE number of ms is the tag-only `null` `parseTtlMs` would have answered. `IsrStore` is a driver seam, and one backed by Redis round-trips the entry through JSON where a `ttlMs` nobody wrote reads back as `undefined`, so `entry.ttlMs === null` is false. Two failures, neither raising: `now - generatedAt < NaN` is false so the page is NEVER fresh and every request regenerates it, and the CDN is handed `s-maxage=NaN` — a directive a conforming cache IGNORES, dropping the page to heuristic caching. Read on the request path, so a refusal would turn a bad stored entry into a 500; the `isr.entry_ttl_invalid` warning is what keeps it from being silent. |
 | Route path from file | ONE reader of the surface segment: `locateSurface()` answers which surface AND where it starts. `registry.ts` sliced at `indexOf('app/')` instead, which matched inside `myapp/`, so every route under `apps/myapp/app/` served at `/app/…`. Never re-derive the offset from the surface NAME. |
 | An undecodable path segment | not a match, never a throw — `decodeSegment` in `registry.ts` is the one reader. `decodeURIComponent('%zz')` is a bare `URIError`, so a typo in a path segment was a 500 where `@ultimat3/http`'s router already answers "this branch does not match". A literal route matching the same text still wins. `router-client.ts` was the second reader and went with `createRouter`. |
 | ISR registration | reconciled against `store.paths()` after every generation (`forgetEvictedPaths`). The store is bounded and evicts silently; `registered` and the cache graph behind it only ever grew, one edge per slug ever requested. Never a store callback — a custom `IsrStore` has none. |
-| Stream hole deadline | `DEFAULT_HOLE_TIMEOUT_MS` (15s), `holeTimeoutMs: null` to opt out. A hole is app code the framework `await`s and nothing else bounds it; one that never settles held the response and its whole closure open for the life of the process. A hole reveals exactly once — its promise, its rejection, or its deadline, whichever lands first. |
+| Stream hole deadline | `DEFAULT_HOLE_TIMEOUT_MS` (15s), `holeTimeoutMs: null` to opt out, and a declared one is a whole number of at least **1** — a deadline is the bound a non-finite value does not disable but MOVES: `setTimeout(fn, NaN)` is `setTimeout(fn, 0)`, so every hole misses a deadline nobody set and the document is all fallbacks. There is no spelling of `holeTimeoutMs` that means "immediately". A hole is app code the framework `await`s and nothing else bounds it; one that never settles held the response and its whole closure open for the life of the process. A hole reveals exactly once — its promise, its rejection, or its deadline, whichever lands first. |
 | Errors | `errors.ts` subclasses only. Never a bare `Error`, never a bare `TODO`. |
 | Policy | render checks *presence* only. Evaluation belongs to `@ultimat3/policy`. |
 | A gated route is never a cached one | `modes.ts` refuses `policy` on BOTH `static` and `isr` (`X_ROUTE_MODE_INVALID`, `modes.test.ts`). `isr` was not refused until 2026-08 and `dev-render.ts` keys the cache on `url.pathname` alone — no actor, no query string — so a gated ISR route rendered the first actor's document and served it to every later actor who passed the same policy. Keying on more is a trap, not a fix: the key would have to enumerate everything a `policy` and a `load` can read. `ssr` is the one gated mode there is. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/render",
-  "version": "15.0.0",
+  "version": "17.0.0",
   "description": "The route primitive and the five render modes: static, isr, ssr, stream, spa.",
   "license": "MIT",
   "type": "module",
@@ -36,10 +36,10 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "15.0.0",
-    "@ultimat3/core": "15.0.0",
-    "@ultimat3/i18n": "15.0.0",
-    "@ultimat3/seo": "15.0.0",
+    "@ultimat3/cache": "17.0.0",
+    "@ultimat3/core": "17.0.0",
+    "@ultimat3/i18n": "17.0.0",
+    "@ultimat3/seo": "17.0.0",
     "sass": "1.102.0"
   }
 }

package/src/finite-status.ts

@@ -0,0 +1,30 @@
+// Single responsibility: the one screen a `RenderResult.status` passes before it reaches
+// `new Response(body, { status })`, which answers a bare `RangeError` — no code, no fix, no
+// `--json` — for anything outside the range it accepts. Its own module because two render modes
+// take a status from their caller and a second copy of the rule is how the two drift apart.
+// Named for `finiteOption`, and the name is load-bearing: `bun run finite-bounds` recognises a
+// repair by the shape of the CALL, so a screen spelled `renderStatus` reads as no screen at all.
+
+import { assert, finiteCount } from '@ultimat3/core';
+
+/**
+ * What `new Response` accepts for a document. It also accepts `101`, which is a protocol switch
+ * and never a rendered page, so this range is the narrower of the two on purpose.
+ */
+const MIN_RENDER_STATUS = 200;
+const MAX_RENDER_STATUS = 599;
+
+/**
+ * `NaN` is the value that gets here: `??` guards NULLISH, so a status read from a config, a JSON
+ * body or `Number(process.env.X)` walks past its default intact — and the boundary then reports it
+ * as `The status provided (-9223372036854775808)`, which names nothing a caller can act on.
+ */
+export function finiteStatus(subject: string, status: number): number {
+  finiteCount(subject, 'status', status, 0);
+  assert(
+    status >= MIN_RENDER_STATUS && status <= MAX_RENDER_STATUS,
+    `${subject} status is ${String(status)}, which new Response() refuses with a RangeError instead of returning a document`,
+    `pass a status between ${String(MIN_RENDER_STATUS)} and ${String(MAX_RENDER_STATUS)} to ${subject}, or omit it and take 200`,
+  );
+  return status;
+}

package/src/head.ts

@@ -7,6 +7,7 @@
  * catalog and so the tag vocabulary keeps exactly one owner (`@ultimat3/seo`).
  */
 
+import { finiteCount } from '@ultimat3/core';
 import type { RouteMeta } from '@ultimat3/seo';
 import { BudgetExceededError } from './errors';
 // `html.ts` is this package's one escaper — a second one is how a character ends up missing.
@@ -188,7 +189,9 @@ export function themeScript(options: ThemeScriptOptions = {}): HeadTag {
     `document.documentElement.setAttribute(${JSON.stringify(attribute)},t)}catch(e){}`;
 
   const bytes = new TextEncoder().encode(source).byteLength;
-  const cap = options.maxBytes ?? THEME_SCRIPT_MAX_BYTES;
+  // `bytes > NaN` is false for every script, so a cap that arrived non-finite does not admit a
+  // bigger script — it removes the only budget a 0kb `site/` route has.
+  const cap = finiteCount('themeScript', 'maxBytes', options.maxBytes ?? THEME_SCRIPT_MAX_BYTES);
   if (bytes > cap) {
     throw new BudgetExceededError(
       `the inlined theme script is ${bytes}b, over its ${cap}b cap — the only script a ` +

package/src/registry.ts

@@ -6,6 +6,7 @@
  */
 
 import type { HydrateStrategy, OfflineStrategy, RenderMode } from '@ultimat3/core';
+import { finiteCount } from '@ultimat3/core';
 import {
   RouteDuplicateError,
   RouteFileInvalidError,
@@ -242,7 +243,14 @@ export function registerRoute<TData = RouteData>(
 
   const derived = routePathFromFile(input.file);
   const path = input.path ?? derived.path;
-  const suspenseBoundaries = input.suspenseBoundaries ?? 0;
+  // `ctx.suspenseBoundaries < 1` is the only thing between `render: 'stream'` and a route that
+  // streams nothing, and `NaN < 1` is false — a count that arrived non-finite does not report the
+  // route it counted, it stops reporting any route.
+  const suspenseBoundaries = finiteCount(
+    'registerRoute',
+    'suspenseBoundaries',
+    input.suspenseBoundaries ?? 0,
+  );
   // Explicit `<TData>`: `isRouteConfig` is a guard over the default `RouteData`, so inference off
   // the narrowed argument would resolve the route's own data generic away here.
   const config = withIslandBudget<TData>(input.config, derived.surface);

package/src/render-isr.ts

@@ -15,7 +15,7 @@ import {
   sampleFence,
   unregisterDependent,
 } from '@ultimat3/cache';
-import { logger, renderThrowable } from '@ultimat3/core';
+import { finiteCount, logger, renderThrowable } from '@ultimat3/core';
 import { parseTtlMs } from './duration';
 import type { RouteDescriptor } from './registry';
 import { describeRoutes } from './registry';
@@ -67,7 +67,13 @@ export interface MemoryIsrStoreOptions {
 }
 
 export function memoryIsrStore(options: MemoryIsrStoreOptions = {}): IsrStore {
-  const maxEntries = options.maxEntries ?? DEFAULT_ISR_MAX_ENTRIES;
+  // `map.size > NaN` is false for every size, so a cap that arrived non-finite is not a bigger
+  // cap — it is no cap, and this store is the one thing bounding a crawler over 100k slugs.
+  const maxEntries = finiteCount(
+    'memoryIsrStore',
+    'maxEntries',
+    options.maxEntries ?? DEFAULT_ISR_MAX_ENTRIES,
+  );
   const map = new Map<string, IsrEntry>();
   return {
     get: (path) => map.get(path),
@@ -236,8 +242,9 @@ export function createIsrController(options: IsrControllerOptions = {}): IsrCont
 
   function isFresh(entry: IsrEntry): boolean {
     if (entry.stale) return false;
-    if (entry.ttlMs === null) return true; // tag-only revalidation: fresh until invalidated
-    return now() - entry.generatedAt < entry.ttlMs;
+    const ttlMs = entryTtlMs(entry);
+    if (ttlMs === null) return true; // tag-only revalidation: fresh until invalidated
+    return now() - entry.generatedAt < ttlMs;
   }
 
   function regenerate(path: string, render: IsrRenderFn): Promise<IsrEntry> {
@@ -397,6 +404,23 @@ function segmentPattern(segment: string): string {
 /** 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;
 
+/**
+ * `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.
+ */
+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:
@@ -404,13 +428,14 @@ const TAG_ONLY_S_MAX_AGE_SECONDS = 60;
  */
 function cacheControl(ttlMs: number | null): string {
   const sMaxAge = ttlMs === null ? TAG_ONLY_S_MAX_AGE_SECONDS : Math.round(ttlMs / 1_000);
+
   return `public, max-age=0, s-maxage=${sMaxAge}, stale-while-revalidate=86400`;
 }
 
 function toResult(entry: IsrEntry, buildId: string, servedStale = false): RenderResult {
   const headers: Record<string, string> = {
     ...staticHeaders(entry.hash, buildId),
-    'cache-control': cacheControl(entry.ttlMs),
+    'cache-control': cacheControl(entryTtlMs(entry)),
     // 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

package/src/render-ssr.ts

@@ -5,6 +5,7 @@
  */
 
 import type { Ctx } from '@ultimat3/core';
+import { finiteStatus } from './finite-status';
 import type { RouteEntry } from './registry';
 import type { RenderResult, RouteParams } from './route';
 
@@ -31,7 +32,9 @@ export async function renderSsr(
 ): Promise<RenderResult> {
   const html = await render(input);
   return {
-    status: options.status ?? 200,
+    // Screened here and not at the Response boundary: `??` guards nullish, so a non-finite status
+    // reaches `new Response` intact and raises a RangeError two frames above the route that set it.
+    status: finiteStatus('renderSsr', options.status ?? 200),
     headers: ssrHeaders(input.entry, options),
     body: html,
   };

package/src/render-stream.ts

@@ -11,7 +11,8 @@
  * contains no interactive island costs literally zero JS.
  */
 
-import { logger, renderThrowable } from '@ultimat3/core';
+import { finiteCount, logger, renderThrowable } from '@ultimat3/core';
+import { finiteStatus } from './finite-status';
 import { escapeAttribute, escapeRawTextContent } from './html';
 import type { RenderResult } from './route';
 
@@ -97,6 +98,18 @@ export interface StreamOptions {
   readonly holeTimeoutMs?: number | null;
 }
 
+/**
+ * `null` is the declared "this hole owns its own timeout" opt-out; every other value is a
+ * deadline, and a deadline of 0 is not one — `setTimeout(fn, 0)` fires on the next tick and the
+ * document becomes all fallbacks.
+ */
+const declaredTimeoutMs = (declared: number | null | undefined): number | null =>
+  declared === undefined
+    ? DEFAULT_HOLE_TIMEOUT_MS
+    : declared === null
+      ? null
+      : finiteCount('renderStreamHtml', 'holeTimeoutMs', declared, 1);
+
 /**
  * Flush order is completion order, not declaration order — a fast hole never waits behind
  * a slow one. The stream closes only after every hole has settled, so a rejected boundary
@@ -110,8 +123,10 @@ export function renderStreamHtml(
   const tail = plan.tail ?? '</body></html>';
   const errorFallback =
     options.errorFallback ?? ((id) => `<div data-x-hole-error="${id}" hidden></div>`);
-  const timeoutMs =
-    options.holeTimeoutMs === undefined ? DEFAULT_HOLE_TIMEOUT_MS : options.holeTimeoutMs;
+  // A deadline is the bound a non-finite value does not disable but MOVES: `setTimeout(fn, NaN)`
+  // is `setTimeout(fn, 0)`, so every hole would miss a deadline nobody set and the document would
+  // be all fallbacks. `null` is the declared opt-out; there is no spelling that means "immediately".
+  const timeoutMs = declaredTimeoutMs(options.holeTimeoutMs);
   /**
    * The response's own lifetime. A client that disconnects mid-stream cancels the stream, and
    * both halves of that have to be honoured: nothing more may be enqueued — `settle`'s
@@ -202,7 +217,7 @@ export function renderStreamHtml(
 
 export function streamResult(plan: StreamPlan, options: StreamOptions, status = 200): RenderResult {
   return {
-    status,
+    status: finiteStatus('streamResult', status),
     headers: {
       'content-type': 'text/html; charset=utf-8',
       'cache-control': 'private, no-store',