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

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

@@ -40,6 +40,10 @@ import {
   type RequestContext,
 } from "../../server/request-context.js";
 import { VERSION } from "@rangojs/router:version";
+import {
+  isPerClientSignalHeader,
+  stripPerClientSignals,
+} from "../../browser/cookie-name.js";
 import {
   resolveTtl,
   resolveSwrWindow,
@@ -214,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;
 
@@ -319,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";
 
 /**
@@ -713,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
 // ============================================================================
@@ -806,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
@@ -905,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;
   }
 
   /**
@@ -1611,6 +1630,9 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     headers.delete(CACHE_STATUS_HEADER);
     headers.delete(CACHE_TAGS_HEADER);
     headers.delete(CACHE_TAGGED_AT_HEADER);
+    // Finding #3 (read side): strip per-client signals a pre-fix or
+    // pinned-version L1 entry may carry. See the read-side note in the design doc.
+    stripPerClientSignals(headers);
     return new Response(response.body, {
       status: response.status,
       statusText: response.statusText,
@@ -1651,6 +1673,10 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       // replaced with a long max-age so the CF Cache API holds the entry across
       // the SWR window; getResponse restores the original before serving.
       const headers = new Headers(response.headers);
+      // Finding #3: never persist a per-client signal in the shared L1 entry
+      // (the platform's Set-Cookie rejection is unverified and ignores the
+      // directive anyway). See stripPerClientSignals.
+      stripPerClientSignals(headers);
       const originalCacheControl = response.headers.get("Cache-Control");
       if (originalCacheControl !== null) {
         headers.set(CACHE_ORIG_CC_HEADER, originalCacheControl);
@@ -1658,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,
@@ -1688,8 +1711,12 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       // L2: persist to KV (KV requires expirationTtl >= 60s)
       if (this.kv && this.waitUntil && totalTtl >= 60) {
         const kvKey = this.toKVKey(`doc:${key}`);
+        // Finding #3: never persist a per-client signal in the KV envelope.
         const headersArray: [string, string][] = [];
-        response.headers.forEach((v, k) => headersArray.push([k, v]));
+        response.headers.forEach((v, k) => {
+          if (isPerClientSignalHeader(k)) return;
+          headersArray.push([k, v]);
+        });
         // Read body as ArrayBuffer and encode to base64 to preserve binary payloads
         const bodyBuf = kvBody
           ? await new Response(kvBody).arrayBuffer()
@@ -2149,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[];
@@ -2848,6 +2893,12 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       // so evict it and miss rather than re-failing every read until TTL.
       let response: Response;
       try {
+        // Finding #3 (read side): strip per-client signals a stale envelope may
+        // carry. Inside the try so a malformed `hd` evicts (not throws through);
+        // mutates `hd` in place so promoteResponseToL1 re-seeds from it too.
+        envelope.hd = envelope.hd.filter(
+          ([name]) => !isPerClientSignalHeader(name),
+        );
         const bodyBuffer = base64ToBuffer(envelope.b);
         const headers = new Headers(envelope.hd);
         response = new Response(bodyBuffer, {
@@ -2903,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

@@ -12,6 +12,7 @@
  */
 
 import type { MiddlewareFn, MiddlewareContext } from "../router/middleware.js";
+import { hasPerClientSignal } from "../browser/cookie-name.js";
 import {
   getRequestContext,
   type RequestContext,
@@ -21,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 {
@@ -58,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 "";
 
@@ -71,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 {
@@ -121,6 +86,16 @@ function shouldCacheResponse(response: Response): CacheDirectives | null {
     return null;
   }
 
+  // Never cache a per-client signal into a SHARED response store. A Set-Cookie
+  // (e.g. a rango state rotation from invalidateClientCache(), or any cookie a
+  // loader set) would be replayed to every client on a hit — pinning them to
+  // one value and even rolling a rotated client back to a prior one. The
+  // x-rango-keep-cache directive header is the mirror image: a replayed "keep"
+  // would suppress invalidation for every replayed client. Refuse both.
+  if (hasPerClientSignal(response.headers)) {
+    return null;
+  }
+
   const cacheControl = response.headers.get("Cache-Control");
   return parseCacheControl(cacheControl);
 }

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

@@ -14,6 +14,7 @@ import type {
   CacheItemOptions,
 } from "./types.js";
 import type { RequestContext } from "../server/request-context.js";
+import { isPerClientSignalHeader } from "../browser/cookie-name.js";
 import {
   resolveTtl,
   resolveSwrWindow,
@@ -58,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;
@@ -170,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,
@@ -193,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>();
@@ -228,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) {
@@ -288,12 +280,10 @@ 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();
       const headers: [string, string][] = [];
       response.headers.forEach((value, name) => {
+        if (isPerClientSignalHeader(name)) return;
         headers.push([name, value]);
       });
 
@@ -363,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) {
@@ -391,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) {
@@ -420,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;
@@ -440,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,
@@ -451,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];