@rangojs/router 0.0.0-experimental.e16b7c00 → 0.0.0-experimental.e9c0b2f2

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

@@ -40,6 +40,10 @@ import {
   type RequestContext,
 } from "../../server/request-context.js";
 import { VERSION } from "@rangojs/router:version";
+import {
+  isPerClientSignalHeader,
+  stripPerClientSignals,
+} from "../../browser/cookie-name.js";
 import {
   resolveTtl,
   resolveSwrWindow,
@@ -47,127 +51,76 @@ import {
 } from "../cache-policy.js";
 import { reportCacheError, reportingAsync } from "../cache-error.js";
 import type { CacheErrorCategory } from "../cache-error.js";
+import { bufferToBase64, base64ToBuffer } from "./cf-base64.js";
+import {
+  KV_MAX_KEY_BYTES,
+  KV_MIN_EXPIRATION_TTL,
+  kvKeyByteLength,
+  remainingCacheControl,
+} from "./cf-kv-utils.js";
+import {
+  TAG_MARKER_CACHE_PREFIX,
+  TAG_MARKER_ABSENT,
+  getTagMarkerMemo,
+  getTagMarkerInflight,
+} from "./cf-tag-marker-memo.js";
 
 // ============================================================================
 // Constants
 // ============================================================================
-
-/** Header storing timestamp when entry becomes stale */
-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 this entry's cache tags as a JSON array. JSON-encoded (not the
- * comma-delimited CF `Cache-Tag` format) so tags containing commas round-trip
- * safely; the read paths parse this to run the tag-invalidation check.
- */
-export const CACHE_TAGS_HEADER = "x-edge-cache-tags";
-
-/** Header storing the ms-epoch timestamp when this entry's tags were attached. */
-export const CACHE_TAGGED_AT_HEADER = "x-edge-cache-tagged-at";
-
-/**
- * KV key prefix for tag-invalidation markers. A marker stores the ms-epoch
- * timestamp of the most recent invalidation of a tag; reads treat any entry
- * whose taggedAt is older than its tags' latest marker as invalidated. Markers
- * live in the SAME KV namespace as the cached entries - there is no separate
- * tag-invalidation store.
- */
-const TAG_MARKER_PREFIX = "__tag__/";
-
-/**
- * Cache-API path prefix for the optional per-colo L1 cache of tag-invalidation
- * markers (enabled by tagCacheTtl). Distinct from data keys (doc:/fn:/segment)
- * and from the KV marker prefix so the two never collide.
- */
-const TAG_MARKER_CACHE_PREFIX = "__tagmarker__/";
-
-/**
- * Sentinel body for an L1-cached marker meaning "this tag has no invalidation
- * marker." Distinct from any real ms-epoch timestamp (always a large positive
- * integer). A Cache API miss (match() === undefined) always means "re-read KV",
- * never "no marker" - absence is only ever represented by this cached sentinel.
- */
-const TAG_MARKER_ABSENT = "none";
-
-/**
- * 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.
- * @internal
- */
-export const MAX_REVALIDATION_INTERVAL = 30;
+//
+// Header names, KV prefixes, and timeout/interval defaults live in
+// cf-cache-constants.ts so collaborator modules can share them without a
+// circular import back to this class. They are re-exported below so existing
+// import paths (`../cf-cache-store`, `./cf-cache-store.js`) still resolve.
+import {
+  CACHE_STALE_AT_HEADER,
+  CACHE_STATUS_HEADER,
+  CACHE_TAGS_HEADER,
+  CACHE_TAGGED_AT_HEADER,
+  TAG_MARKER_PREFIX,
+  CACHE_REVALIDATING_AT_HEADER,
+  CACHE_EXPIRES_AT_HEADER,
+  CACHE_ORIG_CC_HEADER,
+  MAX_REVALIDATION_INTERVAL,
+  EDGE_LOOKUP_TIMEOUT_MS,
+  EDGE_READ_TIMEOUT_MS,
+  KV_READ_TIMEOUT_MS,
+} from "./cf-cache-constants.js";
+
+// Re-export the public constants so consumers/tests importing them from
+// cf-cache-store keep working after the move.
+export {
+  CACHE_STALE_AT_HEADER,
+  CACHE_STATUS_HEADER,
+  CACHE_TAGS_HEADER,
+  CACHE_TAGGED_AT_HEADER,
+  TAG_MARKER_PREFIX,
+  CACHE_REVALIDATING_AT_HEADER,
+  MAX_REVALIDATION_INTERVAL,
+  EDGE_LOOKUP_TIMEOUT_MS,
+  EDGE_READ_TIMEOUT_MS,
+  KV_READ_TIMEOUT_MS,
+};
+
+// The tag-marker prefix/sentinel and per-request memo helpers (with their
+// module-singleton WeakMaps) live in cf-tag-marker-memo.ts; imported above.
 
 /**
- * Per-request memo of tag-invalidation markers (tag -> latest invalidatedAt, or
- * null when no marker exists). Keyed by the request context object so it is
- * naturally request-scoped and garbage-collected with the request.
- *
- * Without it, isGloballyInvalidated() issues a KV read per tag on every tagged
- * cache read, so a page composed of many segments/items sharing a tag pays that
- * cost N times. The memo collapses it to one KV read per distinct tag per
- * request. invalidateTags() writes through so a same-request updateTag() stays
- * read-your-own-writes consistent (the action's own re-render sees its own
- * invalidation from the memo, without a re-read).
+ * Per-request memo of the derived cache-key base URL.
  *
- * It does NOT span requests, so a hot single-entry route still pays one KV read
- * per request; that read hits Cloudflare KV's own edge read cache for hot keys.
- */
-const tagMarkerMemo = new WeakMap<object, Map<string, number | null>>();
-
-function getTagMarkerMemo(ctx: object): Map<string, number | null> {
-  let memo = tagMarkerMemo.get(ctx);
-  if (!memo) {
-    memo = new Map();
-    tagMarkerMemo.set(ctx, memo);
-  }
-  return memo;
-}
-
-/**
- * Per-request map of IN-FLIGHT marker reads (tag -> the pending read promise).
- * The resolved-value memo above only collapses SEQUENTIAL reads of a tag; the
- * router resolves sibling segments in PARALLEL, so without this several
- * concurrently-resolving segments sharing a tag would each issue their own KV
- * read before any of them populates the memo. Sharing the in-flight promise
- * collapses those to a single KV read. Entries are dropped once resolved (the
- * value is then in the memo), so this only spans the concurrent read window.
+ * deriveBaseUrl() is a pure function of the live request URL, but keyToRequest
+ * calls it on EVERY cache operation (each segment/item get/set/delete, each
+ * KV->L1 promote, each tag-marker read), so a page composed of many cached
+ * entries re-parses the same request.url and re-runs the host validation tens
+ * of times. Keying by the request-context object collapses that to one derive
+ * per request. Keyed by ctx alone (not by store) because the derived value
+ * depends only on the request URL, not on which store asked.
  */
-const tagMarkerInflight = new WeakMap<
-  object,
-  Map<string, Promise<number | null>>
->();
-
-function getTagMarkerInflight(
-  ctx: object,
-): Map<string, Promise<number | null>> {
-  let inflight = tagMarkerInflight.get(ctx);
-  if (!inflight) {
-    inflight = new Map();
-    tagMarkerInflight.set(ctx, inflight);
-  }
-  return inflight;
-}
-
-/** KV key byte-length ceiling. Cloudflare KV rejects keys larger than this. */
-const KV_MAX_KEY_BYTES = 512;
+const derivedBaseUrlMemo = new WeakMap<object, string>();
 
-const kvKeyEncoder = new TextEncoder();
-
-/** UTF-8 byte length of a KV key (multibyte tags can exceed the char count). */
-function kvKeyByteLength(key: string): number {
-  return kvKeyEncoder.encode(key).length;
-}
+// Pure KV helpers (key byte-length limits, expirationTtl floor, stale-path
+// Cache-Control recompute) live in cf-kv-utils.ts; imported above.
 
 /**
  * Stores (by namespace) already warned about tag machinery configured without a
@@ -176,29 +129,33 @@ function kvKeyByteLength(key: string): number {
  */
 const warnedNoKvReadInvalidation = new Set<string>();
 
+/**
+ * Stores (by namespace) already warned about a tagInvalidationTtl below KV's
+ * expirationTtl floor, so the floor warning fires once per process rather than
+ * once per request (CFCacheStore is constructed per request).
+ */
+const warnedTagInvalidationTtlFloor = new Set<string>();
+
 // ============================================================================
 // Types
 // ============================================================================
-
-// 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.
- * Avoids hard dependency on @cloudflare/workers-types.
- */
-export interface KVNamespace {
-  get(key: string, options?: { type?: string }): Promise<any>;
-  put(
-    key: string,
-    value: string,
-    options?: { expirationTtl?: number },
-  ): Promise<void>;
-  delete(key: string): Promise<void>;
-}
+//
+// The shared public types (KVNamespace, CFCacheReadDebugEvent, CFCacheDebug,
+// CFCacheStoreOptions) live in cf-cache-types.ts; imported and re-exported below
+// so existing import paths still resolve. The private KV envelope interfaces
+// stay here with the methods that read/write them.
+import type {
+  KVNamespace,
+  CFCacheReadDebugEvent,
+  CFCacheDebug,
+  CFCacheStoreOptions,
+} from "./cf-cache-types.js";
+export type {
+  KVNamespace,
+  CFCacheReadDebugEvent,
+  CFCacheDebug,
+  CFCacheStoreOptions,
+};
 
 /**
  * KV envelope for segment cache entries.
@@ -220,8 +177,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) */
@@ -255,181 +212,6 @@ interface KVResponseEnvelope {
   ta?: number;
 }
 
