@rangojs/router 0.0.0-experimental.143 → 0.0.0-experimental.145

package/skills/use-cache/SKILL.md

@@ -153,6 +153,13 @@ const locale = cookies().get("locale")?.value ?? "en";
 const data = await getCachedData(locale); // locale is now in the cache key
 ```
 
+The guard does not reach into LOADER bodies consumed inside the cached
+function (`await ctx.use(loader)`): loaders always run fresh, so their reads
+are exempt — but the CONSUMED VALUE is captured into the shared cache entry
+like any other computed data. Same rule across `cache()` and the PPR shell:
+handler/cached-scope consumption = baked copy, client-side `useLoader` = live
+(the consumption-lane rule, `/rango` → Invariants).
+
 ### Side-Effect Guards
 
 These ctx methods **throw** inside a `"use cache"` function because their effects
@@ -346,8 +353,11 @@ export async function getProducts() {
 Writes to the same `SegmentCacheStore` as `cache()` DSL, `Static()`, and `Prerender()`.
 One store, one configuration.
 
-Cache entries (and `cacheProfiles`) can be tagged via `cache({ tags })` or, inside
-a `"use cache"` function, runtime `cacheTag(...tags)`. The built-in
+Cache entries (and `cacheProfiles`) can be tagged via `cache({ tags })` or runtime
+`cacheTag(...tags)`. `cacheTag` has two forms: inside a `"use cache"` function it
+tags that entry; called during a request render outside `"use cache"` it tags the
+request's document/shell artifact (rides `_requestTags`) instead of throwing. The
+built-in
 `MemorySegmentCacheStore` and `CFCacheStore` index by tag. Invalidate on demand
 with `updateTag(...tags)` (awaitable, read-your-own-writes; for server actions) or
 `revalidateTag(...tags)` (background, non-blocking; for route handlers/webhooks).

package/src/browser/logging.ts

@@ -63,3 +63,21 @@ export function debugLog(msg: string, ...args: unknown[]): void {
     console.log(msg, ...args);
   }
 }
+
+/**
+ * Boot-sequence debug log: one line per initial-document step (flight decode,
+ * handle stream, bridge wiring, initial tree build, hydration commit), each
+ * stamped with performance.now() so the gap BEFORE hydrateRoot is visible.
+ * The initial document path was otherwise silent — FE debug only started
+ * talking at the first soft navigation, so a boot stall (e.g. an await that
+ * holds initBrowserApp, and with it hydrateRoot) was invisible.
+ */
+export function bootLog(step: string, details?: Record<string, unknown>): void {
+  if (!INTERNAL_RANGO_DEBUG) return;
+  const prefix = `[Browser][boot] ${step} @ ${Math.round(performance.now())}ms`;
+  if (details) {
+    console.log(prefix, details);
+    return;
+  }
+  console.log(prefix);
+}

package/src/browser/partial-update.ts

@@ -395,6 +395,13 @@ export function createPartialUpdater(
           return;
         }
         if (mode.type === "action") {
+          // An action refetch that lands on missing segments (navigated away /
+          // consolidation / HMR) drops rather than refetch-all: the action flow
+          // is storeOnly / skipLoadingState, so a full refetch here would fight
+          // it. Keep the stale-but-consistent tree; log so the drop is visible.
+          debugLog(
+            `[Browser] Action refetch: ${missingCount} segments missing; dropping (stale-but-consistent tree kept).`,
+          );
           return;
         }
         console.warn(

package/src/browser/rsc-router.tsx

@@ -33,6 +33,7 @@ import {
   splitInterceptSegments,
 } from "./intercept-utils.js";
 import { createAppShellRef } from "./app-shell.js";
+import { bootLog, IS_BROWSER_DEBUG } from "./logging.js";
 
 // Vite HMR types are provided by vite/client
 
@@ -156,6 +157,8 @@ export async function initBrowserApp(
     initialTheme,
   } = options;
 
+  bootLog("initBrowserApp start");
+  bootLog("flight decode: awaiting initial payload from document stream");
   const initialPayload =
     await deps.createFromReadableStream<RscPayload>(rscStream);
 
@@ -169,6 +172,14 @@ export async function initBrowserApp(
   // Get initial segments and compute history key from current URL
   const initialSegments = (initialPayload.metadata?.segments ??
     []) as ResolvedSegment[];
+  if (IS_BROWSER_DEBUG) {
+    bootLog("initial payload decoded", {
+      version: initialPayload.metadata?.version,
+      routerId: initialPayload.metadata?.routerId,
+      segments: initialSegments.map((s) => s.id),
+      matched: initialPayload.metadata?.matched,
+    });
+  }
   const initialHistoryKey = generateHistoryKey(window.location.href);
 
   // Create navigation store with history-based caching
@@ -207,11 +218,24 @@ export async function initBrowserApp(
   // This ensures useHandle returns correct data during hydration to avoid mismatch
   // The handles property is an async generator that yields on each push
   if (initialPayload.metadata?.handles) {
+    // This for-await consumes the handle generator to completion BEFORE
+    // hydrateRoot is called — on a streaming/PPR document the generator only
+    // ends when its stream side does, so the per-push logs below are the
+    // primary probe for "the document render is holding hydration".
+    bootLog("handles: consuming payload handle stream (pre-hydration await)");
     const handlesGenerator = initialPayload.metadata.handles;
     let lastHandleData: Record<string, Record<string, unknown[]>> = {};
+    let handlePushes = 0;
     for await (const handleData of handlesGenerator) {
       lastHandleData = handleData;
+      if (IS_BROWSER_DEBUG) {
+        handlePushes += 1;
+        bootLog(`handles: push #${handlePushes}`, {
+          segments: Object.keys(handleData),
+        });
+      }
     }
