@decocms/blocks 7.63.0 → 7.64.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/blocks",
-  "version": "7.63.0",
+  "version": "7.64.0",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -43,6 +43,8 @@
     "./sdk/abTesting": "./src/sdk/abTesting.ts",
     "./sdk/analytics": "./src/sdk/analytics.ts",
     "./sdk/cachedLoader": "./src/sdk/cachedLoader.ts",
+    "./sdk/responseCache": "./src/sdk/responseCache.ts",
+    "./sdk/cacheStorage": "./src/sdk/cacheStorage.ts",
     "./sdk/cacheHeaders": "./src/sdk/cacheHeaders.ts",
     "./sdk/clx": "./src/sdk/clx.ts",
     "./sdk/cn": "./src/sdk/cn.ts",

package/src/cms/index.ts

@@ -84,8 +84,8 @@ export type {
   CommerceLoader,
   DanglingReferenceHandler,
   DecoPageResult,
-  DeferredSection,
   Deferred,
+  DeferredSection,
   MatcherContext,
   PageSeo,
   ResolvedSection,
@@ -93,12 +93,12 @@ export type {
 } from "./resolve";
 export {
   addSkipResolveType,
+  asResolved,
   BOT_UA_SUBSTRINGS,
   cacheDeferredRawProps,
   clearCommerceLoaders,
   evaluateMatcher,
   extractSeoFromProps,
-  asResolved,
   extractSeoFromSections,
   getAsyncRenderingConfig,
   getDeferredRawProps,
@@ -107,6 +107,7 @@ export {
   isEagerRequest,
   isSeoSection,
   onBeforeResolve,
+  readDeferredRawProps,
   reExtractRawProps,
   registerBotPattern,
   registerCommerceLoader,

package/src/cms/resolve.ts

@@ -1,5 +1,7 @@
 import { getMatchersOverride, getRuleOverrideId, hasMatchersOverride } from "../matchers/override";
 import { getMeter, MetricNames, withTracing } from "../middleware/observability";
+import { createCacheStore } from "../sdk/cacheStorage";
+import { detectDevice } from "../sdk/detectDevice";
 import { djb2Hex } from "../sdk/djb2";
 import { stickyDecide } from "../sdk/experiments";
 import { parseSegmentCookie, SEGMENT_COOKIE, type StoredFlag, trafficToPct } from "../sdk/flags";
@@ -15,7 +17,6 @@ import {
   registerActionSchemas,
   registerLoaderSchemas,
 } from "./schema";
-import { detectDevice } from "../sdk/detectDevice";
 import { isLayoutSection, markSectionDegraded, runSingleSectionLoader } from "./sectionLoaders";
 
 // globalThis-backed: share state across Vite server function split modules
@@ -273,10 +274,13 @@ function isAlwaysDeferSection(key: string): boolean {
 // ---------------------------------------------------------------------------
 
 const DEFERRED_PROPS_TTL = 120_000; // 2 minutes
-const deferredRawPropsCache = new Map<string, { rawProps: Record<string, unknown>; ts: number }>();
+const deferredRawPropsCache = createCacheStore<{ rawProps: Record<string, unknown>; ts: number }>(
+  "deferred-props",
+  500,
+);
 
 function deferredPropsCacheKey(pagePath: string, component: string, index: number): string {
-  return `${pagePath}::${component}::${index}`;
+  return deferredRawPropsCache.key(`${pagePath}::${component}::${index}`);
 }
 
 export function cacheDeferredRawProps(
@@ -286,15 +290,17 @@ export function cacheDeferredRawProps(
   rawProps: Record<string, unknown>,
 ): void {
   const key = deferredPropsCacheKey(pagePath, component, index);
-  deferredRawPropsCache.set(key, { rawProps, ts: Date.now() });
+  deferredRawPropsCache.set(key, { rawProps, ts: Date.now() }, Date.now() + DEFERRED_PROPS_TTL);
+}
 
-  // Lazy eviction: remove expired entries when cache grows
-  if (deferredRawPropsCache.size > 500) {
-    const now = Date.now();
-    for (const [k, v] of deferredRawPropsCache) {
-      if (now - v.ts > DEFERRED_PROPS_TTL) deferredRawPropsCache.delete(k);
-    }
-  }
+/** Async form used when a deferred request may run in a different isolate. */
+export async function readDeferredRawProps(
+  pagePath: string,
+  component: string,
+  index: number,
+): Promise<Record<string, unknown> | null> {
+  const entry = await deferredRawPropsCache.read(deferredPropsCacheKey(pagePath, component, index));
+  return entry?.rawProps ?? null;
 }
 
 export function getDeferredRawProps(
@@ -1148,7 +1154,7 @@ interface ResolvedSectionsCache {
   expiresAt: number;
 }
 
-const resolvedLayoutCache = new Map<string, ResolvedSectionsCache>();
+const resolvedLayoutCache = createCacheStore<ResolvedSectionsCache>("resolved-layouts");
 const resolvedLayoutInflight = new Map<string, Promise<ResolvedSection[]>>();
 
 /**
@@ -1178,8 +1184,8 @@ export function layoutCacheKey(blockKey: string, matcherCtx?: MatcherContext): s
   return `${blockKey}::${detectDevice(matcherCtx?.userAgent ?? "")}`;
 }
 
-function getCachedResolvedLayout(blockKey: string): ResolvedSection[] | null {
-  const entry = resolvedLayoutCache.get(blockKey);
+async function getCachedResolvedLayout(blockKey: string): Promise<ResolvedSection[] | null> {
+  const entry = await resolvedLayoutCache.read(blockKey);
   if (!entry) return null;
   if (Date.now() > entry.expiresAt) {
     resolvedLayoutCache.delete(blockKey);
@@ -1189,10 +1195,14 @@ function getCachedResolvedLayout(blockKey: string): ResolvedSection[] | null {
 }
 
 function setCachedResolvedLayout(blockKey: string, sections: ResolvedSection[]): void {
-  resolvedLayoutCache.set(blockKey, {
-    sections,
-    expiresAt: Date.now() + RESOLVE_CACHE_TTL,
-  });
+  resolvedLayoutCache.set(
+    blockKey,
+    {
+      sections,
+      expiresAt: Date.now() + RESOLVE_CACHE_TTL,
+    },
+    Date.now() + RESOLVE_CACHE_TTL,
+  );
 }
 
 /**
@@ -2259,8 +2269,8 @@ async function resolveDecoPageImpl(
           const layoutKey = isRawSectionLayout(section);
 
           if (layoutKey) {
-            const cacheKey = layoutCacheKey(layoutKey, rctx.matcherCtx);
-            const cached = getCachedResolvedLayout(cacheKey);
+            const cacheKey = resolvedLayoutCache.key(layoutCacheKey(layoutKey, rctx.matcherCtx));
+            const cached = await getCachedResolvedLayout(cacheKey);
             if (cached) return cached;
 
             const inflight = resolvedLayoutInflight.get(cacheKey);
@@ -2357,8 +2367,8 @@ export async function resolvePageSections(
         const layoutKey = isRawSectionLayout(section);
 
         if (layoutKey) {
-          const cacheKey = layoutCacheKey(layoutKey, rctx.matcherCtx);
-          const cached = getCachedResolvedLayout(cacheKey);
+          const cacheKey = resolvedLayoutCache.key(layoutCacheKey(layoutKey, rctx.matcherCtx));
+          const cached = await getCachedResolvedLayout(cacheKey);
           if (cached) return cached;
 
           const inflight = resolvedLayoutInflight.get(cacheKey);
@@ -2449,7 +2459,7 @@ export async function resolveDeferredSectionFull(
   // rawProps may be stripped from the client payload — resolve from cache or page
   const rawProps =
     ds.rawProps ??
-    getDeferredRawProps(pagePath, ds.component, ds.index) ??
+    (await readDeferredRawProps(pagePath, ds.component, ds.index)) ??
     (await reExtractRawProps(pagePath, ds.component, ds.index, matcherCtx));
 
   if (!rawProps) return null;

package/src/cms/sectionLoaders.ts

@@ -11,8 +11,8 @@
 
 import { RequestContext } from "@decocms/blocks/sdk/requestContext";
 import { getCacheProfile } from "../sdk/cacheHeaders";
+import { cacheBackground, createCacheStore, getCacheStorageContext } from "../sdk/cacheStorage";
 import { detectDevice } from "../sdk/detectDevice";
-import { djb2 } from "../sdk/djb2";
 import { withInflightTimeout } from "../sdk/inflightTimeout";
 import { withTracing } from "../sdk/observability";
 import type { ResolvedSection } from "./resolve";
@@ -91,6 +91,8 @@ export function getDegradedSections(): string[] {
 
 interface CacheableSectionConfig {
   maxAge: number;
+  /** Bounded stale window in milliseconds. Default: 5 minutes. */
+  staleWhileRevalidate?: number;
 }
 
 export type CacheableSectionInput =
@@ -113,19 +115,10 @@ interface SectionCacheEntry {
   refreshing: boolean;
 }
 
-const sectionLoaderCache = new Map<string, SectionCacheEntry>();
+const sectionLoaderCache = createCacheStore<SectionCacheEntry>("sections");
 const sectionLoaderInflight = new Map<string, Promise<ResolvedSection>>();
-const MAX_SECTION_CACHE_ENTRIES = 200;
-
-function evictSectionCacheIfNeeded() {
-  if (sectionLoaderCache.size <= MAX_SECTION_CACHE_ENTRIES) return;
-  const oldest = [...sectionLoaderCache.entries()].sort((a, b) => a[1].createdAt - b[1].createdAt);
-  const toDelete = oldest.slice(0, sectionLoaderCache.size - MAX_SECTION_CACHE_ENTRIES);
-  for (const [key] of toDelete) sectionLoaderCache.delete(key);
-}
-
 function sectionCacheKey(component: string, props: Record<string, unknown>): string {
-  return `${component}::${djb2(JSON.stringify(props))}`;
+  return `${component}::${JSON.stringify(props)}`;
 }
 
 /**
@@ -142,18 +135,24 @@ export function registerCacheableSections(configs: Record<string, CacheableSecti
   }
 }
 
-function runCacheableSectionLoader(
+async function runCacheableSectionLoader(
   section: ResolvedSection,
   loader: SectionLoaderFn,
   request: Request,
   config: CacheableSectionConfig,
 ): Promise<ResolvedSection> {
-  const key = sectionCacheKey(section.component, section.props as Record<string, unknown>);
+  const key = sectionLoaderCache.key(
+    sectionCacheKey(section.component, section.props as Record<string, unknown>),
+  );
 
   const existing = sectionLoaderInflight.get(key);
   if (existing) return existing;
 
-  const entry = sectionLoaderCache.get(key);
+  const entry = getCacheStorageContext()?.storage
+    ? await sectionLoaderCache.read(key)
+    : sectionLoaderCache.get(key);
+  const pending = sectionLoaderInflight.get(key);
+  if (pending) return pending;
   const now = Date.now();
   const isStale = entry ? now - entry.createdAt > config.maxAge : true;
 
@@ -163,18 +162,25 @@ function runCacheableSectionLoader(
 
   if (entry && isStale && !entry.refreshing) {
     entry.refreshing = true;
-    void Promise.resolve(loader(section.props as Record<string, unknown>, request))
-      .then((enrichedProps) => {
-        const enriched = { ...section, props: enrichedProps };
-        sectionLoaderCache.set(key, {
-          section: enriched,
-          createdAt: Date.now(),
-          refreshing: false,
-        });
-      })
-      .catch(() => {
-        entry.refreshing = false;
-      });
+    cacheBackground(
+      Promise.resolve()
+        .then(() => loader(section.props as Record<string, unknown>, request))
+        .then((enrichedProps) => {
+          const enriched = { ...section, props: enrichedProps };
+          sectionLoaderCache.set(
+            key,
+            {
+              section: enriched,
+              createdAt: Date.now(),
+              refreshing: false,
+            },
+            Date.now() + config.maxAge + (config.staleWhileRevalidate ?? 300_000),
+          );
+        })
+        .catch(() => {
+          entry.refreshing = false;
+        }),
+    );
     return Promise.resolve(entry.section);
   }
 
@@ -184,12 +190,15 @@ function runCacheableSectionLoader(
     (async () => {
       const enrichedProps = await loader(section.props as Record<string, unknown>, request);
       const enriched = { ...section, props: enrichedProps };
-      sectionLoaderCache.set(key, {
-        section: enriched,
-        createdAt: Date.now(),
-        refreshing: false,
-      });
-      evictSectionCacheIfNeeded();
+      sectionLoaderCache.set(
+        key,
+        {
+          section: enriched,
+          createdAt: Date.now(),
+          refreshing: false,
+        },
+        Date.now() + config.maxAge + (config.staleWhileRevalidate ?? 300_000),
+      );
       return enriched;
     })(),
     `sectionLoader ${key}`,
@@ -267,7 +276,7 @@ interface CachedSection {
   expiresAt: number;
 }
 
-const layoutCache = new Map<string, CachedSection>();
+const layoutCache = createCacheStore<CachedSection>("layout-loaders");
 const layoutInflight = new Map<string, Promise<ResolvedSection>>();
 
 /**
@@ -336,8 +345,8 @@ export function layoutLoaderCacheKey(component: string, request?: Request): stri
   return `${component}::${detectDevice(request?.headers?.get?.("user-agent") ?? "")}`;
 }
 
-function getCachedLayout(cacheKey: string): ResolvedSection | null {
-  const entry = layoutCache.get(cacheKey);
+async function getCachedLayout(cacheKey: string): Promise<ResolvedSection | null> {
+  const entry = await layoutCache.read(cacheKey);
   if (!entry) return null;
   if (Date.now() > entry.expiresAt) {
     layoutCache.delete(cacheKey);
@@ -347,21 +356,25 @@ function getCachedLayout(cacheKey: string): ResolvedSection | null {
 }
 
 function setCachedLayout(cacheKey: string, section: ResolvedSection): void {
-  layoutCache.set(cacheKey, {
-    section,
-    expiresAt: Date.now() + LAYOUT_CACHE_TTL,
-  });
+  layoutCache.set(
+    cacheKey,
+    {
+      section,
+      expiresAt: Date.now() + LAYOUT_CACHE_TTL,
+    },
+    Date.now() + LAYOUT_CACHE_TTL,
+  );
 }
 
 /**
  * Run a layout section's loader with in-flight dedup + TTL cache.
  */
-function resolveLayoutSection(
+async function resolveLayoutSection(
   section: ResolvedSection,
   loader: SectionLoaderFn,
   request: Request,
 ): Promise<ResolvedSection> {
-  const key = layoutLoaderCacheKey(section.component, request);
+  const key = layoutCache.key(layoutLoaderCacheKey(section.component, request));
   const { index } = section;
 
   // Re-apply the caller's page-specific index onto a fresh object so the
@@ -369,7 +382,7 @@ function resolveLayoutSection(
   const withIndex = (s: ResolvedSection): ResolvedSection =>
     index !== undefined ? { ...s, index } : s;
 
-  const cached = getCachedLayout(key);
+  const cached = await getCachedLayout(key);
   if (cached) return Promise.resolve(withIndex(cached));
 
   const existing = layoutInflight.get(key);

package/src/middleware/observability.ts

@@ -283,8 +283,7 @@ export const MetricNames = {
   // the metric name already provides the deco.cache.* namespace.
   CACHE_REQUESTS: "deco.cache.requests",
   // Size in bytes of the values moving through a cache, dimensioned by `op`.
-  // Exponential (base-2) aggregation — see METRIC_METADATA for the scale and
-  // why an explicit-bounds histogram is the wrong shape here.
+  // Bucketed in decades of bytes — see CACHE_SIZE_BUCKET_BOUNDARIES_BYTES.
   CACHE_SIZE: "deco.cache.size",
   RESOLVE_DURATION: "deco.cms.resolve.duration",
   LOADER_DURATION: "deco.loader.duration",
@@ -327,6 +326,29 @@ export const DURATION_BUCKET_BOUNDARIES_SECONDS: readonly number[] = [
   10,
 ];
 
+/**
+ * Bucket boundaries, in BYTES, for {@link MetricNames.CACHE_SIZE}.
+ *
+ * Decades, matching the `http.server.response.body.size` histogram already
+ * flowing through the same ingestor — a size distribution is read in orders of
+ * magnitude, not in linear steps, and reusing the house convention means the
+ * two byte histograms are directly comparable.
+ *
+ * The range is bounded on both ends by the loader cache itself: entries are
+ * floored at `MIN_ENTRY_BYTES` (512 B) and the store is capped at 32 MB, which
+ * is why the last bound is the cap rather than another decade — the top bucket
+ * then reads as "single entry at/near the whole cache budget", which is the
+ * thing worth alerting on.
+ */
+export const CACHE_SIZE_BUCKET_BOUNDARIES_BYTES: readonly number[] = [
+  1_000,
+  10_000,
+  100_000,
+  1_000_000,
+  10_000_000,
+  33_554_432,
+];
+
 /**
  * Per-metric metadata emitted in the OTLP payload's `description` and
  * `unit` fields. Durations are normalized to **seconds at the source** (OTel
@@ -347,16 +369,6 @@ export const METRIC_METADATA: Record<
     description: string;
     unit: string;
     boundaries?: readonly number[];
-    /**
-     * Histogram aggregation. Omitted means `"explicit"` — bucket into
-     * `boundaries`. `"exponential"` selects an OTel base-2 exponential
-     * histogram at {@link scale}, where bucket `i` covers
-     * `(2^(2^-scale))^i .. ^(i+1)]`. Adapters that don't implement it are free
-     * to keep treating the metric as an ordinary histogram.
-     */
-    aggregation?: "explicit" | "exponential";
-    /** Exponential-histogram scale. Fixed per metric; adapters never rescale. */
-    scale?: number;
   }
 > = {
   [MetricNames.HTTP_SERVER_REQUEST_DURATION]: {
@@ -376,15 +388,7 @@ export const METRIC_METADATA: Record<
   [MetricNames.CACHE_SIZE]: {
     description: "Size in bytes of values written to / read from a cache, dimensioned by op.",
     unit: "By",
-    // Exponential rather than explicit bounds: entries span 512 B (the
-    // cachedLoader floor) to the 32 MB cap — five decades. Any fixed bound set
-    // wide enough for the top is useless at the bottom.
-    aggregation: "exponential",
-    // scale -1 => base 4, so buckets land on 512 B · 2 K · 8 K · 32 K · 128 K ·
-    // 512 K · 2 M · 8 M · 32 M: ~9 buckets over the real range, ~1.7 per
-    // decade. scale 0 (base 2) would double the series count without saying
-    // anything new about a size distribution.
-    scale: -1,
+    boundaries: CACHE_SIZE_BUCKET_BOUNDARIES_BYTES,
   },
   [MetricNames.RESOLVE_DURATION]: {
     description: "Duration of `deco.cms.resolvePage` — CMS route to block tree resolution.",

package/src/sdk/cacheStorage.test.ts

@@ -0,0 +1,242 @@
+// @vitest-environment node
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { clearLoaderCache, createCachedLoader } from "./cachedLoader";
+import {
+  bindCacheStorage,
+  type CacheStorage,
+  createCacheStore,
+  createKVCacheStorage,
+  createMemoryCacheStorage,
+  createWebCacheStorage,
+} from "./cacheStorage";
+import { RequestContext } from "./requestContext";
+import { createResponseCache } from "./responseCache";
+
+function fakeKV() {
+  const values = new Map<string, string>();
+  return {
+    values,
+    get: vi.fn(async (key: string) => values.get(key) ?? null),
+    put: vi.fn(async (key: string, value: string, _opts: { expirationTtl: number }) => {
+      values.set(key, value);
+    }),
+    delete: vi.fn(async (key: string) => {
+      values.delete(key);
+    }),
+  };
+}
+
+const pending: Promise<unknown>[] = [];
+function run<T>(storage: CacheStorage | null, scope: string, fn: () => T): T {
+  return RequestContext.run(new Request("https://site.test/"), () => {
+    bindCacheStorage({ storage, scope, waitUntil: (work) => pending.push(work) });
+    return fn();
+  });
+}
+async function flush() {
+  await Promise.all(pending.splice(0));
+}
+afterEach(async () => {
+  await flush();
+  clearLoaderCache();
+  vi.useRealTimers();
+});
+
+function fakeWebCache(): Cache {
+  const values = new Map<string, Response>();
+  return {
+    async match(req: Request) {
+      return values.get(req.url)?.clone();
+    },
+    async put(req: Request, response: Response) {
+      values.set(req.url, response.clone());
+    },
+    async delete(req: Request) {
+      return values.delete(req.url);
+    },
+  } as Cache;
+}
+
+for (const [name, make] of [
+  ["memory", () => createMemoryCacheStorage()],
+  ["KV", () => createKVCacheStorage(fakeKV())],
+  ["Web Cache API", () => createWebCacheStorage(fakeWebCache(), "https://site.test")],
+] as const) {
+  describe(`${name} storage contract`, () => {
+    it("round-trips, overwrites and deletes values", async () => {
+      const storage = make();
+      expect(await storage.get("missing")).toBeNull();
+      await storage.set("key", "first", Date.now() + 60_000);
+      expect(await storage.get("key")).toBe("first");
+      await storage.set("key", "second", Date.now() + 60_000);
+      expect(await storage.get("key")).toBe("second");
+      await storage.delete("key");
+      expect(await storage.get("key")).toBeNull();
+    });
+    it("enforces logical expiry even if the backend retains the record", async () => {
+      vi.useFakeTimers();
+      const storage = make();
+      await storage.set("short", "body", Date.now() + 500);
+      expect(await storage.get("short")).toBe("body");
+      vi.advanceTimersByTime(500);
+      expect(await storage.get("short")).toBeNull();
+    });
+  });
+}
+
+it("uses KV's minimum physical TTL while enforcing shorter logical expiry", async () => {
+  const kv = fakeKV();
+  await createKVCacheStorage(kv).set("a".repeat(1000), "value", Date.now() + 2000);
+  expect(kv.put.mock.calls[0][2]).toEqual({ expirationTtl: 60 });
+  expect(kv.put.mock.calls[0][0].length).toBeLessThan(512);
+});
+
+it("hydrates another store and isolates namespace, site and deployment", async () => {
+  const storage = createKVCacheStorage(fakeKV());
+  const first = createCacheStore<{ n: number }>("loaders");
+  await run(storage, "site:build-A", async () => {
+    first.set(first.key("item"), { n: 1 }, Date.now() + 60_000);
+    await flush();
+  });
+  const second = createCacheStore<{ n: number }>("loaders");
+  expect(await run(storage, "site:build-A", () => second.read(second.key("item")))).toEqual({
+    n: 1,
+  });
+  for (const scope of ["other-site:build-A", "site:build-B"]) {
+    expect(await run(storage, scope, () => second.read(second.key("item")))).toBeUndefined();
+  }
+  const sections = createCacheStore("sections");
+  expect(
+    await run(storage, "site:build-A", () => sections.read(sections.key("item"))),
+  ).toBeUndefined();
+});
+
+it("does not switch bindings between concurrent requests", async () => {
+  const a = createMemoryCacheStorage();
+  const b = createMemoryCacheStorage();
+  const cache = createCacheStore<string>("concurrent");
+  await Promise.all(
+    [a, b].map((storage, i) =>
+      run(storage, `site-${i}`, async () => {
+        await Promise.resolve();
+        cache.set(cache.key("key"), String(i), Date.now() + 60_000);
+      }),
+    ),
+  );
+  await flush();
+  cache.clear();
+  expect(await run(a, "site-0", () => cache.read(cache.key("key")))).toBe("0");
+  expect(await run(b, "site-1", () => cache.read(cache.key("key")))).toBe("1");
+});
+
+it("retains non-JSON values locally without silently corrupting them in KV", async () => {
+  const kv = fakeKV();
+  const cache = createCacheStore<{ date: Date }>("dates");
+  await run(createKVCacheStorage(kv), "site", async () => {
+    const value = { date: new Date() };
+    cache.set(cache.key("key"), value, Date.now() + 60_000);
+    expect(cache.get(cache.key("key"))).toBe(value);
+    await flush();
+    expect(kv.put).not.toHaveBeenCalled();
+  });
+});
+
+it("deduplicates a cold loader through slow storage and survives a memory wipe", async () => {
+  const storage = createKVCacheStorage(fakeKV());
+  const fn = vi.fn(async () => ({ product: 42 }));
+  const loader = createCachedLoader("test", fn, {
+    policy: "stale-while-revalidate",
+    maxAge: 60_000,
+  });
+  await run(storage, "site", async () => {
+    const values = await Promise.all([loader({}), loader({}), loader({})]);
+    expect(values).toEqual([{ product: 42 }, { product: 42 }, { product: 42 }]);
+    expect(fn).toHaveBeenCalledTimes(1);
+    await flush();
+    clearLoaderCache();
+    expect(await loader({})).toEqual({ product: 42 });
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+});
+
+it("falls back to the loader when storage reads and writes fail", async () => {
+  const failure = async () => {
+    throw new Error("KV unavailable");
+  };
+  const fn = vi.fn(async () => "origin");
+  const loader = createCachedLoader("failure", fn, { policy: "no-cache", maxAge: 1000 });
+  expect(await run({ get: failure, set: failure, delete: failure }, "site", () => loader({}))).toBe(
+    "origin",
+  );
+  await flush();
+});
+
+it("round-trips binary responses, headers and status through KV", async () => {
+  const cache = createResponseCache(createKVCacheStorage(fakeKV()), "site:build");
+  const req = new Request("https://site.test/image");
+  const bytes = new Uint8Array([0, 255, 128, 1]);
+  await cache.put(
+    req,
+    new Response(bytes, {
+      status: 203,
+      headers: {
+        "cache-control": "public, max-age=60",
+        "content-type": "application/octet-stream",
+        "x-deco-stored-at": "123",
+      },
+    }),
+  );
+  const response = await cache.match(req);
+  expect(response?.status).toBe(203);
+  expect(response?.headers.get("x-deco-stored-at")).toBe("123");
+  expect(new Uint8Array(await response!.arrayBuffer())).toEqual(bytes);
+  await cache.delete(req);
+  expect(await cache.match(req)).toBeUndefined();
+});
+
+it("refuses to serialize private HTTP responses or cookies", async () => {
+  const storage = createMemoryCacheStorage();
+  const cache = createResponseCache(storage, "site");
+  const req = new Request("https://site.test/");
+  await cache.put(
+    req,
+    new Response("private", { headers: { "cache-control": "private, max-age=60" } }),
+  );
+  expect(await cache.match(req)).toBeUndefined();
+  await cache.put(
+    req,
+    new Response("cookie", {
+      headers: { "cache-control": "public, max-age=60", "set-cookie": "session=secret" },
+    }),
+  );
+  expect(await cache.match(req)).toBeUndefined();
+});
+
+it("bounds SWR separately from stale-if-error and stops serving at the final TTL", async () => {
+  vi.useFakeTimers();
+  const storage = createKVCacheStorage(fakeKV());
+  let fail = false;
+  const origin = vi.fn(async () => {
+    if (fail) throw new Error("origin down");
+    return "last good";
+  });
+  const loader = createCachedLoader("bounded-stale", origin, {
+    policy: "stale-while-revalidate",
+    maxAge: 100,
+    staleWhileRevalidate: 100,
+    staleIfError: 300,
+  });
+  await run(storage, "bounded", async () => {
+    expect(await loader({})).toBe("last good");
+    await flush();
+    fail = true;
+    vi.advanceTimersByTime(150);
+    expect(await loader({})).toBe("last good");
+    await flush();
+    vi.advanceTimersByTime(100);
+    expect(await loader({})).toBe("last good");
+    expect(origin).toHaveBeenCalledTimes(3); // foreground retry once SWR has elapsed
+    vi.advanceTimersByTime(150);
+    await expect(loader({})).rejects.toThrow("origin down");
+  });
+});