@rangojs/router 0.0.0-experimental.debug-cache-fix → 0.0.0-experimental.df410dd5

package/src/server/request-context.ts

@@ -20,16 +20,29 @@ import type {
   DefaultRouteName,
 } from "../types/global-namespace.js";
 import type { Handle } from "../handle.js";
-import { type ContextVar, contextGet, contextSet } from "../context-var.js";
-import { createHandleStore, type HandleStore } from "./handle-store.js";
+import {
+  type ContextVar,
+  contextGet,
+  contextSet,
+  isNonCacheable,
+} from "../context-var.js";
+import {
+  createHandleStore,
+  buildHandleSnapshot,
+  type HandleStore,
+  type HandleData,
+} from "./handle-store.js";
 import { isHandle } from "../handle.js";
 import { track, type MetricsStore } from "./context.js";
 import { getFetchableLoader } from "./fetchable-loader-store.js";
 import type { SegmentCacheStore } from "../cache/types.js";
 import type { Theme, ResolvedThemeConfig } from "../theme/types.js";
+import type { ExecutionContext, RequestScope } from "../types/request-scope.js";
+import { fireAndForgetWaitUntil } from "../types/request-scope.js";
 import { THEME_COOKIE } from "../theme/constants.js";
 import type { LocationStateEntry } from "../browser/react/location-state-shared.js";
 import { NOCACHE_SYMBOL, assertNotInsideCacheExec } from "../cache/taint.js";