+    bootLog("handles: stream complete", { pushes: handlePushes });
     // Initialize event controller with initial handle state before hydration.
     eventController.setHandleData(
       lastHandleData,
@@ -221,6 +245,8 @@ export async function initBrowserApp(
     // Update the initial cache entry with the processed handleData
     // The cache entry was created by createNavigationStore but without handleData
     store.updateCacheHandleData(initialHistoryKey, lastHandleData);
+  } else {
+    bootLog("handles: none in payload");
   }
 
   // Create composable utilities
@@ -321,9 +347,17 @@ export async function initBrowserApp(
   if (linkInterception) {
     navigationBridge.registerLinkInterception();
   }
+  bootLog("bridges registered (action + navigation)");
 
   // Build initial tree with rootLayout
+  bootLog("building initial segment tree (renderSegments)");
   const initialTree = renderSegments(initialPayload.metadata!.segments);
+  if (IS_BROWSER_DEBUG && initialTree instanceof Promise) {
+    initialTree.then(
+      () => bootLog("initial segment tree settled"),
+      (err: unknown) => bootLog("initial segment tree rejected", { err }),
+    );
+  }
 
   // Setup HMR with debounce — burst saves (format-on-save, rapid edits)
   // fire many rsc:update events in quick succession. Without debouncing,
@@ -491,9 +525,14 @@ export async function initBrowserApp(
   };
   browserAppContext = context;
 
+  bootLog("initBrowserApp complete -- handing off to hydrateRoot");
   return context;
 }
 
+// Once-flag so the hydration-commit boot log fires a single time (StrictMode
+// re-runs the root effect; the second flush is not a second hydration).
+let hydrationCommitLogged = false;
+
 /**
  * Get the browser app context. Throws if initBrowserApp hasn't been called.
  */
@@ -561,6 +600,10 @@ export function Rango(_props: RangoProps): React.ReactElement {
   // that does not depend on React internals like __reactFiber.
   React.useEffect(() => {
     document.documentElement.dataset.hydrated = "";
+    if (IS_BROWSER_DEBUG && !hydrationCommitLogged) {
+      hydrationCommitLogged = true;
+      bootLog("hydration commit (root effect flushed)");
+    }
   }, []);
 
   return (

package/src/cache/cache-key-utils.ts

@@ -58,3 +58,32 @@ export function sortedRouteParams(
   if (!params) return "";
   return encodeKV(Object.entries(params), { sort: true });
 }
+
+/**
+ * Host-namespaced cache key base: `${host}${pathname}[:params][?search]`.
+ *
+ * The ONE composition of the host-namespacing rule, shared by the segment tier
+ * (cache-scope.ts) and the document tier (document-cache.ts) so the rule cannot
+ * drift between them. Host prefixing matters because VercelCacheStore /
+ * MemorySegmentCacheStore key by the raw string (only CFCacheStore adds host
+ * internally) -- on a single function serving multiple domains an
+ * un-namespaced key bleeds tenant A's cached response to tenant B.
+ *
+ * Output is BYTE-STABLE by contract: changing the composition silently
+ * invalidates every persisted cache entry on upgrade. Callers append their own
+ * tier-specific suffixes (`:rsc`/`:html`, segment hash) after this base.
+ */
+export function cacheKeyBase(
+  host: string,
+  pathname: string,
+  searchParams?: URLSearchParams,
+  params?: Record<string, string>,
+): string {
+  const paramStr = sortedRouteParams(params);
+  const searchStr = searchParams ? sortedSearchString(searchParams) : "";
+
+  let key = `${host}${pathname}`;
+  if (paramStr) key += `:${paramStr}`;
+  if (searchStr) key += `?${searchStr}`;
+  return key;
+}

package/src/cache/cache-runtime.ts

@@ -412,26 +412,26 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
       try {
         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.
-        // Same isolation pattern as route-level background-revalidation.ts.
         runBackground(requestCtx, async () => {
-          // The closure-captured requestCtx is reused for the framework's own
-          // reads (handle store swap, error reporting) AND, below, to
-          // re-establish the request-context ALS around the user fn. ALS context
-          // may be gone inside waitUntil: on workerd a waitUntil task runs
-          // detached from the request's I/O context, so getRequestContext()
-          // inside the cached body would otherwise throw.
-          let originalHandleStore:
-            | ReturnType<typeof createHandleStore>
-            | undefined;
-          if (hasTaintedArgs && requestCtx) {
-            originalHandleStore = requestCtx._handleStore;
-            requestCtx._handleStore = createHandleStore();
-          }
-          const bgHandleStore = hasTaintedArgs
-            ? requestCtx?._handleStore
-            : undefined;
+          // The background body runs under a DERIVED context with an OWN
+          // _handleStore (the shell-capture isolation pattern —
+          // shell-capture.ts attemptCapture): its handle pushes land in the
+          // isolated store (captured below, persisted with the entry) while
+          // the foreground keeps pushing into the ORIGINAL store, untouched.
+          // Derivation matters because the foreground is STILL RENDERING here
+          // — runBackground/waitUntil starts the task on the next microtask,
+          // not after the response. The previous shape swapped
+          // requestCtx._handleStore in place (restore in finally), which
+          // routed the whole overlap window's foreground pushes into the
+          // background store: lost from the live document AND persisted into
+          // the revalidated entry (issue #684, plan 010).
+          const bgHandleStore =
+            hasTaintedArgs && requestCtx ? createHandleStore() : undefined;
+          const bgCtx: typeof requestCtx = bgHandleStore
+            ? Object.assign(Object.create(requestCtx), {
+                _handleStore: bgHandleStore,
+              })
+            : requestCtx;
           let bgCapture: HandleCapture | undefined;
           let bgStopCapture: (() => void) | undefined;
           if (bgHandleStore) {
@@ -440,28 +440,15 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
             bgStopCapture = c.stop;
           }
 
-          // Stamp tainted ARGS only — not requestCtx. The args stamp guards
-          // direct ctx method calls (ctx.set, ctx.header, ctx.onResponse, etc.)
-          // which is sufficient for correctness.
-          //
-          // We intentionally skip stamping requestCtx here because:
-          // 1. runBackground starts the async task synchronously (before the
-          //    first await), so stampCacheExec would pollute the shared
-          //    requestCtx while the foreground pipeline is still running.
-          //    This causes assertNotInsideCacheExec to fire when cache-store
-          //    later calls requestCtx.onResponse().
-          // 2. requestCtx methods are closure-bound to the original ctx, so
-          //    neither Object.create() nor a proxy can isolate the stamp.
-          // 3. The foreground miss path already stamps requestCtx and catches
-          //    cookies()/headers() misuse on first execution. The background
-          //    re-runs the same function with the same request.
-          const bgTaintedArgs: unknown[] = [];
-          for (const arg of args) {
-            if (isTainted(arg)) {
-              stampCacheExec(arg as object);
-              bgTaintedArgs.push(arg);
-            }
-          }
+          // Tainted args are NOT stamped here, in contrast to the foreground
+          // miss path below. The args include the live HandlerContext the
+          // still-rendering foreground holds, and INSIDE_CACHE_EXEC is a
+          // property stamped onto that SHARED object — so for the whole
+          // revalidation window a concurrent foreground ctx.set() /
+          // ctx.headers.*() would throw (issue #684, plan 010). requestCtx is
+          // not stamped for the same reason. In-fn misuse is already caught
+          // by the miss path's stamps on the function's FIRST execution — the
+          // background re-runs the same function with the same request.
 
           try {
             // Re-establish the request-context ALS so a "use cache" body that
@@ -469,8 +456,10 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
             // getRequestContext().env.ApiKey) resolves during the background
             // revalidation instead of throwing "called outside of a request
             // context". runWithRequestContext sets the store for fn's
-            // synchronous kickoff; its async continuations inherit it.
-            const scoped = runWithRequestContext(requestCtx, () =>
+            // synchronous kickoff; its async continuations inherit it. The
+            // DERIVED context goes in, so ambient _handleStore reads inside
+            // the body resolve to the isolated store.
+            const scoped = runWithRequestContext(bgCtx, () =>
               runWithCacheTagScope(() => fn.apply(this, args)),
             );
             const freshResult = await scoped.result;
@@ -507,15 +496,9 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
               "[use cache] background revalidation failed",
               requestCtx,
             );
-          } finally {
-            for (const arg of bgTaintedArgs) {
-              unstampCacheExec(arg as object);
-            }
-            // Restore original handle store
-            if (originalHandleStore && requestCtx) {
-              requestCtx._handleStore = originalHandleStore;
-            }
           }
+          // No finally: nothing shared was mutated — the derived context and
+          // its handle store are garbage after the task settles.
         });
         return result;
       } catch (error) {
@@ -601,6 +584,13 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     // inside the cached function body (those side effects are lost on hit).
     // Uses ref-counted stamp/unstamp so overlapping executions
     // sharing the same ctx don't clear each other's guards.
+    //
+    // LOAD-BEARING for the stale-revalidation path above: the background
+    // re-execution deliberately does NOT re-stamp (the objects are live
+    // foreground state mid-render), relying on THIS stamp having caught in-fn
+    // misuse on the function's first execution — an entry only becomes
+    // stale-revalidatable because a stamped miss ran clean and stored it. Do
+    // not create a "use cache" entry via any path that skips this stamp.
     const taintedArgs: unknown[] = [];
     for (const arg of args) {
       if (isTainted(arg)) {

package/src/cache/cache-scope.ts

@@ -31,7 +31,7 @@ import {
   encodeHandles,
   decodeHandles,
 } from "./handle-snapshot.js";
-import { sortedSearchString, sortedRouteParams } from "./cache-key-utils.js";
+import { cacheKeyBase } from "./cache-key-utils.js";
 import {
   DEFAULT_ROUTE_TTL,
   isFiniteNonNegativeSeconds,
@@ -85,21 +85,6 @@ function validatedSwr(value: number | undefined): number | undefined {
   return isValidCacheSeconds(value, "swr") ? value : undefined;
 }
 
-function getCacheKeyBase(
-  host: string,
-  pathname: string,
-  params?: Record<string, string>,
-  searchParams?: URLSearchParams,
-): string {
-  const paramStr = sortedRouteParams(params);
-  const searchStr = searchParams ? sortedSearchString(searchParams) : "";
-
-  let key = `${host}${pathname}`;
-  if (paramStr) key += `:${paramStr}`;
-  if (searchStr) key += `?${searchStr}`;
-  return key;
-}
-
 function getDefaultRouteCacheKey(
   pathname: string,
   params?: Record<string, string>,
@@ -113,7 +98,7 @@ function getDefaultRouteCacheKey(
   // Intercept navigations get their own cache namespace
   const prefix = isIntercept ? "intercept" : isPartial ? "partial" : "doc";
 
-  return `${prefix}:${getCacheKeyBase(host, pathname, params, searchParams)}`;
+  return `${prefix}:${cacheKeyBase(host, pathname, searchParams, params)}`;
 }
 
 // ============================================================================

package/src/cache/cache-tag.ts

@@ -38,36 +38,82 @@ export function normalizeTags(tags: Iterable<string>): string[] {
 }
 
 /**
- * Tag the current "use cache" entry for later invalidation via
- * updateTag() / revalidateTag().
+ * Tag content for later invalidation via updateTag() / revalidateTag().
  *
- * Must be called inside a function marked with "use cache".
- * Tags are additive - multiple calls accumulate.
+ * cacheTag() serves two forms depending on what is active when it runs:
+ *
+ * 1. Inside a "use cache" function — the DEFAULT. The tags go to the current
+ *    cache entry; `revalidateTag(tag)` drops that entry. Tags are additive
+ *    (multiple calls accumulate), and normalizeTag() is the single chokepoint so
+ *    a padded write matches an unpadded invalidate.
+ *
+ * 2. Render-callable (#648) — no "use cache" scope active, but a request context
+ *    is present. The tags record onto the request's DOCUMENT artifact
+ *    (ctx._requestTags) instead of throwing. The collection layers already exist:
+ *    PPR shell capture unions _requestTags into the shell entry, the document
+ *    cache tags the full-page entry with it, and prerender build contexts seed
+ *    their own set — so a server component that renders into a shell makes
+ *    `revalidateTag("campaign:spring")` evict that shell with ZERO cache()/"use
+ *    cache" in its tree. This is PPR's DERIVATIVE invalidation: PPR is
+ *    execution-PRESERVING (everything still runs underneath; only document bytes
+ *    are shortcut), so its tags ride this existing instrument rather than a
+ *    first-class ppr key/tag API. The shell-expiry invariant holds by
+ *    construction — baked ⇒ evicts (bake-lane loaders execute during capture and
+ *    record here), hole ⇒ fresh (masked loaders behind a renderable loading()
+ *    never execute during capture, so nothing under a hole can tag the shell).
+ *
+ * Inside a cache() DSL segment the render-callable form records at the DOCUMENT
+ * level, not the segment (only the "use cache" runtime enters the tag scope) — a
+ * documented semantic, not a filtered one. An empty/whitespace-only tag is
+ * dropped in both forms (the render-callable form silently, via normalizeTags in
+ * recordRequestTags; the scope form with a dev warning).
+ *
+ * With neither a scope nor a request context, cacheTag() throws.
  *
  * @example
  * ```typescript
+ * // Form 1 — inside "use cache":
  * async function getProduct(ctx) {
  *   "use cache";
  *   cacheTag(`product:${ctx.params.id}`, "products");
  *   return db.getProduct(ctx.params.id);
  * }
+ *
+ * // Form 2 — render-callable, tags the shell/document from a server component:
+ * function CampaignBanner() {
+ *   cacheTag("campaign:spring");
+ *   return <aside>Spring sale</aside>;
+ * }
  * ```
  */
 export function cacheTag(...tags: string[]): void {
   const store = cacheTagStorage.getStore();
-  if (!store) {
-    throw new Error('cacheTag() must be called inside a "use cache" function.');
-  }
-  for (const tag of tags) {
-    const normalized = normalizeTag(tag);
-    if (normalized === null) {
-      if (process.env.NODE_ENV !== "production") {
-        console.warn(`[cacheTag] Ignoring empty or whitespace-only tag.`);
+  if (store) {
+    // Form 1: "use cache" scope wins — tag the cache entry (unchanged).
+    for (const tag of tags) {
+      const normalized = normalizeTag(tag);
+      if (normalized === null) {
+        if (process.env.NODE_ENV !== "production") {
+          console.warn(`[cacheTag] Ignoring empty or whitespace-only tag.`);
+        }
+        continue;
       }
-      continue;
+      store.add(normalized);
     }
-    store.add(normalized);
+    return;
   }
+
+  const reqCtx = _getRequestContext();
+  if (reqCtx?._requestTags) {
+    // Form 2: render-callable — tag the request's document artifact. See the
+    // JSDoc above for the composition doctrine and the baked/hole invariant.
+    recordRequestTags(tags, reqCtx);
+    return;
+  }
+
+  throw new Error(
+    'cacheTag() must be called inside a "use cache" function or during a request render.',
+  );
 }
 
 export function recordRequestTags(

package/src/cache/cf/cf-cache-store.ts

@@ -137,6 +137,16 @@ const warnedNoKvReadInvalidation = new Set<string>();
  */
 const warnedTagInvalidationTtlFloor = new Set<string>();
 
+/**
+ * Stores (by namespace) already warned that tag invalidation is writing KV
+ * markers with no expiry (tagInvalidationTtl unset), so the unbounded-growth
+ * warning fires once per process rather than once per invalidateTags call
+ * (CFCacheStore is constructed per request; invalidateTags runs per marker
+ * batch). Distinct from the floor warning: that one only fires for a positive
+ * below-floor value, never for the unset (no-expiry) default that this bounds.
+ */
+const warnedNoTagInvalidationTtl = new Set<string>();
+
 // ============================================================================
 // Types
 // ============================================================================
@@ -201,6 +211,8 @@ interface KVShellEnvelope {
   po: string | null;
   /** React.version captured at prerender time */
   rv: string;
+  /** Build version captured at prerender time (ShellCacheEntry.buildVersion) */
+  bv?: string;
   /** createdAt (ms epoch) */
   c: number;
   /** When entry becomes stale (ms epoch) */
@@ -340,19 +352,30 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     // kv - yet every tagged read still serves stale data with no other signal.
     // Surface that misconfiguration.
     if (!this.kv && (this.tagCacheTtl > 0 || this.onRevalidateTag)) {
-      const id = this.namespace ?? "default";
-      if (!warnedNoKvReadInvalidation.has(id)) {
-        warnedNoKvReadInvalidation.add(id);
-        console.warn(
-          `[CFCacheStore] tagCacheTtl/onRevalidateTag is configured without a KV ` +
-            `namespace, so tag invalidation has NO read-side effect: tagged reads ` +
-            `are never treated as invalidated and serve stale data. Configure ` +
-            `{ kv } for distributed tag invalidation.`,
-        );
-      }
+      this.warnOncePerNamespace(
+        warnedNoKvReadInvalidation,
+        `[CFCacheStore] tagCacheTtl/onRevalidateTag is configured without a KV ` +
+          `namespace, so tag invalidation has NO read-side effect: tagged reads ` +
+          `are never treated as invalidated and serve stale data. Configure ` +
+          `{ kv } for distributed tag invalidation.`,
+      );
     }
   }
 
+  /**
+   * Warn about a namespace-scoped misconfiguration once per namespace per
+   * isolate. `seen` is the module-level Set for that message family -- Sets
+   * are module-level (not instance fields) so re-constructed stores in the
+   * same isolate don't re-warn.
+   * @internal
+   */
+  private warnOncePerNamespace(seen: Set<string>, message: string): void {
+    const id = this.namespace ?? "default";
+    if (seen.has(id)) return;
+    seen.add(id);
+    console.warn(message);
+  }
+
   /**
    * Validate a consumer-supplied tagInvalidationTtl against CF KV's expirationTtl
    * floor. A finite value below KV_MIN_EXPIRATION_TTL is raised to it (with a
@@ -368,16 +391,13 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     if (value == null) return undefined;
     if (!Number.isFinite(value) || value <= 0) return undefined;
     if (value < KV_MIN_EXPIRATION_TTL) {
-      const id = this.namespace ?? "default";
-      if (!warnedTagInvalidationTtlFloor.has(id)) {
-        warnedTagInvalidationTtlFloor.add(id);
-        console.warn(
-          `[CFCacheStore] tagInvalidationTtl ${value} is below Cloudflare KV's ` +
-            `${KV_MIN_EXPIRATION_TTL}s expirationTtl floor; raising to ` +
-            `${KV_MIN_EXPIRATION_TTL}. It must still exceed your largest entry ` +
-            `TTL+SWR or invalidated entries can resurrect when the marker expires.`,
-        );
-      }
+      this.warnOncePerNamespace(
+        warnedTagInvalidationTtlFloor,
+        `[CFCacheStore] tagInvalidationTtl ${value} is below Cloudflare KV's ` +
+          `${KV_MIN_EXPIRATION_TTL}s expirationTtl floor; raising to ` +
+          `${KV_MIN_EXPIRATION_TTL}. It must still exceed your largest entry ` +
+          `TTL+SWR or invalidated entries can resurrect when the marker expires.`,
+      );
       return KV_MIN_EXPIRATION_TTL;
     }
     return value;
@@ -1655,6 +1675,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
           prelude: envelope.p,
           postponed: envelope.po,
           reactVersion: envelope.rv,
+          buildVersion: envelope.bv,
           initialTheme: envelope.i,
           snapshot: envelope.sn,
           createdAt: envelope.c,
@@ -1716,6 +1737,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
               p: entry.prelude,
               po: entry.postponed,
               rv: entry.reactVersion,
+              bv: entry.buildVersion,
               c: entry.createdAt,
               s: staleAt,
               e: staleAt + swrWindow * 1000,
@@ -2254,6 +2276,22 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     const failedTags = new Set<string>();
     const errors: unknown[] = [];
     if (this.kv) {
+      // Markers written with no expiry (tagInvalidationTtl unset) never expire,
+      // so high-cardinality tags accumulate KV keys unboundedly with no reaper.
+      // Warn once per namespace at the batch entry point (not per marker write,
+      // which would fire once per tag). Kept separate from the floor warning:
+      // that path only fires for a positive below-floor value, never the unset
+      // default sanitizeTagInvalidationTtl passes through as undefined.
+      if (!this.tagInvalidationTtl) {
+        this.warnOncePerNamespace(
+          warnedNoTagInvalidationTtl,
+          `[CFCacheStore] invalidateTags is writing KV markers with no expiry ` +
+            `(tagInvalidationTtl is unset): high-cardinality tags accumulate KV ` +
+            `keys unboundedly (storage + list-scan cost) with no reaper. Set ` +
+            `tagInvalidationTtl above your largest entry TTL+SWR to bound marker ` +
+            `growth; setting it too small resurrects invalidated entries.`,
+        );
+      }
       await Promise.all(
         tags.map(async (tag) => {
           const markerKey = this.tagMarkerKey(tag);

package/src/cache/document-cache.ts

@@ -19,7 +19,7 @@ import {
   type RequestContext,
 } from "../server/request-context.js";
 import { mayNeedSSR } from "../rsc/ssr-setup.js";
-import { sortedSearchString } from "./cache-key-utils.js";
+import { cacheKeyBase } from "./cache-key-utils.js";
 import { runBackground } from "./background-task.js";
 import { reportCacheError } from "./cache-error.js";
 
@@ -188,7 +188,13 @@ export interface DocumentCacheOptions<TEnv = any> {
   skipPaths?: string[];
 
   /**
-   * Custom cache key generator
+   * Custom cache key generator.
+   *
+   * Replaces the default `host + pathname + search` key entirely. On a
+   * multi-domain deployment served by one function you MUST include `url.host`
+   * (or an equivalent tenant discriminator) yourself — the default key is
+   * host-namespaced, but a custom generator's output is used verbatim, so
+   * omitting host bleeds one hostname's cached response to another.
    */
   keyGenerator?: (url: URL) => string;
 
@@ -311,17 +317,17 @@ export function createDocumentCacheMiddleware<TEnv = any>(
         isPartial && clientSegments ? `:${hashSegmentIds(clientSegments)}` : "";
       const typeSuffix = isRscRequest ? ":rsc" : ":html";
 
-      let searchSuffix = "";
-      if (!keyGenerator) {
-        const sorted = sortedSearchString(url.searchParams);
-        if (sorted) {
-          searchSuffix = `?${sorted}`;
-        }
-      }
-
+      // Default key rides the shared host-namespaced base (cacheKeyBase) so the
+      // segment tier (cache-scope.ts) and this document tier cannot drift on the
+      // host-namespacing rule -- see the contract on cacheKeyBase.
+      // The keyGenerator branch is left untouched: a consumer-supplied generator
+      // owns its own namespacing (auto-prefixing host would silently change their
+      // existing keys and double any host they already include).
       const cacheKey = keyGenerator
         ? keyGenerator(url) + segmentHash + typeSuffix
-        : `${url.pathname}${searchSuffix}${segmentHash}${typeSuffix}`;
+        : cacheKeyBase(url.host, url.pathname, url.searchParams) +
+          segmentHash +
+          typeSuffix;
       // 1. Check cache
       const cached = await store.getResponse(cacheKey);