-export interface CFCacheStoreOptions<TEnv = unknown> {
-  /**
-   * Cache namespace. If not provided, uses caches.default (recommended).
-   * Only set this if you need isolated cache storage.
-   */
-  namespace?: string;
-
-  /**
-   * Base URL for cache keys.
-   *
-   * If not provided, derives from request hostname via requestContext:
-   * - Production domains → uses `https://{hostname}/`
-   * - Dev/preview (localhost, workers.dev, pages.dev) → uses internal fallback URL
-   */
-  baseUrl?: string;
-
-  /** Default cache options */
-  defaults?: CacheDefaults;
-
-  /**
-   * Cloudflare ExecutionContext for non-blocking cache writes.
-   * Pass the `ctx` from your worker's fetch handler.
-   *
-   * @example
-   * ```typescript
-   * new CFCacheStore({ ctx: env.ctx })
-   * ```
-   */
-  ctx: ExecutionContext;
-
-  /**
-   * Optional KV namespace for L2 cache persistence.
-   *
-   * When provided, KV acts as a global fallback behind the per-colo Cache API.
-   * On L1 miss, KV is checked and hits are promoted back to L1.
-   * On writes, data is persisted to both L1 and KV.
-   *
-   * @example
-   * ```typescript
-   * new CFCacheStore({ ctx: env.ctx, kv: env.CACHE_KV })
-   * ```
-   *
-   * Tag-based invalidation (updateTag/revalidateTag) requires KV: the
-   * tag-invalidation markers are stored in this same namespace. There is no
-   * separate tag-invalidation store to configure.
-   */
-  kv?: KVNamespace;
-
-  /**
-   * Optional eager-purge hook, called ONCE per updateTag()/revalidateTag() with
-   * the namespaced Cloudflare Cache-Tags to purge (one batched call for the
-   * whole invalidation, not one per tag). These exactly match the `Cache-Tag`
-   * header this store writes on its tag-lookup marker entries
-   * (`rg:{namespace}:lk:{encodedTag}`), so forwarding them to Cloudflare's
-   * purge-by-tag API evicts the cached lookups in every colo - making
-   * cross-colo invalidation prompt instead of waiting out `tagCacheTtl`.
-   *
-   * Only meaningful with `tagCacheTtl > 0` (otherwise there are no cached
-   * lookups to purge). The values are pre-encoded, so commas in tag names are
-   * safe to pass straight to the purge API.
-   *
-   * @example
-   * ```ts
-   * onRevalidateTag: async (cacheTags) => {
-   *   await fetch(`https://api.cloudflare.com/client/v4/zones/${ZONE}/purge_cache`, {
-   *     method: "POST",
-   *     headers: { Authorization: `Bearer ${TOKEN}`, "Content-Type": "application/json" },
-   *     body: JSON.stringify({ tags: cacheTags }),
-   *   });
-   * }
-   * ```
-   */
-  onRevalidateTag?: (cacheTags: string[]) => Promise<void>;
-
-  /**
-   * Optional expiration (seconds) for tag-invalidation markers in KV. A marker
-   * must outlive every entry tagged before the invalidation, so this MUST
-   * exceed your largest entry TTL+SWR. Defaults to no expiration (markers
-   * persist; they are tiny - one timestamp per distinct invalidated tag).
-   *
-   * Note the opposite sizing from `tagCacheTtl` below: `tagInvalidationTtl` must
-   * be LARGE (outlive data); `tagCacheTtl` should be SMALL (a staleness ceiling).
-   *
-   * Cardinality matters: each DISTINCT invalidated tag writes one permanent KV
-   * marker (with the no-expiry default). Keep tags LOW-cardinality and never
-   * derive an invalidation tag from untrusted input (e.g.
-   * `revalidateTag(req.query.tag)`) - an attacker could otherwise grow your KV
-   * namespace without bound. Set a `tagInvalidationTtl` only if your tags are
-   * unavoidably high-cardinality AND it can still safely exceed your max entry
-   * TTL+SWR.
-   */
-  tagInvalidationTtl?: number;
-
-  /**
-   * Optional TTL (seconds) for caching tag-invalidation markers in the per-colo
-   * Cache API (L1), to avoid a KV marker read on every tagged cache read.
-   *
-   * Default `0` = disabled: the marker is read from KV on every tagged read
-   * (today's behavior), giving the strongest cross-colo invalidation latency
-   * (~KV consistency). A positive value caches each marker (including the
-   * "no marker yet" state) in L1 for that many seconds, so within the window a
-   * colo answers from L1 with no KV read.
-   *
-   * The colo that runs `updateTag`/`revalidateTag` writes the fresh marker
-   * straight into its own L1 (write-through), so it observes the invalidation
-   * immediately. By default OTHER colos only converge when their cached marker
-   * expires, so `tagCacheTtl` is the MAXIMUM extra cross-colo invalidation
-   * latency for them. Recommended 30-60 for high-read, low-mutation tags; leave
-   * at 0 when prompt global invalidation matters and you cannot wire a purge.
-   *
-   * To make other colos prompt WITHOUT a short TTL, wire `onRevalidateTag` to a
-   * Cloudflare purge-by-tag call: each marker entry carries a namespaced
-   * `Cache-Tag`, and `onRevalidateTag` is handed exactly those tags to purge, so
-   * the cached lookups are evicted everywhere on invalidation. With a purge
-   * wired, `tagCacheTtl` becomes purely a read-cost reducer + fallback window
-   * (safe to set large) rather than the invalidation-latency ceiling.
-   */
-  tagCacheTtl?: number;
-
-  /**
-   * 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 the `@rangojs/router:version` virtual module.
-   * Only set this if you need a custom versioning strategy.
-   */
-  version?: string;
-
-  /**
-   * Custom key generator applied to all cache operations.
-   * Receives the full RequestContext (including env) and the default-generated key.
-   * Return value becomes the final cache key (unless route overrides with `key` option).
-   *
-   * Reserved prefixes: tag-invalidation markers live in the SAME KV namespace as
-   * data, keyed `__tag__/<tag>` (and `__tagmarker__/<tag>` for the L1 cache). A
-   * returned key must NOT begin with `__tag__/` or `__tagmarker__/`, or it can
-   * collide with a tag marker and corrupt invalidation. The documented
-   * prepend-style generators below are safe.
-   *
-   * @example Using headers for user segmentation
-   * ```typescript
-   * keyGenerator: (ctx, defaultKey) => {
-   *   const segment = ctx.request.headers.get('x-user-segment') || 'default';
-   *   return `${segment}:${defaultKey}`;
-   * }
-   * ```
-   *
-   * @example Using env bindings for multi-region
-   * ```typescript
-   * keyGenerator: (ctx, defaultKey) => {
-   *   const region = ctx.env.REGION || 'us';
-   *   return `${region}:${defaultKey}`;
-   * }
-   * ```
-   *
-   * @example Using cookies for locale-aware caching
-   * ```typescript
-   * keyGenerator: (ctx, defaultKey) => {
-   *   const locale = cookies().get('locale')?.value || 'en';
-   *   return `${locale}:${defaultKey}`;
-   * }
-   * ```
-   */
-  keyGenerator?: (
-    ctx: RequestContext<TEnv>,
-    defaultKey: string,
-  ) => string | Promise<string>;
-}
-
-/**
- * Cache status values for the x-edge-cache-status header.
- * @internal
- */
-export type CacheStatus = "HIT" | "REVALIDATING";
-
 // ============================================================================
 // CFCacheStore Implementation
 // ============================================================================
@@ -442,9 +224,13 @@ 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 kvReadTimeoutMs: number;
+  private readonly debug?: (event: CFCacheReadDebugEvent) => void;
   private readonly kv?: KVNamespace;
   private readonly onRevalidateTag?: (tags: string[]) => Promise<void>;
   private readonly tagInvalidationTtl?: number;
@@ -460,22 +246,71 @@ 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;
+    // Coalesce only finite numbers to the override; a non-finite value (NaN from
+    // `Number(env.UNSET)`, or Infinity) would otherwise sail past `?? DEFAULT`
+    // (which only replaces null/undefined) into setTimeout, where NaN/Infinity
+    // are spec-coerced to ~1ms and silently turn the budget into a near-100%
+    // false-miss on that tier. A genuine finite 0 or negative still passes
+    // through and disables the budget per the documented `<= 0` contract.
+    const finiteBudget = (
+      value: number | undefined,
+      fallback: number,
+    ): number =>
+      typeof value === "number" && Number.isFinite(value) ? value : fallback;
+    this.edgeLookupTimeoutMs = finiteBudget(
+      options.edgeLookupTimeoutMs,
+      EDGE_LOOKUP_TIMEOUT_MS,
+    );
+    this.edgeReadTimeoutMs = finiteBudget(
+      options.edgeReadTimeoutMs,
+      EDGE_READ_TIMEOUT_MS,
+    );
+    this.kvReadTimeoutMs = finiteBudget(
+      options.kvReadTimeoutMs,
+      KV_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;
     this.onRevalidateTag = options.onRevalidateTag;
-    this.tagInvalidationTtl = options.tagInvalidationTtl;
-    this.tagCacheTtl = options.tagCacheTtl ?? 0;
+    // tagInvalidationTtl feeds KV's expirationTtl, which CF rejects below
+    // KV_MIN_EXPIRATION_TTL (60s) -- a too-small finite value would make EVERY
+    // marker write throw and break ALL invalidation. Floor it (and warn once);
+    // a non-finite/non-positive value falls back to the no-expiry default
+    // (markers persist) rather than silently sailing a NaN into expirationTtl.
+    this.tagInvalidationTtl = this.sanitizeTagInvalidationTtl(
+      options.tagInvalidationTtl,
+    );
+    // tagCacheTtl gates the L1 marker cache via `> 0`. A non-finite value (NaN
+    // from `Number(env.UNSET)`) is not null/undefined, so `?? 0` would let it
+    // through and silently disable the cache while reading as "configured".
+    // finiteBudget coerces non-finite/null/undefined to 0; the `> 0` guard then
+    // collapses a finite non-positive value to the documented 0 = disabled.
+    const tagCacheTtl = finiteBudget(options.tagCacheTtl, 0);
+    this.tagCacheTtl = tagCacheTtl > 0 ? tagCacheTtl : 0;
 
     // Read-side tag invalidation requires KV: isGloballyInvalidated() compares an
     // entry's taggedAt against the per-tag KV marker and short-circuits to "not
     // invalidated" when no KV namespace is configured. A consumer who wires the
     // tag machinery (tagCacheTtl for L1 markers, or onRevalidateTag for CDN purge)
-    // but omits kv gets markers written and the purge fired, yet every tagged read
-    // still serves stale data with no other signal. Surface that misconfiguration.
+    // but omits kv gets only the purge fired - marker writes are skipped without
+    // 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)) {
@@ -490,44 +325,113 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     }
   }
 
