@rangojs/router 0.4.0 → 0.4.2

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

@@ -35,11 +35,14 @@ import type {
   CacheItemResult,
   CacheItemOptions,
   ShellCacheEntry,
+  CacheReadError,
 } from "../types.js";
+import { CACHE_READ_ERROR } from "../types.js";
 import {
   _getRequestContext,
   type RequestContext,
 } from "../../server/request-context.js";
+import { INTERNAL_RANGO_DEBUG } from "../../internal-debug.js";
 import { VERSION } from "@rangojs/router:version";
 import {
   isPerClientSignalHeader,
@@ -260,10 +263,10 @@ interface KVItemEnvelope {
 }
 
 /**
- * KV envelope for PPR shell cache entries.
+ * Coupled Cache API/KV envelope for PPR shell cache entries.
  * @internal
  */
-interface KVShellEnvelope {
+interface CFShellEnvelope {
   /** base64-encoded prelude bytes */
   p: string;
   /** postponed state JSON, or null (DATA variant — no holes) */
@@ -286,6 +289,14 @@ interface KVShellEnvelope {
   i?: string;
   /** Capture data snapshot: recorded cache-store hits/writes for HIT parity */
   sn?: import("../types.js").ShellSnapshotRecord[];
+  /**
+   * ShellCacheEntry.docKey. Must round-trip: navigation-replay eligibility
+   * requires the exact canonical doc segment record named here — dropping the
+   * field reads back as "no consumable record" and every partial navigation
+   * reports `no-segment-snapshot` after a KV round trip (the memory store
+   * passes the entry by reference, so only envelope stores can lose it).
+   */
+  dk?: string;
   /**
    * ShellCacheEntry.handlerLiveHoles. Must round-trip: the serve side arms the
    * handler-free fast path on `!entry.handlerLiveHoles`, so dropping the flag
@@ -299,6 +310,67 @@ interface KVShellEnvelope {
   no?: true;
 }
 
+type CFShellDebugOutcome =
+  | "l1-hit"
+  | "l1-miss"
+  | "kv-hit"
+  | "kv-miss"
+  | "kv-promoted"
+  | "marker-invalidated"
+  | "l1-stored"
+  | "kv-stored"
+  | "write-invalidated";
+
+interface CFShellDebugDetails {
+  tier?: "l1" | "kv";
+  reason?:
+    | "absent"
+    | "timeout"
+    | "error"
+    | "non-200"
+    | "corrupt"
+    | "malformed"
+    | "expired"
+    | "unavailable";
+  freshness?: "fresh" | "stale";
+  status?: number;
+  matchMs?: number;
+  bodyReadMs?: number;
+  markerMs?: number;
+  readMs?: number;
+  expiresAt?: number;
+  remainingTtl?: number;
+}
+
+/** Validate the coupled PPR shell envelope before any field reaches resume. */
+function isShellEnvelope(value: unknown): value is CFShellEnvelope {
+  if (value == null || typeof value !== "object") return false;
+  const envelope = value as Partial<CFShellEnvelope>;
+  return (
+    typeof envelope.p === "string" &&
+    (envelope.po === null || typeof envelope.po === "string") &&
+    typeof envelope.rv === "string" &&
+    (envelope.bv === undefined || typeof envelope.bv === "string") &&
+    typeof envelope.c === "number" &&
+    Number.isFinite(envelope.c) &&
+    typeof envelope.s === "number" &&
+    Number.isFinite(envelope.s) &&
+    typeof envelope.e === "number" &&
+    Number.isFinite(envelope.e) &&
+    (envelope.t === undefined ||
+      (Array.isArray(envelope.t) &&
+        envelope.t.every((tag) => typeof tag === "string"))) &&
+    (envelope.ta === undefined ||
+      (typeof envelope.ta === "number" && Number.isFinite(envelope.ta))) &&
+    (envelope.i === undefined || typeof envelope.i === "string") &&
+    (envelope.sn === undefined || Array.isArray(envelope.sn)) &&
+    (envelope.dk === undefined || typeof envelope.dk === "string") &&
+    (envelope.lh === undefined || typeof envelope.lh === "boolean") &&
+    (envelope.tw === undefined || envelope.tw === true) &&
+    (envelope.no === undefined || envelope.no === true)
+  );
+}
+
 /**
  * KV envelope for document cache entries.
  * @internal
@@ -505,6 +577,36 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     }
   }
 
+  /** Build-time-gated shell tier trace for deployed cross-colo diagnostics. */
+  private debugShell(
+    key: string,
+    outcome: CFShellDebugOutcome,
+    details: CFShellDebugDetails = {},
+  ): void {
+    if (!INTERNAL_RANGO_DEBUG) return;
+    const request = _getRequestContext()?.request as
+      | (Request & { cf?: { colo?: unknown } })
+      | undefined;
+    const ray = request?.headers.get("cf-ray") ?? undefined;
+    const cfColo = request?.cf?.colo;
+    const colo =
+      typeof cfColo === "string"
+        ? cfColo
+        : ray?.includes("-")
+          ? ray.slice(ray.lastIndexOf("-") + 1)
+          : undefined;
+    console.log(
+      `[CFCacheStore][shell] ${JSON.stringify({
+        key,
+        outcome,
+        at: Date.now(),
+        ray,
+        colo,
+        ...details,
+      })}`,
+    );
+  }
+
   /**
    * Resolve the cache-key base URL for the current cache operation.
    * Prefers an explicit `baseUrl` option; otherwise derives it from the live
@@ -883,7 +985,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
    * On L1 miss, falls back to KV (L2) if configured.
    * KV hits are promoted to L1 in the background.
    */
-  async get(key: string): Promise<CacheGetResult | null> {
+  async get(key: string): Promise<CacheGetResult | null | CacheReadError> {
     if (this.isReservedSegmentKey(key, "cache-read")) return null;
     try {
       const cache = await this.getCache();
@@ -897,27 +999,40 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       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)
+        if (matchError) {
+          // A match REJECTION is reported as cache-read and still degrades to
+          // L2/KV -- a real KV value (or KV's own CACHE_READ_ERROR) stands on
+          // its own. But a null KV result (unconfigured namespace, kv-miss,
+          // kv-timeout) is NOT proof of absence under a rejected L1 match:
+          // the only real signal this read produced is the failure, so
+          // surface CACHE_READ_ERROR instead of a replayable miss (the PPR
+          // seeded fallback must render uncached, not substitute the doc
+          // record for a partition the store could not actually read).
           reportCacheError(
             matchError,
             "cache-read",
             "[CFCacheStore] get L1 match",
           );
+          if (this.debug)
+            this.emitDebug({
+              op: "get",
+              key,
+              // 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: "match-error",
+              matchMs,
+            });
+          const kvResult = await this.kvGetSegment(key);
+          return kvResult ?? CACHE_READ_ERROR;
+        }
+        // An abandoned slow match (timedOut) keeps the fail-open latency-budget
+        // policy: degrade to L2/KV, and a KV null stays a miss.
         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",
+            outcome: timedOut ? "match-timeout" : "l1-miss",
             matchMs,
           });
         return this.kvGetSegment(key);
@@ -1098,7 +1213,9 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       // 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;
+      // Distinct from a miss so the PPR replay composition renders uncached
+      // instead of substituting the seeded doc record (CACHE_READ_ERROR).
+      return CACHE_READ_ERROR;
     }
   }
 
@@ -1740,17 +1857,18 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   }
 
   // ============================================================================
-  // Shell Cache Methods (PPR shell resume) — KV-only in v1
+  // Shell Cache Methods (PPR shell resume) — Cache API L1 + KV L2
   // ============================================================================
   //
-  // Unlike the segment/item/document tiers, the shell family has NO Cache-API L1
-  // tier: the prelude bytes + postponed blob are large and version-coupled, and a
-  // per-colo L1 for them is a deliberate follow-up (see the PPR shell-resume
-  // design doc). Shell entries live only in KV (the global tier), so the family
-  // requires a configured KV namespace; without one, getShell/putShell no-op and
-  // the integrated PPR serve path fails open to a full HTML render. Tag invalidation
-  // still applies: shell entries carry tags/taggedAt and are checked against the
-  // same KV markers isGloballyInvalidated() reads for every other tier.
+  // KV remains the durable, cross-colo shell tier. Cache API is a per-colo
+  // read-through accelerator: writes populate both tiers, and a valid KV hit
+  // promotes the same coupled envelope into L1. The family still requires KV;
+  // without it, getShell/putShell no-op and PPR fails open to a full HTML render.
+  //
+  // Shell L1 hits deliberately keep the KV generation-marker check even in
+  // purge mode. A shell's taggedAt is its CAPTURE START, not its write time: an
+  // invalidation can purge while an older capture is still running, then that
+  // capture can land after the purge. The marker check rejects that resurrection.
 
   /**
    * Warn once per isolate that the shell family is inert: getShell/putShell
@@ -1774,10 +1892,10 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   }
 
   /**
-   * Get a cached PPR shell entry by key from KV (no L1). Applies the KV read
-   * budget, corrupt-entry eviction, hard-expiry, and tag invalidation exactly
-   * like kvGetItem, minus the L1 promote. SWR is a plain staleness flag — KV has
-   * no REVALIDATING herd guard, so the capture scheduler's module-level
+   * Get a cached PPR shell entry from Cache API, falling through to KV and
+   * promoting a valid KV hit. Both tiers store one envelope so the prelude,
+   * postponed state, snapshot, versions, and generation metadata cannot mix.
+   * SWR remains a plain staleness flag; the capture scheduler's module-level
    * in-flight set is the recapture stampede guard.
    */
   async getShell(
@@ -1788,55 +1906,128 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       return null;
     }
     try {
-      const kvKey = this.toKVKey(`shell:${key}`);
-      const { value: envelope, timedOut } =
-        await this.kvGetOrEvict<KVShellEnvelope>(
-          kvKey,
-          (e) =>
-            typeof e.p === "string" &&
-            (e.po === null || typeof e.po === "string") &&
-            typeof e.rv === "string" &&
-            typeof e.e === "number" &&
-            typeof e.s === "number",
+      const cache = await this.getCache();
+      const request = this.keyToRequest(`shell:${key}`);
+      const matchStartedAt = INTERNAL_RANGO_DEBUG ? Date.now() : 0;
+      const {
+        response,
+        timedOut,
+        error: matchError,
+      } = await this.matchWithTimeout(cache, request);
+      const matchMs = INTERNAL_RANGO_DEBUG
+        ? Date.now() - matchStartedAt
+        : undefined;
+
+      if (!response) {
+        if (matchError) {
+          reportCacheError(
+            matchError,
+            "cache-read",
+            "[CFCacheStore] getShell L1 match",
+          );
+        }
+        this.debugShell(key, "l1-miss", {
+          reason: matchError ? "error" : timedOut ? "timeout" : "absent",
+          matchMs,
+        });
+        return this.kvGetShell(key);
+      }
+      if (response.status !== 200) {
+        this.debugShell(key, "l1-miss", {
+          reason: "non-200",
+          status: response.status,
+          matchMs,
+        });
+        return this.kvGetShell(key);
+      }
+
+      const bodyStartedAt = INTERNAL_RANGO_DEBUG ? Date.now() : 0;
+      const { value, errored, error } =
+        await this.readJsonWithTimeout<unknown>(response);
+      const bodyReadMs = INTERNAL_RANGO_DEBUG
+        ? Date.now() - bodyStartedAt
+        : undefined;
+      if (value === undefined) {
+        this.debugShell(key, "l1-miss", {
+          reason: errored ? "corrupt" : "timeout",
+          matchMs,
+          bodyReadMs,
+        });
+        if (errored) {
+          return this.healCorruptL1(cache, request, error, "getShell", () =>
+            this.kvGetShell(key),
+          );
+        }
+        return this.kvGetShell(key);
+      }
+      if (!isShellEnvelope(value)) {
+        this.debugShell(key, "l1-miss", {
+          reason: "malformed",
+          matchMs,
+          bodyReadMs,
+        });
+        return this.healCorruptL1(
+          cache,
+          request,
+          new Error("malformed/partial L1 shell envelope"),
           "getShell",
+          () => this.kvGetShell(key),
         );
-      // A timeout, a missing key, or an already-evicted corrupt entry is a miss.
-      if (timedOut || !envelope) return null;
+      }
 
       const now = Date.now();
-      if (now > envelope.e) return null;
+      if (now > value.e) {
+        this.debugShell(key, "l1-miss", {
+          reason: "expired",
+          matchMs,
+          bodyReadMs,
+          expiresAt: value.e,
+        });
+        return this.kvGetShell(key);
+      }
 
-      if (await this.isGloballyInvalidated(envelope.t, envelope.ta)) {
+      // Unlike other L1 families, shells always check the durable generation
+      // marker. See the capture-start/purge race documented above.
+      const markerStartedAt = INTERNAL_RANGO_DEBUG ? Date.now() : 0;
+      const invalidated = await this.isGloballyInvalidated(value.t, value.ta);
+      const markerMs = INTERNAL_RANGO_DEBUG
+        ? Date.now() - markerStartedAt
+        : undefined;
+      if (invalidated) {
+        this.debugShell(key, "marker-invalidated", {
+          tier: "l1",
+          matchMs,
+          bodyReadMs,
+          markerMs,
+        });
         return null;
       }
 
-      const shouldRevalidate = envelope.s > 0 && now > envelope.s;
+      const shouldRevalidate = value.s > 0 && now > value.s;
+      this.debugShell(key, "l1-hit", {
+        freshness: shouldRevalidate ? "stale" : "fresh",
+        matchMs,
+        bodyReadMs,
+        markerMs,
+        expiresAt: value.e,
+      });
       return {
-        entry: {
-          prelude: envelope.p,
-          postponed: envelope.po,
-          reactVersion: envelope.rv,
-          buildVersion: envelope.bv,
-          initialTheme: envelope.i,
-          snapshot: envelope.sn,
-          handlerLiveHoles: envelope.lh,
-          transitionWhen: envelope.tw,
-          navigationOnly: envelope.no,
-          createdAt: envelope.c,
-        },
+        entry: this.shellEnvelopeToEntry(value),
         shouldRevalidate,
       };
     } catch (error) {
       reportCacheError(error, "cache-read", "[CFCacheStore] getShell");
-      return null;
+      this.debugShell(key, "l1-miss", { reason: "error" });
+      return this.kvGetShell(key);
     }
   }
 
   /**
-   * Store a PPR shell entry in KV with TTL and optional SWR window. The write is
-   * registered with waitUntil and awaited so invalidation rejection can be
-   * acknowledged to the capture scheduler. The tags/taggedAt ride in the envelope
-   * so isGloballyInvalidated() can invalidate the shell via the shared KV markers.
+   * Store a PPR shell envelope in Cache API and, when its retention meets KV's
+   * 60-second floor, KV. The shared write is registered with waitUntil and
+   * awaited so invalidation rejection can be acknowledged to the capture
+   * scheduler. Short-lived shells remain useful in L1 even though KV rejects
+   * them.
    */
   async putShell(
     key: string,
@@ -1845,9 +2036,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     swrSeconds?: number,
     tags?: string[],
   ): Promise<"stored" | "invalidated" | void> {
-    // KV-only tier: needs a KV namespace and waitUntil. The same write promise is
-    // registered for isolate lifetime and awaited so invalidation rejection can
-    // be acknowledged to the capture scheduler.
+    // KV remains required for durable generation markers and cross-colo reads.
     if (!this.kv) {
       this.warnShellFamilyInertOnce();
       return;
@@ -1857,9 +2046,6 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       const ttl = resolveTtl(ttlSeconds, this.defaults, DEFAULT_FUNCTION_TTL);
       const swrWindow = resolveSwrWindow(swrSeconds, this.defaults);
       const totalTtl = ttl + swrWindow;
-      // KV requires expirationTtl >= 60s; skip a shorter-lived shell rather than
-      // letting kv.put reject inside waitUntil (mirrors setItem/kvSetSegment).
-      if (totalTtl < 60) return;
 
       const retentionTtl =
         tags && tags.length > 0 && this.tagInvalidationTtl
@@ -1872,54 +2058,93 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
         Array.isArray(tags) && tags.length > 0 ? entry.createdAt : undefined;
 
       const kvKey = this.toKVKey(`shell:${key}`);
-      // A key over the KV limit makes kv.put reject deep inside waitUntil; report
-      // and skip the doomed write (mirrors kvSetSegment).
+      let writeKv = retentionTtl >= KV_MIN_EXPIRATION_TTL;
       const kvKeyBytes = kvKeyByteLength(kvKey);
       if (kvKeyBytes > KV_MAX_KEY_BYTES) {
         reportCacheError(
           new Error(
             `shell cache key produces a ${kvKeyBytes}-byte KV key, over the ` +
-              `${KV_MAX_KEY_BYTES}-byte limit; the shell was not persisted.`,
+              `${KV_MAX_KEY_BYTES}-byte limit; the shell was not persisted to KV (L2).`,
           ),
           "cache-write",
           "[CFCacheStore] putShell",
         );
-        return;
+        writeKv = false;
       }
 
       const write = (async (): Promise<"stored" | "invalidated" | void> => {
-        try {
-          if (
-            tags &&
-            tags.length > 0 &&
-            (await this.isGloballyInvalidated(tags, entry.createdAt))
-          ) {
-            return "invalidated";
-          }
-          const envelope: KVShellEnvelope = {
-            p: entry.prelude,
-            po: entry.postponed,
-            rv: entry.reactVersion,
-            bv: entry.buildVersion,
-            c: entry.createdAt,
-            s: staleAt,
-            e: expiresAt,
-            t: tags,
-            ta: taggedAt,
-            i: entry.initialTheme,
-            sn: entry.snapshot,
-            lh: entry.handlerLiveHoles,
-            tw: entry.transitionWhen,
-            no: entry.navigationOnly,
-          };
-          await this.kv!.put(kvKey, JSON.stringify(envelope), {
-            expirationTtl: retentionTtl,
-          });
-          return "stored";
-        } catch (error) {
-          reportCacheError(error, "cache-write", "[CFCacheStore] putShell");
-          return undefined;
+        if (
+          tags &&
+          tags.length > 0 &&
+          (await this.isGloballyInvalidated(tags, entry.createdAt))
+        ) {
+          this.debugShell(key, "write-invalidated");
+          return "invalidated";
+        }
+
+        const envelope: CFShellEnvelope = {
+          p: entry.prelude,
+          po: entry.postponed,
+          rv: entry.reactVersion,
+          bv: entry.buildVersion,
+          c: entry.createdAt,
+          s: staleAt,
+          e: expiresAt,
+          t: tags,
+          ta: taggedAt,
+          i: entry.initialTheme,
+          sn: entry.snapshot,
+          dk: entry.docKey,
+          lh: entry.handlerLiveHoles,
+          tw: entry.transitionWhen,
+          no: entry.navigationOnly,
+        };
+        const body = JSON.stringify(envelope);
+        const writes: Promise<boolean>[] = [
+          (async () => {
+            try {
+              const cache = await this.getCache();
+              await cache.put(
+                this.keyToRequest(`shell:${key}`),
+                this.shellEnvelopeResponse(body, envelope),
+              );
+              this.debugShell(key, "l1-stored", {
+                expiresAt: envelope.e,
+              });
+              return true;
+            } catch (error) {
+              reportCacheError(
+                error,
+                "cache-write",
+                "[CFCacheStore] putShell L1",
+              );
+              return false;
+            }
+          })(),
+        ];
+        if (writeKv) {
+          writes.push(
+            (async () => {
+              try {
+                await this.kv!.put(kvKey, body, {
+                  expirationTtl: retentionTtl,
+                });
+                this.debugShell(key, "kv-stored", {
+                  expiresAt: envelope.e,
+                });
+                return true;
+              } catch (error) {
+                reportCacheError(
+                  error,
+                  "cache-write",
+                  "[CFCacheStore] putShell L2",
+                );
+                return false;
+              }
+            })(),
+          );
         }
+        return (await Promise.all(writes)).some(Boolean) ? "stored" : undefined;
       })();
       this.waitUntil(async () => {
         await write;
@@ -1930,6 +2155,141 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     }
   }
 
+  /** Rebuild the public shell entry from its validated storage envelope. */
+  private shellEnvelopeToEntry(envelope: CFShellEnvelope): ShellCacheEntry {
+    return {
+      prelude: envelope.p,
+      postponed: envelope.po,
+      reactVersion: envelope.rv,
+      buildVersion: envelope.bv,
+      initialTheme: envelope.i,
+      snapshot: envelope.sn,
+      docKey: envelope.dk,
+      handlerLiveHoles: envelope.lh,
+      transitionWhen: envelope.tw,
+      navigationOnly: envelope.no,
+      createdAt: envelope.c,
+    };
+  }
+
+  /** Build the Cache API representation of the coupled shell envelope. */
+  private shellEnvelopeResponse(
+    body: string,
+    envelope: CFShellEnvelope,
+  ): Response {
+    const remainingTtl = Math.max(
+      1,
+      Math.floor((envelope.e - Date.now()) / 1000),
+    );
+    return new Response(body, {
+      headers: {
+        "Content-Type": "application/json",
+        "Cache-Control": `public, max-age=${remainingTtl}`,
+        [CACHE_STALE_AT_HEADER]: String(envelope.s),
+        [CACHE_EXPIRES_AT_HEADER]: String(envelope.e),
+        [CACHE_STATUS_HEADER]: "HIT",
+        ...this.tagHeaderEntries(envelope.t, envelope.ta),
+      },
+    });
+  }
+
+  /** KV shell fallback with corruption checks and background L1 promotion. */
+  private async kvGetShell(
+    key: string,
+  ): Promise<{ entry: ShellCacheEntry; shouldRevalidate?: boolean } | null> {
+    if (!this.kv) return null;
+    try {
+      const readStartedAt = INTERNAL_RANGO_DEBUG ? Date.now() : 0;
+      const kvKey = this.toKVKey(`shell:${key}`);
+      const { value: envelope, timedOut } =
+        await this.kvGetOrEvict<CFShellEnvelope>(
+          kvKey,
+          isShellEnvelope,
+          "getShell",
+        );
+      const readMs = INTERNAL_RANGO_DEBUG
+        ? Date.now() - readStartedAt
+        : undefined;
+      if (timedOut || !envelope) {
+        this.debugShell(key, "kv-miss", {
+          reason: timedOut ? "timeout" : "unavailable",
+          readMs,
+        });
+        return null;
+      }
+
+      const now = Date.now();
+      if (now > envelope.e) {
+        this.debugShell(key, "kv-miss", {
+          reason: "expired",
+          readMs,
+          expiresAt: envelope.e,
+        });
+        return null;
+      }
+      const markerStartedAt = INTERNAL_RANGO_DEBUG ? Date.now() : 0;
+      const invalidated = await this.isGloballyInvalidated(
+        envelope.t,
+        envelope.ta,
+      );
+      const markerMs = INTERNAL_RANGO_DEBUG
+        ? Date.now() - markerStartedAt
+        : undefined;
+      if (invalidated) {
+        this.debugShell(key, "marker-invalidated", {
+          tier: "kv",
+          readMs,
+          markerMs,
+        });
+        return null;
+      }
+
+      const shouldRevalidate = envelope.s > 0 && now > envelope.s;
+      this.debugShell(key, "kv-hit", {
+        freshness: shouldRevalidate ? "stale" : "fresh",
+        readMs,
+        markerMs,
+        expiresAt: envelope.e,
+      });
+      this.promoteShellToL1(key, envelope);
+      return {
+        entry: this.shellEnvelopeToEntry(envelope),
+        shouldRevalidate,
+      };
+    } catch (error) {
+      reportCacheError(error, "cache-read", "[CFCacheStore] kvGetShell");
+      this.debugShell(key, "kv-miss", { reason: "error" });
+      return null;
+    }
+  }
+
+  /** Promote a valid KV shell into the per-colo Cache API tier. */
+  private promoteShellToL1(key: string, envelope: CFShellEnvelope): void {
+    if (!this.waitUntil) return;
+    this.waitUntil(() =>
+      reportingAsync(
+        async () => {
+          if (Date.now() > envelope.e) return;
+          const cache = await this.getCache();
+          const body = JSON.stringify(envelope);
+          await cache.put(
+            this.keyToRequest(`shell:${key}`),
+            this.shellEnvelopeResponse(body, envelope),
+          );
+          this.debugShell(key, "kv-promoted", {
+            remainingTtl: Math.max(
+              1,
+              Math.floor((envelope.e - Date.now()) / 1000),
+            ),
+            expiresAt: envelope.e,
+          });
+        },
+        "cache-write",
+        "[CFCacheStore] promoteShellToL1",
+      ),
+    );
+  }
+
   // ============================================================================
   // Key Helpers
   // ============================================================================
@@ -2817,7 +3177,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   private async kvGetSegment(
     key: string,
     opts?: { suppressRevalidate?: boolean },
-  ): Promise<CacheGetResult | null> {
+  ): Promise<CacheGetResult | null | CacheReadError> {
     if (!this.kv) return null;
 
     try {
@@ -2886,7 +3246,15 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     } catch (error) {
       reportCacheError(error, "cache-read", "[CFCacheStore] kvGetSegment");
       if (this.debug) this.emitDebug({ op: "get", key, outcome: "error" });
-      return null;
+      // A KV failure is NOT proof of absence: returning null classified it a
+      // real miss and let the PPR seeded fallback substitute the doc record
+      // for a key partition the store could not actually read. Same sentinel
+      // as get()'s own catch — lookupRouteDetailed classifies it `error` and
+      // the render stays uncached. (A kvGetOrEvict TIMEOUT above stays null
+      // by design: it is a bounded-latency degrade of a likely-healthy read,
+      // and serving the equivalent seeded record there is the fallback
+      // working as intended, not a masked failure.)
+      return CACHE_READ_ERROR;
     }
   }