@rangojs/router 0.0.0-experimental.35 → 0.0.0-experimental.358c376d

package/src/router/match-middleware/cache-store.ts

@@ -101,10 +101,15 @@
  *   - Non-GET request (only GET requests are cacheable)
  */
 import type { ResolvedSegment } from "../../types.js";
-import { getRequestContext } from "../../server/request-context.js";
+import {
+  getRequestContext,
+  runWithRequestContext,
+} from "../../server/request-context.js";
 import type { MatchContext, MatchPipelineState } from "../match-context.js";
+import { createShellImplicitDocScope } from "../../cache/cache-scope.js";
 import { getRouterContext } from "../router-context.js";
-import { debugLog, debugWarn } from "../logging.js";
+import { debugLog, debugWarn, getOrCreateRequestId } from "../logging.js";
+import { INTERNAL_RANGO_DEBUG } from "../../internal-debug.js";
 import type { GeneratorMiddleware } from "./cache-lookup.js";
 
 /**
@@ -120,21 +125,24 @@ export function withCacheStore<TEnv>(
   return async function* (
     source: AsyncGenerator<ResolvedSegment>,
   ): AsyncGenerator<ResolvedSegment> {
-    const pipelineStart = performance.now();
     const ms = ctx.metricsStore;
 
-    // Collect all segments while passing them through
     const allSegments: ResolvedSegment[] = [];
     for await (const segment of source) {
       allSegments.push(segment);
       yield segment;
     }
 
-    // Skip caching if:
-    // 1. Cache miss but cache scope is disabled
-    // 2. This is an action (actions don't cache)
-    // 3. Cache was already hit (no need to re-cache)
-    // 4. Non-GET request (only cache GET requests)
+    const ownStart = performance.now();
+
+    // Shell capture composition (capture side): a route-derived cache() scope
+    // keeps its normal store write below, but the capture's shell entry still
+    // needs the CANONICAL doc segment record for navigation replay. Recorded
+    // before the skip check because it must run on the explicit tier's hit
+    // path too (state.cacheHit skips the normal write, yet the served
+    // segments were collected into allSegments either way).
+    recordShellCaptureDocRecord(ctx, state, allSegments);
+
     if (
       !ctx.cacheScope?.enabled ||
       ctx.isAction ||
@@ -144,8 +152,8 @@ export function withCacheStore<TEnv>(
       if (ms) {
         ms.metrics.push({
           label: "pipeline:cache-store",
-          duration: performance.now() - pipelineStart,
-          startTime: pipelineStart - ms.requestStart,
+          duration: performance.now() - ownStart,
+          startTime: ownStart - ms.requestStart,
         });
       }
       return;
@@ -159,13 +167,22 @@ export function withCacheStore<TEnv>(
       createHandleStore,
     } = getRouterContext<TEnv>();
 
-    // Combine main segments with intercept segments
-    const allSegmentsToCache = [...allSegments, ...state.interceptSegments];
+    // On a fresh intercept miss the intercept slot segments flow through
+    // `source` into allSegments AND are also recorded on state.interceptSegments.
+    // Dedup by id so each segment is cached once — cacheRoute serializes the
+    // array verbatim (no id-dedup), so an un-deduped append doubles the intercept
+    // segment in the cached entry, re-rendering the slot twice on the next hit.
+    const seenSegmentIds = new Set(allSegments.map((s) => s.id));
+    const allSegmentsToCache = [
+      ...allSegments,
+      ...state.interceptSegments.filter((s) => !seenSegmentIds.has(s.id)),
+    ];
 
-    // Check if any non-loader segments have null components
-    // This happens when client already had those segments (partial navigation)
     const hasNullComponents = allSegmentsToCache.some(
-      (s) => s.component === null && s.type !== "loader",
+      (s) =>
+        s.component === null &&
+        s.type !== "loader" &&
+        ctx.clientSegmentSet.has(s.id),
     );
 
     const requestCtx = getRequestContext();
@@ -173,10 +190,22 @@ export function withCacheStore<TEnv>(
 
     const cacheScope = ctx.cacheScope;
 
-    // Register onResponse callback to skip caching for non-200 responses
-    // Note: error/notFound status codes are set elsewhere (not caching-specific)
+    // Record the route's segment-DSL cache tags into the request tag union NOW,
+    // synchronously in the pipeline. The actual store write (cacheRoute) runs in
+    // requestCtx.waitUntil() below — and the proactive path re-resolves the whole
+    // tree first — so cacheRoute's own tag recording races the document cache's
+    // post-body-drain snapshot of _requestTags. On a first-write miss the document
+    // tag union could miss these tags and revalidateTag()/updateTag() would not
+    // invalidate the cached document. Recording here (before the snapshot) closes
+    // the window for both the direct and proactive write paths; the duplicate
+    // record inside cacheRoute is idempotent.
+    cacheScope.recordTags(requestCtx);
+
+    const reqId = INTERNAL_RANGO_DEBUG
+      ? getOrCreateRequestId(ctx.request)
+      : undefined;
+
     requestCtx.onResponse((response) => {
-      // Only cache successful responses
       if (response.status !== 200) {
         debugLog("cacheStore", "skipping cache for non-200 response", {
           status: response.status,
@@ -186,21 +215,17 @@ export function withCacheStore<TEnv>(
       }
 
       if (hasNullComponents) {
-        // Proactive caching: render all segments fresh in background
-        // This ensures cache has complete components for future requests
         requestCtx.waitUntil(async () => {
+          const savedMetrics = ctx.Store.metrics;
+          ctx.Store.metrics = undefined;
+
+          const start = performance.now();
           debugLog("cacheStore", "proactive caching started", {
             pathname: ctx.pathname,
           });
-          // Swap to a fresh HandleStore so handle.push() calls from
-          // proactive resolution are captured (not silenced). The original
-          // store's stream is already sent by waitUntil time.
-          // cacheRoute reads from requestCtx._handleStore, so this ensures
-          // complete handle data (e.g. breadcrumbs) is cached.
           const originalHandleStore = requestCtx._handleStore;
           requestCtx._handleStore = createHandleStore();
           try {
-            // Create fresh context for proactive caching
             const proactiveHandlerContext = createHandlerContext(
               ctx.matched.params,
               ctx.request,
@@ -215,33 +240,49 @@ export function withCacheStore<TEnv>(
             );
             const proactiveLoaderPromises = new Map<string, Promise<any>>();
 
-            // Use normal loader access so handle data is captured
             setupLoaderAccess(proactiveHandlerContext, proactiveLoaderPromises);
 
-            // Re-resolve ALL segments without revalidation
             const Store = ctx.Store;
-            const freshSegments = await Store.run(() =>
-              resolveAllSegments(
-                ctx.entries,
-                ctx.routeKey,
-                ctx.matched.params,
-                proactiveHandlerContext,
-                proactiveLoaderPromises,
+            // Re-establish the request-context ALS around the re-render. Store
+            // is a different ALS (DSL build context); on workerd a waitUntil
+            // task runs detached from the request's I/O context, so a handler/
+            // component that reads the ambient getRequestContext() during this
+            // background re-render would otherwise throw "called outside of a
+            // request context".
+            const freshSegments = await runWithRequestContext(requestCtx, () =>
+              Store.run(() =>
+                resolveAllSegments(
+                  ctx.entries,
+                  ctx.routeKey,
+                  ctx.matched.params,
+                  proactiveHandlerContext,
+                  proactiveLoaderPromises,
+                  { skipLoaders: true },
+                ),
               ),
             );
 
-            // Also resolve intercept segments fresh if applicable
             let freshInterceptSegments: ResolvedSegment[] = [];
             if (ctx.interceptResult) {
-              freshInterceptSegments = await Store.run(() =>
-                resolveInterceptEntry(
-                  ctx.interceptResult!.intercept,
-                  ctx.interceptResult!.entry,
-                  ctx.matched.params,
-                  proactiveHandlerContext,
-                  true, // belongsToRoute
-                  // No revalidationContext = render fresh
-                ),
+              freshInterceptSegments = await runWithRequestContext(
+                requestCtx,
+                () =>
+                  Store.run(() =>
+                    resolveInterceptEntry(
+                      ctx.interceptResult!.intercept,
+                      ctx.interceptResult!.entry,
+                      ctx.matched.params,
+                      proactiveHandlerContext,
+                      true, // belongsToRoute
+                      // No revalidationContext = render fresh
+                      undefined,
+                      // Skip intercept middleware: the foreground already ran it
+                      // before the response was sent. Re-running here (post-
+                      // response, background) would fire side effects twice and a
+                      // short-circuit Response would silently abort this write.
+                      { skipMiddleware: true },
+                    ),
+                  ),
               );
             }
 
@@ -256,28 +297,51 @@ export function withCacheStore<TEnv>(
               completeSegments,
               ctx.isIntercept,
             );
+            if (INTERNAL_RANGO_DEBUG) {
+              const dur = performance.now() - start;
+              console.log(
+                `[RSC Background][req:${reqId}] Proactive cache ${ctx.pathname} (${dur.toFixed(2)}ms) segments=${completeSegments.length}`,
+              );
+            }
             debugLog("cacheStore", "proactive caching complete", {
               pathname: ctx.pathname,
             });
           } catch (error) {
+            if (INTERNAL_RANGO_DEBUG) {
+              const dur = performance.now() - start;
+              console.log(
+                `[RSC Background][req:${reqId}] Proactive cache ${ctx.pathname} FAILED (${dur.toFixed(2)}ms) error=${String(error)}`,
+              );
+            }
             debugWarn("cacheStore", "proactive caching failed", {
               pathname: ctx.pathname,
               error: String(error),
             });
           } finally {
             requestCtx._handleStore = originalHandleStore;
+            ctx.Store.metrics = savedMetrics;
           }
         });
       } else {
-        // All segments have components - cache directly
-        // Schedule caching in waitUntil since cacheRoute is now async (key resolution)
+        if (INTERNAL_RANGO_DEBUG) {
+          console.log(
+            `[RSC CacheStore][req:${reqId}] Direct cache path: scheduling cacheRoute for ${ctx.pathname} (${allSegmentsToCache.length} segments, hasNullComponents=${hasNullComponents})`,
+          );
+        }
         requestCtx.waitUntil(async () => {
+          const start = performance.now();
           await cacheScope.cacheRoute(
             ctx.pathname,
             ctx.matched.params,
             allSegmentsToCache,
             ctx.isIntercept,
           );
+          if (INTERNAL_RANGO_DEBUG) {
+            const dur = performance.now() - start;
+            console.log(
+              `[RSC Background][req:${reqId}] Cache store ${ctx.pathname} (${dur.toFixed(2)}ms) segments=${allSegmentsToCache.length}`,
+            );
+          }
         });
       }
 
@@ -287,9 +351,70 @@ export function withCacheStore<TEnv>(
     if (ms) {
       ms.metrics.push({
         label: "pipeline:cache-store",
-        duration: performance.now() - pipelineStart,
-        startTime: pipelineStart - ms.requestStart,
+        duration: performance.now() - ownStart,
+        startTime: ownStart - ms.requestStart,
       });
     }
   };
 }
+
+/**
+ * During a SHELL CAPTURE of a route with a route-derived cache() scope, write
+ * the matched non-loader segments as the canonical doc segment record through
+ * the capture marker's SnapshotOnlySegmentStore — IN ADDITION to the explicit
+ * scope's normal real-store write. The record rides only inside the shell
+ * entry (a real doc-keyed write would poison the next capture's lookup; see
+ * RecordingShellStore.recordSegmentWrite), so no real-store behavior changes.
+ * Without it, navigation replay was structurally dead for any ppr route under
+ * a cache() scope (including an app-wide one): the snapshot held only
+ * explicit-tier-keyed records a partial lookup can never resolve.
+ *
+ * Records nothing when:
+ * - not a capture render, or the route derived no scope (the implicit doc
+ *   scope's own cacheRoute below already records the doc record);
+ * - the scope is STATICALLY disabled (cache(false)) — the replay gate
+ *   pre-decides that shape as `cache-disabled` before any shell read, so a
+ *   record would be dead weight;
+ * - the prerender store supplied the match: those partials are served from
+ *   build-time segments and report `prerender-store`.
+ *
+ * A false condition() suppresses the record too — the consumer's write
+ * refusal is absolute. The prelude-already-bakes-it argument does NOT excuse
+ * recording: a NAVIGATION-ONLY capture's prelude is never served as a
+ * document, so for those entries the segment record would be the sole
+ * persisted copy of a render the consumer refused to cache — and a later
+ * request where condition() flips true could consume it through the seeded
+ * fallback. The lookup-time `cache-disabled` report stays reachable without
+ * the record: matchPartialWithPprReplay installs a REPORT-ONLY marker (no
+ * store) on the no-eligible-snapshot path, so the lookup's own refusal is
+ * still surfaced while the fallback has nothing to serve.
+ *
+ * Wrapped in requestCtx.waitUntil — during a capture that is the tracked-write
+ * override, so captureAndStoreShell's settleWrites awaits the record before
+ * draining the snapshot.
+ */
+function recordShellCaptureDocRecord<TEnv>(
+  ctx: MatchContext<TEnv>,
+  state: MatchPipelineState,
+  segments: ResolvedSegment[],
+): void {
+  const requestCtx = getRequestContext();
+  if (!requestCtx?._shellCaptureRun) return;
+  const marker = requestCtx._shellImplicitCache;
+  if (!marker?.store) return;
+  const scope = ctx.cacheScope;
+  if (!scope || scope.isShellImplicitDocScope) return;
+  if (ctx.isAction || ctx.isIntercept || ctx.request.method !== "GET") return;
+  if (state.cacheSource === "prerender") return;
+  if (!scope.allowsCache("write")) return;
+
+  const docScope = createShellImplicitDocScope(marker);
+  requestCtx.waitUntil(() =>
+    docScope.cacheRoute(
+      ctx.pathname,
+      ctx.matched.params,
+      segments,
+      ctx.isIntercept,
+    ),
+  );
+}

