feat(router)!: location state is versioned by the app version; createLocationState gains clearOnReload (#994) - #1020

…de it did not change (#1034)

* docs(design): per-app cache versions, releasing without clearing the cache

* fix(router): a router's $$id comes from the createRouter() line in the source file

The id is a hash of the file path and the line of the createRouter() call.
The line was taken from the code the transform hook receives, which has
already been through the TypeScript transform: a dev server keeps comments
there and a build drops them. Build-time route discovery runs on a dev
server, so discovery and the bundle disagreed on the id of any router with a
comment above the call. The build registered that router's lazy route
manifest under an id no running router had, and the router rebuilt its trie
at run time (e2e/test-app, tests/cloudflare-basic, one of four routers in
examples/cloudflare-multi-router).

The line now comes from the file on disk (routerCallLines). A call the
source scan does not list keeps its line in the transformed code.

$$sourceFile is root-relative in a build. Discovery and the CLI read it on a
dev server, where it stays absolute; a build shipped the checkout directory
in every router's chunk.

Router ids change once for routers written with a comment above the call.
The rango state cookie name contains the id.

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

Every build got a new version, the build time, and every persistent cache
key and stored PPR shell carried it: each deploy started cold, a rebuild of
unchanged source cleared the cache, and under a host router a deploy of one
app cleared the others.

vite build now computes two versions per createRouter() from that router's
built code. The data version (its server code) keys segment entries,
"use cache" items and loader data. The document version (the data version,
the SSR output, the client asset names, base, Prerender payloads) keys PPR
shells and document-cache responses, stamps shells, is sent as
metadata.version and is what _rsc_v is compared with.

Build (src/vite/discovery/build-versions.ts, router-versions-phase.ts):
- membership on the module graph: from the createRouter() module and its
  static importers, stopping at the build's registries; actions and loaders
  only client code imports are attributed through the client graph
- hashes the chunk bytes on disk after postprocessBundle, with chunk file
  names replaced, the server-reference map skipped and virtual-module region
  comments made root-relative
- adds what no chunk of the router holds: its lazy route manifest, its
  clientUrls() projections, the encryption key file for routers that
  encrypt, Static payloads, server-component stylesheets, and what is
  installed for dependencies the bundle left external (name@version of the
  package and its dependencies; a file digest for a linked package; a
  per-build value and a build note for one that cannot be found)
- the built @rangojs/router:version module holds a placeholder the buildApp
  post hook fills in every environment's output; a build that cannot compute
  or fill fails
- prints the versions and writes their inputs to
  node_modules/.rangojs-router-build/cache-versions.json

Determinism: no build stamp; rango({ encryptionKey }) validated at config
time; plugin-rsc's server-reference map sorted and its assets-manifest import
given one name (stable-rsc-output.ts); loader manifest and client-URL
projections sorted; node and vercel RSC entries built with
preserveEntrySignatures "strict".

Runtime: createRSCHandler resolves its router's pair once
(server/build-version-table.ts); stores read the request's versions per
operation. CFCacheStore and VercelCacheStore key cached data with the data
version and stored HTML with the document version. VercelCacheStore is
versioned by default. Tag markers are stored without a version, so an
invalidation reaches every version, including one a rollback brings back.
A consumer-set version is used for both, and is now honored on the node and
vercel presets.

classifyRequest checks for an app switch before it compares versions: each
router has its own version, so a tab of another app always carries one this
router does not have.

Testing: setBuildVersions installs the versions of a simulated build for
serveShellRequest and dispatch. getCacheVersions is public from
@rangojs/router/cache for a custom store.

Dev is unchanged: one stamp, bumped on every RSC module edit.

* test(e2e): cache versions across deploys on node and cloudflare; stress-demo retention check

One scenario (runCacheVersionScenario, tests/shared-e2e) on a two-app host
fixture built four times with a server restart on each build: an unchanged
rebuild, a server change to app A, a client change both apps render. It
asserts cached data (a cache() route), stored HTML (a ppr route) and whether
a tab opened before the deploy reloads.

- packages/rangojs-router/e2e/cache-version.test.ts: node preset,
  VercelCacheStore over a file-backed Runtime Cache handle
- tests/cloudflare-basic/e2e/cache-version.test.ts: CFCacheStore with KV,
  miniflare persistence, route manifests built as workerd Text modules

Production only: the versions come from vite build. Neither describe owns a
useFixture, so the parity check expects no dev twin.

tests/cloudflare-stress-demo: bench:retention builds three times and fails
when an entry does not survive a restart or an unchanged rebuild, or
survives a server change.

bundle-analysis.test.ts follows the version module's new contract: a table
keyed by the built routers' ids, VERSION read from it, nothing of it in the
client bundle.

* docs: per-app cache versions as built; changelog

docs/design/per-app-cache-version.md is rewritten against the
implementation: how membership and hashing work, the table of version
consumers, what counts as a change, where the proposal was wrong, and the
measurements (retention, determinism samples, build time, bundle guards).

caching.md, cache-tags-flow.md and vercel-cache-store.md describe the two
versions, the unversioned tag markers and the Vercel store's default.

Skills, the docs site, the internal feature maps and the vercel-basic example
follow: what each kind of deploy keeps, how to force a clear or keep the old
behavior, rango({ encryptionKey }), setBuildVersions, getCacheVersions.

The location-state entries from #1020 say "every deploy that changes the
app": the app version they key on is the router's document version.

CHANGELOG: a Breaking entry with the deploy table, and entries for the
encryptionKey option and for tag invalidations applying across versions.

* fix(router): a ctx.waitUntil() task re-enters the request context it was scheduled under

A cache store builds its key when the write runs, from the request context:
the serving router's versions and the request host. cacheRoute calls
store.set inside ctx.waitUntil(), and the document cache does the same on a
MISS. Deployed workerd runs a deferred waitUntil task outside the request's
async context (Node and miniflare keep it), so that write was keyed with the
whole-build pair, which no router with its own version reads, and cacheRoute
did not write at all: it needs the request context before it reaches the
store.

ctx.waitUntil() now runs every task inside the context it was scheduled
under: the active store, else the context itself. One place, instead of a
re-entry at each call site; the four existing ones stay.

getCacheVersions() warns once per process when it falls back to the
whole-build pair while routers have versions of their own, so a production
log shows any other path that loses the context.

The whole-build memo and the test-only generation counter are gone from
build-version-table.ts; the serveShellRequest handler cache compares the
versions a handler was created with.

Test: cache/__tests__/background-write-versions.rsc-test.tsx schedules each
task from an async scope outside any request and asserts the segment record
and the document response are keyed with the serving router's versions.

* fix(router): a router's $$id is a hash of its file and call position, not of the call's line

The id was sha256(path:line). Taking the line from the file as written made
build-time discovery and the bundle agree, and kept the other half of the
problem: a blank line or a comment added above createRouter() changed the
id, and with it the state cookie name, the route manifest chunk name and the
router's cache versions, for an edit that changed nothing.

Nothing else reads the line, so the id is sha256(path#ordinal): the
root-relative file and the call's position among the file's createRouter()
calls in code. The transform no longer reads the file from disk.

Every router's generated id changes once. A router with an explicit id is
unaffected.

* fix(router): cache versions fail closed and do not depend on where the build ran

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

- a file a bundle lists that is not on disk, an unrecorded RSC, SSR or client
  bundle, an unrecorded version-module chunk and a missing plugin-rsc assets
  manifest fail the build
- the encryption key: a module depends on it when it uses the namespace it
  imports plugin-rsc's runtime under, whatever the function is called; a
  module that cannot be read counts; a key file with no module recognised
  makes the key every router's; a module that encrypts with no key file
  fails the build
- an external import is classified in one place (classifyExternal): runtime
  builtins and two plugin markers are covered elsewhere, a package by what is
  installed, a path by the file's bytes; a package that is not installed, a
  path that does not resolve and anything else get a per-build value and the
  build names them

Inputs that moved versions with no code change:

- region comments: every path is taken out of the hash input (the working
  directory, the pnpm store directory with its peer suffix, absolute paths in
  virtual ids)
- the SSR output goes through the same digest as the RSC output, file names
  tokenised
- module ids: a pnpm store directory is reduced to name@version, and
  plugin-rsc's client-reference group id of a virtual facade loses the
  working directory it carried

Structure:

- ownersOf: one ownership rule for registry targets, build data, server
  stylesheets and the key
- digestBundle: one digest per file with an ordered list of the files it
  names, in place of the parts template and its per-ownership memo
- runRouterVersionsPhase returns the table; runShellPrerenderPhase takes it
- cache-versions.json lists, once, what ssr-and-client is a digest of and
  the server files no router owns

The build-level suite gains three builds: the same source from another
working directory, lines added above createRouter(), and an app with no
bound action arguments.

* docs: per-app cache versions after the independent review

The design doc describes the build as it is now: the ownership rule, what is
taken out of a chunk before hashing and why, the failure-direction table,
what an external import is, the request context in deferred writes, and the
measurements on the final code (determinism from two working directories,
interleaved build time, retention).

CHANGELOG: every router id changes once, what the build cannot read, where
and how you build, ctx.waitUntil() and the request context, the warning for
a key built outside a request.

* docs: the waitUntil re-entry is a hardening; say what was seen on deployed workers

The comment, the test header and the design doc said deployed workerd runs a
deferred waitUntil task outside the request's async context. That was seen
once, in "use cache" background revalidation. It is not the general case:
cacheRoute already throws without a request context on main, and route
caching works on deployed workers.