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

package/src/server/request-context.ts

@@ -13,6 +13,12 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import type { CacheErrorCategory } from "../cache/cache-error.js";
 import type { CookieOptions } from "../router/middleware.js";
+import {
+  KEEP_CACHE_HEADER,
+  getRawCookieValue,
+  mintStateValue,
+  serializeStateCookie,
+} from "../browser/cookie-name.js";
 import type { LoaderDefinition, LoaderContext } from "../types.js";
 import type { ScopedReverseFunction } from "../reverse.js";
 import type {
@@ -103,6 +109,10 @@ export interface RequestContext<
   setStatus(status: number): void;
   /** @internal Set status bypassing cache-exec guard (for framework error handling) */
   _setStatus(status: number): void;
+  /** @internal Rotate the rango state cookie (server seat of invalidateClientCache). */
+  _rotateStateCookie(): void;
+  /** @internal Set the keepClientCache() directive header on the response. */
+  _setKeepCacheDirective(): void;
 
   /**
    * Access loader data or push handle data.
@@ -360,6 +370,15 @@ export interface RequestContext<
    * to avoid a second resolveRoute call. Cleared on HMR invalidation.
    */
   _classifiedRoute?: import("../router/route-snapshot.js").RouteSnapshot;
+
+  /**
+   * @internal Coarse route-level cache signal for the X-Rango-Cache debug
+   * header. Populated by match/matchPartial only when the debug cache signal
+   * gate is enabled (debugCacheSignal option or RANGO_TEST_SIGNALS=1). Read by
+   * the response-finalization path (createResponseWithMergedHeaders). Undefined
+   * when the gate is off, so no header is emitted.
+   */
+  _cacheSignal?: import("../router/telemetry.js").CacheSegmentSignal[];
 }
 
 /**
@@ -401,8 +420,11 @@ export type PublicRequestContext<
   | "_metricsStore"
   | "_basename"
   | "_setStatus"
+  | "_rotateStateCookie"
+  | "_setKeepCacheDirective"
   | "_variables"
   | "_classifiedRoute"
+  | "_cacheSignal"
   | "res"
 >;
 
@@ -540,6 +562,10 @@ export interface CreateRequestContextOptions<TEnv> {
   executionContext?: ExecutionContext;
   /** Optional theme configuration (enables ctx.theme and ctx.setTheme) */
   themeConfig?: ResolvedThemeConfig | null;
