@rangojs/router 0.0.0-experimental.a769fbe7 → 0.0.0-experimental.ac99d918

package/src/build/route-types/source-scan.ts

@@ -0,0 +1,118 @@
+// Allocation-light, linear-time source scanning for the build-time scanners.
+//
+// The router-file scanner, the HMR relevance check, and the unsupported-shape
+// warning all need to know whether a token like `createRouter(` / `createLoader(`
+// appears in REAL code versus inside a comment or string literal. Rather than
+// build a full comment/string-stripped copy of the source (which on a large
+// file allocates an O(n) string plus, naively, a per-char array), these helpers
+// run the regex over the whole source ONCE (the engine sweeps left-to-right,
+// O(n)) and classify each match's offset with a forward, O(1)-memory cursor that
+// advances monotonically across the source.
+//
+// Time: O(n) — one native regex sweep plus one forward classification pass.
+// Memory: O(1) for the boolean check; O(#matches) for the index list. No
+// stripped copy and no per-char array are ever materialized.
+//
+// Pragmatic scanner, not a full tokenizer: regex literals are not special-cased
+// (a target token inside one is implausible) and template interpolations are
+// treated as opaque string content. One intentional consequence: a token whose
+// match would only complete by treating an interleaved comment as whitespace
+// (e.g. `createRouter /* x */ (`) is not detected — real calls never interleave
+// a comment between the callee and its arguments.
+
+// JS line terminators end a `//` comment: LF, CR, LS (U+2028), PS (U+2029).
+function isLineTerminator(ch: string): boolean {
+  const c = ch.charCodeAt(0);
+  // LF, CR, LS (U+2028), PS (U+2029)
+  return c === 10 || c === 13 || c === 0x2028 || c === 0x2029;
+}
+
+/**
+ * Build a classifier that answers "is offset `q` in code (not a comment or
+ * string)?" for STRICTLY INCREASING `q`. The internal cursor only moves forward,
+ * so a full left-to-right sequence of queries costs O(n) total with O(1) memory.
+ */
+function makeCodeClassifier(code: string): (q: number) => boolean {
+  const n = code.length;
+  let i = 0; // forward cursor: everything before `i` is already classified
+  let skipStart = -1; // last detected comment/string region (cache)
+  let skipEnd = -1;
+
+  return (q: number): boolean => {
+    if (q >= skipStart && q < skipEnd) return false; // q in the cached region
+    while (i < n && i <= q) {
+      const c = code[i];
+      const d = i + 1 < n ? code[i + 1] : "";
+      let end = -1;
+      if (c === "/" && d === "/") {
+        let j = i + 2;
+        while (j < n && !isLineTerminator(code[j])) j++;
+        end = j;
+      } else if (c === "/" && d === "*") {
+        let j = i + 2;
+        while (j < n && !(code[j] === "*" && code[j + 1] === "/")) j++;
+        end = Math.min(n, j + 2);
+      } else if (c === '"' || c === "'" || c === "`") {
+        let j = i + 1;
+        while (j < n) {
+          if (code[j] === "\\") {
+            j += 2;
+            continue;
+          }
+          if (code[j] === c) {
+            j++;
+            break;
+          }
+          j++;
+        }
+        end = j;
+      }
+      if (end >= 0) {
+        // Comment/string region [i, end). `q >= i` here (loop condition).
+        if (q < end) {
+          skipStart = i;
+          skipEnd = end;
+          return false;
+        }
+        i = end;
+      } else {
+        i++;
+      }
+    }
+    return true; // reached q in code mode
+  };
+}
+
+/**
+ * Index of the first match of `pattern` that occurs in code (not in a comment
+ * or string), or -1. `pattern` MUST be a global (`/g`) regex. Single native
+ * regex sweep with early-exit; O(1) extra memory.
+ */
+export function firstCodeMatchIndex(code: string, pattern: RegExp): number {
+  const inCode = makeCodeClassifier(code);
+  pattern.lastIndex = 0;
+  let m: RegExpExecArray | null;
+  while ((m = pattern.exec(code)) !== null) {
+    if (inCode(m.index)) return m.index;
+    if (pattern.lastIndex <= m.index) pattern.lastIndex = m.index + 1;
+  }
+  return -1;
+}
+
+/**
+ * Byte offsets of every match of `pattern` that occurs in code (not in a
+ * comment or string). `pattern` MUST be a global (`/g`) regex. Each offset is
+ * the match start — the same byte offset a raw `pattern.exec` reports. O(n)
+ * time, O(#matches) memory.
+ */
+export function codeMatchIndices(code: string, pattern: RegExp): number[] {
+  const inCode = makeCodeClassifier(code);
+  const indices: number[] = [];
+  pattern.lastIndex = 0;
+  let m: RegExpExecArray | null;
+  while ((m = pattern.exec(code)) !== null) {
+    if (inCode(m.index)) indices.push(m.index);
+    if (pattern.lastIndex <= m.index) pattern.lastIndex = m.index + 1;
+  }
+  return indices;
+}

