feat(router): per-app cache versions, a deploy keeps the cache of code it did not change - #1034

Problem

Every production build got a new version, the build time
(Date.now().toString(16) in the version plugin), and every persistent cache
key and every stored PPR shell carried it. A consumer saw three things:

• every deploy started with a cold cache, whatever it changed;
• a rebuild of unchanged source (a CI retry, a redeploy, a rollback) cleared
  the cache too: measured on tests/cloudflare-stress-demo, /app/cached/hot
  was a hit after a server restart on the same build and a miss after
  rebuilding the same source;
• under a host router, deploying one app cleared the cache of every other app
  in the worker.

What a consumer sees now

vite build computes two versions for each createRouter() from that
router's built code and prints them:

[rango] Cache versions for 2 router(s), data / document (9.8ms):
[rango]   141feb48ee9301cb / c1e538fdfeb8470a  src/apps/a/router.tsx
[rango]   a04e7def0c013c33 / f22c12acd5ee9ed9  src/apps/b/router.tsx

• The data version is a hash of the router's server code. It keys cached
  RSC data: cache() segment entries, "use cache" values, loader data.
• The document version is the data version plus the SSR output, the
  client asset file names, base and the router's Prerender payloads. It
  keys stored HTML (PPR shells, document-cache responses), stamps shells, is
  sent as metadata.version, and is what an open tab's _rsc_v is compared
  with.

The same code builds to the same versions, on any machine and in any checkout
directory, so a new deployment finds the entries the previous one wrote.

Before and after

No API is needed to get the new behavior. What changes is what the same
requests return across a deploy.

Before:

build 1   1a101ad4ae4
          GET /app/cached/hot -> 1791029499936   (stored)
          GET /app/cached/hot -> 1791029499936   (hit)
restart   GET /app/cached/hot -> 1791029499936   (hit)
build 2   1a101adbfc4                            (same source; the version is the build time)
          GET /app/cached/hot -> 1791029529495   (miss)

After (pnpm --filter cloudflare-stress-demo bench:retention, this branch):

build 1   aa0e4ac8b921d1c9 / 1c86a03ad46604c1
          GET /app/cached/hot -> 1791058181368   (stored)
          GET /app/cached/hot -> 1791058181368   (hit)
restart   GET /app/cached/hot -> 1791058181368   (hit)
build 2   aa0e4ac8b921d1c9 / 1c86a03ad46604c1   (same source)
          GET /app/cached/hot -> 1791058181368   (hit)
build 3   12461c4786a9d057 / f0c8fd830c5cb52e   (server code of this router changed)
          GET /app/cached/hot -> 1791058193306   (miss)

The one place a consumer writes something different is the stable encryption
key, and the Vercel store wiring:

// vite.config.ts, before
rango({ preset: "vercel" });
// RANGO_ENCRYPTION_KEY, if set, was read from the environment by the plugin

// vite.config.ts, after
rango({
  preset: "vercel",
  encryptionKey: process.env.RANGO_ENCRYPTION_KEY, // validated at config time
});

// router.tsx, before: a per-deploy namespace, the cache is cleared on every deploy
const runtimeCache = getCache({ namespace: process.env.VERCEL_DEPLOYMENT_ID });

// router.tsx, after: the store versions its keys per router
const runtimeCache = getCache();

End-to-end example

A host router with two apps (Cloudflare)

// vite.config.ts
export default defineConfig({
  plugins: [
    react(),
    rango({
      preset: "cloudflare",
      encryptionKey: process.env.RANGO_ENCRYPTION_KEY,
    }),
    cloudflare({
      configPath: "./wrangler.json",
      viteEnvironment: { name: "rsc", childEnvironments: ["ssr"] },
    }),
  ],
});

// src/worker.rsc.tsx
import { createHostRouter } from "@rangojs/router/host";

const hostRouter = createHostRouter();
hostRouter.host(["shop.example.com"]).lazy(() => import("./apps/shop/handler.js"));
hostRouter.host(["blog.example.com"]).lazy(() => import("./apps/blog/handler.js"));

export default {
  fetch: (request, env, ctx) => hostRouter.match(request, { env, ctx }),
} satisfies ExportedHandler<Env>;

// src/apps/shop/router.tsx (blog is the same shape)
import { createRouter } from "@rangojs/router";
import { CFCacheStore } from "@rangojs/router/cache";

export const router = createRouter<Env>({
  document: Document,
  // No `version`: the store keys with this router's own cache versions.
  cache: (env, ctx) => ({ store: new CFCacheStore({ ctx: ctx!, kv: env.KV }) }),
}).routes(urlpatterns);

// src/apps/shop/urls.tsx
export const urlpatterns = urls(({ path, cache }) => [
  cache({ ttl: 600 }, () => [path("/products/:id", ProductPage, { name: "product" })]),
  path("/", HomePage, { name: "home", ppr: { ttl: 600 } }),
]);

