@rangojs/router 0.0.0-experimental.dfa55db4 → 0.0.0-experimental.e16b7c00

package/src/cache/cf/index.ts

@@ -16,7 +16,10 @@ export {
   type KVNamespace,
 } from "./cf-cache-store.js";
 
-// Header constants for debugging and inspection
+// 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,

package/src/cache/document-cache.ts

@@ -12,10 +12,14 @@
  */
 
 import type { MiddlewareFn, MiddlewareContext } from "../router/middleware.js";
-import { getRequestContext } from "../server/request-context.js";
+import {
+  getRequestContext,
+  type RequestContext,
+} from "../server/request-context.js";
 import { mayNeedSSR } from "../rsc/ssr-setup.js";
 import { sortedSearchString } from "./cache-key-utils.js";
 import { runBackground } from "./background-task.js";
+import { reportCacheError } from "./cache-error.js";
 
 // ============================================================================
 // Constants
@@ -24,6 +28,32 @@ import { runBackground } from "./background-task.js";
 /** 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: segment 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 segment-DSL tags may miss those (the
+ * segment cache entry itself is still correctly tagged and invalidated). Runtime
+ * cacheTag()/"use cache" and loader tags are always captured once the body drains.
+ */
+function collectRequestTags(
+  requestCtx: RequestContext | undefined,
+): string[] | undefined {
+  const tags = requestCtx?._requestTags;
+  return tags && tags.size > 0 ? [...tags] : undefined;
+}
+
 /**
  * Simple hash function for segment IDs.
  * Creates a short, deterministic hash to differentiate cache keys
@@ -303,17 +333,26 @@ export function createDocumentCacheMiddleware<TEnv = any>(
             const fresh = await next();
             const directives = shouldCacheResponse(fresh);
 
-            if (directives) {
+            if (directives && fresh.body) {
+              // Background revalidation: nothing streams to a client, so drain
+              // the fresh render fully before snapshotting tags (same
+              // render-complete barrier as the miss path).
+              const body = await new Response(fresh.body).arrayBuffer();
               await store.putResponse!(
                 cacheKey,
-                fresh,
+                new Response(body, fresh),
                 directives.sMaxAge!,
                 directives.staleWhileRevalidate,
+                collectRequestTags(requestCtx),
               );
               log(`[DocumentCache] REVALIDATED ${typeLabel}: ${url.pathname}`);
             }
           } catch (error) {
-            console.error(`[DocumentCache] Revalidation failed:`, error);
+            reportCacheError(
+              error,
+              "cache-write",
+              "[DocumentCache] revalidation",
+            );
           }
         });
 
@@ -346,14 +385,27 @@ export function createDocumentCacheMiddleware<TEnv = any>(
         // Clone response for caching (non-blocking)
         runBackground(requestCtx, async () => {
           try {
+            // Drain the cache copy fully BEFORE snapshotting tags. Tags from
+            // Suspense-streamed "use cache"/cacheTag and loaders are recorded as
+            // each value resolves during the RSC/HTML render, which completes
+            // only when the stream ends - the handler-settlement barrier is too
+            // early. Buffering the body (the client streams the other tee branch,
+            // unaffected) is the render-complete barrier that keeps the cached
+            // body and its tag set consistent.
+            const body = await new Response(cacheStream).arrayBuffer();
             await store.putResponse!(
               cacheKey,
-              new Response(cacheStream, originalResponse),
+              new Response(body, originalResponse),
               directives.sMaxAge!,
               directives.staleWhileRevalidate,
+              collectRequestTags(requestCtx),
             );
           } catch (error) {
-            console.error(`[DocumentCache] Cache write failed:`, error);
+            reportCacheError(
+              error,
+              "cache-write",
+              "[DocumentCache] cache write",
+            );
           }
         });
 
@@ -366,7 +418,7 @@ export function createDocumentCacheMiddleware<TEnv = any>(
       // No cache headers - pass through
       return originalResponse;
     } catch (error) {
-      console.error(`[DocumentCache] Error:`, error);
+      reportCacheError(error, "cache-read", "[DocumentCache] middleware");
       if (handlerCalled) {
         // Post-handler failure (e.g. body.tee()): do not call next() again
         // as that would re-run handler side effects.

package/src/cache/index.ts

@@ -42,3 +42,9 @@ 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

@@ -21,10 +21,13 @@ import {
   computeExpiration,
   DEFAULT_FUNCTION_TTL,
 } from "./cache-policy.js";
+import { reportCacheError } from "./cache-error.js";
 
 const CACHE_REGISTRY_KEY = "__rsc_router_segment_cache_registry__";
 const RESPONSE_CACHE_REGISTRY_KEY = "__rsc_router_response_cache_registry__";
 const ITEM_CACHE_REGISTRY_KEY = "__rsc_router_item_cache_registry__";
+const TAG_INDEX_REGISTRY_KEY = "__rsc_router_tag_index_registry__";
+const KEY_TAGS_REGISTRY_KEY = "__rsc_router_key_tags_registry__";
 
 /**
  * Get or create a named Map from a globalThis-backed registry.
@@ -59,6 +62,7 @@ interface CachedItemEntry {
   handles?: Record<string, SegmentHandleData>;
   expiresAt: number;
   staleAt: number;
+  tags?: string[];
 }
 
 /**
@@ -73,6 +77,11 @@ export interface MemorySegmentCacheStoreOptions<TEnv = unknown> {
    * When omitted, the store uses a plain instance-level Map with no
    * globalThis sharing, which is the safest default for isolation.
    *
+   * Caveat: two instances constructed with the SAME name share all backing maps
+   * (data + tag index), but each keeps its OWN `defaults` and `keyGenerator` from
+   * its options - those are not shared. Use one instance per name, or keep the
+   * options identical, to avoid surprising divergence.
+   *
    * @example
    * ```typescript
    * // Two named stores are isolated from each other
@@ -121,6 +130,11 @@ export interface MemorySegmentCacheStoreOptions<TEnv = unknown> {
  * For production with multiple instances, use a distributed store
  * like Cloudflare KV or Redis.
  *
+ * Tag-index cleanup is lazy, mirroring the data maps: a tagged entry that
+ * expires but is never re-read or invalidated leaves its forward+reverse index
+ * entries resident until the key is reused or invalidated. This is bounded by
+ * the distinct-tag count and acceptable for a dev/single-instance store.
+ *
  * @example
  * ```typescript
  * // Basic usage
@@ -143,6 +157,10 @@ export class MemorySegmentCacheStore<
   private cache: Map<string, CachedEntryData>;
   private responseCache: Map<string, CachedResponseEntry>;
   private itemCache: Map<string, CachedItemEntry>;
+  /** tag -> set of prefixed cache keys (seg:key, res:key, item:key) */
+  private tagIndex: Map<string, Set<string>>;
+  /** prefixed cache key -> set of tags (reverse index for O(tags) unregister) */
+  private keyTags: Map<string, Set<string>>;
   readonly defaults?: CacheDefaults;
   readonly keyGenerator?: (
     ctx: RequestContext<TEnv>,
@@ -165,11 +183,21 @@ export class MemorySegmentCacheStore<
         ITEM_CACHE_REGISTRY_KEY,
         options.name,
       );