+  /** Resolved rango state cookie name, for the server seat of invalidateClientCache(). */
+  stateCookieName?: string;
+  /** Build version, used as the prefix of a server-rotated rango state value. */
+  version?: string;
 }
 
 /**
@@ -564,12 +590,13 @@ export function createRequestContext<TEnv>(
     cacheProfiles,
     executionContext,
     themeConfig,
+    stateCookieName,
+    version: stateVersion,
   } = options;
   const cookieHeader = request.headers.get("Cookie");
+  let rangoStateRotated = false;
   let parsedCookies: Record<string, string> | null = null;
 
-  // Create stub response for collecting headers/cookies.
-  // All cookie/header mutations go here; cookie reads derive from it.
   let stubResponse = initialResponse
     ? new Response(null, {
         status: initialResponse.status,
@@ -578,11 +605,9 @@ export function createRequestContext<TEnv>(
       })
     : new Response(null, { status: 200 });
 
-  // Create handle store and loader memoization for this request
   const handleStore = createHandleStore();
   const loaderPromises = new Map<string, Promise<any>>();
 
-  // Lazy parse cookies from the original Cookie header
   const getParsedCookies = (): Record<string, string> => {
     if (!parsedCookies) {
       parsedCookies = parseCookiesFromHeader(cookieHeader);
@@ -590,7 +615,6 @@ export function createRequestContext<TEnv>(
     return parsedCookies;
   };
 
-  // Cached response cookie mutations — invalidated on setCookie/deleteCookie/setTheme
   let responseCookieCache: Map<string, string | null> | null = null;
   const getResponseCookies = (): Map<string, string | null> => {
     if (!responseCookieCache) {
@@ -602,8 +626,6 @@ export function createRequestContext<TEnv>(
     responseCookieCache = null;
   };
 
-  // Guard: throw if a response-level side effect is called inside a cache() scope.
-  // Uses ALS to detect the scope (set during segment resolution).
   function assertNotInsideCacheScopeALS(methodName: string): void {
     if (isInsideCacheScope()) {
       throw new Error(
@@ -614,8 +636,7 @@ export function createRequestContext<TEnv>(
     }
   }
 
-  // Effective cookie read: response stub Set-Cookie wins, then original header.
-  // The stub IS the source of truth for same-request mutations.
+  // Response stub Set-Cookie wins, then original header (source of truth for mutations).
   const effectiveCookie = (name: string): string | undefined => {
     const mutations = getResponseCookies();
     if (mutations.has(name)) {
@@ -625,14 +646,11 @@ export function createRequestContext<TEnv>(
     return getParsedCookies()[name];
   };
 
-  // Theme helpers (only used when themeConfig is provided)
   const getTheme = (): Theme | undefined => {
     if (!themeConfig) return undefined;
 
-    // Use overlay-aware read so setTheme() in the same request is reflected
     const stored = effectiveCookie(themeConfig.storageKey);
     if (stored) {
-      // Validate stored value
       if (stored === "system" && themeConfig.enableSystem) {
         return "system";
       }
@@ -646,7 +664,6 @@ export function createRequestContext<TEnv>(
   const setTheme = (theme: Theme): void => {
     if (!themeConfig) return;
 
-    // Validate theme value
     if (theme !== "system" && !themeConfig.themes.includes(theme)) {
       console.warn(
         `[Theme] Invalid theme value: "${theme}". Valid values: system, ${themeConfig.themes.join(", ")}`,
@@ -654,7 +671,6 @@ export function createRequestContext<TEnv>(
       return;
     }
 
-    // Write to stub — effectiveCookie() will pick it up on next read
     stubResponse.headers.append(
       "Set-Cookie",
       serializeCookieValue(themeConfig.storageKey, theme, {
@@ -666,10 +682,8 @@ export function createRequestContext<TEnv>(
     invalidateResponseCookieCache();
   };
 
-  // Strip internal _rsc* params so userland sees a clean URL.
   const cleanUrl = stripInternalParams(url);
 
-  // Build the context object first (without use), then add use
   const ctx: RequestContext<TEnv> = {
     env,
     request,
@@ -755,6 +769,45 @@ export function createRequestContext<TEnv>(
       stubResponse.headers.set(name, value);
     },
 
+    // Rotate the rango state cookie for the responding client (the server seat
+    // of invalidateClientCache). Writes ONE Set-Cookie per request with the
+    // value {version}:{timestamp}; the `:` stays raw (the cookie-name.ts
+    // serializer), not the URL-encoded form serializeCookieValue would produce.
+    // The timestamp is strictly greater than the client's current one (inbound
+    // X-Rango-State), so a same-millisecond server rotation still differs from
+    // the client value and the divergence observer fires.
+    _rotateStateCookie(): void {
+      if (rangoStateRotated) return;
+      rangoStateRotated = true;
+      if (!stateCookieName) return;
+      // The client's current value, for the monotonic guard: prefer the
+      // X-Rango-State header (router navigation/prefetch fetches send it), but
+      // fall back to the request's rango state cookie — action POSTs / plain
+      // app fetch()s carry no router header yet DO send the cookie. Without the
+      // fallback, prevTs stays 0 and a same-ms mint can equal the client value,
+      // leaving the divergence observer silent. `|| null` so an empty header
+      // ('' from proxy normalization) falls through instead of short-circuiting.
+      // getRawCookieValue reads the cookie undecoded (the wire value
+      // decodeStateValue decodes exactly once) AND is the same parser the client
+      // mirror uses, so both seats read the same jar entry.
+      const prevRaw =
+        (request.headers.get("x-rango-state") || null) ??
+        getRawCookieValue(cookieHeader, stateCookieName);
+      const value = mintStateValue(stateVersion ?? "0", prevRaw);
+      stubResponse.headers.append(
+        "Set-Cookie",
+        serializeStateCookie(stateCookieName, value, url.protocol === "https:"),
+      );
+      invalidateResponseCookieCache();
+    },
+
+    // Set the keepClientCache() directive header. The action bridge reads it on
+    // the response and suppresses its automatic invalidation. `.set` makes this
+    // idempotent (one header regardless of call count).
+    _setKeepCacheDirective(): void {
+      stubResponse.headers.set(KEEP_CACHE_HEADER, "1");
+    },
+
     setStatus(status: number): void {
       assertNotInsideCacheExec(ctx, "setStatus");
       assertNotInsideCacheScopeALS("setStatus");
@@ -771,7 +824,6 @@ export function createRequestContext<TEnv>(
       });
     },
 
-    // Placeholder - will be replaced below
     use: null as any,
 
     method: request.method,
@@ -800,7 +852,6 @@ export function createRequestContext<TEnv>(
       this._onResponseCallbacks.push(callback);
     },
 
-    // Theme properties (only set when themeConfig is provided)
     get theme() {
       return themeConfig ? getTheme() : undefined;
     },
@@ -824,19 +875,17 @@ export function createRequestContext<TEnv>(
     _reportedErrors: new WeakSet<object>(),
     _metricsStore: undefined,
 
-    // Render barrier: deferred promise resolved after non-loader segments settle.
-    _renderBarrier: null as any, // set below
-    _resolveRenderBarrier: null as any, // set below
+    _renderBarrier: null as any,
+    _resolveRenderBarrier: null as any,
     _renderBarrierSegmentOrder: undefined,
 
     reverse: createReverseFunction(getGlobalRouteMap(), undefined, {}),
   };
 
-  // Lazy render barrier: only allocate the Promise when a loader actually
-  // calls rendered(). Requests that don't use rendered() pay zero cost.
+  // Lazy allocation: only create Promise when a loader calls rendered().
   let barrierResolved = false;
   let resolveBarrier: (() => void) | undefined;
-  ctx._renderBarrier = null as any; // lazy — created on first access
+  ctx._renderBarrier = null as any;
   ctx._resolveRenderBarrier = (
     segments: Array<{ type: string; id: string }>,
   ) => {
@@ -847,9 +896,6 @@ export function createRequestContext<TEnv>(
       .map((s) => s.id);
     ctx._renderBarrierSegmentOrder = segOrder;
 
-    // Closing the guard window means no handler can still form a deadlock cycle
-    // with a rendered() loader: drop the dependency-tracking state and mark it
-    // closed. WHEN this runs is the only streaming/non-streaming difference.
     const closeGuard = () => {
       ctx._renderBarrierWaiters = undefined;
       ctx._handlerLoaderDeps = undefined;
@@ -857,20 +903,8 @@ export function createRequestContext<TEnv>(
     };
 
     if (ctx._treeHasStreaming) {
-      // Streaming: rendered() keeps waiting on handleStore.settled past this
-      // point, and loading() handlers are still in flight. The eager snapshot
-      // here would be incomplete, so leave it unset — rendered() builds and
-      // caches the complete one after settled. Keep the guard window OPEN so a
-      // handler that resumes and awaits a still-waiting rendered() loader is
-      // still caught; close it once settled (every tracked handler has finished
-      // then, so none can await a loader anymore). settled resolves after
-      // rendered() seals; if no loader used rendered(), nothing seals and the
-      // (empty) guard state is simply GC'd at request end.
       handleStore.settled.then(closeGuard);
     } else {
-      // Non-streaming: all handlers have settled by now. Build and cache the
-      // snapshot so loader ctx.use(handle) calls don't rebuild it, and close the
-      // guard window immediately.
       ctx._renderBarrierHandleSnapshot = buildHandleSnapshot(
         handleStore,
         segOrder,
@@ -881,9 +915,6 @@ export function createRequestContext<TEnv>(
   };
   Object.defineProperty(ctx, "_renderBarrier", {
     get() {
-      // Barrier already resolved (cache/prerender hit) or first lazy access.
-      // Either way, replace the getter with a concrete value to avoid
-      // repeated Promise.resolve() allocations on subsequent reads.
       const p = barrierResolved
         ? Promise.resolve()
         : new Promise<void>((resolve) => {
@@ -899,24 +930,16 @@ export function createRequestContext<TEnv>(
     configurable: true,
   });
 
-  // Now create use() with access to ctx
   ctx.use = createUseFunction({
     handleStore,
     loaderPromises,
     getContext: () => ctx,
   });
 
-  // Brand with taint symbol so "use cache" excludes ctx from cache keys
   (ctx as any)[NOCACHE_SYMBOL] = true;
   return ctx;
 }
 
-/**
- * Parse Set-Cookie headers from a response into effective cookie state.
- * Returns a map of cookie name -> value (string) or name -> null (deleted).
- * Last-write-wins: later Set-Cookie entries for the same name overwrite earlier ones.
- * Max-Age=0 is treated as a delete.
- */
 const MAX_AGE_ZERO_RE = /;\s*Max-Age\s*=\s*0/i;
 
 function parseResponseCookies(response: Response): Map<string, string | null> {
@@ -924,7 +947,6 @@ function parseResponseCookies(response: Response): Map<string, string | null> {
   const setCookies = response.headers.getSetCookie();
 
   for (const header of setCookies) {
-    // First segment before ';' is the name=value pair
     const semiIdx = header.indexOf(";");
     const pair = semiIdx === -1 ? header : header.substring(0, semiIdx);
     const eqIdx = pair.indexOf("=");
@@ -936,11 +958,9 @@ function parseResponseCookies(response: Response): Map<string, string | null> {
       name = decodeURIComponent(pair.substring(0, eqIdx).trim());
       value = decodeURIComponent(pair.substring(eqIdx + 1).trim());
     } catch {
-      // Malformed encoding — skip this entry
       continue;
     }
 
-    // Max-Age=0 means the cookie is being deleted
     const isDeleted = MAX_AGE_ZERO_RE.test(header);
     result.set(name, isDeleted ? null : value);
   }
@@ -948,9 +968,6 @@ function parseResponseCookies(response: Response): Map<string, string | null> {
   return result;
 }
 
-/**
- * Parse cookies from Cookie header
- */
 function parseCookiesFromHeader(
   cookieHeader: string | null,
 ): Record<string, string> {
@@ -966,7 +983,7 @@ function parseCookiesFromHeader(
       try {
         cookies[name] = decodeURIComponent(raw);
       } catch {
-        // Malformed percent-encoded value (e.g. %zz, %2) - fall back to raw value
+        // Malformed percent-encoding: fall back to raw value
         cookies[name] = raw;
       }
     }
@@ -975,9 +992,6 @@ function parseCookiesFromHeader(
   return cookies;
 }
 
-/**
- * Serialize a cookie for Set-Cookie header
- */
 function serializeCookieValue(
   name: string,
   value: string,
@@ -1005,20 +1019,12 @@ export interface CreateUseFunctionOptions<TEnv> {
   getContext: () => RequestContext<TEnv>;
 }
 
-/**
- * Create the use() function for loader and handle composition.
- *
- * This is the unified implementation used by both RequestContext and HandlerContext.
- * - For loaders: executes and memoizes loader functions
- * - For handles: returns a push function to add handle data
- */
 export function createUseFunction<TEnv>(
   options: CreateUseFunctionOptions<TEnv>,
 ): RequestContext["use"] {
   const { handleStore, loaderPromises, getContext } = options;
 
   return ((item: LoaderDefinition<any, any> | Handle<any, any>) => {
-    // Handle case: return a push function
     if (isHandle(item)) {
       const handle = item;
       const ctx = getContext();
@@ -1031,30 +1037,24 @@ export function createUseFunction<TEnv>(
         );
       }
 
-      // Return a push function bound to this handle and segment
       return (
         dataOrFn: unknown | Promise<unknown> | (() => Promise<unknown>),
       ) => {
-        // If it's a function, call it immediately to get the promise
         const valueOrPromise =
           typeof dataOrFn === "function"
             ? (dataOrFn as () => Promise<unknown>)()
             : dataOrFn;
 
-        // Push directly - promises will be serialized by RSC and streamed
         handleStore.push(handle.$$id, segmentId, valueOrPromise);
       };
     }
 
-    // Loader case
     const loader = item as LoaderDefinition<any, any>;
 
-    // Return cached promise if already started
     if (loaderPromises.has(loader.$$id)) {
       return loaderPromises.get(loader.$$id);
     }
 
-    // Get loader function - either from loader object or fetchable registry
     let loaderFn = loader.fn;
     if (!loaderFn) {
       const fetchable = getFetchableLoader(loader.$$id);
@@ -1071,7 +1071,6 @@ export function createUseFunction<TEnv>(
 
     const ctx = getContext();
 
-    // Create loader context with recursive use() support
     const loaderCtx: LoaderContext<Record<string, string | undefined>, TEnv> = {
       params: ctx.params,
       routeParams: (ctx.params ?? {}) as Record<string, string>,
@@ -1088,7 +1087,6 @@ export function createUseFunction<TEnv>(
       use: (<TDep, TDepParams = any>(
         dep: LoaderDefinition<TDep, TDepParams>,
       ): Promise<TDep> => {
-        // Recursive call - will start dep loader if not already started
         return ctx.use(dep);
       }) as LoaderContext["use"],
       method: "GET",
@@ -1112,7 +1110,6 @@ export function createUseFunction<TEnv>(
       doneLoader();
     });
 
-    // Memoize for subsequent calls
     loaderPromises.set(loader.$$id, promise);
 
     return promise;

package/src/ssr/index.tsx

@@ -71,7 +71,7 @@ export interface SSRRenderOptions {
  */
 export interface SSRDependencies<TEnv = unknown> {
   /**
-   * createFromReadableStream from @vitejs/plugin-rsc/ssr
+   * createFromReadableStream from @rangojs/router/internal/deps/ssr
    */
   createFromReadableStream: <T>(
     stream: ReadableStream<Uint8Array>,
@@ -86,7 +86,7 @@ export interface SSRDependencies<TEnv = unknown> {
   ) => Promise<ReactDOMReadableStream>;
 
   /**
-   * injectRSCPayload from rsc-html-stream/server
+   * injectRSCPayload from @rangojs/router/internal/deps/html-stream-server
    */
   injectRSCPayload: (
     rscStream: ReadableStream<Uint8Array>,
@@ -218,10 +218,10 @@ function createSsrEventController(opts: {
  *
  * @example
  * ```tsx
- * import { createSSRHandler } from "rsc-router/ssr";
- * import { createFromReadableStream } from "@vitejs/plugin-rsc/ssr";
+ * import { createSSRHandler } from "@rangojs/router/ssr";
+ * import { createFromReadableStream } from "@rangojs/router/internal/deps/ssr";
  * import { renderToReadableStream } from "react-dom/server.edge";
- * import { injectRSCPayload } from "rsc-html-stream/server";
+ * import { injectRSCPayload } from "@rangojs/router/internal/deps/html-stream-server";
  *
  * export const renderHTML = createSSRHandler({
  *   createFromReadableStream,
@@ -263,6 +263,7 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
       let payload: Promise<RscPayload> | undefined;
       let handlesPromise: Promise<HandleData> | undefined;
       let ssrContextValue: NavigationStoreContextValue | undefined;
+      let rootPromise: Promise<React.ReactNode> | undefined;
       function SsrRoot() {
         payload ??= createFromReadableStream<RscPayload>(rscStream1);
         const resolved = React.use(payload);
@@ -296,17 +297,16 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
         };
 
         // Build content tree from segments.
-        // Order must match NavigationProvider: NavigationStoreContext > ThemeProvider > content
-        const reconstructedRoot = renderSegments(
-          resolved.metadata?.segments ?? [],
-          {
+        // Order must match NavigationProvider: NavigationStoreContext > NonceContext > ThemeProvider > content
+        // Memoize like payload/handles above: renderSegments is async, so
+        // React.use() on a fresh promise suspends and replays SsrRoot, which
+        // would re-run the entire segment-tree build on every initial render.
+        rootPromise ??= Promise.resolve(
+          renderSegments(resolved.metadata?.segments ?? [], {
             rootLayout: resolved.metadata?.rootLayout,
-          },
+          }),
         );
-        let content: React.ReactNode =
-          reconstructedRoot instanceof Promise
-            ? React.use(reconstructedRoot)
-            : reconstructedRoot;
+        let content: React.ReactNode = React.use(rootPromise);
 
         // Wrap content with ThemeProvider if theme is enabled
         if (themeConfig) {

package/src/static-handler.ts

@@ -35,8 +35,7 @@ import type { Handler } from "./types.js";
 import type { StaticBuildContext } from "./prerender.js";
 import type { UseItems, HandlerUseItem } from "./route-types.js";
 import { isCachedFunction } from "./cache/taint.js";
-
-// -- Types ------------------------------------------------------------------
+import { isUnderTestRunner } from "./runtime-env.js";
 
 export interface StaticHandlerOptions {
   /**
@@ -61,7 +60,9 @@ export interface StaticHandlerDefinition<
   use?: () => UseItems<HandlerUseItem>;
 }
 
-// -- Function ---------------------------------------------------------------
+// Process-stable fallback id counter (mirrors createHandle/createLoader/Prerender).
+// Only assigned in bare unit tests where the Vite plugin did not inject an id.
+let runtimeStaticIdCounter = 0;
 
 export function Static<TParams extends Record<string, any> = {}>(
   handler: (ctx: StaticBuildContext) => ReactNode | Promise<ReactNode>,
@@ -69,8 +70,6 @@ export function Static<TParams extends Record<string, any> = {}>(
   __injectedId?: string,
 ): StaticHandlerDefinition<TParams>;
 
-// -- Implementation ---------------------------------------------------------
-
 export function Static<TParams extends Record<string, any>>(
   handler: Function,
   optionsOrId?: StaticHandlerOptions | string,
@@ -94,12 +93,15 @@ export function Static<TParams extends Record<string, any>>(
     id = maybeId ?? "";
   }
 
-  if (!id) {
+  if (!id && !isUnderTestRunner()) {
     throw new Error(
-      "[rango] Static: missing $$id. " +
-        "Ensure the exposeInternalIds Vite plugin is configured.",
+      "[rango] Static: missing $$id. Use `export const X = Static(...)` and " +
+        "ensure the exposeInternalIds Vite plugin is configured.",
     );
   }
+  if (!id) {
+    id = `__rango_runtime_static_${runtimeStaticIdCounter++}`;
+  }
 
   return {
     __brand: "staticHandler" as const,
@@ -109,11 +111,6 @@ export function Static<TParams extends Record<string, any>>(
   };
 }
 
-// -- Type guard -------------------------------------------------------------
-
-/**
- * Type guard to check if a value is a StaticHandlerDefinition.
- */
 export function isStaticHandler(
   value: unknown,
 ): value is StaticHandlerDefinition {

package/src/testing/cache-status.ts

@@ -0,0 +1,119 @@
+/**
+ * Cache-status testing primitives for @rangojs/router consumers.
+ *
+ * Two complementary paths, both DEVELOPMENT/TEST ONLY:
+ *
+ * 1. Header path — `parseCacheHeader` / `assertCacheStatus` read the
+ *    `X-Rango-Cache` response header. The header is emitted only when the
+ *    router's debug cache signal gate is on (the `debugCacheSignal` option or
+ *    `RANGO_TEST_SIGNALS=1`). With the gate off there is no header and these
+ *    helpers throw a clear "header missing" error.
+ *
+ * 2. Telemetry path — `createCacheSink` returns a `{ sink, events }` pair the
+ *    consumer wires via `createRouter({ telemetry: sink })`. This has ZERO
+ *    production surface: no header, just structured `cache.decision` events
+ *    (which carry the same coarse `segments` cache signal).
+ *
+ * v1 cache status is COARSE (route-level): the router reports a single entry
+ * keyed by the route key (the route NAME), not per individual segment.
+ *
+ * Import path: from a Vitest unit/integration test use `@rangojs/router/testing`;
+ * from a Playwright e2e use `@rangojs/router/testing/e2e` (the barrel pulls a
+ * build-only virtual that does not resolve in a plain Playwright runner).
+ */
+
+import type {
+  CacheDecisionEvent,
+  CacheSegmentStatus,
+  TelemetryEvent,
+  TelemetrySink,
+} from "../router/telemetry.js";
+
+const CACHE_HEADER = "X-Rango-Cache";
+
+/** Expected cache status passed to assertCacheStatus. */
+export type ExpectedCacheStatus = CacheSegmentStatus;
+
+/** A target carrying response headers (a Response or a `{ headers }` object). */
+export type CacheStatusTarget = Response | { headers: Headers };
+
+export function parseCacheHeader(
+  headerValue: string | null | undefined,
+): Record<string, string> {
+  const result: Record<string, string> = {};
+  if (!headerValue) return result;
+  for (const rawEntry of headerValue.split(",")) {
+    const entry = rawEntry.trim();
+    if (entry.length === 0) continue;
+    const eq = entry.indexOf("=");
+    if (eq === -1) continue;
+    const id = entry.slice(0, eq).trim();
+    const status = entry.slice(eq + 1).trim();
+    if (id.length === 0 || status.length === 0) continue;
+    result[id] = status;
+  }
+  return result;
+}
+
+function getHeaders(target: CacheStatusTarget): Headers {
+  return target.headers;
+}
+
+export function assertCacheStatus(
+  target: CacheStatusTarget,
+  segment: string,
+  expected: ExpectedCacheStatus,
+): void {
+  const headerValue = getHeaders(target).get(CACHE_HEADER);
+  if (headerValue === null) {
+    throw new Error(
+      `assertCacheStatus: response has no ${CACHE_HEADER} header. ` +
+        `Enable the debug cache signal via createRouter({ debugCacheSignal: true }) ` +
+        `or RANGO_TEST_SIGNALS=1.`,
+    );
+  }
+  const map = parseCacheHeader(headerValue);
+  const actual = map[segment];
+  if (actual === undefined) {
+    const known = Object.keys(map);
+    throw new Error(
+      `assertCacheStatus: segment "${segment}" not found in ${CACHE_HEADER} ` +
+        `("${headerValue}"). Known segments: ${
+          known.length > 0 ? known.join(", ") : "(none)"
+        }.`,
+    );
+  }
+  if (actual !== expected) {
+    throw new Error(
+      `assertCacheStatus: segment "${segment}" expected "${expected}" but got "${actual}".`,
+    );
+  }
+}
+
+/**
+ * A telemetry sink paired with the array it records events into.
+ */
+export interface CacheSink {
+  /** Wire into `createRouter({ telemetry: sink })`. */
+  sink: TelemetrySink;
+  /** All telemetry events captured so far, in emit order. */
+  events: TelemetryEvent[];
+}
+
+export function createCacheSink(): CacheSink {
+  const events: TelemetryEvent[] = [];
+  const sink: TelemetrySink = {
+    emit(event: TelemetryEvent): void {
+      events.push(event);
+    },
+  };
+  return { sink, events };
+}
+
+export function filterCacheDecisions(
+  events: readonly TelemetryEvent[],
+): CacheDecisionEvent[] {
+  return events.filter(
+    (e): e is CacheDecisionEvent => e.type === "cache.decision",
+  );
+}