@rangojs/router 0.5.1 → 0.5.2

package/skills/use-cache/SKILL.md

@@ -307,6 +307,53 @@ intercept("@modal", ".product", async (ctx) => {
 }),
 ```
 
+## Embedding server actions in cached components
+
+A cached function may return a component that creates an inline `"use server"`
+action. The canonical case is a cached list whose items each carry an action --
+e.g. a cached article list where every row has a like button:
+
+```typescript
+export async function ArticleList() {
+  "use cache: articles";
+  const articles = await db.query("SELECT id, title FROM articles");
+  return (
+    <ul>
+      {articles.map((a) => {
+        const articleId = a.id; // captured -> frozen with the cache entry
+        async function like() {
+          "use server";
+          // runs live on click, in the CURRENT request scope
+          const user = cookies().get("session")?.value;
+          if (user) await db.like(articleId, user);
+        }
+        return <LikeButton key={a.id} title={a.title} action={like} />;
+      })}
+    </ul>
+  );
+}
+```
+
+Three behaviors, locked by `use-cache-inline-action.test.ts` (dev + prod):
+
+| What                                            | Behavior                  | Why                                                                                                                                                                           |
+| ----------------------------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Values the action **closes over** (`articleId`) | **Frozen** at cache-write | The closure compiles to encrypted bound args, snapshotted when the entry is written and replayed verbatim on a hit. Correct for stable identities; wrong for volatile values. |
+| The action **body**                             | **Runs live** every call  | Once invoked it is an ordinary server function: fresh computation and live request context. `cookies()` / `headers()` work here (the body executes in the live request).      |
+| Invocability on a **cache hit**                 | **Works**                 | The action survives serialize -> cache -> deserialize and stays callable.                                                                                                     |
+
+Rule of thumb: **capture stable identities, read volatile/request-scoped values
+live in the body.** Do not close over a per-request token, the current user, or
+the current time and expect freshness -- those are frozen at cache-write. The
+`cookies()`/`headers()` read guard applies to the cached function body, NOT to an
+inline action's body.
+
+Deploy note: captured values are encrypted with a per-build key by default. If
+cache entries can outlive a deploy (a persistent store such as the Cloudflare
+cache store), set `RANGO_ENCRYPTION_KEY` (base64-encoded 32 bytes) in the build
+environment so actions embedded in entries written by a previous deploy still
+decrypt; without it they fail until the entry expires or revalidates.
+
 ## Vite Transform
 
 The `rango:use-cache` Vite plugin detects the directive and wraps exports with

package/src/browser/event-controller.ts

@@ -234,6 +234,12 @@ export interface EventController {
     listener: ActionStateListener,
   ): () => void;
   subscribeToHandles(listener: HandleListener): () => void;
+  /**
+   * Deliver queued location, params, navigation, and handle notifications now.
+   * NavigationProvider calls this inside the payload update so React assigns
+   * every route-state hook update to the same normal or transition lane.
+   */
+  flushRouteState(): void;
 
   // Handle operations
   setHandleData(
@@ -367,19 +373,32 @@ function matchesActionId(
   return entryActionId.endsWith(`#${subscriptionId}`);
 }
 
