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

package/src/cache/tag-invalidation.ts

@@ -0,0 +1,230 @@
+/**
+ * Cache Tag Invalidation API
+ *
+ * Two on-demand invalidation verbs, mirroring the distinction popularized by
+ * Next.js so consumers can pick the right consistency model:
+ *
+ * - updateTag(...tags): read-your-own-writes. Awaitable - resolves only after
+ *   in-process invalidation across every configured store completes. Use in a
+ *   Server Action and `await` it before the action re-renders, so the action's
+ *   own response reflects the mutation.
+ *
+ * - revalidateTag(...tags): fire-and-forget via waitUntil - the response is not
+ *   blocked. Use in Route Handlers / webhooks. NOTE: both verbs hard-purge; the
+ *   only difference is awaitability. revalidateTag does NOT serve stale content -
+ *   the next read after the invalidation lands is a hard miss that re-renders.
+ *   (The name mirrors Next.js, where it is SWR; here it is background-purge.)
+ *
+ * Both fan out across the app-level store (ctx._cacheStore) and every explicit
+ * per-scope store from cache({ store }) registered for this handler
+ * (ctx._explicitTaggedStores), calling the store-level invalidateTags()
+ * primitive for each tag. A single configured store (the common case) owns its
+ * own tag index and distributed invalidation - there is no separate
+ * tag-invalidation store.
+ */
+
+import { _getRequestContext } from "../server/request-context.js";
+import { reportingAsync } from "./cache-error.js";
+import { normalizeTags } from "./cache-tag.js";
+import type { SegmentCacheStore } from "./types.js";
+
+/**
+ * Collect every store that may hold entries tagged for this request's handler:
+ * the app-level store plus all explicit per-scope stores (deduplicated). Splits
+ * them into tag-capable (implement invalidateTags()) and not, so callers can
+ * warn about configured stores whose tagged entries will NOT be invalidated.
+ *
+ * `hasContext` reports whether an ALS request context existed at all. Without one
+ * (e.g. a queue consumer or cron job calling updateTag/revalidateTag) no stores
+ * are reachable, and the empty-capable case is a missing-context problem, not a
+ * store-config problem - callers branch on this to warn about the right cause.
+ */
+function collectStores(): {
+  capable: SegmentCacheStore[];
+  incapable: number;
+  hasContext: boolean;
+} {
+  const ctx = _getRequestContext();
+  const stores = new Set<SegmentCacheStore>();
+  if (ctx?._cacheStore) stores.add(ctx._cacheStore);
+  if (ctx?._explicitTaggedStores) {
+    for (const store of ctx._explicitTaggedStores) stores.add(store);
+  }
+  const capable: SegmentCacheStore[] = [];
+  let incapable = 0;
+  for (const store of stores) {
+    if (typeof store.invalidateTags === "function") capable.push(store);
+    else incapable++;
+  }
+  return { capable, incapable, hasContext: ctx != null };
+}
+
+/**
+ * Production-visible warning. A misconfigured store silently dropping
+ * invalidations is a data-correctness footgun, so this surfaces in every
+ * environment (not dev-only).
+ */
+function warnNoTagStore(fn: string, tags: string[]): void {
+  console.warn(
+    `[${fn}] No tag-capable cache store is configured; tags ` +
+      `[${tags.join(", ")}] were not invalidated. The configured store must ` +
+      `implement invalidateTags() (the built-in MemorySegmentCacheStore and ` +
+      `CFCacheStore do).`,
+  );
+}
+
+/**
+ * Production-visible warning for the no-request-context case. Distinct from
+ * warnNoTagStore: the stores are not unreachable because they are misconfigured,
+ * but because there is no ALS request context to reach them through (e.g. a queue
+ * consumer or scheduled job). Naming the real cause keeps consumers from chasing
+ * a store-config red herring.
+ */
+function warnNoRequestContext(fn: string, tags: string[]): void {
+  console.warn(
+    `[${fn}] Called outside a request context (e.g. from a queue consumer or ` +
+      `scheduled job); no cache stores are reachable and tags ` +
+      `[${tags.join(", ")}] were not invalidated. Invoke it within a request ` +
+      `(Server Action or route handler).`,
+  );
+}
+
+/**
+ * Production-visible warning for mixed-store configs: at least one configured
+ * store does not support tag invalidation, so its tagged entries (if any) are
+ * left stale even though other stores were invalidated.
+ */
+function warnPartialTagStore(fn: string, incapable: number): void {
+  console.warn(
+    `[${fn}] ${incapable} configured cache store(s) do not implement ` +
+      `invalidateTags(); their tagged entries were NOT invalidated. Use a ` +
+      `tag-capable store (e.g. MemorySegmentCacheStore / CFCacheStore) for any ` +
+      `cache({ store }) boundary whose entries you invalidate by tag.`,
+  );
+}
+
+async function invalidateAcross(
+  stores: SegmentCacheStore[],
+  tags: string[],
+): Promise<void> {
+  // One invalidateTags(tags) call per store: the store receives the whole tag
+  // batch so it can do a single CDN purge request rather than one per tag.
+  //
+  // allSettled, not all: a store's invalidateTags() can reject (e.g. CFCacheStore
+  // surfaces a failed durable KV marker write). With Promise.all, the first
+  // rejection would short-circuit and the other stores' outcomes would go
+  // unobserved. Attempt every store, then surface a combined error so an awaited
+  // updateTag() still rejects (read-your-own-writes honesty) without masking the
+  // stores that did succeed.
+  const results = await Promise.allSettled(
+    stores.map((store) => store.invalidateTags!(tags)),
+  );
+  const errors = results
+    .filter((r): r is PromiseRejectedResult => r.status === "rejected")
+    .map((r) => r.reason);
+  if (errors.length > 0) {
+    const err = new Error(
+      `[tag invalidation] ${errors.length}/${stores.length} store(s) failed to ` +
+        `invalidate tags [${tags.join(", ")}]; their entries may still serve ` +
+        `stale data. Retry the invalidation.`,
+    );
+    (err as Error & { cause?: unknown }).cause = errors[0];
+    throw err;
+  }
+}
+
+/**
+ * Immediately expire every cache entry tagged with any of `tags`, resolving
+ * once in-process invalidation across all configured stores completes.
+ *
+ * Read-your-own-writes: because the returned promise resolves before you return
+ * from a Server Action, awaiting it guarantees the action's own re-render (and
+ * any subsequent read) sees fresh data.
+ *
+ * @example
+ * ```typescript
+ * async function updateProduct(formData: FormData) {
+ *   "use server";
+ *   await db.updateProduct(formData);
+ *   await updateTag("products");   // next render is fresh
+ * }
+ * ```
+ */
+export async function updateTag(...tags: string[]): Promise<void> {
+  const valid = normalizeTags(tags);
+  if (valid.length === 0) return;
+
+  const { capable, incapable, hasContext } = collectStores();
+  if (capable.length === 0) {
+    if (hasContext) warnNoTagStore("updateTag", valid);
+    else warnNoRequestContext("updateTag", valid);
+    return;
+  }
+  if (incapable > 0) warnPartialTagStore("updateTag", incapable);
+
+  await invalidateAcross(capable, valid);
+}
+
+/**
+ * Invalidate every cache entry tagged with any of `tags` in the background,
+ * without blocking the current response (fire-and-forget via waitUntil).
+ *
+ * This is NOT stale-while-revalidate: like updateTag() it hard-purges, so the
+ * next read after the invalidation lands is a miss that re-renders fresh. The
+ * only difference from updateTag() is awaitability - revalidateTag() defers the
+ * purge off the response path and is not awaited.
+ *
+ * Use in Route Handlers / webhooks. For read-your-own-writes inside a Server
+ * Action, use updateTag() instead so the action's own response is fresh.
+ *
+ * Fire-and-forget: because this returns void and runs in the background, a
+ * failed durable marker write (e.g. a transient KV outage) is NOT surfaced to
+ * the caller. It IS reported - logged loudly and routed through the router's
+ * `onError` callback (phase `cache`, `metadata.category === "cache-invalidate"`)
+ * via reportingAsync - so the failure is observable in telemetry even though it
+ * cannot be awaited. If you need the invalidation to be CONFIRMED (and to retry
+ * on failure), use `await updateTag()` instead, which rejects when a store's
+ * durable write fails.
+ *
+ * @example
+ * ```typescript
+ * // route handler invoked by an external webhook
+ * export async function POST() {
+ *   "use server";
+ *   revalidateTag("products");
+ *   return new Response("ok");
+ * }
+ * ```
+ */
+export function revalidateTag(...tags: string[]): void {
+  const valid = normalizeTags(tags);
+  if (valid.length === 0) return;
+
+  const { capable, incapable, hasContext } = collectStores();
+  if (capable.length === 0) {
+    if (hasContext) warnNoTagStore("revalidateTag", valid);
+    else warnNoRequestContext("revalidateTag", valid);
+    return;
+  }
+  if (incapable > 0) warnPartialTagStore("revalidateTag", incapable);
+
+  const ctx = _getRequestContext();
+  // reportingAsync never rejects: it catches a failed durable write and routes
+  // it through reportCacheError (loud log + onError). This is the only place a
+  // revalidateTag failure can be observed, since it is not awaitable. Pass ctx
+  // explicitly - the run executes in a detached waitUntil where the ALS context
+  // is gone, so onError fires only if we hand it the captured context.
+  const run = () =>
+    reportingAsync(
+      () => invalidateAcross(capable, valid),
+      "cache-invalidate",
+      "[revalidateTag] background invalidation",
+      ctx,
+    );
+  if (ctx?.waitUntil) {
+    ctx.waitUntil(run);
+  } else {
+    // No request context (e.g. called outside ALS): best-effort background run.
+    void run();
+  }
+}

