@rangojs/router 0.27.0 → 0.29.0

package/src/router/segment-resolution/revalidation.ts

@@ -1,9 +1,14 @@
 /**
- * Revalidation Path Segment Resolution
+ * The segment walker.
  *
- * Functions for resolving segments during partial (revalidation) requests.
- * Mirrors the fresh path but adds revalidation awareness: only re-resolves
- * segments whose revalidate() predicate returns true.
+ * Resolves a matched chain's segments (loaders, layouts, routes, parallels,
+ * orphan layouts, error boundaries) in handler-first order. A partial request
+ * re-resolves only what the client lacks and what a held segment's
+ * revalidate() rules ask for. A full match (a document, the background
+ * re-render of a route record, a build-time prerender) walks the same code
+ * with `pass.client === FRESH` (resolution-pass.ts): every segment is new,
+ * and the branches marked FRESH keep what the full match has always done
+ * differently.
  */
 
 import type { ReactNode } from "react";
@@ -18,6 +23,7 @@ import {
   getParallelSlotEntries,
   type EntryData,
   type LoaderEntry,
+  type ParallelEntries,
   type ParallelEntryData,
 } from "../../server/context";
 import type {
@@ -26,18 +32,20 @@ import type {
   ResolvedSegment,
   ShouldRevalidateFn,
 } from "../../types";
-import type {
-  SegmentResolutionDeps,
-  SegmentRevalidationResult,
-  ActionContext,
-} from "../types.js";
+import type { SegmentRevalidationResult } from "../types.js";
+import type { InterceptResult } from "../router-context.js";
+import { FRESH, type ResolutionPass } from "./resolution-pass.js";
 import {
   debugLog,
   pushRevalidationTraceEntry,
   isTraceActive,
 } from "../logging.js";
 import { resolveLoaderData } from "./loader-cache.js";
-import { entryLoadingMasksLoaders } from "./loader-mask.js";
+import {
+  entryLoadingMasksLoaders,
+  isShellCaptureActive,
+} from "./loader-mask.js";
+import { _getRequestContext } from "../../server/request-context.js";
 import {
   defersLoader,
   deferUnit,
@@ -54,13 +62,13 @@ import {
   resolveLayoutComponent,
   resolveWithErrorBoundary,
   buildLoaderErrorContext,
+  noteThrower,
 } from "./helpers.js";
 import { applyViewTransitionDefault } from "./view-transition-default.js";
 import { isLayoutLoaderCopy } from "../../client-urls/layout-loader-copies.js";
 import { getRouterContext } from "../router-context.js";
 import { observeEvent, observeSegmentHandler } from "../instrument.js";
 import { withReverseScope } from "../handler-context.js";
-import { runInSegmentTagScope } from "../../cache/cache-tag.js";
 import { trackStreamedHandler } from "./streamed-handler-boundary.js";
 import {
   track,
@@ -116,24 +124,60 @@ function emitRevalidationDecision(
   });
 }
 
+/** What evaluateRevalidation reads from the pass, the same for every segment. */
+function revalidationInputOf<TEnv>(
+  pass: ResolutionPass<TEnv>,
+): Pick<
+  EvaluateRevalidationOptions<TEnv>,
+  | "prevParams"
+  | "getPrevSegment"
+  | "request"
+  | "prevUrl"
+  | "nextUrl"
+  | "routeKey"
+  | "context"
+  | "actionContext"
+  | "stale"
+> {
+  return {
+    prevParams: pass.prevParams,
+    getPrevSegment: null,
+    // Only a build-time FRESH pass lacks a request, and it decides nothing.
+    request: pass.request!,
+    prevUrl: pass.prevUrl,
+    nextUrl: pass.nextUrl,
+    routeKey: pass.routeKey,
+    context: pass.context,
+    actionContext: pass.actionContext,
+    stale: pass.stale,
+  };
+}
+
 /**
- * Whether a segment the client holds (`held`, the set resolution works on)
- * renders again. A fill keeps it (prefetch-deferral.ts fillSends): no
+ * Whether a segment the client holds (`pass.client`, the set resolution works
+ * on) renders again. A fill keeps it (prefetch-deferral.ts fillSends): no
  * revalidate() predicate runs and nothing is traced or observed. Any other
  * request asks the segment's revalidate() chain, and `onEvaluated` sees that
  * answer.
  */
-async function revalidateHeld<TEnv>({
-  held,
-  onEvaluated,
-  ...options
-}: EvaluateRevalidationOptions<TEnv> & {
-  held: ReadonlySet<string>;
-  onEvaluated?: (shouldRevalidate: boolean) => void;
-}): Promise<boolean> {
-  const fill = fillSends(options.context, options.segment.id, held);
+async function revalidateHeld<TEnv>(
+  pass: ResolutionPass<TEnv>,
+  {
+    onEvaluated,
+    ...held
+  }: Pick<
+    EvaluateRevalidationOptions<TEnv>,
+    "segment" | "revalidations" | "traceSource"
+  > & {
+    onEvaluated?: (shouldRevalidate: boolean) => void;
+  },
+): Promise<boolean> {
+  const fill = fillSends(pass.context, held.segment.id, pass.client);
   if (fill !== undefined) return fill;
-  const shouldRevalidate = await evaluateRevalidation(options);
+  const shouldRevalidate = await evaluateRevalidation({
+    ...revalidationInputOf(pass),
+    ...held,
+  });
   onEvaluated?.(shouldRevalidate);
   return shouldRevalidate;
 }
@@ -166,7 +210,7 @@ export function deliverStartedLoaders<TEnv>(
   if (plan?.mode !== "prefetch") return;
   const internal = ctx as InternalHandlerContext<any, TEnv>;
   const started = (loaderId: string): boolean =>
-    plan.deferredLoaders?.get(loaderId)?.started === true ||
+    internal._deferredLoaders?.get(loaderId)?.started === true ||
     internal._loaderStarted?.(loaderId) === true;
   for (const segment of segments) {
     if (!segment.deferred || segment.type !== "loader") continue;
@@ -178,7 +222,7 @@ export function deliverStartedLoaders<TEnv>(
 }
 
 // ---------------------------------------------------------------------------
-// Revalidation path (partial match)
+// Loaders
 // ---------------------------------------------------------------------------
 
 /**
@@ -199,6 +243,11 @@ export interface LoaderOwner {
    * False for an intercept: never a document.
    */
   readonly bakeLane: boolean;
+  /**
+   * The owner declares loading(false). A FRESH pass then settles every loader
+   * before the handler runs (resolveOwnerLoaders). Unset for an intercept.
+   */
+  readonly loadingDisabled?: boolean;
   readonly traceSource: "loader" | "intercept-loader";
 }
 
@@ -213,137 +262,185 @@ export function ownerOf(
     segmentPrefix: shortCodeOverride ?? entry.shortCode,
     boundary: entry,
     bakeLane: !entryLoadingMasksLoaders(entry.loading),
+    loadingDisabled: entry.loading === false,
     traceSource: "loader",
   };
 }
 
 /**
- * The partial lane's one loader funnel: each loader is a segment, run when
- * the client lacks it, asked its revalidate() when held, kept outright in a
- * fill (fillSends), deferred in a prefetch that defers it (defersLoader).
+ * resolveOwnerLoaders has something to resolve for `entry`'s loaders. The
+ * walker checks before the call: most entries own none, and the async call
+ * would cost a promise and microtask ticks for an empty result.
+ */
+function ownsLoaders(entry: EntryData): boolean {
+  return (entry.loader?.length ?? 0) > 0;
+}
+
+/** getParallelSlotEntries(parallels) lists a slot. */
+function declaresSlot(parallels: ParallelEntries): boolean {
+  for (const slot in parallels) {
+    if (parallels[slot as `@${string}`]) return true;
+  }
+  return false;
+}
+
+/**
+ * Register flagged loader $$ids on the request context and return their
+ * indices. Must run BEFORE kickoff: rendered() checks the set to fail
+ * fast on the barrier cycle (resolution awaits the loader, the barrier
+ * awaits resolution).
+ */
+function registerAwaitBeforeFlushIds(
+  loaderEntries: readonly LoaderEntry[],
+): number[] {
+  const awaitedIndices: number[] = [];
+  for (let i = 0; i < loaderEntries.length; i++) {
+    if (loaderEntries[i]!.awaitBeforeFlush) awaitedIndices.push(i);
+  }
+  if (awaitedIndices.length > 0) {
+    const reqCtx = _getRequestContext();
+    if (reqCtx) {
+      reqCtx._awaitBeforeFlushLoaderIds ??= new Set();
+      for (const i of awaitedIndices) {
+        reqCtx._awaitBeforeFlushLoaderIds.add(loaderEntries[i]!.loader.$$id);
+      }
+    }
+  }
+  return awaitedIndices;
+}
+
+const AWAIT_BEFORE_FLUSH = { awaitBeforeFlush: true } as const;
+
+/** Spread into a FRESH loader segment: the flag, or nothing. */
+function stampAwaitBeforeFlush(
+  loaderEntry: LoaderEntry,
+): typeof AWAIT_BEFORE_FLUSH | undefined {
+  return loaderEntry.awaitBeforeFlush === true ? AWAIT_BEFORE_FLUSH : undefined;
+}
+
+/**
+ * The loaders of a partial pass that run, as indices into `owner.loaders`:
+ * each one the client lacks, and each held one whose revalidate() rules ask
+ * for it (kept outright in a fill, fillSends). Every decision is traced and
+ * observed. `segmentIds` are the loaders' segment ids, by index.
+ */
+async function loadersToRerun<TEnv>(
+  pass: ResolutionPass<TEnv>,
+  owner: LoaderOwner,
+  belongsToRoute: boolean,
+  segmentIds: readonly string[],
+): Promise<number[]> {
+  const ctx = pass.context;
+  const checks = await Promise.all(
+    owner.loaders.map(async (loaderEntry, index) => {
+      const segmentId = segmentIds[index]!;
+      const shouldRun = await revalidate(
+        async () => {
+          if (!pass.client.has(segmentId)) {
+            if (isTraceActive()) {
+              pushRevalidationTraceEntry({
+                segmentId,
+                segmentType: "loader",
+                belongsToRoute,
+                source: owner.traceSource,
+                defaultShouldRevalidate: true,
+                finalShouldRevalidate: true,
+                reason: "new-segment",
+              });
+            }
+            return true;
+          }
+
+          const dummySegment: ResolvedSegment = {
+            id: segmentId,
+            namespace: owner.namespace,
+            type: "loader",
+            index,
+            component: null,
+            params: ctx.params,
+            loaderId: loaderEntry.loader.$$id,
+            // A clientUrls() layout() loader's copy is projected onto the
+            // route but owned by a layout: it takes a layout's default.
+            belongsToRoute:
+              belongsToRoute && !isLayoutLoaderCopy(loaderEntry.loader),
+          };
+
+          return await revalidateHeld(pass, {
+            segment: dummySegment,
+            revalidations: loaderEntry.revalidate.map((fn, j) => ({
+              name: `${owner.traceSource}-revalidate${j}`,
+              fn,
+            })),
+            traceSource: owner.traceSource,
+          });
+        },
+        async () => true,
+        () => false,
+      );
+      emitRevalidationDecision(
+        segmentId,
+        ctx.pathname,
+        pass.routeKey,
+        shouldRun,
+      );
+      return shouldRun;
+    }),
+  );
+  const indices: number[] = [];
+  for (let i = 0; i < checks.length; i++) if (checks[i]) indices.push(i);
+  return indices;
+}
+
+/**
+ * The walker's one loader funnel: each loader is a segment, run when the
+ * client lacks it, asked its revalidate() when held, kept outright in a fill
+ * (fillSends), deferred in a prefetch that defers it (defersLoader).
+ *
+ * Loaders run lazily via ctx.use() and are memoized, so they run in
+ * parallel. A FRESH pass kicks every loader off without an await, in the
+ * tick the call starts: a reader's ctx.use(Loader) finds the binding only if
+ * it registered first (docs/design/handle-push-ownership.md).
  */
 export async function resolveOwnerLoaders<TEnv>(
+  pass: ResolutionPass<TEnv>,
   owner: LoaderOwner,
-  ctx: HandlerContext<any, TEnv>,
   belongsToRoute: boolean,
-  clientSegmentIds: ReadonlySet<string>,
-  prevParams: Record<string, string>,
-  request: Request,
-  prevUrl: URL,
-  nextUrl: URL,
-  routeKey: string,
-  deps: SegmentResolutionDeps<TEnv>,
-  actionContext?: ActionContext,
-  stale?: boolean,
 ): Promise<{ segments: ResolvedSegment[]; matchedIds: string[] }> {
   const loaderEntries = owner.loaders;
   if (loaderEntries.length === 0) return { segments: [], matchedIds: [] };
 
+  const ctx = pass.context;
   const shortCode = owner.segmentPrefix;
-
-  // Pin `_currentSegmentId` to the OWNING entry before the kickoffs below —
-  // createLoaderExecutor captures it synchronously for ctx.use(Handle) push
-  // attribution. Same pin as resolveLoaders (fresh.ts); this REVALIDATION
-  // funnel is the navigation/action lane's kickoff site, where nothing else
-  // assigns the id first (pushes silently vanished: an id outside
-  // matched/segmentOrder is dropped by collectHandleData).
+  const fresh = pass.client === FRESH;
+
+  // Pin `_currentSegmentId` to the OWNING entry BEFORE the loader kickoffs:
+  // createLoaderExecutor captures it synchronously at kickoff for
+  // ctx.use(Handle) push attribution (loader writes land in the same bucket
+  // as the entry's handler pushes — shortCode is in matched/segmentOrder, so
+  // collectHandleData keeps them; an id outside the order is silently
+  // dropped). Loaders resolve BEFORE the handler-resolution sites assign
+  // this (handler-first ordering), so without the pin the captured value is
+  // a stale sibling's id (document lane) or undefined (navigation lane —
+  // pushes silently vanished).
   (ctx as InternalHandlerContext<any, TEnv>)._currentSegmentId = shortCode;
 
-  const loaderMeta = loaderEntries.map((loaderEntry, i) => ({
-    loaderEntry,
-    loader: loaderEntry.loader,
-    loaderRevalidateFns: loaderEntry.revalidate,
-    segmentId: `${shortCode}D${i}.${loaderEntry.loader.$$id}`,
-    index: i,
-  }));
-
-  const matchedIds = loaderMeta.map((m) => m.segmentId);
-
-  const revalidationChecks = await Promise.all(
-    loaderMeta.map(
-      async ({
-        loaderEntry,
-        loader,
-        loaderRevalidateFns,
-        segmentId,
-        index,
-      }) => {
-        const shouldRun = await revalidate(
-          async () => {
-            if (!clientSegmentIds.has(segmentId)) {
-              if (isTraceActive()) {
-                pushRevalidationTraceEntry({
-                  segmentId,
-                  segmentType: "loader",
-                  belongsToRoute,
-                  source: owner.traceSource,
-                  defaultShouldRevalidate: true,
-                  finalShouldRevalidate: true,
-                  reason: "new-segment",
-                });
-              }
-              return true;
-            }
-
-            const dummySegment: ResolvedSegment = {
-              id: segmentId,
-              namespace: owner.namespace,
-              type: "loader",
-              index,
-              component: null,
-              params: ctx.params,
-              loaderId: loader.$$id,
-              // A clientUrls() layout() loader's copy is projected onto the
-              // route but owned by a layout: it takes a layout's default.
-              belongsToRoute: belongsToRoute && !isLayoutLoaderCopy(loader),
-            };
-
-            return await revalidateHeld({
-              segment: dummySegment,
-              prevParams,
-              getPrevSegment: null,
-              request,
-              prevUrl,
-              nextUrl,
-              revalidations: loaderRevalidateFns.map((fn, j) => ({
-                name: `${owner.traceSource}-revalidate${j}`,
-                fn,
-              })),
-              routeKey,
-              context: ctx,
-              actionContext,
-              stale,
-              traceSource: owner.traceSource,
-              held: clientSegmentIds,
-            });
-          },
-          async () => true,
-          () => false,
-        );
-        emitRevalidationDecision(segmentId, ctx.pathname, routeKey, shouldRun);
-        return { shouldRun, loaderEntry, loader, segmentId, index };
-      },
-    ),
-  );
+  const matchedIds: string[] = [];
+  for (let i = 0; i < loaderEntries.length; i++) {
+    matchedIds.push(`${shortCode}D${i}.${loaderEntries[i]!.loader.$$id}`);
+  }
 
-  // Partial (revalidation) render path: a throwing DSL loader must still fire
-  // onError/loader.error. isPartial flags the reporting phase accordingly.
-  const errorContext = { ...buildLoaderErrorContext(ctx), isPartial: true };
-
-  // PPR bake/seed key, same as fresh.ts (lane rule: see resolveLoaderData,
-  // loader-cache.ts). The key must thread through EVERY resolveLoaderData
-  // funnel — omitting it here made a capture-active context
-  // whole-container-mask every loader on this path (a never-settling promise
-  // for a loader that should have executed).
-  // Outside capture the key only activates the _shellLoaderSeed overlay,
-  // which serveShellHit seeds for a document HIT and the PPR partial replay
-  // (matchPartialWithPprReplay) seeds once its doc record hits.
+  // PPR bake/seed key (lane rule: see resolveLoaderData, loader-cache.ts).
+  // The key must thread through EVERY resolveLoaderData funnel — omitting it
+  // made a capture-active context whole-container-mask every loader on the
+  // partial path (a never-settling promise for a loader that should have
+  // executed). Outside capture the key only activates the _shellLoaderSeed
+  // overlay, which serveShellHit seeds for a document HIT and the PPR
+  // partial replay (matchPartialWithPprReplay) seeds once its doc record hits.
   const bakeLane = owner.bakeLane;
 
   const kickoff = (
     loaderEntry: LoaderEntry,
     segmentId: string,
-    loaderId: string,
   ): Promise<unknown> =>
     runInsideLoaderScope(
       () =>
@@ -351,89 +448,164 @@ export async function resolveOwnerLoaders<TEnv>(
           loaderEntry,
           ctx,
           ctx.pathname,
-          // `bake`, not awaitBeforeFlush: a navigation evaluation never
-          // carries awaitBeforeFlush, and an ssr: false loader must pin
-          // here exactly as on the document HIT.
+          // The bake key rides for flagged loaders too (`bake`): ssr: false
+          // bakes at capture regardless of the entry's loading() lane
+          // (loader-cache.ts capture branch), its HIT-tail seed overlay needs
+          // the same key, and on a navigation it pins exactly as on the
+          // document HIT.
           bakeLane || loaderEntry.bake === true ? segmentId : null,
         ),
-      loaderId,
+      loaderEntry.loader.$$id,
       loaderEntry.reverseScope,
     );
-  const start = (
-    loaderEntry: LoaderEntry,
-    segmentId: string,
-    loaderId: string,
-  ) =>
-    deps.wrapLoaderPromise(
-      kickoff(loaderEntry, segmentId, loaderId),
+
+  // skipLoaders: no loader runs and none is emitted. Each is registered
+  // instead, so a reader starts it as a MISS starts it, in its DSL scope
+  // under this owner: a route record leaves its pushes out (captureHandles)
+  // and a HIT's live run shows them once. The pin above holds as on a MISS:
+  // an orphan layout's handler pushes under the orphan.
+  if (pass.skipLoaders) {
+    for (let i = 0; i < loaderEntries.length; i++) {
+      const loaderEntry = loaderEntries[i]!;
+      registerDeferredLoader(ctx, loaderEntry.loader.$$id, shortCode, () =>
+        kickoff(loaderEntry, matchedIds[i]!),
+      );
+    }
+    return { segments: [], matchedIds: [] };
+  }
+
+  // FRESH: every loader is new; no decision is asked, traced or observed.
+  const toRun = fresh
+    ? undefined
+    : await loadersToRerun(pass, owner, belongsToRoute, matchedIds);
+
+  // Error context for wrapLoaderPromise: without it, a throwing DSL loader never
+  // fires createRouter({ onError }) (phase "loader") nor emits the loader.error
+  // telemetry event. A partial pass reports with isPartial.
+  const errorContext = fresh
+    ? buildLoaderErrorContext(ctx)
+    : { ...buildLoaderErrorContext(ctx), isPartial: true };
+
+  // FRESH: awaitBeforeFlush (loader(Def, { ssr: false })). A document render
+  // awaits these loaders before returning, so their data is settled, their
+  // handle pushes beat the barrier snapshot, and a thrown notFound()'s status
+  // write deterministically precedes Response construction. The ids must
+  // register on the request context BEFORE kickoff — rendered() checks the
+  // set to fail fast on the barrier cycle (segment resolution awaits the
+  // loader, the barrier awaits segment resolution, rendered() awaits the
+  // barrier), and the loader body can call rendered() before the await below
+  // is reached. Shell-capture renders await too: flagged loaders execute at
+  // capture (lane rule: see resolveLoaderData, loader-cache.ts), so their
+  // handle pushes must land in the prelude. A navigation evaluation never
+  // carries awaitBeforeFlush.
+  const awaitedIndices = fresh
+    ? registerAwaitBeforeFlushIds(loaderEntries)
+    : [];
+
+  // The wrapped promise is contracted to never reject (wrapLoaderPromise): a
+  // failed loader resolves with its error envelope and renders its own
+  // per-loader boundary.
+  const start = (loaderEntry: LoaderEntry, segmentId: string) =>
+    pass.deps.wrapLoaderPromise(
+      kickoff(loaderEntry, segmentId),
       owner.boundary,
       segmentId,
       ctx.pathname,
       errorContext,
+      // FRESH: a flagged loader's failure falls back to the default boundary.
+      fresh ? loaderEntry.awaitBeforeFlush : undefined,
     );
 
-  const loadersToRun = revalidationChecks.filter((c) => c.shouldRun);
-  const segments: ResolvedSegment[] = loadersToRun.map(
-    ({ loaderEntry, loader, segmentId, index }) => {
-      const base = {
+  const segments: ResolvedSegment[] = [];
+  const count = toRun === undefined ? loaderEntries.length : toRun.length;
+  for (let k = 0; k < count; k++) {
+    const index = toRun === undefined ? k : toRun[k]!;
+    const loaderEntry = loaderEntries[index]!;
+    const segmentId = matchedIds[index]!;
+    const { loader } = loaderEntry;
+    // Only a loader on a segment the client lacks (defersLoader). It
+    // would have run. Registered, not started: it runs, and reads its
+    // cache(), only if a reader starts it (startDeferredLoader).
+    if (defersLoader(ctx, loaderEntry, segmentId)) {
+      registerDeferredLoader(ctx, loader.$$id, shortCode, () =>
+        kickoff(loaderEntry, segmentId),
+      );
+      const deferred: ResolvedSegment = {
         id: segmentId,
         namespace: owner.namespace,
-        type: "loader" as const,
+        type: "loader",
         index,
         component: null,
         params: ctx.params,
         loaderId: loader.$$id,
-      };
-      // Only a loader on a segment the client lacks (defersLoader). It
-      // would have run. Registered, not started: it runs, and reads its
-      // cache(), only if a reader starts it (startDeferredLoader).
-      if (defersLoader(ctx, loaderEntry, segmentId)) {
-        registerDeferredLoader(ctx, loader.$$id, shortCode, () =>
-          kickoff(loaderEntry, segmentId, loader.$$id),
-        );
-        const deferred: ResolvedSegment = {
-          ...base,
-          belongsToRoute,
-          deferred: true,
-        };
-        deferredLoaderRuns.set(deferred, () =>
-          start(loaderEntry, segmentId, loader.$$id),
-        );
-        return deferred;
-      }
-      return {
-        ...base,
-        loaderData: start(loaderEntry, segmentId, loader.$$id),
         belongsToRoute,
+        deferred: true,
       };
-    },
-  );
+      deferredLoaderRuns.set(deferred, () => start(loaderEntry, segmentId));
+      segments.push(deferred);
+      continue;
+    }
+    segments.push({
+      id: segmentId,
+      namespace: owner.namespace,
+      type: "loader",
+      index,
+      component: null,
+      params: ctx.params,
+      loaderId: loader.$$id,
+      // FRESH, document AND capture renders: segment-system's value-delivery
+      // await and the dev SSR-suspension diagnostic both key off it.
+      ...(fresh ? stampAwaitBeforeFlush(loaderEntry) : undefined),
+      loaderData: start(loaderEntry, segmentId),
+      belongsToRoute,
+    });
+  }
+
+  if (fresh) {
+    // loading(false): every loader settles before the handler runs, so the
+    // handler streams no loading placeholder. A PPR shell capture keeps the
+    // streaming shape: it masks LIVE-lane loaders with never-resolving
+    // promises (loader-mask.ts), and awaiting them would hang the capture
+    // render's match() forever. The `loadingDisabled` short-circuit keeps the
+    // ALS check off the hot path. Otherwise only the flagged loaders are
+    // awaited; unflagged siblings keep streaming.
+    const settled =
+      owner.loadingDisabled && !isShellCaptureActive()
+        ? segments
+        : awaitedIndices.length > 0
+          ? awaitedIndices.map((i) => segments[i]!)
+          : undefined;
+    if (settled !== undefined && settled.length > 0) {
+      await Promise.all(settled.map((s) => s.loaderData));
+    }
+  }
 
   return { segments, matchedIds };
 }
 
 /**
- * Resolve only loader segments for all entries with revalidation logic.
+ * Resolve only loader segments for all entries: a cache() or prerender HIT
+ * serves the cached non-loader segments, and loaders are never cached. Under
+ * an intercept the route's entry, and on an intercept's fill an entry the
+ * client lacks, are skipped as resolveAllSegments skips them, after the ppr
+ * header latch below has read the chain's leaf.
  */
-export async function resolveLoadersOnlyWithRevalidation<TEnv>(
+export async function resolveLoadersOnly<TEnv>(
+  pass: ResolutionPass<TEnv>,
   entries: EntryData[],
-  context: HandlerContext<any, TEnv>,
-  clientSegmentIds: Set<string>,
-  prevParams: Record<string, string>,
-  request: Request,
-  prevUrl: URL,
-  nextUrl: URL,
-  routeKey: string,
-  deps: SegmentResolutionDeps<TEnv>,
-  actionContext?: ActionContext,
-  stale?: boolean,
+  walk?: Pick<RevalidatingWalkOptions, "interceptResult">,
 ): Promise<{ segments: ResolvedSegment[]; matchedIds: string[] }> {
   const allLoaderSegments: ResolvedSegment[] = [];
   const allMatchedIds: string[] = [];
   const seenIds = new Set<string>();
 
-  // ppr header-write guard latch — see resolveAllSegments (fresh.ts).
-  latchPprHeaderScopeForEntries(entries, routeKey);
+  // Loader-only serves still run loaders live — on a ppr route their header
+  // writes are dead letters (headers flushed with the shell), so the guard
+  // latches here too (see resolveAllSegments). cache() needs
+  // no latch: loader writes are exempt under cache()
+  // (assertCachedHeaderWriteAllowed).
+  latchPprHeaderScopeForEntries(entries, pass.routeKey);
+  const handleStore = _getRequestContext()?._handleStore;
 
   async function collectEntryLoaders(
     entry: EntryData,
@@ -449,20 +621,11 @@ export async function resolveLoadersOnlyWithRevalidation<TEnv>(
       loaderEntries.every((le, i) =>
         seenIds.has(`${sc}D${i}.${le.loader.$$id}`),
       );
-    if (!allAlreadySeen) {
+    if (!allAlreadySeen && ownsLoaders(entry)) {
       const { segments, matchedIds } = await resolveOwnerLoaders(
+        pass,
         ownerOf(entry, shortCodeOverride),
-        context,
         belongsToRoute,
-        clientSegmentIds,
-        prevParams,
-        request,
-        prevUrl,
-        nextUrl,
-        routeKey,
-        deps,
-        actionContext,
-        stale,
       );
       for (const seg of segments) {
         if (!seenIds.has(seg.id)) {
@@ -472,6 +635,9 @@ export async function resolveLoadersOnlyWithRevalidation<TEnv>(
       }
       allMatchedIds.push(...matchedIds);
     }
+    // Where the MISS runs this entry's handler: before its slots' loaders,
+    // which push into its segment too (a slot's own call releases nothing).
+    handleStore?.releaseRecordedValues(sc);
 
     const seenParallelEntryIds = new Set<string>();
     for (const parallelEntry of getParallelEntries(entry.parallel)) {
@@ -493,18 +659,9 @@ export async function resolveLoadersOnlyWithRevalidation<TEnv>(
         Object.keys(layoutEntry.parallel).length > 0
       ) {
         const inherited = await resolveOwnerLoaders(
+          pass,
           ownerOf(entry, layoutEntry.shortCode),
-          context,
           childBelongsToRoute,
-          clientSegmentIds,
-          prevParams,
-          request,
-          prevUrl,
-          nextUrl,
-          routeKey,
-          deps,
-          actionContext,
-          stale,
         );
         for (const seg of inherited.segments) {
           if (!seenIds.has(seg.id)) {
@@ -518,11 +675,18 @@ export async function resolveLoadersOnlyWithRevalidation<TEnv>(
     }
   }
 
+  const fillMatch = {
+    handlerContext: pass.context,
+    isIntercept: !!walk?.interceptResult,
+    clientSegmentSet: pass.client,
+  };
   for (const entry of entries) {
+    if (entry.type === "route" && walk?.interceptResult) continue;
+    if (interceptFillSkips(fillMatch, entry.shortCode)) continue;
     await collectEntryLoaders(entry, entry.type === "route");
   }
 
-  deliverStartedLoaders(context, allLoaderSegments);
+  deliverStartedLoaders(pass.context, allLoaderSegments);
   return { segments: allLoaderSegments, matchedIds: allMatchedIds };
 }
 
@@ -540,16 +704,15 @@ export function buildEntryRevalidateMap(
     { entry: EntryData; revalidate: ShouldRevalidateFn<any, any>[] }
   >();
 
-  function processEntry(entry: EntryData, parentShortCode?: string) {
+  function processEntry(entry: EntryData) {
     map.set(entry.shortCode, { entry, revalidate: entry.revalidate });
 
     if (entry.type !== "parallel") {
+      // The walker's slot id (resolveParallelSegments), an orphan's included.
       for (const { slot, entry: parallelEntry } of getParallelSlotEntries(
         entry.parallel,
       )) {
-        const parallelParentShortCode = parentShortCode ?? entry.shortCode;
-        const parallelId = `${parallelParentShortCode}.${slot}`;
-        map.set(parallelId, {
+        map.set(`${entry.shortCode}.${slot}`, {
           entry: parallelEntry,
           revalidate: parallelEntry.revalidate,
         });
@@ -557,7 +720,7 @@ export function buildEntryRevalidateMap(
     }
 
     for (const layoutEntry of entry.layout) {
-      processEntry(layoutEntry, entry.shortCode);
+      processEntry(layoutEntry);
     }
   }
 
@@ -569,44 +732,43 @@ export function buildEntryRevalidateMap(
 }
 
 /**
- * Resolve the component for a single parallel slot on the revalidation path.
- * Pure component resolution shared verbatim by
- * resolveParallelSegmentsWithRevalidation and the orphan-inlined loop in
- * resolveOrphanLayoutWithRevalidation: try the static slot cache, else run the
- * slot handler (pinning _currentSegmentId to the slot id so handle pushes land
- * in the slot's own bucket, and wrapping a streamed handler). Returns the
- * resolved component and whether the handler actually ran. Does NOT touch the
- * revalidate-default policy (the caller decides shouldResolve, including the
- * orphan-vs-main defaultOverride divergence) or loader-resolution ordering.
+ * Resolve the component for a single parallel slot. Pure component resolution
+ * shared by the main path and the orphan path of
+ * resolveParallelSegments: try the static slot cache, else run
+ * the slot handler (pinning _currentSegmentId to the slot id so handle pushes
+ * land in the slot's own bucket, and wrapping a streamed handler). Returns the
+ * resolved component and whether the handler actually ran, or undefined when
+ * there is nothing to render: the handler was evicted (production static
+ * slot) and the static lookup missed. Does NOT touch the revalidate-default
+ * policy (the caller decides shouldResolve, including the orphan-vs-main
+ * defaultOverride divergence) or loader-resolution ordering.
  */
-async function resolveParallelSlotComponent<TEnv>(args: {
-  shouldResolve: boolean;
-  parallelEntry: ParallelEntryData;
-  slot: string;
-  parallelId: string;
-  handler:
-    | ((ctx: HandlerContext<any, TEnv>) => ReactNode | Promise<ReactNode>)
-    | ReactNode
-    | undefined;
-  context: HandlerContext<any, TEnv>;
-  deps: SegmentResolutionDeps<TEnv>;
-  routeKey: string;
-  params: Record<string, string>;
-  /** Matched chain entry (where the sync path catches), else the slot's owner. */
-  boundaryEntry: EntryData;
-}): Promise<{ component: ReactNode | undefined; handlerRan: boolean }> {
+async function resolveParallelSlotComponent<TEnv>(
+  pass: ResolutionPass<TEnv>,
+  args: {
+    shouldResolve: boolean;
+    parallelEntry: ParallelEntryData;
+    slot: string;
+    parallelId: string;
+    handler:
+      | ((ctx: HandlerContext<any, TEnv>) => ReactNode | Promise<ReactNode>)
+      | ReactNode
+      | undefined;
+    /** Matched chain entry (where the sync path catches), else the slot's owner. */
+    boundaryEntry: EntryData;
+  },
+): Promise<
+  { component: ReactNode | undefined; handlerRan: boolean } | undefined
+> {
   const {
     shouldResolve,
     parallelEntry,
     slot,
     parallelId,
     handler,
-    context,
-    deps,
-    routeKey,
-    params,
     boundaryEntry,
   } = args;
+  const { context, deps, routeKey, params } = pass;
 
   let component: ReactNode | undefined;
   let handlerRan = false;
@@ -621,9 +783,7 @@ async function resolveParallelSlotComponent<TEnv>(args: {
     if (!shouldResolve) {
       component = null;
     } else if (handler === undefined) {
-      // Handler evicted (production static slot) but static lookup missed.
-      // Nothing to render — use null so the client keeps its cached version.
-      component = null;
+      return undefined;
     } else {
       // Slot-keyed pushes — slot owns its own bucket, parent layout owns its
       // own. On slot-only revalidations the partial merge updates only the
@@ -632,30 +792,44 @@ async function resolveParallelSlotComponent<TEnv>(args: {
         parallelId;
       handlerRan = true;
       const slotContext = withReverseScope(context, parallelEntry.reverseScope);
-      if (hasLoadingFallback) {
-        const result =
-          typeof handler === "function"
-            ? runInSegmentTagScope(parallelId, handler, slotContext)
-            : handler;
-        if (result instanceof Promise) {
-          warnOnStreamedResponse(result, parallelId);
-          component = trackStreamedHandler(deps, result, {
-            boundaryEntry,
-            segmentId: parallelId,
-            segmentType: "parallel",
-            context,
-            routeKey,
-            params,
-            recover: true,
-          });
+      const doneHandler = track(`handler:${parallelEntry.id}.${slot}`, 2);
+      const run = () =>
+        typeof handler !== "function"
+          ? handler
+          : observeSegmentHandler(
+              parallelId,
+              `${parallelEntry.id}.${slot}`,
+              handler,
+              slotContext,
+            );
+      // A throw before the slot streams reaches the owning entry's boundary.
+      try {
+        if (hasLoadingFallback) {
+          const result = run();
+          if (result instanceof Promise) {
+            warnOnStreamedResponse(result, parallelId);
+            result.finally(doneHandler).catch(() => {});
+            component = trackStreamedHandler(deps, result, {
+              boundaryEntry,
+              segmentId: parallelId,
+              segmentType: "parallel",
+              context,
+              routeKey,
+              params,
+              isPartial: reportsPartial(pass),
+              recover: !pass.throwOnError,
+            });
+          } else {
+            doneHandler();
+            component = result as ReactNode;
+          }
         } else {
-          component = result as ReactNode;
+          // A static value (a Promise included) goes to render as is.
+          component = typeof handler === "function" ? await run() : handler;
+          doneHandler();
         }
-      } else {
-        component =
-          typeof handler === "function"
-            ? await runInSegmentTagScope(parallelId, handler, slotContext)
-            : handler;
+      } catch (error) {
+        throw noteThrower(error, parallelId, "parallel");
       }
     }
   }
@@ -664,22 +838,12 @@ async function resolveParallelSlotComponent<TEnv>(args: {
 }
 
 /**
- * Resolve parallel segments with revalidation.
+ * Resolve an entry's parallel slots: each slot's segment and its loaders.
  */
-export async function resolveParallelSegmentsWithRevalidation<TEnv>(
+export async function resolveParallelSegments<TEnv>(
+  pass: ResolutionPass<TEnv>,
   entry: EntryData,
-  params: Record<string, string>,
-  context: HandlerContext<any, TEnv>,
   belongsToRoute: boolean,
-  clientSegmentIds: Set<string>,
-  prevParams: Record<string, string>,
-  request: Request,
-  prevUrl: URL,
-  nextUrl: URL,
-  routeKey: string,
-  deps: SegmentResolutionDeps<TEnv>,
-  actionContext?: ActionContext,
-  stale?: boolean,
   options?: {
     /**
      * Seed for an unknown parent-chain slot (slot not in clientSegmentIds) when
@@ -698,10 +862,16 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
      * to it: loader sub-ids are filtered out and slots are re-grouped by parent).
      */
     loaderOrder?: "after" | "before";
-    /** Matched chain entry being resolved; see ResolveSegmentOptions.boundaryEntry. */
+    /**
+     * The matched chain entry being resolved: where the sync path catches a
+     * handler error, so a streamed slot handler (or a slot owned by a
+     * routeless layout) recovers into the same boundary. Defaults to `entry`.
+     */
     boundaryEntry?: EntryData;
   },
 ): Promise<SegmentRevalidationResult> {
+  const { context, client: clientSegmentIds, params, routeKey } = pass;
+  const fresh = clientSegmentIds === FRESH;
   const segments: ResolvedSegment[] = [];
   const matchedIds: string[] = [];
   const parentChainDefault = options?.parentChainDefault ?? "type-derived";
@@ -733,28 +903,31 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
 
     // A slot's loaders (never cached) are deduped per parallel entry and
     // emitted either before or after the slot segment per loaderOrder.
-    const resolveSlotLoaders = async () => {
-      if (resolvedParallelEntries.has(parallelEntry.id)) return;
-      const loaderResult = await resolveOwnerLoaders(
-        ownerOf(parallelEntry, entry.shortCode),
-        context,
-        belongsToRoute,
-        clientSegmentIds,
-        prevParams,
-        request,
-        prevUrl,
-        nextUrl,
-        routeKey,
-        deps,
-        actionContext,
-        stale,
-      );
-      segments.push(...loaderResult.segments);
-      matchedIds.push(...loaderResult.matchedIds);
-      resolvedParallelEntries.add(parallelEntry.id);
-    };
+    const resolveSlotLoaders =
+      resolvedParallelEntries.has(parallelEntry.id) ||
+      !ownsLoaders(parallelEntry)
+        ? undefined
+        : async () => {
+            const loaderResult = await resolveOwnerLoaders(
+              pass,
+              ownerOf(parallelEntry, entry.shortCode),
+              belongsToRoute,
+            );
+            // FRESH tags a slot's loaders with the slot's loading(), so
+            // renderSegments streams them under it instead of awaiting them
+            // on the layout. A partial pass's are tagged on render
+            // (restoreParallelLoaderMarkers, segment-system.tsx).
+            if (fresh && parallelEntry.loading) {
+              for (const seg of loaderResult.segments) {
+                seg.parallelLoading = parallelEntry.loading;
+              }
+            }
+            segments.push(...loaderResult.segments);
+            matchedIds.push(...loaderResult.matchedIds);
+            resolvedParallelEntries.add(parallelEntry.id);
+          };
 
-    if (loaderOrder === "before") {
+    if (resolveSlotLoaders && loaderOrder === "before") {
       await resolveSlotLoaders();
     }
     // Always announce the slot in matchedIds — it's unconditionally appended
@@ -771,7 +944,10 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
     // below (fillSends).
     const fill = fillSends(context, parallelId, clientSegmentIds);
     let shouldResolve: boolean;
-    if (fill !== undefined) {
+    if (fresh) {
+      // FRESH: the slot is new; no trace entry, no decision event.
+      shouldResolve = true;
+    } else if (fill !== undefined) {
       shouldResolve = fill;
     } else if (deferred) {
       shouldResolve = true;
@@ -824,47 +1000,51 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
       };
 
       shouldResolve = await evaluateRevalidation({
+        ...revalidationInputOf(pass),
         segment: dummySegment,
-        prevParams,
-        getPrevSegment: null,
-        request,
-        prevUrl,
-        nextUrl,
         revalidations: parallelEntry.revalidate.map((fn, i) => ({
           name: `revalidate${i}`,
           fn,
         })),
-        routeKey,
-        context,
-        actionContext,
-        stale,
         traceSource: "parallel",
         defaultOverride,
       });
     }
-    emitRevalidationDecision(
-      parallelId,
-      context.pathname,
-      routeKey,
-      shouldResolve,
-    );
+    if (!fresh) {
+      emitRevalidationDecision(
+        parallelId,
+        context.pathname,
+        routeKey,
+        shouldResolve,
+      );
+    }
 
     // A slot with its own flagged loading() is its own unit.
     if (shouldResolve) deferred ??= deferUnit(context, parallelId, "slot");
-    const { component, handlerRan } = deferred
+    const resolved = deferred
       ? { component: null, handlerRan: false }
-      : await resolveParallelSlotComponent({
+      : await resolveParallelSlotComponent(pass, {
           shouldResolve,
           parallelEntry,
           slot,
           parallelId,
           handler,
-          context,
-          deps,
-          routeKey,
-          params,
           boundaryEntry: options?.boundaryEntry ?? entry,
         });
+    if (resolved === undefined && fresh) {
+      // FRESH: an evicted slot handler whose static lookup missed renders no
+      // slot segment; its loaders still resolve.
+      if (resolveSlotLoaders && loaderOrder === "after") {
+        await resolveSlotLoaders();
+      }
+      continue;
+    }
+    // Nothing to render on a partial pass: null, so the client keeps its
+    // cached version.
+    const { component, handlerRan } = resolved ?? {
+      component: null,
+      handlerRan: false,
+    };
 
     segments.push({
       id: parallelId,
@@ -875,7 +1055,7 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
       loading: parallelEntry.loading === false ? null : parallelEntry.loading,
       transition: applyViewTransitionDefault(
         parallelEntry.transition,
-        deps.viewTransitionDefault,
+        pass.deps.viewTransitionDefault,
       ),
       params,
       slot,
@@ -888,7 +1068,7 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
       ...deferred,
     });
 
-    if (loaderOrder === "after") {
+    if (resolveSlotLoaders && loaderOrder === "after") {
       await resolveSlotLoaders();
     }
   }
@@ -897,190 +1077,180 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
 }
 
 /**
- * Resolve entry handler (layout, cache, or route) with revalidation.
+ * Whether a partial pass re-renders a chain entry: one the client lacks, or a
+ * held one whose revalidate() rules ask for it (revalidateHeld).
  */
-export async function resolveEntryHandlerWithRevalidation<TEnv>(
+async function entryRevalidates<TEnv>(
+  pass: ResolutionPass<TEnv>,
   entry: Exclude<EntryData, { type: "parallel" }>,
-  params: Record<string, string>,
-  context: HandlerContext<any, TEnv>,
   belongsToRoute: boolean,
-  clientSegmentIds: Set<string>,
-  prevParams: Record<string, string>,
-  request: Request,
-  prevUrl: URL,
-  nextUrl: URL,
-  routeKey: string,
-  deps: SegmentResolutionDeps<TEnv>,
-  actionContext?: ActionContext,
-  stale?: boolean,
-): Promise<{ segment: ResolvedSegment; matchedId: string }> {
-  const matchedId = entry.shortCode;
-
-  let handlerRan = false;
-  let deferred: { readonly deferred: true } | undefined;
-  const component = await revalidate(
-    async () => {
-      const hasSegment = clientSegmentIds.has(entry.shortCode);
-      debugLog("segment.revalidate", "entry presence check", {
+): Promise<boolean> {
+  const { context, params, routeKey } = pass;
+  const hasSegment = pass.client.has(entry.shortCode);
+  debugLog("segment.revalidate", "entry presence check", {
+    segmentId: entry.shortCode,
+    entryType: entry.type,
+    clientHasSegment: hasSegment,
+    belongsToRoute,
+  });
+  if (!hasSegment) {
+    if (isTraceActive()) {
+      const segType =
+        entry.type === "cache" ? "layout" : (entry.type as "layout" | "route");
+      pushRevalidationTraceEntry({
         segmentId: entry.shortCode,
-        entryType: entry.type,
-        clientHasSegment: hasSegment,
+        segmentType: segType,
         belongsToRoute,
+        source: "segment-resolution",
+        defaultShouldRevalidate: true,
+        finalShouldRevalidate: true,
+        reason: "new-segment",
       });
-      if (!hasSegment) {
-        if (isTraceActive()) {
-          const segType =
-            entry.type === "cache"
-              ? "layout"
-              : (entry.type as "layout" | "route");
-          pushRevalidationTraceEntry({
-            segmentId: entry.shortCode,
-            segmentType: segType,
-            belongsToRoute,
-            source: "segment-resolution",
-            defaultShouldRevalidate: true,
-            finalShouldRevalidate: true,
-            reason: "new-segment",
-          });
-        }
-        return true;
-      }
+    }
+    return true;
+  }
 
-      const dummySegment: ResolvedSegment = {
-        id: entry.shortCode,
-        namespace: entry.id,
-        type:
-          entry.type === "cache"
-            ? "layout"
-            : (entry.type as "layout" | "route"),
-        index: 0,
-        component: null as any,
-        params,
-        belongsToRoute,
-        ...(entry.type === "layout" || entry.type === "cache"
-          ? { layoutName: entry.id }
-          : {}),
-        ...(entry.mountPath ? { mountPath: entry.mountPath } : {}),
-      };
+  const dummySegment: ResolvedSegment = {
+    id: entry.shortCode,
+    namespace: entry.id,
+    type:
+      entry.type === "cache" ? "layout" : (entry.type as "layout" | "route"),
+    index: 0,
+    component: null as any,
+    params,
+    belongsToRoute,
+    ...(entry.type === "layout" || entry.type === "cache"
+      ? { layoutName: entry.id }
+      : {}),
+    ...(entry.mountPath ? { mountPath: entry.mountPath } : {}),
+  };
 
-      return revalidateHeld({
-        segment: dummySegment,
-        prevParams,
-        getPrevSegment: null,
-        request,
-        prevUrl,
-        nextUrl,
-        revalidations: entry.revalidate.map((fn, i) => ({
-          name: `revalidate${i}`,
-          fn,
-        })),
+  return revalidateHeld(pass, {
+    segment: dummySegment,
+    revalidations: entry.revalidate.map((fn, i) => ({
+      name: `revalidate${i}`,
+      fn,
+    })),
+    traceSource: entry.type === "route" ? "route-handler" : "layout-handler",
+    onEvaluated: (shouldRevalidate) => {
+      emitRevalidationDecision(
+        entry.shortCode,
+        context.pathname,
         routeKey,
-        context,
-        actionContext,
-        stale,
-        traceSource:
-          entry.type === "route" ? "route-handler" : "layout-handler",
-        held: clientSegmentIds,
-        onEvaluated: (shouldRevalidate) => {
-          emitRevalidationDecision(
-            entry.shortCode,
-            context.pathname,
-            routeKey,
-            shouldRevalidate,
-          );
-          debugLog("segment.revalidate", "entry revalidation decision", {
-            segmentId: entry.shortCode,
-            shouldRevalidate,
-          });
-        },
+        shouldRevalidate,
+      );
+      debugLog("segment.revalidate", "entry revalidation decision", {
+        segmentId: entry.shortCode,
+        shouldRevalidate,
       });
     },
-    async () => {
-      // Only an entry the client lacks (defersUnit). Its handler would
-      // have run, and a prefetch sends the entry's fallback in its place.
-      deferred = deferUnit(context, entry.shortCode, "chain");
-      if (deferred) return null;
+  });
+}
+
+/**
+ * Run a route entry's handler: a static store hit, else the handler, streamed
+ * under the route's loading() unless an action awaits it.
+ */
+async function resolveRouteComponent<TEnv>(
+  pass: ResolutionPass<TEnv>,
+  entry: Extract<EntryData, { type: "route" }>,
+): Promise<ReactNode | { content: ReactNode }> {
+  const { context, params, routeKey, actionContext } = pass;
+  // A static hit runs no handler: no handler metric, no span.
+  const staticComponent = await tryStaticHandler(entry, entry.shortCode);
+  if (staticComponent !== undefined) return staticComponent;
+  const doneHandler = track(`handler:${entry.id}`, 2);
+  // For Passthrough routes at runtime, use the live handler instead of
+  // the build handler. At build time (context.build === true), always
+  // use the build handler from entry.handler.
+  const handler =
+    !context.build && entry.liveHandler ? entry.liveHandler : entry.handler;
+  if (!entry.loading) {
+    const result = handleHandlerResult(
+      await observeSegmentHandler(entry.shortCode, entry.id, handler, context),
+    );
+    doneHandler();
+    return result;
+  }
+  if (!actionContext) {
+    const result = handleHandlerResult(
+      observeSegmentHandler(entry.shortCode, entry.id, handler, context),
+    );
+    if (result instanceof Promise) {
+      warnOnStreamedResponse(result, entry.id);
+      result.finally(doneHandler).catch(() => {});
+      return {
+        content: trackStreamedHandler(pass.deps, result, {
+          boundaryEntry: entry,
+          segmentId: entry.shortCode,
+          segmentType: entry.type,
+          context,
+          routeKey,
+          params,
+          isPartial: reportsPartial(pass),
+          recover: !pass.throwOnError,
+        }),
+      };
+    }
+    doneHandler();
+    return { content: result };
+  }
+  debugLog("segment.action", "resolving action route with awaited value", {
+    entryId: entry.id,
+  });
+  const actionResult = handleHandlerResult(
+    await observeSegmentHandler(entry.shortCode, entry.id, handler, context),
+  );
+  doneHandler();
+  return {
+    content: Promise.resolve(actionResult),
+  };
+}
+
+/**
+ * Resolve a chain entry's handler (layout, cache, or route) into its segment.
+ */
+export async function resolveEntryHandler<TEnv>(
+  pass: ResolutionPass<TEnv>,
+  entry: Exclude<EntryData, { type: "parallel" }>,
+  belongsToRoute: boolean,
+): Promise<{ segment: ResolvedSegment; matchedId: string }> {
+  const { context, params } = pass;
+  const fresh = pass.client === FRESH;
+  const matchedId = entry.shortCode;
+
+  let handlerRan = false;
+  let deferred: { readonly deferred: true } | undefined;
+  let component: ReactNode | { content: ReactNode } = null;
+  // FRESH: the entry is new; no decision is asked, traced or observed.
+  if (fresh || (await entryRevalidates(pass, entry, belongsToRoute))) {
+    // Only an entry the client lacks (defersUnit). Its handler would
+    // have run, and a prefetch sends the entry's fallback in its place.
+    deferred = deferUnit(context, entry.shortCode, "chain");
+    if (!deferred) {
       handlerRan = true;
-      const doneHandler = track(`handler:${entry.id}`, 2);
       (context as InternalHandlerContext<any, TEnv>)._currentSegmentId =
         entry.shortCode;
-      if (entry.type === "layout" || entry.type === "cache") {
-        const layoutComponent = await resolveLayoutComponent(entry, context);
-        doneHandler();
-        return layoutComponent;
-      }
-      const staticComponent = await tryStaticHandler(entry, entry.shortCode);
-      if (staticComponent !== undefined) {
-        doneHandler();
-        return staticComponent;
-      }
-      const routeEntry = entry as Extract<EntryData, { type: "route" }>;
-      // For Passthrough routes at runtime, use the live handler instead of
-      // the build handler. At build time (context.build === true), always
-      // use the build handler from routeEntry.handler.
-      const handler =
-        !context.build && routeEntry.liveHandler
-          ? routeEntry.liveHandler
-          : routeEntry.handler;
-      if (!routeEntry.loading) {
-        const result = handleHandlerResult(
-          await observeSegmentHandler(
-            entry.shortCode,
-            entry.id,
-            handler,
-            context,
-          ),
-        );
-        doneHandler();
-        return result;
-      }
-      if (!actionContext) {
-        const result = handleHandlerResult(
-          observeSegmentHandler(entry.shortCode, entry.id, handler, context),
-        );
-        if (result instanceof Promise) {
-          warnOnStreamedResponse(result, routeEntry.id);
-          result.finally(doneHandler).catch(() => {});
-          return {
-            content: trackStreamedHandler(deps, result, {
-              boundaryEntry: entry,
-              segmentId: entry.shortCode,
-              segmentType: entry.type,
-              context,
-              routeKey,
-              params,
-              recover: true,
-            }),
-          };
-        }
+      if (entry.type === "route") {
+        component = await resolveRouteComponent(pass, entry);
+      } else {
+        const doneHandler = track(`handler:${entry.id}`, 2);
+        component = await resolveLayoutComponent(entry, context);
         doneHandler();
-        return { content: result };
       }
-      debugLog("segment.action", "resolving action route with awaited value", {
-        entryId: entry.id,
-      });
-      const actionResult = handleHandlerResult(
-        await observeSegmentHandler(
-          entry.shortCode,
-          entry.id,
-          handler,
-          context,
-        ),
-      );
-      doneHandler();
-      return {
-        content: Promise.resolve(actionResult),
-      };
-    },
-    () => null,
-  );
+    }
+  }
 
   // Normalize void handlers (undefined) to null so the reconciler's
-  // component === null checks work consistently for both void and explicit null.
+  // component === null checks work consistently for both void and explicit
+  // null. FRESH keeps a void layout's undefined: cache-scope.ts refuses a
+  // document record whose layout component is null.
   const resolvedComponent =
     component && typeof component === "object" && "content" in component
       ? ((component as { content: ReactNode }).content ?? null)
-      : (component ?? null);
+      : fresh && entry.type !== "route"
+        ? (component as ReactNode)
+        : (component ?? null);
 
   const segment: ResolvedSegment = {
     id: entry.shortCode,
@@ -1092,39 +1262,32 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
     loading: entry.loading === false ? null : entry.loading,
     transition: applyViewTransitionDefault(
       entry.transition,
-      deps.viewTransitionDefault,
+      pass.deps.viewTransitionDefault,
     ),
     params,
     belongsToRoute,
-    ...(entry.clientGroup ? { clientGroup: entry.clientGroup } : {}),
-    ...(entry.type === "layout" || entry.type === "cache"
-      ? { layoutName: entry.id }
-      : {}),
-    ...(entry.mountPath ? { mountPath: entry.mountPath } : {}),
-    _handlerRan: handlerRan,
-    ...deferred,
   };
+  // Assigned, not spread: a conditional spread costs a temporary object and a
+  // property copy on every chain entry. The keys keep this order.
+  if (entry.clientGroup) segment.clientGroup = entry.clientGroup;
+  if (entry.type === "layout" || entry.type === "cache") {
+    segment.layoutName = entry.id;
+  }
+  if (entry.mountPath) segment.mountPath = entry.mountPath;
+  segment._handlerRan = handlerRan;
+  if (deferred) segment.deferred = deferred.deferred;
 
   return { segment, matchedId };
 }
 
 /**
- * Resolve segments with revalidation awareness (for partial rendering).
+ * Resolve one chain entry's segments: its loaders, its handler, its orphan
+ * layouts and its parallels, handler first.
  */
-export async function resolveSegmentWithRevalidation<TEnv>(
+export async function resolveSegment<TEnv>(
+  pass: ResolutionPass<TEnv>,
   entry: Exclude<EntryData, { type: "parallel" }>,
-  routeKey: string,
-  params: Record<string, string>,
-  context: HandlerContext<any, TEnv>,
-  clientSegmentIds: Set<string>,
-  prevParams: Record<string, string>,
-  request: Request,
-  prevUrl: URL,
-  nextUrl: URL,
-  deps: SegmentResolutionDeps<TEnv>,
-  actionContext?: ActionContext,
-  stale?: boolean,
-  /** The matched route's full chain; see ResolveSegmentOptions.chain (fresh.ts). */
+  /** The matched route's full chain; see RevalidatingWalkOptions.chain. */
   chain?: readonly EntryData[],
 ): Promise<SegmentRevalidationResult> {
   const segments: ResolvedSegment[] = [];
@@ -1132,22 +1295,15 @@ export async function resolveSegmentWithRevalidation<TEnv>(
 
   const belongsToRoute = entry.type === "route";
 
-  const loaderResult = await resolveOwnerLoaders(
-    ownerOf(entry),
-    context,
-    belongsToRoute,
-    clientSegmentIds,
-    prevParams,
-    request,
-    prevUrl,
-    nextUrl,
-    routeKey,
-    deps,
-    actionContext,
-    stale,
-  );
-  segments.push(...loaderResult.segments);
-  matchedIds.push(...loaderResult.matchedIds);
+  if (ownsLoaders(entry)) {
+    const loaderResult = await resolveOwnerLoaders(
+      pass,
+      ownerOf(entry),
+      belongsToRoute,
+    );
+    segments.push(...loaderResult.segments);
+    matchedIds.push(...loaderResult.matchedIds);
+  }
 
   // For route entries, execute the handler BEFORE orphan layouts and parallels
   // so ctx.set() data is available to them via ctx.get(). The handler's
@@ -1156,111 +1312,59 @@ export async function resolveSegmentWithRevalidation<TEnv>(
     | { segment: ResolvedSegment; matchedId: string }
     | undefined;
   if (entry.type === "route") {
-    routeHandlerResult = await resolveEntryHandlerWithRevalidation(
-      entry,
-      params,
-      context,
-      belongsToRoute,
-      clientSegmentIds,
-      prevParams,
-      request,
-      prevUrl,
-      nextUrl,
-      routeKey,
-      deps,
-      actionContext,
-      stale,
-    );
+    routeHandlerResult = await resolveEntryHandler(pass, entry, belongsToRoute);
 
     for (const orphan of entry.layout) {
-      const orphanResult = await resolveOrphanLayoutWithRevalidation(
-        orphan,
-        params,
-        context,
-        clientSegmentIds,
-        prevParams,
-        request,
-        prevUrl,
-        nextUrl,
-        routeKey,
-        true,
-        deps,
-        actionContext,
-        stale,
-        entry,
-      );
+      const orphanResult = await resolveOrphanLayout(pass, orphan, true, entry);
       segments.push(...orphanResult.segments);
       matchedIds.push(...orphanResult.matchedIds);
     }
   }
 
-  const resolveSlots = () =>
-    resolveParallelSegmentsWithRevalidation(
-      entry,
-      params,
-      context,
-      belongsToRoute,
-      clientSegmentIds,
-      prevParams,
-      request,
-      prevUrl,
-      nextUrl,
-      routeKey,
-      deps,
-      actionContext,
-      stale,
-    );
+  const slotted = declaresSlot(entry.parallel);
 
   if (routeHandlerResult) {
     // Route entry: handler already executed above; resolve parallels
     // (handler data visible) then push handler segment last for tree order.
-    const parallelResult = await resolveSlots();
-    segments.push(...parallelResult.segments);
-    matchedIds.push(...parallelResult.matchedIds);
+    if (slotted) {
+      const parallelResult = await resolveParallelSegments(
+        pass,
+        entry,
+        belongsToRoute,
+      );
+      segments.push(...parallelResult.segments);
+      matchedIds.push(...parallelResult.matchedIds);
+    }
 
     segments.push(routeHandlerResult.segment);
     matchedIds.push(routeHandlerResult.matchedId);
   } else {
     // Layout/cache entry: handler-first — resolve handler before parallels
     // so ctx.set() values are visible to parallel children.
-    const handlerResult = await resolveEntryHandlerWithRevalidation(
+    const handlerResult = await resolveEntryHandler(
+      pass,
       entry,
-      params,
-      context,
       belongsToRoute,
-      clientSegmentIds,
-      prevParams,
-      request,
-      prevUrl,
-      nextUrl,
-      routeKey,
-      deps,
-      actionContext,
-      stale,
     );
     segments.push(handlerResult.segment);
     matchedIds.push(handlerResult.matchedId);
 
-    const parallelResult = await resolveSlots();
-    segments.push(...parallelResult.segments);
-    matchedIds.push(...parallelResult.matchedIds);
+    if (slotted) {
+      const parallelResult = await resolveParallelSegments(
+        pass,
+        entry,
+        belongsToRoute,
+      );
+      segments.push(...parallelResult.segments);
+      matchedIds.push(...parallelResult.matchedIds);
+    }
 
     for (const orphan of entry.layout) {
       if (chain?.includes(orphan)) continue;
-      const orphanResult = await resolveOrphanLayoutWithRevalidation(
+      const orphanResult = await resolveOrphanLayout(
+        pass,
         orphan,
-        params,
-        context,
-        clientSegmentIds,
-        prevParams,
-        request,
-        prevUrl,
-        nextUrl,
-        routeKey,
         false,
-        deps,
-        actionContext,
-        stale,
         undefined,
         entry,
       );
@@ -1273,25 +1377,74 @@ export async function resolveSegmentWithRevalidation<TEnv>(
 }
 
 /**
- * Resolve orphan layout with revalidation.
+ * Whether a partial pass re-renders an orphan layout: one the client lacks,
+ * or a held one whose revalidate() rules ask for it (revalidateHeld).
  */
-export async function resolveOrphanLayoutWithRevalidation<TEnv>(
+async function orphanRevalidates<TEnv>(
+  pass: ResolutionPass<TEnv>,
+  orphan: EntryData,
+  belongsToRoute: boolean,
+): Promise<boolean> {
+  const { context, params, routeKey } = pass;
+  if (!pass.client.has(orphan.shortCode)) {
+    if (isTraceActive()) {
+      pushRevalidationTraceEntry({
+        segmentId: orphan.shortCode,
+        segmentType: "layout",
+        belongsToRoute,
+        source: "orphan-layout",
+        defaultShouldRevalidate: true,
+        finalShouldRevalidate: true,
+        reason: "new-segment",
+      });
+    }
+    return true;
+  }
+
+  const dummySegment: ResolvedSegment = {
+    id: orphan.shortCode,
+    namespace: orphan.id,
+    type: "layout",
+    index: 0,
+    component: null as any,
+    params,
+    belongsToRoute,
+    layoutName: orphan.id,
+    ...(orphan.mountPath ? { mountPath: orphan.mountPath } : {}),
+  };
+
+  return revalidateHeld(pass, {
+    segment: dummySegment,
+    revalidations: orphan.revalidate.map((fn, i) => ({
+      name: `revalidate${i}`,
+      fn,
+    })),
+    traceSource: "orphan-layout",
+    onEvaluated: (shouldRevalidate) =>
+      emitRevalidationDecision(
+        orphan.shortCode,
+        context.pathname,
+        routeKey,
+        shouldRevalidate,
+      ),
+  });
+}
+
+/**
+ * Resolve an orphan layout: its loaders, its handler, its slots and the
+ * routeless entries nested in it.
+ */
+export async function resolveOrphanLayout<TEnv>(
+  pass: ResolutionPass<TEnv>,
   orphan: EntryData,
-  params: Record<string, string>,
-  context: HandlerContext<any, TEnv>,
-  clientSegmentIds: Set<string>,
-  prevParams: Record<string, string>,
-  request: Request,
-  prevUrl: URL,
-  nextUrl: URL,
-  routeKey: string,
   belongsToRoute: boolean,
-  deps: SegmentResolutionDeps<TEnv>,
-  actionContext?: ActionContext,
-  stale?: boolean,
   /** Parent route entry — its loaders are inherited so parallel slots can access them. */
   parentRouteEntry?: EntryData,
-  /** Matched chain entry being resolved (see ResolveSegmentOptions.boundaryEntry); defaults to parentRouteEntry. */
+  /**
+   * Matched chain entry being resolved (see
+   * resolveParallelSegments's boundaryEntry); defaults to
+   * parentRouteEntry.
+   */
   boundaryEntry: EntryData | undefined = parentRouteEntry,
 ): Promise<SegmentRevalidationResult> {
   invariant(
@@ -1299,28 +1452,25 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
     `Expected orphan to be a layout or cache, got: ${orphan.type}`,
   );
 
+  const { context, params } = pass;
+  const fresh = pass.client === FRESH;
   const segments: ResolvedSegment[] = [];
   const matchedIds: string[] = [];
 
-  const loaderResult = await resolveOwnerLoaders(
-    ownerOf(orphan),
-    context,
-    belongsToRoute,
-    clientSegmentIds,
-    prevParams,
-    request,
-    prevUrl,
-    nextUrl,
-    routeKey,
-    deps,
-    actionContext,
-    stale,
-  );
-  segments.push(...loaderResult.segments);
-  matchedIds.push(...loaderResult.matchedIds);
+  if (ownsLoaders(orphan)) {
+    const loaderResult = await resolveOwnerLoaders(
+      pass,
+      ownerOf(orphan),
+      belongsToRoute,
+    );
+    segments.push(...loaderResult.segments);
+    matchedIds.push(...loaderResult.matchedIds);
+  }
 
   // Inherit parent route's loaders so parallel slots inside this layout
-  // can access them via useLoader(). See resolveOrphanLayout in fresh.ts.
+  // can access them via useLoader(). Without this, the route's loaders are
+  // only in the route's OutletProvider (rendered as <Outlet /> content),
+  // which is a child — not a parent — of the layout's context.
   if (
     parentRouteEntry &&
     parentRouteEntry.loader &&
@@ -1328,18 +1478,9 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
     Object.keys(orphan.parallel).length > 0
   ) {
     const inheritedResult = await resolveOwnerLoaders(
+      pass,
       ownerOf(parentRouteEntry, orphan.shortCode),
-      context,
       belongsToRoute,
-      clientSegmentIds,
-      prevParams,
-      request,
-      prevUrl,
-      nextUrl,
-      routeKey,
-      deps,
-      actionContext,
-      stale,
     );
     // Tag as inherited so buildMatchResult can deduplicate when safe
     for (const s of inheritedResult.segments) {
@@ -1353,70 +1494,33 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
   // so ctx.set() values are visible to parallel children.
   matchedIds.push(orphan.shortCode);
 
+  let handlerRan = false;
   let deferred: { readonly deferred: true } | undefined;
-  const component = await revalidate(
-    async () => {
-      if (!clientSegmentIds.has(orphan.shortCode)) {
-        if (isTraceActive()) {
-          pushRevalidationTraceEntry({
-            segmentId: orphan.shortCode,
-            segmentType: "layout",
-            belongsToRoute,
-            source: "orphan-layout",
-            defaultShouldRevalidate: true,
-            finalShouldRevalidate: true,
-            reason: "new-segment",
-          });
-        }
-        return true;
+  let component: ReactNode = null;
+  // FRESH: the orphan is new; no decision is asked, traced or observed.
+  if (fresh || (await orphanRevalidates(pass, orphan, belongsToRoute))) {
+    // Below a unit a prefetch skipped: the orphan goes with it.
+    deferred = deferUnit(context, orphan.shortCode, "below");
+    if (!deferred) {
+      handlerRan = true;
+      // Its handler's pushes are its own. Pinned only while it runs: a route
+      // under loading() streams its handler, whose pushes after an await
+      // read the pin after this returns.
+      const internal = context as InternalHandlerContext<any, TEnv>;
+      const pinned = internal._currentSegmentId;
+      internal._currentSegmentId = orphan.shortCode;
+      const doneHandler = track(`handler:${orphan.id}`, 2);
+      try {
+        component = await resolveLayoutComponent(orphan, context);
+      } catch (error) {
+        // Its owning entry's boundary catches it.
+        throw noteThrower(error, orphan.shortCode, orphan.type);
+      } finally {
+        internal._currentSegmentId = pinned;
       }
-
-      const dummySegment: ResolvedSegment = {
-        id: orphan.shortCode,
-        namespace: orphan.id,
-        type: "layout",
-        index: 0,
-        component: null as any,
-        params,
-        belongsToRoute,
-        layoutName: orphan.id,
-        ...(orphan.mountPath ? { mountPath: orphan.mountPath } : {}),
-      };
-
-      return revalidateHeld({
-        segment: dummySegment,
-        prevParams,
-        getPrevSegment: null,
-        request,
-        prevUrl,
-        nextUrl,
-        revalidations: orphan.revalidate.map((fn, i) => ({
-          name: `revalidate${i}`,
-          fn,
-        })),
-        routeKey,
-        context,
-        actionContext,
-        stale,
-        traceSource: "orphan-layout",
-        held: clientSegmentIds,
-        onEvaluated: (shouldRevalidate) =>
-          emitRevalidationDecision(
-            orphan.shortCode,
-            context.pathname,
-            routeKey,
-            shouldRevalidate,
-          ),
-      });
-    },
-    async () => {
-      // Below a unit a prefetch skipped: the orphan goes with it.
-      deferred = deferUnit(context, orphan.shortCode, "below");
-      if (deferred) return null;
-      return resolveLayoutComponent(orphan, context);
-    },
-    () => null,
-  );
+      doneHandler();
+    }
+  }
 
   segments.push({
     id: orphan.shortCode,
@@ -1430,9 +1534,10 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
     loading: orphan.loading === false ? null : orphan.loading,
     transition: applyViewTransitionDefault(
       orphan.transition,
-      deps.viewTransitionDefault,
+      pass.deps.viewTransitionDefault,
     ),
     ...(orphan.mountPath ? { mountPath: orphan.mountPath } : {}),
+    _handlerRan: handlerRan,
     ...deferred,
   });
 
@@ -1442,48 +1547,35 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
   //     `true` (orphan parallels always belong to the route — the #482 guard),
   //     where the main path would seed `belongsToRoute || isNewParent`.
   //   - loaderOrder "before": a slot's loaders are emitted before the slot
-  //     segment, matching the prior inlined order.
+  //     segment, matching the prior inlined order. FRESH emits them after it,
+  //     as on the main path.
   // `entry.shortCode` inside the helper is `orphan.shortCode` (orphan is passed
   // as `entry`), so the parallel ids + loader shortCodeOverride are unchanged.
-  const parallelResult = await resolveParallelSegmentsWithRevalidation(
-    orphan,
-    params,
-    context,
-    belongsToRoute,
-    clientSegmentIds,
-    prevParams,
-    request,
-    prevUrl,
-    nextUrl,
-    routeKey,
-    deps,
-    actionContext,
-    stale,
-    {
-      parentChainDefault: "force-render",
-      loaderOrder: "before",
-      boundaryEntry,
-    },
-  );
-  segments.push(...parallelResult.segments);
-  matchedIds.push(...parallelResult.matchedIds);
+  if (declaresSlot(orphan.parallel)) {
+    const parallelResult = await resolveParallelSegments(
+      pass,
+      orphan,
+      belongsToRoute,
+      {
+        parentChainDefault: "force-render",
+        loaderOrder: fresh ? "after" : "before",
+        boundaryEntry,
+      },
+    );
+    segments.push(...parallelResult.segments);
+    matchedIds.push(...parallelResult.matchedIds);
+  }
 
-  // Nested routeless entries; see resolveOrphanLayout (fresh.ts).
+  // Routeless entries nested in this one (a layout() after a bare cache()
+  // marker, a wrapper inside a routeless wrapper) wrap the same content one
+  // level deeper. Issue #918: they were never rendered. None is in the
+  // matched chain: that would put this orphan in it, and
+  // resolveSegment skips those.
   for (const nested of orphan.layout) {
-    const nestedResult = await resolveOrphanLayoutWithRevalidation(
+    const nestedResult = await resolveOrphanLayout(
+      pass,
       nested,
-      params,
-      context,
-      clientSegmentIds,
-      prevParams,
-      request,
-      prevUrl,
-      nextUrl,
-      routeKey,
       belongsToRoute,
-      deps,
-      actionContext,
-      stale,
       undefined,
       boundaryEntry,
     );
@@ -1494,44 +1586,103 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
   return { segments, matchedIds };
 }
 
+/** What resolveAllSegments needs beyond its pass. */
+export interface RevalidatingWalkOptions {
+  /**
+   * The intercept the request resolves: the route's entry (its handler and
+   * loaders) is skipped and only its id is matched. None on a full match.
+   */
+  readonly interceptResult?: InterceptResult | null;
+  /** For the intercept skip's debug log. */
+  readonly localRouteName?: string;
+  /** Where an entry's error boundary reports (resolveWithErrorBoundary). */
+  readonly pathname: string;
+  /**
+   * The matched route's full entry chain. Defaults to `entries`;
+   * withCacheLookup passes it when it resolves only the entries above a
+   * cache() boundary. An orphan list can hold an entry of the chain: a bare
+   * cache() marker sits in its layout's layout[] (it wraps that layout's
+   * routes) and is the parent of the routes after it. For those routes it
+   * resolves once, as a chain entry, below the cache() header latch (issue
+   * #918: resolved twice on a MISS, once and discarded on a HIT).
+   */
+  readonly chain?: readonly EntryData[];
+}
+
+/**
+ * The onError `isPartial` of an error the walk catches. FRESH: a full match
+ * reports it unset. A re-render a navigation started reports it true
+ * (partialRequest).
+ */
+function reportsPartial(pass: ResolutionPass<any>): true | undefined {
+  return pass.client !== FRESH || pass.partialRequest ? true : undefined;
+}
+
+/** An entry's error or not-found segment, as its whole result. */
+function boundaryResult(seg: ResolvedSegment): SegmentRevalidationResult {
+  return { segments: [seg], matchedIds: [seg.id] };
+}
+
 /**
- * Resolve all segments for a route with revalidation logic (for matchPartial).
+ * Resolve all segments for a route: a partial match (matchPartial), a full
+ * match with a FRESH pass, or the FRESH pass of an intercept record's
+ * background re-render (rerenderAndCacheRoute). A thrown action's pass is cut
+ * at its error boundary (ActionContext.boundary).
  */
-export async function resolveAllSegmentsWithRevalidation<TEnv>(
+export async function resolveAllSegments<TEnv>(
+  pass: ResolutionPass<TEnv>,
   entries: EntryData[],
-  routeKey: string,
-  params: Record<string, string>,
-  context: HandlerContext<any, TEnv>,
-  clientSegmentSet: Set<string>,
-  prevParams: Record<string, string>,
-  request: Request,
-  prevUrl: URL,
-  nextUrl: URL,
-  actionContext: ActionContext | undefined,
-  interceptResult: { intercept: any; entry: EntryData } | null,
-  localRouteName: string,
-  pathname: string,
-  deps: SegmentResolutionDeps<TEnv>,
-  stale?: boolean,
-  /** The matched route's full chain; see ResolveSegmentOptions.chain (fresh.ts). */
-  chain: readonly EntryData[] = entries,
+  walk: RevalidatingWalkOptions,
 ): Promise<{ segments: ResolvedSegment[]; matchedIds: string[] }> {
+  const { context, params, routeKey, request } = pass;
+  const { interceptResult, localRouteName, pathname } = walk;
+  const chain = walk.chain ?? entries;
   const allSegments: ResolvedSegment[] = [];
   const matchedIds: string[] = [];
   const seenSegIds = new Set<string>();
   const seenMatchIds = new Set<string>();
 
-  // ppr header-write guard latch — see resolveAllSegments (fresh.ts).
+  // ppr routes are document-scoped cached territory: the whole chain (root
+  // layout down to the page) bakes into the shared shell, so the header-write
+  // guard latches BEFORE any entry resolves (unlike the positional cache()
+  // latch below). See assertCachedHeaderWriteAllowed (server/context.ts).
   latchPprHeaderScopeForEntries(entries, routeKey);
 
-  const telemetry = getRouterContext()?.telemetry;
+  // No router context at build time (prerender-match.ts): no telemetry sink.
+  let telemetry;
+  try {
+    telemetry = getRouterContext()?.telemetry;
+  } catch {}
+  // A build-time pass rethrows an entry's error (throwOnError).
+  const report = {
+    request,
+    url: context.url,
+    routeKey,
+    isPartial: reportsPartial(pass),
+    telemetry,
+  };
   const fillMatch = {
     handlerContext: context,
     isIntercept: !!interceptResult,
-    clientSegmentSet,
+    clientSegmentSet: pass.client,
   };
 
+  const boundary = pass.actionContext?.boundary;
+  const cutId = boundary?.id ?? pass.heldBoundary;
+  let cut = false;
   for (const entry of entries) {
+    if (entry.shortCode === cutId) {
+      // The outlet's loader ids stay claimed. _handlerRan makes the browser
+      // clear the outlet's handle values. A held boundary sends no segment:
+      // the client keeps its own, with its handle values.
+      if (boundary) allSegments.push({ ...boundary, _handlerRan: true });
+      matchedIds.push(cutId);
+      entry.loader?.forEach((loaderEntry, i) =>
+        matchedIds.push(`${entry.shortCode}D${i}.${loaderEntry.loader.$$id}`),
+      );
+      cut = true;
+      break;
+    }
     if (entry.type === "route" && interceptResult) {
       debugLog(
         "matchPartial.intercept",
@@ -1550,7 +1701,11 @@ export async function resolveAllSegmentsWithRevalidation<TEnv>(
     if (interceptFillSkips(fillMatch, entry.shortCode)) continue;
 
     const nonParallelEntry = entry as Exclude<EntryData, { type: "parallel" }>;
-    // Same latch as resolveAllSegments (fresh.ts), route-level cache() included.
+    // Set ALS flag when entering a cache() boundary so that ctx.get()
+    // can guard non-cacheable variable reads. Also latch the header-write
+    // scope (response-level side effects — headers/cookies/status).
+    // Persists for all descendant entries. A route entry carries `cache` when
+    // cache() is among its own children (dsl-helpers.ts cache()).
     if (entry.cache) {
       const store = RangoContext.getStore();
       if (store) store.insideCacheScope = true;
@@ -1560,32 +1715,19 @@ export async function resolveAllSegmentsWithRevalidation<TEnv>(
     const resolved = await resolveWithErrorBoundary(
       nonParallelEntry,
       params,
-      () =>
-        resolveSegmentWithRevalidation(
-          nonParallelEntry,
-          routeKey,
-          params,
-          context,
-          clientSegmentSet,
-          prevParams,
-          request,
-          prevUrl,
-          nextUrl,
-          deps,
-          actionContext,
-          stale,
-          chain,
-        ),
-      (seg) => ({ segments: [seg], matchedIds: [seg.id] }),
-      deps,
-      { request, url: context.url, routeKey, isPartial: true, telemetry },
+      () => resolveSegment(pass, nonParallelEntry, chain),
+      boundaryResult,
+      pass.deps,
+      report,
       pathname,
+      pass.throwOnError,
     );
     doneEntry();
 
-    // Deduplicate segments and matchedIds by ID, matching resolveAllSegments.
-    // include() scopes can produce entries that resolve the same shared
-    // layout/loader segment. Duplicates cause React tree depth changes.
+    // Deduplicate segments and matchedIds by ID. include() scopes can produce
+    // entries that resolve the same shared layout/loader segment. Duplicates
+    // in the segment array propagate to the client's matched[] and change
+    // the React tree depth.
     for (const seg of resolved.segments) {
       if (!seenSegIds.has(seg.id)) {
         seenSegIds.add(seg.id);
@@ -1600,6 +1742,14 @@ export async function resolveAllSegmentsWithRevalidation<TEnv>(
     }
   }
 
+  // A held boundary that names no entry (HMR rewrote the routes since the
+  // page rendered): the page renders whole, as without one.
+  if (pass.heldBoundary && !cut && process.env.NODE_ENV !== "production") {
+    console.warn(
+      `[@rangojs/router] A refetch held the error boundary "${pass.heldBoundary}", ` +
+        `which is not on the route's chain (${routeKey}): the page renders whole.`,
+    );
+  }
   deliverStartedLoaders(context, allSegments);
   return { segments: allSegments, matchedIds };
 }