@timber-js/app 0.2.0-alpha.207 → 0.2.0-alpha.209

package/src/cache/tag-aware-handler.ts

@@ -26,7 +26,19 @@ const DATA_PREFIX = 'd:';
 const TAG_SET_PREFIX = 'ts:';
 const TAG_VERSION_PREFIX = 'tv:';
 
-type Strategy = 'native' | 'eager' | 'lazy';
+/** A store whose optional capability methods are known to be present. */
+type StoreWith<K extends keyof CacheStore> = CacheStore & Required<Pick<CacheStore, K>>;
+type NativeStore = StoreWith<'setWithTags' | 'invalidateTag'>;
+type EagerStore = StoreWith<'sadd' | 'smembers' | 'srem' | 'sdel'>;
+
+/**
+ * The detected strategy carries the store narrowed to the capabilities that
+ * strategy relies on, so each branch calls those methods without assertions.
+ */
+type Strategy =
+  | { kind: 'native'; store: NativeStore }
+  | { kind: 'eager'; store: EagerStore }
+  | { kind: 'lazy' };
 
 /** Stored entry format for eager strategy. */
 interface EagerEntry {
@@ -43,10 +55,18 @@ interface LazyEntry {
   tagVersions: Record<string, number>;
 }
 
+function isNativeStore(store: CacheStore): store is NativeStore {
+  return !!(store.setWithTags && store.invalidateTag);
+}
+
+function isEagerStore(store: CacheStore): store is EagerStore {
+  return !!(store.sadd && store.smembers && store.srem && store.sdel);
+}
+
 function detectStrategy(store: CacheStore): Strategy {
-  if (store.setWithTags && store.invalidateTag) return 'native';
-  if (store.sadd && store.smembers && store.srem && store.sdel) return 'eager';
-  return 'lazy';
+  if (isNativeStore(store)) return { kind: 'native', store };
+  if (isEagerStore(store)) return { kind: 'eager', store };
+  return { kind: 'lazy' };
 }
 
 export class TagAwareCacheHandler implements CacheHandler {
@@ -85,7 +105,7 @@ export class TagAwareCacheHandler implements CacheHandler {
     const raw = await this.store.get(this.dataKey(key));
     if (raw === null) return null;
 
-    if (this.strategy === 'native' || this.strategy === 'eager') {
+    if (this.strategy.kind !== 'lazy') {
       const entry = JSON.parse(raw) as EagerEntry;
       const stale = Date.now() > entry.expiresAt;
       return { value: entry.value, stale };
@@ -111,8 +131,9 @@ export class TagAwareCacheHandler implements CacheHandler {
     opts: { ttl: number; tags: string[]; generation?: number }
   ): Promise<void> {
     const physicalTtl = Math.max(opts.ttl * 2 + 60, 120);
+    const strategy = this.strategy;
 
-    if (this.strategy === 'native') {
+    if (strategy.kind === 'native') {
       const entry: EagerEntry = {
         value,
         expiresAt: Date.now() + opts.ttl * 1000,
@@ -120,7 +141,7 @@ export class TagAwareCacheHandler implements CacheHandler {
       };
       const payload = JSON.stringify(entry);
       if (opts.tags.length > 0) {
-        await this.store.setWithTags!(
+        await strategy.store.setWithTags(
           this.dataKey(key),
           payload,
           physicalTtl,
@@ -132,7 +153,7 @@ export class TagAwareCacheHandler implements CacheHandler {
       return;
     }
 
-    if (this.strategy === 'eager') {
+    if (strategy.kind === 'eager') {
       const entry: EagerEntry = {
         value,
         expiresAt: Date.now() + opts.ttl * 1000,
@@ -141,7 +162,7 @@ export class TagAwareCacheHandler implements CacheHandler {
       await this.store.set(this.dataKey(key), JSON.stringify(entry), physicalTtl);
       if (opts.tags.length > 0) {
         await Promise.all(
-          opts.tags.map((tag) => this.store.sadd!(this.tagSetKey(tag), [key], physicalTtl))
+          opts.tags.map((tag) => strategy.store.sadd(this.tagSetKey(tag), [key], physicalTtl))
         );
       }
       return;
@@ -159,27 +180,30 @@ export class TagAwareCacheHandler implements CacheHandler {
   }
 
   async invalidate(opts: { key?: string; tag?: string }): Promise<void> {
+    const strategy = this.strategy;
+
     if (opts.key) {
-      if (this.strategy === 'eager') {
-        const raw = await this.store.get(this.dataKey(opts.key));
+      const key = opts.key;
+      if (strategy.kind === 'eager') {
+        const raw = await this.store.get(this.dataKey(key));
         if (raw !== null) {
           const entry = JSON.parse(raw) as EagerEntry;
           if (entry.tags.length > 0) {
             await Promise.all(
-              entry.tags.map((tag) => this.store.srem!(this.tagSetKey(tag), [opts.key!]))
+              entry.tags.map((tag) => strategy.store.srem(this.tagSetKey(tag), [key]))
             );
           }
         }
       }
-      await this.store.del(this.dataKey(opts.key));
+      await this.store.del(this.dataKey(key));
     }
 
     if (opts.tag) {
       const tag = opts.tag;
-      if (this.strategy === 'native') {
-        await this.store.invalidateTag!(`${this.prefix}${tag}`);
-      } else if (this.strategy === 'eager') {
-        const members = await this.store.smembers!(this.tagSetKey(tag));
+      if (strategy.kind === 'native') {
+        await strategy.store.invalidateTag(`${this.prefix}${tag}`);
+      } else if (strategy.kind === 'eager') {
+        const members = await strategy.store.smembers(this.tagSetKey(tag));
         // Verify each member still carries the tag before deleting — the set
         // can contain stale memberships from overwritten entries or LRU eviction.
         // Remove only the snapshot members (via srem, not sdel) so concurrent
@@ -187,17 +211,10 @@ export class TagAwareCacheHandler implements CacheHandler {
         await Promise.all(
           members.map(async (k) => {
             const raw = await this.store.get(this.dataKey(k));
-            if (raw === null) {
-              await this.store.srem!(this.tagSetKey(tag), [k]);
-              return;
-            }
-            const entry = JSON.parse(raw) as EagerEntry;
-            if (entry.tags.includes(tag)) {
+            if (raw !== null && (JSON.parse(raw) as EagerEntry).tags.includes(tag)) {
               await this.store.del(this.dataKey(k));
-              await this.store.srem!(this.tagSetKey(tag), [k]);
-            } else {
-              await this.store.srem!(this.tagSetKey(tag), [k]);
             }
+            await strategy.store.srem(this.tagSetKey(tag), [k]);
           })
         );
       } else {

package/src/cli-check.ts

@@ -36,10 +36,7 @@ import { dirname, join, resolve } from 'node:path';
 import { scanRoutes } from './routing/scanner.ts';
 import { lintConventions, formatConventionWarnings } from './routing/convention-lint.ts';
 import { writeRouteCodegen, CODEGEN_OUTPUT, ENV_DTS_FILENAME } from './routing/codegen-write.ts';
-import { isTimberPluginApi } from './plugin-context.ts';
-
-/** The plugin that publishes timber's resolved context on its Vite `api`. */
-const TIMBER_ROOT_SYNC_PLUGIN = 'timber-root-sync';
+import { resolveTimberContext, type ResolveViteConfig } from './cli-context.ts';
 
 /** The npm package that provides tsgo. Named in the missing-tool message. */
 const TSGO_PACKAGE = '@typescript/native-preview';
@@ -68,23 +65,6 @@ export type RunTsgo = (command: string, args: string[], cwd: string) => Promise<
  */
 export type ReadTsgoConfig = (command: string, args: string[], cwd: string) => Promise<string>;
 
-/**
- * Vite's own `resolveConfig`, narrowed to what this module passes and reads.
- *
- * The seam sits at `resolveConfig` rather than at "give me the plugins" so the
- * *arguments* are the thing under test: which config file, which command, and
- * which mode defaults. Those arguments have been wrong three separate times
- * (TIM-1332 rounds 4-6), and a double that answered "here are the plugins"
- * could not see any of it. The double returns what Vite returns — plugins with
- * an opaque `api` — so the lookup and narrowing under test stay the real ones.
- */
-export type ResolveViteConfig = (
-  inlineConfig: { configFile: string | undefined },
-  command: 'build',
-  defaultMode: string,
-  defaultNodeEnv: string
-) => Promise<{ plugins: readonly PluginWithApi[] }>;
-
 /** @internal Dependency injection for testing. */
 export interface CheckDeps {
   /**
@@ -164,89 +144,19 @@ export interface RouteInputs {
   pageExtensions: string[] | undefined;
 }
 
-/** The subset of a resolved Vite plugin this module reads. */
-export interface PluginWithApi {
-  name: string;
-  api?: unknown;
-}
-
 /**
- * Ask Vite for the resolved config, which is what carries timber's context.
- *
- * `resolveConfig` runs the whole config pipeline — config file discovery,
- * `config` and `configResolved` hooks — so the context it produces is the one
- * `timber build` would use. Measured at ~300-400ms on a real app; the type pass
- * it precedes costs far more.
- */
-const defaultResolveViteConfig: ResolveViteConfig = async (
-  inlineConfig,
-  command,
-  defaultMode,
-  defaultNodeEnv
-) => {
-  const { resolveConfig } = await import('vite');
-  return resolveConfig(inlineConfig, command, defaultMode, defaultNodeEnv);
-};
-
-/**
- * The mode defaults `timber build` resolves under.
- *
- * `resolveConfig`'s own defaults are `'development'` for both, but nothing
- * reaches it with those on a build: `createBuilder` goes through Vite's
- * internal `resolveConfigToBuild`, which calls
- * `resolveConfig(inlineConfig, 'build', 'production', 'production')`. A config
- * written as `defineConfig(({ mode }) => …)`, or one that loads `.env.production`,
- * therefore resolves to a *different* app under the two. Passing the defaults
- * explicitly is what makes "check validates what build builds" true rather than
- * true-by-coincidence for configs that ignore mode (TIM-1332, round 6).
- */
-const BUILD_MODE_DEFAULTS = ['production', 'production'] as const;
-
-/**
- * Resolve root, appDir and pageExtensions the way `timber build` resolves them.
- *
- * Reading `timber.config.ts` directly is **not** equivalent, which is the whole
- * reason this goes through Vite (TIM-1332, review round 3):
- *
- * - Config passed inline — `timber({ pageExtensions: [...] })` in
- *   `vite.config.ts` — lives only in the plugin's closure. Nothing that
- *   re-reads the config file can see it, so a scan built that way silently uses
- *   default page extensions and writes a route map missing the app's pages.
- *   `examples/next-playground-migration` is exactly this shape.
- * - `root` is Vite's resolved root, not the caller's cwd, and the two differ in
- *   the monorepo layouts TIM-498 describes. `appDir` resolves against it.
- *
- * There is no fallback to a second, hand-rolled resolution. A project whose
- * Vite config does not produce the timber plugin cannot be built either, so a
- * check that quietly proceeded on a guessed tree would report a verdict about
- * an app that does not exist.
+ * Resolve root, appDir and pageExtensions the way `timber build` resolves them
+ * — through Vite, never by re-reading `timber.config.ts` (see `cli-context.ts`).
+ * Inline `timber({ pageExtensions: [...] })` is the case that bites: a scan
+ * that re-read the file would silently use default page extensions and write a
+ * route map missing the app's pages. `examples/next-playground-migration` is
+ * exactly this shape.
  */
 export async function resolveRouteInputs(
   options: RouteOptions = {},
   deps: CheckDeps = {}
 ): Promise<RouteInputs> {
-  const resolveViteConfig = deps.resolveViteConfig ?? defaultResolveViteConfig;
-  // `configFile: undefined` is Vite's own "discover it" value, so the default
-  // path stays exactly what Vite does for `timber build` without `--config`.
-  const { plugins } = await resolveViteConfig(
-    { configFile: options.viteConfigFile },
-    'build',
-    ...BUILD_MODE_DEFAULTS
-  );
-
-  const rootSync = plugins.find((plugin) => plugin.name === TIMBER_ROOT_SYNC_PLUGIN);
-  if (!rootSync || !isTimberPluginApi(rootSync.api)) {
-    throw new Error(
-      `[timber] Could not read the resolved timber configuration from your Vite config.\n\n` +
-        `  \`timber check\` resolves your project through Vite so it validates the same\n` +
-        `  routes \`timber build\` builds — including config passed inline to timber().\n\n` +
-        `  Check that vite.config.ts exists and lists the timber plugin:\n\n` +
-        `    import { timber } from '@timber-js/app';\n` +
-        `    export default { plugins: [timber()] };\n`
-    );
-  }
-
-  const ctx = rootSync.api.getContext();
+  const ctx = await resolveTimberContext('check', options.viteConfigFile, deps.resolveViteConfig);
   return { root: ctx.root, appDir: ctx.appDir, pageExtensions: ctx.config.pageExtensions };
 }
 

package/src/cli-context.ts

@@ -0,0 +1,119 @@
+/**
+ * Resolve timber's configuration the way `timber build` resolves it, for CLI
+ * commands that run outside the build: `timber check` and `timber preview`.
+ *
+ * Reading `timber.config.ts` directly is **not** equivalent, which is the whole
+ * reason this goes through Vite (TIM-1332, review round 3; TIM-1531):
+ *
+ * - Config passed inline — `timber({ pageExtensions, adapter, output })` in
+ *   `vite.config.ts` — lives only in the plugin's closure. Nothing that
+ *   re-reads the config file can see it.
+ * - `root` is Vite's resolved root, not the caller's cwd, and the two differ in
+ *   the monorepo layouts TIM-498 describes.
+ * - The build directory can come from Vite's `build.outDir`, which only a
+ *   resolved Vite config knows.
+ * - `--config` names a Vite config file; only Vite can load it.
+ *
+ * There is no fallback to a second, hand-rolled resolution. A project whose
+ * Vite config does not produce the timber plugin cannot be built either, so a
+ * command that quietly proceeded on a guess would act on an app that does not
+ * exist.
+ *
+ * Design docs: 11-platform.md §CLI
+ */
+
+import { isTimberPluginApi, type PluginContext } from './plugin-context.ts';
+
+/** The plugin that publishes timber's resolved context on its Vite `api`. */
+const TIMBER_ROOT_SYNC_PLUGIN = 'timber-root-sync';
+
+/** The subset of a resolved Vite plugin this module reads. */
+export interface PluginWithApi {
+  name: string;
+  api?: unknown;
+}
+
+/**
+ * Vite's own `resolveConfig`, narrowed to what this module passes and reads.
+ *
+ * The seam sits at `resolveConfig` rather than at "give me the plugins" so the
+ * *arguments* are the thing under test: which config file, which command, and
+ * which mode defaults. Those arguments have been wrong three separate times
+ * (TIM-1332 rounds 4-6), and a double that answered "here are the plugins"
+ * could not see any of it. The double returns what Vite returns — plugins with
+ * an opaque `api` — so the lookup and narrowing under test stay the real ones.
+ */
+export type ResolveViteConfig = (
+  inlineConfig: { configFile: string | undefined },
+  command: 'build',
+  defaultMode: string,
+  defaultNodeEnv: string
+) => Promise<{ plugins: readonly PluginWithApi[] }>;
+
+/**
+ * Ask Vite for the resolved config, which is what carries timber's context.
+ *
+ * `resolveConfig` runs the whole config pipeline — config file discovery,
+ * `config` and `configResolved` hooks — so the context it produces is the one
+ * `timber build` would use. Measured at ~300-400ms on a real app.
+ */
+const defaultResolveViteConfig: ResolveViteConfig = async (
+  inlineConfig,
+  command,
+  defaultMode,
+  defaultNodeEnv
+) => {
+  const { resolveConfig } = await import('vite');
+  return resolveConfig(inlineConfig, command, defaultMode, defaultNodeEnv);
+};
+
+/**
+ * The mode defaults `timber build` resolves under.
+ *
+ * `resolveConfig`'s own defaults are `'development'` for both, but nothing
+ * reaches it with those on a build: `createBuilder` goes through Vite's
+ * internal `resolveConfigToBuild`, which calls
+ * `resolveConfig(inlineConfig, 'build', 'production', 'production')`. A config
+ * written as `defineConfig(({ mode }) => …)`, or one that loads `.env.production`,
+ * therefore resolves to a *different* app under the two. Passing the defaults
+ * explicitly is what makes "check validates what build builds" — and "preview
+ * serves what build wrote" — true rather than true-by-coincidence for configs
+ * that ignore mode (TIM-1332, round 6).
+ */
+const BUILD_MODE_DEFAULTS = ['production', 'production'] as const;
+
+/**
+ * Resolve the project through Vite and return timber's context as
+ * `timber build` would see it.
+ *
+ * @param command The CLI command asking, named in the error message.
+ * @param viteConfigFile `--config`. Undefined means Vite's own discovery, the
+ *   same as `timber build` without the flag.
+ */
+export async function resolveTimberContext(
+  command: string,
+  viteConfigFile: string | undefined,
+  resolveViteConfig: ResolveViteConfig = defaultResolveViteConfig
+): Promise<PluginContext> {
+  // `configFile: undefined` is Vite's own "discover it" value, so the default
+  // path stays exactly what Vite does for `timber build` without `--config`.
+  const { plugins } = await resolveViteConfig(
+    { configFile: viteConfigFile },
+    'build',
+    ...BUILD_MODE_DEFAULTS
+  );
+
+  const rootSync = plugins.find((plugin) => plugin.name === TIMBER_ROOT_SYNC_PLUGIN);
+  if (!rootSync || !isTimberPluginApi(rootSync.api)) {
+    throw new Error(
+      `[timber] Could not read the resolved timber configuration from your Vite config.\n\n` +
+        `  \`timber ${command}\` resolves your project through Vite so it sees the same\n` +
+        `  configuration \`timber build\` uses — including config passed inline to timber().\n\n` +
+        `  Check that vite.config.ts exists and lists the timber plugin:\n\n` +
+        `    import { timber } from '@timber-js/app';\n` +
+        `    export default { plugins: [timber()] };\n`
+    );
+  }
+
+  return rootSync.api.getContext();
+}

package/src/cli.ts

@@ -15,6 +15,7 @@
 // Type-only — the implementation is imported dynamically inside runCheck so the
 // CLI's other commands never load the route scanner.
 import type { CheckDeps } from './cli-check.ts';
+import type { ResolveViteConfig } from './cli-context.ts';
 
 export type { CheckDeps };
 
@@ -140,6 +141,7 @@ export interface ViteDeps {
   createServer?: typeof import('vite').createServer;
   createBuilder?: typeof import('vite').createBuilder;
   preview?: typeof import('vite').preview;
+  resolveViteConfig?: ResolveViteConfig;
 }
 
 /**
@@ -227,42 +229,31 @@ export async function runBuild(options: CommandOptions, _deps?: ViteDeps): Promi
   await builder.buildApp();
 }
 
-/**
- * Determine whether to use the adapter's preview or Vite's built-in preview.
- * Exported for testing — the actual runPreview function uses this internally.
- */
-export function resolvePreviewStrategy(
-  adapter: import('./adapters/types.ts').TimberPlatformAdapter | undefined
-): 'adapter' | 'vite' {
-  if (adapter && typeof adapter.preview === 'function') {
-    return 'adapter';
-  }
-  return 'vite';
-}
-
 /**
  * Serve the production build for local testing.
  * If the adapter provides a preview() method, it takes priority.
  * Otherwise falls back to Vite's built-in preview server.
  *
- * Uses the same loadTimberConfigFile loader as dev/build — one loader,
- * one set of module semantics. A config file that exists but fails to
- * load throws (naming the file) instead of silently degrading to plain
- * Vite preview. See TIM-1066.
+ * The project is resolved through Vite, as `timber check` resolves it
+ * (`cli-context.ts`), so the adapter, the output mode, and the build
+ * directory are the ones `timber build` used — including `--config`, inline
+ * `timber({ ... })` options, Vite's `root`, and `build.outDir`, none of which
+ * a re-read of `timber.config.ts` can see (TIM-1531). A config file that
+ * exists but fails to load throws (naming the file) instead of silently
+ * degrading to plain Vite preview (TIM-1066).
  */
 export async function runPreview(options: CommandOptions, _deps?: ViteDeps): Promise<void> {
-  const { loadTimberConfigFile, resolveBuildDir } = await import('./plugin-context.ts');
+  const { resolveTimberContext } = await import('./cli-context.ts');
+  const { adapterConfig, contextAdapter } = await import('./plugin-context.ts');
 
-  const root = process.cwd();
-  const config = loadTimberConfigFile(root);
-  const adapter = config?.adapter as
-    | import('./adapters/types.ts').TimberPlatformAdapter
-    | undefined;
-
-  if (resolvePreviewStrategy(adapter) === 'adapter') {
-    const buildDir = resolveBuildDir(root, config?.buildDir);
-    const timberConfig = { output: (config?.output ?? 'server') as 'server' | 'static' };
-    await adapter!.preview!(timberConfig, buildDir);
+  const ctx = await resolveTimberContext('preview', options.config, _deps?.resolveViteConfig);
+  const adapter = contextAdapter(ctx);
+
+  if (typeof adapter?.preview === 'function') {
+    await adapter.preview(adapterConfig(ctx), {
+      output: ctx.config.output ?? 'server',
+      outputDir: ctx.buildDir,
+    });
     return;
   }
 

package/src/client/browser-dev.ts

@@ -312,7 +312,7 @@ export function setupClientErrorForwarding(hot: HotInterface): void {
  * they are expected during navigation and are handled by the error boundary
  * and router. Exported for tests.
  *
- * See also: isControlFlowSignal() in server/primitives.ts (server-side,
+ * See also: isControlFlowSignal() in server/signal-identity.ts (server-side,
  * handles both instanceof and digest detection).
  */
 export function isFrameworkSignalError(error: unknown): boolean {

package/src/client/browser-entry/action-dispatch.ts

@@ -22,11 +22,12 @@ import { setHardNavigating } from '../navigation-root.tsx';
 import { getClientDeploymentId, DEPLOYMENT_ID_HEADER, RELOAD_HEADER } from '../rsc-fetch.ts';
 import { markClientStale } from '../stale-client.ts';
 import { RSC_CONTENT_TYPE } from '../../shared/rsc-media-type.ts';
+import { CSRF_REJECT_HEADER, CSRF_REJECT_VALUE } from '../../shared/csrf-reject.ts';
 import { createActionQueue } from './action-queue.ts';
 
 /**
  * Wait for a navigation or refresh to both settle (promise resolved) AND
- * commit (pushState / renderPayload's commit thunk ran). The queue must
+ * commit (pushState / the navigation's commit thunk ran). The queue must
  * not release the next action until the URL is correct in the address bar
  * — same rule `<Link>` uses for `isPending` (design/19 §Per-Link Pending
  * State). `onCommit` fires exactly once: on commit, supersession, or
@@ -93,6 +94,13 @@ export function setupServerActions(): void {
           markClientStale();
           throw new Error('Version skew detected — this client is out of date');
         }
+        // A CSRF 403 has a plain-text body; handing it to createFromFetch
+        // would surface as an opaque Flight decode error (TIM-1459).
+        if (res.headers.get(CSRF_REJECT_HEADER) === CSRF_REJECT_VALUE) {
+          throw new Error(
+            'Server action rejected: CSRF origin check failed (403). ' + 'The server log says why.'
+          );
+        }
         hasRevalidation = res.headers.get('X-Timber-Revalidation') === '1';
         hasRedirect = res.headers.get('X-Timber-Redirect') != null;
         reval.paths = res.headers.get('X-Timber-Revalidation-Path');
@@ -170,7 +178,8 @@ export function setupServerActions(): void {
               .then(
                 (applied) => {
                   if (!applied) {
-                    router.evictStaleCaches();
+                    // Synchronous eviction already ran at line 121 — only
+                    // the refresh flag needs deferral (TIM-1518).
                     queue.markNeedsRefresh();
                   }
                 },
@@ -184,8 +193,17 @@ export function setupServerActions(): void {
       }
 
       // revalidatePath was called but only for non-current paths —
-      // caches were already invalidated above, no refresh needed.
+      // caches were already invalidated above, so no refresh is needed
+      // unless a navigation ran while this action was in flight. That
+      // navigation may have consumed a pre-mutation prefetch before the
+      // eviction above, or fetched before the mutation landed, and it is
+      // now on screen. The other branches catch this through
+      // applyActionResult's epoch check; this one must check itself
+      // (TIM-1483).
       if (reval.paths) {
+        if (router && epoch && !router.isEpochCurrent(epoch)) {
+          queue.markNeedsRefresh();
+        }
         return decoded;
       }
 
@@ -194,11 +212,15 @@ export function setupServerActions(): void {
       // the queue until the refresh commits so the next action captures a
       // current epoch (codex on #1125).
       if (router && epoch) {
+        // TIM-1518: Evict synchronously so a navigation that supersedes
+        // this action's refresh cannot consume a pre-mutation prefetch.
+        // The deferred eviction in .then() ran as a microtask — after the
+        // superseding navigation had already consumed a stale entry.
+        router.evictStaleCaches();
         hold(
           router.applyActionResult(epoch).then(
             (applied) => {
               if (!applied) {
-                router.evictStaleCaches();
                 queue.markNeedsRefresh();
               }
             },