+      this.tagIndex = getNamedMap<Set<string>>(
+        TAG_INDEX_REGISTRY_KEY,
+        options.name,
+      );
+      this.keyTags = getNamedMap<Set<string>>(
+        KEY_TAGS_REGISTRY_KEY,
+        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>();
+      this.tagIndex = new Map<string, Set<string>>();
+      this.keyTags = new Map<string, Set<string>>();
     }
     this.defaults = options?.defaults;
     this.keyGenerator = options?.keyGenerator;
@@ -184,6 +212,7 @@ export class MemorySegmentCacheStore<
 
     // Check expiration
     if (Date.now() > cached.expiresAt) {
+      this.unregisterTags(`seg:${key}`);
       this.cache.delete(key);
       return null;
     }
@@ -204,10 +233,18 @@ export class MemorySegmentCacheStore<
       ...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) {
+      this.registerTags(data.tags, prefixedKey);
+    }
   }
 
   async delete(key: string): Promise<boolean> {
+    this.unregisterTags(`seg:${key}`);
     return this.cache.delete(key);
   }
 
@@ -215,6 +252,8 @@ export class MemorySegmentCacheStore<
     this.cache.clear();
     this.responseCache.clear();
     this.itemCache.clear();
+    this.tagIndex.clear();
+    this.keyTags.clear();
   }
 
   async getResponse(
@@ -224,6 +263,7 @@ export class MemorySegmentCacheStore<
     if (!cached) return null;
 
     if (Date.now() > cached.expiresAt) {
+      this.unregisterTags(`res:${key}`);
       this.responseCache.delete(key);
       return null;
     }
@@ -244,23 +284,40 @@ export class MemorySegmentCacheStore<
     response: Response,
     ttl: number,
     swr?: number,
+    tags?: string[],
   ): Promise<void> {
-    const body = await response.clone().arrayBuffer();
-    const headers: [string, string][] = [];
-    response.headers.forEach((value, name) => {
-      headers.push([name, value]);
-    });
+    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) => {
+        headers.push([name, value]);
+      });
 