Deploy a change to apps/blog: the build prints a new pair for
src/apps/blog/router.tsx and the same pair as before for
src/apps/shop/router.tsx. Shop's /products/:id entries and its / shell
are served from the store; shop's open tabs keep navigating without a reload;
blog starts cold and blog's tabs reload on their next navigation.

A single app (node or Vercel)

// vite.config.ts
export default defineConfig({
  plugins: [
    react(),
    rango({ preset: "vercel", encryptionKey: process.env.RANGO_ENCRYPTION_KEY }),
  ],
  define: { "process.env.NODE_ENV": JSON.stringify("production") },
});

// src/router.tsx
import { getCache, waitUntil } from "@vercel/functions";
import { VercelCacheStore } from "@rangojs/router/cache";

const runtimeCache = getCache();

export const router = createRouter({
  document: Document,
  cache: () => ({ store: new VercelCacheStore({ cache: runtimeCache, waitUntil }) }),
}).routes(urlpatterns);

A single app is one router: a redeploy of unchanged code, a docs-only commit,
a CI config change or a rollback keeps the cache; a server change clears it; a
client-only change keeps cached data and replaces stored HTML.

To clear the cache on demand, or to keep "every deploy clears":

createRouter({ version: "2026-10-03.1" }); // change it to clear
createRouter({ version: process.env.BUILD_ID }); // the old behavior

Semantics

Verified end to end on the node preset (packages/rangojs-router/e2e/cache-version.test.ts,
VercelCacheStore over a file-backed Runtime Cache handle) and on Cloudflare
(tests/cloudflare-basic/e2e/cache-version.test.ts, CFCacheStore with KV
under miniflare persistence). Both run one scenario: a host router with two
apps, four builds, a server restart on each, open tabs. The Vercel preset is
verified at build level only (see Notes).

Deliberately unchanged:

Code change

Paths are under packages/rangojs-router/. The design, with what the
proposal got wrong, is docs/design/per-app-cache-version.md.

Build: which code is a router's, and what is hashed

src/vite/discovery/build-versions.ts (new, pure over data the hooks record):

• resolveRouterMembers: membership on the bundler's MODULE graph. The walk
  starts at the createRouter() module and every module that statically
  imports it, follows static and dynamic imports, and stops at the build's
  registries (plugin-rsc's server-reference map, the loader manifest, the
  routes manifest), which name every app. An action or loader only a client
  component imports is attributed through the CLIENT graph.
