@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.211

package/src/server/rsc-entry/render-route.ts

@@ -0,0 +1,229 @@
+/**
+ * Route renderer — turns a matched route into a Response.
+ *
+ * Extracted from `rsc-entry/index.ts` so the entry can stay focused on
+ * pipeline construction. This module owns the steps that happen *after*
+ * the pipeline has matched a route and before it commits a response:
+ * element-tree build, RSC Flight render, and dispatch to either the SSR
+ * HTML path or the RSC payload path. A deny or redirect captured during the
+ * render is rethrown to the pipeline, which answers it.
+ *
+ * The function is parameterized over its dependencies — `clientBootstrap`,
+ * `clientJsDisabled`, `renderDenyFallback`, `globalError` — so the entry passes
+ * them in once at handler-construction time and they ride along on every
+ * call. No globals, no closures over the entry's createRequestHandler
+ * scope.
+ *
+ * Design docs: 02-rendering-pipeline.md, 19-client-navigation.md.
+ */
+
+import type { BuildManifest } from '../build-manifest.ts';
+import {
+  buildCssLinkTags,
+  buildFontPreloadTags,
+  buildModulepreloadTags,
+  collectRouteCss,
+  collectRouteFonts,
+  collectRouteModulepreloads,
+} from '../build-manifest.ts';
+import type { ClientBootstrapConfig } from '../html-injectors.ts';
+import type { InterceptionContext, RouteMatch } from '../pipeline.ts';
+import { DenySignal } from '../primitives.ts';
+import { buildRouteElement, NoPageComponentError } from '../route-element-builder.ts';
+import { recordTiming } from '../server-timing.ts';
+import { parseClientStateTree } from '../state-tree-diff.ts';
+
+import { handleApiRoute } from './api-handler.ts';
+import type { DenyFallbackRenderer } from './deny-fallback.ts';
+import { isRscRequest } from '../../shared/rsc-media-type.ts';
+import { buildRscPayloadResponse } from './rsc-payload.ts';
+import { renderRscStream } from './rsc-stream.ts';
+import { renderSsrResponse } from './ssr-renderer.ts';
+
+/**
+ * Static-per-handler dependencies for `renderRoute` — captured once at
+ * handler construction so each per-request call site only has to pass
+ * the request-specific arguments.
+ */
+export interface RenderRouteDeps {
+  clientBootstrap: ClientBootstrapConfig;
+  clientJsDisabled: boolean;
+  clientSegmentCache: boolean;
+  renderDenyFallback: DenyFallbackRenderer;
+  buildManifest: BuildManifest;
+  globalError?: { load: () => Promise<unknown>; filePath: string };
+}
+
+/**
+ * Render a matched route to an HTML Response via RSC → SSR pipeline,
+ * or return a raw RSC Flight stream for client-side navigation requests.
+ *
+ * 1. Load page/layout components from the segment chain
+ * 2. Resolve metadata
+ * 3. Render to RSC Flight stream (serializes "use client" as references)
+ * 4. If Accept: text/x-component → return RSC stream directly
+ *    Otherwise → pass RSC stream to SSR entry for HTML rendering
+ */
+export async function renderRoute(
+  req: Request,
+  match: RouteMatch,
+  responseHeaders: Headers,
+  deps: RenderRouteDeps,
+  interception?: InterceptionContext
+): Promise<Response> {
+  const { clientBootstrap, clientJsDisabled, buildManifest, globalError } = deps;
+  const segments = match.segments;
+  const leaf = segments[segments.length - 1];
+
+  // API routes (route.ts) — run access.ts standalone then dispatch to handler.
+  // No React render pass — AccessGate is not used, React.cache is not active.
+  // See design/04-authorization.md §"Auth in API Routes".
+  if (leaf.route && !leaf.page) {
+    return handleApiRoute(req, segments, responseHeaders);
+  }
+
+  // Parse X-Timber-State-Tree for RSC payload requests (client navigation).
+  // The state tree lists sync segments the client has cached — the server
+  // skips re-rendering those layouts for a smaller, faster RSC payload.
+  // Only used for RSC requests — HTML requests always get a full render.
+  // See design/19-client-navigation.md §"X-Timber-State-Tree Header"
+  const clientStateTree =
+    deps.clientSegmentCache && isRscRequest(req) ? parseClientStateTree(req) : null;
+
+  // Build the React element tree — runs access checks eagerly to gate
+  // metadata resolution (TIM-1027), then loads modules and resolves
+  // metadata for non-denied segments. Denied segments' verdicts are
+  // passed to AccessGate for in-tree replay. Passing segments' access
+  // re-runs during render for React.cache population (TIM-662).
+  let routeResult;
+  const _buildStart = performance.now();
+  try {
+    routeResult = await buildRouteElement(
+      req,
+      match,
+      interception,
+      clientStateTree,
+      buildManifest.metadataRouteHashes
+    );
+  } catch (error) {
+    // No PageComponent found — render the app's 404 page as for an
+    // unmatched URL: the root chain, not the matched one. No access.ts has
+    // run for the matched chain yet, so its layouts must not wrap the page
+    // (design/13-security.md). The deny fallback is the one assembler of
+    // that page; calling it with no match selects the root chain.
+    if (error instanceof NoPageComponentError) {
+      if (process.env.NODE_ENV !== 'production') {
+        console.warn(`[timber] ${error.message}`);
+      }
+      return deps.renderDenyFallback(new DenySignal(404), req, responseHeaders);
+    }
+    throw error;
+  }
+
+  const _buildEnd = performance.now();
+  recordTiming({
+    name: 'build',
+    dur: Math.round(_buildEnd - _buildStart),
+    desc: 'build element tree',
+  });
+
+  const {
+    payload,
+    layoutComponents,
+    deferSuspenseFor,
+    skippedSegments,
+    slotSkipInfo,
+    leafDenyChain,
+  } = routeResult;
+
+  // Build head HTML for injection into the SSR output.
+  // Collects CSS, fonts, and modulepreload from the build manifest for matched segments.
+  // In dev mode the manifest is empty — Vite HMR handles CSS/JS.
+  //
+  // Link headers (for 103 Early Hints) are emitted by the earlyHints pipeline
+  // stage before middleware runs. Here we only emit the <head> HTML fallback tags
+  // — these ensure resources load even on platforms without Early Hints support.
+  let headHtml = '';
+
+  // Font CSS is NOT inlined here anymore (TIM-828). The transform hook
+  // injects a side-effect `import 'virtual:timber-font-css/<hash>.css'`
+  // into each file that calls a font function. @vitejs/plugin-rsc's
+  // `collectCss` walks the RSC module graph, finds the virtual CSS
+  // module, and React Float `preinit()`s it as
+  // `<link rel="stylesheet" data-rsc-css-href=...>` — the same path
+  // component CSS rides on. Dev and production share a single path,
+  // with no `globalThis` channel and no dev/prod skew.
+  //
+  // Font preload hints (distinct from the @font-face CSS) still flow
+  // through `BuildManifest.fonts[importer]` and are emitted below plus
+  // as 103 Early Hints via `buildEarlyHintsHeaders()`.
+  const fontEntries = collectRouteFonts(segments, buildManifest);
+  if (fontEntries.length > 0) {
+    headHtml += buildFontPreloadTags(fontEntries);
+  }
+
+  // Emit <link rel="stylesheet"> tags for per-route CSS (TIM-1014).
+  // React Float also emits stylesheet links via preinit() during Fizz
+  // rendering, but those arrive too late — after the RSC stream starts.
+  // These <head> tags ensure CSS is discovered during HTML parsing.
+  // Float deduplicates, so no double-fetch.
+  const cssUrls = collectRouteCss(segments, buildManifest);
+  if (cssUrls.length > 0) {
+    headHtml += buildCssLinkTags(cssUrls);
+  }
+
+  // Skip modulepreload tags when client JavaScript is disabled — no JS to preload.
+  if (!clientJsDisabled) {
+    const preloadUrls = collectRouteModulepreloads(segments, buildManifest);
+    if (preloadUrls.length > 0) {
+      headHtml += buildModulepreloadTags(preloadUrls);
+    }
+  }
+
+  // Metadata tags (<title>, <meta>, <link>) are now rendered as React
+  // elements in the route element tree — React 19 Float hoists them into
+  // <head> during SSR and manages them during client rendering. No string
+  // splice needed. See TIM-1151.
+
+  // Render to RSC Flight stream with signal tracking.
+  const _rscStart = performance.now();
+  const { rscStream, signals } = renderRscStream(payload, req, leafDenyChain);
+
+  recordTiming({
+    name: 'rsc-init',
+    dur: Math.round(performance.now() - _rscStart),
+    desc: 'RSC stream init',
+  });
+
+  // For RSC payload requests (client navigation), return the RSC Flight
+  // stream directly — skip SSR HTML rendering entirely.
+  // See design/19-client-navigation.md §"RSC Payload Handling"
+  if (isRscRequest(req)) {
+    return buildRscPayloadResponse(
+      rscStream,
+      signals,
+      segments,
+      layoutComponents,
+      responseHeaders,
+      skippedSegments,
+      slotSkipInfo
+    );
+  }
+
+  // Pipe through SSR for HTML rendering with streaming Suspense support.
+  return renderSsrResponse({
+    req,
+    rscStream,
+    signals,
+    segments,
+    layoutComponents,
+    match,
+    responseHeaders,
+    clientBootstrap,
+    clientJsDisabled,
+    headHtml,
+    deferSuspenseFor,
+    globalError,
+    slotSkipInfo,
+  });
+}