package/src/build/runtime-discovery.ts

@@ -1,8 +1,9 @@
-import { dirname, join, basename, resolve } from "node:path";
+import { resolve } from "node:path";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import {
   generateRouteTypesSource,
-  buildCombinedRouteMapForRouterFile,
+  genFileTsPath,
+  resolveSearchSchemas,
 } from "./generate-route-types.ts";
 import { isAutoGeneratedRouteName } from "../route-name.js";
 
@@ -175,25 +176,13 @@ export async function discoverAndWriteRouteTypes(
         );
       }
 
-      // Search schema fallback: runtime manifest may omit search schema metadata
-      // in some module-runner flows. Fall back to static source parsing.
-      if (!routeSearchSchemas || Object.keys(routeSearchSchemas).length === 0) {
-        const staticParsed = buildCombinedRouteMapForRouterFile(sourceFile);
-        if (Object.keys(staticParsed.searchSchemas).length > 0) {
-          const filtered: Record<string, Record<string, string>> = {};
-          for (const name of Object.keys(routeManifest)) {
-            const schema = staticParsed.searchSchemas[name];
-            if (schema) filtered[name] = schema;
-          }
-          if (Object.keys(filtered).length > 0) {
-            routeSearchSchemas = filtered;
-          }
-        }
-      }
+      routeSearchSchemas = resolveSearchSchemas(
+        Object.keys(routeManifest),
+        routeSearchSchemas,
+        sourceFile,
+      );
 
