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

package/src/browser/rsc-router.tsx

@@ -22,6 +22,7 @@ import type {
 import type { EventController } from "./event-controller.js";
 import type { ResolvedThemeConfig, Theme } from "../theme/types.js";
 import { initRangoState } from "./rango-state.js";
+import { registerNavigationStore } from "./navigation-store-handle.js";
 import { initPrefetchCache } from "./prefetch/cache.js";
 import { setPrefetchDecoder } from "./prefetch/fetch.js";
 import { setAppVersion } from "./app-version.js";
@@ -175,6 +176,12 @@ export async function initBrowserApp(
     ...(storeOptions?.cacheSize && { cacheSize: storeOptions.cacheSize }),
   });
 
+  // Register the active store on the module-level handle and wire the
+  // jar-divergence observer before any getRangoState() read can detect a
+  // cross-tab/server rotation. There is no global store singleton, so this
+  // handle is the live reference.
+  registerNavigationStore(store);
+
   // Seed router identity from the initial SSR payload so the first
   // cross-app SPA navigation can detect the app switch.
   if (initialPayload.metadata?.routerId) {
@@ -228,10 +235,11 @@ export async function initBrowserApp(
     version,
   });
 
-  // Initialize the localStorage state key for cache invalidation.
-  // The build version busts cached prefetches on deploy; the routerId
-  // namespaces the key so sibling apps on the same origin don't collide.
-  initRangoState(version ?? "0", initialPayload.metadata?.routerId);
+  // Initialize the rango state cookie for cache invalidation. The build version
+  // busts cached prefetches on deploy; the server-resolved cookie name
+  // namespaces the cookie so sibling apps on the same origin don't collide
+  // (falls back to the bare default prefix if metadata lacks the name).
+  initRangoState(version ?? "0", initialPayload.metadata?.stateCookieName);
   setAppVersion(version);
 
   // Initialize the in-memory prefetch cache TTL from server config.

package/src/browser/server-action-bridge.ts

@@ -4,6 +4,8 @@ import type {
   RscPayload,
 } from "./types.js";
 import { createPartialUpdater } from "./partial-update.js";