package/src/server/rsc-entry/render-signals.ts

@@ -0,0 +1,108 @@
+/**
+ * Render signals — the deny / redirect / unhandled-error state one RSC
+ * render captures, and the recorder that writes it.
+ *
+ * Kept apart from `rsc-stream.ts` so the contract carries no Flight runtime:
+ * consumers and tests can hold signals without loading the renderer.
+ *
+ * Design docs: 02-rendering-pipeline.md §"Single-Pass Rendering",
+ *              49-explicit-subsystem-boundaries.md §"C"
+ */
+
+import type { DenySignal, RedirectSignal } from '../primitives.ts';
+
+/**
+ * Signal state captured during RSC rendering. Read-only for consumers: only
+ * the render that produced it records into it (`createSignalRecorder`).
+ *
+ * Signals fire asynchronously via `onError` during stream consumption.
+ * The first deny wins; a later redirect replaces an earlier one.
+ *
+ * The two notification channels are values the producer owns and returns,
+ * not callback slots a consumer assigns after the fact. A slot only works if
+ * no `await` separates `renderRscStream()` from the assignment — add one and
+ * an early signal fires into an empty slot with no trace. A promise that has
+ * already resolved, and an `AbortSignal` that is already aborted, carry the
+ * early event to a late reader.
+ */
+export interface RenderSignals {
+  readonly denySignal: DenySignal | null;
+  /**
+   * The first deny that no in-tree catch site could place — no `owners`, so
+   * no boundary may claim its error row and only the re-render fallback can
+   * produce a page for it.
+   *
+   * Tracked apart from `denySignal` because one render can produce both. A
+   * deep page can hoist a 404 to a boundary that will render it while an
+   * outer layout separately throws a 403 nothing matches; whichever lands in
+   * `denySignal` first, the unplaced one still needs the fallback, and
+   * deciding from `denySignal.owners` alone would strand it. See TIM-1356.
+   */
+  readonly unplacedDeny: DenySignal | null;
+  readonly redirectSignal: RedirectSignal | null;
+  /**
+   * Resolves when the first deny or redirect is captured; never rejects.
+   * Consumers race it to react the instant `onError` fires instead of
+   * polling with setTimeout/queueMicrotask.
+   */
+  readonly captured: Promise<void>;
+  /**
+   * Aborted when the first unhandled (non-signal) error is captured. Halts
+   * Flight data injection into the inline stream (TIM-938).
+   */
+  readonly unhandledError: AbortSignal;
+}
+
+/** The write side of `RenderSignals`, held by the render that captures. */
+export interface SignalRecorder {
+  readonly signals: RenderSignals;
+  deny(signal: DenySignal): void;
+  redirect(signal: RedirectSignal): void;
+  unhandledError(): void;
+}
+
+/**
+ * Create the signal state for one render. `renderRscStream()` records into
+ * it from Flight's `onError`; tests record into it to stand in for Flight.
+ */
+export function createSignalRecorder(): SignalRecorder {
+  let denySignal: DenySignal | null = null;
+  let unplacedDeny: DenySignal | null = null;
+  let redirectSignal: RedirectSignal | null = null;
+  let notifyCaptured!: () => void;
+  const captured = new Promise<void>((resolve) => {
+    notifyCaptured = resolve;
+  });
+  const errorAbort = new AbortController();
+
+  return {
+    signals: {
+      get denySignal() {
+        return denySignal;
+      },
+      get unplacedDeny() {
+        return unplacedDeny;
+      },
+      get redirectSignal() {
+        return redirectSignal;
+      },
+      captured,
+      unhandledError: errorAbort.signal,
+    },
+    deny(signal) {
+      // First-wins: two concurrent denies from separately serialized
+      // subtrees must commit a deterministic status. See
+      // spike-TIM-1441 §"two-concurrent-denials scenario".
+      denySignal ??= signal;
+      if (!signal.owners) unplacedDeny ??= signal;
+      notifyCaptured();
+    },
+    redirect(signal) {
+      redirectSignal = signal;
+      notifyCaptured();
+    },
+    unhandledError() {
+      errorAbort.abort();
+    },
+  };
+}