-// Batch rapid notifications into one microtask to prevent render storms
-function makeDebouncedNotifier(listeners: Set<() => void>): () => void {
+interface DebouncedNotifier {
+  schedule(): void;
+  flush(): void;
+}
+
+// Batch rapid notifications into one task to prevent render storms. The
+// explicit flush lets a React update owner preserve its scheduling lane.
+function makeDebouncedNotifier(listeners: Set<() => void>): DebouncedNotifier {
   let timeout: ReturnType<typeof setTimeout> | null = null;
-  return () => {
-    if (timeout !== null) clearTimeout(timeout);
-    timeout = setTimeout(() => {
-      timeout = null;
-      notifyListeners(
-        [...listeners],
-        (listener) => listener(),
-        (listener) => listeners.has(listener),
-      );
-    }, 0);
+  const flush = () => {
+    if (timeout === null) return;
+    clearTimeout(timeout);
+    timeout = null;
+    notifyListeners(
+      [...listeners],
+      (listener) => listener(),
+      (listener) => listeners.has(listener),
+    );
+  };
+
+  return {
+    schedule() {
+      if (timeout !== null) clearTimeout(timeout);
+      timeout = setTimeout(flush, 0);
+    },
+    flush,
   };
 }
 
@@ -459,7 +478,7 @@ export function createEventController(
 
   function notify(): void {
     cachedDerivedState = null;
-    notifyStateListeners();
+    notifyStateListeners.schedule();
   }
 
   const actionNotifyTimeouts = new Map<string, ReturnType<typeof setTimeout>>();
@@ -517,6 +536,11 @@ export function createEventController(
 
   const notifyHandles = makeDebouncedNotifier(handleListeners);
 
+  function flushRouteState(): void {
+    notifyStateListeners.flush();
+    notifyHandles.flush();
+  }
+
   function getState(): DerivedNavigationState {
     if (cachedDerivedState) return cachedDerivedState;
 
@@ -1001,7 +1025,7 @@ export function createEventController(
     handleSegmentOrder = newSegmentOrder;
     routeSegmentIds = newRouteSegmentIds;
 
-    notifyHandles();
+    notifyHandles.schedule();
   }
 
   function getHandleState(): HandleState {
@@ -1021,7 +1045,7 @@ export function createEventController(
       return;
     }
     routeSegmentIds = next;
-    notifyHandles();
+    notifyHandles.schedule();
   }
 
   // ========================================================================
@@ -1102,6 +1126,7 @@ export function createEventController(
     subscribe,
     subscribeToAction,
     subscribeToHandles,
+    flushRouteState,
 
     // Direct access
     getCurrentNavigation: () => currentNavigation,

package/src/browser/partial-update.ts

@@ -421,10 +421,8 @@ export function createPartialUpdater(
         // forceAwait unwraps the ROUTER loader promises during render so they
         // land without a loading()/fallback frame. A fully-prefetched nav has
         // its router data already resolved (the prefetch stream drained), so
-        // awaiting it here is free and lets us commit NORMALLY (not in a
-        // transition) below — a normal commit still shows fallbacks for any
-        // CLIENT component that suspends on mount, which a transition would
-        // wrongly suppress by holding the old UI until that suspense settles.
+        // awaiting it here is free; the commit below then runs in a transition
+        // (fullyPrefetched branch) so nothing router-owned can flash.
         forceAwait: mode.type === "stale-revalidation" || fullyPrefetched,
         interceptSegments:
           reconciled.interceptSegments.length > 0
@@ -549,14 +547,31 @@ export function createPartialUpdater(
             scroll: scrollPayload,
           });
         });
+      } else if (fullyPrefetched) {
+        // Fully-prefetched nav: the payload is fully resolved (forceAwait
+        // above), so commit inside a transition to hold the current UI across
+        // the synchronous resolution — no fallback flash. No addTransitionType:
+        // this is the React content-hold, not a view transition. Deliberate
+        // trade-off (#622 introduced, #624 reverted, then reinstated): a client
+        // component that suspends during its FIRST render (use() of a promise
+        // created at mount — see ClientMountSuspense in the e2e test-app) under
+        // an ALREADY-REVEALED boundary holds the old content until it resolves
+        // instead of revealing that boundary's fallback; its render happens
+        // pre-commit inside the transition, so userland effects cannot run
+        // first. Boundaries newly mounted by this nav still reveal their
+        // fallbacks (React shows new boundaries inside transitions).
+        startTransition(() => {
+          onUpdate({
+            root: newTree,
+            metadata: payload.metadata!,
+            scroll: scrollPayload,
+          });
+        });
       } else {
-        // Normal commit for ALL navs here, never a transition (see the
-        // forceAwait comment above for why prefetched router data lands
-        // without fallback frames). A transition would hold the OLD UI until
-        // every suspense in the new tree settles — including a client
-        // component that only starts fetching post-mount, retaining the
-        // previous page indefinitely. Explicit transition() routes keep the
-        // content-hold via the hasTransition branch above (the opt-in).
+        // Cold/partially-prefetched nav: normal commit so fallbacks stream
+        // like a first load and the click has visible feedback. Explicit
+        // transition() routes keep the content-hold via the hasTransition
+        // branch above (the opt-in).
         onUpdate({
           root: newTree,
           metadata: payload.metadata!,

package/src/browser/react/NavigationProvider.tsx

@@ -456,6 +456,13 @@ export function NavigationProvider({
           cached === undefined ? update.metadata.resolvedIds : undefined,
         );
       }
+
+      // tx.commit() and the metadata updates above mutate the controller
+      // synchronously, but its ordinary notifications are task-debounced. Flush
+      // them here so hook setState calls inherit this payload update's lane. In
+      // a transition that suspends, the source tree therefore keeps its source
+      // pathname/params until the destination payload commits with them.
+      eventController.flushRouteState();
     });
 
     return unsubscribe;

package/src/cache/cache-runtime.ts

@@ -205,8 +205,63 @@ interface CacheEnvelope {
  * singleton), and cleared for a key as soon as the leader settles: a rejected
  * leader (function threw, or the result was not serializable) propagates to
  * current waiters, which then retry fresh.
+ *
+ * A leader that NEVER settles must not hang followers (scar tissue, autobarn
+ * pilot outage): a background shell capture's render became leader, awaited a
+ * tarpitting upstream fetch, and workerd killed the capture's waitUntil context
+ * — orphaning the leader promise as permanently pending, its map entry never
+ * cleared. Every later document render calling the same cached function (an
+ * isolate-global key for plain-args calls) awaited it forever before first
+ * byte: isolate-wide TTFB-0 until redeploy. Followers therefore trust an entry
+ * only for {@link IN_FLIGHT_LEADER_MAX_WAIT_MS} from registration; past it
+ * they evict the entry and run fresh — bounded duplicate upstream work instead
+ * of an unbounded hang. Eviction is age-based off `registeredAt`, so it also
+ * heals entries stranded by a killed context (no timer in that context needs
+ * to survive).
+ */
+interface InFlightExecution {
+  promise: Promise<CacheEnvelope>;
+  registeredAt: number;
+}
+
+const inFlightExecutions = new Map<string, InFlightExecution>();
+
+/**
+ * How long a follower trusts an in-flight leader before evicting it and
+ * running fresh. High enough that a slow-but-healthy upstream never triggers
+ * duplicate work (a legitimate cached call taking >15s is already pathological);
+ * low enough to bound the blast radius of a wedged leader to seconds, not the
+ * isolate lifetime. Aligned with SHELL_CAPTURE_MAX_WAIT_MS.
+ */
+const IN_FLIGHT_LEADER_MAX_WAIT_MS = 15_000;
+
+/** Distinguishes a leader timeout from a leader rejection in raceLeader. */
+const LEADER_TIMED_OUT = Symbol("leader-timed-out");
+
+/**
+ * Await a leader's envelope for at most `remainingMs`. Resolves with the
+ * envelope, `undefined` on leader rejection (the leader already cleared its
+ * entry — caller falls through to a fresh run), or {@link LEADER_TIMED_OUT}
+ * when the window expires first (caller must evict the entry itself).
  */
-const inFlightExecutions = new Map<string, Promise<CacheEnvelope>>();
+function raceLeader(
+  promise: Promise<CacheEnvelope>,
+  remainingMs: number,
+): Promise<CacheEnvelope | undefined | typeof LEADER_TIMED_OUT> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => resolve(LEADER_TIMED_OUT), remainingMs);
+    promise.then(
+      (envelope) => {
+        clearTimeout(timer);
+        resolve(envelope);
+      },
+      () => {
+        clearTimeout(timer);
+        resolve(undefined);
+      },
+    );
+  });
+}
 
 // ============================================================================
 // Core: registerCachedFunction
