@rangojs/router 0.0.0-experimental.77 → 0.0.0-experimental.77ed8945

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

@@ -56,6 +56,28 @@ export const CACHE_STALE_AT_HEADER = "x-edge-cache-stale-at";
 /** Header storing cache status: HIT | REVALIDATING */
 export const CACHE_STATUS_HEADER = "x-edge-cache-status";
 
+/**
+ * Header storing the epoch-ms timestamp when an entry was marked REVALIDATING.
+ * The SWR thundering-herd guard reads this to decide whether the in-flight
+ * revalidation is still recent. It replaces a prior reliance on the HTTP `Age`
+ * header: CF's Cache API does not populate `Age` reliably per-colo (and our own
+ * unit MockCache never set it), so an absent `Age` defaulted to 0 and made every
+ * REVALIDATING entry look "just revalidated" forever -- a dropped/never-finished
+ * background revalidation could then pin an entry stale until hard expiry. An
+ * explicit timestamp we write ourselves (same pattern as CACHE_STALE_AT_HEADER)
+ * is reliable and lets the MAX_REVALIDATION_INTERVAL re-arm actually fire.
+ */
+export const CACHE_REVALIDATING_AT_HEADER = "x-edge-cache-revalidating-at";
+
+/**
+ * Header stashing the route author's original Cache-Control on L1 document
+ * entries. putResponse/promoteResponseToL1 overwrite Cache-Control with a long
+ * `max-age` so the CF Cache API retains the entry across the whole SWR window;
+ * getResponse restores this original value before serving so the client and any
+ * upstream CDN see the author's intended directive, not the internal edge TTL.
+ */
+const CACHE_ORIG_CC_HEADER = "x-edge-cache-orig-cc";
+
 /**
  * Maximum age in seconds for REVALIDATING status before allowing new revalidation.
  * After this period, a stale entry in REVALIDATING status will trigger revalidation again.
@@ -63,17 +85,44 @@ export const CACHE_STATUS_HEADER = "x-edge-cache-status";
  */
 export const MAX_REVALIDATION_INTERVAL = 30;
 
+/**
+ * Maximum time (ms) to wait for an L1 edge cache (CF Cache API) read before
+ * giving up and treating it as a miss. The Cache API is normally sub-millisecond
+ * per-colo, so a slow `match` signals a degraded colo; we don't want it adding
+ * latency to the request. On timeout the lookup is abandoned, a warning is
+ * logged, and the read falls through to its normal miss path (L2/KV or render).
+ *
+ * This is the default; override per store via
+ * `CFCacheStoreOptions.edgeLookupTimeoutMs` (<= 0 disables the budget).
+ */
+export const EDGE_LOOKUP_TIMEOUT_MS = 10;
+
+/**
+ * Maximum time (ms) to wait for the BODY of a matched L1 entry to be read
+ * (response.json()) before treating the read as a miss.
+ *
+ * This is separate from {@link EDGE_LOOKUP_TIMEOUT_MS} on purpose. CF's Cache
+ * API resolves `match()` with a lazily-streamed body, so a fast `match` can be
+ * followed by a multi-second stall while the body bytes are fetched -- the
+ * latency tail lives here, after the match budget has already passed. The body
+ * read also includes JSON parsing of a potentially large Flight payload, so a
+ * healthy read legitimately takes longer than a `match`; a 10ms budget here
+ * would false-miss large entries. The default is generous enough to clear a
+ * healthy fetch+parse yet still bound the seconds-long degraded tail.
+ *
+ * Override per store via `CFCacheStoreOptions.edgeReadTimeoutMs` (<= 0 disables).
+ */
+export const EDGE_READ_TIMEOUT_MS = 100;
+
 // ============================================================================
 // Types
 // ============================================================================
 
-/**
- * Cloudflare Workers ExecutionContext (subset we need)
- */
-export interface ExecutionContext {
-  waitUntil(promise: Promise<any>): void;
-  passThroughOnException(): void;
-}
+// Re-exported from the canonical home so cf-cache-store consumers keep
+// importing `ExecutionContext` from this module without a second interface
+// drifting over time.
+export type { ExecutionContext } from "../../types/request-scope.js";
+import type { ExecutionContext } from "../../types/request-scope.js";
 
 /**
  * Minimal Cloudflare KV Namespace interface.
@@ -109,8 +158,8 @@ interface KVSegmentEnvelope {
 interface KVItemEnvelope {
   /** RSC-serialized return value */
   v: string;