package/src/server/rsc-entry/revalidate-renderer.ts

@@ -0,0 +1,349 @@
+/**
+ * Revalidation renderer — builds the React element tree for the target
+ * path requested by `revalidatePath()` from inside a server action, with
+ * the same security guarantees as a normal route render.
+ *
+ * Before this module existed, `revalidatePath()` matched the route, coerced
+ * params, and called `buildRouteElement()` directly. That bypassed the
+ * target route's `middleware.ts` chain entirely. An action that revalidated
+ * a higher-privilege or user-controlled path could leak an authenticated
+ * RSC tree to the action submitter even when middleware on that path
+ * would have denied them.
+ *
+ * The fix (TIM-996) is to run the target route's middleware chain inside
+ * a fresh `runWithRequestContext` scope BEFORE building the element tree,
+ * propagate `DenySignal` and `RedirectSignal` to `executeAction`, drop the
+ * revalidation when middleware returns a short-circuit `Response`, and
+ * lift the request-header overlay onto the action's ALS store so the
+ * revalidated component render sees middleware-injected headers via
+ * `getHeaders()`.
+ *
+ * The input `path` is also validated as a local root-relative pathname so
+ * `revalidatePath('//evil.com/admin')` and similar scheme/authority
+ * injections cannot smuggle a foreign host through `new URL(path, base)`.
+ *
+ * See design/08-forms-and-actions.md §"revalidatePath()" and
+ * design/13-security.md §"Server actions silently bypass middleware".
+ */
+
+import { stringifyCookie } from 'cookie';
+
+import type { BuildManifest } from '../build-manifest.ts';
+import { canonicalize } from '../canonicalize.ts';
+import { getCookiesForSsr } from '../cookie-context.ts';
+import { logRenderError } from '../logger.ts';
+import { ParamCoercionError } from '../param-coercion.ts';
+import type { RouteMatch, RouteMatcher } from '../pipeline.ts';
+import { DenySignal, RedirectSignal } from '../primitives.ts';
+import { applyRequestHeaderOverlay, setSegmentParams } from '../request-context.ts';
+import { requestContextAls } from '../als-registry.ts';
+import { buildRouteElement } from '../route-element-builder.ts';
+import { createReactCacheScope } from '../react-cache-scope.ts';
+import {
+  RevalidationDropped,
+  type RevalidateRenderer,
+  type RevalidationResult,
+} from '../actions.ts';
+import type { CoercedParams } from '../../shared/param-value.ts';
+
+import { runMiddlewareForAction } from './action-middleware-runner.ts';
+import { RSC_CONTENT_TYPE } from '../../shared/rsc-media-type.ts';
+
+/** Result of validating a `revalidatePath()` argument. */
+type PathValidation =
+  | { ok: true; pathname: string; search: string }
+  | { ok: false; reason: string };
+
+/**
+ * Validate a `revalidatePath()` argument.
+ *
+ * Accepts local root-relative pathnames only. Rejects anything that
+ * `new URL(path, base)` would resolve to a different host or scheme:
+ *
+ *   - Empty / non-string input
+ *   - Anything not starting with `/` (relative, scheme-bearing, etc.)
+ *   - Protocol-relative `//evil.com/admin` — resolves to scheme://evil.com
+ *   - Backslash-prefixed `/\evil.com` — some clients fold `\` into `/`
+ *   - Control characters and null bytes
+ *   - Paths that fail canonicalization (encoded separators, `..` escaping
+ *     root, malformed percent-encoding)
+ *
+ * The pathname is canonicalized so the rest of the renderer matches the
+ * same shape the page pipeline matches.
+ */
+export function validateRevalidatePath(path: unknown): PathValidation {
+  if (typeof path !== 'string' || path.length === 0) {
+    return { ok: false, reason: 'must be a non-empty string' };
+  }
+  if (!path.startsWith('/')) {
+    return { ok: false, reason: 'must start with "/" (root-relative path)' };
+  }
+  if (path.startsWith('//')) {
+    return { ok: false, reason: 'must not start with "//" (protocol-relative URL)' };
+  }
+  if (path.startsWith('/\\')) {
+    return { ok: false, reason: 'must not start with "/\\" (backslash injection)' };
+  }
+  for (let i = 0; i < path.length; i++) {
+    const code = path.charCodeAt(i);
+    if (code <= 0x1f || code === 0x7f) {
+      return { ok: false, reason: 'must not contain control characters' };
+    }
+  }
+  const hashIndex = path.indexOf('#');
+  // Fragments are meaningless server-side and would not be sent back to
+  // the client on revalidation anyway. Drop them silently before splitting
+  // the query so a `#` cannot smuggle additional path content past the
+  // canonicalizer.
+  const noFragment = hashIndex >= 0 ? path.slice(0, hashIndex) : path;
+  const queryIndex = noFragment.indexOf('?');
+  const pathnameOnly = queryIndex >= 0 ? noFragment.slice(0, queryIndex) : noFragment;
+  const search = queryIndex >= 0 ? noFragment.slice(queryIndex) : '';
+  const canonical = canonicalize(pathnameOnly, true);
+  if (!canonical.ok) {
+    return { ok: false, reason: `failed URL canonicalization (status ${canonical.status})` };
+  }
+  return { ok: true, pathname: canonical.pathname, search };
+}
+
+/**
+ * Serialize a cookie map into a `Cookie:` request header value
+ * (`name1=value1; name2=value2`).
+ *
+ * The RYW map holds decoded logical values (decodeURIComponent has
+ * already run), so we use the default encode (encodeURIComponent) to
+ * re-encode for the wire — mirroring getCookieJar().toString().
+ *
+ * Total — never throws. Malformed inbound cookie names (e.g. spaces)
+ * survive parseCookie but make stringifyCookie throw, so we fall back
+ * to a manual join to stay total over arbitrary request headers.
+ */
+function serializeCookieMap(cookies: Map<string, string>): string {
+  try {
+    return stringifyCookie(Object.fromEntries(cookies));
+  } catch {
+    return Array.from(cookies.entries())
+      .map(([name, value]) => `${name}=${encodeURIComponent(value)}`)
+      .join('; ');
+  }
+}
+
+/** Coerce a matched route's raw segment params via its `app/schema.ts` codecs. */
+export type CoerceSegmentParamsFn = (match: RouteMatch) => Promise<CoercedParams>;
+
+/** Dependencies for the revalidate renderer factory. */
+export interface RevalidateRendererDeps {
+  matchRoute: RouteMatcher;
+  coerceSegmentParams: CoerceSegmentParamsFn;
+  buildManifest: BuildManifest;
+}
+
+/**
+ * Build a per-request `RevalidateRenderer`.
+ *
+ * The returned renderer:
+ *   1. Validates the requested path.
+ *   2. Matches the canonicalized path against the route tree.
+ *   3. Coerces segment params via the `app/schema.ts` codecs.
+ *   4. Runs the matched route's `middleware.ts` chain inside a fresh
+ *      `runWithRequestContext` scope (via `runMiddlewareForAction`).
+ *      Deny/redirect signals are re-thrown so `executeAction` can apply
+ *      its existing redirect handling and the new deny-drop behavior.
+ *      A short-circuit `Response` becomes `RevalidationDropped`.
+ *   5. Lifts the request-header overlay onto the OUTER action's ALS store
+ *      so the revalidated component render (which happens later inside
+ *      `renderToReadableStream` in the action's scope) observes
+ *      middleware-injected headers via `getHeaders()`. Acceptable because
+ *      revalidation runs after the action body has returned — the only
+ *      remaining ALS readers are render-phase code that should see the
+ *      same overlay a normal page render would see.
+ *   6. Builds and returns the route element tree, ready for the action
+ *      handler to serialize alongside the action result.
+ *
+ * Cookies set inside the revalidation middleware are intentionally NOT
+ * propagated to the action response. The middleware on a *different* path
+ * setting cookies via the action's response is surprising semantics; the
+ * scoped cookie jar on the inner ALS run is discarded with the scope.
+ * The primary security boundary closed here is auth — `deny()` from the
+ * target's middleware now prevents the revalidated tree from leaking.
+ */
+export function createRevalidateRendererFactory(
+  deps: RevalidateRendererDeps
+): (req: Request) => RevalidateRenderer {
+  return (req: Request): RevalidateRenderer => {
+    return async (path: string): Promise<RevalidationResult> => {
+      // ── 1. Validate the path ────────────────────────────────────────
+      const validation = validateRevalidatePath(path);
+      if (!validation.ok) {
+        // Throwing a typed error here drops the revalidation. We do not
+        // surface the message to the client (logRenderError sinks it).
+        const err = new RevalidationDropped(
+          `revalidatePath(${JSON.stringify(path)}) rejected: ${validation.reason}`
+        );
+        logRenderError({ method: req.method, path: new URL(req.url).pathname, error: err });
+        throw err;
+      }
+
+      // ── 2. Build the revalidation Request on the canonical pathname ─
+      //
+      // Use the canonical pathname (not the raw input) so the rebuilt
+      // URL cannot carry a hostile authority — `new URL('//evil.com/x',
+      // base)` would otherwise resolve to scheme://evil.com/x. Forward
+      // the original action request's headers (session IDs, accept-
+      // language, etc.) so middleware on the target route sees the same
+      // identity the action did.
+      //
+      // The `Cookie:` header is REBUILT from the action's
+      // read-your-own-writes cookie state rather than copied from the
+      // inbound request. An action that rotates the session via
+      // `getCookieJar().set('session', newToken)` and then calls
+      // `revalidatePath('/dashboard')` should have the target route's
+      // middleware see the NEW session — otherwise a session-rotation
+      // action would succeed only to have the piggybacked revalidation
+      // redirect to /login. `getCookieJar()` writes only update the ALS
+      // jar, not the immutable `Request.headers`, so without this step
+      // middleware reading `ctx.req.headers.get('cookie')` sees stale
+      // values. Codex P2.
+      const baseUrl = new URL(req.url);
+      const revalidateUrl = new URL(baseUrl.origin);
+      revalidateUrl.pathname = validation.pathname;
+      revalidateUrl.search = validation.search;
+      const revalidateHeaders = new Headers(req.headers);
+      revalidateHeaders.set('Accept', RSC_CONTENT_TYPE);
+      // Snapshot the action's post-mutation cookie map (deletions
+      // included) and serialize it into a `Cookie:` header value the
+      // target middleware can read off `ctx.req.headers.get('cookie')`.
+      // Only attempt this inside a request context — `getCookiesForSsr`
+      // throws otherwise — and bail out gracefully if no context is
+      // active (the legacy call-site contract permitted this).
+      //
+      // The same map becomes the middleware scope's parsed cookies, so
+      // its `runWithRequestContext` skips `parseCookieHeader` — the H-3
+      // smuggling primitive mitigated by TIM-868. The Cookie header stays
+      // for code that reads `ctx.req.headers.get('cookie')` directly.
+      const ryw = requestContextAls.getStore() ? getCookiesForSsr() : undefined;
+      if (ryw) {
+        if (ryw.size === 0) {
+          revalidateHeaders.delete('cookie');
+        } else {
+          revalidateHeaders.set('cookie', serializeCookieMap(ryw));
+        }
+      }
+      const revalidateReq = new Request(revalidateUrl.toString(), {
+        headers: revalidateHeaders,
+      });
+
+      // ── 3. Match the canonical path and coerce its params ───────────
+      //
+      // Coercion runs before middleware, as in the page pipeline, and on
+      // both branches below. The match keeps its raw params beside the
+      // coerced ones, so slot resolution in step 6 reads URL values.
+      const rawMatch = deps.matchRoute(validation.pathname);
+      if (!rawMatch) {
+        throw new Error(`revalidatePath('${path}') — no matching route`);
+      }
+      let match: RouteMatch;
+      try {
+        match = { ...rawMatch, segmentParams: await deps.coerceSegmentParams(rawMatch) };
+      } catch (error) {
+        // Bad params on the target path — drop revalidation. The action's
+        // own response still goes back to the client.
+        if (error instanceof ParamCoercionError) {
+          throw new RevalidationDropped(
+            `revalidatePath('${path}') — segment param coercion failed`
+          );
+        }
+        throw error;
+      }
+
+      // ── 4. Run middleware in a fresh ALS scope ──────────────────────
+      //
+      // We only run middleware when the matched chain has at least one
+      // entry. Routes with no middleware skip this step (no scope, no
+      // overlay) — matching the page pipeline's behavior in
+      // `handleRequest` where `runMiddlewarePhase` is gated on
+      // `middlewareChain.length > 0`.
+      //
+      // The scope opened here is fresh — the action body read through its
+      // own scope before it mutated — and the revalidated tree renders in it
+      // later, so this middleware shares React.cache with that render.
+      const reactCacheScope = createReactCacheScope();
+      let overlay: Headers | undefined;
+      if (match.middlewareChain.length > 0) {
+        const outcome = await runMiddlewareForAction(revalidateReq, match, {
+          reactCacheScope,
+          cookies: ryw,
+        });
+
+        if (outcome.kind === 'error') {
+          // Re-throw unhandled middleware errors so `executeAction` logs
+          // them and the action handler reports them. Not surfaced to the
+          // action client (revalidation is best-effort).
+          throw outcome.error;
+        }
+        if (outcome.kind === 'redirect') {
+          // Propagate the redirect — `executeAction` catches
+          // RedirectSignal and converts it to an action-level redirect.
+          // See actions.ts §"Process path revalidation".
+          throw outcome.signal;
+        }
+        if (outcome.kind === 'deny') {
+          // Propagate the deny — `executeAction` catches DenySignal
+          // (added in this PR) and drops the revalidation.
+          throw outcome.signal;
+        }
+        if (outcome.kind === 'short-circuit') {
+          // Middleware returned a Response directly. A redirect Response
+          // (`return Response.redirect('/login')` or a 3xx + Location)
+          // is the same outcome as throwing `redirect()` — common for
+          // session-expiry / feature-flag gates — and the action client
+          // should follow it. Translate to a `RedirectSignal` so
+          // `executeAction` surfaces it as the action redirect, matching
+          // the normal page-pipeline behavior promised in
+          // design/08-forms-and-actions.md §"revalidatePath()". Codex P2.
+          const status = outcome.response.status;
+          const location = outcome.response.headers.get('location');
+          if (status >= 300 && status < 400 && location) {
+            throw new RedirectSignal(location, status);
+          }
+          // Any other short-circuit Response (200/403/418/etc.) cannot
+          // be translated to a piggy-backed element tree. Drop the
+          // revalidation; the action result still ships.
+          throw new RevalidationDropped(
+            `revalidatePath('${path}') — middleware returned a short-circuit Response (status ${status})`
+          );
+        }
+
+        // `continue` — capture the overlay so we can apply it to the
+        // action's request-context store below. Cookies the middleware set
+        // are not forwarded; see this factory's docstring for why.
+        overlay = outcome.overlay;
+      }
+
+      // ── 5. Lift state onto the action's ALS store ───────────────────
+      //
+      // Segment params are set unconditionally so `getSegmentParams()`
+      // inside the revalidated tree returns the target path's coerced
+      // params, not the action route's. The overlay is applied only
+      // when middleware ran and produced headers — otherwise we leave
+      // the action's `headers()` view untouched.
+      setSegmentParams(match.segmentParams);
+      if (overlay) {
+        applyRequestHeaderOverlay(overlay);
+      }
+
+      // ── 6. Build the route element tree ─────────────────────────────
+      const routeResult = await buildRouteElement(
+        revalidateReq,
+        match,
+        undefined,
+        null,
+        deps.buildManifest.metadataRouteHashes
+      );
+      return {
+        payload: routeResult.payload,
+        reactCacheScope,
+      };
+    };
+  };
+}