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

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

@@ -218,6 +218,19 @@ function getTagMarkerInflight(
   return inflight;
 }
 
+/**
+ * Per-request memo of the derived cache-key base URL.
+ *
+ * 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 derivedBaseUrlMemo = new WeakMap<object, string>();
+
 /** KV key byte-length ceiling. Cloudflare KV rejects keys larger than this. */
 const KV_MAX_KEY_BYTES = 512;
 
@@ -323,10 +336,9 @@ function remainingCacheControl(headers: Headers, now: number): 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";
+// Imported from the canonical home (also publicly exported from src/index.ts /
+// src/index.rsc.ts) so this module shares the one interface rather than
+// declaring a second that could drift.
 import type { ExecutionContext } from "../../types/request-scope.js";
 
 /**
@@ -717,12 +729,6 @@ export interface CFCacheStoreOptions<TEnv = unknown> {
   ) => string | Promise<string>;
 }
 
-/**
- * Cache status values for the x-edge-cache-status header.
- * @internal
- */
-export type CacheStatus = "HIT" | "REVALIDATING";
-
 // ============================================================================
 // CFCacheStore Implementation
 // ============================================================================
@@ -810,13 +816,10 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     // 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".
-    // Coerce any non-finite/non-positive value to the documented 0 = disabled.
-    this.tagCacheTtl =
-      typeof options.tagCacheTtl === "number" &&
-      Number.isFinite(options.tagCacheTtl) &&
-      options.tagCacheTtl > 0
-        ? options.tagCacheTtl
-        : 0;
+    // 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
@@ -909,31 +912,43 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       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;
   }
 
   /**
@@ -1669,10 +1684,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       headers.set("Cache-Control", `public, max-age=${totalTtl}`);
       headers.set(CACHE_STALE_AT_HEADER, String(staleAt));
       // 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,
@@ -2164,6 +2176,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[];
@@ -2924,10 +2954,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
           // 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, {

package/src/cache/cf/index.ts

@@ -1,15 +1,3 @@
-/**
- * Cloudflare Cache Store Exports
- *
- * Main export:
- * - CFCacheStore - Production cache store using Cloudflare's Cache API
- *
- * Header constants (for inspection/debugging):
- * - CACHE_STALE_AT_HEADER - Header containing staleness timestamp
- * - CACHE_STATUS_HEADER - Header containing HIT/REVALIDATING status
- */
-
-// Public API
 export {
   CFCacheStore,
   type CFCacheStoreOptions,
@@ -18,26 +6,14 @@ export {
   type KVNamespace,
 } from "./cf-cache-store.js";
 
-// Header constants for debugging and inspection. The tag headers
-// (x-edge-cache-tags / x-edge-cache-tagged-at) are intentionally NOT re-exported:
-// they are an internal encoding detail of the store's tag-invalidation check, not
-// a consumer-inspectable contract.
 export {
   CACHE_STALE_AT_HEADER,
   CACHE_STATUS_HEADER,
   CACHE_REVALIDATING_AT_HEADER,
 } from "./cf-cache-store.js";
 
-// Default latency-budget values, exported so the CFCacheStoreOptions JSDoc
-// {@link}s resolve and consumers can derive margins from the defaults.
 export {
   EDGE_LOOKUP_TIMEOUT_MS,
   EDGE_READ_TIMEOUT_MS,
   KV_READ_TIMEOUT_MS,
 } from "./cf-cache-store.js";
-
-// Internal exports (re-exported for backwards compatibility, marked @internal in source)
-export {
-  type CacheStatus,
-  MAX_REVALIDATION_INTERVAL,
-} from "./cf-cache-store.js";

package/src/cache/document-cache.ts

@@ -22,36 +22,8 @@ import { sortedSearchString } from "./cache-key-utils.js";
 import { runBackground } from "./background-task.js";
 import { reportCacheError } from "./cache-error.js";
 
-// ============================================================================
-// Constants
-// ============================================================================
-
-/** Header indicating cache status for debugging */
 const CACHE_STATUS_HEADER = "x-document-cache-status";
 
-/**
- * Snapshot the request-scoped tag union for a document cache write. The full-page
- * entry is tagged with every cache tag its content resolved (runtime cacheTag(),
- * "use cache" profile tags, and loader cache tags) so updateTag()/revalidateTag()
- * can invalidate it. Returns undefined when no tags were used, keeping untagged
- * document entries header-free.
- *
- * This is a plain synchronous snapshot. The CALLER must drain the rendered body
- * first (see the cache-write closures): runtime cacheTag()/"use cache" and loader
- * tags are recorded synchronously as each value resolves during render, including
- * Suspense-streamed ones that resolve AFTER the handler-settlement barrier - so
- * the correct barrier is the stream draining (render complete), not _handleStore.
- *
- * Caveat: this applies only to the segment cache WRITE path. When a segment is
- * cached for the first time, its cache({ tags }) DSL tags are recorded inside the
- * deferred cacheRoute waitUntil, which can still run after this snapshot; a
- * document that combines whole-page document caching with first-write segment-DSL
- * tags may miss those (the segment cache entry itself is still correctly tagged
- * and invalidated). On a segment-cache HIT the entry's tags are recorded
- * synchronously during lookupRoute, before this snapshot, so they are captured.
- * Runtime cacheTag()/"use cache" and loader tags are always captured once the
- * body drains.
- */
 function collectRequestTags(
   requestCtx: RequestContext | undefined,
 ): string[] | undefined {
@@ -59,11 +31,6 @@ function collectRequestTags(
   return tags && tags.size > 0 ? [...tags] : undefined;
 }
 
-/**
- * Simple hash function for segment IDs.
- * Creates a short, deterministic hash to differentiate cache keys
- * based on which segments the client already has.
- */
 function hashSegmentIds(segmentIds: string): string {
   if (!segmentIds) return "";
 
@@ -72,12 +39,9 @@ function hashSegmentIds(segmentIds: string): string {
     const char = segmentIds.charCodeAt(i);
     hash = ((hash << 5) - hash + char) | 0;
   }
-  // Convert to base36 for shorter string, take absolute value
   return Math.abs(hash).toString(36);
 }
 
-// ============================================================================
-// Cache Control Parsing
 // ============================================================================
 
 interface CacheDirectives {

package/src/cache/handle-snapshot.ts

@@ -11,23 +11,10 @@ import type { HandleStore } from "../server/handle-store.js";
 import type { SegmentHandleData } from "./types.js";
 import { serializeResult, deserializeResult } from "./segment-codec.js";
 
-/**
- * Bound on the background cache-write encode of handle data. A pushed handle
- * value can be a Promise (request-context push-a-promise) or a Promise<ReactNode>
- * (Breadcrumbs content), which the Flight encoder awaits while draining. The
- * encode runs in waitUntil/runBackground, so a never-resolving handle value
- * would otherwise pin a background slot indefinitely; on timeout the entry's
- * handles coalesce to empty rather than hanging or poisoning the whole write.
- */
 const HANDLE_ENCODE_TIMEOUT_MS = 5000;
 
 type HandleRecord = Record<string, SegmentHandleData>;
 
-// captureHandles builds a per-segment map keyed by every cached segment id, even
-// segments that pushed nothing (their entry is an empty object). "No handle data"
-// means no segment has any handle, in which case we skip the Flight encode and
-// store an empty string — so the common handle-free route pays neither an encode
-// on write nor a decode on every cache hit.
 function hasHandleData(handles: HandleRecord): boolean {
   for (const segId in handles) {
     for (const _ in handles[segId]) return true;
@@ -55,42 +42,15 @@ function withTimeout<T>(p: Promise<T>, ms: number, onTimeout: T): Promise<T> {
   ]);
 }
 
-/**
- * Encode a captured handle map to a string for cache storage.
- *
- * Handle values can be Promises or React elements (e.g. Breadcrumbs `content`).
- * JSON.stringify destroys those (Promise -> {}, ReactNode non-representable), so
- * persisting the raw map silently corrupts non-scalar handle values on stores
- * that serialize to JSON (the Cloudflare cache). Routing the map through the same
- * RSC-Flight codec the segments/value already use awaits Promises and serializes
- * React elements, so the stored field is a lossless, JSON-safe string. The
- * in-memory store keeps the same string by reference, so both backends replay
- * identical decoded values.
- */
 export async function encodeHandles(handles: HandleRecord): Promise<string> {
-  // No handle was pushed anywhere — store an empty marker (decoded as "skip").
   if (!hasHandleData(handles)) return "";
   return encodeHandleValue(handles);
 }
 
-/**
- * Decode a stored handle string back to a handle map. Returns null on any
- * decode failure (e.g. a cross-version entry read under a pinned static
- * version), so the caller can skip handle restore without discarding the
- * otherwise-valid cached segments alongside it.
- */
 export function decodeHandles(encoded: string): Promise<HandleRecord | null> {
   return decodeHandleValue<HandleRecord>(encoded);
 }
 
-/**
- * Encode an arbitrary handle-data value to a Flight string. Used directly by the
- * prerender/static pipeline, whose static path holds a single segment's
- * `SegmentHandleData` (not a segId-keyed map). Bounded by the same timeout as
- * encodeHandles; failure/timeout coalesces to "". The caller owns the empty
- * check (an empty value still encodes to a non-empty Flight string, so skip the
- * call when there is nothing to store).
- */
 export async function encodeHandleValue(value: unknown): Promise<string> {
   const encoded = await withTimeout(
     serializeResult(value),

package/src/cache/index.ts

@@ -1,36 +1,15 @@
-/**
- * Cache Store
- *
- * Server-side caching for RSC segments and loader data.
- *
- * Main exports for users:
- * - SegmentCacheStore - Interface for implementing custom cache stores
- * - MemorySegmentCacheStore - In-memory cache for development/testing
- * - CFCacheStore - Cloudflare edge cache store for production
- * - CacheScope / createCacheScope - Request-scoped cache provider
- */
-
-// Segment cache store types and implementations
 export type {
   SegmentCacheStore,
-  SegmentCacheProvider,
   CachedEntryData,
-  CachedEntryResult,
   CacheGetResult,
-  // The getItem()/setItem() signature types on SegmentCacheStore. Exported
-  // alongside CacheGetResult so a consumer implementing a custom store can name
-  // every type its interface methods use, not just the segment-read result.
   CacheItemResult,
   CacheItemOptions,
   SerializedSegmentData,
   SegmentHandleData,
-  CacheConfig,
-  CacheConfigOrFactory,
 } from "./types.js";
 
 export { MemorySegmentCacheStore } from "./memory-segment-store.js";
 
-// Cloudflare cache store
 export {
   CFCacheStore,
   type CFCacheStoreOptions,
@@ -45,17 +24,11 @@ export {
   KV_READ_TIMEOUT_MS,
 } from "./cf/index.js";
 
-// Cache scope
 export { CacheScope, createCacheScope } from "./cache-scope.js";
 
-// Document-level cache middleware
 export {
   createDocumentCacheMiddleware,
   type DocumentCacheOptions,
 } from "./document-cache.js";
 
-// Cache error reporting. CacheErrorCategory is the discriminator surfaced to a
-// router's onError callback as `metadata.category` for the `cache` phase, so
-// consumers can branch on the failure kind (e.g. distinguish a transient
-// cache-read outage from cache-corrupt self-heal).
 export type { CacheErrorCategory } from "./cache-error.js";

package/src/cache/memory-segment-store.ts

@@ -59,8 +59,6 @@ interface CachedResponseEntry {
 
 interface CachedItemEntry {
   value: string;
-  /** RSC-encoded handle data (see handle-snapshot.ts encodeHandles). Stored as
-   *  the encoded string by reference, identical to the JSON-serializing stores. */
   handles?: string;
   expiresAt: number;
   staleAt: number;
@@ -171,8 +169,6 @@ export class MemorySegmentCacheStore<
 
   constructor(options?: MemorySegmentCacheStoreOptions<TEnv>) {
     if (options?.name != null) {
-      // Named stores use the globalThis registry so data survives HMR.
-      // Each name gets its own isolated Map.
       this.cache = getNamedMap<CachedEntryData>(
         CACHE_REGISTRY_KEY,
         options.name,
@@ -194,7 +190,6 @@ export class MemorySegmentCacheStore<
         options.name,
       );
     } else {
-      // Unnamed stores get a plain instance-level Map (no globalThis sharing).
       this.cache = new Map<string, CachedEntryData>();
       this.responseCache = new Map<string, CachedResponseEntry>();
       this.itemCache = new Map<string, CachedItemEntry>();
@@ -229,15 +224,11 @@ export class MemorySegmentCacheStore<
     ttl: number,
     _swr?: number,
   ): Promise<void> {
-    // Note: Memory store doesn't implement SWR - entries just expire at TTL
-    // For SWR support, use CFCacheStore or similar distributed cache
     const entry: CachedEntryData = {
       ...data,
       expiresAt: Date.now() + ttl * 1000,
     };
     const prefixedKey = `seg:${key}`;
-    // Always drop stale tag mappings before writing so an overwrite with
-    // different (or no) tags cannot leave the previous tags pointing here.
     this.unregisterTags(prefixedKey);
     this.cache.set(key, entry);
     if (data.tags && data.tags.length > 0) {
@@ -289,14 +280,7 @@ export class MemorySegmentCacheStore<
     tags?: string[],
   ): Promise<void> {
     try {
-      // arrayBuffer() can reject (e.g. an already-consumed body). A write
-      // failure must degrade to a no-op (entry simply not cached), never throw
-      // up and fail the request.
       const body = await response.clone().arrayBuffer();
-      // Defense-in-depth (Finding #3): never persist a per-client signal into a
-      // shared store. The document-cache chokepoint already refuses these, but
-      // putResponse is public and reachable directly (e.g. tag-revalidation
-      // re-puts), so strip them here too.
       const headers: [string, string][] = [];
       response.headers.forEach((value, name) => {
         if (isPerClientSignalHeader(name)) return;
@@ -369,19 +353,11 @@ export class MemorySegmentCacheStore<
     }
   }
 
-  /**
-   * Invalidate every cache entry (segment, response, item) tagged with any of
-   * `tags`. Entries are dropped immediately; the next read is a miss and
-   * re-renders fresh. This is the store-level primitive both updateTag() and
-   * revalidateTag() delegate to. (In-process, so there is nothing to batch
-   * beyond looping the tags.)
-   */
   async invalidateTags(tags: string[]): Promise<void> {
     for (const tag of tags) {
       const keys = this.tagIndex.get(tag);
       if (!keys || keys.size === 0) continue;
 
-      // Snapshot the keys before mutating the index inside the loop.
       const prefixedKeys = [...keys];
 
       for (const prefixedKey of prefixedKeys) {
@@ -397,18 +373,11 @@ export class MemorySegmentCacheStore<
           this.itemCache.delete(rawKey);
         }
 
-        // Drop this key from every tag set it belonged to, not just `tag`.
         this.unregisterTags(prefixedKey);
       }
     }
   }
 
-  /**
-   * Register `tags` for a prefixed cache key in both the forward
-   * (tag -> keys) and reverse (key -> tags) indexes.
-   * Callers must call unregisterTags() first to clear stale mappings.
-   * @internal
-   */
   private registerTags(tags: string[], prefixedKey: string): void {
     let tagSet = this.keyTags.get(prefixedKey);
     if (!tagSet) {
@@ -426,11 +395,6 @@ export class MemorySegmentCacheStore<
     }
   }
 
-  /**
-   * Remove a prefixed cache key from every tag set it belongs to.
-   * Uses the reverse index so this is O(tags-per-key), not O(total-tags).
-   * @internal
-   */
   private unregisterTags(prefixedKey: string): void {
     const tagSet = this.keyTags.get(prefixedKey);
     if (!tagSet) return;
@@ -446,10 +410,6 @@ export class MemorySegmentCacheStore<
     this.keyTags.delete(prefixedKey);
   }
 
-  /**
-   * Get cache statistics for debugging purposes.
-   * @internal
-   */
   getStats(): { size: number; keys: string[] } {
     return {
       size: this.cache.size,
@@ -457,18 +417,6 @@ export class MemorySegmentCacheStore<
     };
   }
 
-  /**
-   * Reset the global cache registry.
-   * Useful for test isolation - call this in beforeEach to ensure
-   * tests don't share cache state via globalThis.
-   *
-   * @example
-   * ```typescript
-   * beforeEach(() => {
-   *   MemorySegmentCacheStore.resetGlobalCache();
-   * });
-   * ```
-   */
   static resetGlobalCache(): void {
     delete (globalThis as any)[CACHE_REGISTRY_KEY];
     delete (globalThis as any)[RESPONSE_CACHE_REGISTRY_KEY];

package/src/cache/profile-registry.ts

@@ -64,9 +64,13 @@ export function setCacheProfiles(profiles: Record<string, CacheProfile>): void {
 }
 
 /**
- * Get a cache profile by name from the global registry.
- * Used only at DSL-time (cache("profileName") inside urls() evaluation).
- * Runtime code uses request-scoped profiles instead.
+ * Read a profile out of the global registry by name.
+ *
+ * There is currently no production reader: the "use cache: <profile>" runtime
+ * path resolves from the request-scoped _cacheProfiles map (see
+ * cache-runtime.ts), and the route DSL has no cache("profileName") form (see
+ * dsl-helpers.ts). This accessor exists so tests can assert what
+ * setCacheProfiles() wrote into the global registry.
  */
 export function getCacheProfile(name: string): CacheProfile | undefined {
   return _profiles[name];

package/src/cache/read-through-swr.ts

@@ -13,10 +13,15 @@
 
 import type { CacheItemResult, CacheItemOptions } from "./types.js";
 import { runBackground } from "./background-task.js";
+import { reportCacheError } from "./cache-error.js";
+import type { CacheErrorReporter } from "./cache-error.js";
 
-interface WaitUntilHost {
+// The host carries both the optional waitUntil (for background scheduling) and
+// the CacheErrorReporter seam (for routing degradation errors through onError).
+// loader-cache.ts passes the request context, which provides both.
+type WaitUntilHost = {
   waitUntil?: (fn: () => Promise<void>) => void;
-}
+} & CacheErrorReporter;
 
 export interface ReadThroughItemConfig<T> {
   /** Retrieve a cached item by key */
@@ -74,11 +79,20 @@ export async function readThroughItem<T>(
     host,
   } = config;
 
-  // Cache lookup
+  // Cache lookup. An infra read failure (getItem) is reported by the store
+  // itself, so here we just degrade to a miss. A deserialize failure is a
+  // corrupt/truncated stored entry, which this layer owns: report it LOUD as
+  // cache-corrupt, then fall through to a fresh execution (the miss-path write
+  // self-heals the bad entry).
+  let cached: CacheItemResult | null = null;
   try {
-    const cached = await getItem(key);
+    cached = await getItem(key);
+  } catch {
+    cached = null;
+  }
 
-    if (cached) {
+  if (cached) {
+    try {
       const data = await deserialize(cached.value);
 
       if (!cached.shouldRevalidate) {
@@ -97,16 +111,27 @@ export async function readThroughItem<T>(
             if (serialized !== null) {
               await setItem(key, serialized, storeOptions);
             }
-          } catch {
-            // Background revalidation failed silently
+          } catch (error) {
+            reportCacheError(
+              error,
+              "stale-revalidation",
+              "[read-through] background revalidation",
+              host ?? undefined,
+            );
           }
         },
         true,
       );
       return data;
+    } catch (error) {
+      reportCacheError(
+        error,
+        "cache-corrupt",
+        "[read-through] deserialize stored entry",
+        host ?? undefined,
+      );
+      // fall through to fresh execution
     }
-  } catch {
-    // Cache lookup failed, fall through to fresh execution
   }
 
   // Cache miss
@@ -123,8 +148,13 @@ export async function readThroughItem<T>(
           await setItem(key, serialized, storeOptions);
           onCached?.();
         }
-      } catch {
-        // Cache write failed silently
+      } catch (error) {
+        reportCacheError(
+          error,
+          "cache-write",
+          "[read-through] cache write",
+          host ?? undefined,
+        );
       }
     },
     true,