+  /**
+   * 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
+   * one-time warning) so invalidation keeps working instead of every marker
+   * write throwing; a non-finite or non-positive value returns undefined (the
+   * no-expiry default). The warning still notes the sizing rule: the TTL must
+   * exceed the largest entry TTL+SWR or invalidated entries can resurrect.
+   * @internal
+   */
+  private sanitizeTagInvalidationTtl(
+    value: number | undefined,
+  ): number | undefined {
+    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.`,
+        );
+      }
+      return KV_MIN_EXPIRATION_TTL;
+    }
+    return value;
+  }
+
+  /**
+   * 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) {
       return fallback;
     }
 
-    try {
-      const url = new URL(ctx.request.url);
-      const hostname = url.hostname;
+    // The result is deterministic per request, but keyToRequest calls this on
+    // every cache operation; memoize per request context (see derivedBaseUrlMemo).
+    const memoized = derivedBaseUrlMemo.get(ctx);
+    if (memoized !== undefined) {
+      return memoized;
+    }
 
-      // Use fallback for dev/preview environments
-      if (
-        hostname === "localhost" ||
-        hostname === "127.0.0.1" ||
-        hostname.endsWith(".workers.dev") ||
-        hostname.endsWith(".pages.dev")
-      ) {
-        return fallback;
-      }
+    const derived = ((): string => {
+      try {
+        const url = new URL(ctx.request.url);
+        const hostname = url.hostname;
+
+        // Use fallback for dev/preview environments
+        if (
+          hostname === "localhost" ||
+          hostname === "127.0.0.1" ||
+          hostname.endsWith(".workers.dev") ||
+          hostname.endsWith(".pages.dev")
+        ) {
+          return fallback;
+        }
 
-      // Validate hostname: must be a valid domain (alphanumeric, hyphens, dots)
-      // to prevent host header injection into cache keys
-      if (!/^[a-zA-Z0-9.-]+$/.test(hostname) || hostname.length > 253) {
+        // Validate hostname: must be a valid domain (alphanumeric, hyphens, dots)
+        // to prevent host header injection into cache keys
+        if (!/^[a-zA-Z0-9.-]+$/.test(hostname) || hostname.length > 253) {
+          return fallback;
+        }
+
+        // Use actual hostname for production
+        return `https://${hostname}/`;
+      } catch {
         return fallback;
       }
+    })();
 