package/src/cache/types.ts

@@ -136,12 +136,14 @@ export interface SegmentCacheStore<TEnv = unknown> {
    * @param response - Response to cache (will be cloned)
    * @param ttl - Time-to-live in seconds
    * @param swr - Optional stale-while-revalidate window in seconds
+   * @param tags - Optional cache tags for invalidation
    */
   putResponse?(
     key: string,
     response: Response,
     ttl: number,
     swr?: number,
+    tags?: string[],
   ): Promise<void>;
 
   // ============================================================================
@@ -167,6 +169,20 @@ export interface SegmentCacheStore<TEnv = unknown> {
     value: string,
     options?: CacheItemOptions,
   ): Promise<void>;
+
+  // ============================================================================
+  // Tag-based Invalidation (optional)
+  // ============================================================================
+
+  /**
+   * Invalidate every cache entry (segment, response, item) tagged with any of
+   * `tags`. Store-level primitive that the public updateTag()/revalidateTag()
+   * APIs delegate to. Receives ALL of one invalidation call's tags at once so
+   * stores can batch their work (e.g. a single CDN purge request rather than
+   * one per tag). Stores that do not support tags simply omit this method.
+   * @param tags - The cache tags to invalidate
+   */
+  invalidateTags?(tags: string[]): Promise<void>;
 }
 
 /**
@@ -181,6 +197,13 @@ export interface CacheItemResult {
   handles?: string;
   /** Whether the entry is stale and should be revalidated */
   shouldRevalidate: boolean;
