@rangojs/router 0.0.0-experimental.8 → 0.0.0-experimental.80daa23e

package/src/cache/cache-scope.ts

@@ -2,276 +2,132 @@
  * CacheScope - Runtime cache scope for iterator-based caching
  *
  * Each cache() boundary in the route tree creates a new CacheScope.
- * The scope owns: config, serialization, and storage operations.
+ * The scope owns: config, key management, and storage operations.
+ *
+ * Serialization is delegated to segment-codec.ts.
+ * Handle data capture/restore is delegated to handle-snapshot.ts.
  */
 
-/// <reference types="@vitejs/plugin-rsc/types" />
-
 import type { PartialCacheOptions } from "../types.js";
 import type { ResolvedSegment } from "../types.js";
-import type {
-  SegmentCacheStore,
-  SegmentHandleData,
-  CachedEntryData,
-  SerializedSegmentData,
-} from "./types.js";
-import { getRequestContext } from "../server/request-context.js";
+import type { SegmentCacheStore, CachedEntryData } from "./types.js";
+import { CACHE_READ_ERROR } from "./types.js";
+import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
 import {
-  renderToReadableStream,
-  createTemporaryReferenceSet,
-} from "@vitejs/plugin-rsc/rsc";
-import { createFromReadableStream } from "@vitejs/plugin-rsc/rsc";
-
-// ============================================================================
-// Constants
-// ============================================================================
-
-/** Default TTL when no explicit value or store defaults are configured */
-const DEFAULT_TTL_SECONDS = 60;
-
-// ============================================================================
-// Serialization Utilities (internal)
-// ============================================================================
-
-/**
- * Generate cache key base from pathname and params.
- * Params are sorted alphabetically for consistent key generation.
- * @internal
- */
-function getCacheKeyBase(
-  pathname: string,
-  params?: Record<string, string>
-): string {
-  const paramStr = params
-    ? Object.entries(params)
-        .sort(([a], [b]) => a.localeCompare(b))
-        .map(([k, v]) => `${k}=${v}`)
-        .join("&")
-    : "";
-
-  return paramStr ? `${pathname}:${paramStr}` : pathname;
-}
-
-/**
- * Generate default cache key for a route request.
- * Single cache entry per route - uses pathname as the key.
- * 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>,
-  isIntercept?: boolean
-): string {
-  const ctx = getRequestContext();
-  const isPartial = ctx?.url.searchParams.has("_rsc_partial") ?? false;
-
-  // Intercept navigations get their own cache namespace
-  const prefix = isIntercept ? "intercept" : isPartial ? "partial" : "doc";
-
-  return `${prefix}:${getCacheKeyBase(pathname, params)}`;
+  getRequestContext,
+  _getRequestContext,
+} from "../server/request-context.js";
+import { recordRequestTags } from "./cache-tag.js";
+import { reportCacheError } from "./cache-error.js";
+// segment-codec is the only module on cache-scope's import graph that eagerly
+// pulls @vitejs/plugin-rsc (a virtual: module the plain node/vitest runner cannot
+// resolve). It is imported LAZILY at the two call sites below (deserializeSegments
+// in lookupRoute, serializeSegments in cacheRoute) so that requiring cache-scope —
+// e.g. dispatch's lazy `import("../cache/cache-scope.js")` for the response-route
+// cache path — does not crash a consumer test that never mocks plugin-rsc. Behavior
+// is unchanged: both methods are async and already awaited the codec.
+import {
+  captureHandles,
+  restoreHandles,
+  encodeHandles,
+  decodeHandles,
+} from "./handle-snapshot.js";
+import { cacheKeyBase } from "./cache-key-utils.js";
+import {
+  DEFAULT_ROUTE_TTL,
+  isFiniteNonNegativeSeconds,
+  resolveCacheKey,
+  resolveCacheStore,
+  resolveTagsOption,
+} from "./cache-policy.js";
+import type { RequestContext } from "../server/request-context.js";
+
+export function resolveCacheTags(
+  config: PartialCacheOptions | false,
+  ctx: RequestContext | undefined,
+): string[] | undefined {
+  if (config === false) return undefined;
+  return resolveTagsOption(config.tags, ctx, "CacheScope");
 }
 
-/**
- * Convert a ReadableStream to a string.
- * @internal
- */
-async function streamToString(
-  stream: ReadableStream<Uint8Array>
-): Promise<string> {
-  const reader = stream.getReader();
-  const decoder = new TextDecoder();
-  let result = "";
-
-  while (true) {
-    const { done, value } = await reader.read();
-    if (done) break;
-    result += decoder.decode(value, { stream: true });
+function debugCacheLog(message: string): void {
+  if (INTERNAL_RANGO_DEBUG) {
+    console.log(message);
   }
-
-  result += decoder.decode(); // flush
-  return result;
 }
 
 /**
- * Convert a string to a ReadableStream.
- * @internal
+ * A finite, non-negative seconds value? A NaN/Infinity ttl/swr (from a bad
+ * cache() option or store defaults) flows into computeExpiration ->
+ * staleAt/expiresAt = NaN, where every `now > NaN` is false so the entry never
+ * evicts and is served fresh forever; a negative value makes every read a miss.
+ * Mirror profile-registry.ts's Number.isFinite + >= 0 check, but the callers
+ * degrade to a default (warning in dev) rather than throw — this runs on the
+ * foreground render.
  */
-function stringToStream(str: string): ReadableStream<Uint8Array> {
-  const encoder = new TextEncoder();
-  const uint8 = encoder.encode(str);
-
-  return new ReadableStream({
-    start(controller) {
-      controller.enqueue(uint8);
-      controller.close();
-    },
-  });
+function isValidCacheSeconds(value: number, label: string): boolean {
+  if (isFiniteNonNegativeSeconds(value)) return true;
+  if (process.env.NODE_ENV !== "production") {
+    console.warn(
+      `[CacheScope] Invalid ${label} ${value}; falling back to default`,
+    );
+  }
+  return false;
 }
 
-/**
- * RSC-serialize a value using React Server Components stream.
- * Used for serializing loaderData, layout, loading components etc.
- * @internal
- */
-async function rscSerialize(value: unknown): Promise<string | undefined> {
-  if (value === undefined || value === null) return undefined;
-
-  const temporaryReferences = createTemporaryReferenceSet();
-  const stream = renderToReadableStream(value, { temporaryReferences });
-  return streamToString(stream);
+/** Coerce a resolved ttl to a finite, non-negative number (default on invalid). */
+function validatedTtl(value: number): number {
+  return isValidCacheSeconds(value, "ttl") ? value : DEFAULT_ROUTE_TTL;
 }
 
-/**
- * RSC-deserialize a value from a stored string.
- * @internal
- */
-async function rscDeserialize<T>(
-  encoded: string | undefined
-): Promise<T | undefined> {
-  if (!encoded) return undefined;
-
-  const temporaryReferences = createTemporaryReferenceSet();
-  const stream = stringToStream(encoded);
-  return createFromReadableStream<T>(stream, { temporaryReferences });
+/** Coerce a resolved swr to a finite, non-negative number, or undefined (no SWR window). */
+function validatedSwr(value: number | undefined): number | undefined {
+  if (value === undefined) return undefined;
+  return isValidCacheSeconds(value, "swr") ? value : undefined;
 }
 
-/**
- * Serialize segments for storage.
- * Each segment's component, layout, loading, and loaderData are RSC-serialized.
- * Metadata is preserved as-is.
- * @internal
- */
-async function serializeSegments(
-  segments: ResolvedSegment[]
-): Promise<SerializedSegmentData[]> {
-  const serialized: SerializedSegmentData[] = [];
-
-  for (const segment of segments) {
-    const temporaryReferences = createTemporaryReferenceSet();
-
-    // Await component if it's a Promise (intercepts with loading keep component as Promise)
-    const componentResolved =
-      segment.component instanceof Promise
-        ? await segment.component
-        : segment.component;
-
-    // Serialize the component to RSC stream
-    const stream = renderToReadableStream(componentResolved, {
-      temporaryReferences,
-    });
-
-    // Convert stream to string
-    const encoded = await streamToString(stream);
-
-    // RSC-serialize layout if present (ReactNode)
-    const encodedLayout = segment.layout
-      ? await rscSerialize(segment.layout)
-      : undefined;
-
-    // RSC-serialize loading if present (ReactNode) - preserves tree structure
-    // Use "null" string to distinguish explicit null from undefined
-    const encodedLoading =
-      segment.loading !== undefined
-        ? segment.loading === null
-          ? "null"
-          : await rscSerialize(segment.loading)
-        : undefined;
-
-    // Await and RSC-serialize loaderData if present
-    const loaderDataResolved =
-      segment.loaderData instanceof Promise
-        ? await segment.loaderData
-        : segment.loaderData;
-    const encodedLoaderData = await rscSerialize(loaderDataResolved);
-
-    // Await and RSC-serialize loaderDataPromise if present
-    const loaderDataPromiseResolved =
-      segment.loaderDataPromise instanceof Promise
-        ? await segment.loaderDataPromise
-        : segment.loaderDataPromise;
-    const encodedLoaderDataPromise = await rscSerialize(
-      loaderDataPromiseResolved
-    );
-
-    serialized.push({
-      encoded,
-      encodedLayout,
-      encodedLoading,
-      encodedLoaderData,
-      encodedLoaderDataPromise,
-      metadata: {
-        id: segment.id,
-        type: segment.type,
-        namespace: segment.namespace,
-        index: segment.index,
-        params: segment.params,
-        slot: segment.slot,
-        belongsToRoute: segment.belongsToRoute,
-        layoutName: segment.layoutName,
-        parallelName: segment.parallelName,
-        loaderId: segment.loaderId,
-        loaderIds: segment.loaderIds,
-      },
-    });
-  }
-
-  return serialized;
-}
-
-/**
- * Deserialize segments from storage.
- * Reconstructs ResolvedSegment objects from RSC-serialized data.
- * @internal
- */
-async function deserializeSegments(
-  data: SerializedSegmentData[]
-): Promise<ResolvedSegment[]> {
-  const segments: ResolvedSegment[] = [];
-
-  for (const item of data) {
-    const temporaryReferences = createTemporaryReferenceSet();
-
-    // Revive the component from cached string
-    const stream = stringToStream(item.encoded);
-    const component = await createFromReadableStream(stream, {
-      temporaryReferences,
-    });
+function getDefaultRouteCacheKey(
+  pathname: string,
+  params?: Record<string, string>,
+  isIntercept?: boolean,
+  prefixOverride?: "doc",
+): string {
+  const ctx = getRequestContext();
+  const isPartial = ctx?.originalUrl?.searchParams.has("_rsc_partial") ?? false;
+  const searchParams = ctx?.url.searchParams;
+  const host = ctx?.url.host ?? "localhost";
 
-    // RSC-deserialize layout, loaderData, loaderDataPromise in parallel
-    const [layout, loaderData, loaderDataPromise, loadingData] =
-      await Promise.all([
-        rscDeserialize(item.encodedLayout),
-        rscDeserialize(item.encodedLoaderData),
-        rscDeserialize(item.encodedLoaderDataPromise),
-        rscDeserialize(item.encodedLoading),
-      ]);
-
-    segments.push({
-      ...item.metadata,
-      component: await component,
-      layout,
-      loading: loadingData,
-      loaderData,
-      loaderDataPromise,
-    } as ResolvedSegment);
-  }
+  // Intercept navigations get their own cache namespace
+  const prefix = isIntercept
+    ? "intercept"
+    : (prefixOverride ?? (isPartial ? "partial" : "doc"));
 
-  return segments;
+  return `${prefix}:${cacheKeyBase(host, pathname, searchParams, params, ctx?._searchParamsFilter)}`;
 }
 
 // ============================================================================
 // CacheScope
 // ============================================================================
 
+const CACHE_HIT_OBSERVERS = new WeakMap<CacheScope, () => void>();
+
+/**
+ * Discriminated outcome of a route cache lookup — see
+ * {@link CacheScope.lookupRouteDetailed} for what each status licenses.
+ */
+export type CacheRouteLookupOutcome =
+  | {
+      status: "hit";
+      result: { segments: ResolvedSegment[]; shouldRevalidate: boolean };
+    }
+  | { status: "miss" | "bypass" | "error" };
+
 /**
  * CacheScope represents a cache boundary in the route tree.
  *
  * When withCache encounters an entry with cache config, it creates
- * a new CacheScope. The scope owns serialization, storage, and TTL.
+ * a new CacheScope. The scope owns key management, TTL resolution,
+ * and storage operations. Serialization is handled by segment-codec.ts.
  *
  * Store resolution priority:
  * 1. Explicit store in cache() options
@@ -291,7 +147,8 @@ export class CacheScope {
 
   constructor(
     config: PartialCacheOptions | false,
-    parent: CacheScope | null = null
+    parent: CacheScope | null = null,
+    private readonly defaultKeyPrefix?: "doc",
   ) {
     this.config = config;
     this.parent = parent;
@@ -307,40 +164,49 @@ export class CacheScope {
   }
 
   /**
-   * Get effective TTL from config or store defaults
+   * Get effective TTL from config or store defaults.
+   *
+   * Unlike profile-registry.ts (which fails fast at config time), the render
+   * path must DEGRADE: a non-finite/negative ttl (NaN/Infinity from a bad
+   * defaults config) would make computeExpiration produce NaN deadlines so the
+   * entry never evicts, or a guaranteed miss for a negative value. Fall back to
+   * DEFAULT_ROUTE_TTL instead of throwing in the foreground render.
    */
   get ttl(): number {
     if (this.config === false) return 0;
 
     // Explicit TTL in cache() options
     if (this.config.ttl !== undefined) {
-      return this.config.ttl;
+      return validatedTtl(this.config.ttl);
     }
 
     // Fall back to store defaults (explicit store first, then app-level)
     const store = this.getStore();
     if (store?.defaults?.ttl !== undefined) {
-      return store.defaults.ttl;
+      return validatedTtl(store.defaults.ttl);
     }
 
     // Hardcoded fallback
-    return DEFAULT_TTL_SECONDS;
+    return DEFAULT_ROUTE_TTL;
   }
 
   /**
-   * Get SWR window from config or store defaults
+   * Get SWR window from config or store defaults.
+   *
+   * A non-finite/negative swr is degraded to undefined (no SWR window) rather
+   * than fed into expiry math; see the ttl getter for the rationale.
    */
   get swr(): number | undefined {
     if (this.config === false) return undefined;
 
     // Explicit SWR in cache() options
     if (this.config.swr !== undefined) {
-      return this.config.swr;
+      return validatedSwr(this.config.swr);
     }
 
     // Fall back to store defaults
     const store = this.getStore();
-    return store?.defaults?.swr;
+    return validatedSwr(store?.defaults?.swr);
   }
 
   /**
@@ -348,65 +214,99 @@ export class CacheScope {
    * 1. Explicit store from cache() options
    * 2. App-level store from request context
    */
-  private getStore(): SegmentCacheStore | null {
-    // Explicit store from cache() options takes precedence
-    if (this.explicitStore) {
-      return this.explicitStore;
-    }
-    // Fall back to app-level store from request context
-    const ctx = getRequestContext();
-    return ctx?._cacheStore ?? null;
+  getStore(): SegmentCacheStore | null {
+    return resolveCacheStore(this.explicitStore);
   }
 
   /**
-   * Resolve the cache key using custom key functions or default generation.
-   *
-   * Resolution priority:
-   * 1. Route-level `key` function (full override)
-   * 2. Store-level `keyGenerator` (modifies default key)
-   * 3. Default key generation (prefix:pathname:params)
-   *
+   * Resolve the cache key using the shared 3-tier priority.
    * @internal
    */
   private async resolveKey(
     pathname: string,
     params: Record<string, string>,
-    isIntercept?: boolean
+    isIntercept?: boolean,
   ): Promise<string> {
-    const requestCtx = getRequestContext();
-    if (!requestCtx) {
-      // Fallback to default key if no request context
-      return getDefaultRouteCacheKey(pathname, params, isIntercept);
-    }
+    const defaultKey = getDefaultRouteCacheKey(
+      pathname,
+      params,
+      isIntercept,
+      this.defaultKeyPrefix,
+    );
+    const keyFn = this.config !== false ? this.config.key : undefined;
+    return resolveCacheKey(keyFn, this.getStore(), defaultKey, "CacheScope");
+  }
 
-    // Priority 1: Route-level key function (full override)
-    if (this.config !== false && this.config.key) {
-      try {
-        const customKey = await this.config.key(requestCtx);
-        return customKey;
-      } catch (error) {
-        console.error(`[CacheScope] Custom key function failed, using default:`, error);
-        return getDefaultRouteCacheKey(pathname, params, isIntercept);
-      }
-    }
+  /**
+   * @internal Whether a cache read/write is allowed for the current request:
+   * the scope is enabled AND its `condition` (if any) returns true. "read"
+   * is consulted by the PPR navigation-replay gate BEFORE any shell-store
+   * read so a cache(false)/condition-false route reports `cache-disabled`
+   * without spending getShell I/O; "write" gates the capture's snapshot-only
+   * doc record (cache-store middleware) under the same semantics as the
+   * scope's own store write. Consumer opt-outs are absolute — the seeded
+   * fallback must never serve where the consumer refused cached serves.
+   */
+  allowsCache(op: "read" | "write"): boolean {
+    return this.enabled && this.conditionAllows(op);
+  }
+
+  /**
+   * @internal True for scopes minted from the `_shellImplicitCache` marker
+   * (createShellImplicitDocScope) — the only construction path that passes
+   * the `doc` defaultKeyPrefix; route-derived scopes (createCacheScope) never
+   * do. withCacheLookup/withCacheStore use this to tell the implicit doc
+   * scope from a route-derived scope: the two compose on the replay serve
+   * path and only the route-derived kind gets the seeded fallback /
+   * doc-record treatment.
+   */
+  get isShellImplicitDocScope(): boolean {
+    return this.defaultKeyPrefix === "doc";
+  }
 
-    // Generate default key
-    const defaultKey = getDefaultRouteCacheKey(pathname, params, isIntercept);
+  /**
+   * Evaluate the cache `condition` predicate. Returns false (skip the cache
+   * operation) when the predicate returns false or throws; returns true when
+   * there is no condition or no request context to evaluate it against.
+   */
+  /**
+   * One WRITE decision per (scope, request), memoized on the request context.
+   * A capture render has TWO writers consulting the same predicate — the
+   * explicit tier's cacheRoute and the snapshot-only doc record gate
+   * (recordShellCaptureDocRecord) — and a true→false flap between the two
+   * evaluations recorded a REPLAYABLE canonical snapshot for a render whose
+   * real write was refused. The first evaluation pins the answer for the
+   * whole render (the capture's derived context during captures). READ
+   * decisions stay per-lookup by design: pre-deciding a flappable predicate
+   * at the replay gate was the round-2 regression.
+   */
+  private readonly writeConditionMemo = new WeakMap<RequestContext, boolean>();
 
-    // Priority 2: Store-level keyGenerator (modifies default key)
-    const store = this.getStore();
-    if (store?.keyGenerator) {
-      try {
-        const modifiedKey = await store.keyGenerator(requestCtx, defaultKey);
-        return modifiedKey;
-      } catch (error) {
-        console.error(`[CacheScope] Store keyGenerator failed, using default:`, error);
-        return defaultKey;
+  private conditionAllows(op: "read" | "write"): boolean {
+    if (this.config === false || !this.config.condition) return true;
+    const requestCtx = getRequestContext();
+    if (!requestCtx) return true;
+    if (op === "write") {
+      const memoized = this.writeConditionMemo.get(requestCtx);
+      if (memoized !== undefined) return memoized;
+    }
+    let allowed: boolean;
+    try {
+      allowed = !!this.config.condition(requestCtx);
+      if (!allowed) {
+        debugCacheLog(
+          `[CacheScope] condition returned false, skipping cache ${op}`,
+        );
       }
+    } catch (error) {
+      console.error(
+        `[CacheScope] condition function threw, skipping cache ${op}:`,
+        error,
+      );
+      allowed = false;
     }
-
-    // Priority 3: Default key
-    return defaultKey;
+    if (op === "write") this.writeConditionMemo.set(requestCtx, allowed);
+    return allowed;
   }
 
   /**
@@ -420,56 +320,173 @@ export class CacheScope {
   async lookupRoute(
     pathname: string,
     params: Record<string, string>,
-    isIntercept?: boolean
+    isIntercept?: boolean,
   ): Promise<{
     segments: ResolvedSegment[];
     shouldRevalidate: boolean;
   } | null> {
-    if (!this.enabled) return null;
-
-    const store = this.getStore();
-    if (!store) return null;
+    const outcome = await this.lookupRouteDetailed(
+      pathname,
+      params,
+      isIntercept,
+    );
+    return outcome.status === "hit" ? outcome.result : null;
+  }
 
-    // Resolve cache key (may use custom key functions)
-    const key = await this.resolveKey(pathname, params, isIntercept);
+  /**
+   * @internal lookupRoute with a discriminated outcome. The PPR replay
+   * composition (withCacheLookup) may substitute the seeded doc record ONLY on
+   * a true `miss` — the other non-hit outcomes must not be papered over:
+   *
+   * - `bypass`: the scope refused the read — cache(false), a false
+   *   `condition()`, or no resolvable store. Consumer opt-outs are absolute;
+   *   a fallback here would serve cached segments to a request the consumer
+   *   said must render fresh.
+   * - `error`: a throwing consumer key()/store keyGenerator/store.get. The
+   *   contract on that failure is "render uncached" (see the catch below) —
+   *   falling back would serve the canonical doc record across a broken key
+   *   partition, exactly the collision resolveCacheKey's no-default-fallback
+   *   rule exists to prevent.
+   *
+   * A corrupt entry that was evicted reads as `miss`: the store was consulted
+   * and holds nothing servable, which is the post-eviction truth.
+   */
+  async lookupRouteDetailed(
+    pathname: string,
+    params: Record<string, string>,
+    isIntercept?: boolean,
+  ): Promise<CacheRouteLookupOutcome> {
+    if (!this.enabled) return { status: "bypass" };
+    if (!this.conditionAllows("read")) return { status: "bypass" };
 
+    const store = this.getStore();
+    if (!store) return { status: "bypass" };
+
+    // Resolve cache key INSIDE the try so a throwing consumer key() (or a
+    // store.keyGenerator) degrades to a cache miss (return null -> render
+    // uncached) instead of crashing the foreground render. resolveCacheKey
+    // itself keeps its hard-fail/no-fallback-to-default contract (a throw must
+    // not silently collide onto the default slot); the graceful degradation
+    // happens here, where a miss is a safe outcome.
+    let key: string | undefined;
     try {
+      key = await this.resolveKey(pathname, params, isIntercept);
+
       const result = await store.get(key);
 
+      // Built-in stores swallow backend read failures internally and signal
+      // them with CACHE_READ_ERROR — classify as `error`, not `miss`, so the
+      // replay composition renders uncached instead of substituting the
+      // seeded doc record for a tier whose backend never answered.
+      if (result === CACHE_READ_ERROR) {
+        return { status: "error" };
+      }
+
       if (!result) {
-        console.log(`[CacheScope] MISS: ${key}`);
-        return null;
+        debugCacheLog(`[CacheScope] MISS: ${key}`);
+        return { status: "miss" };
       }
 
       const { data: cached, shouldRevalidate } = result;
 
-      // Deserialize segments
-      const segments = await deserializeSegments(cached.segments);
+      // Deserialize segments. A failure means the cached segments are corrupt/
+      // partial: evict the entry (self-heal - the re-render re-caches under the
+      // same key) and report it as corruption, distinct from a transient infra
+      // error (handled by the outer catch).
+      //
+      // Shell-HIT tail (_shellFragmentPayload, issue #700): skip the decode and
+      // carry the stored fragment strings verbatim — the payload consumers
+      // expand them (segment-fragments.ts). Read off the ambient context at the
+      // same point the cache key was resolved (getDefaultRouteCacheKey), so the
+      // flag shares fate with the key: a disrupted ALS already missed the
+      // seeded record and degraded to the full tail.
+      let segments: ResolvedSegment[];
+      const ambientContext = _getRequestContext();
+      try {
+        const codec = await import("./segment-codec.js");
+        segments = ambientContext?._shellFragmentPayload
+          ? await codec.fragmentSegments(cached.segments)
+          : await codec.deserializeSegments(cached.segments);
+      } catch (error) {
+        reportCacheError(
+          error,
+          "cache-corrupt",
+          `[CacheScope] ${key}: corrupt cached segments, evicting`,
+        );
+        await store
+          .delete(key)
+          .catch((e) =>
+            reportCacheError(e, "cache-delete", `[CacheScope] ${key}: evict`),
+          );
+        if (this.isShellImplicitDocScope) {
+          ambientContext?._shellImplicitCache?.onCorrupt?.();
+        }
+        return { status: "miss" };
+      }
 
-      // Replay handle data
-      const handleStore = getRequestContext()?._handleStore;
-      if (handleStore) {
-        for (const [segId, segHandles] of Object.entries(cached.handles)) {
-          if (Object.keys(segHandles).length > 0) {
-            handleStore.replaySegmentData(segId, segHandles);
-          }
+      // A hit serves content that was tagged at write time, so the document
+      // tag union must include this entry's tags for updateTag()/revalidateTag()
+      // to invalidate any full-page entry built on top of it. The write path
+      // records via cacheRoute (resolveCacheTags); the hit path records here.
+      recordRequestTags(cached.tags);
+
+      // Replay handle data. An empty string means the route pushed no handles —
+      // skip the decode entirely (the common case). Otherwise decode the
+      // Flight-encoded blob; a decode failure skips handle restore but keeps the
+      // valid cached segments.
+      const handleStore = _getRequestContext()?._handleStore;
+      if (handleStore && cached.handles) {
+        const handlesRecord = await decodeHandles(cached.handles);
+        if (handlesRecord) {
+          restoreHandles(handlesRecord, handleStore);
         }
       }
 
-      const segmentTypes = segments.map((s) =>
-        s.type === "parallel" ? s.slot : s.type
-      );
-      console.log(
-        `[CacheScope] ${shouldRevalidate ? "STALE" : "HIT"}: ${key} (${segmentTypes.join(", ")})`
-      );
+      if (INTERNAL_RANGO_DEBUG) {
+        const segmentTypes = segments.map((s) =>
+          s.type === "parallel" ? s.slot : s.type,
+        );
+        debugCacheLog(
+          `[CacheScope] ${shouldRevalidate ? "STALE" : "HIT"}: ${key} (${segmentTypes.join(", ")})`,
+        );
+      }
 
-      return { segments, shouldRevalidate };
+      CACHE_HIT_OBSERVERS.get(this)?.();
+      return { status: "hit", result: { segments, shouldRevalidate } };
     } catch (error) {
-      console.error(`[CacheScope] Failed to lookup ${key}:`, error);
-      return null;
+      // Covers a store.get() failure AND a throwing consumer key()/keyGenerator
+      // (resolveKey). Either way degrade to an uncached render — reported as
+      // `error`, not `miss`, so the replay composition cannot substitute the
+      // seeded doc record for a lookup that never resolved its key partition.
+      reportCacheError(
+        error,
+        "cache-read",
+        `[CacheScope] lookup ${key ?? "(key resolution failed)"}`,
+      );
+      return { status: "error" };
     }
   }
 
+  /**
+   * Record this scope's segment-DSL cache({ tags }) into the request tag union
+   * synchronously, under the same gate cacheRoute() uses for a write.
+   *
+   * cacheRoute() already records these tags, but it is invoked inside
+   * requestCtx.waitUntil() by the cache-store middleware (and the proactive path
+   * re-resolves the whole tree before calling it), so its recording is deferred
+   * and RACES the document cache's post-body-drain snapshot of _requestTags. On a
+   * first-write (segment-cache miss) the document tag union could miss these
+   * tags, and updateTag()/revalidateTag() would then fail to invalidate the
+   * cached document until a later write reseeded it. Calling this synchronously
+   * in the request pipeline (before the snapshot) closes that window. Idempotent
+   * (the tag union is a Set), so the duplicate record in cacheRoute is harmless.
+   */
+  recordTags(requestCtx: RequestContext | undefined): void {
+    if (!this.enabled) return;
+    if (!this.conditionAllows("write")) return;
+    recordRequestTags(resolveCacheTags(this.config, requestCtx), requestCtx);
+  }
+
   /**
    * Cache all segments for a route (non-blocking via waitUntil)
    * Single cache entry per route request.
@@ -484,9 +501,10 @@ export class CacheScope {
     pathname: string,
     params: Record<string, string>,
     segments: ResolvedSegment[],
-    isIntercept?: boolean
+    isIntercept?: boolean,
   ): Promise<void> {
     if (!this.enabled || segments.length === 0) return;
+    if (!this.conditionAllows("write")) return;
 
     const store = this.getStore();
     if (!store) return;
@@ -507,47 +525,115 @@ export class CacheScope {
     // Resolve cache key early (while request context is available)
     const key = await this.resolveKey(pathname, params, isIntercept);
 
+    // Doc-namespaced scopes (the shell implicit scope and the capture's
+    // composed doc scope) publish the canonical document segment key so
+    // captureAndStoreShell can stamp it onto the shell entry (`docKey`).
+    // Replay eligibility then requires this exact record — "any segment
+    // record" previously counted unusable explicit-tier-keyed records too.
+    if (this.defaultKeyPrefix === "doc" && requestCtx._shellImplicitCache) {
+      requestCtx._shellImplicitCache.docKey = key;
+    }
+
+    // Resolve tags early (while request context is available, before waitUntil)
+    const tags = resolveCacheTags(this.config, requestCtx);
+    recordRequestTags(tags, requestCtx);
+
     // Check if this is a partial request (navigation) vs document request
-    const isPartial = requestCtx.url.searchParams.has("_rsc_partial");
+    const isPartial = requestCtx.originalUrl.searchParams.has("_rsc_partial");
+
+    if (INTERNAL_RANGO_DEBUG) {
+      debugCacheLog(
+        `[CacheScope] cacheRoute: scheduling waitUntil for ${key} (${nonLoaderSegments.length} segments, isPartial=${isPartial})`,
+      );
+    }
 
     requestCtx.waitUntil(async () => {
+      if (INTERNAL_RANGO_DEBUG) {
+        debugCacheLog(
+          `[CacheScope] waitUntil: awaiting handleStore.settled for ${key}`,
+        );
+      }
+
       await handleStore.settled;
 
-      // For document requests: only cache if ALL segments have components (complete render)
-      // For partial requests: null components are expected (client already has them)
+      if (INTERNAL_RANGO_DEBUG) {
+        debugCacheLog(`[CacheScope] waitUntil: handleStore settled for ${key}`);
+      }
+
+      // For document requests: only cache if layout segments have components
+      // (complete render). Parallel and route segments may legitimately have
+      // null components — UI-less @meta parallels return null, and void route
+      // handlers produce null when the UI lives in parallel slots/layouts.
+      // Partial requests always allow null components (client already has them).
       if (!isPartial) {
-        const hasAllComponents = nonLoaderSegments.every(
-          (s) => s.component !== null
+        const hasIncompleteLayouts = nonLoaderSegments.some(
+          (s) => s.component === null && s.type === "layout",
         );
-        if (!hasAllComponents) return;
+        if (hasIncompleteLayouts) {
+          const nullSegments = nonLoaderSegments
+            .filter((s) => s.component === null && s.type === "layout")
+            .map((s) => s.id);
+          const error = new Error(
+            `[CacheScope] Cache write skipped: layout segments have null components ` +
+              `(${nullSegments.join(", ")}). This indicates an incomplete render — ` +
+              `layout handlers must return JSX for document requests to be cacheable.`,
+          );
+          error.name = "CacheScopeInvariantError";
+          console.error(error.message);
+          return;
+        }
       }
 
       // Collect handle data for non-loader segments only
-      const handles: Record<string, SegmentHandleData> = {};
-      for (const seg of nonLoaderSegments) {
-        handles[seg.id] = handleStore.getDataForSegment(seg.id);
-      }
+      const handles = captureHandles(
+        nonLoaderSegments,
+        handleStore,
+        requestCtx._shellCaptureLoaderHandleValues,
+      );
 
       try {
-        // Serialize non-loader segments only
-        const serializedSegments = await serializeSegments(nonLoaderSegments);
+        if (INTERNAL_RANGO_DEBUG) {
+          debugCacheLog(
+            `[CacheScope] waitUntil: serializing ${nonLoaderSegments.length} segments for ${key}`,
+          );
+        }
+
+        // Serialize segments and Flight-encode handles in parallel. Handles go
+        // through the codec (not raw into the entry) so Promise/ReactNode handle
+        // values survive a JSON-serializing store — see encodeHandles.
+        const { serializeSegments } = await import("./segment-codec.js");
+        const [serializedSegments, encodedHandles] = await Promise.all([
+          serializeSegments(nonLoaderSegments),
+          encodeHandles(handles),
+        ]);
 
         const data: CachedEntryData = {
           segments: serializedSegments,
-          handles,
+          handles: encodedHandles,
           expiresAt: Date.now() + ttl * 1000,
+          tags,
         };
 
+        if (INTERNAL_RANGO_DEBUG) {
+          debugCacheLog(`[CacheScope] waitUntil: calling store.set for ${key}`);
+        }
+
         await store.set(key, data, ttl, swr);
 
-        const segmentTypes = nonLoaderSegments.map((s) =>
-          s.type === "parallel" ? s.slot : s.type
-        );
-        console.log(
-          `[CacheScope] Cached: ${key} (${segmentTypes.join(", ")}) ttl=${ttl}s [loaders excluded]`
-        );
+        if (INTERNAL_RANGO_DEBUG) {
+          const segmentTypes = nonLoaderSegments.map((s) =>
+            s.type === "parallel" ? s.slot : s.type,
+          );
+          debugCacheLog(
+            `[CacheScope] Cached: ${key} (${segmentTypes.join(", ")}) ttl=${ttl}s [loaders excluded]`,
+          );
+        }
       } catch (error) {
-        console.error(`[CacheScope] Failed to cache ${key}:`, error);
+        reportCacheError(
+          error,
+          "cache-write",
+          `[CacheScope] Failed to cache ${key}`,
+        );
       }
     });
   }
@@ -558,8 +644,58 @@ export class CacheScope {
  */
 export function createCacheScope(
   config: { options: PartialCacheOptions | false } | undefined,
-  parent: CacheScope | null = null
+  parent: CacheScope | null = null,
 ): CacheScope | null {
   if (!config) return parent; // No config, inherit parent
   return new CacheScope(config.options, parent);
 }
+
+type ShellImplicitCacheMarker = NonNullable<
+  RequestContext["_shellImplicitCache"]
+>;
+
+/**
+ * Mint the implicit doc-level scope for a `_shellImplicitCache` marker: key
+ * resolution under the marker's `doc` namespace against the marker's store,
+ * with the marker's onHit wired as the hit observer. Shared by
+ * {@link resolveShellImplicitCacheScope} (routes that derived no scope) and
+ * the explicit-scope composition sites (capture doc record in the cache-store
+ * middleware, seeded replay fallback in withCacheLookup) so both ends of the
+ * shell contract resolve the SAME canonical document key.
+ */
+export function createShellImplicitDocScope(
+  marker: ShellImplicitCacheMarker,
+): CacheScope {
+  const implicitScope = new CacheScope(
+    { ttl: marker.ttl, swr: marker.swr, store: marker.store },
+    null,
+    marker.keyPrefix,
+  );
+  if (marker.onHit) CACHE_HIT_OBSERVERS.set(implicitScope, marker.onHit);
+  return implicitScope;
+}
+
+/**
+ * Shell fast path: when the route tree derived NO cache scope and the current
+ * request context carries the `_shellImplicitCache` marker (a shell capture,
+ * an eligible HIT tail, or a normal partial navigation replay), substitute an
+ * implicit doc-level scope so withCacheLookup/withCacheStore treat the WHOLE
+ * matched route as a cache() boundary — the shell entry IS a cache() of the
+ * handler layer, with loaders as the live carve-outs
+ * (resolveFreshLoadersAndYield).
+ *
+ * An existing scope — including an explicit cache(false) opt-out — always
+ * wins HERE: the consumer's cache() semantics (their ttl/swr/store/condition)
+ * are never overridden, and cache(false) keeps the tail on the full handler
+ * re-run path. On the navigation-replay serve path the marker still composes
+ * with an explicit scope downstream (withCacheLookup's seeded fallback after
+ * an explicit-tier miss) — see `onExplicitHit` on `_shellImplicitCache`.
+ */
+export function resolveShellImplicitCacheScope(
+  scope: CacheScope | null,
+): CacheScope | null {
+  if (scope) return scope;
+  const marker = getRequestContext()?._shellImplicitCache;
+  if (!marker) return null;
+  return createShellImplicitDocScope(marker);
+}