@rangojs/router 0.0.0-experimental.124 → 0.0.0-experimental.125

package/src/router/match-handlers.ts

@@ -89,20 +89,6 @@ export interface MatchHandlers<TEnv = any> {
     negotiated?: boolean;
     manifestEntry?: EntryData;
   } | null>;
-  createMatchContextForFull: (
-    request: Request,
-    env: TEnv,
-  ) => Promise<MatchContext<TEnv> | { type: "redirect"; redirectUrl: string }>;
-  createMatchContextForPartial: (
-    request: Request,
-    env: TEnv,
-    actionContext?: {
-      actionId?: string;
-      actionUrl?: URL;
-      actionResult?: any;
-      formData?: FormData;
-    },
-  ) => Promise<MatchContext<TEnv> | null>;
 }
 
 /**
@@ -123,9 +109,6 @@ export function createMatchHandlers<TEnv = any>(
   const hasTelemetry = !!deps.telemetry;
   const telemetry = resolveSink(deps.telemetry);
   const cacheSignalEnabled = !!deps.cacheSignalEnabled;
-  // Compute the coarse cache signal when EITHER telemetry needs it (for the
-  // cache.decision event) OR the debug header gate is on. When neither is set,
-  // this is never called — zero extra work on the hot path.
   const buildSignal = (
     routeKey: string,
     state: {
@@ -134,8 +117,6 @@ export function createMatchHandlers<TEnv = any>(
       shouldRevalidate?: boolean;
     },
   ): CacheSegmentSignal[] => buildCacheSignalSegments(routeKey, state);
-  // Stash the signal on the request context for the response path to emit as
-  // the X-Rango-Cache header. Only when the debug gate is on.
   const recordSignalIfEnabled = (segments: CacheSegmentSignal[]): void => {
     if (!cacheSignalEnabled) return;
     const reqCtx = _getRequestContext();
@@ -173,15 +154,6 @@ export function createMatchHandlers<TEnv = any>(
     );
   }
 
-  /**
-   * Match request and return segments (document/SSR requests)
-   *
-   * Uses generator middleware pipeline for clean separation of concerns:
-   * - cache-lookup: Check cache first
-   * - segment-resolution: Resolve segments on cache miss
-   * - cache-store: Store results in cache
-   * - background-revalidation: SWR revalidation
-   */
   async function match(request: Request, env: TEnv): Promise<MatchResult> {
     const requestId = hasTelemetry ? getRequestId(request) : undefined;
     return runWithRouterLogContext({ request, transaction: "match" }, () => {
@@ -205,7 +177,6 @@ export function createMatchHandlers<TEnv = any>(
 
           const result = await createMatchContextForFull(request, env);
 
-          // Handle redirect case
           if ("type" in result && result.type === "redirect") {
             if (hasTelemetry) {
               safeEmit(telemetry, {
@@ -284,7 +255,6 @@ export function createMatchHandlers<TEnv = any>(
               });
             }
             if (error instanceof Response) throw error;
-            // Report unhandled errors during full match pipeline
             callOnError(error, "routing", {
               request,
               url: ctx.url,
@@ -319,16 +289,6 @@ export function createMatchHandlers<TEnv = any>(
     );
   }
 
-  /**
-   * Match partial request with revalidation
-   *
-   * Uses generator middleware pipeline for clean separation of concerns:
-   * - cache-lookup: Check cache first
-   * - segment-resolution: Resolve segments on cache miss
-   * - intercept-resolution: Handle intercept routes
-   * - cache-store: Store results in cache
-   * - background-revalidation: SWR revalidation
-   */
   async function matchPartial(
     request: Request,
     context: TEnv,
@@ -448,7 +408,6 @@ export function createMatchHandlers<TEnv = any>(
                 });
               }
               if (error instanceof Response) throw error;
-              // Report unhandled errors during partial match pipeline
               callOnError(error, actionContext ? "action" : "revalidation", {
                 request,
                 url: ctx.url,
@@ -477,7 +436,5 @@ export function createMatchHandlers<TEnv = any>(
     matchPartial: matchPartial,
     matchError: matchError,
     previewMatch: previewMatch,
-    createMatchContextForFull: createMatchContextForFull,
-    createMatchContextForPartial: createMatchContextForPartial,
   };
 }

package/src/router/match-middleware/background-revalidation.ts

@@ -168,8 +168,6 @@ export function withBackgroundRevalidation<TEnv>(
       requestCtx._handleStore = createHandleStore();
 
       try {
-        // Create fresh handler context and loader promises to avoid
-        // reusing memoized results from the foreground pass
         const freshHandlerContext = createHandlerContext(
           ctx.matched.params,
           ctx.request,
@@ -185,10 +183,6 @@ export function withBackgroundRevalidation<TEnv>(
         const freshLoaderPromises = new Map<string, Promise<any>>();
         setupLoaderAccess(freshHandlerContext, freshLoaderPromises);
 
-        // Resolve all segments fresh (without revalidation logic)
-        // to ensure complete components for caching.
-        // Skip DSL loaders — they are never cached (cacheRoute filters them)
-        // and are always resolved fresh on each request.
         const freshSegments = await ctx.Store.run(() =>
           resolveAllSegments(
             ctx.entries,
@@ -200,7 +194,6 @@ export function withBackgroundRevalidation<TEnv>(
           ),
         );
 
-        // Also resolve intercept segments fresh if applicable
         let freshInterceptSegments: ResolvedSegment[] = [];
         if (ctx.interceptResult) {
           freshInterceptSegments = await ctx.Store.run(() =>

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

@@ -103,6 +103,7 @@ import {
   getRequestContext,
   _getRequestContext,
 } from "../../server/request-context.js";
+import { paramsEqual } from "../params-util.js";
 
 // Lazily initialized prerender store singleton and dynamically imported deps.
 // Dynamic imports prevent pulling in @vitejs/plugin-rsc/rsc virtual module at
@@ -124,22 +125,6 @@ let _lazyGetRequestContext:
   | typeof import("../../server/request-context.js").getRequestContext
   | undefined;
 
-function paramsEqual(
-  a: Record<string, string>,
-  b: Record<string, string>,
-): boolean {
-  if (a === b) return true;
-
-  const keysA = Object.keys(a);
-  if (keysA.length !== Object.keys(b).length) return false;
-
-  for (const key of keysA) {
-    if (a[key] !== b[key]) return false;
-  }
-
-  return true;
-}
-
 async function ensurePrerenderDeps() {
   if (!_deserializeSegments) {
     const [codec, snapshot, paramHash, reqCtx, store] = await Promise.all([
@@ -367,10 +352,6 @@ export function withCacheLookup<TEnv>(
       resolveLoadersOnly,
     } = getRouterContext<TEnv>();
 
-    // Prerender lookup: check build-time cached data before runtime cache.
-    // Prerender data is available regardless of runtime cache configuration.
-    // Skip for HMR requests — the dev prerender endpoint reads from a stale
-    // RouterRegistry snapshot; rendering fresh ensures edits are visible.
     const isHmr = !!ctx.request.headers.get("X-RSC-HMR");
     if (!ctx.isAction && !isHmr && ctx.matched.pr) {
       await ensurePrerenderDeps();
@@ -385,14 +366,6 @@ export function withCacheLookup<TEnv>(
       }
     }
 
-    // Dev-mode static handler interception for non-Node.js runtimes.
-    // __PRERENDER_DEV_URL is set by the Vite plugin when the RSC environment
-    // lacks a Node.js module runner (e.g. workerd, Deno workers). In those
-    // runtimes, handlers that depend on Node APIs like node:fs can't run
-    // in-process. We redirect them to the /__rsc_prerender endpoint which
-    // resolves segments in a Node.js temp server, same as prerender routes.
-    // In Node.js dev mode this variable is undefined -- handlers run
-    // in-process where Node APIs work, so no interception is needed.
     if (!ctx.isAction && !ctx.matched.pr && globalThis.__PRERENDER_DEV_URL) {
       const hasStatic = ctx.entries.some(
         (e) =>
@@ -415,9 +388,7 @@ export function withCacheLookup<TEnv>(
       }
     }
 
-    // Skip cache during actions
     if (ctx.isAction || !ctx.cacheScope?.enabled) {
-      // Cache miss - pass through to segment resolution
       yield* source;
       if (ms) {
         ms.metrics.push({
@@ -429,7 +400,6 @@ export function withCacheLookup<TEnv>(
       return;
     }
 
-    // Lookup cache
     const cacheResult = await ctx.cacheScope.lookupRoute(
       ctx.pathname,
       ctx.matched.params,
@@ -437,7 +407,6 @@ export function withCacheLookup<TEnv>(
     );
 
     if (!cacheResult) {
-      // Cache miss - pass through to segment resolution
       yield* source;
       if (ms) {
         ms.metrics.push({
@@ -449,16 +418,12 @@ export function withCacheLookup<TEnv>(
       return;
     }
 
-    // Cache HIT
     state.cacheHit = true;
     state.cacheSource = "runtime";
     state.shouldRevalidate = cacheResult.shouldRevalidate;
     state.cachedSegments = cacheResult.segments;
     state.cachedMatchedIds = cacheResult.segments.map((s) => s.id);
 
-    // Apply revalidation to cached segments.
-    // For full matches or empty client segment sets, this map is unnecessary:
-    // we never run segment-level revalidation and can stream segments directly.
     const canCheckSegmentRevalidation =
       !ctx.isFullMatch &&
       ctx.clientSegmentSet.size > 0 &&
@@ -468,7 +433,6 @@ export function withCacheLookup<TEnv>(
       : undefined;
 
     for (const segment of cacheResult.segments) {
-      // Skip segments client doesn't have - they need their component
       if (!ctx.clientSegmentSet.has(segment.id)) {
         if (isTraceActive()) {
           pushRevalidationTraceEntry({
@@ -485,19 +449,13 @@ export function withCacheLookup<TEnv>(
         continue;
       }
 
-      // Skip intercept segments - they're handled separately
       if (segment.namespace?.startsWith("intercept:")) {
         yield segment;
         continue;
       }
 
-      // Look up revalidation rules for this segment
       const entryInfo = entryRevalidateMap?.get(segment.id);
 
-      // Even without explicit revalidation rules, route segments and their
-      // children must re-render when params or search params change — the
-      // handler reads ctx.params/ctx.searchParams so different values produce
-      // different content. Matches evaluateRevalidation's default logic.
       const searchChanged = ctx.prevUrl.search !== ctx.url.search;
       const routeParamsChanged = !paramsEqual(
         ctx.matched.params,
@@ -511,7 +469,6 @@ export function withCacheLookup<TEnv>(
 
       if (!entryInfo || entryInfo.revalidate.length === 0) {
         if (shouldDefaultRevalidate) {
-          // Params or search params changed — must re-render even without custom rules
           if (isTraceActive()) {
             pushRevalidationTraceEntry({
               segmentId: segment.id,
@@ -528,7 +485,6 @@ export function withCacheLookup<TEnv>(
           yield segment;
           continue;
         }
-        // No revalidation rules, use default behavior (skip if client has)
         if (isTraceActive()) {
           pushRevalidationTraceEntry({
             segmentId: segment.id,
@@ -546,7 +502,6 @@ export function withCacheLookup<TEnv>(
         continue;
       }
 
-      // Evaluate revalidation rules
       const shouldRevalidate = await evaluateRevalidation({
         segment,
         prevParams: ctx.prevParams,
@@ -580,7 +535,6 @@ export function withCacheLookup<TEnv>(
       }
 
       if (!shouldRevalidate) {
-        // Client has it, no revalidation needed
         segment.component = null;
         segment.loading = undefined;
       }
@@ -588,7 +542,6 @@ export function withCacheLookup<TEnv>(
       yield segment;
     }
 
-    // Set streaming flag (once) and resolve render barrier.
     const barrierReqCtx = _getRequestContext();
     if (barrierReqCtx) {
       if (barrierReqCtx._treeHasStreaming === undefined) {
@@ -597,22 +550,17 @@ export function withCacheLookup<TEnv>(
       barrierReqCtx._resolveRenderBarrier(cacheResult.segments);
     }
 
-    // Resolve loaders fresh (loaders are NOT cached by default)
-    // This ensures fresh data even on cache hit
     const Store = ctx.Store;
     const loaderStart = performance.now();
 
     if (ctx.isFullMatch) {
-      // Full match (document request) - simple loader resolution without revalidation
       if (resolveLoadersOnly) {
         const loaderSegments = await Store.run(() =>
           resolveLoadersOnly(ctx.entries, ctx.handlerContext),
         );
 
-        // Update state - full match doesn't track matchedIds separately
         state.matchedIds = state.cachedMatchedIds!;
 
-        // Yield fresh loader segments
         for (const segment of loaderSegments) {
           yield segment;
         }
@@ -620,7 +568,6 @@ export function withCacheLookup<TEnv>(
         state.matchedIds = state.cachedMatchedIds!;
       }
     } else {
-      // Partial match (navigation) - loader resolution with revalidation
       if (resolveLoadersOnlyWithRevalidation) {
         const loaderResult = await Store.run(() =>
           resolveLoadersOnlyWithRevalidation(

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

@@ -123,21 +123,14 @@ export function withCacheStore<TEnv>(
   ): AsyncGenerator<ResolvedSegment> {
     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;
     }
 
-    // Measure own work only (after source iteration completes)
     const ownStart = performance.now();
 
-    // 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)
     if (
       !ctx.cacheScope?.enabled ||
       ctx.isAction ||
@@ -162,13 +155,8 @@ export function withCacheStore<TEnv>(
       createHandleStore,
     } = getRouterContext<TEnv>();
 
-    // Combine main segments with intercept segments
     const allSegmentsToCache = [...allSegments, ...state.interceptSegments];
 
-    // Check if any non-loader segments have null components from revalidation
-    // skip (client already had them). Segments where the handler intentionally
-    // returned null are not revalidation skips — re-rendering them will still
-    // produce null, so proactive caching would be wasted work.
     const hasNullComponents = allSegmentsToCache.some(
       (s) =>
         s.component === null &&
@@ -184,10 +172,7 @@ export function withCacheStore<TEnv>(
       ? getOrCreateRequestId(ctx.request)
       : undefined;
 
-    // Register onResponse callback to skip caching for non-200 responses
-    // Note: error/notFound status codes are set elsewhere (not caching-specific)
     requestCtx.onResponse((response) => {
-      // Only cache successful responses
       if (response.status !== 200) {
         debugLog("cacheStore", "skipping cache for non-200 response", {
           status: response.status,
@@ -197,10 +182,7 @@ 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 () => {
-          // Prevent background metrics from polluting foreground timeline.
           const savedMetrics = ctx.Store.metrics;
           ctx.Store.metrics = undefined;
 
@@ -208,15 +190,9 @@ export function withCacheStore<TEnv>(
           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,
@@ -231,12 +207,8 @@ 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.
-            // Skip DSL loaders — they are never cached (cacheRoute filters them)
-            // and are always resolved fresh on each request.
             const Store = ctx.Store;
             const freshSegments = await Store.run(() =>
               resolveAllSegments(
@@ -249,7 +221,6 @@ export function withCacheStore<TEnv>(
               ),
             );
 
-            // Also resolve intercept segments fresh if applicable
             let freshInterceptSegments: ResolvedSegment[] = [];
             if (ctx.interceptResult) {
               freshInterceptSegments = await Store.run(() =>
@@ -301,8 +272,6 @@ export function withCacheStore<TEnv>(
           }
         });
       } 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})`,

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

@@ -125,17 +125,14 @@ export function withInterceptResolution<TEnv>(
   ): AsyncGenerator<ResolvedSegment> {
     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;
     }
 
-    // Measure own work only (after source iteration completes)
     const ownStart = performance.now();
 
-    // Skip intercept resolution for full match (document requests don't have intercepts)
     if (ctx.isFullMatch) {
       if (ms) {
         ms.metrics.push({
@@ -147,18 +144,12 @@ export function withInterceptResolution<TEnv>(
       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);
       }
@@ -172,7 +163,6 @@ export function withInterceptResolution<TEnv>(
       return;
     }
 
-    // Resolve intercept segments
     const { resolveInterceptEntry } = getRouterContext<TEnv>();
 
     const slotName = ctx.interceptResult!.intercept.slotName;
@@ -181,7 +171,6 @@ export function withInterceptResolution<TEnv>(
       slotName,
     });
 
-    // Resolve intercept entry (middleware, loaders, handler)
     const Store = ctx.Store;
     const interceptSegments = await Store.run(() =>
       resolveInterceptEntry(
@@ -203,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;
     }
@@ -225,11 +212,6 @@ export function withInterceptResolution<TEnv>(
   };
 }
 
-/**
- * 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,
@@ -241,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(() =>
@@ -271,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

@@ -93,12 +93,6 @@ import type { MatchContext, MatchPipelineState } from "../match-context.js";
 import { getRouterContext } from "../router-context.js";
 import type { GeneratorMiddleware } from "./cache-lookup.js";
 
-/**
- * Check whether any entry in the tree uses loading() (streaming).
- * Matches the router's streaming semantics in fresh.ts: streaming is
- * enabled when `loading` is defined AND not `false`. `loading: false`
- * explicitly disables streaming; `undefined` means no loading at all.
- */
 export function treeHasStreaming(entries: EntryData[]): boolean {
   for (const entry of entries) {
     if (
@@ -130,12 +124,6 @@ export function treeHasStreaming(entries: EntryData[]): boolean {
   return false;
 }
 
-/**
- * Creates segment resolution middleware
- *
- * Only runs on cache miss (state.cacheHit === false).
- * Uses resolveAllSegmentsWithRevalidation from RouterContext to resolve segments.
- */
 export function withSegmentResolution<TEnv>(
   ctx: MatchContext<TEnv>,
   state: MatchPipelineState,
@@ -145,17 +133,12 @@ export function withSegmentResolution<TEnv>(
   ): AsyncGenerator<ResolvedSegment> {
     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;
     }
 
-    // Measure own work only (after source iteration completes)
     const ownStart = performance.now();
 
-    // If cache hit, segments were already yielded by cache lookup
-    // (render barrier is resolved on the cache-hit path)
     if (state.cacheHit) {
       if (ms) {
         ms.metrics.push({
@@ -178,7 +161,6 @@ export function withSegmentResolution<TEnv>(
     const Store = ctx.Store;
 
     if (ctx.isFullMatch) {
-      // Full match (document request) - simple resolution without revalidation
       const segments = await Store.run(() =>
         resolveAllSegments(
           ctx.entries,
@@ -189,15 +171,12 @@ export function withSegmentResolution<TEnv>(
         ),
       );
 
-      // Update state with resolved segments
       state.segments = segments;
       state.matchedIds = segments.map((s: { id: string }) => s.id);
 
       if (reqCtx) {
         reqCtx._resolveRenderBarrier(segments);
       }
-
-      // Yield all resolved segments
       for (const segment of segments) {
         yield segment;
       }

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());
 }