+  /**
+   * The entry's cache tags (including runtime cacheTag() tags), surfaced on read
+   * so a "use cache" HIT can still contribute its tags to the request-scoped tag
+   * set used by document-level caching. On a hit the cached function is not
+   * re-run, so its runtime tags are only available here, not from re-execution.
+   */
+  tags?: string[];
 }
 
 /**
@@ -235,6 +258,10 @@ export interface CachedEntryData {
   handles: string;
   /** Expiration timestamp (ms since epoch) */
   expiresAt: number;
+  /** Cache tags for invalidation */
+  tags?: string[];
+  /** Timestamp (ms since epoch) when tags were attached, for distributed invalidation */
+  taggedAt?: number;
 }
 
 // ============================================================================

package/src/index.rsc.ts

@@ -189,6 +189,13 @@ export {
   type ReadonlyHeaders,
 } from "./server/cookie-store.js";
 
+// Cache tag APIs (server-only)
+// cacheTag: tag the current "use cache" entry at runtime.
+// updateTag: read-your-own-writes invalidation (awaitable, for Server Actions).
+// revalidateTag: background hard-purge invalidation (not awaited, for route handlers / webhooks).
+export { cacheTag } from "./cache/cache-tag.js";
+export { updateTag, revalidateTag } from "./cache/tag-invalidation.js";
+
 // Meta types
 export type { MetaDescriptor, MetaDescriptorBase } from "./router/types.js";
 

package/src/index.ts

