@timber-js/app 0.2.0-alpha.96 → 0.2.0-alpha.98

package/src/server/pipeline.ts

@@ -4,25 +4,21 @@
  * Pipeline stages (in order):
  *   proxy.ts → canonicalize → route match → 103 Early Hints → middleware.ts → render
  *
- * Each stage is a pure function or returns a Response to short-circuit.
- * Each request gets a trace ID, structured logging, and OTEL spans.
+ * The phase functions live in `pipeline-phases.ts` so each phase can be
+ * tested in isolation. The terminal `outcomeToResponse` translator and
+ * stateless helpers live in `pipeline-phases.ts` and `pipeline-helpers.ts`
+ * respectively. This file owns only the public type surface and the
+ * `createPipeline` entry point: trace ID setup, request-context ALS,
+ * Server-Timing wrapping, and the activeRequests counter.
  *
  * See design/07-routing.md §"Request Lifecycle", design/02-rendering-pipeline.md §"Request Flow",
  * and design/17-logging.md §"Production Logging"
  */
 
-import { canonicalize } from './canonicalize.js';
-import { runProxy, type ProxyExport } from './proxy.js';
-import { runMiddlewareChain, type MiddlewareFn } from './middleware-runner.js';
-import { runWithTimingCollector, withTiming, getServerTimingHeader } from './server-timing.js';
-import {
-  runWithRequestContext,
-  applyRequestHeaderOverlay,
-  setMutableCookieContext,
-  getSetCookieHeaders,
-  markResponseFlushed,
-  setSegmentParams,
-} from './request-context.js';
+import type { ProxyExport } from './proxy.js';
+import type { MiddlewareFn } from './middleware-runner.js';
+import { runWithTimingCollector, getServerTimingHeader } from './server-timing.js';
+import { runWithRequestContext } from './request-context.js';
 import {
   generateTraceId,
   runWithTraceId,
@@ -30,55 +26,35 @@ import {
   replaceTraceId,
   withSpan,
   setSpanAttribute,
-  getTraceId,
 } from './tracing.js';
-import {
-  logRequestReceived,
-  logRequestCompleted,
-  logSlowRequest,
-  logProxyError,
-  logMiddlewareError,
-  logMiddlewareShortCircuit,
-  logRenderError,
-} from './logger.js';
-import { callOnRequestError } from './instrumentation.js';
-import { RedirectSignal, DenySignal } from './primitives.js';
-import { ParamCoercionError } from './route-element-builder.js';
-import { checkVersionSkew, applyReloadHeaders } from './version-skew.js';
-import { serveStaticMetadataFile, serializeSitemap } from './pipeline-metadata.js';
-import { loadModule } from './safe-load.js';
-import { findInterceptionMatch } from './pipeline-interception.js';
-import type { MiddlewareContext } from './types.js';
-import type { SegmentNode } from '../routing/types.js';
+import { logRequestReceived, logRequestCompleted, logSlowRequest } from './logger.js';
+import { DenySignal } from './primitives.js';
+import type { ManifestSegmentNode } from './route-matcher.js';
+import { makeProxyResolver } from './pipeline-helpers.js';
+import { handleRequest, outcomeToResponse, runProxyPhase } from './pipeline-phases.js';
+
+// ─── Re-exports for backwards compatibility ────────────────────────────────
 
-// ─── Prototype-Pollution-Safe Merge ────────────────────────────────────────
+// `safeMerge` and `coerceSegmentParams` were originally exported from this
+// module. They now live in pipeline-helpers.ts and pipeline-phases.ts; the
+// re-exports preserve `import { safeMerge } from './pipeline.js'` callers.
+export { safeMerge } from './pipeline-helpers.js';
+export { coerceSegmentParams } from './pipeline-phases.js';
 
-/** Keys that must never be merged via Object.assign — they pollute Object.prototype. */
-const DANGEROUS_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+// ─── Route Match Result ────────────────────────────────────────────────────
 
 /**
- * Shallow merge that skips prototype-polluting keys.
- *
- * Used instead of Object.assign when the source object comes from
- * user-authored codec output (segmentParams.parse), which could
- * contain __proto__, constructor, or prototype keys.
+ * Result of matching a canonical pathname against the route tree.
  *
- * See TIM-655, design/13-security.md
+ * `segments` is the runtime (`ManifestFile`-specialized) shape — the same
+ * nodes carried in the virtual route manifest. TIM-863 unified this: the
+ * matcher produces `ManifestSegmentNode[]` directly and every consumer
+ * (render, slots, params coercion, early hints, deny fallback) sees the
+ * same structural type with no `as unknown as` laundering.
  */
-export function safeMerge(target: Record<string, unknown>, source: Record<string, unknown>): void {
-  for (const key of Object.keys(source)) {
-    if (!DANGEROUS_KEYS.has(key)) {
-      target[key] = source[key];
-    }
-  }
-}
-
-// ─── Route Match Result ────────────────────────────────────────────────────
-
-/** Result of matching a canonical pathname against the route tree. */
 export interface RouteMatch {
   /** The matched segment chain from root to leaf. */
-  segments: SegmentNode[];
+  segments: ManifestSegmentNode[];
   /** Extracted segment params (catch-all segments produce string[]). */
   segmentParams: Record<string, string | string[]>;
   /** Middleware chain from the segment tree, ordered root-to-leaf. */
@@ -117,11 +93,32 @@ export type EarlyHintsEmitter = (
 
 // ─── Pipeline Configuration ────────────────────────────────────────────────
 
+/**
+ * Proxy source — a tagged union so the choice between "already-resolved
+ * export" and "lazy HMR-friendly loader" is encoded in the type, not
+ * inferred per-request.
+ *
+ * - `static` — the proxy export is already resolved (production, tests).
+ * - `lazy`   — a loader is called per-request for HMR freshness (dev).
+ *
+ * `PipelineConfig.proxy` also accepts a bare `ProxyExport` (a function or
+ * function array) as shorthand for the static variant — convenient for tests
+ * that construct a `createPipeline` config inline. Omit the field entirely
+ * when the app has no `proxy.ts`.
+ *
+ * See design/07-routing.md §"proxy.ts — Global Middleware".
+ */
+export type ProxyConfig =
+  | { kind: 'static'; export: ProxyExport }
+  | { kind: 'lazy'; loader: () => Promise<{ default: ProxyExport }> };
+
 export interface PipelineConfig {
-  /** The proxy.ts default export (function or array). Undefined if no proxy.ts. */
-  proxy?: ProxyExport;
-  /** Lazy loader for proxy.ts — called per-request so HMR updates take effect. */
-  proxyLoader?: () => Promise<{ default: ProxyExport }>;
+  /**
+   * proxy.ts source. Undefined if the app has no proxy.ts. Accepts either a
+   * tagged `ProxyConfig` (canonical) or a bare `ProxyExport` as sugar for the
+   * static variant.
+   */
+  proxy?: ProxyConfig | ProxyExport;
   /** Route matcher — resolves a canonical pathname to a RouteMatch. */
   matchRoute: RouteMatcher;
   /** Metadata route matcher — resolves metadata route pathnames (sitemap.xml, robots.txt, etc.) */
@@ -209,70 +206,26 @@ export interface PipelineConfig {
   ) => Response | Promise<Response>;
 }
 
-// ─── Param Coercion ────────────────────────────────────────────────────────
-
-/**
- * Run segment param coercion on the matched route's segments.
- *
- * Loads params.ts modules from segments that have them, extracts the
- * segmentParams definition, and coerces raw string params through codecs.
- * Throws ParamCoercionError if any codec fails (→ 404).
- *
- * This runs BEFORE middleware, so ctx.segmentParams is already typed.
- * See design/07-routing.md §"Where Coercion Runs"
- */
-export async function coerceSegmentParams(match: RouteMatch): Promise<void> {
-  const segments = match.segments as unknown as import('./route-matcher.js').ManifestSegmentNode[];
-
-  for (const segment of segments) {
-    // Only process segments that have a params.ts convention file
-    if (!segment.params) continue;
-
-    let mod: Record<string, unknown>;
-    try {
-      mod = await loadModule(segment.params);
-    } catch (err) {
-      throw new ParamCoercionError(
-        `Failed to load params module for segment "${segment.segmentName}": ${err instanceof Error ? err.message : String(err)}`
-      );
-    }
-
-    const segmentParamsDef = mod.segmentParams as
-      | { parse(raw: Record<string, string | string[]>): Record<string, unknown> }
-      | undefined;
-
-    if (!segmentParamsDef || typeof segmentParamsDef.parse !== 'function') continue;
-
-    try {
-      const coerced = segmentParamsDef.parse(match.segmentParams);
-      // Merge coerced values back — use safeMerge to prevent prototype pollution
-      // from malicious/buggy codec output. See TIM-655.
-      safeMerge(match.segmentParams, coerced as Record<string, unknown>);
-    } catch (err) {
-      throw new ParamCoercionError(err instanceof Error ? err.message : String(err));
-    }
-  }
-}
-
 // ─── Pipeline ──────────────────────────────────────────────────────────────
 
 /**
  * Create the request handler from a pipeline configuration.
  *
- * Returns a function that processes an incoming Request through all pipeline stages
- * and produces a Response. This is the top-level entry point for the server.
+ * Returns a function that processes an incoming Request through all pipeline
+ * stages and produces a Response. This is the top-level entry point for the
+ * server. The body is intentionally small — phase logic lives in
+ * `pipeline-phases.ts`. This function only owns the per-request setup that
+ * has to wrap the entire dispatch: trace ID, request context ALS, span
+ * scope, Server-Timing header emission, and the active-request counter.
  */
 export function createPipeline(config: PipelineConfig): (req: Request) => Promise<Response> {
-  const {
-    proxy,
-    matchRoute,
-    render,
-    earlyHints,
-    stripTrailingSlash = true,
-    slowRequestMs = 3000,
-    serverTiming = 'total',
-    onPipelineError,
-  } = config;
+  // Resolve the proxy source once. The request hot path calls this closure
+  // directly with no discriminant check — the branch is taken here during
+  // setup. For the lazy variant, `loader()` still runs per-request so HMR
+  // continues to re-import the user's proxy.ts.
+  const proxyResolver = makeProxyResolver(config.proxy);
+  const slowRequestMs = config.slowRequestMs ?? 3000;
+  const serverTiming = config.serverTiming ?? 'total';
 
   // Concurrent request counter — tracks how many requests are in-flight.
   // Logged with each request for diagnosing resource contention.
@@ -311,10 +264,11 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
               }
 
               let result: Response;
-              if (proxy || config.proxyLoader) {
-                result = await runProxyPhase(req, method, path);
+              if (proxyResolver) {
+                const outcome = await runProxyPhase(config, proxyResolver, req, method, path);
+                result = await outcomeToResponse(config, outcome, { req, method, path });
               } else {
-                result = await handleRequest(req, method, path);
+                result = await handleRequest(config, req, method, path);
               }
 
               // Set response status on the root span before it ends —
@@ -322,13 +276,14 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
               await setSpanAttribute('http.response.status_code', result.status);
 
               // Append Server-Timing header based on configured mode.
-              // Response.redirect() creates immutable headers, so we must
-              // ensure mutability before writing Server-Timing.
+              // Header mutability is guaranteed by the producer-side clone
+              // in `outcomeToResponse` and the metadata-route / auto-sitemap
+              // user-handler clones in `handleRequest`, so we can write
+              // directly without a runtime probe. See TIM-866.
               if (serverTiming === 'detailed') {
                 // Detailed: per-phase breakdown (proxy, middleware, render).
                 const timingHeader = getServerTimingHeader();
                 if (timingHeader) {
-                  result = ensureMutableResponse(result);
                   result.headers.set('Server-Timing', timingHeader);
                 }
               } else if (serverTiming === 'total') {
@@ -336,7 +291,6 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
                 // Prevents information disclosure while giving browser
                 // DevTools useful timing data.
                 const totalMs = Math.round(performance.now() - startTime);
-                result = ensureMutableResponse(result);
                 result.headers.set('Server-Timing', `total;dur=${totalMs}`);
               }
               // serverTiming === false: no header at all
@@ -363,421 +317,4 @@ export function createPipeline(config: PipelineConfig): (req: Request) => Promis
       });
     });
   };