@@ -541,20 +596,34 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     // requests. The store write stays exactly once (the leader's).
     const existing = inFlightExecutions.get(cacheKey);
     if (existing) {
-      let envelope: CacheEnvelope | undefined;
-      try {
-        envelope = await existing;
-      } catch {
-        // Leader rejected (function threw or its result was not serializable);
-        // its map entry is already cleared, so fall through to a fresh run.
-        envelope = undefined;
-      }
-      if (envelope) {
+      const remainingMs =
+        IN_FLIGHT_LEADER_MAX_WAIT_MS - (Date.now() - existing.registeredAt);
+      const raced =
+        remainingMs <= 0
+          ? LEADER_TIMED_OUT
+          : await raceLeader(existing.promise, remainingMs);
+      if (raced === LEADER_TIMED_OUT) {
+        // Wedged (or context-orphaned) leader: evict so this call and every
+        // later one run fresh. Guard the delete so a newer leader's entry is
+        // never removed; the stale leader's own clearSelf is identity-guarded
+        // the same way, so it can't evict our replacement if it settles late.
+        if (inFlightExecutions.get(cacheKey) === existing) {
+          inFlightExecutions.delete(cacheKey);
+        }
+        reportCacheError(
+          new Error(
+            `in-flight leader did not settle within ${IN_FLIGHT_LEADER_MAX_WAIT_MS}ms; evicted — executing fresh`,
+          ),
+          "cache-read",
+          `[use cache] "${id}" inflight-timeout`,
+        );
+        // Fall through to a fresh execution below (this call becomes leader).
+      } else if (raced) {
         try {
           return await serveCached({
-            value: envelope.serialized,
-            handles: envelope.handles,
-            tags: envelope.tags,
+            value: raced.serialized,
+            handles: raced.handles,
+            tags: raced.tags,
             shouldRevalidate: false,
           });
         } catch (error) {
@@ -566,6 +635,8 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
           // Fall through to a fresh execution below.
         }
       }
+      // raced === undefined: leader rejected; its map entry is already
+      // cleared, so fall through to a fresh run.
     }
 
     // This call becomes the leader. Register a deferred envelope so concurrent
@@ -582,9 +653,12 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     // Followers attach their own catch; guard the map's own reference so a
     // rejected envelope with no waiter is not an unhandled rejection.
     envelopePromise.catch(() => {});
-    inFlightExecutions.set(cacheKey, envelopePromise);
+    inFlightExecutions.set(cacheKey, {
+      promise: envelopePromise,
+      registeredAt: Date.now(),
+    });
     const clearSelf = (): void => {
-      if (inFlightExecutions.get(cacheKey) === envelopePromise) {
+      if (inFlightExecutions.get(cacheKey)?.promise === envelopePromise) {
         inFlightExecutions.delete(cacheKey);
       }
     };

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

@@ -85,8 +85,15 @@ export const MAX_REVALIDATION_INTERVAL = 30;
  *
  * This is the default; override per store via
  * `CFCacheStoreOptions.edgeLookupTimeoutMs` (<= 0 disables the budget).
+ *
+ * 25ms, raised from 10: production Workers logs (autobarn pilot) showed the
+ * 10ms budget firing frequently on cold colos where the first Cache API touch
+ * is slow but healthy — each false positive downgrades a warm L1 HIT to an
+ * L2/render round trip that costs far more than the 15ms of extra patience.
+ * A genuinely degraded colo still gets cut off; tune per store for
+ * shell-critical routes.
  */
-export const EDGE_LOOKUP_TIMEOUT_MS = 10;
+export const EDGE_LOOKUP_TIMEOUT_MS = 25;
 
 /**
  * Maximum time (ms) to wait for the BODY of a matched L1 entry to be read

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

@@ -57,10 +57,13 @@ import { reportCacheError, reportingAsync } from "../cache-error.js";
 import type { CacheErrorCategory } from "../cache-error.js";
 import { bufferToBase64, base64ToBuffer } from "./cf-base64.js";
 import {
+  KV_KEY_PRESERVED_PREFIX_BYTES,
   KV_MAX_KEY_BYTES,
   KV_MIN_EXPIRATION_TTL,
   kvKeyByteLength,
+  kvKeyDigest,
   remainingCacheControl,
+  truncateToBytes,
 } from "./cf-kv-utils.js";
 import {
   TAG_MARKER_CACHE_PREFIX,
@@ -1325,7 +1328,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
 
       // L2: delete from KV
       if (this.kv && this.waitUntil) {
-        const kvKey = this.toKVKey(key);
+        const kvKey = await this.toKVKey(key);
         this.waitUntil(() =>
           reportingAsync(
             () => this.kv!.delete(kvKey),
@@ -1559,7 +1562,7 @@ 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.toDocKVKey(key);
+        const kvKey = await this.toDocKVKey(key);
         // Finding #3: never persist a per-client signal in the KV envelope.
         const headersArray: [string, string][] = [];
         response.headers.forEach((v, k) => {
@@ -1848,7 +1851,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       // JSON.stringify(KVItemEnvelope); field names differ from L1 so we assemble
       // from the pre-escaped value/handles pieces rather than re-stringifying.
       if (this.kv && this.waitUntil && totalTtl >= 60) {
-        const kvKey = this.toKVKey(`fn:${key}`);
+        const kvKey = await this.toKVKey(`fn:${key}`);
         const expiresAt = staleAt + swrWindow * 1000;
         let envelopeJson = `{"v":${valueJson}`;
         if (handlesJson !== undefined) envelopeJson += `,"h":${handlesJson}`;
@@ -2073,20 +2076,8 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       const taggedAt =
         Array.isArray(tags) && tags.length > 0 ? entry.createdAt : undefined;
 
-      const kvKey = this.toKVKey(`shell:${key}`);
-      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 to KV (L2).`,
-          ),
-          "cache-write",
-          "[CFCacheStore] putShell",
-        );
-        writeKv = false;
-      }
+      const kvKey = await this.toKVKey(`shell:${key}`);
+      const writeKv = retentionTtl >= KV_MIN_EXPIRATION_TTL;
 
       const write = (async (): Promise<"stored" | "invalidated" | void> => {
         if (
@@ -2219,7 +2210,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     if (!this.kv) return null;
     try {
       const readStartedAt = INTERNAL_RANGO_DEBUG ? Date.now() : 0;
-      const kvKey = this.toKVKey(`shell:${key}`);
+      const kvKey = await this.toKVKey(`shell:${key}`);
       const { value: envelope, timedOut } =
         await this.kvGetOrEvict<CFShellEnvelope>(
           kvKey,
@@ -2330,11 +2321,27 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   /**
    * Convert string key to KV key string.
    * Uses same version prefix as Cache API for consistent invalidation.
+   *
+   * Single chokepoint for EVERY KV family (segments, items, shells, documents
+   * via toDocKVKey, tag markers via tagMarkerKey): a composed key over
+   * Cloudflare KV's 512-byte limit is normalized to a preserved readable
+   * prefix plus a SHA-256-derived 128-bit digest of the FULL key. Without
+   * this, kv.put/get reject with `414 ... exceeds key length limit of 512`
+   * and the entry silently never reaches L2 (observed in production for
+   * "use cache" items whose serialized args — e.g. a CMS query object — blow
+   * the cap; autobarn pilot). Keys are opaque storage identifiers, so
+   * normalization is semantics-preserving as long as distinct logical keys
+   * stay distinct: colliding requires an identical 400-byte prefix AND a
+   * 128-bit SHA-256 collision. Deterministic, so every family's read, write,
+   * and delete paths agree on the stored key.
    * @internal
    */
-  private toKVKey(key: string): string {
+  private async toKVKey(key: string): Promise<string> {
     const versionPath = this.version ? `v/${this.version}/` : "";
-    return `${versionPath}${key}`;
+    const composed = `${versionPath}${key}`;
+    if (kvKeyByteLength(composed) <= KV_MAX_KEY_BYTES) return composed;
+    const prefix = truncateToBytes(composed, KV_KEY_PRESERVED_PREFIX_BYTES);
+    return `${prefix}~${await kvKeyDigest(composed)}`;
   }
 
   /**
@@ -2364,7 +2371,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
    * document tier is the one with a request-host context here.
    * @internal
    */
-  private toDocKVKey(key: string): string {
+  private toDocKVKey(key: string): Promise<string> {
     return this.toKVKey(`h/${this.docKVHost()}/doc:${key}`);
   }
 
@@ -2480,7 +2487,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   // ============================================================================
 
   /** KV key for a tag's invalidation marker. */
-  private tagMarkerKey(tag: string): string {
+  private tagMarkerKey(tag: string): Promise<string> {
     return this.toKVKey(`${TAG_MARKER_PREFIX}${tag}`);
   }
 
@@ -2805,7 +2812,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     // (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" }),
+      async () => this.kv!.get(await this.tagMarkerKey(tag), { type: "text" }),
       this.kvReadTimeoutMs,
       "tag marker KV read",
     );
@@ -3012,7 +3019,8 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
    *
    * Durable-write integrity: the in-memory write-through (memo + L1) for a tag
    * runs ONLY after that tag's KV marker write is confirmed. If any KV write
-   * fails (transient error, or an over-512-byte key), this rejects with the
+   * fails (transient error; over-limit keys are normalized by toKVKey rather
+   * than rejected), this rejects with the
    * failed tags so an awaiting updateTag() surfaces the failure instead of
    * silently reporting success while other requests/colos serve stale data. The
    * eager purge still fires for the whole batch first (it is additive).
@@ -3065,18 +3073,10 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       }
       await Promise.all(
         tags.map(async (tag) => {
-          const markerKey = this.tagMarkerKey(tag);
-          const markerKeyBytes = kvKeyByteLength(markerKey);
-          if (markerKeyBytes > KV_MAX_KEY_BYTES) {
-            failedTags.add(tag);
-            errors.push(
-              new Error(
-                `tag "${tag}" produces a ${markerKeyBytes}-byte KV ` +
-                  `marker key, over the ${KV_MAX_KEY_BYTES}-byte limit`,
-              ),
-            );
-            return;
-          }
+          // An over-limit tag no longer rejects: tagMarkerKey normalizes
+          // through toKVKey, and the marker read path derives the key the same
+          // way, so oversized tags invalidate correctly instead of erroring.
+          const markerKey = await this.tagMarkerKey(tag);
           try {
             await this.kv!.put(markerKey, String(invalidatedAt), {
               ...(this.tagInvalidationTtl
@@ -3200,7 +3200,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     if (!this.kv) return null;
 
     try {
-      const kvKey = this.toKVKey(key);
+      const kvKey = await this.toKVKey(key);
       const { value: envelope, timedOut } =
         await this.kvGetOrEvict<KVSegmentEnvelope>(
           kvKey,
@@ -3294,29 +3294,6 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     // KV requires expirationTtl >= 60s. Skip write for short-lived entries.
     if (!this.kv || !this.waitUntil || totalTtl < 60) return;
 
-    const kvKey = this.toKVKey(key);
-
-    // Reject an oversized data-segment KV key the same way tag-marker keys are
-    // rejected in invalidateTags(). A key over KV_MAX_KEY_BYTES makes kv.put()
-    // fail, so the segment silently never lands in L2 (KV) and every cold-colo
-    // or TTL-expired read re-renders instead of serving stale. Segment keys can
-    // grow with user-controlled inputs (e.g. a route's search params), so report
-    // a clear, actionable error and skip the doomed write rather than letting it
-    // reject deep inside waitUntil as an opaque cache-write failure.
-    const kvKeyBytes = kvKeyByteLength(kvKey);
-    if (kvKeyBytes > KV_MAX_KEY_BYTES) {
-      reportCacheError(
-        new Error(
-          `cache segment key produces a ${kvKeyBytes}-byte KV key, over the ` +
-            `${KV_MAX_KEY_BYTES}-byte limit; the segment was not persisted to KV (L2). ` +
-            `Reduce the cache-key inputs (e.g. large search params on this route).`,
-        ),
-        "cache-write",
-        "[CFCacheStore] kvSetSegment",
-      );
-      return;
-    }
-
     const expiresAt = staleAt + swrWindow * 1000;
     // Same wire shape as JSON.stringify({ d, s, e }) — dataJson is already
     // valid JSON for CachedEntryData, so embedding it avoids re-walking the tree.
@@ -3324,8 +3301,8 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
 
     this.waitUntil(() =>
       reportingAsync(
-        () =>
-          this.kv!.put(kvKey, envelopeJson, {
+        async () =>
+          this.kv!.put(await this.toKVKey(key), envelopeJson, {
             expirationTtl: totalTtl,
           }),
         "cache-write",
@@ -3386,7 +3363,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     if (!this.kv) return null;
 
     try {
-      const kvKey = this.toKVKey(`fn:${key}`);
+      const kvKey = await this.toKVKey(`fn:${key}`);
       const { value: envelope, timedOut } =
         await this.kvGetOrEvict<KVItemEnvelope>(
           kvKey,
@@ -3508,7 +3485,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     if (!this.kv) return null;
 
     try {
-      const kvKey = this.toDocKVKey(key);
+      const kvKey = await 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

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

@@ -333,7 +333,7 @@ export interface CFCacheStoreOptions<TEnv = unknown> {
    * cannot stall the request; the read then falls through to its normal miss
    * path (L2/KV or render).
    *
-   * Defaults to {@link EDGE_LOOKUP_TIMEOUT_MS} (10). Set to 0 (or any value
+   * Defaults to {@link EDGE_LOOKUP_TIMEOUT_MS} (25). Set to 0 (or any value
    * <= 0) to disable the budget and always await `match`.
    */
   edgeLookupTimeoutMs?: number;

package/src/cache/cf/cf-kv-utils.ts

@@ -26,6 +26,44 @@ export function kvKeyByteLength(key: string): number {
   return kvKeyEncoder.encode(key).length;
 }
 
+/**
+ * Bytes of a composed key preserved verbatim when an over-limit key is
+ * normalized (toKVKey). 400 leaves room for the `~` separator and the 32-hex
+ * digest inside KV_MAX_KEY_BYTES while keeping the version prefix and most of
+ * the logical key readable (and prefix-listable) in the KV dashboard.
+ */
+export const KV_KEY_PRESERVED_PREFIX_BYTES = 400;
+
+/**
+ * Truncate to at most `maxBytes` of UTF-8. A multibyte sequence split at the
+ * boundary decodes to U+FFFD, which is stripped — the result is deterministic
+ * for a given input, which is all key normalization needs.
+ */
+export function truncateToBytes(value: string, maxBytes: number): string {
+  const bytes = kvKeyEncoder.encode(value);
+  if (bytes.length <= maxBytes) return value;
+  return new TextDecoder()
+    .decode(bytes.subarray(0, maxBytes))
+    .replace(/�+$/, "");
+}
+
+/**
+ * 128-bit hex digest (SHA-256 truncated) of a composed KV key. WebCrypto is
+ * available on workerd and Node alike; SHA-256 (not a fast non-crypto hash)
+ * because cache keys embed user-influenced serialized args — an engineered
+ * collision between two normalized keys would serve one entry's payload for
+ * the other's.
+ */
+export async function kvKeyDigest(value: string): Promise<string> {
+  const digest = await crypto.subtle.digest(
+    "SHA-256",
+    kvKeyEncoder.encode(value),
+  );
+  return Array.from(new Uint8Array(digest, 0, 16), (b) =>
+    b.toString(16).padStart(2, "0"),
+  ).join("");
+}
+
 /**
  * Compute the Cache-Control directive for a stale-path REVALIDATING re-put from
  * the entry's stored hard-expiry deadline (CACHE_EXPIRES_AT_HEADER). Returns the