@@ -237,6 +237,18 @@ export function middleware(): never {
 export function revalidate(): never {
   throw serverOnlyStubError("revalidate");
 }
+// Cache tag APIs are server-only (real implementations in index.rsc.ts). These
+// stubs keep the named-export shape identical under the default/non-react-server
+// condition so SSR/client/default bundles that encounter the import link cleanly.
+export function cacheTag(): never {
+  throw serverOnlyStubError("cacheTag");
+}
+export function updateTag(): never {
+  throw serverOnlyStubError("updateTag");
+}
+export function revalidateTag(): never {
+  throw serverOnlyStubError("revalidateTag");
+}
 export function loader(): never {
   throw serverOnlyStubError("loader");
 }

package/src/router/prerender-match.ts

@@ -216,6 +216,7 @@ export async function matchForPrerender<TEnv = any>(
       }) as any,
       method: "GET",
       _handleStore: handleStore,
+      _requestTags: new Set<string>(),
       waitUntil: () => {},
       onResponse: () => {},
       _onResponseCallbacks: [],
@@ -465,6 +466,7 @@ export async function renderStaticSegment<TEnv = any>(
     }) as any,
     method: "GET",
     _handleStore: handleStore,
+    _requestTags: new Set<string>(),
     waitUntil: () => {},
     onResponse: () => {},
     _onResponseCallbacks: [],

package/src/router/segment-resolution/loader-cache.ts

@@ -28,9 +28,11 @@ import {
   resolveSwrWindow,
   resolveCacheKey,
   resolveCacheStore,
+  resolveTagsOption,
   DEFAULT_ROUTE_TTL,
 } from "../../cache/cache-policy.js";
 import { readThroughItem } from "../../cache/read-through-swr.js";
+import { recordRequestTags } from "../../cache/cache-tag.js";
 // Lazy-loaded to avoid pulling @vitejs/plugin-rsc/rsc into modules that
 // import segment-resolution but never use loader caching.
 let _serializeResult: typeof import("../../cache/segment-codec.js").serializeResult;