-    const swrWindow = resolveSwrWindow(swr, this.defaults);
-    const { staleAt, expiresAt } = computeExpiration(ttl, swrWindow);
+      const swrWindow = resolveSwrWindow(swr, this.defaults);
+      const { staleAt, expiresAt } = computeExpiration(ttl, swrWindow);
 
-    this.responseCache.set(key, {
-      body,
-      status: response.status,
-      headers,
-      expiresAt,
-      staleAt,
-    });
+      const prefixedKey = `res:${key}`;
+      this.unregisterTags(prefixedKey);
+      this.responseCache.set(key, {
+        body,
+        status: response.status,
+        headers,
+        expiresAt,
+        staleAt,
+      });
+      if (tags && tags.length > 0) {
+        this.registerTags(tags, prefixedKey);
+      }
+    } catch (error) {
+      reportCacheError(
+        error,
+        "cache-write",
+        "[MemorySegmentCacheStore] putResponse",
+      );
+    }
   }
 
   async getItem(key: string): Promise<CacheItemResult | null> {
@@ -269,6 +326,7 @@ export class MemorySegmentCacheStore<
 
     const now = Date.now();
     if (now > cached.expiresAt) {
+      this.unregisterTags(`item:${key}`);
       this.itemCache.delete(key);
       return null;
     }
@@ -278,6 +336,7 @@ export class MemorySegmentCacheStore<
       value: cached.value,
       handles: cached.handles,
       shouldRevalidate: isStale,
+      tags: cached.tags,
     };
   }
 
@@ -289,12 +348,95 @@ export class MemorySegmentCacheStore<
     const ttl = resolveTtl(options?.ttl, this.defaults, DEFAULT_FUNCTION_TTL);
     const swrWindow = resolveSwrWindow(options?.swr, this.defaults);
     const { staleAt, expiresAt } = computeExpiration(ttl, swrWindow);
+    const prefixedKey = `item:${key}`;
+    this.unregisterTags(prefixedKey);
     this.itemCache.set(key, {
       value,
       handles: options?.handles,
       expiresAt,
       staleAt,
+      tags: options?.tags,
     });
+    if (options?.tags && options.tags.length > 0) {
+      this.registerTags(options.tags, prefixedKey);
+    }
+  }
+
+  /**
+   * 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) {
+        const colonIdx = prefixedKey.indexOf(":");
+        const prefix = prefixedKey.slice(0, colonIdx);
+        const rawKey = prefixedKey.slice(colonIdx + 1);
+
+        if (prefix === "seg") {
+          this.cache.delete(rawKey);
+        } else if (prefix === "res") {
+          this.responseCache.delete(rawKey);
+        } else if (prefix === "item") {
+          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) {
+      tagSet = new Set();
+      this.keyTags.set(prefixedKey, tagSet);
+    }
+    for (const tag of tags) {
+      tagSet.add(tag);
+      let keys = this.tagIndex.get(tag);
+      if (!keys) {
+        keys = new Set();
+        this.tagIndex.set(tag, keys);
+      }
+      keys.add(prefixedKey);
+    }
+  }
+
+  /**
+   * 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;
+    for (const tag of tagSet) {
+      const keys = this.tagIndex.get(tag);
+      if (keys) {
+        keys.delete(prefixedKey);
+        if (keys.size === 0) {
+          this.tagIndex.delete(tag);
+        }
+      }
+    }
+    this.keyTags.delete(prefixedKey);
   }
 
   /**
@@ -324,5 +466,7 @@ export class MemorySegmentCacheStore<
     delete (globalThis as any)[CACHE_REGISTRY_KEY];
     delete (globalThis as any)[RESPONSE_CACHE_REGISTRY_KEY];
     delete (globalThis as any)[ITEM_CACHE_REGISTRY_KEY];
+    delete (globalThis as any)[TAG_INDEX_REGISTRY_KEY];
+    delete (globalThis as any)[KEY_TAGS_REGISTRY_KEY];
   }
 }

package/src/cache/tag-invalidation.ts

@@ -0,0 +1,206 @@
+/**
+ * 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.
+ */
+function collectStores(): {
+  capable: SegmentCacheStore[];
+  incapable: number;
+} {
+  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 };
+}
+
+/**
+ * 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 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 } = collectStores();
+  if (capable.length === 0) {
+    warnNoTagStore("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 } = collectStores();
+  if (capable.length === 0) {
+    warnNoTagStore("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();
+  }
+}