package/src/router/match-middleware/intercept-resolution.ts

@@ -123,54 +123,46 @@ export function withInterceptResolution<TEnv>(
   return async function* (
     source: AsyncGenerator<ResolvedSegment>,
   ): AsyncGenerator<ResolvedSegment> {
-    const pipelineStart = performance.now();
     const ms = ctx.metricsStore;
 
-    // First, yield all segments from the source (main segment resolution or cache)
     const segments: ResolvedSegment[] = [];
     for await (const segment of source) {
       segments.push(segment);
       yield segment;
     }
 
-    // Skip intercept resolution for full match (document requests don't have intercepts)
+    const ownStart = performance.now();
+
     if (ctx.isFullMatch) {
       if (ms) {
         ms.metrics.push({
           label: "pipeline:intercept",
-          duration: performance.now() - pipelineStart,
-          startTime: pipelineStart - ms.requestStart,
+          duration: performance.now() - ownStart,
+          startTime: ownStart - ms.requestStart,
         });
       }
       return;
     }
 
-    // Skip intercept resolution if:
-    // 1. No intercept result
-    // 2. Already have intercept segments (from cache hit with intercept key)
-    // 3. Cache hit with intercept key
     const skipInterceptResolution =
       !ctx.interceptResult ||
       state.interceptSegments.length > 0 ||
       (state.cacheHit && ctx.isIntercept);
 
     if (skipInterceptResolution) {
-      // For cache hit with intercept, extract intercept segments from cached data for slots
-      // and re-resolve loaders for fresh data
       if (ctx.interceptResult && state.cacheHit && ctx.isIntercept) {
         await handleCacheHitIntercept(ctx, state, segments);
       }
       if (ms) {
         ms.metrics.push({
           label: "pipeline:intercept",
-          duration: performance.now() - pipelineStart,
-          startTime: pipelineStart - ms.requestStart,
+          duration: performance.now() - ownStart,
+          startTime: ownStart - ms.requestStart,
         });
       }
       return;
     }
 
-    // Resolve intercept segments
     const { resolveInterceptEntry } = getRouterContext<TEnv>();
 
     const slotName = ctx.interceptResult!.intercept.slotName;
@@ -179,7 +171,6 @@ export function withInterceptResolution<TEnv>(
       slotName,
     });
 
-    // Resolve intercept entry (middleware, loaders, handler)
     const Store = ctx.Store;
     const interceptSegments = await Store.run(() =>
       resolveInterceptEntry(
@@ -201,14 +192,12 @@ export function withInterceptResolution<TEnv>(
       ),
     );
 
-    // Update state
     state.interceptSegments = interceptSegments;
     state.slots[slotName] = {
       active: true,
       segments: interceptSegments,
     };
 
-    // Yield intercept segments
     for (const segment of interceptSegments) {
       yield segment;
     }
@@ -216,18 +205,13 @@ export function withInterceptResolution<TEnv>(
     if (ms) {
       ms.metrics.push({
         label: "pipeline:intercept",
-        duration: performance.now() - pipelineStart,
-        startTime: pipelineStart - ms.requestStart,
+        duration: performance.now() - ownStart,
+        startTime: ownStart - ms.requestStart,
       });
     }
   };
 }
 
-/**
- * Handle cache hit with intercept scenario
- *
- * Extract intercept segments from cached data and re-resolve loaders for fresh data.
- */
 async function handleCacheHitIntercept<TEnv>(
   ctx: MatchContext<TEnv>,
   state: MatchPipelineState,
@@ -239,14 +223,11 @@ async function handleCacheHitIntercept<TEnv>(
 
   const slotName = ctx.interceptResult.intercept.slotName;
 
-  // Find intercept segments from cached segments (namespace starts with "intercept:")
   const interceptSegments = segments.filter((s) =>
     s.namespace?.startsWith("intercept:"),
   );
   state.interceptSegments = interceptSegments;
 
-  // Re-resolve intercept loaders for fresh data on cache hit
-  // This keeps cached component/layout but fetches fresh loader data
   if (resolveInterceptLoadersOnly) {
     const Store = ctx.Store;
     const freshLoaderResult = await Store.run(() =>
@@ -269,7 +250,6 @@ async function handleCacheHitIntercept<TEnv>(
       ),
     );
 
-    // Update intercept segment's loaderDataPromise with fresh data
     if (freshLoaderResult) {
       const interceptMainSegment = interceptSegments.find(
         (s) => s.type === "parallel" && s.slot,

package/src/router/match-middleware/segment-resolution.ts

@@ -87,16 +87,43 @@
  *   if (state.cacheHit) return;   // Now we can check
  */
 import type { ResolvedSegment } from "../../types.js";
+import type { EntryData } from "../../server/context.js";
+import { _getRequestContext } from "../../server/request-context.js";
 import type { MatchContext, MatchPipelineState } from "../match-context.js";
 import { getRouterContext } from "../router-context.js";
 import type { GeneratorMiddleware } from "./cache-lookup.js";
 
-/**
- * Creates segment resolution middleware
- *
- * Only runs on cache miss (state.cacheHit === false).
- * Uses resolveAllSegmentsWithRevalidation from RouterContext to resolve segments.
- */
+export function treeHasStreaming(entries: EntryData[]): boolean {
+  for (const entry of entries) {
+    if (
+      "loading" in entry &&
+      entry.loading !== undefined &&
+      entry.loading !== false
+    )
+      return true;
+    if (entry.layout) {
+      if (treeHasStreaming(entry.layout)) return true;
+    }
+    if (entry.parallel) {
+      for (const key in entry.parallel) {
+        const parallelEntry = entry.parallel[key as `@${string}`];
+        if (parallelEntry) {
+          if (
+            "loading" in parallelEntry &&
+            parallelEntry.loading !== undefined &&
+            parallelEntry.loading !== false
+          )
+            return true;
+          if (parallelEntry.layout) {
+            if (treeHasStreaming(parallelEntry.layout)) return true;
+          }
+        }
+      }
+    }
+  }
+  return false;
+}
+
 export function withSegmentResolution<TEnv>(
   ctx: MatchContext<TEnv>,
   state: MatchPipelineState,
@@ -104,34 +131,36 @@ export function withSegmentResolution<TEnv>(
   return async function* (
     source: AsyncGenerator<ResolvedSegment>,
   ): AsyncGenerator<ResolvedSegment> {
-    const pipelineStart = performance.now();
     const ms = ctx.metricsStore;
 
-    // IMPORTANT: Always iterate source first to give cache-lookup a chance
-    // to run and set state.cacheHit. Without this, cache-lookup never executes!
     for await (const segment of source) {
       yield segment;
     }
 
-    // If cache hit, segments were already yielded by cache lookup
+    const ownStart = performance.now();
+
     if (state.cacheHit) {
       if (ms) {
         ms.metrics.push({
           label: "pipeline:segment-resolve",
-          duration: performance.now() - pipelineStart,
-          startTime: pipelineStart - ms.requestStart,
+          duration: performance.now() - ownStart,
+          startTime: ownStart - ms.requestStart,
         });
       }
       return;
     }
 
+    const reqCtx = _getRequestContext();
+    if (reqCtx && reqCtx._treeHasStreaming === undefined) {
+      reqCtx._treeHasStreaming = treeHasStreaming(ctx.entries);
+    }
+
     const { resolveAllSegmentsWithRevalidation, resolveAllSegments } =
       getRouterContext<TEnv>();
 
     const Store = ctx.Store;
 
     if (ctx.isFullMatch) {
-      // Full match (document request) - simple resolution without revalidation
       const segments = await Store.run(() =>
         resolveAllSegments(
           ctx.entries,
@@ -142,11 +171,12 @@ export function withSegmentResolution<TEnv>(
         ),
       );
 
-      // Update state with resolved segments
       state.segments = segments;
       state.matchedIds = segments.map((s: { id: string }) => s.id);
 
-      // Yield all resolved segments
+      if (reqCtx) {
+        reqCtx._resolveRenderBarrier(segments);
+      }
       for (const segment of segments) {
         yield segment;
       }
@@ -163,11 +193,11 @@ export function withSegmentResolution<TEnv>(
           ctx.request,
           ctx.prevUrl,
           ctx.url,
-          ctx.loaderPromises,
           ctx.actionContext,
           ctx.interceptResult,
           ctx.localRouteName,
           ctx.pathname,
+          ctx.stale,
         ),
       );
 
@@ -175,6 +205,10 @@ export function withSegmentResolution<TEnv>(
       state.segments = result.segments;
       state.matchedIds = result.matchedIds;
 
+      if (reqCtx) {
+        reqCtx._resolveRenderBarrier(result.segments);
+      }
+
       // Yield all resolved segments
       for (const segment of result.segments) {
         yield segment;
@@ -184,8 +218,8 @@ export function withSegmentResolution<TEnv>(
     if (ms) {
       ms.metrics.push({
         label: "pipeline:segment-resolve",
-        duration: performance.now() - pipelineStart,
-        startTime: pipelineStart - ms.requestStart,
+        duration: performance.now() - ownStart,
+        startTime: ownStart - ms.requestStart,
       });
     }
   };

package/src/router/match-pipelines.ts

@@ -106,16 +106,6 @@ import {
   withSegmentResolution,
 } from "./match-middleware/index.js";
 
-/**
- * Compose multiple async generator middleware into a single middleware
- *
- * Middleware are applied in reverse order (rightmost runs first, innermost).
- * For the pipeline:
- *   compose(A, B, C)(source)
- *
- * The flow is: source -> C -> B -> A -> output
- * Where C is the innermost (runs first on input) and A is outermost (runs last).
- */
 export function compose<T>(
   ...middleware: GeneratorMiddleware<T>[]
 ): GeneratorMiddleware<T> {
@@ -126,54 +116,23 @@ export function compose<T>(
     return middleware[0];
   }
   return (source) => {
-    // Apply middleware in reverse order (rightmost first)
     return middleware.reduceRight((prev, fn) => fn(prev), source);
   };
 }
 
-/**
- * Create an empty async generator (source for pipeline)
- */
-export async function* empty<T>(): AsyncGenerator<T> {
-  // Yields nothing - used as the initial source for the pipeline
-}
+export async function* empty<T>(): AsyncGenerator<T> {}
 
-/**
- * Create the match partial pipeline
- *
- * Pipeline order (innermost to outermost):
- * 1. cache-lookup    - Check cache first, yield cached segments if hit
- * 2. segment-resolution - Resolve segments if cache miss
- * 3. intercept-resolution - Resolve intercept segments
- * 4. cache-store     - Store segments in cache
- * 5. background-revalidation - Trigger SWR if cache was stale
- *
- * Data flow:
- * - empty() produces no segments
- * - cache-lookup either yields cached segments OR passes through to segment-resolution
- * - segment-resolution resolves fresh segments on cache miss
- * - intercept-resolution adds intercept segments
- * - cache-store observes and caches segments
- * - background-revalidation triggers SWR revalidation if needed
- */
 export function createMatchPartialPipeline<TEnv>(
   ctx: MatchContext<TEnv>,
   state: MatchPipelineState,
 ): AsyncGenerator<ResolvedSegment> {
-  // Build the middleware chain
   const pipeline = compose<ResolvedSegment>(
-    // Outermost - observes segments and triggers background revalidation
     withBackgroundRevalidation(ctx, state),
-    // Observes and stores segments in cache
     withCacheStore(ctx, state),
-    // Adds intercept segments after main segments
     withInterceptResolution(ctx, state),
-    // Resolves segments on cache miss
     withSegmentResolution(ctx, state),
-    // Innermost - checks cache first
     withCacheLookup(ctx, state),
   );
 
-  // Start with empty source - cache lookup or segment resolution will produce segments
   return pipeline(empty());
 }