+import { isInsideCacheScope } from "./context.js";
 import {
   createReverseFunction,
   stripInternalParams,
@@ -47,24 +60,9 @@ import { isAutoGeneratedRouteName } from "../route-name.js";
 export interface RequestContext<
   TEnv = DefaultEnv,
   TParams = Record<string, string>,
-> {
-  /** Platform bindings (Cloudflare env, etc.) */
-  env: TEnv;
-  /** Original HTTP request */
-  request: Request;
-  /** Parsed URL (with internal `_rsc*` params stripped) */
-  url: URL;
-  /**
-   * The original request URL with all parameters intact, including
-   * internal `_rsc*` transport params.
-   */
-  originalUrl: URL;
-  /** URL pathname */
-  pathname: string;
-  /** URL search params (with internal `_rsc*` params stripped, same as `url.searchParams`) */
-  searchParams: URLSearchParams;
-  /** Variables set by middleware (same as ctx.var) */
-  var: Record<string, any>;
+> extends RequestScope<TEnv> {
+  /** @internal Shared variable backing store for ctx.get()/ctx.set(). */
+  _variables: Record<string, any>;
   /** Get a variable set by middleware */
   get: {
     <T>(contextVar: ContextVar<T>): T | undefined;
@@ -72,8 +70,12 @@ export interface RequestContext<
   };
   /** Set a variable (shared with middleware and handlers) */
   set: {
-    <T>(contextVar: ContextVar<T>, value: T): void;
-    <K extends string>(key: K, value: any): void;
+    <T>(
+      contextVar: ContextVar<T>,
+      value: T,
+      options?: { cache?: boolean },
+    ): void;
+    <K extends string>(key: K, value: any, options?: { cache?: boolean }): void;
   };
   /**
    * Route params (populated after route matching)
@@ -144,20 +146,6 @@ export interface RequestContext<
     import("../cache/profile-registry.js").CacheProfile
   >;
 
-  /**
-   * Schedule work to run after the response is sent.
-   * On Cloudflare Workers, uses ctx.waitUntil().
-   * On Node.js, runs as fire-and-forget.
-   *
-   * @example
-   * ```typescript
-   * ctx.waitUntil(async () => {
-   *   await cacheStore.set(key, data, ttl);
-   * });
-   * ```
-   */
-  waitUntil(fn: () => Promise<void>): void;
-
   /**
    * Register a callback to run when the response is created.
    * Callbacks are sync and receive the response. They can:
@@ -261,6 +249,54 @@ export interface RequestContext<
   /** @internal Previous route key (from the navigation source), used for revalidation */
   _prevRouteKey?: string;
 
+  /**
+   * @internal Render barrier for experimental `rendered()` API.
+   * Resolves when all non-loader segments have settled and handle data
+   * is available. Used by DSL loaders that call `ctx.rendered()`.
+   */
+  _renderBarrier: Promise<void>;
+
+  /**
+   * @internal Resolve the render barrier. Accepts resolved segments, filters
+   * out loaders, and captures non-loader segment IDs as the handle ordering.
+   * Called after segment resolution (fresh) or handle replay (cache/prerender).
+   */
+  _resolveRenderBarrier: (
+    segments: Array<{ type: string; id: string }>,
+  ) => void;
+
+  /**
+   * @internal Segment order at barrier resolution time, used by loader
+   * ctx.use(handle) to collect handle data in correct order.
+   */
+  _renderBarrierSegmentOrder?: string[];
+
+  /**
+   * @internal Set to true when the matched entry tree contains any `loading()`
+   * entries (streaming). Used by rendered() to fail fast.
+   */
+  _treeHasStreaming?: boolean;
+
+  /**
+   * @internal Loader IDs that have called rendered() and are waiting for the
+   * barrier. Used to detect deadlocks when a handler tries to await the same
+   * loader via ctx.use(Loader).
+   */
+  _renderBarrierWaiters?: Set<string>;
+
+  /**
+   * @internal Loader IDs that handlers have started awaiting via ctx.use().
+   * Used for bidirectional deadlock detection: if a loader later calls
+   * rendered() and a handler already awaits it, we can detect the deadlock.
+   */
+  _handlerLoaderDeps?: Set<string>;
+
+  /**
+   * @internal Cached HandleData snapshot built at barrier resolution time.
+   * Avoids rebuilding the snapshot on every loader ctx.use(handle) call.
+   */
+  _renderBarrierHandleSnapshot?: HandleData;
+
   /** @internal Per-request error dedup set for onError reporting */
   _reportedErrors: WeakSet<object>;
 
@@ -277,6 +313,24 @@ export interface RequestContext<
 
   /** @internal Request-scoped performance metrics store */
   _metricsStore?: MetricsStore;
+
+  /** @internal Router basename for this request (used by redirect()) */
+  _basename?: string;
+
+  /**
+   * @internal RouteSnapshot from classifyRequest, reused by match/matchPartial
+   * 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[];
 }
 
 /**
@@ -303,10 +357,21 @@ export type PublicRequestContext<
   | "_routeName"
   | "_prevRouteKey"
   | "_reportedErrors"
+  | "_renderBarrier"
+  | "_resolveRenderBarrier"
+  | "_renderBarrierSegmentOrder"
+  | "_treeHasStreaming"
+  | "_renderBarrierWaiters"
+  | "_handlerLoaderDeps"
+  | "_renderBarrierHandleSnapshot"
   | "_reportBackgroundError"
   | "_debugPerformance"
   | "_metricsStore"
+  | "_basename"
   | "_setStatus"
+  | "_variables"
+  | "_classifiedRoute"
+  | "_cacheSignal"
   | "res"
 >;
 
@@ -416,13 +481,7 @@ export function requireRequestContext<
   return getRequestContext<TEnv>();
 }
 
-/**
- * Cloudflare Workers ExecutionContext (subset we need)
- */
-export interface ExecutionContext {
-  waitUntil(promise: Promise<any>): void;
-  passThroughOnException(): void;
-}
+export type { ExecutionContext };
 
 /**
  * Options for creating a request context
@@ -506,6 +565,18 @@ 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(
+        `ctx.${methodName}() cannot be called inside a cache() boundary. ` +
+          `On cache hit the handler is skipped, so this side effect would be lost. ` +
+          `Move ctx.${methodName}() to a middleware or layout outside the cache() scope.`,
+      );
+    }
+  }
+
   // Effective cookie read: response stub Set-Cookie wins, then original header.
   // The stub IS the source of truth for same-request mutations.
   const effectiveCookie = (name: string): string | undefined => {
@@ -569,12 +640,20 @@ export function createRequestContext<TEnv>(
     originalUrl: new URL(request.url),
     pathname: url.pathname,
     searchParams: cleanUrl.searchParams,
-    var: variables,
-    get: ((keyOrVar: any) =>
-      contextGet(variables, keyOrVar)) as RequestContext<TEnv>["get"],
-    set: ((keyOrVar: any, value: any) => {
+    _variables: variables,
+    get: ((keyOrVar: any) => {
+      if (isNonCacheable(variables, keyOrVar) && isInsideCacheScope()) {
+        throw new Error(
+          `ctx.get() for a non-cacheable variable cannot be called inside a cache() boundary. ` +
+            `The variable was created with { cache: false } or set with { cache: false }, ` +
+            `and its value would be stale on cache hit. Move the read outside the cached scope.`,
+        );
+      }
+      return contextGet(variables, keyOrVar);
+    }) as RequestContext<TEnv>["get"],
+    set: ((keyOrVar: any, value: any, options?: any) => {
       assertNotInsideCacheExec(ctx, "set");
-      contextSet(variables, keyOrVar, value);
+      contextSet(variables, keyOrVar, value, options);
     }) as RequestContext<TEnv>["set"],
     params: {} as Record<string, string>,
 
@@ -612,6 +691,7 @@ export function createRequestContext<TEnv>(
 
     setCookie(name: string, value: string, options?: CookieOptions): void {
       assertNotInsideCacheExec(ctx, "setCookie");
+      assertNotInsideCacheScopeALS("setCookie");
       stubResponse.headers.append(
         "Set-Cookie",
         serializeCookieValue(name, value, options),
@@ -624,6 +704,7 @@ export function createRequestContext<TEnv>(
       options?: Pick<CookieOptions, "domain" | "path">,
     ): void {
       assertNotInsideCacheExec(ctx, "deleteCookie");
+      assertNotInsideCacheScopeALS("deleteCookie");
       stubResponse.headers.append(
         "Set-Cookie",
         serializeCookieValue(name, "", { ...options, maxAge: 0 }),
@@ -633,11 +714,13 @@ export function createRequestContext<TEnv>(
 
     header(name: string, value: string): void {
       assertNotInsideCacheExec(ctx, "header");
+      assertNotInsideCacheScopeALS("header");
       stubResponse.headers.set(name, value);
     },
 
     setStatus(status: number): void {
       assertNotInsideCacheExec(ctx, "setStatus");
+      assertNotInsideCacheScopeALS("setStatus");
       stubResponse = new Response(null, {
         status,
         headers: stubResponse.headers,
@@ -662,20 +745,19 @@ export function createRequestContext<TEnv>(
 
     waitUntil(fn: () => Promise<void>): void {
       if (executionContext?.waitUntil) {
-        // Cloudflare Workers: use native waitUntil
         executionContext.waitUntil(fn());
       } else {
-        // Node.js / dev: fire-and-forget with error logging
-        fn().catch((err) =>
-          console.error("[waitUntil] Background task failed:", err),
-        );
+        fireAndForgetWaitUntil(fn);
       }
     },
 
+    executionContext,
+
     _onResponseCallbacks: [],
 
     onResponse(callback: (response: Response) => Response): void {
       assertNotInsideCacheExec(ctx, "onResponse");
+      assertNotInsideCacheScopeALS("onResponse");
       this._onResponseCallbacks.push(callback);
     },
 
@@ -703,9 +785,58 @@ 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
+    _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.
+  let barrierResolved = false;
+  let resolveBarrier: (() => void) | undefined;
+  ctx._renderBarrier = null as any; // lazy — created on first access
+  ctx._resolveRenderBarrier = (
+    segments: Array<{ type: string; id: string }>,
+  ) => {
+    if (barrierResolved) return;
+    barrierResolved = true;
+    const segOrder = segments
+      .filter((s) => s.type !== "loader")
+      .map((s) => s.id);
+    ctx._renderBarrierSegmentOrder = segOrder;
+    // Build and cache handle snapshot so loader ctx.use(handle) calls
+    // don't rebuild it on every invocation.
+    ctx._renderBarrierHandleSnapshot = buildHandleSnapshot(
+      handleStore,
+      segOrder,
+    );
+    ctx._renderBarrierWaiters = undefined;
+    ctx._handlerLoaderDeps = undefined;
+    if (resolveBarrier) resolveBarrier();
+  };
+  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) => {
+            resolveBarrier = resolve;
+          });
+      Object.defineProperty(ctx, "_renderBarrier", {
+        value: p,
+        writable: false,
+        configurable: false,
+      });
+      return p;
+    },
+    configurable: true,
+  });
+
   // Now create use() with access to ctx
   ctx.use = createUseFunction({
     handleStore,
@@ -887,15 +1018,17 @@ export function createUseFunction<TEnv>(
       search: (ctx as any).search ?? {},
       pathname: ctx.pathname,
       url: ctx.url,
+      originalUrl: ctx.originalUrl,
       env: ctx.env as any,
-      var: ctx.var as any,
+      waitUntil: ctx.waitUntil.bind(ctx),
+      executionContext: ctx.executionContext,
       get: ctx.get as any,
-      use: <TDep, TDepParams = any>(
+      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",
       body: undefined,
       reverse: createReverseFunction(
@@ -904,9 +1037,14 @@ export function createUseFunction<TEnv>(
         ctx.params as Record<string, string>,
         ctx._routeName ? isRouteRootScoped(ctx._routeName) : undefined,
       ),
+      rendered: () => {
+        throw new Error(
+          `ctx.rendered() is only available in DSL loaders (registered via loader() in urls()). ` +
+            `It cannot be used from request-context loaders or server actions.`,
+        );
+      },
     };
 
-    // Start loader execution with tracking
     const doneLoader = track(`loader:${loader.$$id}`, 2);
     const promise = Promise.resolve(loaderFn(loaderCtx)).finally(() => {
       doneLoader();

package/src/ssr/index.tsx

@@ -129,6 +129,7 @@ interface RscPayload {
     matched?: string[];
     pathname?: string;
     params?: Record<string, string>;
+    basename?: string;
     themeConfig?: ResolvedThemeConfig | null;
     initialTheme?: Theme;
     version?: string;
@@ -161,9 +162,13 @@ function createSsrEventController(opts: {
 }): EventController {
   const location = new URL(opts.pathname, "http://localhost");
   let params = opts.params ?? {};
+  const rawMatched = opts.matched ?? [];
   const handleState = {
     data: opts.handleData ?? {},
-    segmentOrder: filterSegmentOrder(opts.matched ?? []),
+    segmentOrder: filterSegmentOrder(rawMatched),
+    routeSegmentIds: rawMatched.filter(
+      (id) => !id.includes(".@") && !/D\d+\./.test(id),
+    ),
   };
   const state: DerivedNavigationState = {
     state: "idle",
@@ -261,6 +266,7 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
       function SsrRoot() {
         payload ??= createFromReadableStream<RscPayload>(rscStream1);
         const resolved = React.use(payload);
+
         const themeConfig = resolved.metadata?.themeConfig ?? null;
         const pathname = resolved.metadata?.pathname ?? "/";
 
@@ -286,6 +292,7 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
           navigate: async () => {},
           refresh: async () => {},
           version: resolved.metadata?.version,
+          basename: resolved.metadata?.basename,
         };
 
         // Build content tree from segments.

package/src/static-handler.ts

@@ -32,11 +32,21 @@
  */
 import type { ReactNode } from "react";
 import type { Handler } from "./types.js";
-import type { PrerenderOptions, StaticBuildContext } from "./prerender.js";
+import type { StaticBuildContext } from "./prerender.js";
+import type { UseItems, HandlerUseItem } from "./route-types.js";
 import { isCachedFunction } from "./cache/taint.js";
 
 // -- Types ------------------------------------------------------------------
 
+export interface StaticHandlerOptions {
+  /**
+   * Keep handler in server bundle for live fallback (default: false).
+   * false: handler replaced with stub, source-only APIs excluded from bundle.
+   * true: handler stays in bundle, renders live at request time.
+   */
+  passthrough?: boolean;
+}
+
 export interface StaticHandlerDefinition<
   TParams extends Record<string, any> = any,
 > {
@@ -46,14 +56,16 @@ export interface StaticHandlerDefinition<
   /** In dev mode, the actual handler function that layout/path/parallel can call. */
   handler: Handler<TParams>;
   /** Static handler options (passthrough support). */
-  options?: PrerenderOptions;
+  options?: StaticHandlerOptions;
+  /** Composable default DSL items merged when the handler is mounted. */
+  use?: () => UseItems<HandlerUseItem>;
 }
 
 // -- Function ---------------------------------------------------------------
 
 export function Static<TParams extends Record<string, any> = {}>(
   handler: (ctx: StaticBuildContext) => ReactNode | Promise<ReactNode>,
-  options?: PrerenderOptions,
+  options?: StaticHandlerOptions,
   __injectedId?: string,
 ): StaticHandlerDefinition<TParams>;
 
@@ -61,7 +73,7 @@ export function Static<TParams extends Record<string, any> = {}>(
 
 export function Static<TParams extends Record<string, any>>(
   handler: Function,
-  optionsOrId?: PrerenderOptions | string,
+  optionsOrId?: StaticHandlerOptions | string,
   maybeId?: string,
 ): StaticHandlerDefinition<TParams> {
   if (isCachedFunction(handler)) {
@@ -72,19 +84,19 @@ export function Static<TParams extends Record<string, any>>(
     );
   }
 
-  let options: PrerenderOptions | undefined;
+  let options: StaticHandlerOptions | undefined;
   let id: string;
 
   if (typeof optionsOrId === "string") {
     id = optionsOrId;
   } else {
-    options = optionsOrId as PrerenderOptions | undefined;
+    options = optionsOrId as StaticHandlerOptions | undefined;
     id = maybeId ?? "";
   }
 
   if (!id) {
     throw new Error(
-      "[rsc-router] Static: missing $$id. " +
+      "[rango] Static: missing $$id. " +
         "Ensure the exposeInternalIds Vite plugin is configured.",
     );
   }

package/src/testing/cache-status.ts

@@ -0,0 +1,166 @@
+/**
+ * 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 };
+
+/**
+ * Parse an `X-Rango-Cache` header value into a `{ routeKey: status }` map.
+ *
+ * Header format: `<routeKey>=<status>, <routeKey2>=<status2>`. The key is the
+ * route NAME (ctx.routeKey, e.g. `product.detail`), NOT the URL pattern —
+ * see assertCacheStatus. Whitespace around entries and the `=` is tolerated.
+ * Entries without a status are ignored.
+ *
+ * @example
+ * parseCacheHeader("product.detail=hit, shop.layout=stale")
+ * // => { "product.detail": "hit", "shop.layout": "stale" }
+ */
+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;
+}
+
+/**
+ * Assert that the `X-Rango-Cache` header reports `expected` status for the
+ * given route. Throws a descriptive error when the header is missing (gate
+ * off), the route is absent, or the status differs.
+ *
+ * `routeKey` is the route NAME (e.g. `product.detail`), the same id the header
+ * carries — NOT the URL pattern (`/products/:id`). The signal is built from
+ * ctx.routeKey (telemetry.ts), so a pattern-shaped key never matches.
+ *
+ * The header is produced by the RSC render pipeline, so get the Response from
+ * the router's real fetch path (`router.fetch(...)`), with the debug cache
+ * signal gate enabled (`debugCacheSignal: true` or `RANGO_TEST_SIGNALS=1`).
+ * NOTE: `dispatch()` is the non-RSC primitive and never emits this header.
+ *
+ * @example
+ * // debugCacheSignal must be enabled on the router under test.
+ * const res = await router.fetch(new Request("https://app/products/42"));
+ * assertCacheStatus(res, "product.detail", "hit");
+ */
+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[];
+}
+
+/**
+ * Create a capturing telemetry sink for asserting on `cache.decision` events.
+ *
+ * This is the ZERO-production-surface path: no response header is emitted, the
+ * consumer just inspects the captured events.
+ *
+ * @example
+ * const { sink, events } = createCacheSink();
+ * const router = createRouter({ telemetry: sink, ... });
+ * // ...send a request through the router's RSC fetch path...
+ * const decisions = filterCacheDecisions(events);
+ * expect(decisions[0].segments?.[0].cacheStatus).toBe("hit");
+ */
+export function createCacheSink(): CacheSink {
+  const events: TelemetryEvent[] = [];
+  const sink: TelemetrySink = {
+    emit(event: TelemetryEvent): void {
+      events.push(event);
+    },
+  };
+  return { sink, events };
+}
+
+/**
+ * Filter captured telemetry events down to `cache.decision` events.
+ */
+export function filterCacheDecisions(
+  events: readonly TelemetryEvent[],
+): CacheDecisionEvent[] {
+  return events.filter(
+    (e): e is CacheDecisionEvent => e.type === "cache.decision",
+  );
+}