-
-  async function runProxyPhase(req: Request, method: string, path: string): Promise<Response> {
-    try {
-      // Resolve the proxy export. When a proxyLoader is provided (lazy import),
-      // it is called per-request so HMR updates in dev take effect immediately.
-      let proxyExport: ProxyExport;
-      if (config.proxyLoader) {
-        const mod = await config.proxyLoader();
-        proxyExport = mod.default;
-      } else {
-        proxyExport = config.proxy!;
-      }
-      const proxyFn = () => runProxy(proxyExport, req, () => handleRequest(req, method, path));
-      return await withSpan('timber.proxy', {}, () =>
-        serverTiming === 'detailed' ? withTiming('proxy', 'proxy.ts', proxyFn) : proxyFn()
-      );
-    } catch (error) {
-      // Uncaught proxy.ts error → bare HTTP 500
-      logProxyError({ error });
-      await fireOnRequestError(error, req, 'proxy');
-      if (onPipelineError && error instanceof Error) onPipelineError(error, 'proxy');
-      return new Response(null, { status: 500 });
-    }
-  }
-
-  /**
-   * Build a redirect Response from a RedirectSignal.
-   *
-   * For RSC payload requests (client navigation), returns 204 + X-Timber-Redirect
-   * so the client router can perform a soft SPA redirect. A raw 302 would be
-   * turned into an opaque redirect by fetch({redirect:'manual'}), crashing
-   * createFromFetch. See design/19-client-navigation.md.
-   */
-  function buildRedirectResponse(signal: RedirectSignal, req: Request, headers: Headers): Response {
-    const isRsc = (req.headers.get('Accept') ?? '').includes('text/x-component');
-    if (isRsc) {
-      headers.set('X-Timber-Redirect', signal.location);
-      return new Response(null, { status: 204, headers });
-    }
-    headers.set('Location', signal.location);
-    return new Response(null, { status: signal.status, headers });
-  }
-
-  async function handleRequest(req: Request, method: string, path: string): Promise<Response> {
-    // Stage 1: URL canonicalization
-    const url = new URL(req.url);
-    const result = canonicalize(url.pathname, stripTrailingSlash);
-    if (!result.ok) {
-      return new Response(null, { status: result.status });
-    }
-    const canonicalPathname = result.pathname;
-
-    // Stage 1b: Metadata route matching — runs before regular route matching.
-    // Metadata routes skip middleware.ts and access.ts (public endpoints for crawlers).
-    // See design/16-metadata.md §"Pipeline Integration"
-    if (config.matchMetadataRoute) {
-      const metaMatch = config.matchMetadataRoute(canonicalPathname);
-      if (metaMatch) {
-        try {
-          // Static metadata files (.xml, .txt, .png, .ico, etc.) are served
-          // directly from disk. Dynamic metadata routes (.ts, .tsx) export a
-          // handler function that generates the response.
-          if (metaMatch.isStatic) {
-            return await serveStaticMetadataFile(metaMatch);
-          }
-
-          const mod = await loadModule<{ default?: Function }>(metaMatch.file);
-          if (typeof mod.default !== 'function') {
-            return new Response('Metadata route must export a default function', { status: 500 });
-          }
-          const handlerResult = await mod.default();
-          // If the handler returns a Response, use it directly
-          if (handlerResult instanceof Response) {
-            return handlerResult;
-          }
-          // Otherwise, serialize based on content type
-          const contentType = metaMatch.contentType;
-          let body: string;
-          if (typeof handlerResult === 'string') {
-            body = handlerResult;
-          } else if (contentType === 'application/xml') {
-            body = serializeSitemap(handlerResult);
-          } else if (contentType === 'application/manifest+json') {
-            body = JSON.stringify(handlerResult, null, 2);
-          } else {
-            body = typeof handlerResult === 'string' ? handlerResult : String(handlerResult);
-          }
-          return new Response(body, {
-            status: 200,
-            headers: { 'Content-Type': `${contentType}; charset=utf-8` },
-          });
-        } catch (error) {
-          logRenderError({ method, path, error });
-          if (onPipelineError && error instanceof Error) onPipelineError(error, 'metadata-route');
-          return new Response(null, { status: 500 });
-        }
-      }
-    }
-
-    // Stage 1b.2: Auto-generated sitemap — serves /sitemap.xml and /sitemap/N.xml
-    // when sitemap generation is enabled and no user-authored sitemap exists.
-    // Runs after metadata route matching so user sitemaps always take precedence.
-    // See design/16-metadata.md §"Auto-generated Sitemap"
-    if (config.autoSitemapHandler) {
-      try {
-        const sitemapResponse = await config.autoSitemapHandler(canonicalPathname);
-        if (sitemapResponse) return sitemapResponse;
-      } catch (error) {
-        logRenderError({ method, path, error });
-        if (onPipelineError && error instanceof Error) onPipelineError(error, 'auto-sitemap');
-        return new Response(null, { status: 500 });
-      }
-    }
-
-    // Stage 1c: Version skew detection (TIM-446).
-    // For RSC payload requests (client navigation), check if the client's
-    // deployment ID matches the current build. On mismatch, signal the
-    // client to do a full page reload instead of returning an RSC payload
-    // that references mismatched module IDs.
-    const isRscRequest = (req.headers.get('Accept') ?? '').includes('text/x-component');
-    if (isRscRequest) {
-      const skewCheck = checkVersionSkew(req);
-      if (!skewCheck.ok) {
-        const reloadHeaders = new Headers();
-        applyReloadHeaders(reloadHeaders);
-        return new Response(null, { status: 204, headers: reloadHeaders });
-      }
-    }
-
-    // Stage 2: Route matching
-    let match = matchRoute(canonicalPathname);
-    let interception: InterceptionContext | undefined;
-
-    // Stage 2a: Intercepting route resolution (modal pattern).
-    // On soft navigation, check if an intercepting route should render instead.
-    // The client sends X-Timber-URL with the current pathname (where they're
-    // navigating FROM). If a rewrite matches, re-route to the source URL so
-    // the source layout renders with the intercepted content in the slot.
-    const sourceUrl = req.headers.get('X-Timber-URL');
-    if (sourceUrl && config.interceptionRewrites?.length) {
-      const intercepted = findInterceptionMatch(
-        canonicalPathname,
-        sourceUrl,
-        config.interceptionRewrites
-      );
-      if (intercepted) {
-        const sourceMatch = matchRoute(intercepted.sourcePathname);
-        if (sourceMatch) {
-          match = sourceMatch;
-          interception = { targetPathname: canonicalPathname };
-        }
-      }
-    }
-
-    if (!match) {
-      // No route matched — render 404.tsx in root layout if available,
-      // otherwise fall back to a bare 404 Response.
-      if (config.renderNoMatch) {
-        const responseHeaders = new Headers();
-        return config.renderNoMatch(req, responseHeaders);
-      }
-      return new Response(null, { status: 404 });
-    }
-
-    // Response and request header containers — created before early hints so
-    // the emitter can append Link headers (e.g. for Cloudflare CDN → 103).
-    const responseHeaders = new Headers();
-    const requestHeaderOverlay = new Headers();
-
-    // Set Cache-Control for dynamic HTML responses. Without this header,
-    // CDNs (particularly Cloudflare) may attempt to buffer/process the
-    // response differently, causing intermittent multi-second delays.
-    // This matches Next.js's default behavior.
-    responseHeaders.set('Cache-Control', 'private, no-cache, no-store, max-age=0, must-revalidate');
-
-    // Stage 2b: 103 Early Hints (before middleware, after match)
-    // Fires before middleware so the browser can begin fetching critical
-    // assets while middleware runs. Non-fatal — a failing emitter never
-    // blocks the request.
-    if (earlyHints) {
-      try {
-        await earlyHints(match, req, responseHeaders);
-      } catch {
-        // Early hints failure is non-fatal
-      }
-    }
-
-    // Stage 2c: Param coercion (before middleware)
-    // Load params.ts modules from matched segments and coerce raw string
-    // params through defineSegmentParams codecs. Coercion failure → 404
-    // (middleware never runs). See design/07-routing.md §"Where Coercion Runs"
-    try {
-      await coerceSegmentParams(match);
-    } catch (error) {
-      if (error instanceof ParamCoercionError) {
-        // For API routes (route.ts), return a bare 404 — not an HTML page.
-        // API consumers expect JSON/empty responses, not rendered HTML.
-        const leafSegment = match.segments[match.segments.length - 1];
-        if (
-          (leafSegment as { route?: unknown }).route &&
-          !(leafSegment as { page?: unknown }).page
-        ) {
-          return new Response(null, { status: 404 });
-        }
-        // Route through the app's 404 page (404.tsx in root layout) instead of
-        // returning a bare empty 404 Response. Falls back to bare 404 only if
-        // no renderNoMatch renderer is configured.
-        if (config.renderNoMatch) {
-          return config.renderNoMatch(req, responseHeaders);
-        }
-        return new Response(null, { status: 404 });
-      }
-      throw error;
-    }
-
-    // Store coerced segment params in ALS so components can access them
-    // via getSegmentParams() instead of receiving them as a prop.
-    // See design/07-routing.md §"params.ts — Convention File for Typed Params"
-    setSegmentParams(match.segmentParams);
-
-    // Stage 3: Middleware chain (root-to-leaf, short-circuits on first Response)
-    if (match.middlewareChain.length > 0) {
-      const ctx: MiddlewareContext = {
-        req,
-        requestHeaders: requestHeaderOverlay,
-        headers: responseHeaders,
-        segmentParams: match.segmentParams,
-        earlyHints: (hints) => {
-          for (const hint of hints) {
-            // Match Cloudflare's cached Early Hints attribute order: `as` before `rel`.
-            // Cloudflare caches Link headers and re-emits them on subsequent 200s.
-            // If our order differs, the browser sees duplicate preloads and warns.
-            let value: string;
-            if (hint.as !== undefined) {
-              value = `<${hint.href}>; as=${hint.as}; rel=${hint.rel}`;
-            } else {
-              value = `<${hint.href}>; rel=${hint.rel}`;
-            }
-            if (hint.crossOrigin !== undefined) value += `; crossorigin=${hint.crossOrigin}`;
-            if (hint.fetchPriority !== undefined) value += `; fetchpriority=${hint.fetchPriority}`;
-            responseHeaders.append('Link', value);
-          }
-        },
-      };
-
-      try {
-        // Enable cookie mutation during middleware (design/29-cookies.md §"Context Tracking")
-        setMutableCookieContext(true);
-        const chainFn = () => runMiddlewareChain(match.middlewareChain, ctx);
-        const middlewareResponse = await withSpan('timber.middleware', {}, () =>
-          serverTiming === 'detailed' ? withTiming('mw', 'middleware.ts', chainFn) : chainFn()
-        );
-        setMutableCookieContext(false);
-        if (middlewareResponse) {
-          // Apply cookie jar to short-circuit response.
-          // Response.redirect() creates immutable headers, so ensure
-          // mutability before appending Set-Cookie entries.
-          const finalResponse = ensureMutableResponse(middlewareResponse);
-          applyCookieJar(finalResponse.headers);
-          // Merge parent-set responseHeaders onto the short-circuit response.
-          // Child-set headers take precedence — only add headers not already present.
-          // Snapshot existing keys first so multi-value headers (Set-Cookie, Link)
-          // from the parent are all appended when the child didn't set that key.
-          const existingKeys = new Set(
-            [...finalResponse.headers.keys()].map((k) => k.toLowerCase())
-          );
-          for (const [key, value] of responseHeaders.entries()) {
-            if (!existingKeys.has(key.toLowerCase())) {
-              finalResponse.headers.append(key, value);
-            }
-          }
-          logMiddlewareShortCircuit({ method, path, status: finalResponse.status });
-          return finalResponse;
-        }
-        // Middleware chain completed without short-circuiting — apply any
-        // injected request headers so getHeaders() returns them downstream.
-        applyRequestHeaderOverlay(requestHeaderOverlay);
-      } catch (error) {
-        setMutableCookieContext(false);
-        // RedirectSignal from middleware → HTTP redirect (not an error)
-        if (error instanceof RedirectSignal) {
-          applyCookieJar(responseHeaders);
-          return buildRedirectResponse(error, req, responseHeaders);
-        }
-        // DenySignal from middleware → render deny page with correct status code.
-        // Previously returned bare Response(null) — now renders 403.tsx etc.
-        if (error instanceof DenySignal) {
-          applyCookieJar(responseHeaders);
-          if (config.renderDenyFallback) {
-            try {
-              return await config.renderDenyFallback(error, req, responseHeaders, match);
-            } catch {
-              // Deny page rendering failed — fall through to bare response
-            }
-          }
-          return new Response(null, { status: error.status, headers: responseHeaders });
-        }
-        // Middleware throw → HTTP 500 (middleware runs before rendering,
-        // no error boundary to catch it)
-        logMiddlewareError({ method, path, error });
-        await fireOnRequestError(error, req, 'handler');
-        if (onPipelineError && error instanceof Error) onPipelineError(error, 'middleware');
-        return new Response(null, { status: 500 });
-      }
-    }
-
-    // Apply cookie jar to response headers before render commits them.
-    // Middleware may have set cookies; they need to be on responseHeaders
-    // before flushResponse creates the Response object.
-    applyCookieJar(responseHeaders);
-
-    // Stage 4: Render (access gates + element tree + renderToReadableStream)
-    try {
-      const renderFn = () =>
-        render(req, match, responseHeaders, requestHeaderOverlay, interception);
-      const response = await withSpan('timber.render', { 'http.route': canonicalPathname }, () =>
-        serverTiming === 'detailed'
-          ? withTiming('render', 'RSC + SSR render', renderFn)
-          : renderFn()
-      );
-      markResponseFlushed();
-      return response;
-    } catch (error) {
-      // DenySignal leaked from render (e.g. notFound() in metadata()).
-      // Render the deny page with the correct status code.
-      if (error instanceof DenySignal) {
-        if (config.renderDenyFallback) {
-          try {
-            return await config.renderDenyFallback(error, req, responseHeaders, match);
-          } catch {
-            // Deny page rendering failed — fall through to bare response
-          }
-        }
-        return new Response(null, { status: error.status, headers: responseHeaders });
-      }
-      // RedirectSignal leaked from render — honour the redirect
-      if (error instanceof RedirectSignal) {
-        return buildRedirectResponse(error, req, responseHeaders);
-      }
-      logRenderError({ method, path, error });
-      await fireOnRequestError(error, req, 'render');
-      if (onPipelineError && error instanceof Error) onPipelineError(error, 'render');
-      // Try fallback error page before bare 500
-      if (config.renderFallbackError) {
-        try {
-          return await config.renderFallbackError(error, req, responseHeaders);
-        } catch {
-          // Fallback rendering itself failed — fall through to bare 500
-        }
-      }
-      return new Response(null, { status: 500 });
-    }
-  }
-}
-
-/**
- * Fire the user's onRequestError hook with request context.
- * Extracts request info from the Request object and calls the instrumentation hook.
- */
-async function fireOnRequestError(
-  error: unknown,
-  req: Request,
-  phase: 'proxy' | 'handler' | 'render' | 'action' | 'route'
-): Promise<void> {
-  const url = new URL(req.url);
-  const headersObj: Record<string, string> = {};
-  req.headers.forEach((v, k) => {
-    headersObj[k] = v;
-  });
-
-  await callOnRequestError(
-    error,
-    { method: req.method, path: url.pathname, headers: headersObj },
-    { phase, routePath: url.pathname, routeType: 'page', traceId: getTraceId() }
-  );
-}
-
-// ─── Cookie Helpers ──────────────────────────────────────────────────────
-
-/**
- * Apply all Set-Cookie headers from the cookie jar to a Headers object.
- * Each cookie gets its own Set-Cookie header per RFC 6265 §4.1.
- */
-function applyCookieJar(headers: Headers): void {
-  for (const value of getSetCookieHeaders()) {
-    headers.append('Set-Cookie', value);
-  }
-}
-
-// ─── Immutable Response Helpers ──────────────────────────────────────────
-
-/**
- * Ensure a Response has mutable headers so the pipeline can safely append
- * Set-Cookie and Server-Timing entries.
- *
- * `Response.redirect()` and some platform-level responses return objects
- * with immutable headers. Calling `.set()` or `.append()` on them throws
- * `TypeError: immutable`. This helper detects the immutable case by
- * attempting a no-op write and, on failure, clones into a fresh Response
- * with mutable headers.
- */
-function ensureMutableResponse(response: Response): Response {
-  try {
-    // Probe mutability with a benign operation that we immediately undo.
-    // We pick a header name that is extremely unlikely to collide with
-    // anything meaningful and delete it right away.
-    response.headers.set('X-Timber-Probe', '1');
-    response.headers.delete('X-Timber-Probe');
-    return response;
-  } catch {
-    // Headers are immutable — rebuild with mutable headers.
-    return new Response(response.body, {
-      status: response.status,
-      statusText: response.statusText,
-      headers: new Headers(response.headers),
-    });
-  }
 }