• ownersOf: the one ownership rule for everything that is not a chunk the
  walk reaches (a registry target, a Static payload, a clientUrls()
  projection, a server component's stylesheets, the encryption key): it
  belongs to the routers that reach one of its subject modules, and to every
  router when none does.
• digestBundle: each file digested once, with what says where or how the
  build ran taken out first: the hashed names of bundle files (kept as an
  ordered list of referenced files), the server-reference map's body, and the
  paths in region comments. The RSC and the SSR output both go through it.
• computeRouterVersions: per router, [file digest, ...references as the target's identity when owned, one token when not] for each owned file, plus
  what its chunks leave external (classifyExternal) and the inputs it owns.

const data = hashInputs("rango-data-version", dataInputs);
const document = hashInputs(`rango-document-version\n${data}`, documentInputs);
table[routerId] = [data, document];

One rule for what the build cannot determine: it fails, or the version changes
on every build. It never silently stays the same.

src/vite/discovery/router-versions-phase.ts (new) runs in the buildApp
post hook and hands the table to the build-time shell capture:

buildApp: {
  order: "post",
  async handler(builder) {
    try {
      await runShellPrerenderPhase(
        s,
        builder as any,
        runRouterVersionsPhase(s, builder as any), // compute, fill, print, report
      );

A version cannot be a constant in the code it hashes, so the built
@rangojs/router:version module is byte-identical in every build and holds a
free identifier the phase replaces in the written chunk
(getVirtualBuildVersionContent, src/vite/plugins/virtual-entries.ts):

export const ROUTER_VERSIONS = __RANGO_ROUTER_VERSIONS__;
export const VERSION = ROUTER_VERSIONS["*"][1];

The placeholder is filled in every environment's output that holds the
module, not only the RSC one.

Determinism (each one measured):

• build stamp removed (the placeholder above);
• region paths out of the hash input: the working directory, the pnpm store
  directory with its peer suffix, absolute paths in virtual ids;
• module ids made portable (portableModuleId): root-relative, the pnpm store
  directory reduced to name@version, plugin-rsc's client-reference group id
  of a virtual facade without the working directory;
• $$sourceFile root-relative in a build, and the router $$id a hash of the
  root-relative path and the call's position among the file's
  createRouter() calls (routerId,
  src/vite/plugins/expose-ids/router-transform.ts), not of its line;
• rango({ encryptionKey }), validated in configureEncryptionKey
  (src/vite/encryption-key.ts);
• src/vite/plugins/stable-rsc-output.ts (new): sorts plugin-rsc's
  server-reference map and gives its assets-manifest import one local name;
• loader manifest and client-URL projections sorted
  (expose-internal-ids.ts, discovery/virtual-module-codegen.ts);
• node and vercel RSC entry built with preserveEntrySignatures: "strict"
  (RSC_ENTRY_SIGNATURES, src/vite/rango.ts), as @cloudflare/vite-plugin
  already forces.

Runtime: one resolution, per-family keys

src/router-versions.ts and src/server/build-version-table.ts (new):

export function resolveRouterVersions(routerId, override?): RouterVersions {
  return (
    resolveVersionsFrom(table, routerId, override) ?? uniformVersions(VERSION)
  );
}

createRSCHandler (src/rsc/handler.ts) resolves its router's pair once. Its
own version is the document version (payload metadata, _rsc_v check, shell
stamp and gate, rango state value). The data version reaches the stores on the
request context (_versions), read per operation:

export function versionKeyPrefix(storeVersion, kind: KeyVersion): string {
  if (kind === null) return "";
  const version = storeVersion ?? getCacheVersions()[kind];
  return version ? `v/${version}/` : "";
}

• CFCacheStore: keyToRequest(key, family) / toKVKey(key, family);
  segments and fn: items "data", doc: and shell2: "document", tag
  markers null (KV key, edge marker request, isolate memo key).
• VercelCacheStore: FAMILY_VERSION (s, i data; r, h document;
  tm none), now on by default.
• src/rsc/shell-build-manifest.ts: the verdict memo is keyed by the asking
  router's version as well as the spec.
• getCacheVersions() is public from @rangojs/router/cache for a custom
  store.
• src/router/request-classification.ts: the app-switch check runs before the
  version check. Every router has its own version now, so a tab of app A
  navigating into app B always carries a version B does not have; that is an
  app switch (same reload), not a stale client.

Why here and not in each store's constructor: the cache factory builds the
store before the request context exists and without knowing the router (the
same reason CFCacheStore resolves its base URL lazily).

That makes the request context load-bearing for every deferred write, so
ctx.waitUntil() re-enters the context a task was scheduled under
(src/server/request-context.ts):

const scheduledUnder = requestContextStorage.getStore() ?? ctx;
const task = Promise.resolve().then(() =>
  requestContextStorage.run(scheduledUnder, fn),
);

cacheRoute calls store.set inside waitUntil, and so does the document
cache on a MISS. This is a hardening: these writes keep their context on
deployed workers today (cacheRoute throws without one on main, and route
caching works there). Deployed workerd lost it once, in "use cache"
revalidation. If a task ran without it, the document write would be keyed with
the whole-build pair, which no router with its own version reads. getCacheVersions() warns once
per process when it falls back to the whole-build pair in a build whose
routers have versions of their own, so a production log shows any other path
that loses the context.

Testing

setBuildVersions (src/testing/build-versions.ts, exported from
@rangojs/router/testing) installs a table where the build's is absent, so
serveShellRequest and dispatch resolve versions through the production
path. The handler cache of serveShellRequest reuses a handler only while
the router would still resolve the versions it was created with, so a second
setBuildVersions is a deploy; the production module carries nothing for
tests.

Test plan

Unit, next to the changed modules (packages/rangojs-router):

• src/vite/__tests__/build-versions.test.ts (74): membership and
  hashing on hand-built graphs. Pins: the walk stops at registries; the
  static-importer climb; client-graph attribution; the ownership rule;
  file names tokenised (RSC and SSR); the server-reference map is not
  hashed; region paths are not hashed and the code under them is; Static
  and clientUrls() projections in the data version, Prerender in the
  document version only; the key rule (encrypting router, every router
  when unrecognised, build failure without the key file, no key when
  nothing encrypts); classifyExternal and its inputs; server
  stylesheets; portable ids (pnpm peer suffix, client-reference group of a
  virtual facade); a listed file missing on disk throws; $ in a router
  id; the files no router owns.
• src/vite/discovery/__tests__/router-versions-phase.test.ts (31):
  the phase against files on disk. Pins: the table is written into the
  built module, in every environment that holds it, and returned; a
  relative outDir is read against the root; the build fails when a
  bundle or the version-module chunk was not recorded, when a listed file
  or the assets manifest is missing, when a router encrypts without a key
  file, and when it cannot compute or fill; the (whole build) line; a
  linked external is digested; a path external is digested; an external
  that cannot be found moves the version every build and is named; the
  encryption note is printed once and only when it applies; the report
  lists unownedFiles.
• src/vite/discovery/__tests__/installed-packages.test.ts (11):
  name@version closure, nested and symlinked (pnpm) layouts, cycles; a
  linked package is described by its files (symlinks followed, a link
  back up the tree ends the walk, its node_modules and .git left out,
  an unreadable file throws).
• src/vite/__tests__/stable-rsc-output.test.ts (15),
  encryption-key.test.ts (19), expose-router-id.test.ts (34: the id is
  a hash of path and call position, the same from dev-shaped and
  build-shaped code, unchanged by a comment or blank line above the call),
  expose-internal-ids.test.ts, version-plugin.test.ts,
  discovery/__tests__/virtual-module-codegen.test.ts.
• src/server/__tests__/build-version-table.test.ts (23): resolution
  order, per-request versions, versionKeyPrefix, the rango state prefix,
  the once-per-process warning when a key is built outside a request.
• src/cache/__tests__/background-write-versions.rsc-test.tsx (2, in
  test:unit:rsc): a route's segment record and a document-cache MISS,
  deferred with waitUntil and run outside the request's async context,
  are keyed with the serving router's data and document version.
• src/router/__tests__/request-classification.test.ts (30): a cross-app
  navigation is an app switch whatever version the other app's tab carries.
• src/cache/cf/__tests__/cf-cache-store-versions.test.ts (17) and
  src/cache/vercel/__tests__/vercel-cache-store-versions.test.ts
  (12): key per family, a store version wins, and the rollback
  case (an invalidation made under deploy B makes deploy A's entry stale).
• src/rsc/__tests__/shell-build-manifest.test.ts,
  src/prerender/__tests__/build-shell-capture.test.ts: memo per version;
  build shells stamped with the document version.

Build level, real vite build (runs in test:unit, so in CI's unit-tests
job):

• src/vite/__tests__/cache-versions-build.test.ts (22 tests over 18
  builds of a two-app host fixture, node preset, three at a time, about
  12 s). Scenarios: no change in a second directory; no change, built with
  vite build app from the parent directory; lines added above
  createRouter(); server text in A; a route added to A; a client
  component in A; a shared server module; a different encryption key; no
  bound action arguments anywhere (no key file, no key in any version, the
  build does not fail); an action only a client component imports; a new
  action in A; the host entry; code only the mounted handler reaches; a
  clientUrls() route that declares another loader; a server component's
  stylesheet; an external dependency and one of its dependencies. It also
  asserts the table is keyed by the $$ids in the built chunks and which
  files no router owns.

Userland, through @rangojs/router/testing:

• src/testing/__tests__/build-versions.rsc-test.tsx (14, in
  test:unit:rsc): setBuildVersions + serveShellRequest on a
  VercelCacheStore over one fake handle. Pins the consumer contract:
  stored HTML follows the document version, cached data the data version,
  the reload check reads the document version, each router of a table gets
  its own pair, a consumer version wins.

E2e, production only (versions come from vite build; dev keeps one stamp,
covered by the existing HMR suites). Neither describe owns a useFixture, so
check:e2e-parity --strict expects no dev twin:

• packages/rangojs-router/e2e/cache-version.test.ts (node preset,
  VercelCacheStore over a file-backed handle)
• tests/cloudflare-basic/e2e/cache-version.test.ts (Cloudflare,
  CFCacheStore with KV, miniflare persistence)
• tests/cloudflare-stress-demo/bench/retention.ts
  (pnpm bench:retention)

Both suites run runCacheVersionScenario (tests/shared-e2e): a host router
with two apps, four builds, a restart on each, a cache() route, a ppr
route and open tabs.

Red before green. Each mechanism was removed in turn (one edit, the tests that
pin it run, the edit reverted) and the result recorded: 33 ablations here and
14 more for the review fixes further down, every one red.

The router-id fix, at build level: with the source-line lookup removed,
keys the table by the ids the built routers carry fails with
expected [ '1bcc02f6', '718ea8bc' ] to deeply equal [ '718ea8bc', 'c63295f3' ].

Regressions found by an adversarial review of the first implementation, each
fixed here with a test that was red first. cache-versions-build.test.ts
against the code before the fixes, 8 of 17 failing:

× builds the same source in another directory to the same versions
× keeps every data version and replaces every document version for a client change
× changes the router that encrypts with the key when the key changes, and no other
    expected [ 'encryption-key', …(3) ] to deeply equal [ 'encryption-key' ]
× covers code that only a module importing the router reaches
    expected 'c8b4bbf2c1e862e1' not to be 'c8b4bbf2c1e862e1'
× changes app A's data version when a stylesheet its server component imports changes
    expected [ 'file handler~6f1d9895.mjs', …(3) ] to include 'server-css src/apps/a/note.tsx'
× changes app B when a dependency its server code leaves external is bumped
    expected [] to deeply equal [ 'external ext-lib' ]
× follows an external dependency's own dependencies
× keeps both apps when only the host entry changes

Those are: a server component's stylesheet URL was in cached Flight and in no
version; a router's code was walked from its createRouter() module only; the
node preset's external dependencies were not hashed; every router that reached
any "use server" module counted as depending on the key; a virtual module's
region comment carried the checkout directory. A sixth showed up while writing
those tests: 1 of 10 concurrent builds of the fixture produced another version
table, because the bundler kept a different local name for the assets-manifest
import (44 of 44 identical after stableRscOutput renames it).

A second adversarial review of the fixed code found nine more. Each is fixed
with a test, and each fix removed in turn turns that test red:

The first of those at build level: with the projection left out,
cache-versions-build.test.ts fails changes app B's data version when a clientUrls() route declares another loader with
expected 'ba93ab92cdc2f4b3' not to be 'ba93ab92cdc2f4b3'.

One regression came from those fixes and was caught by the determinism sample,
not by a test. With "an external that cannot be found gets a per-build value"
in place, tests/cloudflare-stress-demo built to 6 different versions in 6
builds: its route manifest is large enough to ship as a workerd Text module,
and @cloudflare/vite-plugin imports that through
__CLOUDFLARE_MODULE__Text__<path>__CLOUDFLARE_MODULE__, which was read as
a package named __CLOUDFLARE_MODULE__Text__. The marker is now classified
as a file the hash already covers (classifyExternal; 6 of 6 identical
after). Pinned twice:

• unit, in classifies a specifier (at the time: does not take another plugin's import marker for a package, red without the check with
  expected '__CLOUDFLARE_MODULE__Text__' to be undefined).
• e2e, where CI runs it: the Cloudflare cache-version suite now builds with
  RANGO_MANIFEST_TEXT=1. Against the plugin build without the check it
  fails at an unchanged rebuild keeps every version
  (expect(built2).toEqual(built1), 4 lines differ); with it, 1 passed.

A third, independent read of that last round's diff found three more, all in
how an external or an output directory is read. Fixed, each with a test that
is red without the fix:

It also reported that a linked external's digest covers build artifacts in its
directory (a log, a .tsbuildinfo), so such a package can move the version
with no source change. Left as it is, on purpose: nothing says which files an
import can reach, and leaving a file out is the unsafe direction. It is in the
design doc's open questions. Checked by that read and found sound: the
clientUrls() record (no reference id or absolute path in the digest), the
package-name test, the portable ids, the fill loop, the reordered request
classification (actions, loader fetches and form posts never carry
_rsc_partial; both modes answer with the same reload), and the binding
rename.

E2e red before green, on the real fixtures:

• Node (cache-version, production): with every store key on the document
  version, the scenario fails at app A's entry after a client change
  (Expected: "1791058306073", Received: "1791058308761"), 3 of 3 attempts.
• Cloudflare (cache-version, production): with router ids taken from the
  transformed code, it fails at expect(a1).not.toBe(b1)
  (Expected: not "1791058354398"): both apps were served one entry.

Dogfood red before green: with a static import of the version table in
testing/serve-shell-request.ts, tests/vite-rsc-demo's test:unit:rsc
failed (Cannot find package '@rangojs/router:version'): a flight-only test
config does not alias the build-only virtual. The import is lazy again and
that suite passes. pnpm --filter @rangojs/router test:unit alone did not
show it.

Independent review. Four reviewers read the final diff of the three rounds
above. Why another round before merging: changing a hash input later moves
every consumer's versions once, so input-shape fixes belong here. Applied:

• Run time. A task scheduled with ctx.waitUntil() re-enters the request
  context it was scheduled under, once, where every task is scheduled
  (src/server/request-context.ts). getCacheVersions() warns once per
  process when it falls back to the whole-build pair while routers have their
  own versions. The four existing per-site re-entries are left as they are
  (cache-runtime.ts, document-cache.ts STALE, loader-cache.ts,
  background-revalidation.ts): the last enters a different (render) context,
  the others now nest inside the same one and keep documenting the dependency
  at the site.
• Build, unsafe directions. One rule, stated once in the code and in the
  design doc: an input the build cannot determine fails the build or changes
  the version every build. A listed file missing on disk, an unrecorded
  client or SSR bundle, an unrecorded version-module chunk, a missing assets
  manifest and a missing key file under an encrypting module now fail the
  build. An external import the build cannot read gets a per-build value and
  a build note; a path left external is digested.
• Build, inputs that moved versions with no code change. Region paths are
  out of the hash input (the working directory, the pnpm peer suffix, absolute
  paths in virtual ids); the SSR output goes through the same code as the RSC
  output; a pnpm store directory is name@version in module ids; the router
  id is a hash of path and call position, so a blank line above
  createRouter() no longer renames the state cookie and the versions.
• Structure. One ownership function (ownersOf) for registry targets,
  build data, server stylesheets and the key; one digest per file with an
  ordered reference list in place of the parts template and its per-ownership
  memo; the phase returns the table instead of parking it on the state; the
  holdsServerReferences flag, Reach.seeded, the whole-build memo and the
  test-only generation counter are gone; the report lists unownedFiles and
  what ssr-and-client is a digest of.

Two items were not applied as written, with the evidence:

• The key rule "the runtime is in the server graph but the call pattern
  matches nothing: every router that reaches the runtime depends on the key"
  would put the key in nearly every router of an app that has server actions
  and no inline closure: plugin-rsc prepends the runtime import to every
  "use server" module (plugin-CLvIS10V.js:1709) and emits the call only
  for a bound closure (:1694), so "matches nothing" is the normal state of
  such an app, and without a stable key it would get new versions on every
  build. Implemented instead: per module, any use of the namespace the import
  binds (not the function's name); a module that cannot be read counts as
  encrypting; and the key file, which plugin-rsc writes only when a chunk
  reads the key, as a second signal: a key file with no module recognised
  makes the key every router's.
• Typed per-family key helpers in CFCacheStore: skipped. The 20 call sites
  already pass a typed KeyVersion; a helper per family moves the same
  choice into the helper's name at every one of them.

One more input that depended on the working directory was found by building
tests/cloudflare-stress-demo from two directories, after region paths and
SSR names were fixed: plugin-rsc's client-reference group id for a chunk whose
facade is a virtual module (@cloudflare/vite-plugin's worker entry) is
path.relative(root, id) of a non-path id, which resolves against the working
directory (…/group/facade:__/__/\0virtual:cloudflare/worker-entry). The SSR
chunk holding it got another identity and the document version moved.
portableModuleId drops that prefix.

Red before green for this round (one edit each, the pinning tests run, the
edit reverted):

The last row is also the evidence for not applying the key rule as written:
with "reaches the runtime" as the test, a build with file-level actions and no
bound closure has no key file, and the missing-key failure then stops it.

A read of this round's own diff by a fresh reviewer found two more inputs
(the printable file-name token and the name of an absolute external outside
the project, both in the table above) and raised one concern that was checked
and left: an inline action whose every use is tree-shaken would be detected
before tree-shaking and then fail on the missing key file. Tried on the
fixture: a module with a bound inline action that nothing renders (imported
for its side effects only) still builds, the key file is written and its app
gets the key input, because plugin-rsc exports the hoisted action and its
server-reference map imports the module. An import the TypeScript transform
drops never reaches the graph. The build-level scenario without bound
arguments covers the direction that would fail.

Required runs, local (Apple M4, one machine). The production projects, the
cache-version suites and the retention bench ran on the final code. The dev
projects and the HMR suite ran three edits earlier; those edits are in code
that only runs in vite build (the file-name token, the name of an absolute
external, one refactor for lint):

The existing PPR, cache, document-cache, prerender and host-routing suites are
inside those runs, in dev and in production.

Tests that failed or needed a retry, with how often. None is touched by this
PR:

• tests/cloudflare-basic default-prefetch-none (dev) › an offscreen viewport override waits for intersection (expect(top).toBeGreaterThan(920),
  received 0). Full dev suite on this branch, 6 runs: failed in 4 (one
  disturbed by my own source edits), 470 passed in 2. On the base commit
  (9938350d): failed in 2 of 2 full dev runs. Alone (--repeat-each=8): 8
  of 8 passed. When it fails, the production project does not run, because
  it depends on dev; that is why production above was run with --no-deps.
• test:hmr-routes-local. Base commit, 4 runs: 21 passed in 2, recovery: helper-file fix after broken-import error re-runs discovery failed in 2
  (expect(received).not.toContain("\"blog.recovered\"") on the generated
  route names). This branch, 12 runs: that test failed in 6, with the same
  assertion; 21 passed in 3; 20 passed with one test passing on retry in 3
  (an invalid transition({ when }) edit prints the error and shows the Vite overlay twice, should not overwrite when routes have not changed once). A
  failed run reports "1 failed, 1 flaky, 19 passed" on both commits, because
  the serial retry fails in beforeAll, and leaves
  e2e/test-app/src/urls/blog.handlers.tsx modified; it was restored each
  time.
• The router smoke setup project, first attempt of one test: 2 of 7
  production runs on this branch, both in the last round (smoke (production) › URL params: blog post once, smoke › SSR renders home page once). The
  attempt never reached the app: the fixture's server command went through
  pnpm, which ran an install whose lefthook step failed on the hooks directory
  the worktrees share (could not replace the hook: can't rename pre-commit to pre-commit.old - file already exists, then remove …/.git/hooks/pre-commit: no such file or directory), the environment gotcha in AGENTS.md. Passed on
  retry both times.
• Router dev shell-capture-timeout (dev) › budget shorter than the settlement sequence refuses: stays MISS, no partial bake, once-per-key warning: 1 of 6 full dev runs on this branch, apiRequestContext.get: socket hang up from the test's isolated dev server on the first attempt,
  passed on retry. Alone on this branch (--repeat-each=5): 20 of 20 passed.
  Not run alone on the base commit.

One more, caused by this PR's own test and fixed: src/rsc/__tests__/stream-idle.test.ts
(real timers, a 20 ms margin) failed once in a full unit run while
cache-versions-build.test.ts ran its 14 builds at once. The builds now run
3 at a time; every full unit run and gate since has been green.

Gate, from the worktree root, on the final commit (cc7bc6aa):

• pnpm run typecheck: 16 of 16 tasks
• pnpm run test:unit:all: router 7409 passed (5 skipped, 6 todo) and
  461 RSC; tests/cloudflare-basic 68 and 17; tests/vite-rsc-demo 25
  and 1; e2e/mini 25 and 3; tests/shared-e2e 8
• pnpm run lint: 0 warnings, 0 errors
• pnpm run format
• pnpm check:e2e-bucketing
• pnpm check:e2e-parity --strict
• pnpm run check:docs-api: 269 identifiers
• pnpm check:bundle-guards: green across 3 apps
• git status --porcelain empty; no *.gen.ts changes (no routes added
  to a committed app; the fixtures ignore their generated files)
• On top of origin/main (eed288b1, feat(router)!: location state is versioned by the app version; createLocationState gains clearOnReload (#994) #1020); fetched again before the
  last commits, it had not moved

Commits on feat/per-app-cache-version, on top of the design-doc commit
9938350d:

• a2389916 fix(router): a router's $$id comes from the createRouter() line in the source file
• f17bccb7 feat(router)!: per-app cache versions, a deploy keeps the cache of code it did not change
• d674abc4 test(e2e): cache versions across deploys on node and cloudflare; stress-demo retention check
• b200d91c docs: per-app cache versions as built; changelog

and, from the independent review, on top of b200d91c:

• f3a03402 fix(router): a ctx.waitUntil() task re-enters the request context it was scheduled under
• 3760870f fix(router): a router's $$id is a hash of its file and call position, not of the call's line
• c9bcc479 fix(router): cache versions fail closed and do not depend on where the build ran
• cc7bc6aa docs: per-app cache versions after the independent review

Review. Three simplify passes (reuse, quality, efficiency) and an adversarial
correctness pass ran on the diff, then again on the code the fixes added, and
one more correctness read on the last round's diff.
Applied: shared resolveVersionsFrom (one function, the lookup merged into
it), versionKeyPrefix, compareStrings, id constants,
createCallStartIndices and offsetToLineColumn; the phase fails instead of
falling back to a stamp; reuse of each router's walk; a memo of located
packages. (The per-ownership digest memo of the first pass was replaced by
one digest per file in the independent review.)
Skipped, with reasons: a single request-context read per key (saves one
getStore()); a faster file-name scan than one alternation regex (it is 9 of
the stress demo's 19 ms; the alternative changes matching semantics); a
warning when plugin-rsc's server-reference module is not the expected shape
(it would only matter for minified server builds); renaming
server/build-version-table.ts.

Measurements

Full tables and conditions are in the design doc's "Measuring it". One
machine (Apple M4, 10 cores, AC power, Node 24.12, Vite 8.0.16, rolldown
1.0.3). Retention, determinism, build time and bundle guards are from
2026-10-04, on the code as it ships; the run-time numbers are from 2026-10-03.

Retention on tests/cloudflare-stress-demo (bench:retention):

Build time, interleaved: 7 rounds, the base commit and then the branch in each
round, one vite build per app per side, load 1.0 to 3.9:

Every median is inside its base range (the proposal's pass mark). The build is
between unchanged and 1.4% slower. The proposal projected under 5 ms for the
hashing; the step that shipped takes 15 to 29 ms, because it does more than
one sha256: it reads the RSC and the SSR output, takes region paths and file
names out of every chunk, makes module ids portable and describes the
installed externals. Earlier back-to-back sessions ran while other suites
loaded the machine (load up to 20) and are not reported.

pnpm check:bundle-guards, before and after: cloudflare-basic client router
chunk 47077 B gzip in both (limit 47104 B, same content hash in the file
name); stress-demo eager routes manifest 315 B and 314 B (limit 2048 B).

Same source, same versions, on the final code:

• sequential builds: cloudflare-multi-router 10 of 10 identical,
  vercel-multi-router 10 of 10, stress demo 6 of 6;
• the test fixture, 44 concurrent builds in separate directories: 44 of 44;
• vite build in the app against vite build <app> from the repository
  root: vercel-multi-router, cloudflare-multi-router and the stress demo
  each give one table from both directories.

What the samples caught on the way, each now pinned by a test: 1 of 10 fixture
builds with another import binding name; 6 different tables in 6 stress-demo
builds while Cloudflare's Text-module marker counted as a missing package;
two tables from two working directories on vercel-multi-router (region
paths), and then on the stress demo's document version (plugin-rsc's
client-reference group id of a virtual facade).

Run time: the prefix of a key costs 62 ns when it is read from the request's
versions and 11 ns with a store-level version (2 million calls, median of 7
rounds, Node). The stress-demo throughput harness was run on both commits;
bench/compare.ts calls all 16 scenarios "within variance" with a reported
variance of 44% to 124%, so nothing is claimed from it.

Notes

Migration and surprising interactions (all in the CHANGELOG entry):

• Entries now outlive a deploy. Anything that relied on a deploy to clear the
  cache has to invalidate tags or change version.
• VercelCacheStore is versioned by default; the documented wiring drops the
  deployment id from getCache(). Entries written without a version are no
  longer read.
• Two environments built from one commit have the same versions. A preview
  sharing production's KV namespace shares its entries. "use cache" item keys
  carry no host.
• A pinned store version (new CFCacheStore({ version })) keeps its entries
  across this upgrade while the markers that invalidated them move to the
  unversioned key, so entries tagged before the last updateTag() are served
  again until their TTL. Change the pinned value once. No transitional read of
  the old marker key was added.
• Every router's generated id changes once (the state cookie name contains the
  id): it is a hash of the file path and the call's position in the file, no
  longer of its line. The line was a bug on main twice over: build-time
  discovery and the bundle disagreed on the id of a router with a comment
  above the call, so the lazy route manifest was registered under an id no
  running router had and the trie was rebuilt at run time (measured on
  e2e/test-app, tests/cloudflare-basic and one of four routers of
  examples/cloudflare-multi-router); and a blank line above the call
  renamed the cookie. A router with an explicit id is unaffected.
• createRouter({ version }) now takes effect on the node and vercel presets;
  the generated entry used to pass the build version over it.
• The node and vercel RSC builds use preserveEntrySignatures: "strict".
  Shared code moves from dist/rsc/index.js into chunks.
• A router whose build output differs on every build gets a new version on
  every build: a Prerender/Static() handler that renders a timestamp, or an
  inline action with bound arguments inside one (random IV). e2e/test-app
  and tests/cloudflare-basic do the first on purpose, so their main router
  is not stable across builds; the retention checks use fixtures and the
  stress demo.
• A stylesheet that server code links is part of the data version. For an app
  that compiles one stylesheet from every class, a class change in a client
  component clears cached data.
• Isolation between apps needs lazy mounts. Routers one module imports
  statically share that module's code.
• A clientUrls() module tells the server which loaders, loading and
  transition a route has. Changing those changes the app's data version;
  changing the components it renders does not.
• The working directory, the checkout directory and the pnpm peer layout do
  not change the versions. What remains: with build.minify: false on the
  CLIENT build, client chunks carry region comments, their names depend on the
  working directory, and the document version with them.
• A build can now fail where it used to pass: a build output file the bundle
  lists that is not on disk, a missing plugin-rsc assets manifest, a missing
  encryption key file while code encrypts. Each of those used to leave an
  input out of the versions without a word.
• An import the server build leaves external and cannot read (a package not
  in node_modules, a path that does not resolve, a URL) gives the routers
  importing it a new version on every build, and the build names it.
• Every task scheduled with ctx.waitUntil() re-enters the request context it
  was scheduled under.

Follow-ups, from the independent review, not in this PR:

• postprocessBundle hardcodes dist/rsc while the version phase reads the
  configured outDir (bundle-postprocess.ts, untouched by this branch).
• A plugin-rsc version-range warning: the key detection, the assets manifest
  shape and the client-reference group id are all plugin-rsc 0.5.35 shapes;
  each fails closed, none warns ahead of an upgrade.
• The remaining build-step micro-costs: the alternation regex scan over each
  chunk, the extendReach rescan of the reached set, records times routers.
• shellMemoKey builds a Request to read a URL (already on main).

Not done, with reasons:

• Yarn Plug'n'Play (no node_modules): not tested. On the node preset every
  external would be "not found", so versions would change on every build,
  with the build note saying so.
• A linked workspace package left external is digested whole, build artifacts
  in its directory included. Narrowing it to what files/exports reach is
  an open question in the design doc.
• No e2e on a deployed Vercel project or deployed Cloudflare worker. The
  Vercel preset is verified by real builds (examples/vercel-multi-router,
  10 of 10 identical) and VercelCacheStore unit tests; the node e2e runs
  VercelCacheStore over a file-backed handle.
• A deferred task that loses the request context cannot be reproduced locally
  (Node and miniflare keep it; no loss is known on these write paths). The re-entry in
  ctx.waitUntil() is tested by producing the loss at the scheduling
  boundary. CFCacheStore's own tasks on the platform waitUntil (KV-to-L1
  promotion) are not covered by it; three of them build a key after an
  await, as they did for the key's host before this PR. The once-per-process
  warning is what would show a loss there.
• Minified server builds (build.minify on the RSC environment): the
  server-reference map cannot be skipped and region comments do not exist, so
  adding an action in one app changes every app's data version. Not tested.
• Encrypted bound arguments inside build-rendered payloads differ per build
  (random IV in plugin-rsc). A deterministic IV would have to come from
  plugin-rsc.
• A dependency left external whose files change while its version does not (a
  patched package, a git dependency at a moved ref) is not seen.
• The encryption key is resolved once per process. Two Vite configs with
  different keys loaded in one process before either builds is not supported.
• Per-app client asset sets (so a client change in app A keeps app B's stored
  HTML) would need the client-reference map out of the shared chunk. Left as
  designed: the HTML is re-rendered from cached data.
• tests/cloudflare-basic does not build from another working directory (its
  build-time prerender of /build-env fails before the versions are
  computed), so it is not in the two-directory sample.