@rangojs/router 0.0.0-experimental.141 → 0.0.0-experimental.143

package/src/cache/vercel/vercel-cache-store.ts

@@ -156,7 +156,7 @@ interface VercelResponseEnvelope {
   s: number;
   /** expiresAt (ms since epoch). */
   e: number;
-  /** Tags, preserved so a stale re-stamp keeps them. */
+  /** Tags, preserved so a background revalidation re-write keeps them. */
   t?: string[];
 }
 
@@ -174,7 +174,7 @@ interface VercelShellEnvelope {
   s: number;
   /** expiresAt (ms since epoch). */
   e: number;
-  /** Tags, preserved so a stale re-stamp keeps them. */
+  /** Tags, preserved so a background revalidation re-write keeps them. */
   t?: string[];
   /** initialTheme the capture render was built with (resume theme fidelity). */
   i?: string;
@@ -226,9 +226,9 @@ export interface VercelCacheStoreOptions<TEnv = unknown> {
   cache: VercelRuntimeCache;
 
   /**
-   * `waitUntil` from `@vercel/functions`. Used only to run the stale-read
-   * re-stamp (herd dampening) off the response path - the router already
-   * backgrounds the actual writes. When omitted, the re-stamp runs detached
+   * `waitUntil` from `@vercel/functions`. Used only to run the stale-read lock
+   * write (herd dampening) off the response path - the router already
+   * backgrounds the actual writes. When omitted, the lock write runs detached
    * (fire-and-forget) instead.
    */
   waitUntil?: (promise: Promise<unknown>) => void;
@@ -393,7 +393,7 @@ export class VercelCacheStore<
       this.emitDebug({ op: "get", key, outcome: "miss", readMs });
       return null;
     }
-    const env = this.asSegmentEnvelope(raw);
+    const env = this.asSegmentEnvelope(this.decodeRaw(raw));
     if (!env) {
       reportCacheError(
         new Error("malformed segment envelope"),
@@ -420,35 +420,19 @@ export class VercelCacheStore<
     }
 
     const isStale = env.s > 0 && now > env.s;
-    if (isStale) {
-      this.markRevalidating(
-        storeKey,
-        env,
-        env.d.tags,
-        "[VercelCacheStore] get",
-      );
-      this.emitDebug({
-        op: "get",
-        key,
-        outcome: "stale-revalidate",
-        shouldRevalidate: true,
-        staleAt: env.s,
-        expiresAt: env.e,
-        readMs,
-      });
-      return { data: env.d, shouldRevalidate: true };
-    }
-
+    const shouldRevalidate = isStale
+      ? await this.claimRevalidation(storeKey, env.e, "[VercelCacheStore] get")
+      : false;
     this.emitDebug({
       op: "get",
       key,
-      outcome: "fresh",
-      shouldRevalidate: false,
+      outcome: shouldRevalidate ? "stale-revalidate" : "fresh",
+      shouldRevalidate,
       staleAt: env.s,
       expiresAt: env.e,
       readMs,
     });
-    return { data: env.d, shouldRevalidate: false };
+    return { data: env.d, shouldRevalidate };
   }
 
   async set(
@@ -462,8 +446,7 @@ export class VercelCacheStore<
       const { staleAt, expiresAt } = computeExpiration(ttl, swrWindow);
       // Embed the CLAMPED tags, like putResponse/setItem: the segment family
       // carries its tags inside `d`, and a raw list would resurface dropped
-      // tags into recordRequestTags on every hit AND get re-clamped (with a
-      // spurious cache-write report) by markRevalidating on every stale read.
+      // tags into recordRequestTags on every hit.
       const safeTags = this.clampTagsForWrite(
         data.tags,
         "[VercelCacheStore] set",
@@ -517,7 +500,7 @@ export class VercelCacheStore<
       this.emitDebug({ op: "getResponse", key, outcome: "miss", readMs });
       return null;
     }
-    const env = this.asResponseEnvelope(raw);
+    const env = this.asResponseEnvelope(this.decodeRaw(raw));
     if (!env) {
       reportCacheError(
         new Error("malformed response envelope"),
@@ -543,11 +526,11 @@ export class VercelCacheStore<
       return null;
     }
 
-    // Reconstruct the Response BEFORE marking revalidating. A corrupt body (e.g.
-    // invalid base64 from base64ToBuffer, or bad header entries) would otherwise
-    // throw out of getResponse — breaking the fail-open contract — and a stale
-    // re-stamp would re-persist the bad value. Treat a reconstruction failure as
-    // a corrupt entry: report, evict, and miss.
+    // Reconstruct the Response BEFORE claiming revalidation. A corrupt body
+    // (e.g. invalid base64 from base64ToBuffer, or bad header entries) would
+    // otherwise throw out of getResponse — breaking the fail-open contract — and
+    // a stale read would have written a lock for an entry it then evicts. Treat a
+    // reconstruction failure as a corrupt entry: report, evict, and miss.
     let response: Response;
     try {
       response = new Response(base64ToBuffer(env.b), {
@@ -566,24 +549,23 @@ export class VercelCacheStore<
     }
 
     const isStale = env.s > 0 && now > env.s;
-    if (isStale) {
-      this.markRevalidating(
-        storeKey,
-        env,
-        env.t,
-        "[VercelCacheStore] getResponse",
-      );
-    }
+    const shouldRevalidate = isStale
+      ? await this.claimRevalidation(
+          storeKey,
+          env.e,
+          "[VercelCacheStore] getResponse",
+        )
+      : false;
     this.emitDebug({
       op: "getResponse",
       key,
-      outcome: isStale ? "stale-revalidate" : "fresh",
-      shouldRevalidate: isStale,
+      outcome: shouldRevalidate ? "stale-revalidate" : "fresh",
+      shouldRevalidate,
       staleAt: env.s,
       expiresAt: env.e,
       readMs,
     });
-    return { response, shouldRevalidate: isStale };
+    return { response, shouldRevalidate };
   }
 
   async putResponse(
@@ -650,7 +632,7 @@ export class VercelCacheStore<
       this.emitDebug({ op: "getItem", key, outcome: "miss", readMs });
       return null;
     }
-    const env = this.asItemEnvelope(raw);
+    const env = this.asItemEnvelope(this.decodeRaw(raw));
     if (!env) {
       reportCacheError(
         new Error("malformed item envelope"),
@@ -677,14 +659,18 @@ export class VercelCacheStore<
     }
 
     const isStale = env.s > 0 && now > env.s;
-    if (isStale) {
-      this.markRevalidating(storeKey, env, env.t, "[VercelCacheStore] getItem");
-    }
+    const shouldRevalidate = isStale
+      ? await this.claimRevalidation(
+          storeKey,
+          env.e,
+          "[VercelCacheStore] getItem",
+        )
+      : false;
     this.emitDebug({
       op: "getItem",
       key,
-      outcome: isStale ? "stale-revalidate" : "fresh",
-      shouldRevalidate: isStale,
+      outcome: shouldRevalidate ? "stale-revalidate" : "fresh",
+      shouldRevalidate,
       staleAt: env.s,
       expiresAt: env.e,
       readMs,
@@ -692,7 +678,7 @@ export class VercelCacheStore<
     return {
       value: env.v,
       handles: env.h,
-      shouldRevalidate: isStale,
+      shouldRevalidate,
       tags: env.t,
     };
   }
@@ -752,7 +738,7 @@ export class VercelCacheStore<
       this.emitDebug({ op: "getShell", key, outcome: "miss", readMs });
       return null;
     }
-    const env = this.asShellEnvelope(raw);
+    const env = this.asShellEnvelope(this.decodeRaw(raw));
     if (!env) {
       reportCacheError(
         new Error("malformed shell envelope"),
@@ -779,19 +765,18 @@ export class VercelCacheStore<
     }
 
     const isStale = env.s > 0 && now > env.s;
-    if (isStale) {
-      this.markRevalidating(
-        storeKey,
-        env,
-        env.t,
-        "[VercelCacheStore] getShell",
-      );
-    }
+    const shouldRevalidate = isStale
+      ? await this.claimRevalidation(
+          storeKey,
+          env.e,
+          "[VercelCacheStore] getShell",
+        )
+      : false;
     this.emitDebug({
       op: "getShell",
       key,
-      outcome: isStale ? "stale-revalidate" : "fresh",
-      shouldRevalidate: isStale,
+      outcome: shouldRevalidate ? "stale-revalidate" : "fresh",
+      shouldRevalidate,
       staleAt: env.s,
       expiresAt: env.e,
       readMs,
@@ -805,7 +790,7 @@ export class VercelCacheStore<
         snapshot: env.sn,
         createdAt: env.c,
       },
-      shouldRevalidate: isStale,
+      shouldRevalidate,
     };
   }
 
@@ -901,68 +886,107 @@ export class VercelCacheStore<
     tags: string[] | undefined,
     label: string,
   ): Promise<void> {
-    if (!this.withinSizeLimit(value, label)) return;
+    // Serialize the envelope exactly ONCE: the same string measures the entry
+    // against the size cap AND is what we hand the platform. The Vercel client
+    // JSON-serializes whatever value it is given, so passing the raw object here
+    // would walk and stringify the (potentially large) envelope a SECOND time.
+    // Entries written this way are JSON strings; the read path (decodeRaw)
+    // parses them back, and still accepts the legacy object shape written before
+    // this change.
+    let serialized: string | undefined;
+    try {
+      serialized = JSON.stringify(value);
+    } catch {
+      // Unserializable value: fall back to letting the platform serialize it
+      // (best-effort — matches the prior "cannot measure -> allow the write").
+      serialized = undefined;
+    }
+    if (serialized !== undefined && !this.withinSizeLimit(serialized, label)) {
+      return;
+    }
     const safeTags = this.clampTagsForWrite(tags, label);
     const options: { ttl: number; tags?: string[]; name?: string } = {
       ttl: Math.max(1, Math.ceil(totalTtlSeconds)),
     };
     if (safeTags.length > 0) options.tags = safeTags;
     if (this.name) options.name = this.name;
-    await this.cache.set(storeKey, value, options);
+    await this.cache.set(storeKey, serialized ?? value, options);
   }
 
   /**
-   * Stale-read herd dampening: push staleAt forward by REVALIDATION_LOCK_MS
-   * (clamped to the hard expiry) and re-write the same envelope under the
-   * remaining lifetime, so concurrent same-region readers see it as fresh while
-   * one revalidates. Best-effort and non-blocking; never throws.
+   * Normalize a value read back from the cache. Entries written by this store
+   * are pre-serialized JSON strings (see write()); legacy entries (written
+   * before that change, or by a client that deserializes for us) come back as
+   * objects. Parse strings, pass objects through, and treat a non-JSON string
+   * as corrupt (returns undefined, so the caller reports + evicts).
+   */
+  private decodeRaw(raw: unknown): unknown {
+    if (typeof raw !== "string") return raw;
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return undefined;
+    }
+  }
+
+  /**
+   * Stale-read herd dampening via a tiny companion lock key. On a stale read,
+   * check `{storeKey}:lock`; if absent, claim it (write a short-TTL marker) and
+   * return true so THIS reader triggers revalidation. If present, another
+   * same-region reader already claimed it, so return false and serve the stale
+   * entry as fresh without piling on. Best-effort and non-blocking; never throws.
+   *
+   * Only the STALE path pays the extra lock read; the fresh-hit path takes no
+   * lock round trip. Unlike the prior whole-envelope re-stamp, a stale read now
+   * writes only the tiny lock, never the (potentially large) payload.
    *
-   * Two races are accepted here because `getCache` offers no compare-and-set: a
-   * fast background revalidation that lands between this stale read and the
-   * re-stamp write can be overwritten by the (staler) locked envelope, and an
-   * `expireTag` that deletes the entry in the same window can be resurrected by
-   * the re-stamp. Both self-heal within REVALIDATION_LOCK_MS (the re-stamped
-   * copy is then re-read as stale and revalidated again, or re-deleted). The
-   * window is narrow and the cost is at most one extra revalidation / one brief
-   * stale serve; a read-compare would not close it atomically without CAS.
+   * Non-atomic (getCache has no compare-and-set): two readers can both find no
+   * lock and both revalidate. The window is REVALIDATION_LOCK_MS wide, after
+   * which the lock expires and the entry is re-claimed (or a fresh write has
+   * superseded it). A read-compare would not close the race without CAS.
    */
-  private markRevalidating<E extends { s: number; e: number }>(
+  private async claimRevalidation(
     storeKey: string,
-    env: E,
-    tags: string[] | undefined,
+    expiresAt: number,
     label: string,
-  ): void {
-    const now = Date.now();
-    const remainingSeconds = Math.ceil((env.e - now) / 1000);
-    if (remainingSeconds <= 0) return;
-    const locked: E = {
-      ...env,
-      s: Math.min(now + REVALIDATION_LOCK_MS, env.e),
-    };
+  ): Promise<boolean> {
+    const lockKey = `${storeKey}:lock`;
+    let lock: unknown;
+    try {
+      lock = await this.cache.get(lockKey);
+    } catch {
+      // A lock-read failure must not break the read path: treat as unlocked.
+      lock = null;
+    }
+    if (lock != null) return false;
+
+    const remainingSeconds = Math.ceil((expiresAt - Date.now()) / 1000);
+    const lockTtl = Math.max(
+      1,
+      Math.min(Math.ceil(REVALIDATION_LOCK_MS / 1000), remainingSeconds),
+    );
     const task = (): Promise<void> =>
-      this.write(storeKey, locked, remainingSeconds, tags, label);
+      this.cache.set(lockKey, 1, { ttl: lockTtl });
     if (this.waitUntil) {
       this.waitUntil(reportingAsync(task, "cache-write", label));
     } else {
       void reportingAsync(task, "cache-write", label);
     }
+    return true;
   }
 
-  private withinSizeLimit(value: unknown, label: string): boolean {
-    try {
-      const bytes = new TextEncoder().encode(JSON.stringify(value)).length;
-      if (bytes >= this.maxItemBytes) {
-        reportCacheError(
-          new Error(
-            `entry is ${bytes}B, at/above the ${this.maxItemBytes}B cap; not cached`,
-          ),
-          "cache-write",
-          label,
-        );
-        return false;
-      }
-    } catch {
-      // If the value cannot be measured, allow the write (best-effort).
+  /** Measure a pre-serialized entry against the per-item size cap (see write). */
+  private withinSizeLimit(serialized: string, label: string): boolean {
+    const bytes = new TextEncoder().encode(serialized).length;
+    if (bytes >= this.maxItemBytes) {
+      reportCacheError(
+        new Error(
+          `entry is ${bytes}B, at/above the ${this.maxItemBytes}B cap; not cached`,
+        ),
+        "cache-write",
+        label,
+      );
+      return false;
     }
     return true;
   }

package/src/cloudflare/tracing.ts

@@ -39,7 +39,7 @@ import { _getRequestContext } from "../server/request-context.js";
 import {
   type RouterTracingConfig,
   type SpanRunner,
-  type TracePhaseToggles,
+  type TracingToggleOptions,
   NOOP_TRACE_SPAN,
 } from "../router/tracing.js";
 
@@ -57,13 +57,12 @@ interface CloudflareTracing {
   enterSpan<T>(name: string, callback: (span: CloudflareSpan) => T): T;
 }
 
-/** Options for createCloudflareTracing. */
-export interface CloudflareTracingOptions {
-  /** Master switch. Defaults to true. */
-  enabled?: boolean;
-  /** Per-phase span toggles. Omitted phases default to enabled. */
-  spans?: TracePhaseToggles;
-}
+/**
+ * Options for createCloudflareTracing. Alias of the shared
+ * {@link TracingToggleOptions} (`enabled` master switch + per-phase `spans`
+ * toggles); the name is public API.
+ */
+export type CloudflareTracingOptions = TracingToggleOptions;
 
 /**
  * Resolve the per-request Cloudflare tracer from the active execution context.

package/src/index.rsc.ts

@@ -308,6 +308,7 @@ export type {
   RouterTracingConfig,
   TracePhase,
   TracePhaseToggles,
+  TracingToggleOptions,
 } from "./router/tracing.js";
 
 // Timeout types and error class

package/src/index.ts

@@ -343,14 +343,17 @@ export {
 // Path and response types are ambient on the `Rango` namespace (`Rango.Path`,
 // `Rango.PathResponse`, declared in href-client.ts) — no import needed.
 
-// Telemetry types only — the createConsoleSink/createOTelSink values are
-// server-only and live in index.rsc.ts (the `react-server` condition of the
-// bare `@rangojs/router` import). Re-exporting them as values from this
-// (default/client) entry would pull telemetry.ts and telemetry-otel.ts into
-// the client module graph; both tree-shake to zero bytes but still appear in
-// bundle analysis output and slow build-time module resolution. Consumers
-// who need the values in non-RSC contexts can import from
-// `@rangojs/router/server`.
+// Telemetry types only — the createConsoleSink / createOTelSink /
+// createOTelTracing VALUES are server-only and live in index.rsc.ts (the
+// `react-server` condition of the bare `@rangojs/router` import). Re-exporting
+// them as values from this (default/client) entry would pull telemetry.ts and
+// telemetry-otel.ts into the client module graph; both tree-shake to zero bytes
+// but still appear in bundle analysis output and slow build-time module
+// resolution. The factory values are NOT re-exported from `@rangojs/router/server`
+// either — that subpath is internal, not user-facing (see server.ts header).
+// Non-RSC server code imports these TYPES from the root and obtains the factory
+// VALUES from its own router definition module, which resolves to index.rsc.ts
+// under the `react-server` condition.
 export type {
   OTelTracer,
   OTelActiveSpanTracer,
@@ -386,6 +389,7 @@ export type {
   RouterTracingConfig,
   TracePhase,
   TracePhaseToggles,
+  TracingToggleOptions,
 } from "./router/tracing.js";
 
 // Timeout types and error class

package/src/route-definition/helpers-types.ts

@@ -149,8 +149,11 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    *              so they take precedence on `loading()` and other last-write-wins
    *              fields.
    */
-  parallel: <
-    TSlots extends Record<
+  // Not generic over the slots record: an inferred type parameter makes the
+  // object literal an inference site, which suppresses contextual typing of
+  // arrow slot handlers (`(ctx) => ...` was implicit any).
+  parallel: (
+    slots: Record<
       `@${string}`,
       | Handler<any, any, TEnv>
       | ReactNode
@@ -159,8 +162,6 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
           use?: () => UseItems<ParallelUseItem>;
         }
     >,
-  >(
-    slots: TSlots,
     use?: () => UseItems<ParallelUseItem>,
   ) => ParallelItem;
   /**

package/src/route-map-builder.ts

@@ -139,6 +139,7 @@ export function clearAllRouterData(): void {
   perRouterManifestMap.clear();
   perRouterTrieMap.clear();
   perRouterPrecomputedEntriesMap.clear();
+  authoritativeTrieRouters.clear();
 }
 
 export function setRouterManifest(
@@ -162,6 +163,23 @@ export function setRouterTrie(
   perRouterTrieMap.set(routerId, trie);
 }
 
+// Routers whose trie came from the COMPLETE build manifest (deserialized via
+// ensureRouterManifest). For these, a trie miss is a real 404 and findMatch
+// skips the regex fallback scan — the only remaining route-count-proportional
+// match path (#664). Dev rebuilds (manifest-init.ts, router-discovery HMR
+// pushes) deliberately never mark authoritative: the dev-only trie-gap warning
+// in find-match.ts depends on the fallback running on misses, and dev route
+// churn (HMR, dev-time routes) makes a stale-trie 404 unacceptable there.
+const authoritativeTrieRouters: Set<string> = new Set();
+
+export function markRouterTrieAuthoritative(routerId: string): void {
+  authoritativeTrieRouters.add(routerId);
+}
+
+export function isRouterTrieAuthoritative(routerId: string): boolean {
+  return authoritativeTrieRouters.has(routerId);
+}
+
 export function getRouterTrie(
   routerId: string,
 ): import("./build/route-trie.js").TrieNode | undefined {
@@ -204,7 +222,12 @@ export async function ensureRouterManifest(routerId: string): Promise<void> {
   if (loader) {
     const mod = await loader();
     if (mod.manifest) perRouterManifestMap.set(routerId, mod.manifest);
-    if (mod.trie) perRouterTrieMap.set(routerId, mod.trie);
+    if (mod.trie) {
+      perRouterTrieMap.set(routerId, mod.trie);
+      // A trie serialized into the build manifest comes from complete
+      // discovery — misses are authoritative 404s (see find-match.ts).
+      markRouterTrieAuthoritative(routerId);
+    }
     if (mod.precomputedEntries)
       perRouterPrecomputedEntriesMap.set(routerId, mod.precomputedEntries);
     routerManifestLoaders.delete(routerId);

package/src/router/find-match.ts

@@ -1,5 +1,8 @@
 import { tryTrieMatch } from "./trie-matching.js";
-import { getRouterTrie } from "../route-map-builder.js";
+import {
+  getRouterTrie,
+  isRouterTrieAuthoritative,
+} from "../route-map-builder.js";
 import {
   findMatch as findRouteMatch,
   isLazyEvaluationNeeded,
@@ -166,6 +169,17 @@ export function createFindMatch<TEnv = any>(
           };
           return cloneMatchResult(lastFindMatchResult);
         }
+      } else if (isRouterTrieAuthoritative(deps.routerId)) {
+        // Authoritative miss (#664): this trie was deserialized from the
+        // COMPLETE build manifest, so trailing-slash redirects are already
+        // trie-native hits and a miss means no route exists. Skip the regex
+        // fallback — the only route-count-proportional match path — and do
+        // not evaluate lazy includes for unmatched (bot-probe) traffic.
+        // Trie hits that need lazy splicing keep the fallback loop below
+        // (trieMatched === true never reaches this branch).
+        lastFindMatchPathname = pathname;
+        lastFindMatchResult = null;
+        return null;
       }
     }
 

package/src/router/instrument.ts

@@ -318,10 +318,10 @@ export function observeHandler<C, R>(
  * sink is configured.
  *
  * This is the canonical emitter for SYNCHRONOUS facts that fire inside the
- * request's ALS scope (handler errors, timeouts, origin rejections, revalidation
- * decisions). A few emitters deliberately stay on the lower-level
- * resolveSink + safeEmit because observeEvent's lazy, per-call
- * getRouterContext() read does not fit them — keep this the complete list:
+ * request's ALS scope (revalidation decisions, cache-lookup decisions). A few
+ * emitters deliberately stay on the lower-level resolveSink + safeEmit because
+ * observeEvent's lazy, per-call getRouterContext() read does not fit them — keep
+ * this the complete list:
  *   - router.ts wrapLoaderPromise (loader.start/end/error) and
  *     segment-resolution/streamed-handler-telemetry.ts (streamed handler.error)
  *     capture the sink + request id EAGERLY and emit from a fire-and-forget
@@ -330,6 +330,11 @@ export function observeHandler<C, R>(
  *     loop (request.start/end/error, cache.decision, ...).
  *   - segment-resolution/helpers.ts emits via a caller-provided report.telemetry
  *     sink rather than the ALS router context.
+ *   - rsc/handler.ts handleTimeoutResponse (request.timeout), the origin guard
+ *     (request.origin-rejected), and handleStore.onError (late-handle
+ *     handler.error) emit via router.telemetry directly — they run outside the
+ *     RouterContext ALS (only match()/matchPartial() enter it), so a
+ *     getRouterContext() read there throws and the event would vanish.
  */
 export function observeEvent(event: TelemetryEvent): void {
   // getRouterContext() either throws (real impl, outside a router context — e.g.

package/src/router/manifest.ts

@@ -82,10 +82,14 @@ export async function loadManifest(
     Store.mountIndex = mountIndex;
     Store.isSSR = isSSR;
     if (metricsStore) Store.metrics = metricsStore;
-    // Restore cached manifest into Store
-    for (const [k, v] of cached) {
-      Store.manifest.set(k, v);
-    }
+    // Alias the request-scoped Store to the cached Map instead of copying it
+    // entry-by-entry. At request time this Store is throwaway (no ambient
+    // RangoContext store spans classify->match->render, so getOrCreateStore
+    // returns a fresh detached store here), so nothing mutates it in place after
+    // loadManifest returns. The fresh path below REASSIGNS Store.manifest rather
+    // than clearing it in place, so a later fresh load sharing this Store cannot
+    // poison the cached Map.
+    Store.manifest = cached;
     pushMetric?.("manifest:cache-hit", cacheStart);
     return cached.get(routeKey)!;
   }
@@ -103,7 +107,11 @@ export async function loadManifest(
   pushMetric?.("manifest:store-setup", storeSetupStart);
 
   const clearStart = performance.now();
-  Store.manifest.clear();
+  // Reassign rather than clear() in place: a prior cache-hit may have aliased
+  // Store.manifest to a shared module-cache Map (see cache-hit branch above),
+  // and clearing it in place would poison that cache. A fresh Map isolates this
+  // build; the cache still receives an independent copy at the end.
+  Store.manifest = new Map();
   pushMetric?.("manifest:clear", clearStart);
 
   try {