@@ -87,23 +89,8 @@ async function resolveLoaderKey(
  */
 function resolveTags(loaderEntry: LoaderEntry): string[] | undefined {
   const options = loaderEntry.cache?.options;
-  if (!options || !options.tags) return undefined;
-
-  if (typeof options.tags === "function") {
-    const requestCtx = getRequestContext();
-    if (!requestCtx) return undefined;
-    try {
-      return options.tags(requestCtx);
-    } catch (error) {
-      console.error(
-        `[LoaderCache] Tags function failed, caching without tags:`,
-        error,
-      );
-      return undefined;
-    }
-  }
-
-  return options.tags;
+  if (!options) return undefined;
+  return resolveTagsOption(options.tags, getRequestContext(), "LoaderCache");
 }
 
 function getLoaderStore(
@@ -152,6 +139,10 @@ export function resolveLoaderData<TEnv>(
   const swrWindow = resolveSwrWindow(options.swr, store.defaults);
   const swr = swrWindow || undefined;
   const tags = resolveTags(loaderEntry);
+  // Loader tags are config-derived, so they are the complete set whether this is
+  // a cache hit or miss; record them every time so a document built from this
+  // loader is tagged for invalidation.
+  recordRequestTags(tags);
 
   // Wrap ctx.use() so cache HIT primes the handler's memoization map.
   // ctx.use() closes over the match context's loaderPromises (not request context's).

package/src/rsc/handler.ts

@@ -57,6 +57,7 @@ import {
   getRouterTrie,
 } from "../route-map-builder.js";
 import type { HandlerContext } from "./handler-context.js";
+import type { CacheErrorCategory } from "../cache/cache-error.js";
 import type { SegmentCacheStore } from "../cache/types.js";
 import { buildRouterTrieFromUrlpatterns } from "./manifest-init.js";
 import { handleProgressiveEnhancement } from "./progressive-enhancement.js";
@@ -150,6 +151,13 @@ export function createRSCHandler<
 >(options: CreateRSCHandlerOptions<TEnv, TRoutes>) {
   const { router, version = VERSION, nonce: nonceProvider } = options;
 
+  // Handler-owned registry of explicit per-scope stores from cache({ store }).
+  // Lives in the closure so it is scoped per handler (multi-router deployments
+  // get separate registries) and accumulates every explicit store this handler
+  // resolves across requests. updateTag()/revalidateTag() iterate it to reach
+  // stores not covered by the app-level ctx._cacheStore.
+  const explicitTaggedStores = new Set<SegmentCacheStore>();
+
   // Use provided deps or default to @vitejs/plugin-rsc/rsc exports
   const deps = options.deps ?? rscDeps;
   const {
@@ -441,6 +449,7 @@ export function createRSCHandler<
       url,
       variables,
       cacheStore,
+      explicitTaggedStores,
       cacheProfiles: router.cacheProfiles,
       executionContext: executionCtx,
       themeConfig: router.themeConfig,
@@ -453,7 +462,7 @@ export function createRSCHandler<
     // can surface non-fatal errors through the router's onError callback.
     requestContext._reportBackgroundError = (
       error: unknown,
-      category: string,
+      category: CacheErrorCategory,
     ) => {
       callOnError(error, "cache", {
         request,

package/src/rsc/response-route-handler.ts

@@ -12,7 +12,7 @@ import { contextGet } from "../context-var.js";
 import { NOCACHE_SYMBOL } from "../cache/taint.js";
 import { traverseBack } from "../router/pattern-matching.js";
 import { RESPONSE_TYPE_MIME } from "../router/content-negotiation.js";
-import { createCacheScope } from "../cache/cache-scope.js";
+import { createCacheScope, resolveCacheTags } from "../cache/cache-scope.js";
 import { executeMiddleware } from "../router/middleware.js";
 import {
   createReverseFunction,
@@ -277,6 +277,11 @@ export async function handleResponseRoute<TEnv>(
           }
         }
 
+        // Resolve cache tags for this document entry (static or dynamic),
+        // while request context is available. Passed to putResponse so the
+        // entry is tag-invalidatable.
+        const responseTags = resolveCacheTags(cacheScope.config, reqCtx);
+
         // Save pre-handler callbacks (registered by app-level middleware
         // before we reach the cache block) and clear the live array.
         // createResponseWithMergedHeaders (inside the handler) eagerly
@@ -318,6 +323,7 @@ export async function handleResponseRoute<TEnv>(
                     fresh.clone(),
                     cacheScope!.ttl,
                     cacheScope!.swr,
+                    responseTags,
                   );
                 }
               } catch (error) {
@@ -346,6 +352,7 @@ export async function handleResponseRoute<TEnv>(
                 response.clone(),
                 cacheScope!.ttl,
                 cacheScope!.swr,
+                responseTags,
               );
             } catch (error) {
               console.error(`[ResponseCache] Cache write failed:`, error);

package/src/server/request-context.ts

@@ -11,6 +11,7 @@
  */
 
 import { AsyncLocalStorage } from "node:async_hooks";
+import type { CacheErrorCategory } from "../cache/cache-error.js";
 import type { CookieOptions } from "../router/middleware.js";
 import type { LoaderDefinition, LoaderContext } from "../types.js";
 import type { ScopedReverseFunction } from "../reverse.js";
@@ -140,6 +141,25 @@ export interface RequestContext<
   /** @internal Cache store for segment caching (optional, used by CacheScope) */
   _cacheStore?: SegmentCacheStore;
 
+  /**
+   * @internal Handler-owned registry of explicit per-scope stores from
+   * cache({ store }). Created once per createRSCHandler() and threaded into
+   * every request context, so it accumulates every explicit store the handler
+   * resolves. updateTag()/revalidateTag() iterate this set plus _cacheStore to
+   * reach every store that may hold tagged entries. The app-level store is not
+   * added here (it is always reachable via _cacheStore).
+   */
+  _explicitTaggedStores?: Set<SegmentCacheStore>;
+
+  /**
+   * @internal Union of every cache tag resolved while producing this request's
+   * response (from cache({ tags }), runtime cacheTag(), and loader cache tags).
+   * Populated at the tag-resolution sites via recordRequestTags(). Read by the
+   * document cache middleware so a full-page entry is tagged with everything its
+   * content used and can therefore be invalidated by updateTag()/revalidateTag().
+   */
+  _requestTags: Set<string>;
+
   /** @internal Cache profiles for "use cache" profile resolution (per-router) */
   _cacheProfiles?: Record<
     string,
@@ -318,9 +338,13 @@ export interface RequestContext<
    * @internal Report a non-fatal background error through the router's
    * onError callback. Wired by the RSC handler / router during request
    * creation. Cache-runtime and other subsystems call this to surface
-   * errors without failing the response.
+   * errors without failing the response. `category` is surfaced to consumers as
+   * `metadata.category` on the onError context (phase `cache`).
    */
-  _reportBackgroundError?: (error: unknown, category: string) => void;
+  _reportBackgroundError?: (
+    error: unknown,
+    category: CacheErrorCategory,
+  ) => void;
 
   /** @internal Per-request debug performance override (set via ctx.debugPerformance()) */
   _debugPerformance?: boolean;
@@ -355,6 +379,8 @@ export type PublicRequestContext<
   | "deleteCookie"
   | "_handleStore"
   | "_cacheStore"
+  | "_explicitTaggedStores"
+  | "_requestTags"
   | "_cacheProfiles"
   | "_onResponseCallbacks"
   | "_themeConfig"
@@ -500,6 +526,11 @@ export interface CreateRequestContextOptions<TEnv> {
   initialResponse?: Response;
   /** Optional cache store for segment caching (used by CacheScope) */
   cacheStore?: SegmentCacheStore;
+  /**
+   * Handler-owned registry of explicit per-scope stores for cross-store tag
+   * invalidation. Created once per handler, reused across requests.
+   */
+  explicitTaggedStores?: Set<SegmentCacheStore>;
   /** Optional cache profiles for "use cache" resolution (per-router) */
   cacheProfiles?: Record<
     string,
@@ -529,6 +560,7 @@ export function createRequestContext<TEnv>(
     variables,
     initialResponse,
     cacheStore,
+    explicitTaggedStores,
     cacheProfiles,
     executionContext,
     themeConfig,
@@ -746,6 +778,8 @@ export function createRequestContext<TEnv>(
 
     _handleStore: handleStore,
     _cacheStore: cacheStore,
+    _explicitTaggedStores: explicitTaggedStores,
+    _requestTags: new Set<string>(),
     _cacheProfiles: cacheProfiles,
 
     waitUntil(fn: () => Promise<void>): void {

package/src/types/cache-types.ts

@@ -78,6 +78,14 @@ export interface CacheOptions<TEnv = unknown> {
    * - Loader-specific caching strategies
    * - Hot data in fast cache, cold data in larger/slower cache
    *
+   * Tag invalidation caveat: a per-boundary store becomes reachable by
+   * `updateTag()` / `revalidateTag()` once this boundary is resolved in the
+   * current process. If the store is *durable* (shared across processes) and the
+   * very first request to a fresh worker is an `updateTag`/`revalidateTag` for a
+   * tag held only in this store - before this boundary is matched - that
+   * invalidation can miss it. For data you invalidate by tag, prefer the
+   * app-level store (always reachable), or ensure the boundary is warmed.
+   *
    * @example
    * ```typescript
    * const kvStore = new CloudflareKVStore(env.CACHE_KV);
@@ -145,10 +153,11 @@ export interface CacheOptions<TEnv = unknown> {
    * Tags for cache invalidation.
    * Can be a static array or a function that returns tags.
    *
-   * Note: Tags are passed through to the store but built-in stores
-   * (MemorySegmentCacheStore, CFCacheStore) do not yet index or
-   * invalidate by tag. Effective tag-based invalidation requires a
-   * custom store implementation with secondary indices.
+   * The built-in `MemorySegmentCacheStore` and `CFCacheStore` index by tag.
+   * Invalidate on demand with `updateTag(...tags)` (awaitable, read-your-own-writes;
+   * for server actions) or `revalidateTag(...tags)` (background hard-purge, not
+   * awaited; for route handlers / webhooks). For `CFCacheStore`, distributed
+   * invalidation requires a `kv` namespace (markers live in that same namespace).
    *
    * @example
    * ```typescript

package/src/types/error-types.ts

@@ -155,7 +155,11 @@ export interface OnErrorContext<TEnv = any> {
   stack?: string;
 
   /**
-   * Additional metadata specific to the error phase
+   * Additional metadata specific to the error phase. For the `cache` phase,
+   * `metadata.category` is a `CacheErrorCategory` (exported from
+   * `@rangojs/router/cache`) identifying the failure kind, e.g. `cache-read`
+   * (transient outage, degraded to a miss) vs `cache-corrupt` (faulty entry
+   * self-healed) vs `cache-invalidate` (a failed background revalidateTag).
    */
   metadata?: Record<string, unknown>;
 }