-      const routerDir = dirname(sourceFile);
-      const routerBasename = basename(sourceFile).replace(/\.(tsx?|jsx?)$/, "");
-      const outPath = join(routerDir, `${routerBasename}.named-routes.gen.ts`);
+      const outPath = genFileTsPath(sourceFile);
 
       const source = generateRouteTypesSource(
         routeManifest,

package/src/cache/cache-error.ts

@@ -0,0 +1,104 @@
+/**
+ * Cache error reporting.
+ *
+ * Caches are best-effort: a read failure degrades to a miss (render fresh) and a
+ * write failure degrades to a no-op - they MUST NOT throw up and fail the
+ * request. But the failure must still be LOUD: it is logged to the console (so
+ * it is visible even in a background waitUntil task or when no hook is wired)
+ * AND routed through the router's onError callback (via the request context's
+ * deduped _reportBackgroundError) so consumers can observe cache degradation in
+ * their own telemetry.
+ *
+ * The one deliberate exception is the invalidation WRITE verb (updateTag ->
+ * store.invalidateTags): a failed durable marker write is rejected so an awaited
+ * updateTag() surfaces it (read-your-own-writes honesty). That is not a data
+ * read/write and does not go through this helper's swallow-and-degrade path.
+ */
+
+import { _getRequestContext } from "../server/request-context.js";
+
+/**
+ * Minimal shape of a request context for error reporting. Passed explicitly by
+ * background tasks (waitUntil) where the ALS context is already gone, so the
+ * error can still reach the router's onError. Structural to avoid importing the
+ * full RequestContext type (request-context.ts imports CacheErrorCategory from
+ * here - a mutual type-only reference).
+ */
+export interface CacheErrorReporter {
+  _reportBackgroundError?: (
+    error: unknown,
+    category: CacheErrorCategory,
+  ) => void;
+}
+
+export type CacheErrorCategory =
+  /** A read failed (transient infra: KV/Cache API error). Degrade to a miss. */
+  | "cache-read"
+  /** A write failed. Degrade to a no-op (entry simply not cached). */
+  | "cache-write"
+  /** A delete/eviction failed. Best-effort. */
+  | "cache-delete"
+  /**
+   * A STORED entry could not be parsed/deserialized (partial KV read, truncated
+   * Cache API body, malformed envelope/RSC payload). The entry is faulty and is
+   * evicted so subsequent reads do not keep failing on it. Distinct from
+   * cache-read so consumers can tell corruption from a transient outage.
+   */
+  | "cache-corrupt"
+  /** A tag-invalidation side effect failed (e.g. the eager CDN purge hook). */
+  | "cache-invalidate"
+  /**
+   * A background stale-while-revalidate refresh failed (the `"use cache"`
+   * read-through path). The stale value was already served; the refresh that
+   * would have replaced it errored.
+   */
+  | "stale-revalidation";
+
+/**
+ * Report a non-fatal cache error loudly without failing the request: always logs
+ * (label + error) and, when a request context is available, routes the error
+ * through the router's onError callback. Never throws.
+ *
+ * `ctx` is for callers running in a detached background task (waitUntil), where
+ * the ALS request context is already gone (so `_getRequestContext()` is null):
+ * they capture the context up front and pass it here so onError still fires.
+ * Foreground callers omit it and fall back to the ALS context.
+ */
+export function reportCacheError(
+  error: unknown,
+  category: CacheErrorCategory,
+  label: string,
+  ctx?: CacheErrorReporter,
+): void {
+  console.error(`${label}:`, error);
+  try {
+    const target = ctx ?? _getRequestContext();
+    target?._reportBackgroundError?.(error, category);
+  } catch {
+    // Reporting must never itself break the cache path.
+  }
+}
+
+/**
+ * Run a best-effort async cache task (typically scheduled via waitUntil), catching
+ * any rejection and routing it through reportCacheError so background cache work
+ * (non-blocking L1 writes, KV persistence, L1 promotion) reports failures via
+ * onError instead of throwing or silently swallowing. Never rejects.
+ *
+ * Pass `ctx` when the task runs detached (the ALS context is gone) and the
+ * failure should still reach onError; omit it to fall back to the ALS context.
+ *
+ * @example this.waitUntil(() => reportingAsync(() => cache.put(req, res), "cache-write", "[CFCacheStore] L1 write"))
+ */
+export async function reportingAsync(
+  task: () => Promise<unknown>,
+  category: CacheErrorCategory,
+  label: string,
+  ctx?: CacheErrorReporter,
+): Promise<void> {
+  try {
+    await task();
+  } catch (error) {
+    reportCacheError(error, category, label, ctx);
+  }
+}

package/src/cache/cache-policy.ts

@@ -9,6 +9,7 @@
 import type { CacheDefaults, SegmentCacheStore } from "./types.js";
 import { _getRequestContext } from "../server/request-context.js";
 import type { RequestContext } from "../server/request-context.js";
+import { normalizeTags } from "./cache-tag.js";
 
 /**
  * Default TTL for route-level cache() DSL and loader cache.
@@ -68,24 +69,6 @@ export function computeExpiration(
   return { staleAt, expiresAt };
 }
 
-// ============================================================================
-// Cache Key Resolution
-// ============================================================================
-
-/**
- * Resolve cache key using the 3-tier priority:
- * 1. keyFn (full override from route/loader cache options)
- * 2. store.keyGenerator (modifies default key)
- * 3. defaultKey (used when neither keyFn nor keyGenerator is provided)
- *
- * Errors from keyFn and store.keyGenerator propagate to the caller.
- * Cache identity is correctness-critical: if explicit key logic throws,
- * silently remapping to a different key could cause cache collisions or
- * serve stale/wrong data. Callers must handle the error or let it surface.
- *
- * Uses _getRequestContext (non-throwing) so that calls outside ALS
- * (e.g. build-time) gracefully fall back to defaultKey.
- */
 export async function resolveCacheKey(
   keyFn: ((ctx: RequestContext) => string | Promise<string>) | undefined,
   store: SegmentCacheStore | null,
@@ -94,32 +77,89 @@ export async function resolveCacheKey(
 ): Promise<string> {
   const requestCtx = _getRequestContext();
 
-  // Priority 1: Route/loader-level key function (full override)
   if (keyFn && requestCtx) {
     return await keyFn(requestCtx);
   }
 
-  // Priority 2: Store-level keyGenerator (modifies default key)
   if (store?.keyGenerator && requestCtx) {
     return await store.keyGenerator(requestCtx, defaultKey);
   }
 
-  // Priority 3: Default key (no custom key logic provided)
   return defaultKey;
 }
 
-// ============================================================================
-// Cache Store Resolution
-// ============================================================================
+export function resolveTagsOption<TEnv>(
+  tags: string[] | ((ctx: RequestContext<TEnv>) => string[]) | undefined,
+  ctx: RequestContext<TEnv> | undefined,
+  label: string,
+): string[] | undefined {
+  if (!tags) return undefined;
+  if (typeof tags === "function") {
+    if (!ctx) {
+      console.warn(
+        `[${label}] Dynamic tags function present but no request context; ` +
+          `caching without tags (this entry will not be tag-invalidatable).`,
+      );
+      return undefined;
+    }
+    try {
+      return normalizeTagList(tags(ctx));
+    } catch (error) {
+      console.error(
+        `[${label}] Tags function failed, caching without tags:`,
+        error,
+      );
+      return undefined;
+    }
+  }
+  return normalizeTagList(tags);
+}
 
 /**
- * Resolve cache store from the 2-tier priority:
- * 1. Explicit store from cache options
- * 2. App-level store from request context
+ * Normalize a resolved tags array so the WRITE path matches the invalidate path:
+ * updateTag()/revalidateTag()/cacheTag() all drop empty/whitespace-only tags via
+ * normalizeTag(). Without this, an empty tag attached at write time would enter
+ * the store index but could never be invalidated (the verbs normalize it away),
+ * and on CFCacheStore would also cost a wasted KV marker read per request.
+ * Returns undefined when nothing usable remains, keeping the entry header-free.
  */
+function normalizeTagList(tags: string[]): string[] | undefined {
+  const out = normalizeTags(tags);
+  return out.length > 0 ? out : undefined;
+}
+
 export function resolveCacheStore(
   explicitStore: SegmentCacheStore | undefined,
 ): SegmentCacheStore | null {
-  if (explicitStore) return explicitStore;
+  if (explicitStore) {
+    registerExplicitTaggedStore(explicitStore);
+    return explicitStore;
+  }
   return _getRequestContext()?._cacheStore ?? null;
 }
+
+/**
+ * Upper bound on the per-handler explicit-store registry. A module-singleton
+ * store (the recommended pattern) dedupes to a single entry and never approaches
+ * this. The cap bounds the niche case of an explicit store constructed PER
+ * request/boundary (e.g. a ctx-bound CFCacheStore, which must take a per-request
+ * ctx): without it the registry - which intentionally persists across requests so
+ * a server action's updateTag() can reach stores a prior render registered -
+ * would accumulate one dead instance per request and fan invalidation out to
+ * finished execution contexts. LRU-touch on re-resolution keeps a live, re-used
+ * store from being evicted by that churn.
+ */
+const EXPLICIT_STORE_REGISTRY_CAP = 64;
+
+function registerExplicitTaggedStore(store: SegmentCacheStore): void {
+  const set = _getRequestContext()?._explicitTaggedStores;
+  if (!set) return;
+  // LRU touch: move an already-present store to the most-recent position (Set
+  // preserves insertion order) so a store re-resolved every request stays live.
+  set.delete(store);
+  set.add(store);
+  if (set.size > EXPLICIT_STORE_REGISTRY_CAP) {
+    const oldest = set.values().next().value;
+    if (oldest !== undefined) set.delete(oldest);
+  }
+}

package/src/cache/cache-runtime.ts

@@ -21,6 +21,7 @@ import {
   createClientTemporaryReferenceSet,
 } from "@vitejs/plugin-rsc/rsc";
 import { getRequestContext } from "../server/request-context.js";
+import { isUnderTestRunner } from "../runtime-env.js";
 import {
   isTainted,
   CACHED_FN_SYMBOL,
@@ -32,10 +33,21 @@ import {
 export { isCachedFunction };
 import { serializeResult, deserializeResult } from "./segment-codec.js";
 import { createHandleStore } from "../server/handle-store.js";
-import { restoreHandles } from "./handle-snapshot.js";
+import {
+  restoreHandles,
+  encodeHandles,
+  decodeHandles,
+} from "./handle-snapshot.js";
 import { startHandleCapture, type HandleCapture } from "./handle-capture.js";
 import { sortedSearchString } from "./cache-key-utils.js";
 import { runBackground } from "./background-task.js";
+import {
+  normalizeTags,
+  recordRequestTags,
+  runWithCacheTagScope,
+} from "./cache-tag.js";
+import { reportCacheError } from "./cache-error.js";
+import type { CacheItemResult } from "./types.js";
 
 /**
  * Convert encodeReply result to a stable string key.
@@ -48,6 +60,10 @@ async function replyToCacheKey(encoded: string | FormData): Promise<string> {
   return text;
 }
 
+// Cached-fn ids already warned about running uncached under a test runner, so
+// the test-ergonomics warning fires once per fn rather than once per call.
+const warnedUncachedUnderTest = new Set<string>();
+
 // ============================================================================
 // Core: registerCachedFunction
 // ============================================================================
@@ -70,9 +86,38 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     const store = requestCtx?._cacheStore;
     const resolvedProfileName = profileName || "default";
 
-    // Bypass: no store or no getItem support
+    // Bypass: no store or no getItem support. Still run inside a tag scope so a
+    // cacheTag() call inside the function degrades to a no-op rather than
+    // throwing "must be called inside a use cache function" - adopting cacheTag()
+    // must not hard-fail in apps/tests without an item-capable cache configured.
+    // Note: the INSIDE_CACHE_EXEC guard (cookies()/headers()/ctx.set() rejection)
+    // is intentionally NOT stamped here. It is a cached-path-only check; in the
+    // bypass the body actually executes, so the guarded side effects take effect
+    // and nothing is lost on a (non-existent) hit. Same applies to the
+    // non-serializable-args bypass below.
     if (!store?.getItem) {
-      return fn.apply(this, args);
+      // Test-ergonomics guard: under a test runner, a "use cache" function that
+      // executes with no item-capable store seeded is exercising the UNCACHED
+      // path — a green test that proves nothing about caching. Warn once per fn
+      // id so the author knows to seed a cacheStore. Advisory (never throws), so
+      // a test that DELIBERATELY runs uncached is unaffected. Gated on the test
+      // runner (process.env.VITEST, not folded) so production never evaluates it.
+      if (isUnderTestRunner() && !warnedUncachedUnderTest.has(id)) {
+        warnedUncachedUnderTest.add(id);
+        console.warn(
+          `[rango] "use cache" function "${id}" executed but no cacheStore was ` +
+            `seeded; the cached path is NOT under test (it ran uncached). Pass ` +
+            `{ cacheStore, cacheProfiles } to runLoader/runMiddleware/renderHandler/` +
+            `runInRequestContext (or configure createRouter({ cache }) for dispatch) ` +
+            `to exercise it.`,
+        );
+      }
+      const scoped = runWithCacheTagScope(() => fn.apply(this, args));
+      const result = await scoped.result;
+      // Still record the runtime tags into the request set so a cacheTag() in an
+      // uncached function tags the document, even with no item-capable store.
+      recordRequestTags(scoped.tags, requestCtx);
+      return result;
     }
 
     // Resolve profile strictly from request-scoped config (set by the
@@ -155,40 +200,57 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
         cacheKey = `use-cache:${id}`;
       }
     } catch {
-      // Non-serializable args: run uncached
-      return fn.apply(this, args);
+      // Non-serializable args: run uncached (within a tag scope so cacheTag()
+      // still does not throw). Record runtime tags so the document union still
+      // sees them even though this call is not itself cached.
+      const scoped = runWithCacheTagScope(() => fn.apply(this, args));
+      const result = await scoped.result;
+      recordRequestTags(scoped.tags, requestCtx);
+      return result;
     }
 
     // Cache lookup
     const cached = await store.getItem(cacheKey);
 
+    // Serve a cached entry on the hit path: deserialize the stored value,
+    // replay handle data (gated on tainted args), and surface the entry's tags
+    // to the request set (the function did not re-run, so its runtime cacheTag()
+    // tags are only available from the stored entry). Shared by the fresh-hit
+    // and stale-hit branches; the only divergence is the stale branch scheduling
+    // background revalidation, which it does after this returns.
+    const serveCached = async (entry: CacheItemResult): Promise<any> => {
+      const result = await deserializeResult(entry.value);
+      if (entry.handles && hasTaintedArgs) {
+        const handleStore = requestCtx?._handleStore;
+        if (handleStore) {
+          const r = await decodeHandles(entry.handles);
+          if (r) restoreHandles(r, handleStore);
+        }
+      }
+      recordRequestTags(entry.tags, requestCtx);
+      return result;
+    };
+
     if (cached && !cached.shouldRevalidate) {
       // Fresh hit: deserialize and return
       try {
-        const result = await deserializeResult(cached.value);
-        // Restore handle data if present
-        if (cached.handles && hasTaintedArgs) {
-          const handleStore = requestCtx?._handleStore;
-          if (handleStore) {
-            restoreHandles(cached.handles, handleStore);
-          }
-        }
-        return result;
-      } catch {
-        // Deserialization failed, fall through to fresh execution
+        return await serveCached(cached);
+      } catch (error) {
+        // The stored value is corrupt/partial (failed RSC deserialize). Report
+        // it, then fall through to fresh execution - the miss path below re-runs
+        // and setItem() overwrites the faulty entry under the same key (self-heal).
+        reportCacheError(
+          error,
+          "cache-corrupt",
+          `[use cache] "${id}" fresh-hit`,
+        );
       }
     }
 
     if (cached?.shouldRevalidate) {
       // Stale hit: return stale value, revalidate in background
       try {
-        const result = await deserializeResult(cached.value);
-        if (cached.handles && hasTaintedArgs) {
-          const handleStore = requestCtx?._handleStore;
-          if (handleStore) {
-            restoreHandles(cached.handles, handleStore);
-          }
-        }
+        const result = await serveCached(cached);
         // Background revalidation — must capture handles if tainted args present.
         // Use an isolated handle store so background pushes don't pollute the
         // live response or throw LateHandlePushError on the completed store.
@@ -238,20 +300,41 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
           }
 
           try {
-            const freshResult = await fn.apply(this, args);
+            const scoped = runWithCacheTagScope(() => fn.apply(this, args));
+            const freshResult = await scoped.result;
             bgStopCapture?.();
+            // Merge profile/DSL tags with runtime cacheTag() tags, read after
+            // awaiting so post-await cacheTag() calls are included. Normalize
+            // (drops empty profile tags, matching the invalidate path) + dedupe.
+            const freshTags = [
+              ...new Set(
+                normalizeTags([...(profile.tags ?? []), ...scoped.tags]),
+              ),
+            ];
+            recordRequestTags(freshTags, requestCtx);
             const serialized = await serializeResult(freshResult);
             if (serialized !== null) {
+              const encodedHandles = bgCapture?.data
+                ? await encodeHandles(bgCapture.data)
+                : undefined;
               await store.setItem!(cacheKey, serialized, {
-                handles: bgCapture?.data,
+                handles: encodedHandles,
                 ttl: profile.ttl,
                 swr: profile.swr,
-                tags: profile.tags,
+                tags: freshTags.length > 0 ? freshTags : undefined,
               });
             }
           } catch (bgError) {
             bgStopCapture?.();
-            requestCtx?._reportBackgroundError?.(bgError, "stale-revalidation");
+            // Pass requestCtx explicitly: this runs in a detached background
+            // task where the ALS context is gone, so onError can only fire if
+            // we hand it the context captured up front.
+            reportCacheError(
+              bgError,
+              "stale-revalidation",
+              "[use cache] background revalidation failed",
+              requestCtx,
+            );
           } finally {
             for (const arg of bgTaintedArgs) {
               unstampCacheExec(arg as object);
@@ -263,8 +346,14 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
           }
         });
         return result;
-      } catch {
-        // Deserialization of stale value failed, fall through
+      } catch (error) {
+        // Stale value is corrupt/partial; report and fall through to a fresh
+        // execution, which overwrites the faulty entry under the same key.
+        reportCacheError(
+          error,
+          "cache-corrupt",
+          `[use cache] "${id}" stale-hit`,
+        );
       }
     }
 
@@ -297,8 +386,10 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     }
 
     let result: any;
+    let scoped: ReturnType<typeof runWithCacheTagScope>;
     try {
-      result = await fn.apply(this, args);
+      scoped = runWithCacheTagScope(() => fn.apply(this, args));
+      result = await scoped.result;
     } finally {
       // Decrement ref count; symbol is deleted when it reaches zero
       for (const arg of taintedArgs) {
@@ -311,17 +402,28 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
       stopCapture?.();
     }
 
+    // Merge profile/DSL tags with runtime cacheTag() tags. Read scoped.tags
+    // after awaiting result so post-await cacheTag() calls are included.
+    // Normalize (drops empty profile tags, matching the invalidate path) + dedupe.
+    const allTags = [
+      ...new Set(normalizeTags([...(profile.tags ?? []), ...scoped!.tags])),
+    ];
+    recordRequestTags(allTags, requestCtx);
+
     // Serialize and store — fully non-blocking when waitUntil is available.
     // The response does not need to wait for serialization or the store write.
     const cacheWrite = async () => {
       try {
         const serialized = await serializeResult(result);
         if (serialized !== null) {
+          const encodedHandles = capture?.data
+            ? await encodeHandles(capture.data)
+            : undefined;
           await store.setItem!(cacheKey, serialized, {
-            handles: capture?.data,
+            handles: encodedHandles,
             ttl: profile.ttl,
             swr: profile.swr,
-            tags: profile.tags,
+            tags: allTags.length > 0 ? allTags : undefined,
           });
         }
       } catch (writeError) {