-  /** Handle data */
-  h?: Record<string, Record<string, unknown[]>>;
+  /** RSC-encoded handle data (see handle-snapshot.ts encodeHandles) */
+  h?: string;
   /** When entry becomes stale (ms epoch) */
   s: number;
   /** When entry hard-expires (ms epoch) */
@@ -136,6 +185,63 @@ interface KVResponseEnvelope {
   e: number;
 }
 
+/**
+ * One L1 read decision, surfaced when `debug` is enabled. Lets an operator
+ * confirm on a real deployment (e.g. via `wrangler tail`) that the store's
+ * observed inputs match its decision: which tier answered, the entry's status,
+ * the stale/revalidating timestamps, the raw CF `Age` header (so its
+ * unreliability can be seen next to the explicit revalidating-at stamp), and
+ * the measured match/body-read durations (where the latency tail shows up).
+ */
+export interface CFCacheReadDebugEvent {
+  /** Which read method produced this event. */
+  op: "get" | "getItem" | "getResponse";
+  /** Cache key (without the internal fn:/doc: prefix or version path). */
+  key: string;
+  /**
+   * What the read resolved to:
+   * - l1-fresh / l1-stale-revalidate / l1-revalidating-guarded: L1 hit outcomes
+   * - match-timeout / body-timeout: the latency budgets fired
+   * - non-200: L1 returned a non-200 (treated as a miss)
+   * - l1-miss: no L1 entry
+   * - kv-fresh / kv-stale / kv-miss: L2 fallback outcomes
+   * - error: the read threw
+   */
+  outcome:
+    | "l1-fresh"
+    | "l1-stale-revalidate"
+    | "l1-revalidating-guarded"
+    | "match-timeout"
+    | "body-timeout"
+    | "non-200"
+    | "l1-miss"
+    | "kv-fresh"
+    | "kv-stale"
+    | "kv-miss"
+    | "error";
+  /** HTTP status of the matched L1 response, when one was returned. */
+  status?: number;
+  /** Epoch-ms when the entry goes stale (from CACHE_STALE_AT_HEADER). */
+  staleAt?: number;
+  /** Epoch-ms the entry was marked REVALIDATING (from the explicit stamp). */
+  revalidatingAt?: number;
+  /** Raw CF `Age` header, for comparison against revalidatingAt (may be null). */
+  ageHeader?: string | null;
+  isStale?: boolean;
+  isRevalidating?: boolean;
+  shouldRevalidate?: boolean;
+  /** Wall-clock ms spent in cache.match (bounded by edgeLookupTimeoutMs). */
+  matchMs?: number;
+  /** Wall-clock ms spent reading the body (bounded by edgeReadTimeoutMs). */
+  bodyReadMs?: number;
+}
+
+/**
+ * Debug sink. `true` logs each {@link CFCacheReadDebugEvent} to console; a
+ * function receives the events for programmatic capture.
+ */
+export type CFCacheDebug = boolean | ((event: CFCacheReadDebugEvent) => void);
+
 export interface CFCacheStoreOptions<TEnv = unknown> {
   /**
    * Cache namespace. If not provided, uses caches.default (recommended).
@@ -184,11 +290,43 @@ export interface CFCacheStoreOptions<TEnv = unknown> {
    * Cache version string override. When this changes, all cached entries are
    * effectively invalidated (new keys won't match old entries).
    *
-   * Defaults to the auto-generated VERSION from `rsc-router:version` virtual module.
+   * Defaults to the auto-generated VERSION from the `@rangojs/router:version` virtual module.
    * Only set this if you need a custom versioning strategy.
    */
   version?: string;
 
+  /**
+   * Latency budget (ms) for an L1 edge cache (CF Cache API) read. A `match`
+   * slower than this is abandoned and treated as a miss, so a degraded colo
+   * cannot stall the request; the read then falls through to its normal miss
+   * path (L2/KV or render).
+   *
+   * Defaults to {@link EDGE_LOOKUP_TIMEOUT_MS} (10). Set to 0 (or any value
+   * <= 0) to disable the budget and always await `match`.
+   */
+  edgeLookupTimeoutMs?: number;
+
+  /**
+   * Latency budget (ms) for reading the BODY of a matched L1 entry
+   * (response.json()). CF streams the cache body lazily, so the multi-second
+   * tail can appear after `match` already resolved; this bounds it. On timeout
+   * the read is treated as a miss and falls through to L2/KV or render.
+   *
+   * Separate from {@link edgeLookupTimeoutMs} because a healthy body read
+   * (fetch + JSON parse of a potentially large Flight payload) legitimately
+   * takes longer than a `match`. Defaults to {@link EDGE_READ_TIMEOUT_MS} (100).
+   * Set to 0 (or any value <= 0) to disable and always await the body.
+   */
+  edgeReadTimeoutMs?: number;
+
+  /**
+   * Emit a {@link CFCacheReadDebugEvent} per L1 read. `true` logs to console
+   * (visible via `wrangler tail`); pass a function to capture events directly.
+   * Off by default. Intended for validating cache behavior on a real
+   * deployment before relying on it; not for steady-state production.
+   */
+  debug?: CFCacheDebug;
+
   /**
    * Custom key generator applied to all cache operations.
    * Receives the full RequestContext (including env) and the default-generated key.
@@ -242,9 +380,12 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   ) => string | Promise<string>;
 
   private readonly namespace?: string;
-  private readonly baseUrl: string;
+  private readonly explicitBaseUrl?: string;
   private readonly waitUntil?: (fn: () => Promise<void>) => void;
   private readonly version?: string;
+  private readonly edgeLookupTimeoutMs: number;
+  private readonly edgeReadTimeoutMs: number;
+  private readonly debug?: (event: CFCacheReadDebugEvent) => void;
   private readonly kv?: KVNamespace;
 
   constructor(options: CFCacheStoreOptions<TEnv>) {
@@ -257,21 +398,63 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     }
 
     this.namespace = options.namespace;
-    this.baseUrl = options.baseUrl ?? this.deriveBaseUrl();
+    // Base URL is resolved lazily per cache operation (see resolveBaseUrl).
+    // The store is constructed before the per-request context ALS is entered
+    // (the cache factory runs ahead of runWithRequestContext in the handler),
+    // so deriving the host here would always miss the request and fall back to
+    // the internal host. Only the explicit override can be captured eagerly.
+    this.explicitBaseUrl = options.baseUrl;
     this.defaults = options.defaults;
     this.version = options.version ?? VERSION;
+    this.edgeLookupTimeoutMs =
+      options.edgeLookupTimeoutMs ?? EDGE_LOOKUP_TIMEOUT_MS;
+    this.edgeReadTimeoutMs = options.edgeReadTimeoutMs ?? EDGE_READ_TIMEOUT_MS;
+    this.debug =
+      options.debug === true
+        ? (event) =>
+            console.log(`[CFCacheStore:debug] ${JSON.stringify(event)}`)
+        : typeof options.debug === "function"
+          ? options.debug
+          : undefined;
     this.keyGenerator = options.keyGenerator;
     this.waitUntil = (fn) => options.ctx.waitUntil(fn());
     this.kv = options.kv;
   }
 
+  /**
+   * Emit a debug event if `debug` is enabled. Swallows sink errors so a faulty
+   * debug callback can never break a cache read.
+   * @internal
+   */
+  private emitDebug(event: CFCacheReadDebugEvent): void {
+    if (!this.debug) return;
+    try {
+      this.debug(event);
+    } catch {
+      // A broken debug sink must not affect the request.
+    }
+  }
+
+  /**
+   * Resolve the cache-key base URL for the current cache operation.
+   * Prefers an explicit `baseUrl` option; otherwise derives it from the live
+   * request. Called per operation (from keyToRequest), which runs inside the
+   * request-context ALS, so deriveBaseUrl sees the request and can use the
+   * production host instead of the internal fallback.
+   * @internal
+   */
+  private resolveBaseUrl(): string {
+    return this.explicitBaseUrl ?? this.deriveBaseUrl();
+  }
+
   /**
    * Derive base URL from request hostname via requestContext.
    * Uses internal fallback for dev/preview environments and untrusted hostnames.
+   * Must run inside the request context (invoked lazily via resolveBaseUrl).
    * @internal
    */
   private deriveBaseUrl(): string {
-    const fallback = "https://rsc-cache.internal.com/";
+    const fallback = "https://rsc-dummy-host-1.com/";
 
     const ctx = _getRequestContext();
     if (!ctx?.request) {
@@ -316,6 +499,92 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     return caches.default;
   }
 
+  /**
+   * Read from the L1 edge cache with a latency budget. A `match` that takes
+   * longer than the configured budget (edgeLookupTimeoutMs, default
+   * EDGE_LOOKUP_TIMEOUT_MS) is abandoned and reported as a miss (undefined) so a
+   * degraded colo cannot stall the request; callers then fall through to their
+   * normal miss path (L2/KV or render). The slow `match` is left to settle in
+   * the background (errors swallowed) rather than aborted, since the Cache API
+   * exposes no cancellation. A budget <= 0 disables the timeout entirely and
+   * awaits `match` directly.
+   * @internal
+   */
+  private async matchWithTimeout(
+    cache: Cache,
+    request: Request,
+  ): Promise<Response | undefined> {
+    const budget = this.edgeLookupTimeoutMs;
+    if (budget <= 0) {
+      return cache.match(request);
+    }
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const timeout = new Promise<{ timedOut: true }>((resolve) => {
+      timer = setTimeout(() => resolve({ timedOut: true }), budget);
+    });
+    try {
+      const matchPromise = cache.match(request);
+      // The losing branch keeps running; ensure a late rejection can't surface
+      // as an unhandled rejection once we've stopped awaiting it.
+      matchPromise.catch(() => {});
+      const result = await Promise.race([
+        matchPromise.then((response) => ({
+          timedOut: false as const,
+          response,
+        })),
+        timeout,
+      ]);
+      if (result.timedOut) {
+        console.warn(
+          `[CFCacheStore] edge cache lookup exceeded ${budget}ms; treating as miss`,
+        );
+        return undefined;
+      }
+      return result.response;
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+
+  /**
+   * Read and JSON-parse a matched L1 Response's body under the edgeReadTimeoutMs
+   * budget. CF resolves `match()` with a lazily-streamed body, so the latency
+   * tail surfaces here -- after matchWithTimeout has already passed -- not in the
+   * match itself. On timeout the read is abandoned (the dangling body read is
+   * left to settle, errors swallowed, since the stream exposes no cancellation)
+   * and `undefined` is returned so the caller falls through to L2/KV or render.
+   * A budget <= 0 disables the bound and awaits the body directly.
+   * @internal
+   */
+  private async readJsonWithTimeout<T>(
+    response: Response,
+  ): Promise<T | undefined> {
+    const budget = this.edgeReadTimeoutMs;
+    if (budget <= 0) return (await response.json()) as T;
+
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const timeout = new Promise<{ timedOut: true }>((resolve) => {
+      timer = setTimeout(() => resolve({ timedOut: true }), budget);
+    });
+    try {
+      const readPromise = response.json() as Promise<T>;
+      readPromise.catch(() => {});
+      const result = await Promise.race([
+        readPromise.then((value) => ({ timedOut: false as const, value })),
+        timeout,
+      ]);
+      if (result.timedOut) {
+        console.warn(
+          `[CFCacheStore] edge cache body read exceeded ${budget}ms; treating as miss`,
+        );
+        return undefined;
+      }
+      return result.value;
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+
   // ============================================================================
   // Segment Cache Methods
   // ============================================================================
@@ -335,26 +604,84 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     try {
       const cache = await this.getCache();
       const request = this.keyToRequest(key);
-      const response = await cache.match(request);
+      const matchStart = Date.now();
+      const response = await this.matchWithTimeout(cache, request);
+      const matchMs = Date.now() - matchStart;
 
       if (!response) {
+        // Genuine L1 miss, or matchWithTimeout abandoned a slow match (it warns).
+        this.emitDebug({ op: "get", key, outcome: "l1-miss", matchMs });
+        return this.kvGetSegment(key);
+      }
+
+      // A non-200 entry (a cached error response, or a foreign response that
+      // landed on this key) is not valid segment data; treat it as a miss
+      // rather than JSON-parsing garbage and serving it as a hit.
+      if (response.status !== 200) {
+        this.emitDebug({
+          op: "get",
+          key,
+          outcome: "non-200",
+          status: response.status,
+          matchMs,
+        });
         return this.kvGetSegment(key);
       }
 
       // Read status headers
       const status = response.headers.get(CACHE_STATUS_HEADER);
-      const age = Number(response.headers.get("age") ?? "0");
+      const ageHeader = response.headers.get("age");
       const staleAt = Number(
         response.headers.get(CACHE_STALE_AT_HEADER) ?? "0",
       );
+      const revalidatingAt = Number(
+        response.headers.get(CACHE_REVALIDATING_AT_HEADER) ?? "0",
+      );
 
       const isStale = staleAt > 0 && Date.now() > staleAt;
+      // Recency comes from our explicit revalidating-at stamp, not CF's `Age`
+      // header (see CACHE_REVALIDATING_AT_HEADER). An absent/zero stamp counts
+      // as "not recent" so a dropped revalidation re-arms instead of pinning.
       const isRevalidating =
-        status === "REVALIDATING" && age < MAX_REVALIDATION_INTERVAL;
+        status === "REVALIDATING" &&
+        revalidatingAt > 0 &&
+        Date.now() - revalidatingAt < MAX_REVALIDATION_INTERVAL * 1000;
 
       // Case 1: Fresh or already being revalidated - just return data
       if (!isStale || isRevalidating) {
-        const data = (await response.json()) as CachedEntryData;
+        const bodyStart = Date.now();
+        const data = await this.readJsonWithTimeout<CachedEntryData>(response);
+        const bodyReadMs = Date.now() - bodyStart;
+        if (data === undefined) {
+          this.emitDebug({
+            op: "get",
+            key,
+            outcome: "body-timeout",
+            status: response.status,
+            staleAt,
+            revalidatingAt,
+            ageHeader,
+            isStale,
+            isRevalidating,
+            matchMs,
+            bodyReadMs,
+          });
+          return this.kvGetSegment(key);
+        }
+        this.emitDebug({
+          op: "get",
+          key,
+          outcome: isRevalidating ? "l1-revalidating-guarded" : "l1-fresh",
+          status: response.status,
+          staleAt,
+          revalidatingAt,
+          ageHeader,
+          isStale,
+          isRevalidating,
+          shouldRevalidate: false,
+          matchMs,
+          bodyReadMs,
+        });
         return { data, shouldRevalidate: false };
       }
 
@@ -363,6 +690,8 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
 
       const headers = new Headers(response.headers);
       headers.set(CACHE_STATUS_HEADER, "REVALIDATING");
+      // Stamp when we marked it so the herd guard / re-arm reads a reliable time.
+      headers.set(CACHE_REVALIDATING_AT_HEADER, String(Date.now()));
 
       // Blocking write - must complete before returning to prevent race
       await cache.put(
@@ -370,10 +699,45 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
         new Response(b1, { status: response.status, headers }),
       );
 
-      const data = (await new Response(b2).json()) as CachedEntryData;
+      const bodyStart = Date.now();
+      const data = await this.readJsonWithTimeout<CachedEntryData>(
+        new Response(b2),
+      );
+      const bodyReadMs = Date.now() - bodyStart;
+      if (data === undefined) {
+        this.emitDebug({
+          op: "get",
+          key,
+          outcome: "body-timeout",
+          status: response.status,
+          staleAt,
+          revalidatingAt,
+          ageHeader,
+          isStale,
+          isRevalidating,
+          matchMs,
+          bodyReadMs,
+        });
+        return this.kvGetSegment(key);
+      }
+      this.emitDebug({
+        op: "get",
+        key,
+        outcome: "l1-stale-revalidate",
+        status: response.status,
+        staleAt,
+        revalidatingAt,
+        ageHeader,
+        isStale,
+        isRevalidating,
+        shouldRevalidate: true,
+        matchMs,
+        bodyReadMs,
+      });
       return { data, shouldRevalidate: true };
     } catch (error) {
       console.error("[CFCacheStore] get failed:", error);
+      this.emitDebug({ op: "get", key, outcome: "error" });
       return null;
     }
   }
@@ -421,7 +785,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       }
 
       // L2: persist to KV
-      this.kvSetSegment(key, data, staleAt, totalTtl);
+      this.kvSetSegment(key, data, staleAt, totalTtl, swrWindow);
     } catch (error) {
       console.error("[CFCacheStore] set failed:", error);
     }
@@ -469,7 +833,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     try {
       const cache = await this.getCache();
       const request = this.keyToRequest(`doc:${key}`);
-      const response = await cache.match(request);
+      const response = await this.matchWithTimeout(cache, request);
 
       if (!response || response.status !== 200) {
         return this.kvGetResponse(key);
@@ -480,7 +844,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       const isStale = staleAt > 0 && Date.now() > staleAt;
 
       return {
-        response,
+        response: this.toClientResponse(response),
         shouldRevalidate: isStale,
       };
     } catch (error) {
@@ -489,6 +853,30 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     }
   }
 
+  /**
+   * Strip internal edge headers and restore the author's Cache-Control before a
+   * cached document Response is served to a client. L1 entries carry the
+   * internal staleness/status headers and a rewritten Cache-Control; none of
+   * those should reach the browser or an upstream CDN.
+   */
+  private toClientResponse(response: Response): Response {
+    const headers = new Headers(response.headers);
+    const originalCacheControl = headers.get(CACHE_ORIG_CC_HEADER);
+    if (originalCacheControl !== null) {
+      headers.set("Cache-Control", originalCacheControl);
+    } else {
+      headers.delete("Cache-Control");
+    }
+    headers.delete(CACHE_ORIG_CC_HEADER);
+    headers.delete(CACHE_STALE_AT_HEADER);
+    headers.delete(CACHE_STATUS_HEADER);
+    return new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers,
+    });
+  }
+
   /**
    * Store a Response with TTL and optional SWR window (for document-level caching).
    * When KV is configured, also persists to L2.
@@ -515,8 +903,14 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
           : [null, null]
         : [response.body, null];
 
-      // Clone and add cache headers
+      // Clone and add cache headers. The author's Cache-Control is stashed and
+      // replaced with a long max-age so the CF Cache API holds the entry across
+      // the SWR window; getResponse restores the original before serving.
       const headers = new Headers(response.headers);
+      const originalCacheControl = response.headers.get("Cache-Control");
+      if (originalCacheControl !== null) {
+        headers.set(CACHE_ORIG_CC_HEADER, originalCacheControl);
+      }
       headers.set("Cache-Control", `public, max-age=${totalTtl}`);
       headers.set(CACHE_STALE_AT_HEADER, String(staleAt));
 
@@ -585,26 +979,81 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     try {
       const cache = await this.getCache();
       const request = this.keyToRequest(`fn:${key}`);
-      const response = await cache.match(request);
+      const matchStart = Date.now();
+      const response = await this.matchWithTimeout(cache, request);
+      const matchMs = Date.now() - matchStart;
+
+      if (!response) {
+        this.emitDebug({ op: "getItem", key, outcome: "l1-miss", matchMs });
+        return this.kvGetItem(key);
+      }
 
-      if (!response) return this.kvGetItem(key);
+      // Non-200 entry is not a valid cached function result; treat as a miss.
+      if (response.status !== 200) {
+        this.emitDebug({
+          op: "getItem",
+          key,
+          outcome: "non-200",
+          status: response.status,
+          matchMs,
+        });
+        return this.kvGetItem(key);
+      }
 
       const staleAt = Number(
         response.headers.get(CACHE_STALE_AT_HEADER) ?? "0",
       );
       const status = response.headers.get(CACHE_STATUS_HEADER);
-      const age = Number(response.headers.get("age") ?? "0");
+      const ageHeader = response.headers.get("age");
+      const revalidatingAt = Number(
+        response.headers.get(CACHE_REVALIDATING_AT_HEADER) ?? "0",
+      );
 
       const isStale = staleAt > 0 && Date.now() > staleAt;
+      // Recency from our explicit stamp, not CF's `Age` header (see get()).
       const isRevalidating =
-        status === "REVALIDATING" && age < MAX_REVALIDATION_INTERVAL;
+        status === "REVALIDATING" &&
+        revalidatingAt > 0 &&
+        Date.now() - revalidatingAt < MAX_REVALIDATION_INTERVAL * 1000;
 
-      const data = (await response.json()) as {
+      const bodyStart = Date.now();
+      const data = await this.readJsonWithTimeout<{
         value: string;
-        handles?: Record<string, Record<string, unknown[]>>;
-      };
+        handles?: string;
+      }>(response);
+      const bodyReadMs = Date.now() - bodyStart;
+      if (data === undefined) {
+        this.emitDebug({
+          op: "getItem",
+          key,
+          outcome: "body-timeout",
+          status: response.status,
+          staleAt,
+          revalidatingAt,
+          ageHeader,
+          isStale,
+          isRevalidating,
+          matchMs,
+          bodyReadMs,
+        });
+        return this.kvGetItem(key);
+      }
 
       if (!isStale || isRevalidating) {
+        this.emitDebug({
+          op: "getItem",
+          key,
+          outcome: isRevalidating ? "l1-revalidating-guarded" : "l1-fresh",
+          status: response.status,
+          staleAt,
+          revalidatingAt,
+          ageHeader,
+          isStale,
+          isRevalidating,
+          shouldRevalidate: false,
+          matchMs,
+          bodyReadMs,
+        });
         return {
           value: data.value,
           handles: data.handles,
@@ -615,11 +1064,27 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       // Stale and needs revalidation — mark REVALIDATING atomically
       const headers = new Headers(response.headers);
       headers.set(CACHE_STATUS_HEADER, "REVALIDATING");
+      // Stamp when we marked it so the herd guard / re-arm reads a reliable time.
+      headers.set(CACHE_REVALIDATING_AT_HEADER, String(Date.now()));
       await cache.put(
         request,
         new Response(JSON.stringify(data), { status: 200, headers }),
       );
 
+      this.emitDebug({
+        op: "getItem",
+        key,
+        outcome: "l1-stale-revalidate",
+        status: response.status,
+        staleAt,
+        revalidatingAt,
+        ageHeader,
+        isStale,
+        isRevalidating,
+        shouldRevalidate: true,
+        matchMs,
+        bodyReadMs,
+      });
       return {
         value: data.value,
         handles: data.handles,
@@ -627,6 +1092,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       };
     } catch (error) {
       console.error("[CFCacheStore] getItem failed:", error);
+      this.emitDebug({ op: "getItem", key, outcome: "error" });
       return null;
     }
   }
@@ -706,7 +1172,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     const encodedKey = encodeURIComponent(key);
     // Include version in URL path to invalidate cache when version changes
     const versionPath = this.version ? `v/${this.version}/` : "";
-    return new Request(`${this.baseUrl}${versionPath}${encodedKey}`, {
+    return new Request(`${this.resolveBaseUrl()}${versionPath}${encodedKey}`, {
       method: "GET",
     });
   }
@@ -766,13 +1232,13 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     data: CachedEntryData,
     staleAt: number,
     totalTtl: number,
+    swrWindow: number,
   ): void {
     // KV requires expirationTtl >= 60s. Skip write for short-lived entries.
     if (!this.kv || !this.waitUntil || totalTtl < 60) return;
 
     const kvKey = this.toKVKey(key);
-    const swrWindow = totalTtl * 1000 - (staleAt - Date.now());
-    const expiresAt = staleAt + swrWindow;
+    const expiresAt = staleAt + swrWindow * 1000;
 
     this.waitUntil(async () => {
       try {
@@ -939,6 +1405,10 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
         const request = this.keyToRequest(`doc:${key}`);
 
         const headers = new Headers(envelope.hd);
+        const originalCacheControl = headers.get("Cache-Control");
+        if (originalCacheControl !== null) {
+          headers.set(CACHE_ORIG_CC_HEADER, originalCacheControl);
+        }
         headers.set("Cache-Control", `public, max-age=${remainingTtl}`);
         headers.set(CACHE_STALE_AT_HEADER, String(envelope.s));