-      // Use actual hostname for production
-      return `https://${hostname}/`;
-    } catch {
-      return fallback;
-    }
+    derivedBaseUrlMemo.set(ctx, derived);
+    return derived;
   }
 
   /**
@@ -541,6 +445,260 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     return caches.default;
   }
 
+  /**
+   * Race an async cache read against a latency budget. Shared by all three read
+   * tiers (L1 match, L1 body, L2/KV) so the timeout policy lives in one place:
+   * on timeout it returns `{ value: undefined, timedOut: true }` and logs
+   * `${label} exceeded ${budgetMs}ms; treating as miss`; the abandoned read is
+   * left to settle in the background (late rejection swallowed) rather than
+   * aborted, since the underlying CF primitives expose no cancellation. A budget
+   * <= 0 disables the bound and awaits the read directly. `read` is a thunk so
+   * the disabled path and the raced path start the read identically.
+   * @internal
+   */
+  private async readWithTimeout<T>(
+    read: () => Promise<T>,
+    budgetMs: number,
+    label: string,
+  ): Promise<{ value: T | undefined; timedOut: boolean }> {
+    if (budgetMs <= 0) return { value: await read(), timedOut: false };
+
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const timeout = new Promise<{ timedOut: true }>((resolve) => {
+      timer = setTimeout(() => resolve({ timedOut: true }), budgetMs);
+    });
+    try {
+      const readPromise = read();
+      // The losing branch keeps running; ensure a late rejection can't surface
+      // as an unhandled rejection once we've stopped awaiting it.
+      readPromise.catch(() => {});
+      const result = await Promise.race([
+        readPromise.then((value) => ({ timedOut: false as const, value })),
+        timeout,
+      ]);
+      if (result.timedOut) {
+        console.warn(
+          `[CFCacheStore] ${label} exceeded ${budgetMs}ms; treating as miss`,
+        );
+        return { value: undefined, timedOut: true };
+      }
+      return { value: result.value, timedOut: false };
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+
+  /**
+   * Read from the L1 edge cache under the edgeLookupTimeoutMs budget. A `match`
+   * slower than the budget is abandoned and reported as a miss
+   * (`{ response: undefined, timedOut: true }`) so a degraded colo cannot stall
+   * the request; callers fall through to their normal miss path (L2/KV or
+   * render). The `timedOut` flag lets callers distinguish an abandoned slow
+   * match from a genuine miss for debug reporting; `error` is set when the
+   * `match` itself rejected (a transient L1 infra error) so the caller can
+   * report it as cache-read while still degrading to L2/KV -- distinct from a
+   * genuine miss (no entry), which sets neither flag.
+   * @internal
+   */
+  private async matchWithTimeout(
+    cache: Cache,
+    request: Request,
+  ): Promise<{
+    response: Response | undefined;
+    timedOut: boolean;
+    error?: unknown;
+  }> {
+    let matchError: unknown;
+    const { value, timedOut } = await this.readWithTimeout(
+      // A fast match rejection is caught at the thunk and reported as a miss
+      // (response undefined), so the caller falls through to L2/KV rather than
+      // escaping to the outer catch -- symmetric with the body-read thunk. The
+      // error is captured (not swallowed) so the caller can surface it via
+      // onError as a cache-read degradation.
+      () =>
+        cache.match(request).catch((e) => {
+          matchError = e;
+          return undefined;
+        }),
+      this.edgeLookupTimeoutMs,
+      "edge cache lookup",
+    );
+    return { response: value, timedOut, error: matchError };
+  }
+
+  /**
+   * 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 `undefined` is returned so the caller falls through
+   * to L2/KV or render.
+   * @internal
+   */
+  private async readJsonWithTimeout<T>(
+    response: Response,
+  ): Promise<{ value: T | undefined; errored: boolean; error?: unknown }> {
+    // A FAST json() rejection (a corrupt body, or a foreign 200 non-JSON
+    // response that collided on this key) is caught at the thunk and turned into
+    // a miss, so the caller falls through to L2/KV exactly like a body-timeout
+    // -- instead of escaping to get()/getItem()'s outer catch, which returns
+    // null WITHOUT ever consulting KV. The catch lives here, not in
+    // readWithTimeout, so the L2/KV tier keeps propagating a genuine kv.get
+    // rejection to its own error sink. The `errored` flag lets the caller emit a
+    // distinct "body-error" debug outcome rather than masquerading as a timeout.
+    // On a TIMEOUT the json() promise is still pending, so the catch has not
+    // fired: errored stays false and the outcome is correctly a body-timeout. A
+    // late rejection after the timeout only mutates the closure flag, which the
+    // already-returned object no longer reads.
+    let errored = false;
+    let error: unknown;
+    const { value } = await this.readWithTimeout<T | undefined>(
+      () =>
+        (response.json() as Promise<T>).catch((e) => {
+          errored = true;
+          error = e;
+          return undefined;
+        }),
+      this.edgeReadTimeoutMs,
+      "edge cache body read",
+    );
+    return { value, errored, error };
+  }
+
+  /**
+   * Self-heal a corrupt L1 entry, then return the fall-through result. Reports
+   * the corruption as cache-corrupt (so an onError consumer sees it distinctly
+   * from a transient outage), runs the caller's L2/KV fall-through, and evicts
+   * the faulty per-colo entry ONLY when that fall-through found no good copy.
+   *
+   * The conditional evict is the load-bearing detail: when KV DOES serve a copy,
+   * kvGet* has already scheduled a same-key promote (`cache.put`); an eager
+   * `cache.delete` here would race that put with no CF Cache API ordering
+   * guarantee and could clobber the freshly-restored entry. So in that case we
+   * lean on #558's heal-by-overwrite (the non-suppressed fall-through promotes /
+   * a fresh render re-`set`s over the bad entry) and skip the delete. Only when
+   * this request's fall-through found no copy (=== null) is the eager evict
+   * scheduled -- useful then, since nothing else will overwrite the poison entry.
+   * A null fall-through can also be a KV-read TIMEOUT rather than a genuine miss:
+   * a concurrent request that read KV successfully may be promoting the same key,
+   * and this evict could race it. That is benign -- the worst case is one wasted
+   * colo-local promote, never a wrong served value, and the next read self-heals
+   * -- so we accept it rather than suppressing the evict on a timeout (which
+   * would strand the poison entry when KV really is empty). The evict is
+   * non-blocking (waitUntil) so it never adds latency to the degraded read.
+   * @internal
+   */
+  private async healCorruptL1<T>(
+    cache: Cache,
+    request: Request,
+    error: unknown,
+    label: string,
+    fallThrough: () => Promise<T | null>,
+  ): Promise<T | null> {
+    reportCacheError(
+      error ?? new Error("corrupt/partial L1 body"),
+      "cache-corrupt",
+      `[CFCacheStore] ${label}: corrupt L1 body`,
+    );
+    const result = await fallThrough();
+    if (result === null) {
+      const evict = (): Promise<void> =>
+        reportingAsync(
+          () => cache.delete(request),
+          "cache-delete",
+          `[CFCacheStore] ${label}: evict corrupt L1`,
+        );
+      if (this.waitUntil) this.waitUntil(evict);
+      else void evict();
+    }
+    return result;
+  }
+
+  /**
+   * Re-put a stale L1 entry marked REVALIDATING, so concurrent requests serve it
+   * without each triggering a revalidation. Shared by get()/getItem().
+   *
+   * The write is NON-BLOCKING (waitUntil) and best-effort by design:
+   * - It runs in waitUntil, so it never adds the put latency to the served stale
+   *   read and a put failure can never turn that good read into a miss. The put
+   *   is still initiated synchronously (this.waitUntil invokes its callback
+   *   immediately), so concurrent readers see the marker land at the same time an
+   *   awaited write would -- awaiting only blocks the current request.
+   * - The background revalidation's fresh set() is gated behind a full re-render,
+   *   so it lands well after this put; a stale-clobbers-fresh race would require
+   *   this single put to be slower than that entire render+set, and self-heals
+   *   within MAX_REVALIDATION_INTERVAL.
+   *
+   * Cache-Control is recomputed to the REMAINING ttl from the stored hard-expiry
+   * deadline (see remainingCacheControl), not copied from the original
+   * full-window header -- copying it would restart CF retention on every re-arm
+   * and pin a perpetually-failing entry past hard-expiry. A legacy/tampered entry
+   * without a valid deadline floors to max-age=1 and self-heals via KV.
+   * @internal
+   */
+  private markRevalidating(
+    cache: Cache,
+    request: Request,
+    sourceHeaders: Headers,
+    status: number,
+    body: string,
+  ): void {
+    const reputNow = Date.now();
+    const headers = new Headers(sourceHeaders);
+    headers.set(CACHE_STATUS_HEADER, "REVALIDATING");
+    headers.set(CACHE_REVALIDATING_AT_HEADER, String(reputNow));
+    headers.set("Cache-Control", remainingCacheControl(headers, reputNow));
+    const markerResponse = new Response(body, { status, headers });
+    const write = async (): Promise<void> => {
+      try {
+        await cache.put(request, markerResponse);
+      } catch {
+        // Best-effort: a failed marker write must not affect the served read;
+        // the entry simply re-arms on the next stale read.
+      }
+    };
+    if (this.waitUntil) this.waitUntil(write);
+    else void write();
+  }
+
+  /**
+   * Document-tier counterpart of markRevalidating for getResponse's herd guard.
+   * The segment/item tiers JSON-parse the body, so they re-put with a string
+   * body; document bodies are streamed verbatim, so we re-put with a CLONED
+   * response body (`response.clone()`) supplied by the caller -- the original
+   * body still streams to the client while the marker carries the clone. Same
+   * REVALIDATING status header, same revalidating-at stamp, same
+   * remainingCacheControl re-put math as markRevalidating, so the document tier
+   * suppresses concurrent revalidation for the identical MAX_REVALIDATION_INTERVAL
+   * window the segment tier does. Best-effort and non-blocking: a failed marker
+   * write must not affect the served stale read.
+   * @internal
+   */
+  private markResponseRevalidating(
+    cache: Cache,
+    request: Request,
+    clonedResponse: Response,
+  ): void {
+    const reputNow = Date.now();
+    const headers = new Headers(clonedResponse.headers);
+    headers.set(CACHE_STATUS_HEADER, "REVALIDATING");
+    headers.set(CACHE_REVALIDATING_AT_HEADER, String(reputNow));
+    headers.set("Cache-Control", remainingCacheControl(headers, reputNow));
+    const markerResponse = new Response(clonedResponse.body, {
+      status: clonedResponse.status,
+      statusText: clonedResponse.statusText,
+      headers,
+    });
+    const write = async (): Promise<void> => {
+      try {
+        await cache.put(request, markerResponse);
+      } catch {
+        // Best-effort: see markRevalidating.
+      }
+    };
+    if (this.waitUntil) this.waitUntil(write);
+    else void write();
+  }
+
   // ============================================================================
   // Segment Cache Methods
   // ============================================================================
@@ -594,60 +752,215 @@ 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,
+        timedOut,
+        error: matchError,
+      } = await this.matchWithTimeout(cache, request);
+      const matchMs = Date.now() - matchStart;
 
       if (!response) {
+        // A transient L1 match error (matchError set) is reported as cache-read
+        // but, like a genuine miss or an abandoned slow match (timedOut), still
+        // degrades to L2/KV rather than failing the read.
+        if (matchError)
+          reportCacheError(
+            matchError,
+            "cache-read",
+            "[CFCacheStore] get L1 match",
+          );
+        if (this.debug)
+          this.emitDebug({
+            op: "get",
+            key,
+            // A match REJECTION (matchError) is distinct from a genuine absence:
+            // surface it as match-error so debug agrees with the cache-read
+            // already routed to onError, instead of masquerading as l1-miss.
+            outcome: matchError
+              ? "match-error"
+              : timedOut
+                ? "match-timeout"
+                : "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) {
+        if (this.debug)
+          this.emitDebug({
+            op: "get",
+            key,
+            outcome: "non-200",
+            status: response.status,
+            matchMs,
+          });
+        // Degraded fall-through: suppress revalidation so a broken L1 entry hit
+        // concurrently serves KV-stale, not a herd. See kvGetSegment.
+        return this.kvGetSegment(key, { suppressRevalidate: true });
+      }
+
       // Tag invalidation: an entry whose tags were invalidated after it was
-      // cached is treated as a miss, so the next render re-populates it.
+      // cached is treated as a miss, so the next render re-populates it. We
+      // return null (re-render locally) rather than falling through to KV. In
+      // the common case the L1 entry and its KV twin were written together with
+      // the same taggedAt, so kvGetSegment's own tag check would miss too and a
+      // fall-through is pure cost. The tiers CAN diverge -- another colo may have
+      // already re-rendered and written a fresher KV envelope -- in which case a
+      // fall-through could serve that copy instead of re-rendering here.
+      // Capturing that cross-colo optimization is a deferred follow-up, not a
+      // correctness gap: this colo's next read after its own re-render self-heals.
       const tagInfo = this.readTagInfo(response.headers);
-      if (await this.isGloballyInvalidated(tagInfo.tags, tagInfo.taggedAt)) {
+      // Measure the marker-resolution tail (memo -> L1 marker cache -> KV) only
+      // when debug is on, so the hot path pays nothing. It is the serial read
+      // that sits between matchMs and bodyReadMs for a tagged entry.
+      const markerStart = this.debug ? Date.now() : 0;
+      const invalidated = await this.isGloballyInvalidated(
+        tagInfo.tags,
+        tagInfo.taggedAt,
+      );
+      const markerMs = this.debug ? Date.now() - markerStart : undefined;
+      if (invalidated) {
+        if (this.debug)
+          this.emitDebug({
+            op: "get",
+            key,
+            outcome: "tag-invalidated",
+            status: response.status,
+            matchMs,
+            markerMs,
+          });
         return null;
       }
 
       // Read status headers
       const status = response.headers.get(CACHE_STATUS_HEADER);
-      const age = Number(response.headers.get("age") ?? "0");
       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;
+      const now = Date.now();
+      const isStale = staleAt > 0 && 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 &&
+        now - revalidatingAt < MAX_REVALIDATION_INTERVAL * 1000;
+
+      // Single emitter for the post-header L1 outcomes. Undefined (so the event
+      // object is never allocated) when debug is off; the informational-only
+      // `age` header is read lazily inside for the same reason.
+      const debugRead = this.debug
+        ? (
+            outcome: CFCacheReadDebugEvent["outcome"],
+            bodyReadMs: number,
+            shouldRevalidate?: boolean,
+          ) =>
+            this.emitDebug({
+              op: "get",
+              key,
+              outcome,
+              status: response.status,
+              cacheStatus: status,
+              staleAt,
+              revalidatingAt,
+              ageHeader: response.headers.get("age"),
+              isStale,
+              isRevalidating,
+              shouldRevalidate,
+              matchMs,
+              markerMs,
+              bodyReadMs,
+            })
+        : undefined;
 
       // Case 1: Fresh or already being revalidated - just return data
       if (!isStale || isRevalidating) {
-        const data = await this.parseOrEvict<CachedEntryData>(
-          () => response.json() as Promise<CachedEntryData>,
-          () => cache.delete(request),
-          "get",
+        const bodyStart = Date.now();
+        const {
+          value: data,
+          errored,
+          error,
+        } = await this.readJsonWithTimeout<CachedEntryData>(response);
+        const bodyReadMs = Date.now() - bodyStart;
+        if (data === undefined) {
+          debugRead?.(errored ? "body-error" : "body-timeout", bodyReadMs);
+          // A body-ERROR (corrupt/foreign body) self-heals via healCorruptL1:
+          // report cache-corrupt, fall through to L2/KV (which overwrites the
+          // bad entry), and evict only if KV had no good copy to promote. A
+          // body-TIMEOUT is a degraded read of a likely-valid entry: leave it
+          // intact and suppress revalidation so a stalling colo cannot herd.
+          if (errored)
+            return this.healCorruptL1(cache, request, error, "get", () =>
+              this.kvGetSegment(key, { suppressRevalidate: false }),
+            );
+          return this.kvGetSegment(key, { suppressRevalidate: true });
+        }
+        debugRead?.(
+          isRevalidating ? "l1-revalidating-guarded" : "l1-fresh",
+          bodyReadMs,
+          false,
         );
-        return data === null ? null : { data, shouldRevalidate: false };
+        return { data, shouldRevalidate: false };
       }
 
-      // Case 2: Stale and needs revalidation - atomically mark REVALIDATING
-      const [b1, b2] = response.body!.tee();
-
-      const headers = new Headers(response.headers);
-      headers.set(CACHE_STATUS_HEADER, "REVALIDATING");
+      // Case 2: Stale and needs revalidation.
+      // Read the body under the edge-read budget BEFORE writing the REVALIDATING
+      // marker. CF can resolve match() fast but stall the body stream; the prior
+      // approach teed the stream and awaited cache.put(b1) first, which blocked
+      // on that same stalled stream so the read budget could never fire on a
+      // stale hit. Reading first bounds the stall and lets us skip marking an
+      // entry we could not even read.
+      const bodyStart = Date.now();
+      const {
+        value: data,
+        errored,
+        error,
+      } = await this.readJsonWithTimeout<CachedEntryData>(response);
+      const bodyReadMs = Date.now() - bodyStart;
+      if (data === undefined) {
+        debugRead?.(errored ? "body-error" : "body-timeout", bodyReadMs);
+        // Heal + conditionally evict a body-error, suppress a body-timeout; see
+        // Case 1.
+        if (errored)
+          return this.healCorruptL1(
+            cache,
+            request,
+            error,
+            "get(revalidating)",
+            () => this.kvGetSegment(key, { suppressRevalidate: false }),
+          );
+        return this.kvGetSegment(key, { suppressRevalidate: true });
+      }
 
-      // Blocking write - must complete before returning to prevent race
-      await cache.put(
+      // Mark REVALIDATING so concurrent requests don't all revalidate, then
+      // return the stale data. The marker write is non-blocking and best-effort
+      // (see markRevalidating) -- it must not add latency to, or fail, the served
+      // stale read.
+      this.markRevalidating(
+        cache,
         request,
-        new Response(b1, { status: response.status, headers }),
+        response.headers,
+        response.status,
+        JSON.stringify(data),
       );
 
-      const data = await this.parseOrEvict<CachedEntryData>(
-        () => new Response(b2).json() as Promise<CachedEntryData>,
-        () => cache.delete(request),
-        "get(revalidating)",
-      );
-      return data === null ? null : { data, shouldRevalidate: true };
+      debugRead?.("l1-stale-revalidate", bodyReadMs, true);
+      return { data, shouldRevalidate: true };
     } catch (error) {
+      // reportCacheError logs and routes to onError (cache-read); the debug
+      // emit is the separate wrangler-tail signal. Keep both observability paths.
       reportCacheError(error, "cache-read", "[CFCacheStore] get");
+      if (this.debug) this.emitDebug({ op: "get", key, outcome: "error" });
       return null;
     }
   }
@@ -677,7 +990,9 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       // into both the L1 body and the KV envelope so reads can run the
       // invalidation check.
       const taggedAt =
-        data.tags && data.tags.length > 0 ? Date.now() : undefined;
+        Array.isArray(data.tags) && data.tags.length > 0
+          ? Date.now()
+          : undefined;
       const dataToStore: CachedEntryData = taggedAt
         ? { ...data, taggedAt }
         : data;
@@ -688,6 +1003,10 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
           "Content-Type": "application/json",
           "Cache-Control": `public, max-age=${totalTtl}`,
           [CACHE_STALE_AT_HEADER]: String(staleAt),
+          // Absolute hard-expiry deadline so a stale-path re-put can recompute a
+          // shrinking max-age instead of restarting retention (see
+          // remainingCacheControl / CACHE_EXPIRES_AT_HEADER).
+          [CACHE_EXPIRES_AT_HEADER]: String(staleAt + swrWindow * 1000),
           [CACHE_STATUS_HEADER]: "HIT",
           ...this.tagHeaderEntries(dataToStore.tags, taggedAt),
         },
@@ -764,9 +1083,26 @@ 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);
+      // The document path is outside the debug surface (op is only get/getItem),
+      // so the match-timeout flag is not surfaced as an event here -- though
+      // matchWithTimeout still warns on a slow match. A miss or timeout falls
+      // through to the KV document path and then render.
+      const { response, error: matchError } = await this.matchWithTimeout(
+        cache,
+        request,
+      );
 
       if (!response || response.status !== 200) {
+        // A transient L1 match rejection (matchError set; only ever set when
+        // response is undefined) is surfaced as cache-read before degrading to
+        // L2/KV -- matching get()/getItem(). A genuine miss or a non-200 hit
+        // carries no matchError and reports nothing.
+        if (matchError)
+          reportCacheError(
+            matchError,
+            "cache-read",
+            "[CFCacheStore] getResponse L1 match",
+          );
         return this.kvGetResponse(key);
       }
 
@@ -778,7 +1114,23 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
 
       // Check staleness
       const staleAt = Number(response.headers.get(CACHE_STALE_AT_HEADER) || 0);
-      const isStale = staleAt > 0 && Date.now() > staleAt;
+      const now = Date.now();
+      const isStale = staleAt > 0 && now > staleAt;
+
+      // Thundering-herd guard, mirroring the segment (get) and item (getItem)
+      // tiers. Without it, every concurrent stale reader returned
+      // shouldRevalidate=true and document-cache.ts scheduled a fresh render for
+      // each one. Recency comes from our own 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 status = response.headers.get(CACHE_STATUS_HEADER);
+      const revalidatingAt = Number(
+        response.headers.get(CACHE_REVALIDATING_AT_HEADER) ?? "0",
+      );
+      const isRevalidating =
+        status === "REVALIDATING" &&
+        revalidatingAt > 0 &&
+        now - revalidatingAt < MAX_REVALIDATION_INTERVAL * 1000;
 
       // L1 document bodies are streamed through verbatim - unlike the segment/
       // item tiers (which JSON-parse and so structurally detect corruption) and
@@ -787,9 +1139,25 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       // response atomically or fails, so a truncated body is not served back. We
       // deliberately do NOT buffer+hash the body to re-verify it: that would
       // defeat streaming the document and add a full read to every cache hit.
+
+      if (isStale && !isRevalidating) {
+        // First stale reader within the window: mark REVALIDATING (non-blocking,
+        // best-effort) so concurrent readers below see the guard and suppress,
+        // then return shouldRevalidate=true so this caller revalidates. Clone the
+        // matched response for the marker since its original body must still
+        // stream to the client.
+        this.markResponseRevalidating(cache, request, response.clone());
+        return {
+          response: this.toClientResponse(response),
+          shouldRevalidate: true,
+        };
+      }
+
+      // Fresh, or stale-but-already-REVALIDATING: serve without scheduling a
+      // (re-)revalidation. A recent marker already has a render in flight.
       return {
         response: this.toClientResponse(response),
-        shouldRevalidate: isStale,
+        shouldRevalidate: false,
       };
     } catch (error) {
       reportCacheError(error, "cache-read", "[CFCacheStore] getResponse");
@@ -816,6 +1184,13 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     headers.delete(CACHE_STATUS_HEADER);
     headers.delete(CACHE_TAGS_HEADER);
     headers.delete(CACHE_TAGGED_AT_HEADER);
+    // Internal stale-path bookkeeping (hard-expiry deadline + REVALIDATING
+    // stamp). Carried on doc L1 entries for the herd guard; never serve them.
+    headers.delete(CACHE_EXPIRES_AT_HEADER);
+    headers.delete(CACHE_REVALIDATING_AT_HEADER);
+    // Finding #3 (read side): strip per-client signals a pre-fix or
+    // pinned-version L1 entry may carry. See the read-side note in the design doc.
+    stripPerClientSignals(headers);
     return new Response(response.body, {
       status: response.status,
       statusText: response.statusText,
@@ -842,7 +1217,8 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       const swrWindow = resolveSwrWindow(swr, this.defaults);
       const totalTtl = ttl + swrWindow;
       const staleAt = Date.now() + ttl * 1000;
-      const taggedAt = tags && tags.length > 0 ? Date.now() : undefined;
+      const taggedAt =
+        Array.isArray(tags) && tags.length > 0 ? Date.now() : undefined;
 
       // Clone body for potential KV write before consuming it for L1
       const [l1Body, kvBody] = this.kv
@@ -855,17 +1231,23 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       // 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);
+      // Finding #3: never persist a per-client signal in the shared L1 entry
+      // (the platform's Set-Cookie rejection is unverified and ignores the
+      // directive anyway). See stripPerClientSignals.
+      stripPerClientSignals(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));
+      // Absolute hard-expiry deadline so a stale-path REVALIDATING re-put can
+      // recompute a shrinking max-age (remainingCacheControl) instead of
+      // restarting retention. Mirrors set()/setItem(). Stripped by
+      // toClientResponse before serving.
+      headers.set(CACHE_EXPIRES_AT_HEADER, String(staleAt + swrWindow * 1000));
       // Internal tag headers (stripped by toClientResponse before serving).
-      const tagHeaders = this.tagHeaderEntries(tags, taggedAt);
-      for (const [name, value] of Object.entries(tagHeaders)) {
-        headers.set(name, value);
-      }
+      this.setTagHeaders(headers, tags, taggedAt);
 
       const toCache = new Response(l1Body, {
         status: response.status,
@@ -891,9 +1273,13 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
 
       // L2: persist to KV (KV requires expirationTtl >= 60s)
       if (this.kv && this.waitUntil && totalTtl >= 60) {
-        const kvKey = this.toKVKey(`doc:${key}`);
+        const kvKey = this.toDocKVKey(key);
+        // Finding #3: never persist a per-client signal in the KV envelope.
         const headersArray: [string, string][] = [];
-        response.headers.forEach((v, k) => headersArray.push([k, v]));
+        response.headers.forEach((v, k) => {
+          if (isPerClientSignalHeader(k)) return;
+          headersArray.push([k, v]);
+        });
         // Read body as ArrayBuffer and encode to base64 to preserve binary payloads
         const bodyBuf = kvBody
           ? await new Response(kvBody).arrayBuffer()
@@ -940,13 +1326,71 @@ 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,
+        timedOut,
+        error: matchError,
+      } = await this.matchWithTimeout(cache, request);
+      const matchMs = Date.now() - matchStart;
 
-      if (!response) return this.kvGetItem(key);
+      if (!response) {
+        // Transient match error reported cache-read; still degrades to L2/KV.
+        if (matchError)
+          reportCacheError(
+            matchError,
+            "cache-read",
+            "[CFCacheStore] getItem L1 match",
+          );
+        if (this.debug)
+          this.emitDebug({
+            op: "getItem",
+            key,
+            // match-error (rejection) vs l1-miss (absence); see get().
+            outcome: matchError
+              ? "match-error"
+              : timedOut
+                ? "match-timeout"
+                : "l1-miss",
+            matchMs,
+          });
+        return this.kvGetItem(key);
+      }
 
-      // Tag invalidation check (treat invalidated entry as a miss).
+      // Non-200 entry is not a valid cached function result; treat as a miss.
+      if (response.status !== 200) {
+        if (this.debug)
+          this.emitDebug({
+            op: "getItem",
+            key,
+            outcome: "non-200",
+            status: response.status,
+            matchMs,
+          });
+        // Degraded fall-through: suppress revalidation so a broken L1 entry hit
+        // concurrently serves KV-stale instead of spawning a herd (see get()).
+        return this.kvGetItem(key, { suppressRevalidate: true });
+      }
+
+      // Tag invalidation check (treat invalidated entry as a miss). Measure the
+      // marker-resolution tail only under debug (see get()).
       const tagInfo = this.readTagInfo(response.headers);
-      if (await this.isGloballyInvalidated(tagInfo.tags, tagInfo.taggedAt)) {
+      const markerStart = this.debug ? Date.now() : 0;
+      const invalidated = await this.isGloballyInvalidated(
+        tagInfo.tags,
+        tagInfo.taggedAt,
+      );
+      const markerMs = this.debug ? Date.now() - markerStart : undefined;
+      if (invalidated) {
+        if (this.debug)
+          this.emitDebug({
+            op: "getItem",
+            key,
+            outcome: "tag-invalidated",
+            status: response.status,
+            matchMs,
+            markerMs,
+          });
         return null;
       }
 
@@ -954,27 +1398,72 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
         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 revalidatingAt = Number(
+        response.headers.get(CACHE_REVALIDATING_AT_HEADER) ?? "0",
+      );
 
-      const isStale = staleAt > 0 && Date.now() > staleAt;
+      const now = Date.now();
+      const isStale = staleAt > 0 && now > staleAt;
+      // Recency from our explicit stamp, not CF's `Age` header (see get()).
       const isRevalidating =
-        status === "REVALIDATING" && age < MAX_REVALIDATION_INTERVAL;
-
-      const data = await this.parseOrEvict<{
+        status === "REVALIDATING" &&
+        revalidatingAt > 0 &&
+        now - revalidatingAt < MAX_REVALIDATION_INTERVAL * 1000;
+
+      // Single emitter for the post-header L1 outcomes (see get()). Undefined
+      // when debug is off, so the event object is never allocated on the hot
+      // path; the informational-only `age` header is read lazily inside.
+      const debugRead = this.debug
+        ? (
+            outcome: CFCacheReadDebugEvent["outcome"],
+            bodyReadMs: number,
+            shouldRevalidate?: boolean,
+          ) =>
+            this.emitDebug({
+              op: "getItem",
+              key,
+              outcome,
+              status: response.status,
+              cacheStatus: status,
+              staleAt,
+              revalidatingAt,
+              ageHeader: response.headers.get("age"),
+              isStale,
+              isRevalidating,
+              shouldRevalidate,
+              matchMs,
+              markerMs,
+              bodyReadMs,
+            })
+        : undefined;
+
+      const bodyStart = Date.now();
+      const {
+        value: data,
+        errored,
+        error,
+      } = await this.readJsonWithTimeout<{
         value: string;
-        handles?: Record<string, Record<string, unknown[]>>;
-      }>(
-        () =>
-          response.json() as Promise<{
-            value: string;
-            handles?: Record<string, Record<string, unknown[]>>;
-          }>,
-        () => cache.delete(request),
-        "getItem",
-      );
-      if (data === null) return null;
+        handles?: string;
+      }>(response);
+      const bodyReadMs = Date.now() - bodyStart;
+      if (data === undefined) {
+        debugRead?.(errored ? "body-error" : "body-timeout", bodyReadMs);
+        // Heal + conditionally evict a body-error, suppress a body-timeout; see
+        // get().
+        if (errored)
+          return this.healCorruptL1(cache, request, error, "getItem", () =>
+            this.kvGetItem(key, { suppressRevalidate: false }),
+          );
+        return this.kvGetItem(key, { suppressRevalidate: true });
+      }
 
       if (!isStale || isRevalidating) {
+        debugRead?.(
+          isRevalidating ? "l1-revalidating-guarded" : "l1-fresh",
+          bodyReadMs,
+          false,
+        );
         return {
           value: data.value,
           handles: data.handles,
@@ -983,14 +1472,18 @@ 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");
-      await cache.put(
+      // Stale and needs revalidation -- mark REVALIDATING (non-blocking,
+      // best-effort, remaining-ttl) and return the stale value. See get() /
+      // markRevalidating for the full rationale.
+      this.markRevalidating(
+        cache,
         request,
-        new Response(JSON.stringify(data), { status: 200, headers }),
+        response.headers,
+        200,
+        JSON.stringify(data),
       );
 
+      debugRead?.("l1-stale-revalidate", bodyReadMs, true);
       return {
         value: data.value,
         handles: data.handles,
@@ -999,6 +1492,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       };
     } catch (error) {
       reportCacheError(error, "cache-read", "[CFCacheStore] getItem");
+      if (this.debug) this.emitDebug({ op: "getItem", key, outcome: "error" });
       return null;
     }
   }
@@ -1022,7 +1516,8 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       const staleAt = Date.now() + ttl * 1000;
 
       const tags = options?.tags;
-      const taggedAt = tags && tags.length > 0 ? Date.now() : undefined;
+      const taggedAt =
+        Array.isArray(tags) && tags.length > 0 ? Date.now() : undefined;
 
       const body = JSON.stringify({ value, handles: options?.handles });
       const response = new Response(body, {
@@ -1030,6 +1525,8 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
           "Content-Type": "application/json",
           "Cache-Control": `public, max-age=${totalTtl}`,
           [CACHE_STALE_AT_HEADER]: String(staleAt),
+          // Absolute hard-expiry deadline; see set() / remainingCacheControl.
+          [CACHE_EXPIRES_AT_HEADER]: String(staleAt + swrWindow * 1000),
           [CACHE_STATUS_HEADER]: "HIT",
           ...this.tagHeaderEntries(tags, taggedAt),
         },
@@ -1090,7 +1587,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",
     });
   }
@@ -1106,41 +1603,36 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   }
 
   /**
-   * Parse a stored entry, EVICTING it if the parse fails. A parse failure means
-   * the entry is corrupt or partial (truncated Cache API body, malformed KV
-   * envelope/base64) - it would deterministically fail every future read - so it
-   * is deleted to self-heal (the next read misses and re-renders) and reported as
-   * cache-corrupt. This is distinct from a transient infra error (the caller's
-   * outer catch reports cache-read and does NOT delete a still-good entry).
-   * Returns null on corruption; the caller treats null as a miss.
+   * Host token for the current request, used to namespace the document KV key.
+   * Derived from the same resolveBaseUrl() that namespaces the L1 (Cache API)
+   * tier, so a doc entry's KV twin lands under the identical host bucket.
+   * Falls back to "_" if the base URL cannot be parsed (it always carries a
+   * trailing-slash origin, so parsing succeeds in practice).
    * @internal
    */
-  private async parseOrEvict<T>(
-    parse: () => Promise<T> | T,
-    evict: () => Promise<unknown>,
-    label: string,
-  ): Promise<T | null> {
+  private docKVHost(): string {
     try {
-      return await parse();
-    } catch (error) {
-      reportCacheError(
-        error,
-        "cache-corrupt",
-        `[CFCacheStore] ${label}: corrupt/partial entry, evicting`,
-      );
-      try {
-        await evict();
-      } catch (evictError) {
-        reportCacheError(
-          evictError,
-          "cache-delete",
-          `[CFCacheStore] ${label}: evicting corrupt entry failed`,
-        );
-      }
-      return null;
+      return new URL(this.resolveBaseUrl()).host || "_";
+    } catch {
+      return "_";
     }
   }
 
+  /**
+   * Convert a document key to its host-namespaced KV key. The L1 tier already
+   * namespaces document entries by host via keyToRequest/resolveBaseUrl, but the
+   * KV fallback keyed only on `doc:{key}`, so two hosts serving the same path
+   * could collide on the KV tier (one host serving another's cached document).
+   * Prefixing the host closes that cross-host collision. Deterministic per
+   * (host, key). Segment/fn/tag-marker KV keys keep toKVKey unchanged: tag
+   * markers are intentionally global (invalidation must cross hosts), and the
+   * document tier is the one with a request-host context here.
+   * @internal
+   */
+  private toDocKVKey(key: string): string {
+    return this.toKVKey(`h/${this.docKVHost()}/doc:${key}`);
+  }
+
   /**
    * Best-effort delete of a single KV key, reporting (not swallowing) a delete
    * failure as cache-delete. Used by the corrupt-entry self-heal paths.
@@ -1158,6 +1650,21 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     }
   }
 
+  /**
+   * Schedule a corrupt-entry KV eviction as a NON-BLOCKING background task
+   * (waitUntil) instead of awaiting it on the request path. The corrupt read has
+   * already resolved to a miss; awaiting an unbounded kv.delete here would re-add
+   * exactly the multi-second stall the read budgets exist to prevent when the KV
+   * namespace is degraded. evictKvKey never rejects (it reports its own failure),
+   * so the fire-and-forget fallback is safe when no waitUntil is available.
+   * @internal
+   */
+  private scheduleKvEvict(kvKey: string, label: string): void {
+    const evict = (): Promise<void> => this.evictKvKey(kvKey, label);
+    if (this.waitUntil) this.waitUntil(evict);
+    else void evict();
+  }
+
   /**
    * KV-get a JSON envelope, EVICTING the key only when it is genuinely corrupt.
    *
@@ -1176,35 +1683,61 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     kvKey: string,
     validate: (envelope: T) => boolean,
     label: string,
-  ): Promise<T | null> {
-    // A transient error here throws and is reported cache-read (no eviction) by
-    // the caller's outer catch - deliberately NOT caught as corruption.
-    const text = await this.kv!.get(kvKey, { type: "text" });
-    if (text == null) return null; // missing key = miss, not corruption
-
-    let raw: T;
-    try {
-      raw = JSON.parse(text) as T;
-    } catch (error) {
-      reportCacheError(
-        error,
-        "cache-corrupt",
-        `[CFCacheStore] ${label}: corrupt JSON in KV, evicting`,
-      );
-      await this.evictKvKey(kvKey, label);
-      return null;
+  ): Promise<{ value: T | null; timedOut: boolean }> {
+    // Bound the read with the KV latency budget (inherited from #558) so a
+    // degraded namespace cannot pin the request. readWithTimeout reports
+    // timedOut on budget expiry; a transient read REJECTION (5xx/429/network)
+    // instead propagates out to the caller's outer catch (reported cache-read,
+    // the entry left intact) -- deliberately NOT caught as corruption.
+    const { value: raw, timedOut } = await this.readWithTimeout<unknown>(
+      () => this.kv!.get(kvKey, { type: "text" }),
+      this.kvReadTimeoutMs,
+      "KV read",
+    );
+    if (timedOut) return { value: null, timedOut: true };
+    if (raw == null) return { value: null, timedOut: false }; // missing = miss
+
+    // Real CF KV with { type: "text" } returns a string: parse + structurally
+    // validate it; a parse/validate failure on a successfully-read body is the
+    // only true corruption (evict + cache-corrupt). A KV binding that already
+    // returns a parsed object (some shims/tests) is used as-is.
+    let envelope: T;
+    if (typeof raw === "string") {
+      try {
+        envelope = JSON.parse(raw) as T;
+      } catch (error) {
+        reportCacheError(
+          error,
+          "cache-corrupt",
+          `[CFCacheStore] ${label}: corrupt JSON in KV, evicting`,
+        );
+        this.scheduleKvEvict(kvKey, label);
+        return { value: null, timedOut: false };
+      }
+    } else {
+      envelope = raw as T;
     }
 
-    if (!validate(raw)) {
+    // A body that parses to null or a primitive ('null', '42', 'true', '"x"')
+    // is not a valid envelope. Guard it BEFORE validate(): the property-reading
+    // validators throw on a null/primitive rather than returning false, which
+    // would escape to the caller's outer catch as a transient cache-read and
+    // leave the bad key un-evicted (re-failing every read until its KV TTL). The
+    // typeof check short-circuits validate() so it only ever runs on an object.
+    if (
+      envelope == null ||
+      typeof envelope !== "object" ||
+      !validate(envelope)
+    ) {
       reportCacheError(
         new Error("malformed/partial KV envelope"),
         "cache-corrupt",
         `[CFCacheStore] ${label}: malformed envelope, evicting`,
       );
-      await this.evictKvKey(kvKey, label);
-      return null;
+      this.scheduleKvEvict(kvKey, label);
+      return { value: null, timedOut: false };
     }
-    return raw;
+    return { value: envelope, timedOut: false };
   }
 
   // ============================================================================
@@ -1225,7 +1758,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     tags: string[] | undefined,
     taggedAt: number | undefined,
   ): Record<string, string> {
-    if (!tags || tags.length === 0 || !taggedAt) return {};
+    if (!Array.isArray(tags) || tags.length === 0 || !taggedAt) return {};
     return {
       // encodeURIComponent so the value is pure ASCII: HTTP header values are
       // ByteStrings, but JSON.stringify leaves codepoints > U+00FF (emoji/CJK)
@@ -1237,6 +1770,24 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     };
   }
 
+  /**
+   * Merge the internal tag headers onto an existing Headers instance. The
+   * from-scratch paths spread tagHeaderEntries() into an object-literal init;
+   * the document put/promote paths build a Headers first, so they .set() each
+   * entry instead.
+   */
+  private setTagHeaders(
+    headers: Headers,
+    tags: string[] | undefined,
+    taggedAt: number | undefined,
+  ): void {
+    for (const [name, value] of Object.entries(
+      this.tagHeaderEntries(tags, taggedAt),
+    )) {
+      headers.set(name, value);
+    }
+  }
+
   /** Read an entry's tags/taggedAt back from its headers. */
   private readTagInfo(headers: Headers): {
     tags?: string[];
@@ -1246,9 +1797,17 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     const rawTaggedAt = headers.get(CACHE_TAGGED_AT_HEADER);
     if (!rawTags || !rawTaggedAt) return {};
     try {
+      const taggedAt = Number(rawTaggedAt);
+      // A corrupt/non-numeric tagged-at header yields NaN. isGloballyInvalidated
+      // short-circuits on a falsy taggedAt (NaN is falsy), so returning
+      // { taggedAt: NaN } would make the entry permanently NON-invalidatable -
+      // a revalidateTag could never evict it. Treat a non-finite stamp the same
+      // as the missing-header case (untagged): drop both tags and taggedAt so the
+      // entry is re-rendered/re-tagged rather than silently un-invalidatable.
+      if (!Number.isFinite(taggedAt)) return {};
       return {
         tags: JSON.parse(decodeURIComponent(rawTags)) as string[],
-        taggedAt: Number(rawTaggedAt),
+        taggedAt,
       };
     } catch {
       return {};
@@ -1266,10 +1825,15 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     tags: string[] | undefined,
     taggedAt: number | undefined,
   ): Promise<boolean> {
-    if (!this.kv || !tags || tags.length === 0 || !taggedAt) return false;
+    // Array.isArray (not just truthiness): a non-array tags value - direct store
+    // misuse like setItem(k, v, { tags: "products" }), or a skewed KV envelope -
+    // must fail safe to "not invalidated" rather than throwing `.map` on every
+    // read (which the outer catch would mis-report as a transient cache-read).
+    if (!this.kv || !Array.isArray(tags) || tags.length === 0 || !taggedAt)
+      return false;
     const ctx = _getRequestContext();
-    const memo = ctx ? getTagMarkerMemo(ctx) : undefined;
-    const inflight = ctx ? getTagMarkerInflight(ctx) : undefined;
+    const memo = ctx ? getTagMarkerMemo(ctx, this) : undefined;
+    const inflight = ctx ? getTagMarkerInflight(ctx, this) : undefined;
     try {
       const markers = await Promise.all(
         tags.map((tag) => this.readTagMarker(tag, memo, inflight)),
@@ -1340,34 +1904,81 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     tag: string,
     memo: Map<string, number | null> | undefined,
   ): Promise<number | null> {
-    // L1 (per-colo) marker cache - opt-in via tagCacheTtl.
+    // Write the resolved marker into the memo WITHOUT clobbering a value a
+    // concurrent invalidateTags() wrote during our await. The router resolves
+    // sibling slots in parallel, so a slot's updateTag() can land the
+    // authoritative invalidatedAt into the memo while this read is still in
+    // flight; overwriting it with our (pre-invalidation) read result would break
+    // read-your-own-writes for the rest of the request. If the tag was memoized
+    // mid-read, that value wins and is returned. Without a memo, the read result
+    // stands as-is.
+    const memoize = (read: number | null): number | null => {
+      if (memo && memo.has(tag)) return memo.get(tag) ?? null;
+      memo?.set(tag, read);
+      return read;
+    };
+
+    // L1 (per-colo) marker cache - opt-in via tagCacheTtl. Bounded by the same
+    // edge budgets as data reads (inherited from #558) so a degraded colo cannot
+    // stall a tagged read; a miss, timeout, or error all fall through to KV.
     if (this.tagCacheTtl > 0) {
       try {
         const cache = await this.getCache();
-        const hit = await cache.match(this.tagMarkerRequest(tag));
+        const { response: hit, error: matchError } =
+          await this.matchWithTimeout(cache, this.tagMarkerRequest(tag));
+        // A transient match REJECTION is captured (not thrown) by
+        // matchWithTimeout; surface it as cache-read like the data read paths
+        // before falling through to KV, rather than silently dropping it.
+        if (matchError)
+          reportCacheError(
+            matchError,
+            "cache-read",
+            "[CFCacheStore] tag marker L1 match",
+          );
         if (hit) {
-          const body = await hit.text();
-          const value = body === TAG_MARKER_ABSENT ? null : Number(body);
-          memo?.set(tag, value);
-          return value;
+          const { value: body } = await this.readWithTimeout(
+            () => hit.text(),
+            this.edgeReadTimeoutMs,
+            "tag marker L1 body read",
+          );
+          if (body !== undefined) {
+            const value = body === TAG_MARKER_ABSENT ? null : Number(body);
+            return memoize(value);
+          }
         }
       } catch {
         // Fall through to KV on any L1 read error.
       }
     }
 
-    // KV (global truth).
-    const raw = await this.kv!.get(this.tagMarkerKey(tag), { type: "text" });
+    // KV (global truth), bounded by the KV budget. On TIMEOUT fail OPEN: treat
+    // the marker as absent (-> entry not invalidated -> served) so a degraded
+    // namespace cannot pin every tagged read behind a slow global lookup. A
+    // transient REJECTION instead propagates to isGloballyInvalidated's catch
+    // (reported cache-read), which also fails open. Either way one slow tag
+    // never amplifies into a per-segment stall.
+    const { value: raw, timedOut } = await this.readWithTimeout<string | null>(
+      () => this.kv!.get(this.tagMarkerKey(tag), { type: "text" }),
+      this.kvReadTimeoutMs,
+      "tag marker KV read",
+    );
+    if (timedOut) {
+      // Memoize the fail-open result so the rest of this request is consistent
+      // (and does not re-pay the timeout per segment sharing the tag).
+      return memoize(null);
+    }
     const value = raw != null ? Number(raw) : null;
-    memo?.set(tag, value);
+    const resolved = memoize(value);
 
-    // Populate L1 for subsequent reads in this colo (non-blocking).
+    // Populate L1 for subsequent reads in this colo (non-blocking). Use the
+    // resolved (memo-aware) value so a marker invalidated mid-read is not
+    // re-cached stale into this colo's L1.
     if (this.tagCacheTtl > 0) {
-      const put = () => this.putTagMarkerL1(tag, value);
+      const put = () => this.putTagMarkerL1(tag, resolved);
       if (this.waitUntil) this.waitUntil(put);
       else void put();
     }
-    return value;
+    return resolved;
   }
 
   /**
@@ -1404,6 +2015,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   private async putTagMarkerL1(
     tag: string,
     value: number | null,
+    opts?: { critical?: boolean },
   ): Promise<void> {
     if (this.tagCacheTtl <= 0) return;
     try {
@@ -1418,8 +2030,29 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
           },
         }),
       );
-    } catch {
-      // Best-effort: a failed L1 populate just means the next read consults KV.
+    } catch (error) {
+      // The read-path populate is best-effort: a failed populate just means the
+      // next read consults KV. The invalidation WRITE-THROUGH (critical) is not
+      // - silently swallowing it would leave this colo's stale marker (often the
+      // ABSENT sentinel) authoritative for tagCacheTtl while updateTag reports
+      // success. Surface it, and best-effort delete the L1 marker so the next
+      // read re-reads KV, which already holds the fresh marker (written before
+      // this write-through in invalidateTags).
+      if (opts?.critical) {
+        reportCacheError(
+          error,
+          "cache-invalidate",
+          "[CFCacheStore] tag marker L1 write-through",
+        );
+        await reportingAsync(
+          async () => {
+            const cache = await this.getCache();
+            await cache.delete(this.tagMarkerRequest(tag));
+          },
+          "cache-delete",
+          "[CFCacheStore] tag marker L1 evict after failed write-through",
+        );
+      }
     }
   }
 
@@ -1446,7 +2079,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     if (tags.length === 0) return;
     const invalidatedAt = Date.now();
     const ctx = _getRequestContext();
-    const memo = ctx ? getTagMarkerMemo(ctx) : undefined;
+    const memo = ctx ? getTagMarkerMemo(ctx, this) : undefined;
 
     if (!this.kv && !this.onRevalidateTag) {
       console.warn(
@@ -1461,11 +2094,12 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       await Promise.all(
         tags.map(async (tag) => {
           const markerKey = this.tagMarkerKey(tag);
-          if (kvKeyByteLength(markerKey) > KV_MAX_KEY_BYTES) {
+          const markerKeyBytes = kvKeyByteLength(markerKey);
+          if (markerKeyBytes > KV_MAX_KEY_BYTES) {
             failedTags.add(tag);
             errors.push(
               new Error(
-                `tag "${tag}" produces a ${kvKeyByteLength(markerKey)}-byte KV ` +
+                `tag "${tag}" produces a ${markerKeyBytes}-byte KV ` +
                   `marker key, over the ${KV_MAX_KEY_BYTES}-byte limit`,
               ),
             );
@@ -1485,20 +2119,27 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       );
     }
 
-    // Write-through memo + L1 only for tags with a confirmed durable marker (or
-    // for every tag when there is no KV at all - a purge-only/dev config, where
-    // the in-memory write-through is the only invalidation signal there is). The
-    // memo write is synchronous (read-your-own-writes); the L1 Cache API writes
-    // are independent, so fan them out in parallel rather than awaiting each.
-    const l1Writes: Promise<void>[] = [];
-    for (const tag of tags) {
-      if (failedTags.has(tag)) continue;
-      memo?.set(tag, invalidatedAt);
-      if (this.tagCacheTtl > 0) {
-        l1Writes.push(this.putTagMarkerL1(tag, invalidatedAt));
+    // Write-through memo + L1 only for tags with a confirmed durable marker, and
+    // only when KV is configured. Markers are read exclusively through
+    // isGloballyInvalidated(), which short-circuits to "not invalidated" when
+    // !this.kv; writing memo/L1 markers without KV would be dead state no read
+    // path ever consults. The onRevalidateTag purge below still fires regardless
+    // (it is additive and external to the marker cascade). The memo write is
+    // synchronous (read-your-own-writes); the L1 Cache API writes are
+    // independent, so fan them out in parallel rather than awaiting each.
+    if (this.kv) {
+      const l1Writes: Promise<void>[] = [];
+      for (const tag of tags) {
+        if (failedTags.has(tag)) continue;
+        memo?.set(tag, invalidatedAt);
+        if (this.tagCacheTtl > 0) {
+          l1Writes.push(
+            this.putTagMarkerL1(tag, invalidatedAt, { critical: true }),
+          );
+        }
       }
+      if (l1Writes.length > 0) await Promise.all(l1Writes);
     }
-    if (l1Writes.length > 0) await Promise.all(l1Writes);
 
     // One batched eager purge of the lookup markers for the whole call. Fired
     // regardless of KV write outcome (it is additive and uses pure string ops).
@@ -1535,39 +2176,78 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
    * Promotes hits to L1 via waitUntil.
    * @internal
    */
-  private async kvGetSegment(key: string): Promise<CacheGetResult | null> {
+  private async kvGetSegment(
+    key: string,
+    opts?: { suppressRevalidate?: boolean },
+  ): Promise<CacheGetResult | null> {
     if (!this.kv) return null;
 
     try {
       const kvKey = this.toKVKey(key);
-      const envelope = await this.kvGetOrEvict<KVSegmentEnvelope>(
-        kvKey,
-        (e) =>
-          typeof e.e === "number" && typeof e.s === "number" && e.d != null,
-        "kvGetSegment",
-      );
-      if (!envelope) return null;
+      const { value: envelope, timedOut } =
+        await this.kvGetOrEvict<KVSegmentEnvelope>(
+          kvKey,
+          (e) =>
+            typeof e.e === "number" && typeof e.s === "number" && e.d != null,
+          "kvGetSegment",
+        );
+      if (timedOut) {
+        // Abandoned slow KV read: no envelope, so no promote-to-L1. Distinct
+        // from a genuine kv-miss so the degradation is visible on wrangler tail.
+        if (this.debug)
+          this.emitDebug({ op: "get", key, outcome: "kv-timeout" });
+        return null;
+      }
+      if (!envelope) {
+        // Missing key, or a corrupt entry already evicted + reported by
+        // kvGetOrEvict. Either way a miss.
+        if (this.debug) this.emitDebug({ op: "get", key, outcome: "kv-miss" });
+        return null;
+      }
 
       const now = Date.now();
 
       // Hard-expired — treat as miss
-      if (now > envelope.e) return null;
+      if (now > envelope.e) {
+        if (this.debug) this.emitDebug({ op: "get", key, outcome: "kv-miss" });
+        return null;
+      }
 
       // Tag invalidation check (also covers the KV tier, not just L1).
       if (
         await this.isGloballyInvalidated(envelope.d.tags, envelope.d.taggedAt)
       ) {
+        if (this.debug)
+          this.emitDebug({ op: "get", key, outcome: "tag-invalidated" });
         return null;
       }
 
-      const shouldRevalidate = now > envelope.s;
+      // When this is a degraded L1 fall-through (body-timeout / non-200), the
+      // caller asks us to suppress revalidation: KV has no REVALIDATING herd
+      // guard, so N concurrent degraded reads would otherwise each spawn a
+      // render exactly when the colo is already struggling. We still serve the
+      // stale data and still promote to L1; only the revalidation is withheld.
+      const stale = now > envelope.s;
+      const shouldRevalidate = stale && !opts?.suppressRevalidate;
 
       // Promote to L1 in background
       this.promoteSegmentToL1(key, envelope);
 
+      if (this.debug)
+        this.emitDebug({
+          op: "get",
+          key,
+          outcome: !stale
+            ? "kv-fresh"
+            : opts?.suppressRevalidate
+              ? "kv-stale-suppressed"
+              : "kv-stale",
+          shouldRevalidate,
+        });
       return { data: envelope.d, shouldRevalidate };
     } catch (error) {
       reportCacheError(error, "cache-read", "[CFCacheStore] kvGetSegment");
+      if (this.debug) this.emitDebug({ op: "get", key, outcome: "error" });
       return null;
     }
   }
@@ -1630,6 +2310,9 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
               "Content-Type": "application/json",
               "Cache-Control": `public, max-age=${remainingTtl}`,
               [CACHE_STALE_AT_HEADER]: String(envelope.s),
+              // Carry the hard-expiry deadline so a promoted entry that later
+              // goes stale re-puts with the correct remaining ttl (see set()).
+              [CACHE_EXPIRES_AT_HEADER]: String(envelope.e),
               [CACHE_STATUS_HEADER]: "HIT",
               // Preserve tags across KV->L1 promotion so the promoted entry
               // stays tag-invalidatable.
@@ -1649,35 +2332,68 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
    * KV fallback for function cache reads.
    * @internal
    */
-  private async kvGetItem(key: string): Promise<CacheItemResult | null> {
+  private async kvGetItem(
+    key: string,
+    opts?: { suppressRevalidate?: boolean },
+  ): Promise<CacheItemResult | null> {
     if (!this.kv) return null;
 
     try {
       const kvKey = this.toKVKey(`fn:${key}`);
-      const envelope = await this.kvGetOrEvict<KVItemEnvelope>(
-        kvKey,
-        (e) =>
-          typeof e.v === "string" &&
-          typeof e.e === "number" &&
-          typeof e.s === "number",
-        "kvGetItem",
-      );
-      if (!envelope) return null;
+      const { value: envelope, timedOut } =
+        await this.kvGetOrEvict<KVItemEnvelope>(
+          kvKey,
+          (e) =>
+            typeof e.v === "string" &&
+            typeof e.e === "number" &&
+            typeof e.s === "number",
+          "kvGetItem",
+        );
+      if (timedOut) {
+        if (this.debug)
+          this.emitDebug({ op: "getItem", key, outcome: "kv-timeout" });
+        return null;
+      }
+      if (!envelope) {
+        if (this.debug)
+          this.emitDebug({ op: "getItem", key, outcome: "kv-miss" });
+        return null;
+      }
 
       const now = Date.now();
 
-      if (now > envelope.e) return null;
+      if (now > envelope.e) {
+        if (this.debug)
+          this.emitDebug({ op: "getItem", key, outcome: "kv-miss" });
+        return null;
+      }
 
       // Tag invalidation check (also covers the KV tier, not just L1).
       if (await this.isGloballyInvalidated(envelope.t, envelope.ta)) {
+        if (this.debug)
+          this.emitDebug({ op: "getItem", key, outcome: "tag-invalidated" });
         return null;
       }
 
-      const shouldRevalidate = now > envelope.s;
+      // Degraded fall-through suppresses revalidation (no KV herd guard); see
+      // kvGetSegment. Still serves stale and still promotes.
+      const stale = now > envelope.s;
+      const shouldRevalidate = stale && !opts?.suppressRevalidate;
 
       // Promote to L1
       this.promoteItemToL1(key, envelope);
 
+      if (this.debug)
+        this.emitDebug({
+          op: "getItem",
+          key,
+          outcome: !stale
+            ? "kv-fresh"
+            : opts?.suppressRevalidate
+              ? "kv-stale-suppressed"
+              : "kv-stale",
+          shouldRevalidate,
+        });
       return {
         value: envelope.v,
         handles: envelope.h,
@@ -1686,6 +2402,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       };
     } catch (error) {
       reportCacheError(error, "cache-read", "[CFCacheStore] kvGetItem");
+      if (this.debug) this.emitDebug({ op: "getItem", key, outcome: "error" });
       return null;
     }
   }
@@ -1717,6 +2434,8 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
               "Content-Type": "application/json",
               "Cache-Control": `public, max-age=${remainingTtl}`,
               [CACHE_STALE_AT_HEADER]: String(envelope.s),
+              // Carry the hard-expiry deadline; see promoteSegmentToL1 / set().
+              [CACHE_EXPIRES_AT_HEADER]: String(envelope.e),
               [CACHE_STATUS_HEADER]: "HIT",
               // Preserve tags across KV->L1 promotion (the item tier previously
               // dropped them, permanently disabling tag invalidation here).
@@ -1742,15 +2461,32 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     if (!this.kv) return null;
 
     try {
-      const kvKey = this.toKVKey(`doc:${key}`);
-      const envelope = await this.kvGetOrEvict<KVResponseEnvelope>(
+      const kvKey = this.toDocKVKey(key);
+      // The document path is debug-silent (op is only get/getItem): a KV-read
+      // timeout here is bounded for resilience parity (kvGetOrEvict applies the
+      // budget) but emits no kv-timeout event, so its absence from the debug
+      // stream is expected. A null envelope is a miss -- missing key, a budget
+      // timeout, or a corrupt entry already evicted + reported by kvGetOrEvict.
+      const { value: envelope } = await this.kvGetOrEvict<KVResponseEnvelope>(
         kvKey,
         (e) =>
           typeof e.b === "string" &&
           typeof e.st === "number" &&
           typeof e.e === "number" &&
           typeof e.s === "number" &&
-          Array.isArray(e.hd),
+          // stx is optional but, if present, must be a string (feeds Response).
+          (e.stx === undefined || typeof e.stx === "string") &&
+          // hd must be an array of [name, value] string tuples; a malformed
+          // shape would otherwise throw in `new Headers(hd)`. Validate it here
+          // so a faulty envelope is a fail-open MISS, never a thrown read.
+          Array.isArray(e.hd) &&
+          e.hd.every(
+            (entry) =>
+              Array.isArray(entry) &&
+              entry.length === 2 &&
+              typeof entry[0] === "string" &&
+              typeof entry[1] === "string",
+          ),
         "kvGetResponse",
       );
       if (!envelope) return null;
@@ -1772,6 +2508,12 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       // so evict it and miss rather than re-failing every read until TTL.
       let response: Response;
       try {
+        // Finding #3 (read side): strip per-client signals a stale envelope may
+        // carry. Inside the try so a malformed `hd` evicts (not throws through);
+        // mutates `hd` in place so promoteResponseToL1 re-seeds from it too.
+        envelope.hd = envelope.hd.filter(
+          ([name]) => !isPerClientSignalHeader(name),
+        );
         const bodyBuffer = base64ToBuffer(envelope.b);
         const headers = new Headers(envelope.hd);
         response = new Response(bodyBuffer, {
@@ -1785,7 +2527,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
           "cache-corrupt",
           "[CFCacheStore] kvGetResponse: corrupt response envelope, evicting",
         );
-        await this.evictKvKey(kvKey, "kvGetResponse");
+        this.scheduleKvEvict(kvKey, "kvGetResponse");
         return null;
       }
 
@@ -1824,13 +2566,15 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
           }
           headers.set("Cache-Control", `public, max-age=${remainingTtl}`);
           headers.set(CACHE_STALE_AT_HEADER, String(envelope.s));
+          // Carry the hard-expiry deadline so the document herd guard's
+          // markResponseRevalidating re-put can compute the remaining window
+          // (matches promoteSegmentToL1/promoteItemToL1); without it a stale
+          // re-put would floor to max-age=1 and churn the KV-promoted twin.
+          headers.set(CACHE_EXPIRES_AT_HEADER, String(envelope.e));
           // Re-attach the internal tag headers (envelope.hd is client-facing
           // and intentionally excludes them) so the promoted entry stays
           // invalidatable.
-          const tagHeaders = this.tagHeaderEntries(envelope.t, envelope.ta);
-          for (const [name, value] of Object.entries(tagHeaders)) {
-            headers.set(name, value);
-          }
+          this.setTagHeaders(headers, envelope.t, envelope.ta);
 
           const bodyBuffer = base64ToBuffer(envelope.b);
           const response = new Response(bodyBuffer, {
@@ -1847,27 +2591,3 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     );
   }
 }
-
-// ============================================================================
-// Base64 Helpers (binary-safe response body encoding for KV)
-// ============================================================================
-
-/** Encode ArrayBuffer to base64 string. */
-function bufferToBase64(buffer: ArrayBuffer): string {
-  const bytes = new Uint8Array(buffer);
-  let binary = "";
-  for (let i = 0; i < bytes.length; i++) {
-    binary += String.fromCharCode(bytes[i]!);
-  }
-  return btoa(binary);
-}
-
-/** Decode base64 string to ArrayBuffer. */
-function base64ToBuffer(base64: string): ArrayBuffer {
-  const binary = atob(base64);
-  const bytes = new Uint8Array(binary.length);
-  for (let i = 0; i < binary.length; i++) {
-    bytes[i] = binary.charCodeAt(i);
-  }
-  return bytes.buffer;
-}