+import { enterActionFence, exitActionFence } from "./action-fence.js";
+import { KEEP_CACHE_HEADER } from "./cookie-name.js";
 import { createNavigationTransaction } from "./navigation-transaction.js";
 import {
   reconcileSegments,
@@ -156,12 +158,40 @@ export function createServerActionBridge(
 
     // Start action in event controller - handles lifecycle tracking
     const handle = eventController.startAction(id, args);
+    // Whether the action's response carried the keepClientCache() directive.
+    // Set when the response arrives; gates the deferred invalidation below.
+    let keepCache = false;
+    // Single deferred invalidation + fence release, run exactly ONCE however the
+    // action terminates (normal, redirect, error, abort, intercept, concurrent).
+    // This replaces main's eager clear at action start: every directive-free
+    // action invalidates once; keepClientCache() suppresses only the automatic
+    // invalidation, so a concurrent directive-free action still invalidates via
+    // its own latch. Latched so the finally AND the early SPA-redirect returns
+    // (whose Flight stream never settles) can both call it safely.
+    let actionFinalized = false;
+    // skipInvalidation: the version-mismatch reload terminal released nothing
+    // server-side, so it releases the fence without invalidating.
+    const finalizeAction = (skipInvalidation = false): void => {
+      if (actionFinalized) return;
+      actionFinalized = true;
+      // finally so a throw in invalidation cannot leak the fence (latch is set).
+      try {
+        if (!keepCache && !skipInvalidation) {
+          store.markCacheAsStaleAndBroadcast();
+        }
+      } finally {
+        exitActionFence();
+      }
+    };
     try {
       const segmentState = store.getSegmentState();
 
-      // Mark cache as stale immediately when action starts
-      // This ensures SWR pattern kicks in if user navigates away during action
-      store.markCacheAsStaleAndBroadcast();
+      // Raise the action fence (replaces the old eager clear). Nothing is wiped,
+      // rotated, or broadcast yet: navigations during the flight fetch fresh
+      // (no-store) and popstate is treated as SWR, but the decision to
+      // invalidate is deferred to the response so a no-op action (keepClientCache)
+      // can leave the caches and the jar untouched.
+      enterActionFence();
 
       // Create temporary references for serialization
       const temporaryReferences = deps.createTemporaryReferenceSet();
@@ -237,11 +267,22 @@ export function createServerActionBridge(
         // abortAllActions() doesn't disrupt the in-progress Flight stream.
         handle.signal.removeEventListener("abort", onHandleAbort);
 
+        // Did the action call keepClientCache()? If so the deferred invalidation
+        // below is suppressed for THIS action (a concurrent directive-free
+        // action still invalidates via its own response).
+        keepCache = response.headers.get(KEEP_CACHE_HEADER) === "1";
+
         // Check for version mismatch - server wants us to reload
         const reloadResult = handleReloadHeader(response, {
           onBlocked: resolveStreamComplete,
-          onReload: (url) =>
-            log("version mismatch on action, reloading", { reloadUrl: url }),
+          onReload: (url) => {
+            log("version mismatch on action, reloading", { reloadUrl: url });
+            // Never-settling terminal (navigates away), so the finally never
+            // runs: release the fence here. skipInvalidation — the mismatch
+            // short-circuits the action server-side, so nothing mutated and a
+            // broadcast would only risk hard-reloading a sibling mid-task.
+            finalizeAction(true);
+          },
         });
         if (reloadResult) return reloadResult;
 
@@ -253,6 +294,10 @@ export function createServerActionBridge(
         if (redirect && redirect !== "blocked" && !handle.signal.aborted) {
           log("action simple redirect", { url: redirect.url });
           handle.complete(undefined);
+          // This path returns a never-settling promise, so the finally never
+          // runs: invalidate + release the fence here (the mutation committed
+          // and we're navigating away). Latched, so the finally is a no-op.
+          finalizeAction();
           await dispatchRedirect(redirect.url);
           return new Promise<Response>(() => {});
         }
@@ -277,6 +322,9 @@ export function createServerActionBridge(
           log("action router id mismatch, reloading to re-sync");
           handle.complete(undefined);
           resolveStreamComplete();
+          // Never-settling return: release the fence before the reload (the
+          // reload resets module state anyway, but stay balanced). Latched.
+          finalizeAction();
           window.location.reload();
           return new Promise<Response>(() => {});
         }
@@ -542,8 +590,9 @@ export function createServerActionBridge(
           handle.clearConsolidation();
 
           if (scenario.historyKeyChanged) {
-            if (!scenario.onInterceptRoute) {
-              store.markCacheAsStaleAndBroadcast();
+            // Invalidation is deferred to finalizeAction(); here we only trigger
+            // the revalidation refetch of the new route (suppressed on keep).
+            if (!scenario.onInterceptRoute && !keepCache) {
               refetchRoute().catch((error) => {
                 if (isBackgroundSuppressible(error)) return;
                 console.error(
@@ -555,11 +604,14 @@ export function createServerActionBridge(
             break;
           }
 
-          // Same history key but different pathname - safe to refetch current route
-          store.markCacheAsStaleAndBroadcast();
-          await refetchRoute({
-            interceptSourceUrl: store.getInterceptSourceUrl(),
-          });
+          // Same history key but different pathname - safe to refetch current
+          // route. Invalidation is deferred to finalizeAction(); here we only
+          // trigger the revalidation refetch (suppressed on keep).
+          if (!keepCache) {
+            await refetchRoute({
+              interceptSourceUrl: store.getInterceptSourceUrl(),
+            });
+          }
           break;
         }
 
@@ -567,8 +619,11 @@ export function createServerActionBridge(
           console.warn(
             `[Browser] Missing segments after action (HMR detected), refetching...`,
           );
+          // Repair (not revalidation), so ungated on keepCache: a keep action
+          // resolving last must discharge a directive-free sibling's repair.
+          // See the keep row in docs/design/rango-state-cookie.md (the all-keep
+          // edge, and the benign re-mark-stale-after-refetch end-state delta).
           await refetchRoute({ interceptSourceUrl });
-          store.broadcastCacheInvalidation();
           break;
         }
 
@@ -585,11 +640,11 @@ export function createServerActionBridge(
           // Clear consolidation tracking before fetch
           handle.clearConsolidation();
 
+          // Ungated on keepCache, same as hmr-missing above (see the keep row).
           await refetchRoute({
             segments: segmentsToSend,
             interceptSourceUrl,
           });
-          store.broadcastCacheInvalidation();
           break;
         }
 
@@ -653,7 +708,9 @@ export function createServerActionBridge(
             fullSegments,
             currentHandleData,
           );
-          store.markCacheAsStaleAndBroadcast();
+          // Invalidation deferred to finalizeAction() (runs after this caches
+          // the fresh segments), suppressed when the action called
+          // keepClientCache().
           break;
         }
       }
@@ -661,6 +718,11 @@ export function createServerActionBridge(
       handle.complete(returnData);
       return returnData;
     } finally {
+      // The single deferred invalidation + fence release for this action. Runs
+      // for every terminal that settles (normal, navigated-away, error, abort,
+      // intercept, concurrent); the SPA-redirect paths above already ran it.
+      // Latched, so it fires exactly once.
+      finalizeAction();
       handle[Symbol.dispose]();
     }
   }

package/src/browser/types.ts

@@ -14,7 +14,6 @@ import type { RenderSegmentsOptions } from "../segment-system.js";
 export interface RscPayload<TMetadata = RscMetadata> {
   metadata?: TMetadata;
   returnValue?: ActionResult;
-  formState?: unknown;
 }
 
 /**
@@ -71,6 +70,12 @@ export interface RscMetadata {
    * Sent on initial render so the browser can configure its cache duration.
    */
   prefetchCacheTTL?: number;
+  /**
+   * Server-resolved rango state cookie name (`{prefix}_{routerId}`). The client
+   * reads it verbatim and binds the rango state cookie to it; composition
+   * happens only server-side.
+   */
+  stateCookieName?: string;
   /**
    * Theme configuration from router.
    * Included when theme is enabled in router config.
@@ -433,9 +438,9 @@ export interface NavigationStore {
   hasHistoryCache(historyKey: string): boolean;
   updateCacheHandleData(historyKey: string, handleData: HandleData): void;
   markCacheAsStale(): void;
+  markHistoryCacheStale(): void;
   markCacheAsStaleAndBroadcast(): void;
   clearHistoryCache(): void;
-  broadcastCacheInvalidation(): void;
 
   // Cross-tab refresh callback (set by navigation bridge)
   setCrossTabRefreshCallback(callback: () => void): void;

package/src/browser/validate-redirect-origin.ts

@@ -17,11 +17,10 @@ export function validateRedirectOrigin(
       );
       return null;
     }
-    // Return pathname+search+hash for relative inputs, full href for absolute.
-    // This normalizes protocol-relative and other ambiguous forms.
-    return target.href.startsWith(currentOrigin)
-      ? target.href
-      : target.pathname + target.search + target.hash;
+    // Origin matched above, so target.href is same-origin: return the
+    // canonical full href. This normalizes protocol-relative and other
+    // ambiguous forms.
+    return target.href;
   } catch {
     console.error(`[rango] Redirect blocked: invalid URL "${url}"`);
     return null;

package/src/build/route-trie.ts

@@ -63,6 +63,9 @@ export interface TrieNode {
  * @param routeAncestry - Map of route name to ancestry shortCodes
  * @param routeToStaticPrefix - Map of route name to its entry's staticPrefix
  * @param routeTrailingSlash - Optional map of route name to trailing slash mode
+ * @param prerenderRouteNames - Optional set of prerendered route names (sets leaf.pr)
+ * @param passthroughRouteNames - Optional set of passthrough route names (sets leaf.pt)
+ * @param responseTypeRoutes - Optional map of route name to response type (sets leaf.rt)
  */
 export function buildRouteTrie(
   routeManifest: Record<string, string>,

package/src/build/route-types/param-extraction.ts

@@ -37,12 +37,15 @@ export function formatRouteEntry(
 ): string {
   const hasSearch = search && Object.keys(search).length > 0;
 
+  // JSON.stringify the pattern and search values so backslashes and quotes in a
+  // route pattern (e.g. a custom regex constraint) survive interpolation into
+  // both the type-level string and the runtime NamedRoutes value.
   if (!hasSearch) {
-    return `  ${key}: "${pattern}",`;
+    return `  ${key}: ${JSON.stringify(pattern)},`;
   }
 
   const searchBody = Object.entries(search!)
-    .map(([k, v]) => `${k}: "${v}"`)
+    .map(([k, v]) => `${k}: ${JSON.stringify(v)}`)
     .join(", ");
-  return `  ${key}: { path: "${pattern}", search: { ${searchBody} } },`;
+  return `  ${key}: { path: ${JSON.stringify(pattern)}, search: { ${searchBody} } },`;
 }

package/src/build/route-types/router-processing.ts

@@ -617,9 +617,6 @@ export function writeCombinedRouteTypes(
       ? readFileSync(outPath, "utf-8")
       : null;
 
-    // When the static parser can't extract routes (e.g. callback-style urls()),
-    // write an empty placeholder so the build-time transform's injected import
-    // resolves. Runtime discovery will overwrite this with the real routes.
     if (Object.keys(result.routes).length === 0) {
       if (!existing) {
         const emptySource = generateRouteTypesSource({});
@@ -635,11 +632,6 @@ export function writeCombinedRouteTypes(
       hasSearchSchemas ? result.searchSchemas : undefined,
     );
     if (existing !== source) {
-      // On initial dev startup, don't overwrite a file from runtime discovery
-      // (which has all dynamic routes) with a smaller set from the static
-      // parser. The static parser can't see routes generated by Array.from()
-      // or other dynamic code. During HMR (file watcher), always write so
-      // newly added routes appear immediately.
       if (opts?.preserveIfLarger && existing) {
         const existingCount = countPublicRouteEntries(existing);
         const newCount = Object.keys(result.routes).filter(

package/src/cache/cache-policy.ts

@@ -69,24 +69,6 @@ export function computeExpiration(
   return { staleAt, expiresAt };
 }
 
-// ============================================================================
-// Cache Key Resolution
-// ============================================================================
-
-/**
- * Resolve cache key using the 3-tier priority:
- * 1. keyFn (full override from route/loader cache options)
- * 2. store.keyGenerator (modifies default key)
- * 3. defaultKey (used when neither keyFn nor keyGenerator is provided)
- *
- * Errors from keyFn and store.keyGenerator propagate to the caller.
- * Cache identity is correctness-critical: if explicit key logic throws,
- * silently remapping to a different key could cause cache collisions or
- * serve stale/wrong data. Callers must handle the error or let it surface.
- *
- * Uses _getRequestContext (non-throwing) so that calls outside ALS
- * (e.g. build-time) gracefully fall back to defaultKey.
- */
 export async function resolveCacheKey(
   keyFn: ((ctx: RequestContext) => string | Promise<string>) | undefined,
   store: SegmentCacheStore | null,
@@ -95,34 +77,17 @@ export async function resolveCacheKey(
 ): Promise<string> {
   const requestCtx = _getRequestContext();
 
-  // Priority 1: Route/loader-level key function (full override)
   if (keyFn && requestCtx) {
     return await keyFn(requestCtx);
   }
 
-  // Priority 2: Store-level keyGenerator (modifies default key)
   if (store?.keyGenerator && requestCtx) {
     return await store.keyGenerator(requestCtx, defaultKey);
   }
 
-  // Priority 3: Default key (no custom key logic provided)
   return defaultKey;
 }
 
-// ============================================================================
-// Cache Tag Resolution
-// ============================================================================
-
-/**
- * Resolve cache tags from a tags option (static array or function of ctx).
- *
- * Fails open: a thrown tag callback falls back to no tags rather than
- * aborting the request. Tags are additive metadata (not identity), so a
- * missing tag does not cause cache collisions, only a missed invalidation.
- *
- * Shared by the cache() DSL (cache-scope) and loader caching (loader-cache)
- * so tag resolution behaves identically across every cache axis.
- */
 export function resolveTagsOption<TEnv>(
   tags: string[] | ((ctx: RequestContext<TEnv>) => string[]) | undefined,
   ctx: RequestContext<TEnv> | undefined,
@@ -131,10 +96,6 @@ export function resolveTagsOption<TEnv>(
   if (!tags) return undefined;
   if (typeof tags === "function") {
     if (!ctx) {
-      // A dynamic tags function needs the request context to run. Without it
-      // (e.g. resolved outside a request, at build/prerender time) the entry is
-      // cached UNTAGGED and can never be invalidated - surface that rather than
-      // silently dropping the tags, matching the thrown-callback branch below.
       console.warn(
         `[${label}] Dynamic tags function present but no request context; ` +
           `caching without tags (this entry will not be tag-invalidatable).`,
@@ -167,25 +128,10 @@ function normalizeTagList(tags: string[]): string[] | undefined {
   return out.length > 0 ? out : undefined;
 }
 
-// ============================================================================
-// Cache Store Resolution
-// ============================================================================
-
-/**
- * Resolve cache store from the 2-tier priority:
- * 1. Explicit store from cache options
- * 2. App-level store from request context
- */
 export function resolveCacheStore(
   explicitStore: SegmentCacheStore | undefined,
 ): SegmentCacheStore | null {
   if (explicitStore) {
-    // Register explicit per-scope stores so updateTag()/revalidateTag() can
-    // reach them. This is the single chokepoint every cache axis (segment,
-    // response, loader) resolves through, so registering here covers them all
-    // eagerly - no dependence on whether a tagged write has happened yet. The
-    // app-level store is intentionally not registered (always reachable via
-    // ctx._cacheStore).
     registerExplicitTaggedStore(explicitStore);
     return explicitStore;
   }

package/src/cache/cache-runtime.ts

@@ -46,6 +46,7 @@ import {
   runWithCacheTagScope,
 } from "./cache-tag.js";
 import { reportCacheError } from "./cache-error.js";
+import type { CacheItemResult } from "./types.js";
 
 /**
  * Convert encodeReply result to a stable string key.
@@ -84,6 +85,11 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     // cacheTag() call inside the function degrades to a no-op rather than
     // throwing "must be called inside a use cache function" - adopting cacheTag()
     // must not hard-fail in apps/tests without an item-capable cache configured.
+    // Note: the INSIDE_CACHE_EXEC guard (cookies()/headers()/ctx.set() rejection)
+    // is intentionally NOT stamped here. It is a cached-path-only check; in the
+    // bypass the body actually executes, so the guarded side effects take effect
+    // and nothing is lost on a (non-existent) hit. Same applies to the
+    // non-serializable-args bypass below.
     if (!store?.getItem) {
       const scoped = runWithCacheTagScope(() => fn.apply(this, args));
       const result = await scoped.result;
@@ -185,23 +191,29 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     // Cache lookup
     const cached = await store.getItem(cacheKey);
 
+    // Serve a cached entry on the hit path: deserialize the stored value,
+    // replay handle data (gated on tainted args), and surface the entry's tags
+    // to the request set (the function did not re-run, so its runtime cacheTag()
+    // tags are only available from the stored entry). Shared by the fresh-hit
+    // and stale-hit branches; the only divergence is the stale branch scheduling
+    // background revalidation, which it does after this returns.
+    const serveCached = async (entry: CacheItemResult): Promise<any> => {
+      const result = await deserializeResult(entry.value);
+      if (entry.handles && hasTaintedArgs) {
+        const handleStore = requestCtx?._handleStore;
+        if (handleStore) {
+          const r = await decodeHandles(entry.handles);
+          if (r) restoreHandles(r, handleStore);
+        }
+      }
+      recordRequestTags(entry.tags, requestCtx);
+      return result;
+    };
+
     if (cached && !cached.shouldRevalidate) {
       // Fresh hit: deserialize and return
       try {
-        const result = await deserializeResult(cached.value);
-        // Restore handle data if present
-        if (cached.handles && hasTaintedArgs) {
-          const handleStore = requestCtx?._handleStore;
-          if (handleStore) {
-            const r = await decodeHandles(cached.handles);
-            if (r) restoreHandles(r, handleStore);
-          }
-        }
-        // Surface the hit's tags to the request set so a document built from a
-        // cached item is still tagged (the function did not re-run, so its
-        // runtime cacheTag() tags are only available from the stored entry).
-        recordRequestTags(cached.tags, requestCtx);
-        return result;
+        return await serveCached(cached);
       } catch (error) {
         // The stored value is corrupt/partial (failed RSC deserialize). Report
         // it, then fall through to fresh execution - the miss path below re-runs
@@ -217,16 +229,7 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     if (cached?.shouldRevalidate) {
       // Stale hit: return stale value, revalidate in background
       try {
-        const result = await deserializeResult(cached.value);
-        if (cached.handles && hasTaintedArgs) {
-          const handleStore = requestCtx?._handleStore;
-          if (handleStore) {
-            const r = await decodeHandles(cached.handles);
-            if (r) restoreHandles(r, handleStore);
-          }
-        }
-        // Tag the request with the stale entry's tags (see fresh-hit note).
-        recordRequestTags(cached.tags, requestCtx);
+        const result = await serveCached(cached);
         // Background revalidation — must capture handles if tainted args present.
         // Use an isolated handle store so background pushes don't pollute the
         // live response or throw LateHandlePushError on the completed store.

package/src/cache/cache-scope.ts

@@ -34,12 +34,6 @@ import {
 } from "./cache-policy.js";
 import type { RequestContext } from "../server/request-context.js";
 
-/**
- * Resolve tags for a cache() boundary from its config (static array or
- * function of ctx). Thin wrapper over the shared resolveTagsOption so the
- * cache() DSL and loader caching resolve tags identically.
- * @internal
- */
 export function resolveCacheTags(
   config: PartialCacheOptions | false,
   ctx: RequestContext | undefined,
@@ -54,17 +48,6 @@ function debugCacheLog(message: string): void {
   }
 }
 
-// ============================================================================
-// Key Generation (internal)
-// ============================================================================
-
-/**
- * Generate cache key base from host, pathname, route params, and search params.
- * Host is included to prevent cross-host cache collisions on shared stores.
- * Route params and search params are sorted alphabetically for deterministic keys.
- * Internal _rsc* and __* query params are excluded.
- * @internal
- */
 function getCacheKeyBase(
   host: string,
   pathname: string,
@@ -80,16 +63,6 @@ function getCacheKeyBase(
   return key;
 }
 
-/**
- * Generate default cache key for a route request.
- * Includes pathname, route params, and user-facing search params for
- * correct scoping. Internal _rsc* params are excluded.
- * Includes request type prefix since they produce different segment sets:
- * - doc: document requests (full page load)
- * - partial: navigation requests (client-side navigation)
- * - intercept: intercept navigation (modal/overlay routes)
- * @internal
- */
 function getDefaultRouteCacheKey(
   pathname: string,
   params?: Record<string, string>,

package/src/cache/cache-tag.ts

@@ -18,35 +18,11 @@ import {
 
 const cacheTagStorage = new AsyncLocalStorage<Set<string>>();
 
-/**
- * Normalize a tag for storage.
- *
- * Returns the tag unchanged if usable, or null if it is empty/whitespace-only
- * (dropped consistently in every environment - an empty tag matches nothing).
- *
- * Backend-specific constraints are intentionally NOT enforced here so the tag
- * primitive stays backend-agnostic. In particular, the CFCacheStore
- * encodeURIComponent's tags at serialization time so commas/spaces/non-Latin1
- * characters cannot corrupt the comma-delimited Cloudflare Cache-Tag header or
- * the HTTP marker header (it does not reject them). Keep tags short and
- * low-cardinality: a tag's KV marker key must stay under Cloudflare's 512-byte
- * limit, and a Cache-Tag value under 1024 bytes. The in-memory store has no
- * such limitations.
- *
- * @internal
- */
 export function normalizeTag(tag: string): string | null {
   if (!tag || !tag.trim()) return null;
   return tag;
 }
 
-/**
- * Normalize a tag collection: drop empty/whitespace-only tags so the WRITE path
- * matches the invalidate path (updateTag/revalidateTag/cacheTag all normalize).
- * Does not deduplicate - callers that need that wrap with a Set.
- *
- * @internal
- */
 export function normalizeTags(tags: Iterable<string>): string[] {
   const out: string[] = [];
   for (const tag of tags) {
@@ -89,19 +65,6 @@ export function cacheTag(...tags: string[]): void {
   }
 }
 
-/**
- * Record `tags` into the request-scoped tag set (ctx._requestTags), the union of
- * every cache tag resolved while producing the response. The document cache reads
- * this after the render settles so a full-page entry is tagged with everything its
- * content used, making it invalidatable by updateTag()/revalidateTag().
- *
- * Called at the tag-resolution sites: "use cache" stores (cache-runtime, both the
- * miss and read/hit paths), loader cache (cache-policy/loader-cache), and segment
- * cache() (cache-scope). Writes the field directly (not via ctx.set()) so it does
- * not trip the cache-scope side-effect guard, mirroring cacheTag() itself.
- *
- * @internal
- */
 export function recordRequestTags(
   tags: Iterable<string> | undefined,
   ctx: RequestContext | undefined = _getRequestContext(),